多 Agent 协作流程设计文档

多 Agent 协作流程设计文档

版本：v2.4.4 ｜ 架构：1 个领导进程 + N 个任务类型化干活进程 ｜ 状态：定稿锁版候选（A 组一致性硬伤 + B 组补定义已并入；C 组转《工程实施手册》，D 组框架级待拍板）

〇、核心设计原则

判断逻辑留在领导 prompt 里，检查规则全部外置。

接口契约文档、依赖表、文件所有权表、预算计数器、高腐化区清单，都是领导“读的数据”，而不是领导“记的规则”。领导 prompt 只负责启发式决策（怎么拆、派给谁、怎么综合），硬边界与状态检查全部由 Code 层执行。

原因：领导 prompt 过长会导致指令遵循退化——它是全系统杠杆最高也最脆弱的单一故障点，规则堆进去等于自毁。

补充口径：prompt 内若保留“必须/禁止”等硬措辞，仅作为 Code 层判定的前置提示；最终硬边界以 Code 层为准。prompt 硬规则与 Code 层规则的一致性由回归测试集校验，不靠人工背诵。

〇bis、起步期实际口径（2026-09-19 首跑实测后的现状声明）

本文档把硬边界交给「Code 层」执行。**起步期 Code 层尚未实现**：没有编排器进程、没有 SQLite 状态、没有文件锁、没有 worktree 隔离、没有预算熔断、没有 reviewer JSON 比对、没有 Checkpoint 拦截。下列条款现在一律由人工与领导（父代理）自觉兜底 —— 本文档对它们的描述是**目标态**，不是现状；照它当“已有保障”用会翻车。

首跑实测（2026-09-19，hermes-wear「文件」拆页任务，Hermes delegate_task 编排，一个领导 + 2~3 个子代理）：

| 文档的计划 | 实战实际发生 |
|---|---|
| 独立分支、起步期 max_workers=1 | 直接在主工作区改、直接 push main；同一时段 2~3 个 agent 在跑 |
| 每任务独立 worktree（手册 1.3） | 多个 agent 同改一个 worktree、无锁；过程中出现 3 次“该文件已被其他 agent 修改”的告警 |
| 双 Reviewer 独立 JSON verdict | 没有 reviewer 角色；验收 = 静态核对（拿官方产物核 API）+ CI（编译/出图）+ 人工看图 |
| Checkpoint ①②③ 由 Code 层拦截 | 没有拦截；由人类在对话里当场拍板（事后才补 push/交付） |
| repo-scout 先找现成（Phase 1） | 未执行；直接开写 |
| 反作弊/覆盖性 diff/失败阶梯 | 未使用（本轮没有出现需要定级的失败） |

结论：文档预见的坑（共享 worktree、无锁并行）在原样踩到，**因为拦截者不存在**；而真正救场的两条恰好是本手册 0.3 节写对的部分 —— 本机不编译（重活走 CI）与 1.6GB 内存下的保守模式。起步期只有两条路：接受“人工兜底”并明确写下来，或先把 Code 层做出来；两者之间的中间态不得默认按文档执行。

起步期三条全局口径（2026-09-19 复核补，凡是正文没说清执行位置的，按这里）：

1. **测试执行**：所有测试执行（灰轨/白轨/冒烟/全量重跑）**一律走 CI**；本机只允许静态检查与单实例 headless 截图。正文写"重跑全量/跑绿"的地方，默认指 CI 上跑（手册 0.3：本机不编译、不跑完整测试）——照字面在本机跑就是下一个"装 JRE 事件"。
2. **等待人工**：一切"同步等人"的环节（延长批准、Checkpoint ①②③、L2 顾问、L3 决策）在起步期 = **任务挂起 + `mtask todo add` + 每日提醒**；领导显式挂起后可以去做别的，不原地空等（人可能几小时后才回，见设备环境文档）。
3. **顾问模式**：正文假设"人坐在 IDE 前接受 diff"——起步期退化为**把 Diff 文本挂进 mtask 待办**，人在手机上至少能读个大概；不接受也不阻塞，等回到电脑前处理。

一、总览：核心认知

1. 先问该不该用多 Agent，再问怎么用——单 agent 能搞定的任务上多 agent 纯属烧钱（详见 Phase -1）。
2. 先找现成的再自己建——Phase 1 是价值锚点，但时间盒按任务类型弹性化。
3. Brief 的质量上限 = 验收标准的可验证性——验收是主观的等于没写；量化标准要配反作弊条款。
4. 领导 prompt 是全系统杠杆最高、也最脆弱的单一故障点——必须最先打磨，且打磨要靠回归测试集而不是每次跑全流程。
5. 干活 Agent 的真实价值不是“专家人设”，而是上下文隔离 + 工具权限收敛 + 领域工序。

二、执行流程（Phase -1 至 Phase 6）

Phase -1：适切性判断

上多 Agent 前先过三问，任一答“否”就退回单 agent：

1. 单 agent 是否已经跑得动？
   · 一次通过率 > 80% → 别上；
   · 人工介入率 > 20%，或平均追问次数 > 2 次/任务 → 可考虑上；
   · 频繁因上下文超限失败 → 可考虑上。
   · 统计窗口：最近 20 次同类任务，或最近 30 天，取先到者；样本不足时由人工判断并记录理由。
2. 任务有明确、可验证的输出吗？
   · 纯创意类不再一刀切“别上”。若可用“候选多样性 + 人类偏好评测 + 约束满足”验收，可上；
   · 无法定义任何可验证信号，且人类偏好也不可稳定复现 → 别上。
3. 预估 ROI 达标吗？
   · 立项预估 ROI = (人工工时 × 人工时薪) ÷ (预估 token 上限 × token 单价 × 15)。
   · **起步期口径（2026-09-19 定）**：本项目无"人工时薪"这一量纲（单人、学生、无薪资口径），立项预估改用**两栏记录**：预计 token/额度消耗 + 预计人工介入次数；结案实测同样记这两栏。阈值 3~5 **暂不设**，等攒够实测样本（≥3 个真任务）再回头定线。
   · ×15 是多 agent 相对单 agent 的放大系数，按单 agent 基准估算 token，不按多 agent 实际消耗估算，避免双重计数。
   · 结案实测 ROI 必须使用实际 token、工具、云资源、CI、人工评审与等待成本，不得继续用预估分母。
   · 起步阈值：**暂不设**（2026-09-19 定；原「3~5，实测后校准下调」一句作废，勿再恢复）。等 ≥3 个真任务实测后再回填。
   · “调低 ROI 预期”明确为：按风险折扣调低预估收益，使准入更难；若仍要上，须接受更差 ROI 并记录理由，不得偷偷调低阈值。

值得上的典型：大型迁移（100+ 表）、批量重构（跨 50+ 文件）、调研+实现组合。不值得：单文件 bug fix、UI 微调、写脚本。

高腐化区回流读取：系统自动读取历史高腐化区清单（见第十节），若任务涉及该区域：

· 强制建议走旁路模式避开源码级改动；
· 或按风险折扣调低预估收益，提高准入门槛；
· 或切分时配更细粒度的验收标准。

Phase 0：需求

产出五样：交付物、验收标准、边界、预算、冒烟场景。
其中场景分层包含：

