cc-haha/docs/agent/01-usage-guide.md

Claude Code 多 Agent 系统 — 使用指南

让 Claude Code 同时调度多个专业代理，并行处理复杂任务。

多 Agent 系统 · 六种内置 Agent · 如何生成 Agent · 后台任务管理 · Agent Teams · 自定义 Agent · 权限模式 · 快速参考

---

一、什么是多 Agent 系统？

Claude Code 的多 Agent 系统是一套智能任务编排框架，让主代理能够生成多个专业化的子代理（Subagent），各自独立执行不同的任务，最终将结果汇总给用户。

核心理念：把大任务拆分为多个专业小任务，并行执行，提高效率。

场景	传统方式	多 Agent 方式
调研 5 个模块的架构	逐个串行探索	5 个 Explore agent 并行扫描
实现 + 测试 + 文档	顺序完成	Team 成员各自负责一块
代码审查	单线程逐文件看	多个 reviewer 并行审查
调试复杂 bug	一个假设一个假设试	多个 debugger 并行验证

---

二、六种内置 Agent

Claude Code 内置了 6 种专业代理，每种都有特定的工具池和适用场景：

1. general-purpose（通用代理）

适用场景：复杂的多步骤研究、代码搜索、需要完整工具访问的任务。

Agent({
  description: "调研认证模块",
  prompt: "分析 src/auth/ 下所有文件的认证流程...",
  subagent_type: "general-purpose"
})

• 工具池：全部工具（*）
• 模型：继承父代理
• 特点：万能型，不确定用哪个 agent 时选它

2. Explore（探索代理）

适用场景：快速搜索文件、搜索代码模式、回答代码库结构问题。

Agent({
  description: "搜索 API 端点",
  prompt: "找到所有 REST API 端点的定义...",
  subagent_type: "Explore"
})

• 工具池：只读工具（Glob、Grep、Read、Bash）
• 模型：Haiku（快速低成本）
• 特点：不能修改文件，速度快，适合调研

3. Plan（规划代理）

适用场景：设计实现方案、分析架构权衡、生成分步计划。

Agent({
  description: "规划重构方案",
  prompt: "设计将 monolith 拆分为微服务的方案...",
  subagent_type: "Plan"
})

• 工具池：只读工具（同 Explore）
• 模型：继承父代理（需要强推理能力）
• 特点：输出结构化计划，包含关键文件和依赖分析

4. verification（验证代理）

适用场景：独立验证实现是否正确，运行测试，边界检查。

Agent({
  description: "验证登录功能",
  prompt: "验证新实现的登录功能是否正确...",
  subagent_type: "verification"
})

• 工具池：只读工具
• 模型：继承父代理
• 特点：始终在后台运行，输出 PASS/FAIL/PARTIAL 判定，红色标识

5. claude-code-guide（指南代理）

适用场景：回答关于 Claude Code、Agent SDK、Claude API 的问题。

Agent({
  description: "查询 Claude API 用法",
  prompt: "如何使用 tool_use 功能...",
  subagent_type: "claude-code-guide"
})

• 工具池：Bash、Read、WebFetch、WebSearch
• 模型：Haiku
• 特点：专注文档查询，dontAsk 权限模式

6. statusline-setup（状态栏配置代理）

适用场景：配置 Claude Code 状态栏显示。

• 工具池：仅 Read + Edit
• 模型：Sonnet
• 特点：高度专业化，范围极小

Agent 类型对比表

Agent	读写	工具池	模型	用途
general-purpose	读写	全部	继承	通用任务
Explore	只读	搜索+读取	Haiku	快速探索
Plan	只读	搜索+读取	继承	架构规划
verification	只读	搜索+读取	继承	独立验证
claude-code-guide	只读	搜索+网络	Haiku	文档指南
statusline-setup	读写	Read+Edit	Sonnet	状态栏配置

---

三、如何生成 Agent

基本参数

Agent 工具接受以下参数：

参数	类型	必需	说明
description	string	是	3-5 词任务简述
prompt	string	是	完整的任务描述
subagent_type	string	否	Agent 类型（见上表）
model	string	否	模型覆盖：sonnet/opus/haiku
run_in_background	boolean	否	是否后台运行
name	string	否	命名后可通过 SendMessage 寻址
team_name	string	否	加入指定团队
mode	string	否	权限模式
isolation	string	否	隔离模式：worktree

前台同步执行（默认）

最简单的用法，Agent 执行完毕后返回结果：

Agent({
  description: "分析错误日志",
  prompt: "读取 logs/ 下最近的错误日志，总结常见错误模式"
})

主代理会等待子代理完成，然后收到结果继续工作。

后台异步执行

适合耗时任务，主代理可以继续做其他事情：

Agent({
  description: "全面代码审查",
  prompt: "审查 src/ 下所有 TypeScript 文件的代码质量...",
  run_in_background: true
})

