多 Agent 协作交接（agent-team-handoff）

把一群 AI 助手变成一支有纪律的团队：谁在干什么、干到哪了、下一步是什么，全部落在文件里，任何成员随时接续。

一、共享目录约定（团队唯一事实源）

在项目外建一个共享目录（示例名 .team-shared/），固定放四份文件：

文件	内容	更新时机
CURRENT-TASK.md	当前任务交接单（状态/负责人/进度/下一步/证据）	每次实质进展
HANDOFF-RULES.md	团队协作规则全文（本技能的本地化版本）	规则变更时
MEMORY-SNAPSHOT.md	共享记忆快照（决策、偏好、踩坑）	定期/重大决策
AGENT-ROLES.md	成员角色表与能力分工	编制变化时

规则：所有成员只认这份目录，聊天记录不算数。

二、铁律五条

1. 先读再动：开始任何任务前，先读 CURRENT-TASK.md。
2. 接续不重做：交接单状态为「进行中」时，从记录的当前步骤继续，禁止从头重来。
3. 进展留痕：有实质进展立即回写交接单（进度 + 当前步骤 + 下一步 + 证据）。
4. 切换先交接：暂停或移交前，把交接写完整，状态改为「等待接续」。
5. 完成附证据：改「已完成」必须带验收证据（命令输出 / 截图 / 测试结果），没有证据不许说做完了。

三、任务状态机

待办(queued) → 进行中(in-progress) → 等待接续(handoff-wait) → 进行中 … → 已完成(done)
                                        ↘ 受阻(blocked)：写明具体阻塞条件，连续 3 轮未解决才允许标记

四、单写入者边界

• 同一时刻，一个文件只允许一个成员写入；其他人先读后排队。
• 改公共配置（构建脚本、部署配置、依赖清单）前必须先读当前值并声明改动，防止互相覆盖。
• 冲突处理：以交接单里最后一条带时间戳的记录为准。

五、角色分工模板（按能力分派，不是按头衔）

角色	职责	回退条件
总控	需求拆解、派发、验收、记忆与交接管理	—
调度员	任务路由、负载均衡、状态监控、超时熔断（优先用脚本/看板等确定性手段，不用 LLM 临场发挥）	调度延迟高或误派发率上升
主开发	写代码、实现、修复、部署	连续失败 2 次切备用通道
审查员	只读评审代码/视觉/安全，不给主线改文件	—
专项通道	处理棘手故障与能力缺口，不与主开发并发改同一文件	问题关闭即退出

成本优先路由：日常任务走默认主力模型/订阅 → 失败重试一次 → 再失败切备用通道 → 疑难杂症才动用专项通道。不要因为一次小报错就切换主力。

六、记忆同步

• 每个成员的长期记忆各自维护；共享事实只进 MEMORY-SNAPSHOT.md。
• 提供一个同步脚本（示例）：把各成员当日摘要追加合并进快照，保留最近 N 条。
• 教训类内容（踩坑、纠错）优先级最高，必须进快照，防止同一个坑摔两次。

七、最小闭环示例

1. 总控接到需求 → 在 CURRENT-TASK.md 写下目标、验收标准、指派主开发，状态=进行中。
2. 主开发读完交接单开工 → 完成一个批次 → 回写进度与证据。
3. 完成实现 → 总控派审查员只读评审 → 发现问题回写交接单转回主开发。
4. 全部验收通过 → 状态=已完成，证据归档，MEMORY-SNAPSHOT.md 记录关键决策。

八、协同调度防翻车指南（八大坑与工程化解法）

适用场景：多个 AI 助手并行推进时的典型翻车点。每次组建多 Agent 团队前，逐条对照检查。

#	坑	症状	工程化解法
1	上下文爆炸	共享对话越滚越长，早期任务约束和验收标准被挤出窗口	交接单只存结论与状态（≤200行）；过程性讨论留在各自本地；每批次开始由总控重发「最小必要上下文」
2	幻觉传染	一个成员输出错误信息，经共享记忆被全员当作事实扩散	共享记忆分区：写入需总控标记「已验证」才可见；未验证内容放隔离区并标注来源与置信度
3	协作死锁	A 等 B 的产出、B 等 C、C 又等 A，系统永久挂起	资源/产出申请按全局固定顺序排队；每个等待必须带超时（默认15分钟），超时自动升级总控裁决
4	状态不一致	两人手里的任务状态对不上，重复做或漏做	唯一事实源=交接单状态机；改状态即写文件；口头/会话内状态不作数
5	通信风暴	成员互相直聊，消息链路数随人数平方膨胀，延迟指数涨	星型拓扑：只允许「成员↔总控」通信，禁止成员互发；确需协作由总控转交
6	Agent 蔓延	按功能细分拆出一堆角色，边界重叠、没人负全责	减法原则：新角色上线前先回答「能否并入现有角色的完整闭环」；每个角色必须端到端负责一段可交付物
7	调度靠 LLM 临场发挥	路由派发交给大模型自由决定，同一输入两次派发结果不同	调度确定性化：看板扫描+固定规则（按标签/负载/顺序）派发；LLM 只做需要理解力的规划，不做机械分发
8	无验收聚合	各自交付后没人拼装校验，缺陷在集成时才爆	总控设独立验收门禁：对照交接单验收标准逐条核验+运行证据；不合格整批退回，不带病合并

硬性红线（违反任意一条立即停止协作流程）

• 禁止两个成员同时写同一文件（单写入者边界，见第四节）。
• 禁止跳过交接单直接开工/直接交付。
• 禁止把「我认为完成了」当完成——必须附运行证据。
• 禁止成员间私相授受任务（一切派发过总控）。