multiagent-topology

name	multiagent-topology
description	当你要设计多 Agent 的上下文共享方式（共享/隔离）和协作拓扑（对等/管理者/去中心化）时使用；当需要决定"如何分工、如何通信、谁控制谁"时使用。不适用于失败模式与容错（见 multiagent-failures）。

协作拓扑（Collaboration Topology）

角色与读者

面向需要组织多个 Agent 的开发者。本 Skill 服务的目标：按任务性质选择合适的上下文共享方式和协作拓扑。核心认识：好的协作不是暴露彼此的思考过程，而是约定清晰的接口、边界、权限、验收标准。

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

1. 维度一：上下文是否共享

   • 共享上下文（继承式）：后续 Agent 继承完整轨迹，信息不丢但上下文膨胀、角色惯性。
   • 不共享上下文（隔离式）：独立上下文，模块化隔离好、易扩展并发，但信息同步复杂、调试困难。
   • 通信三机制（对应 IPC 两范式）：工具调用参数（消息传递同步）、共享文件系统（共享内存）、消息总线（消息传递异步）。

2. 维度二：协作拓扑三形态

   • 对等协作（Peer）：2-3 个平等 Agent 迭代改进，实现复杂度最低，只需定义角色/通信/迭代终止条件。
   • 管理者模式（Orchestration）：中心化 Manager 规划调度，每个专门 Agent 建模为 Manager 可调用的工具，统一抽象、天然异构。单点瓶颈。
   • 去中心化（Decentralized）：无中心控制者，Agent 自主决定与谁沟通（移交/请求反馈/报告问题）。

3. 角色转换：替换 system prompt vs 加载 Skill

   • transfer_to_agent：替换 prompt+工具集，强约束（越界工具 schema 层不可见），但每次切换破坏缓存。
   • Skill：固定 prompt 的 Skill 目录按需追加，弱约束（硬权限仍需 Harness），但静态前缀不变缓存可复用。
   • 选择：角色差异来自知识/流程/风格 → Skill；涉及权限/工具隔离/合规边界 → 独立 Agent 或 transfer_to_agent + Harness 代码限制。

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

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

5. 虚拟文件系统四类区域（地址空间）

   • Agent 专属工作区（scratchpad 私有）/ 多 Agent 共享空间（shared workspace，需并发控制）/ 外部挂载资源（只读为主）/ 系统内置资源（Skills 只读）。
   • 明确每区域可见性与生命周期，是避免并发冲突与信息泄露的前提。

执行流程（SOP 检查清单）

1. 先问：多 Agent 是否引入新信息？（否则单 Agent + 外部反馈环路）
2. 选上下文共享方式（共享/隔离）。
3. 选拓扑（对等/管理者/去中心化）。
4. 定义移交包格式（任务描述+事实约束+产物引用）+ 通信机制。
5. 设计文件系统四类区域 + 生命周期原语（spawn/send/cancel/list）。

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

• 禁止为用而用多 Agent（无信息增量的辩论在等计算量下不优于单 Agent）。例外：引入外部反馈环路才有价值。
• 禁止 Manager 平均分配资源。例外：最强模型 + 最精心提示词给规划者。
• 禁止暴露彼此思考过程（传结构化移交包而非完整轨迹）。例外：共享上下文的继承式协作保留完整轨迹。
• 禁止去中心化 handoff 成环（A→B→A 空转）。例外：visited_agents 检测 + 预算上限。
• 禁止共享文件无并发控制。例外：乐观锁防单文件冲突，worktree 防跨文件语义冲突。

参考资料

• 本书第 10.1-10.4 节（分类框架、何时优于单 Agent、共享/不共享上下文、对等/管理者/去中心化、A2A）。
• 笔记 10-多Agent协作.md 第 10.1-10.4 节。
• MetaGPT / AutoGen / OpenAI Swarm；Plan-and-Act 论文。