· 冒烟场景：3-5 个核心路径，Phase 6 先跑；
· 完整场景：全量，冒烟过了再跑。
  完整场景须在 Checkpoint ① 前由 Phase 0 owner 产出、审核并冻结版本；后续变更走验收清单变更控制，不得执行中静默追加。
· 验收标准是全流程“北极星”，Phase 6 回来对照。每条验收项分配唯一 ID（供 Phase 3 覆盖性 diff 与 Phase 5 验收引用）。
· 文档类/设计类任务难量化时用反向量化：“随机抽 5 个新人，能独立按文档完成 setup 的比例 ≥ 60%”。样本选择、独立性、任务时限、成功定义须一并写入验收条款。

Phase 1：找现成

· 时间盒按任务类型弹性化：通用功能（auth、logging）15-20%；业务特有逻辑 5%；基础设施（DB schema、协议实现）25-30%。
· 百分比基数 = 该 Phase 的 token 预算配额；计时由 Code 层承担。
· 到时未出结论 → 默认标记“未完成/超时”，转 Checkpoint ③ 或人工批准延长；禁止直接判“确认没有”。延长须人工批准。
· 四档结论：
  1. 直接可用；
  2. 参考改写；
  3. 存在但不适配（验证失败）；
  4. 确认没有（附完整搜索记录）。
     注：“验证失败”与“确认没有”是不同状态——前者表示现成实现存在但不可用（含许可不兼容、依赖冲突、安全或性能不达标），后者表示未找到。禁止把验证失败降级记为“确认没有”，否则会丢失“可复用但需授权/修复”的线索。
· “参考改写”的门槛是验证强度：改写版必须通过原仓库全部测试 + 我方冒烟场景。原仓库测试仅作证据之一，不足以单独证明适配性（许可、依赖、安全、性能、完整验收项需另行检查）。
· 原仓库测试不可复现时（环境缺失、依赖失效、平台特定、耗时过长）：分类为“不可复现”，走豁免审批，以替代证据（我方冒烟 + 完整验收子集）作判据，不得直接判为验证失败。
· 改动幅度只作参考信号，不作门槛。
· 所有采用代码记来源与许可。

Phase 2：切模块

· 按“可独立验收”切分；标注依赖关系；同时划分文件所有权。
· 高腐化区回流读取：涉及高腐化区必须配更细验收标准或强制拆为旁路任务。
· 【Human Checkpoint ①】模块切分完成后人类审批——切错了下游全错，此处人工介入性价比最高。

Phase 3：写 brief

按第三节方法论撰写，每份 brief 必须包含：

· 要写/要改的文件清单（文件所有权声明，供 Phase 4 冲突检测用）；
· 上游就绪标志；
· 覆盖的 Phase 0 验收项 ID 清单（供 Code 层覆盖性 diff）；
· 若涉及重写：必须引用已知 Bug 清单 ID 与允许偏离声明（清单本体由独立 Reviewer 维护，实现方不得自行增删条目）。

上游就绪标志机器定义（Code 层据此 blocked/unblocked）：

```json
{
  "ready": true,
  "upstream_task_id": "string",
  "contract_version": "string",
  "evidence_uri": "string",
  "approved_by": "string | null",
  "expires_at": "ISO8601 | null"
}
```

满足条件：上游产物存在 + 测试通过 + 契约版本匹配 + 必要人工批准。失效条件：契约版本变更、上游产物被回滚、批准过期。发布者为 Code 层状态服务，非领导或 worker 口头声明。

Phase 4：派发

1. 冲突检测：领导比对各 brief 的文件清单，有交集的模块强制串行或重新切边界；Code 层文件锁兜底。
   冲突不只发生在文件层：资源级（数据库、端口、容器、缓存）、契约级（同一契约条目被多模块改动）、数据级（共享数据集/迁移目标）、环境级（共享测试环境）同样阻止并行，派发时须显式声明，不能只看文件清单有无交集。
2. 接口契约下发：下发 Phase 2 已生成、审批并冻结的契约文档（Contract as Code），所有 worker 输出必须符合契约。此处只做“下发与引用”，不含生成、修改或提交。
3. 无依赖并行、有依赖串行；并行数受 Code 层 max_workers 硬上限约束，超限部分拆批串行。

Phase 5：验收

详见第五节“失败阶梯与双轨测试”。

Phase 6：集成

1. 先跑冒烟场景，通过后再跑完整场景。
2. 接口契约对齐检查，分两层执行：
   · 类型层：由 Code 层编译器/类型检查器执行（TS / Protobuf / OpenAPI），LLM 彻底退出。
   · 行为层：由 CI 测试执行（TTL、轮换、幂等、状态机等语义约束），结果按契约条目归位。
     编译器只能覆盖类型层，不得以“类型通过”代替行为层对齐。
3. 对照 Phase 0 原始验收标准（按 ID）整体再过一遍。

三、Brief 写作方法论

核心原则：两个独立——agent 不靠追问能独立执行；验收者不靠主观判断能独立验收。
（“不靠主观判断”指尽量做到可验证；确属主观的项（代码评审、UI 验收）不视为违反本原则，按 5.1 双 Reviewer + 独立评审量表处理。）

要素 关键要求
① 目标 一句话：做什么 + 量化效果（或反向量化）
② 背景与依赖 上游/下游/参考实现（含来源与许可）、高腐化区警示
③ 交付物 具体到路径、签名、引用的契约条目
④ 验收标准 打勾式、可量化、禁主观词；每条量化标准配一条反作弊条款；逐条引用 Phase 0 验收项 ID
⑤ 资源与约束 工具白名单、禁用项、预算上限、文件所有权清单
⑥ 异常处理 歧义→停问；预算熔断条件；完不成→原因+已尝试+替代方案

反作弊条款示例：

量化标准 配套反作弊条款
测试覆盖率 ≥90% 无效断言（assert true）≤ 2 个
接口响应 ≤200ms 禁止用缓存跳过业务逻辑实现
文档覆盖 X/Y/Z 三节 反向量化：5 个新人独立 setup 成功率 ≥60%

（第 4 条“refresh 轮换断言”随端到端示例归档于附录 B。）

派发前五问：

1. 拿到 brief 能不问人就开始做吗？
2. 只靠验收节能判过/不过吗？
3. 有无主观词？量化标准有没有被 gaming 的空间？
4. agent 能自判“做完了吗”？上游就绪标志明确吗？
5. 文件清单和别的模块冲突吗？

四、Prompt 架构与 Code 层边界

领导 vs 干活

维度 领导 干活
核心职能 拆解/路由/跟踪/综合（不执行；对契约仅引用与提议，无写权限） 隔离上下文内有界子任务
Prompt 只负责 启发式决策：怎么拆、倾向派几个、怎么综合 工序+工具白名单+输出契约
Code 层负责 硬边界：max_workers、token 熔断、预算计数、文件锁、状态持久化 工具权限的物理隔离
上下文 看全局 + 读外置契约/依赖表/所有权表/高腐化区清单 只给切片
失败动作 判断“该我做还是派发” 信息不够就停下要

上下文预算分配

角色 分配
领导 系统提示 ≤10% ｜ 外置数据表 ≤20% ｜ worker 摘要 ≤50% ｜ 调度余量 ≤20%
worker brief ≤30% ｜ 参考代码切片 ≤40% ｜ 工具调用历史 ≤30%

