claude-code-best
diff --git a/‎docs/agent/coordinator-and-swarm.mdx‎
Lines changed: 79 additions & 24 deletions b/‎docs/agent/coordinator-and-swarm.mdx‎
Lines changed: 79 additions & 24 deletions
@@ -10,13 +10,13 @@ keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作",
 
 | 维度 | Coordinator Mode | Agent Swarms |
 |------|-----------------|--------------|
-| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | 任务系统 V2（默认启用） |
-| **拓扑** | 星型：Coordinator 居中，Worker 外围 | 网状：对等 Agent 共享任务列表 |
-| **角色** | 明确分工：Coordinator 编排、Worker 执行 | 模糊：每个 Agent 自主认领任务 |
-| **通信** | `SendMessage` 定向通信 + `<task-notification>` | 任务文件系统 + 邮箱广播 |
-| **适用** | 需要集中决策的复杂任务 | 并行度高的独立子任务 |
+| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 |
+| **拓扑** | 星型：Coordinator 居中，Worker 外围 | 星型+P2P 混合：Team Lead 协调，Teammate 间可直接通信 |
+| **角色** | 明确分工：Coordinator 编排、Worker 执行 | Team Lead 协调 + Teammate 自主认领任务 |
+| **通信** | `SendMessage` 定向通信 + `<task-notification>` | Mailbox 消息系统（message / broadcast） |
+| **适用** | 需要集中决策的复杂任务 | 并行度高、需要 Teammate 间直接协作的任务 |
 
-两者不是互斥的——Coordinator Mode 可以在 Swarm 架构之上运行，将 Coordinator 作为特殊的 Leader Agent。
+两者不是互斥的——理论上 Coordinator Mode 可以在 Agent Teams 架构之上运行（概念层叠加，非嵌套团队），将 Coordinator 作为特殊的 Team Lead，但这部分集成（`workerAgent.ts` 中的 `getCoordinatorAgents`）目前为 stub 实现，尚未完整落地。
 
 ## Coordinator Mode：星型编排架构
 
@@ -45,15 +45,15 @@ Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
 | **TaskStop** | 中途停止走错方向的 Worker |
 | **subscribe_pr_activity** | 订阅 GitHub PR 事件（review comments、CI 结果） |
 
-Coordinator **不写代码、不读文件、不执行命令**——它只做三件事：理解需求、分配任务、综合结果。
+Coordinator **不写代码、不读文件、不执行命令**——它的核心职责是：理解需求、分配任务、综合结果，以及在无需工具时直接回答用户问题。
 
 ### Worker 的工具权限
 
 Worker 的可用工具由 `getCoordinatorUserContext()`（`coordinatorMode.ts:80`）动态注入到 System Prompt：
 
 ```typescript
 // 简化模式下：只有 Bash + Read + Edit
-const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE')
+const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
   ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
   : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
       .filter(name => !INTERNAL_WORKER_TOOLS.has(name))
@@ -63,7 +63,7 @@ const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE')
 
 ### Scratchpad：跨 Worker 的共享知识库
 
-当 `tengu_scratch` feature flag 启用时，Coordinator 拥有一个 Scratchpad 目录：
+当 `isScratchpadGateEnabled()`（内部检查 `tengu_scratch` feature gate）启用时，Workers 获得一个 Scratchpad 目录，Coordinator 通过其系统上下文知晓该目录的存在：
 
 ```
 Scratchpad 目录：
@@ -113,40 +113,92 @@ Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确
 
 这是 Coordinator Mode 最核心的设计约束：Coordinator 必须先理解，再分配。
 
-## Agent Swarms：蜂群式协作
+## Agent Teams (Swarm)：蜂群式协作
 
-Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领**：
+Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领 + Mailbox 消息系统**：
 
 ### 团队初始化
 
 ```
-Leader 创建团队（TeamCreateTool）
+Team Lead 创建团队（TeamCreateTool）
   ↓
 设置 teamName → setLeaderTeamName()
   ↓
-所有 teammate 自动获得相同的 taskListId
+所有 Teammate 自动获得相同的 taskListId
   ↓
-teammate 启动时：
+Teammate 启动时：
   1. CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
-  2. teammate 上下文的 teamName（共享 leader 的任务列表）
+  2. Teammate 上下文的 teamName（共享 Lead 的任务列表）
   3. CLAUDE_CODE_TEAM_NAME 环境变量
-  4. leader 设置的 teamName
+  4. Lead 设置的 teamName
   5. getSessionId()（兜底）
 ```
 
