# 子 Agent 调度协议（P3 / P5 / P6）

主 agent 是唯一调度者。所有代码生成、影响分析、修复派单都通过独立子 agent 完成；子 agent 内部有子模块时，它自动成为下一层主 agent 并递归执行本协议。

## 1. 角色

| 角色 | 谁担任 | 职责 |
|------|--------|------|
| 主 agent（架构师） | 当前会话 agent | 拆解、派单、集成、调试、变更管理、汇报 |
| 模块实现 agent | 每次派单新建的子 agent | 依据 design.md 完整生成一个模块的代码 + 自测 + 报告 |
| 变更分析师 agent | 需求调整时新建 | 读 manifest/designs，输出受影响模块集合 |
| 下层主 agent | 带子模块的模块实现 agent | 递归派单给子模块实现 agent，收集后代产出后集成回报 |

## 2. 派单规则

- **一次一模块**：一个派单提示词只对应一个模块 id，不要合并派单。
- **提示词必须自包含**：子 agent 看不到本会话上下文，所有它需要的事实都要写进提示词。
- **并行**：同一依赖层、互不依赖的模块可以并行派单（后台运行，收集齐再进下一层）；跨层必须等待。
- **有记录**：每次派单在 `.mdd/logs/` 留痕（派给谁、时间、结果），失败注明原因与去向。

## 3. 派单提示词模板

### 3.1 模块实现 agent（叶子模块）

```
你是模块实现 agent。请独立完成模块「<id>」的全部代码。

【模块信息】
- 模块 id：<id>
- 代码输出目录：.mdd/code/<id>/（只允许写这个目录，不要写任何其他路径）
- 设计文档：先读 .mdd/designs/<id>.md，严格按其实现；不得修改设计文档。

【上游接口摘要】（来自依赖模块已定稿的设计，直接使用，不要自行猜测）
- <dep-id> 提供：<签名/数据结构/事件 摘要>
- <dep-id2> 提供：<摘要>

【本模块对外契约】（从 design.md 复制关键签名，供你自测对齐）
- <API / 数据结构 / 行为要点>

【技术栈与约定】
- <语言/框架/版本、目录结构、命名规范、测试方式>

【验收标准】（从 design.md 复制）
- <逐条列出>

【交付物】
1. .mdd/code/<id>/ 下完整可运行的代码；
2. 自测结果（运行了什么、结果如何）；
3. 报告写入 .mdd/logs/<id>/report.md：实现内容、运行方式、自测结论、遗留问题。

【纪律】
- 不修改任何 .mdd/designs/** 文件；不修改其他模块的任何文件；
- 不调用或假定未在上游接口摘要中出现的功能；
- 完成后报告：成功 / 失败（失败必须给出具体原因与卡点）。
```

### 3.2 递归下发（模块 agent 内部有子模块时，它就是下层主 agent）

```
你是「<父模块>」模块的负责人，担任本层的下层主 agent。

你的职责：
1. 读 .mdd/designs/<父模块>.md，按其中「子模块划分」章节确定子模块清单与子模块间契约；
2. 对你的每个子模块，按本模板递归派发独立子 agent（提示词自包含，包含该子模块的设计路径、上游接口摘要、输出目录 .mdd/code/<子模块>/、验收标准）；
3. 收集全部子模块产出，校验对齐后，把「<父模块>」组装成一个完整可用的模块（补上父模块自身的编排代码）；
4. 把整个「<父模块>」的集成结果、自测结果、遗留问题写入 .mdd/logs/<父模块>/report.md，回报给你的上层主 agent。

纪律：只操作「<父模块>」及其子树路径；不修改任何设计文档；子模块之间不允许互相修改。
```

### 3.3 变更分析师 agent（P6 需求调整时）

```
你是变更分析师。用户需求发生了如下调整：

<change-request 内容，或粘贴新需求原文>

请完成影响分析：
1. 读 .mdd/manifest.md 与相关 .mdd/designs/*.md；
2. 输出「受影响模块集合」：
   - 直接受影响：需求点落在哪些模块；
   - 间接受影响：沿依赖图向下游传播——凡是被改接口所依赖的模块都要列出（可传多层）。
3. 对每个受影响模块给出建议动作：仅实现调整（不改契约）/ 设计修订 + 全量重生成 / 无影响；
4. 把分析结果写入 .mdd/logs/impact-<seq>.md，并回报主 agent。

只做分析与报告，不要改任何代码或设计文件。
```

## 4. 收集与校验

- 等待同一批所有子 agent 结束（后台任务逐个收结果）。
- 主 agent 校验每个交付：目录存在、文件完整、契约对齐（抽查关键签名）、自测结论。
- 不合格 → 重派（带具体失败信息，最多 2 次）；仍失败 → 主 agent 亲自处理，或升级为设计变更。

## 5. 失败处理

| 失败类型 | 处理 |
|----------|------|
| 代码缺陷（不违反契约） | 重派该模块 agent 修复；或主 agent 小修（实现细节，不碰设计） |
| 契约/设计缺陷 | 禁止代码打补丁 → 走 P6 设计变更，全量重生成 |
| 子 agent 反复失败 | 主 agent 亲自接管该模块；或缩小模块再拆一层 |
| 依赖的上游契约缺失 | 暂停下游派单，先补上游设计 |

## 6. 并行与调度纪律

- 派单数量一次不要超过 ~8 个，超出分两批，避免调度混乱；
- 同一批派单使用同一套提示词模板（只换模块相关字段），保持一致性；
- 每批结束后同步更新 `.mdd/manifest.md` 状态（designed → implemented → integrated）；
- 主 agent 在任何时刻都知道：哪些模块已交付、哪些在途、哪些失败。