预算基数：默认按当前模型调用窗口计算；任务累计 token 只用于预算池熔断。超额裁剪顺序：工具调用历史 → 参考代码切片 → worker 摘要；摘要失败时保留文件路径与哈希，不保留全文。安全边界：任何角色不得因裁剪丢掉契约版本与上游就绪标志。

领导 Prompt 框架

```markdown
# Orchestrator System Prompt
## 你的角色
调度者。只做：拆解 → 派发 → 跟踪 → 综合。判断逻辑在这份 prompt，
硬边界由外部 Code 层执行，你不需要记忆任何数量限制。
## 拆解规则（启发式）
拆成互相独立的子任务；拆不开就链式派发。
并行前倾向比对文件所有权表；是否真能并行由 Code 层按文件锁、资源/契约/数据/环境级冲突与 max_workers 共同判定，prompt 不下最终结论。
## 规模控制（启发式建议，具体上限由 Code 层执行，prompt 不写死数字）
- 简单：1 worker
- 中等：2 workers（= 手册 0.3 的**硬上限，不得超过**；起步期实际并发以该节为准，当前为 1 —— prompt 里的数字会被字面执行，别写超
- 复杂：并行上限由运行时配置注入（Code 层 max_workers 为硬上限，起步期值以《工程实施手册》0.3 为唯一权威源），超出部分自动拆批串行
## 路由判据
[if-then 规则，禁模糊词]
## 输出契约
派发任务附带：描述 / 工具集 / 引用统一契约文档的对应条目
## 失败根因分析（强制）
每轮修复前你必须输出一句话根因分析，并附证据引用（失败项 ID、日志位置、反证）。
输不出具体根因（只能说“再试一次”）→ 直接回 Phase 3 或升级人工。
## 综合规则
推理不是拼接：判可信度、识冲突缺口、取最强部分。
## 你的上下文里有这些外置数据（读它们，不要背规则）
- 接口契约文档（唯一 schema 来源）
- 依赖表（上游 blocked 则下游不发）
- 文件所有权表（派发前查冲突）
- 预算计数器（Code 层熔断，你只需在汇报时引用数字）
- 高腐化区清单（涉及该区域时强制建议旁路或调低预期）
```

Code 层硬边界

机制 内容
worker 上限 max_workers=**1**（起步期唯一权威值，见《工程实施手册》0.3；硬上限 2，放开条件见同处），超限自动降级：合并 worker 或转串行
调用上限 maxtoolcallsperworker=15，超限 kill 并标记。例外：test-runner 单独计费（完整测试套件常超出 15 次调用），上限按任务规模配置并计入硬总预算，不得挤占其他 worker 额度
预算熔断 单任务 token 超预算 120% → 强制中断；全局池耗尽 → 熔断
文件锁 声明冲突的文件在并行 worker 间物理互斥
工具沙箱 reviewer 无写权限：Bash 走显式只读命令白名单（仅 ls/cat/git show/grep 等），并由文件系统只读挂载兜底，不得只靠角色声明；builder 限定在其文件清单内写入，另加“生成物目录”允许写入模式（锁文件、快照、构建产物），越界写入须动态扩权审批
状态持久化 所有状态落盘（SQLite），进程重启后从 DB 恢复，支持断点续传
分歧比对 双 Reviewer JSON 比对由 Code 层执行，领导无“和稀泥”权限
同因/异因判定 Code 层用结构化信号指纹聚类，LLM 只给聚类结果命名
覆盖性 diff brief 的验收项 ID 集合 vs Phase 0 验收项 ID 集合，缺项判 brief 缺陷
计数口径 brief_rewrite 计数仅统计 L1 触发的 brief 重写（见 5.3）

熔断后业务状态：单任务 token 超 120% → 状态置 paused_for_budget，产物封存并写 manifest；下游置 blocked；恢复须人工批准或预算追加。全局池耗尽 → 状态置 circuit_broken，不再派发新任务，已运行任务允许收尾并封存。

预算池规则

· Phase 独立池 + 全局兜底。
· 分配 Phase 池时先从全局池预留，防止结余退回导致全局可用额度虚增。
· 结余结转：Phase 结案后结余转入全局池，不自动滚入下一 Phase。
· 超支路径：Phase 池耗尽 → 向全局池借调 → 全局池耗尽则熔断（LLM 不可绕过）。
· 借调上限：单 Phase 借调上限 = 该 Phase 原始分配的 50%。超出 → 熔断该 Phase，不继续抽全局池。
· 借调事件：每次借调写入 Checkpoint 汇报队列，防一个失控 Phase 悄悄抽干全局池。
· 非 token 成本账本：工具调用、云资源、CI 时间、人工评审、等待成本按任务归集，供结案实测 ROI 使用。

Observability

领导每次关键决策留一条结构化日志：为什么这么拆、为什么派给这个 worker、失败根因分析内容、为什么升级人工。

```json
{
  "event_id": "uuid",
  "timestamp": "ISO8601",
  "task_id": "string",
  "phase": "string",
  "event_type": "dispatch | failure | escalation | rewrite | human_checkpoint",
  "decision": {
    "what": "string",
    "why": "string",
    "alternatives_considered": ["string"]
  },
  "fingerprint": "string | null",
  "ladder_level": "L0-L3B | null",
  "token_cost": 0,
  "human_required": false
}
```

五、失败阶梯与双轨测试（Phase 5 核心）

5.1 验收流程

· Reviewer 对照全量验收清单逐项检查（修复轮次后必须重跑全量，防 Round 1 已过项回归）。
· 主观任务（代码评审、UI 验收）：双 Reviewer 独立判定，输出机器可读 JSON。
· 分歧外置：Code 层比对两个 JSON verdict。一致→过，分歧→触发 Checkpoint ③。

Reviewer verdict schema：

```json
{
  "verdict": "accept | reject",
  "blocking_issues": [
    {"id": "string", "acceptance_id": "string", "severity": "high | medium | low",
     "detail": "string", "fingerprint": "string", "evidence_uri": "string | null"}
  ],
  "non_blocking_issues": [
    {"id": "string", "acceptance_id": "string", "severity": "high | medium | low", "detail": "string"}
  ],
  "confidence": 0.0,
  "checklist": [
    {"item": "string", "acceptance_id": "string", "pass": true, "detail": "string",
     "evidence_uri": "string | null"}
  ]
}
```

verdict、blocking_issues、confidence、checklist 必填。
issue 用 id + acceptance_id + severity 结构化：Code 层据此做集合比对与严重度分流，禁止用自由文本做子集判定。

空报告规则（修正版）：判“无效”的是“未执行检查”，不是“检查后无阻断项”。

· checklist 缺失 / 覆盖的 acceptance_id 数少于应检验收项数 / 判定为 pass 的项无 evidence_uri → 视为未执行检查，判无效，转 Checkpoint ③。
· checklist 完整、逐项有 evidence、blocking_issues = []、verdict = accept → 正常通过，不触发 Checkpoint ③。
· 本规则的目的是防“永远报零”作弊，判定依据是检查执行的完整性，而不是“必须报出问题”。

分歧比对规则：

· 判定用子集容忍：以较小集合为基准判子集关系（按 id + acceptance_id 比对，不比文本），一方多报一条不算分歧。
· 修复范围用并集：A 报 {a,b,c}、B 报 {a,b} → 判定无冲突，但 c 按“待核实”跟修，不能丢。
· 严重度例外：被多报的那条 severity = high 时，不适用子集容忍，直接转 Checkpoint ③——严重阻断项不得降级为“待核实”。
· 空报告不参与容忍：任一 reviewer 未执行检查（按上方空报告规则判定）→ 判无效，转 Checkpoint ③。