-多级优先级确保了 Leader 和所有 Teammate 指向同一个任务列表，无需额外协调。
+多级优先级确保了 Team Lead 和所有 Teammate 指向同一个任务列表，无需额外协调。
+
+### 架构组件
+
+官方 Agent Teams 架构定义了四个核心组件：
+
+| 组件 | 角色 |
+|------|------|
+| **Team Lead** | 创建团队、分配任务、综合结果的主 Claude Code 会话 |
+| **Teammate** | 独立的 Claude Code 实例，各自拥有独立的上下文窗口 |
+| **Task List** | 共享的任务列表，Teammate 竞争认领和完成 |
+| **Mailbox** | 消息系统，支持 Teammate 间直接通信 |
+
+### Mailbox 消息系统
+
+官方架构中的 Mailbox 是 Teammate 间通信的核心原语，支持两种消息模式（`broadcast` 模式来自源码推断，官方文档未明确细分）：
+
+| 模式 | 作用 | 场景 |
+|------|------|------|
+| **message** | 定向发送给指定 Teammate | 传递具体指令、请求协作 |
+| **broadcast** | 广播给所有 Teammate | 全局通知、状态同步 |
+
+Mailbox 的关键特性：
+- **自动投递**：消息自动送达目标 Teammate 的对话上下文
+- **空闲通知**（TeammateIdle）：Teammate 完成当前任务进入空闲时，自动通过 Mailbox 通知 Team Lead
+- **直接通信**：与 Coordinator Mode 不同，Teammate 之间可以直接通信，无需经过 Lead 中转
+
+### Hook 事件
+
+Agent Teams 提供三个关键 Hook 事件，用于在团队生命周期中注入自定义逻辑：
+
+| Hook | 触发时机 | 典型用途 |
+|------|---------|---------|
+| **TaskCreated** | 新任务添加到任务列表时 | 自动分配、优先级排序 |
+| **TaskCompleted** | 任务标记为完成时 | 结果通知、依赖解锁 |
+| **TeammateIdle** | Teammate 完成所有任务进入空闲时 | Lead 重新分配、动态扩缩容 |
+
+### 限制
+
+当前 Agent Teams 实现的限制：
+- **不支持嵌套团队**：Teammate 不能再创建子团队
+- **每 session 一个团队**：一个会话只能属于一个团队
+- **Lead 固定**：Team Lead 创建后不可更换
+- **不支持 in-process Teammate 的会话恢复**：进程重启后 in-process 类型 Teammate 的状态丢失
+
+### 持久化存储
+
+团队状态通过文件系统持久化，确保进程重启后可恢复：
+
+```
+~/.claude/teams/{team-name}/config.json   ← 团队配置
+~/.claude/tasks/{team-name}/              ← 共享任务列表（文件锁保护）
+```
 
 ### 任务认领与竞争
 
-`claimTask()` 是 Swarm 的核心并发原语：
+`claimTask()` 是 Agent Teams 的核心并发原语：
 
 ```
 Teammate A 调用 TaskList → 发现 task #3 是 pending
 Teammate B 同时发现 task #3 是 pending
   ↓
 两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
   ↓
-文件锁 + 高水位标记保证原子性：
+文件锁保证原子性：
   - 第一个写入者获得 owner 锁定
   - 第二个写入者收到 already_claimed 错误
   ↓
@@ -166,8 +218,11 @@ unassignTeammateTasks()
   → 扫描任务列表，找到 owner === teammateName 的未完成任务
   → 重置为 pending + owner=undefined
   ↓
-Leader 通过 mailbox 收到通知
-  → 重新分配或创建新 Teammate
+Team Lead 感知途径：
+  1. 任务状态变化（pending 重置）—— 通过共享任务列表
+  2. Mailbox 空闲通知（TeammateIdle hook）—— Teammate 停止时自动通知 Lead
+  ↓
+Team Lead 重新分配任务或创建新 Teammate
 ```
 
 ## 任务类型全景
@@ -186,11 +241,11 @@ Leader 通过 mailbox 收到通知
 
 `InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
 
-## Coordinator vs Swarm 的选择
+## Coordinator vs Agent Teams 的选择
 
 | 场景 | 推荐模式 | 原因 |
 |------|---------|------|
 | "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
-| "修复 10 个独立的 lint 警告" | Swarm | 任务独立，可完全并行 |
+| "修复 10 个独立的 lint 警告" | Agent Teams | 任务独立，Teammate 可完全并行 |
 | "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
-| "在大仓库中搜索所有 TODO 并分类" | Swarm | 无依赖，各自领任务即可 |
+| "在大仓库中搜索所有 TODO 并分类" | Agent Teams | 无依赖，各自领任务即可 |