18 · Subagent 子代理

把大型任务拆解为并行流水线——让专业代理干专业的事，主代理做总指挥。

01 Subagent 是什么

Subagent（子代理）是 Cursor 中由主 Agent 派生的轻量级 AI 工作单元。传统工作流中，一个 Agent 按顺序处理所有请求——读文件、改代码、写文档、跑测试，全由同一个上下文完成。Subagent 打破了这种线性瓶颈。

想象一个建筑工地：

• 主 Agent是总工程师，负责拆解蓝图、分配任务、验收成果
• Subagent是专业施工队——电气组负责布线，管道组负责水管，油漆组负责墙面
• 各组同时开工，互不干扰

在 Cursor 中，Subagent 的出现让 AI 驱动的开发从单线程迈入了多线程时代。

核心思想：主 Agent 将一个大型任务拆分为多个子任务，为每个子任务生成一个独立的 Subagent，每个 Subagent 拥有自己的上下文和工具集，并行执行，最后主 Agent 汇总结果。

02 为什么需要 Subagent

在 Subagent 诞生之前，Agent 工作流有一个根本性矛盾：

适用场景：

• 你有一个 10,000 行的代码库需要做架构升级
• 你需要同时改写前端组件、更新 API 文档、补充单元测试
• 你希望 AI 大范围重构代码，同时又不想干扰正在运行的服务

在这些场景下，Subagent 的优势碾压单 Agent 模式。

03 Subagent 的类型

Cursor 内置了多种专业 Subagent，每个擅长不同的工作领域：

3.1 Terminal Subagent（终端子代理）

定位：命令行操作的专用代理。

Terminal Subagent 的任务就是执行命令并解析输出。它不需要关心代码编辑，也不需要理解项目架构——它只关心：

• 运行 npm test 并解析测试结果
• 执行 git log --oneline -10 并提取关键信息
• 运行 python manage.py check --deploy 并报告配置风险
• 执行 docker-compose up -d 并等待服务就绪

典型用法：

主 Agent 判断需要运行测试 → 创建 Terminal Subagent
→ Subagent 运行 npm test → 解析输出中的 pass/fail
→ 返回结构化结果给主 Agent

实际工作流示例：

# 主 Agent 的思维过程
1. 用户："帮我重构 auth 模块，改完后跑测试确保没问题"
2. 主 Agent 拆解任务：
   - Refactor Subagent: 重构 auth 代码
   - Terminal Subagent: 在重构过程中实时跑相关测试验证
   - Docs Subagent: 更新 API 文档
3. 三个 Subagent 同时启动...

3.2 Docs Subagent（文档子代理）

定位：文档编写的专业写手。

Docs Subagent 负责一切和文字打交道的任务：

• 从源代码生成 API 参考文档
• 编写 README、CHANGELOG
• 生成架构说明和设计文档
• 翻译技术内容

Docs Subagent 的优势在于它不给主 Agent 添负担——写文档是上下文密集的任务，如果主 Agent 亲自写，Token 消耗会急剧膨胀。交给专门的 Docs Subagent，主 Agent 只需要审阅最终输出。

3.3 Test Subagent（测试子代理）

定位：测试编写和执行的专业 QA 工程师。

Test Subagent 的能力链：

1. 读取被测代码，分析接口签名和预期行为
2. 编写测试用例（单元测试、集成测试、端到端测试）
3. 运行测试并分析失败原因
4. 修复失败的测试或报告真正的代码缺陷

与其他 Subagent 不同，Test Subagent 通常会迭代多次——写完测试 -> 运行 -> 发现失败 -> 修复 -> 重新运行，直到绿灯全亮。

3.4 Refactor Subagent（重构子代理）

定位：代码重构的专业建筑师。

Refactor Subagent 接手最复杂的代码改动任务：

• 将函数从类组件迁移到函数组件
• 提取公共逻辑到共享工具函数
• 拆分大型模块为多个小文件
• 统一代码风格和模式

Refactor Subagent 是”胆子最大”的 Subagent——它敢于大段删除和移动代码。但也正因为如此，主 Agent 在合并其输出时需要严格审阅。

3.5 对比总结

04 Subagent 并行工作模型

Subagent 最大的威力来自并行执行。让我们用一个真实场景来理解。

场景：重构支付模块

假设你的项目有一个 payment.ts 模块，包含 800 行代码、缺少测试、文档过时。你想：