5.2 失败阶梯（按状态迁移，禁止人工跳级）

每轮修复前，领导必须输出一句话失败根因分析，并附证据引用（失败项 ID、日志、反证）；无证据的根因分析不进入下一轮。

级别 触发条件 动作 信号含义
L1 同因失败 2 次（当轮失败指纹 = 上轮计入指纹） 回 Phase 3 重写 brief（自动限 1 次） 倾向 Brief 问题；需证据判据：目标/约束/依赖/验收描述确有缺陷
L2 指纹漂移（当轮失败指纹 ≠ 上轮计入指纹，且存在上轮计入指纹） 逃生舱（默认落妥协模式） 倾向模块问题；需区分连锁暴露 / 新引入回归 / 独立缺陷 / 随机漂移
L3 逃生舱两级用尽仍失败 标记高腐化区 → 升级人工决策 任务/架构问题
L3 分支 人工批准后 受控重写（新旧双跑）/ 顾问模式 / 旁路外挂 / 彻底放弃 —
拦截 L1 额度用尽后再失败 强制 Checkpoint ③，禁止自动第 2 次重写 权限控制

状态迁移表（唯一合法路径）：

· L0（首次计入，仅登记指纹）
· L0 → 同指纹 → L1 → 同指纹再失败 → 拦截（Checkpoint ③）
· L0 / L1 → 指纹漂移 → L2（妥协）→ 仍失败 → L2（顾问）→ 仍失败 → L3
· “不许跳级”指禁止从 L0/L1 人工直接升到 L3、或跳过 L2 直接进逃生舱；L2 由首次漂移直接触发属正常迁移，不是跳级。

判定顺序（机械执行，不许跳序）：

1. 先过滤三类不计入阶梯的失败（环境类 / brief 覆盖性缺口 / 依赖未就绪）；
2. 过滤后仍失败，才进入 L1-L3 定级。

比较基线口径：

· “上轮失败指纹” = 最近一次计入阶梯的失败指纹。
· 不计入阶梯的失败不更新比较基线，但其指纹照常登记（供高腐化区 failure_history 与 flaky 分析）。
· 首次计入阶梯的失败仅登记指纹，不判级（无基线可比）；自第二次计入起，与最近一次计入阶梯的指纹比对：同指纹 → L1，指纹漂移 → L2。

不计入阶梯的失败（Code 层判定，防误烧额度）：

类型 判定方式 处理
环境类失败 指纹标记为 infra/env（测试环境宕机、网络超时、依赖服务不可用） 不计轮次；Code 层按指数退避（1s/4s/16s + 抖动）重试，仅对可重试错误白名单生效，单任务总重试时限 5 分钟；超限仍失败转 Checkpoint ③
brief 覆盖性缺口 覆盖性 diff：Phase 0 验收项 ID 在 brief 中无对应条目（由 Code 层按 diff 判定，人工不得手工改判） 直接回 Phase 3 补 brief，不消耗阶梯轮次，也不计入 brief_rewrite_auto
依赖未就绪 上游输出与契约不符 下游置 blocked（见 5.5），先修上游

“补 brief”与“重写 brief”的区分标准（防把实质重写伪装成覆盖补缺以绕开计数）：

操作类型 判定主体 判据 计数
覆盖补缺 Code 层 仅新增缺失验收项 ID 及其对应条款；模块边界、文件清单、目标描述均不变 不计入
brief 重写 Code 层 上述之外的任何实质变更（改目标 / 改边界 / 改文件清单 / 改既有验收标准内容） 计入 brief_rewrite_auto

操作类型由 Code 层按 brief diff 自动判定，领导与人工均无权指定；判为“重写”即按 5.3 计数。

异因优先判 L2 的成本依据：

· 过早判 L2 → 便宜（妥协模式 = 一条技术债标注，可退出）
· 误判同因卡 L1 → 贵（烧重写额度 + 轮次 + token）
  因此：出现指纹漂移 → 优先判 L2，不回 L1。

L2 逃生舱落点序列：

触发条件 默认落点 升级条件
首次指纹漂移判 L2 妥协模式（补丁 + FIXME） —
妥协模式后仍失败 顾问模式（人工 IDE 接管） 持续恶化
顾问模式后仍失败 升级 L3 人工决策（受控重写 / 顾问 / 旁路 / 放弃） —

误触发代价 = 一条带标注的技术债，不是一次大手术。但高风险域除外（见下）。

同因/异因判定主体：

· Code 层用结构化信号指纹聚类（错误类型 + 失败文件集合 + 归一化消息）。
· 归一化策略：抹掉行号、绝对路径、时间戳、随机 ID，避免同一 Bug 被判成异因。
· LLM 只负责给聚类结果起名字（根因标签），不做同因/异因归类判断。

降级逃生舱三选一（L2 触发后；L3 人工决策亦可选用）：

策略 做法 适用场景
旁路外挂 禁止修改原文件，新建旁路脚本/模块调用原接口 老模块耦合严重改不动
顾问模式 剥夺 Write/Edit 权限，输出修改指南和 Diff，人类在 IDE 中手动接受（起步期退化：Diff 文本挂 mtask 待办，见〇bis 全局口径 3） 需要人类把关
妥协模式 允许硬编码/补丁实现，只要测试通过，强制打 # FIXME: Tech Debt 标签 只求功能跑通

落点决定权：L2 触发后默认落妥协模式；顾问模式与旁路外挂在 L2 阶段须经 Checkpoint ③ 人工决定；进入 L3 后由人工决策在四个出口中直接选用。

L2 顾问与 L3 顾问的区别：L2 顾问 = 首次人工接管，人类在 IDE 内改码后交回流程继续自动化；L3 顾问 = 前两级顾问均已失败后的兜底，须同时提交前次失败的根因结论。同一模块第二次进入 L3 时，若无新增信息，禁止重复选择顾问模式（须换受控重写 / 旁路 / 放弃）。

顾问模式闭环：人类改完后由人类或授权 agent 提交，提交信息关联原 task_id；回归测试从原阶梯的下一轮重新入梯，指纹按新失败重新登记；若人类改动实际等价于 brief 变更，须补走覆盖性 diff。

妥协模式的禁用域（**只列最常撞到的 5 项；完整清单以《工程实施手册》3.1.2 的 10 项为准**）：认证、支付、权限、数据迁移、生产配置类模块禁止默认落妥协模式，指纹漂移即直接进 L2 顾问或升 L3——补丁在这些域不是“一条可退出的技术债”。

技术债闭环：妥协模式产生的 # FIXME: Tech Debt 必须自动登记 owner、到期日、风险等级、关联工单；逾期未清偿则阻断该模块后续进入受控重写，直到债务关闭或人工豁免。

5.3 重写权限控制

注意区分两种“重写”：本节指 Phase 3 回退（brief 重写）；5.4 的受控重写是代码级重写，由 L3 人工批准，单独计数。

