Skill 契约与运行时适配¶
- 沉淀时间：2026-09-09
- 来源：IK7LI3 技术规格、Agent I/O 流程与 POC 记录
- 成熟度：
provisional - 适用范围：同一 Skill 需要在 Claude Code、OpenCode 或其他 Agent runtime 运行的项目
三层一致性¶
稳定实现应区分三层：
| 层 | 负责什么 | 不应包含什么 |
|---|---|---|
| 规格层 | 业务步骤、输入输出、证据和停止条件 | 特定 runtime 的 Task 语法和 session 细节 |
| Runtime 层 | 把规格映射到子 Agent、权限、路径和工具调用 | 重复定义业务真相 |
| 设计证据层 | 记录探针、token、失败样本和取舍 | 被运行时当作每次必读指令 |
规格层保持框架无关，Runtime 层可以把多个能力打包为子 Agent，也可以 inline 执行，但必须输出同一业务契约。
输入契约¶
大输入通过文件路径传递：
USER_SQL_PATHTABLE_CTX_PATHBASELINE_PATHOPTIMIZED_SQL_PATH- 显式的项目
SKILL_DIR
子 Agent 收到路径后直接读取指定文件。路径缺失或无效时返回 degraded / missing context，禁止搜索仓库、读取任意源码或猜全局 Skill 位置。
输出契约¶
- 子 Agent 只输出窄 JSON 和对应落盘 artifact，不附带长 narrative。
- 主 Agent 校验 schema、路径、case_id 和 artifact 存在性后再继续。
- specialist 只提供候选与风险，最终 workflow JSON 由主 Agent 汇总。
- 子 Agent 禁止再次调用 Task，避免无界嵌套和不可控上下文。
中断语义¶
Task 中断后报告阻塞并停止，不能自动重复派发。数据库执行开始后还需 execution journal；如果进程中断时状态为 started，应进入人工接管，避免重复执行有副作用的操作。
反模式¶
- 在业务 SKILL.md 写死 OpenCode Task 语法。
- 同一字段由路由、generation 和主 Agent 重复判定。
- 让子 Agent通过全盘搜索修复输入路径。
- 用“最后一条自然语言消息”代替结构化输出协议。
- 中断后自动重新执行数据库步骤。
限制与待验收¶
路径化输入和静态契约测试已经完成，fresh OpenCode session、实际 token 上限和服务器路径仍待验证。当前可采用契约设计，不应宣称全部 runtime 已通过生产验收。