• Agent 立即返回 async_launched 状态和 taskId
• 主代理继续工作，不需要等待
• Agent 完成后自动收到 <task-notification> 通知
• 通知包含任务状态、输出文件路径和结果摘要

并行生成多个 Agent

在一条消息中生成多个独立的 Agent，实现真正的并行：

// 同时启动 3 个探索 agent
Agent({ description: "探索前端", prompt: "...", subagent_type: "Explore", run_in_background: true })
Agent({ description: "探索后端", prompt: "...", subagent_type: "Explore", run_in_background: true })
Agent({ description: "探索数据库", prompt: "...", subagent_type: "Explore", run_in_background: true })

Worktree 隔离

让 Agent 在独立的 git worktree 中工作，不影响主工作区：

Agent({
  description: "实验性重构",
  prompt: "尝试将模块 X 重构为...",
  isolation: "worktree"
})

• 自动创建 git worktree（独立分支）
• Agent 在隔离环境中自由修改文件
• 完成后如有改动，返回 worktree 路径和分支名
• 无改动则自动清理

---

四、后台任务管理

任务状态

后台 Agent 有四种状态：

状态	说明
running	正在执行中
completed	执行成功
failed	执行失败
killed	被手动终止

进度追踪

后台 Agent 的进度实时更新：

• Token 消耗：输入/输出 token 计数
• 工具使用：已使用的工具次数
• 最近活动：最近 5 个工具调用描述（循环缓冲区）
• 最后活动时间：用于检测卡住的任务

完成通知

当后台 Agent 完成时，主代理收到 XML 格式的通知：

<task-notification>
  <task-id>abc123</task-id>
  <status>completed</status>
  <summary>Agent "探索前端" completed</summary>
  <output-file>~/.claude/temp/.../tasks/abc123.output</output-file>
</task-notification>

自动后台化

当 tengu_auto_background_agents 特性开启时，前台 Agent 运行超过 120 秒会自动转为后台执行，释放主代理继续工作。

---

五、Agent Teams — 多代理协作

Agent Teams 是更高级的多代理协作模式，多个代理以团队形式工作，通过消息通信协调任务。

创建团队

TeamCreate({
  team_name: "feature-team",
  description: "开发用户认证功能"
})

团队创建后：

• 生成团队配置文件：~/.claude/teams/{team_name}/config.json
• 创建共享任务目录：~/.claude/tasks/{team_name}/
• 当前代理自动成为 Team Lead（团队负责人）

添加团队成员

通过 Agent 工具指定 name 和 team_name 生成队友：

Agent({
  description: "前端开发",
  prompt: "负责实现登录页面的 React 组件...",
  name: "frontend-dev",
  team_name: "feature-team"
})

Agent({
  description: "后端开发",
  prompt: "负责实现认证 API 端点...",
  name: "backend-dev",
  team_name: "feature-team"
})

队友通信

通过 SendMessage 工具发送消息：

// 发送给特定队友
SendMessage({
  to: "frontend-dev",
  message: "API 接口已就绪，格式是...",
  summary: "通知 API 接口格式"
})

// 广播给所有队友
SendMessage({
  to: "*",
  message: "大家暂停，需求变更了...",
  summary: "广播需求变更"
})

关停协调

当任务完成后，Team Lead 请求队友关停：

// 1. 发送关停请求
SendMessage({
  to: "frontend-dev",
  message: { type: "shutdown_request", reason: "任务已完成" }
})

// 2. 队友回复批准
SendMessage({
  to: "team-lead",
  message: { type: "shutdown_response", request_id: "...", approve: true }
})

// 3. 所有队友关停后，清理团队
TeamDelete()

执行后端

Agent Teams 支持两种执行后端：

后端	说明	适用场景
in-process	同进程运行，AsyncLocalStorage 隔离	默认模式，轻量高效
tmux	独立 tmux pane 运行	需要独立终端视图
iTerm2	独立 iTerm2 窗口运行	macOS iTerm2 用户

---

六、自定义 Agent

除了内置 Agent，你还可以创建自己的专业代理。

桌面端管理与作用域

桌面端入口是 设置 → Agents。这里和 CLI 使用同一份 Agent 定义文件，不会再把配置复制到数据库或 localStorage：