· 自动路径回退 Phase 3 上限 1 次（Code 层锁定 brief_rewrite_auto ≤ 1，用尽后禁止自动触发）。
· 人工批准（Checkpoint ③）可授权第 2 次。
· 累计上限 2 次（Code 层锁定 brief_rewrite_total ≤ 2）。第 2 次用尽后再失败 → 强制转逃生舱或彻底放弃，不再提供重写选项。
· 计数口径：brief_rewrite_auto / brief_rewrite_total 仅统计 L1 触发的自动或人工批准 brief 重写。覆盖性缺口导致的补 brief 属 brief 缺陷修复，两者均不计入。

5.4 受控重写（新旧双跑）

触发条件：L3 人工批准后选择“受控重写”。

重写入场三前提（缺一不启动）：

前提 校验方式
接口清晰 契约文件存在且通过类型层编译
有测试保护 灰轨自指验证通过（原代码 100% 绿）∧ 白轨生成与对账完成（见下）
旧版可保留 旧实现代码/分支可冻结，不被删除

双轨测试分离：

轨道 断言对象 100% 通过要求 重写时的角色
特征测试（灰） 旧实现现状（含 Bug） 是（原代码上），固化基线 只允许已知 Bug 清单内条目翻转
契约测试（白） 接口契约定义的应有行为 是（新实现上），含修复项 全部必须绿

白轨生成期三支裁定（白测试生成后先跑在旧实现上，失败项逐条裁定）：

裁定结果 动作
测试生成错误（测试未忠实编码契约） 重新生成测试，契约不动；同一契约条目重生成上限 3 次，仍失败转 Checkpoint ③
契约定义有误 人工批准改契约（Checkpoint ③）→ 重新生成
契约正确、旧实现存在未知 Bug 补录已知 Bug 清单（由独立 Reviewer 执行，实现方不得自批），该条即授权翻转项；随灰白分类审计同次人工复核

对账完成 = 白轨在旧实现上的失败集合，每条均已归位（契约已修或已补录清单），无未裁定项。此对账是已知 Bug 清单完整性的系统性来源（对应开放问题 7）。

白测试失败的两个时期：

时期 白测试失败含义 处理方式
生成期（跑在旧实现上） 契约可能有误 或 旧实现存在未知 Bug 走上方三支裁定
重写期（跑在新实现上） 实现违约 重写 agent 修实现，禁止自行修改契约；确属契约有误须走 Checkpoint ③ 审批后由授权方变更

硬规则：重写 agent 禁止自行修改契约，也无权触发契约变更流程。契约变更一律过 Checkpoint ③，由人工审批后由授权方执行。
白测试必须从契约生成：白测试是契约文件（.proto / interfaces.ts / OpenAPI）的编译产物，禁止手写。

放行条件（形式化）：

```
放行 = 白轨全绿（新实现上）
     ∧ 灰轨失败集合 ⊆ 已授权翻转清单
     ∧ 每个已授权翻转项都有对应白测试通过，或有明确的“放弃修复”记录（含批准人与理由）
```

（“已授权翻转清单” = 已知 Bug 清单中经批准可翻转的条目集合。）
第三条是双向覆盖约束，不可省：只查“灰轨失败 ⊆ 清单”无法发现“清单内条目实际未修”。

灰测试红了不自动算过也不自动算挂，逐条对照已授权翻转清单。

清单外翻转裁定流：

裁决结果 动作
补录清单（确认是存量 Bug） 该条加入已授权翻转清单；对应灰测试标记“被白测试 X 取代”并归档至 archived/（保留溯源，防灰套件红灯膨胀）
真回归（新代码引入的破坏） 修复新代码，灰测试恢复绿

灰/白分类审计：挂在已知 Bug 清单的人工批准环节（Checkpoint ③），一次人工同时审批清单与审计分类。该灰标白 → 重写被迫保留存量 Bug，白测试永远不绿；该白标灰 → 制造假回归。

对比归一化（Code 层执行）：忽略字段（时间戳、随机 ID、trace_id）；浮点容差默认 1e-6。
列表比较：是否排序由契约逐字段显式声明（ordered / unordered）。禁止全局默认排序；契约未声明的字段按 ordered 保守处理。

已知 Bug 清单产出方：独立 Reviewer 产出，实现方 brief 中只引用清单 ID，不得自行增删。

特征测试自指验证：AI 生成的灰轨测试必须先跑在原代码上且 100% 通过，排除 flaky 和误生成，再谈覆盖度。
例外路径：若原代码存在 flaky 或环境依赖导致无法 100% 绿，先隔离 flaky、固定环境、采样稳定性；仍不可建立灰轨时，转 Checkpoint ③ 人工批准替代基线，不得直接跳过。

放行后闭环：
双跑放行 → 旧实现下线（或设观察期，默认 7 天）
→ 新实现重入 Phase 6（冒烟 + 全量）
→ Phase 6 通过 = 重写闭环完成
→ Phase 6 失败 = 回滚旧实现，标记该模块重写失败
（再次受控重写需新一轮 L3 人工决策，不自动重试）

5.5 依赖链阻塞

上游 worker 未通过验收 → 下游自动置为 blocked，不派发不烧 token。

六、Worker 分类（定义 4 类，起步启用 3 类）

类型 工具 职责
① repo-scout（研究型） Read, Grep, Glob, WebFetch 找现成实现，输出四档结论
② builder（实现型） Read, Write, Edit, Bash 读上游接口→实现→跑测试。禁越界写入
③ reviewer（审查型） Read, Grep, Glob + Bash 白名单 对照全量验收清单逐项检查，输出 JSON verdict
④ test-runner（运行型） Bash, Read 跑命令只回摘要，超时强制 kill

**已删除（2026-09-19 对齐实际）**：原 ⑤ data-worker（SQL client / CSV parser / ETL）与 ⑥ deployer（Docker / K8s / cloud CLI）两类。理由：本机无容器运行时（docker / podman 均不存在）、无数据库、无部署目标，留着只会让“六类”这个名字诱导照跑；对应返回 schema 亦从附录 A 删除。将来真有基础设施时按 v2.4.4 备份（多Agent协作流程设计文档_v2.4.4.md.bak_pre_realign_20260919）恢复。

类型注册表（唯一命名来源，别名不得独立成类）：

· code-reviewer = ③ reviewer 的别名；
· debugger = ② builder 的工序变体（工具集同 builder，增加断点/日志分析工序）。
  二者均非独立类型，实现时按注册表映射，不得出现表外类型名。

扩展优先级：起步启用 3 个 = ② builder / ③ reviewer（含 code-reviewer 别名）/ ④ test-runner；debugger 变体按需在 builder 上加载。data-worker / deployer 已删（见上），monitor 放最后。


明确不加：planner worker、design worker——规划是领导的活，拆出去徒增通信成本。

Monitor 型 worker 方案：不用持续占用 LLM context。传统后台进程（Prometheus/Cron）做长时监控，异常时唤醒 Agent 分析。将“长时监听”成本从 LLM 转移到廉价传统计算资源。

七、模型路由

起步期：全部统一用主力档跑通，不做任何分档。理由：初期 worker 分类本身都可能要改，分档是过早优化；路由判断本身耗 token、判断错是灾难。

起步期例外：架构、安全、验收三类任务仍使用最强推理档，不受“统一主力档”约束——这三类降级的收益不值得冒险。

稳定后静态降级（worker 定义时写死档位，不做运行时动态路由）：

