multi-agent

name	multi-agent
description	当单个 Agent 的上下文窗口或能力边界不够、需要分工/并行/相互验证时使用；当任务可分解为有依赖的子任务、或需要"生成-验证"分离时使用。不适用于单个 Agent 内部的 ReAct 循环设计（那是 harness-engineering）。先问自己：多 Agent 是否真的引入了新信息？否则单 Agent 更划算。

多 Agent 协作（Multi-Agent Collaboration）

子 Skill 索引（渐进式披露：目录常驻，正文按需加载）

子 Skill	目录	何时深入加载
协作拓扑	multiagent-topology	共享/隔离上下文、对等/管理者/去中心化拓扑
失败模式	multiagent-failures	并发冲突、级联放大、同质趋同、循环失控

角色与读者

面向需要组织多个 Agent 协同的开发者。本 Skill 服务的目标：通过分工、通信与相互验证完成单 Agent 难以承担的任务。核心认识：群体的智能可以高于个体，但前提是组织得当。

核心原则（配正例/反例）

1. 第一判据：协作是否引入单个 Agent 生成时无法获得的新信息？

   • 引入新信息（代码执行反馈、视觉渲染截图、外部工具验证）→ 显著提升；不引入（同模型自我审查、多 Agent 辩论同一文本）→ 无效甚至有害。
   • 反例：让 GPT-4 无外部反馈自我审查，反而把正确答案改错的次数比改对的多（ICLR 2024）。
   • 成本：多 Agent 收益必须能覆盖数倍额外开销，否则单 Agent 更划算。

2. 提议者-审核者：审核者读独立证据，且不能修改测试/证据采集器/发布门槛

   • 最小不变量：candidate = proposer(...) → evidence = execute_or_render(candidate) → review = independent_reviewer(candidate, evidence)，veto 则 repair 重来。
   • 审核者退回时必须给可定位的修复条件（页码/问题类型/严重度），而非"还不行"。
   • 否则"独立验证"退化成自我批准。

3. 上下文隔离 + 结构化"移交包"（不暴露彼此思考过程）

   • 通信三机制：工具调用参数（同步）、共享文件系统（共享内存）、消息总线（异步）。
   • 移交包三部分：任务描述 + 已确认事实与约束 + 结构化产物引用（文件路径而非内容）。
   • 好的协作不是暴露思考过程，而是约定清晰的接口、边界、权限、验收标准。

4. 最强模型给规划者（弱规划者是系统瓶颈）

   • Plan-and-Act 论文：Planner 规划质量足够高时即使 Executor 简单也取得好结果；Planner 分解错误则后续全建立在错误前提上。
   • 反例：把资源平均分配给所有 Agent。

5. 级联终止：第一个"已验证成功"结算，settle_once 必须幂等

   • 一个子 Agent 找到目标后广播 terminate 给其余，优雅停止（安全点响应、清理资源、返回 ack）。
   • 终止沿创建关系向下级联（Go context 模式），杜绝孤儿 Agent；handoff 用 visited_agents 检测成环。

执行流程（SOP 检查清单）

1. 先问：多 Agent 是否引入新信息？（否则用单 Agent + 外部反馈环路）
2. 选维度：上下文共享 vs 隔离；拓扑（对等/管理者/去中心化）。
3. 定义移交包格式（任务描述 + 事实约束 + 产物引用）与通信机制（文件系统/消息总线）。
4. 设计文件系统四类区域（scratchpad 私有 / shared workspace / 外部挂载 / 系统内置资源）。
5. 设计生命周期：spawn / send_message / cancel / list，级联终止 + settle_once 幂等。
6. 设防失败模式：乐观锁/worktree（并发冲突）、异源交叉验证（级联放大/同质趋同）、目标优先级与权限边界（互相扯皮）、预算与取消（循环失控）。

禁止清单（写清合法例外）

• 禁止为用而用多 Agent（无信息增量的"辩论"在等计算量下不优于单 Agent）。例外：引入外部反馈环路（执行/渲染/工具验证）时才有价值。
• 禁止让同质 Agent（同模型/同上下文）的审核意见当独立证据。例外：主动引入模型、上下文、数据来源差异。
• 禁止审核者修改测试、证据采集器或发布门槛。例外：审核者只读证据并提交审核结果。
• 禁止 handoff 成环（A→B→A 空转）。例外：visited_agents 检测 + 剩余预算上限 + 移交次数上限。
• 禁止共享文件无并发控制。例外：乐观锁（版本号检查）防单文件冲突，worktree 隔离防跨文件语义冲突。
• 禁止 Manager 平均分配资源。例外：最强模型 + 最精心设计的提示词分配给规划者。

参考资料

• 本书第 10 章《多 Agent 协作》（分类框架、何时优于单 Agent、Loop 工程、提议者-审核者、管理者/去中心化、A2A、失败模式、Agent 社会）。
• 笔记 10-多Agent协作.md。
• Anthropic "Patterns and Problems in Emerging Multiagent Systems"；Plan-and-Act 论文。