作用域	唯一事实源	用途
用户	~/.claude/agents/*.md	在所有项目中可用
项目	<项目目录>/.claude/agents/*.md	只在当前项目中可用；同名时覆盖用户 Agent

用户和项目 Agent 可以在桌面端创建、编辑和删除，保存结果会直接写回对应的 Markdown 文件。内置、插件、托管策略和 CLI 参数等其他来源也会显示在列表中，但只能查看，不能从桌面端改写其来源文件。

当桌面端连接着当前运行会话时，创建、编辑或删除 Agent 会原地热重载该会话，下一次 spawn 立即使用新定义。如果没有可用的运行时，或热重载失败，文件保存仍然成功；桌面端会显示不阻塞操作的警告，并在下次启动时自动读取已保存的定义。

定义格式

在用户或项目的 agents 目录下创建 .md 文件：

---
name: code-reviewer
description: 专业代码审查代理
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
effort: high
permissionMode: dontAsk
maxTurns: 10
---

你是一个专业的代码审查员。请检查以下方面：

1. 代码质量和可读性
2. 潜在的安全漏洞
3. 性能问题
4. 最佳实践遵循

可配置字段

字段	类型	说明
name	string	Agent 类型名称
description	string	何时使用的说明
tools	string[]	允许的工具列表（['*'] 表示全部）
disallowedTools	string[]	禁止的工具列表
model	string	使用的模型（fable/opus/sonnet/haiku、完整模型 ID 或 inherit）
effort	string	推理强度（low/medium/high/xhigh/max），以模型能力为准
permissionMode	string	权限模式
maxTurns	number	最大对话轮数
mcpServers	object[]	需要的 MCP 服务器
hooks	object	Agent 特定的钩子
color	string	Agent 的界面标识颜色
skills	string[]	可使用的技能
memory	string	记忆作用域（user/project/local）
isolation	string	隔离模式（worktree/remote）
background	boolean	是否默认后台运行

模型、推理强度与 Thinking

要继承当前会话，最清楚的写法是省略对应字段：不写 model 就继承主会话模型，不写 effort 就继承当前会话的推理强度。model: inherit 是模型字段的等价显式写法；effort 没有 inherit 值。

模型的解析优先级从高到低为：

1. CLAUDE_CODE_SUBAGENT_MODEL 的具体模型值（设为 inherit 时不锁定模型）
2. 本次 Agent({ ..., model: "..." }) 调用指定的模型
3. Agent Markdown frontmatter 中的 model
4. 主会话模型

推理强度的解析优先级从高到低为：

1. CLAUDE_CODE_EFFORT_LEVEL
2. Agent Markdown frontmatter 中的 effort
3. 当前会话的 effort
4. 模型默认值

Agent 工具没有单次调用的 effort 参数，因此应在 Agent 定义或会话层设置。low、medium、high、xhigh、max 是否可用取决于解析后的真实模型及提供商能力；Claude 模型会向下回退到可用档位，其他提供商按各自的模型目录规范化，不支持 effort 的模型不会应用该字段。

整数形式的 effort 仅为既有 SDK/JSON 与内部配置兼容而保留，不属于推荐的官方 Agent 配置；桌面端 Agent 管理器只写入以上五个命名档位。

子 Agent 通常继承主会话的扩展思考（extended thinking）开关，但解析后的模型强制要求优先；例如 Fable 5 会规范化为 adaptive thinking。目前不支持在单个 Agent frontmatter 中设置 thinking 或 thinkingBudget；effort 也不是固定的 thinking token 预算。

同名 Agent 的来源优先级

当多个来源定义了同名 Agent 时，cc-haha 按以下优先级选择实际生效的定义（从高到低）：

1. 策略 Agent（policy）— 组织托管策略
2. CLI 参数 Agent（flag）— 通过 --agents 注册
3. 项目 Agent（project）— <项目目录>/.claude/agents/
4. 用户 Agent（user）— ~/.claude/agents/
5. 插件 Agent（plugin）— 由插件提供
6. 内置 Agent（built-in）— 系统预定义

桌面端仍会展示被覆盖的定义及其来源，但真正 spawn 时使用优先级最高的活动定义。

---

七、权限模式

每个 Agent 可以设置不同的权限模式：

模式	说明
default	正常权限请求，需要用户确认
plan	所有操作需要显式审批
acceptEdits	自动接受文件编辑，其他操作需确认
bypassPermissions	跳过所有权限检查
dontAsk	拒绝所有未预批准的操作
auto	AI 驱动的权限分类（仅 Ant 内部）
bubble	权限提示冒泡到父代理终端

---

八、快速参考

操作	方法
生成子代理	Agent({ prompt: "...", subagent_type: "Explore" })
后台运行	Agent({ ..., run_in_background: true })
并行生成	单条消息中发送多个 Agent 调用
Worktree 隔离	Agent({ ..., isolation: "worktree" })
创建团队	TeamCreate({ team_name: "..." })
发送消息	SendMessage({ to: "name", message: "..." })
广播消息	SendMessage({ to: "*", message: "..." })
请求关停	SendMessage({ to: "name", message: { type: "shutdown_request" } })
删除团队	TeamDelete()
管理自定义 Agent	桌面端 设置 → Agents，或直接编辑 ~/.claude/agents/*.md / <项目目录>/.claude/agents/*.md
指定模型	Agent({ ..., model: "haiku" })
指定推理强度	在 Agent Markdown frontmatter 中设置 effort: high
命名 Agent	Agent({ ..., name: "researcher" })