vault backup: 2026-06-09 23:15:17

claude-code-best/docs/agent/coordinator-and-swarm.md

@@ -1,12 +1,21 @@
 ---
-title: "协调者与蜂群模式 - 多 Agent 高级编排"
-description: "从源码角度解析 Claude Code 多 Agent 协作：Coordinator Mode 的 System Prompt 设计、Worker 生命周期、Task 通信协议和 Swarm 蜂群的任务分配机制。"
-keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作", "任务编排"]
+tags:
+  - 多Agent
+  - 协调者模式
+  - 蜂群模式
+  - 任务编排
+create time: 2026-06-09 22:30
 ---
 
-{/* 本章目标：从源码角度揭示 Coordinator Mode 和 Agent Swarms 的架构设计 */}
+# 协调者与蜂群模式 - 多 Agent 高级编排
 
-## 两种协作模式的架构差异
+## 概述
+
+从源码角度解析 Claude Code 多 Agent 协作：Coordinator Mode 的 System Prompt 设计、Worker 生命周期、Task 通信协议和 Swarm 蜂群的任务分配机制。
+
+## 正文
+
+### 两种协作模式的架构差异
 
 | 维度 | Coordinator Mode | Agent Swarms |
 |------|-----------------|--------------|
@@ -16,11 +25,12 @@ keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作",
 | **通信** | `SendMessage` 定向通信 + `<task-notification>` | Mailbox 消息系统（message / broadcast） |
 | **适用** | 需要集中决策的复杂任务 | 并行度高、需要 Teammate 间直接协作的任务 |
 
-两者不是互斥的——理论上 Coordinator Mode 可以在 Agent Teams 架构之上运行（概念层叠加，非嵌套团队），将 Coordinator 作为特殊的 Team Lead，但这部分集成（`workerAgent.ts` 中的 `getCoordinatorAgents`）目前为 stub 实现，尚未完整落地。
+> [!info]
+> 两者不是互斥的——理论上 Coordinator Mode 可以在 Agent Teams 架构之上运行（概念层叠加，非嵌套团队），将 Coordinator 作为特殊的 Team Lead，但这部分集成（`workerAgent.ts` 中的 `getCoordinatorAgents`）目前为 stub 实现，尚未完整落地。
 
-## Coordinator Mode：星型编排架构
+### Coordinator Mode：星型编排架构
 
-### 激活机制
+#### 激活机制
 
 ```typescript
 // src/coordinator/coordinatorMode.ts:36
@@ -34,7 +44,7 @@ export function isCoordinatorMode(): boolean {
 
 Coordinator Mode 需要双重门控：构建时 `feature('COORDINATOR_MODE')` 和运行时环境变量。`matchSessionMode()` 在会话恢复时自动同步模式状态——如果恢复的会话是 coordinator 模式，它会翻转环境变量以确保一致性。
 
-### Coordinator 的工具集
+#### Coordinator 的工具集
 
 Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
 
@@ -45,9 +55,10 @@ Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
 | **TaskStop** | 中途停止走错方向的 Worker |
 | **subscribe_pr_activity** | 订阅 GitHub PR 事件（review comments、CI 结果） |
 
-Coordinator **不写代码、不读文件、不执行命令**——它的核心职责是：理解需求、分配任务、综合结果，以及在无需工具时直接回答用户问题。
+> [!tip]
+> Coordinator **不写代码、不读文件、不执行命令**——它的核心职责是：理解需求、分配任务、综合结果，以及在无需工具时直接回答用户问题。
 
-### Worker 的工具权限
+#### Worker 的工具权限
 
 Worker 的可用工具由 `getCoordinatorUserContext()`（`coordinatorMode.ts:80`）动态注入到 System Prompt：
 
@@ -61,26 +72,24 @@ const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
 
 `INTERNAL_WORKER_TOOLS`（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）被显式排除——Worker 不能嵌套创建团队或发送消息，防止不可控的递归。
 
-### Scratchpad：跨 Worker 的共享知识库
+#### Scratchpad：跨 Worker 的共享知识库
 
 当 `isScratchpadGateEnabled()`（内部检查 `tengu_scratch` feature gate）启用时，Workers 获得一个 Scratchpad 目录，Coordinator 通过其系统上下文知晓该目录的存在：
 
-```
-Scratchpad 目录：
-  - Workers 可自由读写，无需权限审批
-  - 用于持久化的跨 Worker 知识
-  - 结构由 Coordinator 决定（无固定格式）
-```
+- Workers 可自由读写，无需权限审批
+- 用于持久化的跨 Worker 知识
+- 结构由 Coordinator 决定（无固定格式）
 
-这是一个关键的协作原语——Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
+> [!tip]
+> 这是一个关键的协作原语——Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
 
-### `<task-notification>` 通信协议
+#### \<task-notification\> 通信协议
 
 Worker 完成后，Coordinator 收到 XML 格式的通知：
 
 ```xml
 <task-notification>
