# 阶段 A：边界合同定义

日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：已完成（本文件同时是阶段 A 台账与验证记录）。

## 1. 意图

把总 plan 第 4、5 节的组件边界与约束归属落为仓内唯一边界文档 [`.agent/docs/architecture/边界合同.md`](../../.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 相符。