mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-15 12:53:31 +08:00
072e5bcc48
Add GitHub-compatible slugify (github-slugger algorithm) to VitePress config so heading anchor IDs are consistent across both platforms. Update all inline anchor links in 22 doc files accordingly.
444 lines
12 KiB
Markdown
444 lines
12 KiB
Markdown
# Claude Code 多 Agent 系统 — 使用指南
|
||
|
||
> 让 Claude Code 同时调度多个专业代理，并行处理复杂任务。
|
||
|
||
<p align="center">
|
||
<a href="#一什么是多-agent-系统">多 Agent 系统</a> · <a href="#二六种内置-agent">六种内置 Agent</a> · <a href="#三如何生成-agent">如何生成 Agent</a> · <a href="#四后台任务管理">后台任务管理</a> · <a href="#五agent-teams--多代理协作">Agent Teams</a> · <a href="#六自定义-agent">自定义 Agent</a> · <a href="#七权限模式">权限模式</a> · <a href="#八快速参考">快速参考</a>
|
||
</p>
|
||
|
||
|
||
|
||
---
|
||
|
||
## 一、什么是多 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 格式的通知：
|
||
|
||
```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，你还可以创建自己的专业代理。
|
||
|
||
### 定义格式
|
||
|
||
在 `.claude/agents/` 目录下创建 `.md` 文件：
|
||
|
||
```markdown
|
||
---
|
||
name: code-reviewer
|
||
description: 专业代码审查代理
|
||
tools:
|
||
- Read
|
||
- Grep
|
||
- Glob
|
||
- Bash
|
||
model: sonnet
|
||
permissionMode: dontAsk
|
||
maxTurns: 10
|
||
---
|
||
|
||
你是一个专业的代码审查员。请检查以下方面：
|
||
|
||
1. 代码质量和可读性
|
||
2. 潜在的安全漏洞
|
||
3. 性能问题
|
||
4. 最佳实践遵循
|
||
```
|
||
|
||
### 可配置字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | Agent 类型名称 |
|
||
| `description` | string | 何时使用的说明 |
|
||
| `tools` | string[] | 允许的工具列表（`['*']` 表示全部） |
|
||
| `disallowedTools` | string[] | 禁止的工具列表 |
|
||
| `model` | string | 使用的模型（sonnet/opus/haiku/inherit） |
|
||
| `permissionMode` | string | 权限模式 |
|
||
| `maxTurns` | number | 最大对话轮数 |
|
||
| `mcpServers` | object[] | 需要的 MCP 服务器 |
|
||
| `hooks` | object | Agent 特定的钩子 |
|
||
| `skills` | string[] | 可使用的技能 |
|
||
| `memory` | string | 记忆作用域（user/project/local） |
|
||
| `isolation` | string | 隔离模式（worktree/remote） |
|
||
| `background` | boolean | 是否默认后台运行 |
|
||
|
||
### 加载优先级
|
||
|
||
自定义 Agent 的加载遵循优先级：
|
||
|
||
1. **内置 Agent**（built-in）— 系统预定义
|
||
2. **插件 Agent**（plugin）— 通过插件注册
|
||
3. **用户 Agent**（user）— `~/.claude/agents/`
|
||
4. **项目 Agent**（project）— `.claude/agents/`（项目级）
|
||
5. **标记 Agent**（flag）— 通过 API 注册
|
||
6. **策略 Agent**（policy）— 组织策略
|
||
|
||
同名 Agent 按优先级覆盖。
|
||
|
||
---
|
||
|
||
## 七、权限模式
|
||
|
||
每个 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 | 在 `.claude/agents/*.md` 创建定义文件 |
|
||
| 指定模型 | `Agent({ ..., model: "haiku" })` |
|
||
| 命名 Agent | `Agent({ ..., name: "researcher" })` |
|