提案 03:删除不可达的 stage-contract 契约与资产加载期的死引用机制
状态: 待评审 日期: 2026-10-14 扫描域: assets/、codex-skills/、src/plugin/{skills,commands,server,prompt-lint}.ts、test/
问题
A. stage-contract.md 是不可达的"单一来源"
assets/prompts/stage-contract.md(55 行)会被拷贝到 <skillsDir>/_prompts/(src/plugin/skills.ts:88-97),但没有任何读取路径:
loadPrompt仅被bootstrap调用(src/plugin/bootstrap.ts:18),且从包内assets/prompts/读取(src/plugin/prompts.ts:15-23),不经_prompts/;- skills 注册跳过
_前缀目录(skills.ts:21,32),_prompts/对模型不可见; - 资产与命令对它的引用只有裸名
stage-contract(7 个assets/commands/*.md:4、assets/prompts/bootstrap.md:22),无法定位到任何文件; - 全仓库无
_prompts/路径引用(rg "_prompts/" assets codex-skills test→ 仅prompt-lint.ts:58的跳过分支与prompts.test)。
其规范内容已被局部重述:assets/agents/dev-lifecycle.md:40-44(阶段顺序与 checklist 勾选)、docs/guides/configuration.md:124-132。文档却仍称其为"单一来源"(configuration.md:62、architecture.md:88,153、sops/07-docs-update.md:23)。
B. .opencode/skills/ 加载期改写没有输入
- skills 安装改写:
src/plugin/skills.ts:99-115(processDir内replaceAll)。 - commands 加载改写:
src/plugin/commands.ts:67(replaceAll,并让skillsDir变成文件的缓存键组成部分)。 assets/与codex-skills/中该模式 0 命中;两个改写只被合成夹具测试锁定(test/skills.test.ts:43-53、test/commands.test.ts:65-70)。- 两个模块各自实现同一死约定。
C. promptsDir 安装期拷贝没有消费者
_prompts 拷贝(skills.ts:88-97)只服务一个没有读取者的通道;test/prompts.test.ts:25-40 锁定拷贝行为本身。
提案
- 折叠契约:将
stage-contract.md的独有规范内容并入assets/agents/dev-lifecycle.md的《阶段契约》章节(第 40-44 行处),至少包括:- 阶段表(含
setup行与各阶段产出); - 完成权威(阶段完成 = Parent Issue body checklist
- [x] <stage>,由编排器经gh issue edit更新); - 门禁规则表(前置阶段 completed / requirements 完成需用户确认 / 依赖 Task 已合并 / code 阶段需设计基线已合入);
- Prohibited Actions(不跳阶、不伪造完成、不修改已完成阶段 checklist、reviewer/goal-verify 等子 agent 不执行写命令)。
- 阶段表(含
- 删除
assets/prompts/stage-contract.md;删除skills.ts:88-97的_prompts拷贝与promptsDir参数;server.ts:186,192调用点相应收缩。 - 更新引用文案:7 个
assets/commands/*.md第 4 行去掉"(阶段契约见 stage-contract)"(或改为"(阶段契约见 @dev-lifecycle)");bootstrap.md:22删去悬挂句(其"推荐流程"表已含相同信息)。 - 文档对账:
configuration.md:62,124-126;architecture.md:88,153;sops/07-docs-update.md:23(示例改为"如阶段契约内嵌在 dev-lifecycle agent 定义")。 - 删除
.opencode/skills/改写(skills.ts的processDir段与commands.ts:67);loadCommands签名收缩为loadCommands(commandsDir),缓存键去掉 skillsDir。反向选择:若维护者想保留该约定,必须至少让一个真实资产使用它,并用真实断言替换合成夹具——本提案建议删除(无使用者的约定是投机泛化)。 prompt-lint.ts:58删除_prompts//_context/跳过分支:两个通道均已不存在(_context为更早移除的内置机制),资产无引用,删除后 lint 行为不变。- 测试清理:删除
test/prompts.test.ts:25-40,66-71;test/skills.test.ts:43-53,56-63;test/commands.test.ts:65-70及依赖 skillsDir 的缓存失效用例(缓存断言本身的重做见提案 07)。
我们放弃什么
- "stage-contract 单一来源"的文档模型:契约从独立文件迁移为编排器 prompt 的内嵌章节。仍是单一文本来源,但不再是可独立链接的文件;commands 的指向性文案被删或改为 agent 引用。
- 若未来需要 skill 间共享资产通道(
_prompts)或.opencode/skills/相对引用约定:重新引入时应带真实消费者与测试,而不是凭历史惯性保留双份实现。 - 删除
_context/跳过属顺手清理,与主目标无强耦合,可单独取舍。
验收标准
rg -n "stage-contract" src assets codex-skills test→ 0;docs 不再称其为独立契约文件。rg -n "_prompts|opencode/skills/" src assets test→ 0。npm run prompt-lint、npm run typecheck、npm test通过。npm run docs:build通过(文档链接指向的文件仍存在)。
风险
- 内容折叠不全导致约束丢失:以第 1 条的清单作为执行 checklist;
dev-lifecycle.md是唯一全权编排器,契约语义落点正确。 - commands 去掉括号文本不改变行为(模板文本投递)。
- 中低风险;可 revert。