3.1 第一个 Agent——子代理调度实战
小李听了很多理论，终于想动手试试了。
他的任务很简单：审查一个开源项目的代码质量。这个项目他不熟悉，需要先探索代码结构，再定位可能的问题，最后给出审查报告。
小李打开 Claude Code，准备让 Agent 来做。
理解子代理
Claude Code 的 Agent 系统是三层架构：
主代理 (Primary Agent)
处理对话、加载 Skill、调度子代理
↓
context: fork
↓
Explore
只读搜索
Plan
只做规划
general-purpose
全能执行
- 主代理：和你对话的那个，负责理解需求、分配任务
- 子代理：被主代理调度出去执行的「小工」，各自有专门的能力
- context: fork：子代理在隔离的上下文中运行，不影响主对话
隔离的意义
子代理运行在独立上下文中，就像把任务外包给另一个员工——他在自己的工位上干活，完成后把结果汇报给你，不会把他的工作台搬到你的办公室。
实战：代码审查 Agent
小李的需求：审查一个不熟悉的 Express 项目。
步骤一：用 Explore 代理探索项目
小李输入：
请探索这个项目的代码结构，重点关注：
1. 项目用了什么框架和主要依赖
2. 目录结构是怎么组织的
3. 有哪些主要的路由和 API 端点Claude Code 会自动调度 Explore 子代理：
调度
主代理 → 调度 Explore 子代理（隔离上下文） 搜索 package.json → 发现用 Express + TypeScript
搜索 src/ 目录结构 → 发现 routes/、controllers/、models/
搜索路由文件 → 发现 8 个 API 端点
返回
返回摘要给主代理 Explore 子代理的特点：
- 只读：不能修改任何文件，只能搜索和阅读
- 快速：专为代码搜索优化
- 返回摘要：不会把所有内容塞进主对话，只返回关键发现
步骤二：用 Plan 代理制定审查计划
基于探索结果，小李继续：
很好。现在请制定一个代码审查计划，
重点关注错误处理和安全性。主代理调度 Plan 子代理：
调度
Plan 子代理（隔离上下文中执行） 分析探索结果
制定审查计划：1. 检查所有路由的错误处理 2. 检查 SQL 注入风险 3. 检查认证中间件 4. 检查敏感信息泄露
返回
返回计划摘要给主代理 Plan 子代理的特点：
- 只规划：不执行任何操作，只输出计划
- 考虑全面：有更多空间思考全局
步骤三：用 general-purpose 代理执行审查
请按计划执行代码审查。主代理调度 general-purpose 子代理：
调度
general-purpose 子代理（隔离上下文中执行） 逐一读取路由文件
分析每个端点的错误处理
检查 SQL 查询是否参数化
检查认证中间件覆盖范围
返回
返回详细审查报告 general-purpose 子代理的特点：
- 全能：可以读文件、写文件、跑命令
- 适合复杂任务：需要多步执行和判断
context: fork 的关键细节
子代理的隔离机制（context: fork）有几个重要特点，你必须知道：
| 特点 | 说明 | 影响 |
|---|---|---|
| 无对话历史 | 子代理看不到你之前的对话 | 必须在指令中提供完整上下文 |
| 返回摘要 | 子代理只返回结果摘要 | 详细过程不会污染主对话 |
| 权限子集 | 子代理权限 ≤ 主代理权限 | 主代理不能用的工具，子代理也不能用 |
| 独立进程 | 子代理独立运行 | 不会阻塞主对话 |
最常见的坑
子代理没有对话历史！ 如果你跟主代理聊了 10 轮，然后调度子代理，子代理对这 10 轮对话一无所知。你必须把所有必要信息写进调度指令里。
反面案例：
小李：帮我修一下刚才说的那个 Bug
主代理调度子代理：修一下那个 Bug
子代理：什么 Bug？我没有之前的对话记录……正确做法：
小李：帮我修一下 userRoutes.ts 中第 42 行的空指针异常
主代理调度子代理：修复 userRoutes.ts 第 42 行的空指针异常，
该文件在 src/routes/ 目录下，错误发生在 getUserById 函数中，
当用户 ID 不存在时返回了 null 而非 404 错误。
子代理：收到，我来修复。什么时候用子代理，什么时候自己干？
| 场景 | 推荐 | 原因 |
|---|---|---|
| 搜索代码位置 | Explore 子代理 | 快速、只读、专业 |
| 制定复杂计划 | Plan 子代理 | 有空间思考全局 |
| 执行复杂任务 | general-purpose | 需要读写执行 |
| 简单的延续对话 | 主代理内联 | 不需要隔离，上下文连贯 |
| 需要对话上下文的任务 | 主代理内联 | 子代理没有历史 |
经验法则
如果任务需要大量搜索但不修改代码，用 Explore。如果需要全局规划，用 Plan。如果需要完整执行能力，用 general-purpose。如果只是继续当前的对话，别开子代理。
在其他工具中的对应
| 概念 | Claude Code | Cursor | Windsurf |
|---|---|---|---|
| 子代理 | Agent Tool + context: fork | Agent Mode 后台执行 | Cascade 自动调度 |
| 只读搜索 | Explore subagent | Ctrl+Shift+F 搜索 | Cascade Read 模式 |
| 规划 | Plan subagent | Plan Mode | Cascade Chat 模式 |
| 全能执行 | general-purpose | Agent Mode | Cascade Write 模式 |
本节核心要点
- Claude Code 的 Agent 系统是三层架构：主代理 → 子代理 → 自定义 Agent
- Explore（只读搜索）、Plan（只规划）、general-purpose（全能）是三种内置子代理
- context: fork 让子代理在隔离上下文中运行，只返回摘要
- 子代理没有对话历史，必须在指令中提供完整上下文
- 选子代理还是内联，取决于任务的性质和上下文需求
思考题：如果你要实现一个「代码重构 Agent」，你会怎么设计主代理和子代理的分工？哪些步骤用 Explore，哪些用 Plan，哪些用 general-purpose？
下一节预告：同一任务，不同工具——我们让五个 Agent 干同一件事，看看它们有什么不同。