-  <task-id>agent-a1b</task-id>          ← Worker 的 agentId
+  <task-id>agent-a1b</task-id>
   <status>completed|failed|killed</status>
   <summary>Agent "Investigate auth bug" completed</summary>
   <result>Found null pointer in src/auth/validate.ts:42...</result>
@@ -94,11 +103,11 @@ Worker 完成后，Coordinator 收到 XML 格式的通知：
 
 通知以 `user-role message` 形式送达，Coordinator 通过 `<task-notification>` 标签区分它和用户消息。`<task-id>` 用于 `SendMessage` 的 `to` 参数，实现定向续传。
 
-### Coordinator 的核心职责：综合（Synthesis）
+#### Coordinator 的核心职责：综合（Synthesis）
 
 Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确要求 Coordinator **不能懒惰地委派理解**：
 
-```
+```text
 反模式（禁止）：
   "Based on your findings, fix the auth bug"
   → 把理解的责任推给了 Worker
@@ -111,34 +120,31 @@ Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确
   → Coordinator 自己理解了问题，给出精确指令
 ```
 
-这是 Coordinator Mode 最核心的设计约束：Coordinator 必须先理解，再分配。
+> [!question] 为什么 Coordinator 必须先理解再分配？
+> 这是 Coordinator Mode 最核心的设计约束。如果 Coordinator 把理解的责任推给 Worker，它就失去了编排的价值——Worker 拿到模糊指令，可能走错方向，浪费 token 和时间。
 
-## Agent Teams (Swarm)：蜂群式协作
+### Agent Teams (Swarm)：蜂群式协作
 
-Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领 + Mailbox 消息系统**：
+Swarm 模式基于任务系统 V2，核心机制是**共享任务列表 + 竞争认领 + Mailbox 消息系统**。
 
-### 团队初始化
+#### 团队初始化
 
-```
-Team Lead 创建团队（TeamCreateTool）
-  ↓
-设置 teamName → setLeaderTeamName()
-  ↓
-所有 Teammate 自动获得相同的 taskListId
-  ↓
-Teammate 启动时：
-  1. CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
-  2. Teammate 上下文的 teamName（共享 Lead 的任务列表）
-  3. CLAUDE_CODE_TEAM_NAME 环境变量
-  4. Lead 设置的 teamName
-  5. getSessionId()（兜底）
+```mermaid
+graph TD
+    A["Team Lead 创建团队 TeamCreateTool"] --> B["设置 teamName"]
+    B --> C["setLeaderTeamName()"]
+    C --> D["所有 Teammate 自动获得相同的 taskListId"]
+    D --> E["Teammate 启动时按优先级获取 taskListId"]
+    E --> F["1. CLAUDE_CODE_TASK_LIST_ID 环境变量"]
+    E --> G["2. Teammate 上下文的 teamName"]
+    E --> H["3. CLAUDE_CODE_TEAM_NAME 环境变量"]
+    E --> I["4. Lead 设置的 teamName"]
+    E --> J["5. getSessionId() 兜底"]
 ```
 
 多级优先级确保了 Team Lead 和所有 Teammate 指向同一个任务列表，无需额外协调。
 
-### 架构组件
-
-官方 Agent Teams 架构定义了四个核心组件：
+#### 架构组件
 
 | 组件 | 角色 |
 |------|------|
@@ -147,9 +153,9 @@ Teammate 启动时：
 | **Task List** | 共享的任务列表，Teammate 竞争认领和完成 |
 | **Mailbox** | 消息系统，支持 Teammate 间直接通信 |
 
-### Mailbox 消息系统
+#### Mailbox 消息系统
 
-官方架构中的 Mailbox 是 Teammate 间通信的核心原语，支持两种消息模式（`broadcast` 模式来自源码推断，官方文档未明确细分）：
+Mailbox 是 Teammate 间通信的核心原语，支持两种消息模式（`broadcast` 模式来自源码推断，官方文档未明确细分）：
 
 | 模式 | 作用 | 场景 |
 |------|------|------|
@@ -161,7 +167,7 @@ Mailbox 的关键特性：
 - **空闲通知**（TeammateIdle）：Teammate 完成当前任务进入空闲时，自动通过 Mailbox 通知 Team Lead
 - **直接通信**：与 Coordinator Mode 不同，Teammate 之间可以直接通信，无需经过 Lead 中转
 
-### Hook 事件
+#### Hook 事件
 
 Agent Teams 提供三个关键 Hook 事件，用于在团队生命周期中注入自定义逻辑：
 
@@ -171,61 +177,57 @@ Agent Teams 提供三个关键 Hook 事件，用于在团队生命周期中注
 | **TaskCompleted** | 任务标记为完成时 | 结果通知、依赖解锁 |
 | **TeammateIdle** | Teammate 完成所有任务进入空闲时 | Lead 重新分配、动态扩缩容 |
 
