5.0 KiB
5.0 KiB
阶段 A：边界合同定义
日期：2026-08-22 总 plan：2026-08-22-agent-example整体收敛总plan.md 状态：已完成（本文件同时是阶段 A 台账与验证记录）。
1. 意图
把总 plan 第 4、5 节的组件边界与约束归属落为仓内唯一边界文档 .agent/docs/architecture/边界合同.md，后续所有改动按它归位。
2. 边界
- 只写文档，不修改任何代码。
- 对现有约束抽样登记"现在在哪层、应该在哪层"，形成错位清单；错位项本阶段不修。
- 用户已有的候选设计文档不碰。
3. 错位清单（抽样登记，非穷尽）
| # | 位置 | 现状 | 应属层（按边界合同） | 处置归属 |
|---|---|---|---|---|
| 1 | run_writer_pipeline.py:33-34（MAX_EVIDENCE_REQUESTS=3、MAX_REWRITES=2） |
补证/重写业务上限写死在脚本层，且被 05 领域文档记录为"已落地编排合同" | 业务继续/停止归主代理向人请求授权；脚本只保留技术保护 | 阶段 E |
| 2 | produce_next_chapter.py:113（GATE_ANCHORS 按章字典） |
章级机械门锚数据硬编码在脚本代码里，新章必须改代码才能登记 | 章级验收数据归数据层（库或 meta），机械门执行留脚本 | 阶段 E |
| 3 | 角色合同.md writer 节（"唯一事实来源是冻结任务输入""不读写工作区"） |
写手的数据可访问范围以提示词层合同表达，等于剥夺探索能力 | 数据可访问范围归工具层白名单；提示词只保留写作纪律 | 阶段 C（改合同）+ 阶段 D（工具落地） |
| 4 | 角色合同.md frontmatter modelPolicy 与 muse_role.py:36-43（FIXED_OPUS_* 常量） |
同一模型策略在合同文档与代码两处各自声明，存在漂移风险 | 策略事实源唯一（中央角色合同），代码只校验不自行声明 | 阶段 C 统一口径，随阶段 B/F 直调链终态一并收口 |
| 5 | produce_next_chapter.py:107（ARTIFACTS = docs/write-chapter/artifacts） |
运行时产物目录放在 docs/ 下，看板从文件系统读运行展示 |
运行数据归数据库与运行目录投影；docs/ 只留文档 | 阶段 G |
| 6 | dashboard/server.py:2482（决策菜单生成「改」重产命令文本） |
视图层为人生成 shell 执行命令 | 创作台只读库、展示链路输入输出，不产执行命令 | 阶段 G |
| 7 | 评委角色（盲评链 execute-role-task 无会话进程，角色文件却声明 tools: read, grep, find, ls） |
实际执行无工具，角色文件工具提示与实际白名单长期不一致 | 角色文件可解释工具，但声明的工具应与该角色场景白名单相符 | 阶段 C（合同对齐时明确评委圈定授权两场景） |
抽样覆盖层：脚本层（#1、#2）、提示词层（#3）、双源（#4）、数据层（#5）、视图层（#6）、角色文件一致性（#7）。工具层当前整体缺失（无工具 server），是阶段 D 的建设对象，不属于错位项。
4. 文件台账（阶段 A 触碰的全部文件）
| 处置 | 文件 | 原因 |
|---|---|---|
| 新增 | .agent/docs/architecture/边界合同.md |
填补"组件边界与约束归属无唯一事实源"的合同空白；入口为架构索引、.agent/_index.md 与 AGENTS.md SoT 表；内容为六组件职责边界表、七类约束归属表、三层提示词结构、探索授权模式、证据责任，全部为目标合同表述，不含过程措辞 |
| 新增 | docs/plans/2026-08-22-agent-example整体收敛总plan.md |
总 plan 落盘（意图两线、目标链路、创作台五视图、组件边界、五智能体五链、阶段 A–G、台账要求、总验证） |
| 新增 | docs/plans/2026-08-22-阶段A-边界合同定义.md |
本文件：阶段 A 细节、错位清单、文件台账与验证记录 |
| 修改 | .agent/docs/architecture/_index.md |
登记边界合同入口（目录纪律：新增文档必须同步 _index.md） |
| 修改 | .agent/_index.md |
同上，长期知识索引补边界合同行 |
| 修改 | AGENTS.md |
SoT 表补边界合同行，声明其"唯一事实源"地位 |
| 遗留 | 错位清单 #1–#7 | 本阶段只登记不修；各归属阶段处理时按总 plan 台账要求单独出处置理由 |
| 遗留 | 工作树中上一轮清理的未提交改动（05 领域文档、produce_next_chapter.py、已删 write-chapter 旧脚本） | 属上一轮链路清理产物，待用户决定提交；不属于阶段 A 范围 |
5. 验证
- 边界合同覆盖全部组件（主代理、五智能体、Skill、工具 server、脚本、静态校验、创作台）与约束类型（提示词、角色合同、工具、静态、脚本+数据库、架构门禁、授权管控）：见文档 §1、§2。
- 错位清单每项有具体文件位置与行号：见 §3。
- 技能严格审计：
skill_harness.py --strict通过，58 个 Skill，阻断 0，质量发现 0。 - Skill 索引一致性：
skills_index.py --check通过，索引与磁盘、skills.json 相符。