档位 用途 降级时机
长程自主档 多小时运行、大型迁移 按需
最强推理档 架构、安全、验收 不降
主力档 一般编码 默认
中档 文档、测试、调试 验收通过率稳定后
轻量快速档 运维（原“部署”类已随 deployer 一并删除） 验收通过率稳定后

降级安全阀：降级后该类任务验收通过率下降 >10% → 自动回退原档位。
统计窗口：最小样本 30 次同类任务，观察周期 14 天；区分绝对下降与相对下降，按任务难度分层；未达样本量不得自动回退，只告警。

八、避坑清单

1. 领导 prompt 是最脆弱的单一故障点——改 prompt 必须过回归测试集（10 个典型任务），不跑全流程。
2. 综合 ≠ 拼接——只拼接等于白花 token。
3. 上下文反噬——worker 返回限长，详细结果写文件只回摘要。
4. description 写成路由规则——“修改代码后立即使用”可靠触发；“资深工程师”人设基本不触发。
5. Worker 不是越多越好——子任务真正独立时加 worker 才有收益。
6. Token 成本提前算——多智能体消耗约为普通对话 15 倍起步，复杂任务实测 30-50 倍。
7. 慎用强指令——“必须/永不/总是”会被字面化理解，倾向具体条件描述。
8. 领导 prompt 不堆规则——规则外置到 Code 层和外置数据表，prompt 只留判断逻辑。
9. 特征测试自指验证——灰轨测试必须先在原代码上 100% 通过，排除 flaky，再谈覆盖度。
10. 规则双重实现必须一致性测试——prompt 内硬提示与 Code 层硬边界同时存在时，以 Code 层为准，并用回归集校验 prompt 不诱导违规。

九、Human Checkpoint 机制

检查点 时机 理由
① Phase 2 切分完成后 拆错了下游全错，人工审批性价比最高
② Phase 4 派发前（可选） 高预算任务审批 brief
③ Phase 5 主观分歧 / L3 阶梯 / L1 自动重写额度用尽后再失败、申请第 2 次 brief 重写 / 灰白分类审计 / 清单外翻转裁定 / 契约变更审批 / 环境重试超限 强制介入，防和稀泥与盲目烧钱

Checkpoint 响应规则：

项 规则
责任人 按任务域指定 owner；未指定则默认项目技术负责人
SLA **起步期不适用**：单人项目没有组织、没有值班，"4 小时"这类 SLA 与"超时默认动作"都没有计时器可挂——改用**待办提醒**替代：需要人工拍板的事写进 `/root/mas`（`mtask todo add`），每日 09:00 有未关闭项就提醒一次（纯脚本、零 LLM）。等真有多人协作再回填 SLA
拒绝后流向 回上一稳定状态或转 L3 人工决策，不得静默重试
授权有效期 单次有效（"7 天过期重审"由待办提醒兜底，不做自动失效）

计划内的人工介入不违反“不靠追问”原则——追问是执行中的被动打断，checkpoint 是流程中的主动设计。

十、高腐化区记录结构

字段 说明 列名
zone_id 主键 zone_id
module_path 精确路径（默认按模块/目录粒度划 zone；文件级或跨模块故障由 Checkpoint ③ 人工修订，支持子 zone 继承父 zone 属性） module_path
failure_history 失败史（指纹+轮次），JSON 数组 failure_history
max_ladder_level 该区域历史最高 L 级 max_ladder_level
escape_hatches_used 用过的逃生舱类型 escape_hatches_used
resolution 结局：旁路/重写/放弃/未解决 resolution
post_rewrite_regression_rate 重写后回归率（重写完成后回填） post_rewrite_regression_rate
fail_count 累计失败次数 fail_count
suggested_bypass 旁路建议（标记时留空，由 Checkpoint ③ 人工补齐） suggested_bypass
created_at / updated_at 时间戳 created_at / updated_at

列名以本表为准（此前版本中的 maxladderlevel / escapehatchesused 等无下划线写法为笔误，已废弃）；DB schema 需带版本与校验，迁移时同步。

回流读取：Phase -1 读 fail_count、max_ladder_level、resolution 调整 ROI 预期；Phase 2 读 failure_history、escape_hatches_used 调整切分边界和验收粒度。

十一、Contract as Code

层 内容 执行方式
类型层 TS interfaces / Protobuf / OpenAPI，worker 直接 import Schema 违规编译期就挂
行为层 行为约束（如 ttl≤15min、轮换断言） 写成 CI 测试

契约生命周期（唯一时序，消除“Phase 2 生成 / Phase 4 下发”的前后漂移）：

阶段 动作
Phase 2 生成（人类或最强推理档模型）→ 人工审批 → Commit 到 Git → 冻结（此后进入变更控制）
Phase 3 brief 只能引用契约条目 ID，不能修改
Phase 4 领导下发冻结版本给 worker（只引用，不修改）
Phase 5 / 6 类型层由编译器强校验；行为层由 CI 测试执行

契约 owner：指定人类 owner（或经授权的契约 agent）持有 Git 身份与写权限，负责冲突处理与保护分支规则。领导进程对契约只有引用权与变更提议权，无写权限、不得自行提交（与“领导不执行”一致）。

白测试（契约测试）是契约文件的编译产物，禁止手写。能力边界：结构类断言可由契约自动推导；轮换、幂等、安全语义、状态机等行为断言需人工设计或人工审核生成结果，不得声称完全自动化。契约示例见附录 B。

十二、标定与验收

12.1 异因指纹粒度标定

【起步期不执行（2026-09-19）】本节依赖 10 个典型任务 × 3 类故障 = 30 个失败样本的语料，而当前真实跑过的任务数 = 1（且没有注入故障的 harness）。起步期只做最低限度记录：每次失败记下 错误类型 / 涉及文件集合 / 归一化报错原文 / 定级结果，攒够样本再回来执行本节。

先标定指纹粒度、缓扩 Worker。指纹错一档，决定的是钱烧在 L1 死循环还是 L3 人工，比 max_workers 更贵的参数。

1. 10 个典型任务复用 prompt 回归测试集（一份资产两用）。
2. 每个任务注入 3 类故障：同因重复、异因漂移、跨模块关联。
3. 跑指纹聚类，记录分类准确率。
4. 调归一化正则，直到 30 个样本分类准确率 ≥ 90%。

健康线：

指标 健康阈值 异常含义
L3 占比 ≤ 20% 超过 → 按多因素顺序排查
卡死 L1（同因误聚 ≥2 轮才挣脱） 0 次 出现 → 粒度过粗
直冲 L3 占比 ≤ 10% 超过 → 指纹粒度过细或逃生舱落点不当

每次标定记录四指标：L1/L2/L3 分布；重写额度消耗（自动/人工批准）；每任务 token 成本；误判人工裁定次数。

指标归因规则：健康线指标是诊断信号，不直接绑定单一根因。L3 占比升高需按多因素顺序排查——任务选择是否不适配 → worker 能力是否不足 → 契约质量 → 环境稳定性 → 预算是否过低 → 最后才是指纹粒度。禁止“指标异常即调指纹”的单因归因。

12.2 运行期度量指标（上线后盯这些数字）