1. 将支付逻辑拆分为 gateway.ts、checkout.ts、refund.ts
2. 为拆分的每个模块编写单元测试
3. 更新 API 参考文档
4. 确保重构后所有现有测试仍然通过

单 Agent 的工作流（顺序执行）：

重构代码 (5 min) → 写测试 (4 min) → 修复测试 (2 min) → 写文档 (3 min)
= 总计 14 分钟（串行）

Subagent 的工作流（并行执行）：

主 Agent 制定方案
├── Refactor Subagent：拆分为 3 个文件 (4 min)
├── Terminal Subagent：先跑一遍现有测试基线 (30s)
├── Test Subagent：等 Refactor 完成后，为每个新文件写测试 (3 min)
└── Docs Subagent：从代码注释生成文档 (2 min)
= 总计约 5-6 分钟（并行）

速度提升约 2-3 倍，而且每个 Subagent 的上下文更小、更专注，质量反而更高。

并行度与资源

Cursor 的 Subagent 系统支持多个 Subagent 同时工作。具体并行数量取决于：

• 任务的独立性（如果两个 Subagent 修改同一个文件，就不能并行）
• Cursor 后台的线程可用性
• 项目的规模和复杂度

心智模型：把 Subagent 想象成工厂流水线上的机器人。主 Agent 是车间主任，看一眼图纸就知道要派几个机器人、各自做什么、哪里可能有冲突。机器人各自开工，主任只负责最后的质量检查。

05 主 Agent 如何委派 Subagent

主 Agent 的委派过程不是随机的——它遵循一套决策逻辑：

委派流程

输入任务
  ↓
主 Agent 分析任务结构
  ↓
拆解为原子子任务         ← 粒度关键：太大则 Subagent 负担重，太小则调度开销大
  ↓
判断子任务依赖关系
  ↓
为独立子任务创建 Subagent ← 相互依赖的只能串行
  ↓
分配上下文和指令
  ↓
并行执行
  ↓
汇总结果 → 主 Agent 审阅
  ↓
如果发现问题 → 重新委派或手动修复

指令传递

主 Agent 给 Subagent 的指令就像编程中的函数调用——需要清晰的参数和返回值：

好的指令示例：

Refactor Subagent: 将 src/payment.ts 中的 processCheckout 函数提取到新文件 src/checkout.ts。函数签名保持不变。完成后报告新增文件和修改文件列表。

差的指令示例：

Refactor Subagent: 把支付模块整理一下。

好的指令包含：

• 明确的目标：做什么
• 范围界定：涉及哪些文件
• 约束条件：什么不能改
• 输出格式：完成后汇报什么

收束机制

当 Subagent 完成工作后，主 Agent 执行收束：

1. 汇总：收集所有 Subagent 的输出
2. 冲突检测：检查是否有文件被多个 Subagent 修改
3. 一致性验证：确认代码仍然能编译、测试仍然能通过
4. 最终呈现：向用户展示完整的改动情况和总结报告

06 Subagent 隔离与上下文

上下文隔离

每个 Subagent 拥有完全独立的上下文窗口。这意味着：

• Subagent A 读入的 500 行代码不会被 Subagent B 看到
• Subagent A 的 Token 消耗不影响 Subagent B 的可用窗口
• 每个 Subagent 的”世界”只有其任务范围内的文件

这种隔离带来了巨大的好处：

单 Agent 方式：
[context: 读入了整个项目的 1000 个文件，Token 耗尽，开始遗忘]
   └── 修改 A 文件时已经忘记了 B 文件的内容

Subagent 方式：
Agent A[context: 只读 5 个相关文件] ← 完全专注
Agent B[context: 只读 3 个相关文件] ← 完全专注
Agent C[context: 只读测试文件]       ← 完全专注

共享上下文

但隔离不是绝对的。Subagent 之间可以通过主 Agent 来交换必要的信息：

• Refactor Subagent 通知主 Agent：“我把 payment.ts 拆成了三个文件”
• 主 Agent 将这个信息传递给 Test Subagent：“新文件是 gateway.ts、checkout.ts、refund.ts”
• Test Subagent 据此为这三个文件编写测试

这种模式称之为星型通信拓扑——所有通信经过主 Agent，Subagent 之间不直接对话。

为什么隔离很重要

# 没有隔离的恐怖故事
Agent 正在重构 API 路由层...
Agent 不小心读取了前端组件的文件（占用了大量 Token）
Agent 忘记了自己在重构路由层，开始修 UI 样式
Agent 回到路由层时，关键上下文已经被挤出 Token 窗口
→ 产生了一个半成品重构，还附带了一个没改完的样式修复
 
