Appearance
09 — Agent / Swarm / Task
概述
Claude Code 支持三个层次的并行/协作能力：
- Agent (子代理) — 主会话可以分叉出独立的子代理，每个子代理有自己的对话循环和受限工具集
- Task (后台任务) — 长时间运行的工作单元，可以在后台执行
- Swarm (Teammate) — 多个 Claude Code 实例协作，分布在不同终端窗口/Tmux Pane 中
它们的关系是：Agent 是 同进程 的轻量级并行；Task 是 Agent 的 状态管理封装；Swarm 是 跨进程 的重量级协作。
Agent 系统 (tools/AgentTool/)
核心概念
Agent（子代理）是一个独立的 query() 循环，运行在与主会话相同的进程中。它有：
- 自己的 System Prompt（来自 Agent 定义）
- 受限的 工具集（如 Explore Agent 只有只读工具）
- 隔离的 ToolUseContext（
setAppState是 no-op，见 03-State） - 自己的 agentId 和颜色（UI 中通过颜色区分不同 Agent）
Agent 启动流程
内置 Agent 类型
每个内置 Agent 定义了自己可用的工具集，这是安全隔离的关键：
| Agent | 工具集 | 不可用的工具 | 设计意图 |
|---|---|---|---|
general-purpose | 全部 | — | 最强能力，用于复杂任务 |
Explore | Glob, Grep, Read, Bash(只读), WebFetch, WebSearch | Edit, Write, Agent | 纯探索，不修改代码 |
Plan | 同 Explore | Edit, Write, Agent | 纯规划，不执行 |
claude-code-guide | Glob, Grep, Read, WebFetch, WebSearch | Bash, Edit, Write, Agent | 查文档，不执行代码 |
verification | 配置文件定义 | — | 自定义验证流程 |
自定义 Agent
用户可以在 ~/.claude/agents/ 或 .claude/agents/ 目录下放置 Markdown 文件来定义自定义 Agent：
markdown
name: my-reviewer
description: Code review specialist
model: sonnet
allowedTools: ["Read", "Glob", "Grep", "Bash"]
You are a code review specialist. Focus on...loadAgentsDir.ts 会从这些目录加载定义，合并到 AgentDefinitionsResult 中。
Agent 恢复 (resumeAgent.ts)
SendMessageTool 可以向已存在的子代理发送新消息。通过 agentNameRegistry 找到 Agent，恢复其上下文继续对话。这允许主会话与子代理之间进行多轮交互。
Task 系统 (src/tasks/)
Task 是 Agent 的运行时封装——它给 Agent 加上了生命周期管理、状态追踪和 UI 展示。
Task 类型
| Task 类型 | 文件 | 运行位置 | 说明 |
|---|---|---|---|
LocalAgentTask | tasks/LocalAgentTask/ | 同进程 | 本地 Agent 包装为 Task |
RemoteAgentTask | tasks/RemoteAgentTask/ | 远程 | 远程服务器上的 Agent |
LocalShellTask | tasks/LocalShellTask/ | 同进程 | Shell 命令任务 |
InProcessTeammateTask | tasks/InProcessTeammateTask/ | 同进程 | 进程内 Teammate |
DreamTask | tasks/DreamTask/ | 同进程 | Dream (后台知识整理) |
LocalMainSessionTask | tasks/LocalMainSessionTask.ts | 同进程 | 主会话的 Task 表示 |
Task 生命周期
Task 工具
模型通过 Task 相关的 Tool 管理任务：
| 工具 | 说明 | 与 Task 生命周期的关系 |
|---|---|---|
TaskCreateTool | 创建任务 | Queued → Running |
TaskGetTool | 查询状态 | 读取 TaskState |
TaskUpdateTool | 更新进度/描述 | 修改 TaskState |
TaskListTool | 列出所有任务 | 读取 tasks Map |
TaskStopTool | 停止任务 | Running → Stopped |
TaskOutputTool | 获取输出 | 读取 Task 输出流 |
Task 状态存储在 AppState.tasks 中（这是 AppState 中少数 可变 的字段，不受 DeepImmutable 约束）。
Swarm / Teammate 系统 (utils/swarm/)
Swarm 是最重量级的协作模式。它允许启动多个 Claude Code 进程，分布在不同的终端窗口中，由一个 Leader 协调。
架构
后端选择
Leader 根据终端环境自动选择最佳后端：
| 后端 | 条件 | UI 表现 |
|---|---|---|
TmuxBackend | 在 Tmux 会话中 | 新的 Tmux Pane |
ITermBackend | 在 iTerm2 中 | 新的 iTerm2 Tab/Split |
InProcessBackend | 其他（或 Feature Flag） | 无独立窗口，进程内运行 |
detection.ts 负责检测当前终端环境，registry.ts 管理后端注册。
权限同步
Swarm Worker 没有自己的终端 UI 来显示权限弹窗。权限请求通过 Mailbox 机制转发给 Leader：
这种基于文件系统的 Mailbox 机制确保了跨进程通信的可靠性，即使 Worker 和 Leader 在不同的 Tmux 窗格中。
关键文件
| 文件 | 说明 |
|---|---|
teammateInit.ts | Teammate 初始化流程 |
teammateModel.ts | Teammate 模型选择（可能使用更快的模型） |
teammatePromptAddendum.ts | 注入 Teammate 角色描述到 System Prompt |
teammateLayoutManager.ts | 管理 Tmux/iTerm 窗格布局 |
spawnUtils.ts / spawnInProcess.ts | 启动 Worker 进程 |
inProcessRunner.ts | 进程内 Worker 运行器 |
permissionSync.ts | 权限同步（Leader ↔ Worker） |
leaderPermissionBridge.ts | Leader 端权限桥 |
reconnection.ts | Worker 断线重连 |
teamHelpers.ts | 团队状态辅助函数 |
constants.ts | Swarm 常量 |
三者关系总结
- Agent: 需要隔离上下文的快速子任务（如探索代码库、规划方案）
- Task: 需要跟踪状态的长时间 Agent（如后台运行测试、构建）
- Swarm: 需要真正的多进程并行（如同时修改多个文件、并行开发多个功能）