指标 健康线 恶化动作
首轮通过率 ≥ 60% 低于 → 检查 Brief 质量 / 指纹粒度
平均修复轮次 ≤ 1.5 轮 超过 → 检查 L1 是否误聚同因
升级人工率 ≤ 15% 超过 → 检查粒度过细或任务不适配
重写后回归率 ≤ 5% 超过 → 检查灰/白分类质量
L3 占比 ≤ 20% 超过 → 按 12.1 多因素顺序排查，不直接调指纹
卡死 L1 次数 0 出现 → 指纹粒度过粗
ROI 实测 ≥ 设定阈值（**起步期暂不设**，见 Phase -1 口径；设线后回填此处） 低于 → 该类任务移回单 agent，校准 Phase -1 预估
契约违规次数 趋近 0 频发 → 契约文档不清晰或白测试生成有误

ROI 实测口径：实际 token × 单价 + 工具/云资源 + CI 时间 + 人工评审 + 等待成本；不得继续使用立项预估分母。

12.3 Code 层验证方法

Stress test：故意给超大任务，看系统是否崩溃或烧爆 token——会，就是 hard limit 没做对。（**起步期只在 CI runner 或带内存上限的环境做**：本机 1.6GB 无 swap，故意 OOM 等于自伤。）

十三、待验证的开放问题

1. ROI 阈值该定在哪？（起步期暂不设；实测样本 ≥3 个后回填）
2. “首次指纹漂移即判 L2 + 逃生舱两级用尽升 L3”的新阶梯能否有效拦截打地鼠模式？（触发条件已从“异因 2 次”改为“首次漂移”；基线已限定为“最近一次计入阶梯的失败指纹”）
3. Monitor“传统代码监控 + 异常唤醒 Agent”方案是否跑通？
4. max_workers=1（起步期）下领导综合质量是否达标？放开到 2 之后呢？
5. Contract as Code（类型层+行为层）是否完全阻断契约漂移？
6. 特征测试“自指验证 + 已知 Bug 清单”能否安全支撑受控重写？
7. 已知 Bug 清单完整性：生成期对账是清单的系统性来源，但覆盖率与人工补录橡皮图章风险待验证；补录已限定由独立 Reviewer 执行，第二人复核必要性待实测确认。
8. 异因指纹聚类粒度标定：过粗卡 L1，过细直冲 L3。
9. 规则双重实现一致性测试是否足以防止 prompt 与 Code 层漂移？
10. Checkpoint 响应 SLA 在真实组织内是否可执行？

十四、修订记录

版本 变更 来源
v2.0→v2.1 Phase -1、ROI 公式、Code 层硬边界、Reviewer Bash 白名单、依赖链 blocked、契约统一维护、反作弊条款、场景分层、模型路由起步统一、文件所有权、时间盒弹性化、Worker 扩至 6 类、Observability、Human Checkpoint 一轮评审
v2.1→v2.2 失败类型分类（v2.4.2 起精简为三类；原“五分类”已废弃）、verdict/worker/日志 schema、上下文预算分配、度量指标、端到端 JWT 示例、Contract as Code、状态持久化、预算池隔离 二轮评审
v2.2→v2.3 五级阶梯雏形、重写权限、逃生舱、受控双跑、高腐化区回流、预算结转 三轮评审
v2.3→v2.4 双轨测试四细则、异因优先判 L2、借调上限、腐化区 schema、子集容忍补充、标定验收线 落地实现 + 三轮评审增量
v2.4→v2.4.1 七处修复；恢复 verdict schema、运行期指标表、日志 schema、上下文预算分配表；恢复失败类型精简版；生成期三支裁定、白轨对账措辞、旁路回 L3；悬空引用清理、开放问题 2/7 改写、Checkpoint ③ 补契约变更；新增附录 A、附录 B 四轮评审 + 合并期补漏
v2.4.1→v2.4.2 五轮复核收口，全部为口径澄清：判定顺序、比较基线、brief_rewrite 计数、重写期措辞、L3 出口、生成期裁定上限、附录 B ROI、批 2 拆批、Checkpoint ③ 第 2 次重写、清单名等价 五轮复核
v2.4.2→v2.4.3 Sol 复核 87 条中的 A 组硬伤 34 项并入，仍为消歧/补定义：空报告规则、issue 结构化、放行双向覆盖、列表排序、契约生命周期与 owner、Phase 6 双层、补 brief/重写判据、状态迁移表、环境退避、非文件冲突、worker 注册表、Phase 1 四档、字段统一、修订记录废弃五分类、prompt 去数字、reviewer 只读兜底、起步期例外、test-runner 单独计费、时间盒基数、M5 并行依据、五样 vs 四件套、指标多因素归因 Sol 复核
v2.4.3→v2.4.4 Step 1 一致性硬伤：总数统一为 87；标题分类改为 B 补定义 / C 工程手册 / D 框架级；附录 B 契约 owner 修正；repo-scout 四档；L1 后同指纹/漂移分流；12.2 多因素归因；Phase 1 超时不得默认“确认没有”；附录 B 基数分池说明；Phase 5 标题改 v2.4.4。Step 2 B 组 22 项补定义：ROI 量纲与预估/实测口径、调低预期方向、适切性拆分与样本窗口、纯创意偏好评测、反向量化样本量、上下文预算基数、根因证据判据、完整场景责任与冻结、上游就绪机器定义、token 熔断业务状态、顾问闭环、高腐化区粒度、灰轨例外、模型降级统计窗口、Checkpoint SLA、技术债闭环、分层 DoD、规则双重实现一致性、第 2 次重写权限状态机 五轮复核 + Sol 分诊表

**v2.4.4 勘误（同版修正，不升版号）**：起步期 `max_workers` 的全文口径以《工程实施手册》v0.3.0 的 0.3 节为唯一权威源（**数值见该节，本文件不复述** —— 曾有一版在此复述时写错，见勘误 3），涉及机制表、开放问题 4、附录 B 批排程、运行时注入说明。

**v2.4.4 勘误 3（2026-09-19 复核，同版修正，不升版号）**：此前一处勘误曾把起步期 `max_workers` 写成 2 —— **作废**，统一回 **1**。理由有二：①2026-09-19 实战属无锁阶段，2~3 并发当场出现 3 次文件冲突告警；②本机 worker 是远端 API 调用、不吃本地内存，这个数字的约束来自**工作区冲突**而不是 RAM。硬上限 2 与放开条件（文件所有权机制连续 3 次派发零冲突）写在手册 0.3 节，本文件不再复述数值。附录 B 的 Phase 4 排程保留按 2 编排的版本，并已标注「仅作放开后参考」。

**v2.4.4 勘误 2（2026-09-19，同版修正，不升版号，对齐首跑实测）**：① 新增〇bis「起步期实际口径」——声明 Code 层尚未实现、本文档关于硬边界的条款均为目标态，并附首跑计划 vs 实际对照表；② 第六节删除 ⑤data-worker / ⑥deployer 两类（前提是容器运行时 / 数据库 / 部署目标，本机均不存在），附录 A 对应返回 schema 同步删除。原文备份：`多Agent协作流程设计文档_v2.4.4.md.bak_pre_realign_20260919`。配套变更：《工程实施手册》0.3 本机实测值更新（内存 / swap / docker / 磁盘复测）、新增《多Agent文档_失配清单_v1.txt》与《多Agent项目_状态更新_v3.txt》。



附录 A：Worker 返回 Schema（4 类；起步启用 3 类）

repo-scout