# 有隔离的美好世界
Refactor Subagent: 只读路由层文件，完全不受其他代码干扰
主 Agent: 全程监管，其他任务交给其他 Subagent
→ 路由层重构完美完成

07 Subagent 的适用场景

7.1 大型重构 —— Subagent 的最佳舞台

场景描述：你有一个遗留项目，需要将整个模块从 JavaScript 迁移到 TypeScript，或者从类组件迁移到 Hooks。

为什么 Subagent 适合：

• 文件数量多（50-200+ 个文件），单个 Agent 的上下文窗口不够用
• 任务模式高度重复（每个文件的迁移步骤大同小异）
• 可以有多个独立的工作线程同时处理不同目录

推荐策略：

1. 主 Agent 制定迁移方案和检查清单
2. 创建 3-5 个 Refactor Subagent，每个负责一个子目录
3. 创建 1 个 Terminal Subagent，持续编译检查是否有类型错误
4. 创建 1 个 Test Subagent，在迁移完成后跑全量测试
5. 主 Agent 汇总 Subagent 的改动，做一致性审查

7.2 文档生成 —— 让 AI 做苦力

场景描述：项目缺乏文档，你需要从代码注释和类型定义中生成完整的 API 文档。

为什么 Subagent 适合：

• 文档生成是”读密集型”任务，需要读取大量源代码
• 文档编写不会修改源代码，不会产生冲突
• 可以按模块划分并行生成

推荐策略：

1. 主 Agent 扫描项目结构，列出所有需要文档的模块
2. 创建多个 Docs Subagent，每个负责 3-5 个模块
3. 每个 Subagent 读取源代码 → 提取接口信息 → 生成 Markdown 文档
4. 主 Agent 合并文档，检查结构和风格一致性

7.3 测试覆盖 —— 质量提升的加速器

场景描述：项目测试覆盖率只有 20%，目标是将覆盖率提升到 80% 以上。

为什么 Subagent 适合：

• 测试编写是”写密集型”任务，涉及大量样板代码
• 不同模块的测试完全独立，可以并行编写
• 测试编写和代码运行可以并行（Terminal Subagent 在后台跑测试）

推荐策略：

1. 主 Agent 分析覆盖率报告，列出未覆盖的模块和函数
2. 创建多个 Test Subagent，每个负责一组相关模块
3. 每个 Subagent：读代码 → 分析分支路径 → 编写测试用例 → 运行并修复
4. 主 Agent 检查测试质量，确保没有只写”快乐路径”测试

7.4 不适用 Subagent 的场景

Subagent 不是银弹。以下场景反而不如单个 Agent 高效：

08 实战示例：Subagent 完整工作流

让我们看一个完整的实战流程，从用户输入到 Subagent 交付。

用户输入

“我的 services/order.ts 文件太大了，要 500 行。帮我拆分成 order/validator.ts、order/calculator.ts、order/persistence.ts，为每个新文件写单元测试，然后更新 services/order.ts 让它从这些新文件导入功能。最后更新 README 中的架构说明。“

主 Agent 的分析

主 Agent 的思维过程大致如下：

1. 这是一个中等规模的任务，适合用 Subagent
2. 可以拆分为 4 个子任务：
   a. Refactor: 提取代码到三个新文件
   b. Test: 为三个新文件写测试
   c. Docs: 更新 README 的架构部分
   d. Terminal: 在 Refactor 后跑编译检查
3. 依赖关系：b 依赖 a 完成，c 依赖 a 完成，d 依赖 a 完成
4. 所以流程是：a 单独先跑 → a 完成后，b+c+d 并行跑

执行过程

Phase 1: 主 Agent 读入 order.ts，分析模块结构
         → 识别出三个独立的职责域

Phase 2: 启动 Refactor Subagent
         → Subagent 读取 order.ts，创建 validator.ts / calculator.ts / persistence.ts
         → 更新 order.ts 为导入式结构
         → 报告完成，列出新增和修改的文件

Phase 3 (并行):
   ├── Test Subagent: 读取三个新文件 → 编写 15 个测试用例
   │                    → 运行 npm test → 全部通过
   ├── Docs Subagent: 读取项目 README → 在架构部分追加新文件说明
   └── Terminal Subagent: 运行 tsc --noEmit → 类型检查通过

Phase 4: 主 Agent 汇总
         → 确认所有测试通过
         → 确认类型检查通过
         → 检查 README 格式
         → 向用户展示完整报告