-### 限制
+#### 限制
 
-当前 Agent Teams 实现的限制：
-- **不支持嵌套团队**：Teammate 不能再创建子团队
-- **每 session 一个团队**：一个会话只能属于一个团队
-- **Lead 固定**：Team Lead 创建后不可更换
-- **不支持 in-process Teammate 的会话恢复**：进程重启后 in-process 类型 Teammate 的状态丢失
+> [!warning]
+> 当前 Agent Teams 实现存在以下限制：
+> - **不支持嵌套团队**：Teammate 不能再创建子团队
+> - **每 session 一个团队**：一个会话只能属于一个团队
+> - **Lead 固定**：Team Lead 创建后不可更换
+> - **不支持 in-process Teammate 的会话恢复**：进程重启后 in-process 类型 Teammate 的状态丢失
 
-### 持久化存储
+#### 持久化存储
 
 团队状态通过文件系统持久化，确保进程重启后可恢复：
 
-```
+```text
 ~/.claude/teams/{team-name}/config.json   ← 团队配置
 ~/.claude/tasks/{team-name}/              ← 共享任务列表（文件锁保护）
 ```
 
-### 任务认领与竞争
+#### 任务认领与竞争
 
 `claimTask()` 是 Agent Teams 的核心并发原语：
 
-```
-Teammate A 调用 TaskList → 发现 task #3 是 pending
-Teammate B 同时发现 task #3 是 pending
-  ↓
-两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
-  ↓
-文件锁保证原子性：
-  - 第一个写入者获得 owner 锁定
-  - 第二个写入者收到 already_claimed 错误
-  ↓
-获得任务的 teammate 执行工作
-  ↓
-完成后 TaskUpdate(task #3, {status: "completed"})
-  → 依赖此任务的其他任务自动解锁
-  → tool_result 提示 "Call TaskList to find your next task"
+```mermaid
+graph TD
+    A["Teammate A 调用 TaskList"] --> C["发现 task #3 是 pending"]
+    B["Teammate B 同时发现 task #3 是 pending"] --> C
+    C --> D["两者同时尝试 TaskUpdate"]
+    D --> E["文件锁保证原子性"]
+    E --> F["第一个写入者获得 owner 锁定"]
+    E --> G["第二个写入者收到 already_claimed 错误"]
+    F --> H["获得任务的 teammate 执行工作"]
+    H --> I["完成后 TaskUpdate task #3 completed"]
+    I --> J["依赖此任务的其他任务自动解锁"]
+    I --> K["tool_result 提示 Call TaskList to find your next task"]
 ```
 
-### Teammate 的生命周期管理
+#### Teammate 的生命周期管理
 
-```
-Teammate 异常退出
-  ↓
-unassignTeammateTasks()
-  → 扫描任务列表，找到 owner === teammateName 的未完成任务
-  → 重置为 pending + owner=undefined
-  ↓
-Team Lead 感知途径：
-  1. 任务状态变化（pending 重置）—— 通过共享任务列表
-  2. Mailbox 空闲通知（TeammateIdle hook）—— Teammate 停止时自动通知 Lead
-  ↓
-Team Lead 重新分配任务或创建新 Teammate
+```mermaid
+graph TD
+    A["Teammate 异常退出"] --> B["unassignTeammateTasks()"]
+    B --> C["扫描任务列表找到 owner === teammateName 的未完成任务"]
+    C --> D["重置为 pending + owner=undefined"]
+    D --> E["Team Lead 感知途径"]
+    E --> F["1. 任务状态变化通过共享任务列表"]
+    E --> G["2. Mailbox 空闲通知 TeammateIdle hook"]
+    F --> H["Team Lead 重新分配任务或创建新 Teammate"]
+    G --> H
 ```
 
-## 任务类型全景
+### 任务类型全景
 
 支撑多 Agent 协作的是 7 种任务类型（`src/tasks/types.ts`）：
 
@@ -239,9 +241,10 @@ Team Lead 重新分配任务或创建新 Teammate
 | **LocalWorkflowTask** | 本地 | `LocalWorkflowTaskState` | 工作流编排 |
 | **MonitorMcpTask** | 本地 | `MonitorMcpTaskState` | MCP 监控任务 |
 
-`InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
+> [!tip]
+> `InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
 
-## Coordinator vs Agent Teams 的选择
+### Coordinator vs Agent Teams 的选择
 
 | 场景 | 推荐模式 | 原因 |
 |------|---------|------|
@@ -249,3 +252,8 @@ Team Lead 重新分配任务或创建新 Teammate
 | "修复 10 个独立的 lint 警告" | Agent Teams | 任务独立，Teammate 可完全并行 |
 | "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
 | "在大仓库中搜索所有 TODO 并分类" | Agent Teams | 无依赖，各自领任务即可 |
+
+## 关联笔记
+
+- [[sub-agents]]
+- [[worktree-isolation]]