```json
{
  "status": "done | need_clarification",
  "conclusion": "direct_use | adapt_reference | exists_but_incompatible | not_found",
  "verification_failure": {"reason": "string", "evidence": "string"} | null,
  "candidates": [{
    "url": "string", "license": "string", "last_commit": "date",
    "verification": "原仓库测试+我方冒烟通过 | null",
    "adapt_note": "改动幅度参考信号，非门槛"
  }],
  "search_trace": ["query/source"],
  "license_conflicts": []
}
```

字段名以本 schema 为准：conclusion = not_found 时 search_trace 必填完整；conclusion = exists_but_incompatible 时 verification_failure 必填。禁止使用 notfound / searchtrace 等无下划线写法。

builder

```json
{
  "status": "done | blocked | need_clarification",
  "files_changed": [{"path": "string", "summary": "one line"}],
  "tests": {"passed": 0, "failed": 0},
  "contract_refs": ["contract#section"],
  "reuse_notes": [{"source": "url+license", "where": "path"}],
  "blockers": []
}
```

reviewer

即 5.1 verdict schema，不重复定义。

test-runner

```json
{
  "status": "done | timeout_killed",
  "summary": {"total": 0, "passed": 0, "failed": 0, "skipped": 0},
  "failures": [{"name": "string", "error_head": "首3行"}],
  "log_path": "详细日志落盘路径，不进主上下文"
}
```

（原 **data-worker** 与 **deployer** 两个返回 schema 已于 2026-09-19 删除：本机无数据库、无容器运行时（docker/podman 均不存在）、无部署目标，对应 worker 类型已从第六节移除。将来真有基础设施时按 `多Agent协作流程设计文档_v2.4.4.md.bak_pre_realign_20260919` 恢复。）

附录 B：端到端示例（JWT 迁移）

任务：用户认证从 session 迁移到 JWT，涉及 80+ 文件。

Phase -1：单 agent 试跑 3 次均偏（80 文件上下文超限）✓；输出可验证（187 存量测试）✓；ROI ≈ 3.4 ≥ 示例阈值 3 ✓（示例数字，仅示范流程；本项目起步期暂不设阈值）。

Phase 0：交付物 = 迁移代码 + 迁移指南 + 回滚方案。验收（每条带 ID）：A1 存量 187 测试全过；A2 新增 12 测试全过；A3 access token TTL ≤15min；A4 refresh 轮换生效；A5 恶意样本拒绝率 100%；A6 认证中间件 P99 增幅 ≤5ms。边界 = 不迁移 OAuth、不改权限模型。预算 = 5M token、3 天。冒烟 5 条：登录→带 token 访问→refresh→登出→过期拒绝。完整场景由 Phase 0 owner 在 Checkpoint ① 前冻结。

Phase 1（基础设施类，时间盒 28%）：本任务总预算 5M token 先分池，Phase 1 池 = 5M × 28% = 1.4M token；由 Code 层计时，到时未出结论标记“未完成/超时”，转 Checkpoint ③，不默认判“确认没有”。jose 库 → 直接可用（MIT、活跃）；迁移教程 → 参考改写（通过原仓库测试+我方冒烟，原仓库测试仅作证据之一）；双 token 并存中间件 → 确认没有（附 search_trace）。

Phase 2（→ Checkpoint ①）：M1 token-service → M2 中间件（双 token 并存）→ M3a-d 路由迁移（80 文件按目录切 4 批）；M4 前端 token 存储；M5 e2e 补齐。

文件所有权表：M1=src/auth/token-service/；M2=src/middleware/auth.ts；M3a-d=src/routes/{admin,user,order,billing}/；M4=web/src/auth/；M5=tests/e2e/（应用代码只读）。

契约（类型层示例）：

```yaml
# auth-contract.yaml —— 契约 owner 维护，领导与 worker 只读
jwt_payload: {sub: string, role: enum[admin,member,viewer], exp: int, jti: string}
access_token: {ttl_seconds: 900, header: "Authorization: Bearer <token>"}
refresh_token: {rotation: true}
error_response: {code: enum[AUTH_EXPIRED, AUTH_INVALID, AUTH_REVOKED]}
```

行为层（CI 测试）：轮换断言、TTL 上限断言。
反作弊条款第 4 条（随本示例归档）：A4 refresh 轮换生效 → 断言：轮换前后 refresh token 值不相等 ∧ 旧值使用返回 AUTH_REVOKED。

Phase 4（**按 max_workers=2 编排，属「放开后」参考版本**；起步期 max_workers=1 时全部改为串行、只保留批的先后顺序）：批 1：M1 ∥ M4；批 2：M2 → M3a ∥ M3b；批 3：M3c ∥ M3d；批 4：M5（受 max_workers=2 约束，原三路并行拆为两批）。
M5 可并行的依据：M5 拆为“用例编写”（不依赖迁移实现，可基于契约先行）与“最终全量重跑”（依赖 M1-M4 全部完成）。批 3 的 M5 仅指用例编写部分；最终重跑固定在 Phase 6、所有迁移模块通过后执行，用例版本需与冻结契约版本一致。

Phase 5 实录（v2.4.4 规则重演）：

· Round 1：M3b 失败（A4 轮换断言红，指纹 rotate_assert_fail）。按判定顺序先过滤：覆盖性 diff 发现 A4 未在 brief 验收 ID 清单中 → 判 brief 覆盖性缺口 → 回 Phase 3 补 brief（补轮换条款 + 反作弊断言）。该次失败不计阶梯轮次、不计入 brief_rewrite_auto；指纹照常登记，但不更新比较基线。
· Round 2：通过。
· 对照演示阶梯路径（假设 Round 2 未通过）：Round 2 是首次计入阶梯的失败 → 仅登记指纹，不判级；Round 3 失败且指纹漂移（如 middleware_order）→ 判 L2，默认落妥协模式；持续失败 → 升顾问模式 → 再升 L3 人工决策（受控重写 / 顾问 / 旁路 / 放弃）。

Phase 6：冒烟 5 条全过 → 全量 199 测试 → 契约对齐（类型层编译器 + 行为层 CI 测试）→ 按 ID 对照 A1-A6 → 交付四件套（代码 / 指南 / 回滚方案 / 日志包）。

清单区分：Phase 0 的“产出五样”（交付物、验收标准、边界、预算、冒烟场景）是需求阶段产物；本例的“交付四件套”是客户交付物。二者不同层级，冒烟场景与验收标准已作为交付物附件（指南、日志包）的组成部分随行，不单独列为第五件。

参考来源

· Anthropic《How we built our multi-agent research system》(2025.6)
· Claude Code Subagents 官方规范 (2025.7)
· wshobson/ai-agents 与 VoltAgent 社区实践
· AgentPatterns.ai (2026) Orchestrator-Worker 模式总结
· Michael Feathers, Working Effectively with Legacy Code（特征测试模式）
· 第一~五轮评审与落地实现反馈（已整合）
· Sol 复核（逻辑漏洞 24 / 不可执行 21 / 缺失项 20 / 冲突 18 / 框架级 4，共 87 条）——A 组硬伤与 B 组补定义已并入 v2.4.4，C 组见《工程实施手册》，D 组待拍板

定稿说明：v2.4.4 已并入 Step 1 一致性硬伤与 Step 2 B 组 22 项补定义，仍未新增工程子系统。C 组 28 项转《多 Agent 工程实施手册 v0.1》，D 组框架级 4 项待拍板。下一步应执行 12.1 标定（10 任务 × 3 类故障），由实测数据决定是否还有第六轮。