输出报告示例

## 任务完成报告

### 文件变更
- 新增: src/services/order/validator.ts (120行)
- 新增: src/services/order/calculator.ts (85行)
- 新增: src/services/order/persistence.ts (150行)
- 修改: src/services/order.ts (从500行精简为180行)
- 修改: README.md (架构说明已更新)

### 测试结果
- 新增测试文件: 3
- 测试用例: 15 个 (15 passed, 0 failed)
- 代码覆盖率: 从 35% 提升至 78%

### 质量检查
- TypeScript 编译: ✅ 无错误
- ESLint: ✅ 无新增 warning
- 已有测试: ✅ 全部通过

09 实践技巧与最佳实践

技巧 1：合理掌握粒度

Subagent 的任务不能太大，也不能太小：

❌ 太大：让一个 Subagent "重构整个后端"
    → 上下文不足，范围不清，容易产生不一致的代码

✅ 合适：让一个 Subagent "将 src/legacy/api 目录下 20 个 .js 文件转为 .ts"
    → 范围清晰，模式统一，可验证

❌ 太小：让一个 Subagent "在 index.ts 加一行 import"
    → 调度开销 > 实际收益，不值得

技巧 2：给 Subagent 充分但有边界的上下文

✅ 提供边界：
   - "涉及的文件：src/payment/*.ts, src/shared/types.ts"
   - "不要修改：src/payment/types.ts（其他模块依赖它的接口）"
   - "完成后汇报：新增文件列表、修改文件列表、遗留警告"

技巧 3：善用 Terminal Subagent 做验证器

在重构或测试 Subagent 工作的同时，派一个 Terminal Subagent 在后台持续跑编译/测试：

Refactor Subagent:  修改代码
Terminal Subagent:  不断 tsc --noEmit（检查是否编译通过）
                  不断 npm run lint（检查是否引入风格问题）

这种”实时验证”模式可以在问题出现的第一时间发现，而不是等到最后才暴露。

技巧 4：分阶段委派

对于有依赖链的任务，分批启动 Subagent：

Batch 1: 只启动没有依赖的 Subagent
   ├── Terminal Subagent: 跑一遍当前测试，存下基线结果
   
Batch 2 (等待 Batch 1 完成):
   ├── Refactor Subagent: 执行代码重构
   └── Docs Subagent: 预览现有文档（读操作，不冲突）

Batch 3 (等待 Batch 2 完成):
   ├── Test Subagent: 基于新代码写测试
   └── Terminal Subagent: 对比新旧基线

10 常见问题（FAQ）

Q：Subagent 和主 Agent 是什么关系？

A：主 Agent 是管理者，Subagent 是执行者。主 Agent 负责任务拆分、指令下达、结果汇总和质量控制；Subagent 专注于执行具体的子任务。Subagent 向主 Agent 报告，Subagent 之间不通信。

Q：Subagent 有自己的对话窗口吗？

A：有。每个 Subagent 拥有独立的上下文窗口和 API 调用配额。这意味着你可以同时让多个 Subagent 工作，而不用担心 Token 竞争。

Q：Subagent 能连续执行多个步骤吗？

A：可以。Test Subagent 就是典型的多步骤执行者——它需要写测试 -> 运行 -> 分析结果 -> 修复 -> 重新运行。Subagent 在完成任务之前可以自主迭代多次。

Q：Subagent 的代码改动会自动保存吗？

A：是的。Subagent 的编辑操作和普通 AI 操作一样，直接修改文件系统中的文件。这些修改不是”虚拟的”或”暂存的”——文件被真实地写入磁盘。这也是为什么主 Agent 需要审阅 Subagent 的输出。

11 总结

Subagent 的核心价值：它把 AI 辅助编程从”一个人单干”变成了”一个团队协作”。主 Agent 分派任务，Subagent 干活，你只需要验收最终结果。

什么时候开始用 Subagent？下一次你面对一个大型任务，感觉”这事情一个人干太慢了”的时候——停一下，想想能不能拆开，交给 Subagent。

下一篇

准备好探索更多 Cursor 高级功能了吗？继续阅读 16 · Hooks 钩子，学习如何在 AI 操作的关键时机自动触发你的脚本。

(注：Subagent 和 Hooks 是 Cursor 进阶功能的两大支柱——Subagent 解决”怎么并行干活”，Hooks 解决”怎么自动化控制”，两者配合可以实现极其强大的工作流。)