Skip to content

docs: 审校 Agent 文档术语与架构描述准确性(docs/agent) #231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
claude-code-best merged 1 commit into from
Apr 10, 2026
Merged

docs: 审校 Agent 文档术语与架构描述准确性(docs/agent) #231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 79 additions & 24 deletions docs/agent/coordinator-and-swarm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` 环境变量 |

@coderabbitai coderabbitai Bot Apr 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

补充完整门控条件，避免把启用方式写窄。

当前只写环境变量会让读者误以为这是唯一入口。建议把 CLI 开关与禁用条件一起写上，避免和 src/utils/agentSwarmsEnabled.ts 的实际判定范围脱节。

✏️ 建议文案修正 
-| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 |
+| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 或 `--agent-teams`；且受 RAW/legacy SDK 模式约束 |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 |
| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 或 `--agent-teams`；且受 RAW/legacy SDK 模式约束 |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/agent/coordinator-and-swarm.mdx` at line 13, Update the gate description
to list the full set of enablement checks used by
src/utils/agentSwarmsEnabled.ts: include the feature flag
feature('COORDINATOR_MODE'), the CLI switch (the command-line/feature toggle
that can enable coordinator mode), the environment variables
CLAUDE_CODE_COORDINATOR_MODE and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, and the
explicit disable/negation conditions checked by that utility; rephrase the line
so it does not imply env vars are the only entrypoint but instead summarizes all
positive and negative checks performed by agentSwarmsEnabled.ts.

| **拓扑** | 星型：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：星型编排架构

Expand Down Expand Up @@ -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))
Expand All @@ -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 目录：
Expand Down Expand Up @@ -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 错误
↓
Expand All @@ -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
```

## 任务类型全景
Expand All @@ -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 | 无依赖，各自领任务即可 |
Loading
Loading