多子代理并行研发编排

1. 契约先行（并行的前提）

• 动手前把跨仓库协议写成一份设计文档（消息流/entry 编码/字段/错误码/端点契约），作为所有子代理的唯一事实源；文档放主仓库，其它仓库的子代理按路径读取。
• 子代理 prompt 必须自包含：worktree 路径、必读清单（设计文档具体章节 + 目标仓库的 AGENTS.md/README/既有范式文件）、交付物清单、验证命令、禁止 commit/push、报告格式（文件清单/测试结果/与设计偏差）。
• 分仓认领，一人一仓一 worktree，统一分支名（跨仓库一致便于批量管理）；worktree 从最新 origin/master 创建。

2. 早期契约审查（落盘即审，不等交付）

• 子代理开始落盘后，协议关键文件一出现就读（消息结构体/编解码层/报文组装），对照设计逐字段核：一旦发现漂移立即 send_message 批回修正——修复成本在落盘期最低。
• 双向核对：UI 的 API 层字段 vs 后端响应结构；服务端 entry 编码 vs 平台解析路径；跨服务同名约定（如时间戳格式、错误码大小写）必须三端比对。
• 容错点前置声明：允许的输入差异（如 ts 多格式、可选字段缺失）在消费者侧显式兼容，而不是要求所有生产者严格一致。

3. 独立复测纪律（不信任，要验证）

• 子代理报告的"测试通过"必须由主 agent 实跑复核（同命令再执行一次）。
• "既有失败"申报必须对照证实：git stash 后在干净树复跑，或用纯净 master 临时 worktree 复现（后者还能顺带发现 master 上的存量阻塞——本次实战曾借此发现 sed 破坏 protobuf rawDesc 导致全量测试 panic 的基线 bug 并顺手修复）。
• 真实服务 E2E 兜底：单元测试对跨仓库集成无能为力。起真实中间件（Docker Redis）+ 真实子进程服务 + 平台真实模块跑全链路，integration build tag 隔离入库可复跑——本次抓出 3 个单测发现不了的 bug（回执缺失、权限契约不匹配、重复签发令牌）。

4. 推进节奏与安全

• 主 agent 只做：worktree/分支创建、契约管理与增量批注、审查、复测、提交；实现全部下沉子代理；主 agent 可认领无人覆盖的接缝件（如本例的 video 路由接缝）。
• 提交需用户明确授权；有进展才 commit+push（每仓库一次成型提交 + 后续增量修复提交），身份用研发本人（git-identity）。
• 子代理空转 2~3 轮无落盘时发优先级指引并要求遇阻塞显式上报；文件分钟级 mtime 是最廉价的活性探针。
• 修复链上新 bug（如改 A 引入编译错）要立即补提交修复，不留坏分支。

5. 子代理规模与生命周期治理（防无限膨胀）

• 单代理=一个可独立验证的交付单元（一仓库或一明确功能）。范围要扩=拆新代理，不给老代理加戏。
• 活跃并发上限 3~5：按仓库/领域分槽，超出排队派发；长驻的只有主 agent（编排/审查/提交），worker 一律按需。
• 完成即收口：复核→commit→归档报告，不再 send_message 复活已 inactive 的代理；新需求开新代理（干净上下文）。
• failed ≠ 产物作废：异常退出的代理可能已留完整工作区改动——先 build/test 甄别再决定采用或回滚，不盲目丢弃或盲目信任。
• 定期盘点：list_agents 只看 running；inactive 列表只是账本，不是可调用资源池——膨胀来自历史账本而非真实并发。

6. 里程碑触发的自我完善闭环（长效机制）

• 触发点：方案定稿、全仓交付、集成联调通过、重大坑修复后——四处任一发生即评估沉淀。
• 流程：评估（本里程碑有无可复用经验/新坑）→ 提炼为技能新节或新技能 → fork 分支 + PR（无权限仓库一律 fork+PR，绝不直推 master）→ 研发 review 即质量关卡 → 合并后覆盖式升级本地技能库。
• 纪律：只沉淀可复用方法论，不写项目私货；每次 PR 单一主题、附带出处里程碑，便于 review。