[AI]Cursor Subagent 机制详解

一、什么是 Subagent

Subagent 是 Cursor 主 Agent 可以委派任务的专职 AI 助手：每个 subagent 拥有自己独立的上下文窗口，处理特定类型的工作，完成后把结果返回给父 Agent。

它解决的核心问题是：主 Agent 的上下文窗口是稀缺资源。在没有 subagent 之前，探索代码库产生的大量中间输出、冗长的命令日志、浏览器 DOM 快照全部堆在主对话里，很快就把上下文撑爆。

四个设计目标：

价值	说明
上下文隔离	长研究、探索任务的中间产物不占主对话
并行执行	多个 subagent 同时跑，不用排队等串行完成
专业能力定制	每个 subagent 可配置专属 prompt、工具、模型
可复用	自定义 subagent 可跨项目复用

二、运行原理

委派链路

复制代码

用户 prompt
   │
   ▼
主 Agent（Parent） ──判断任务适合委派──▶ 通过 Task 工具发起调用
   │                                        │
   │                                        ▼
   │                              Subagent 以全新上下文启动
   │                              （父 Agent 把必要信息写进 prompt，
   │                               因为 subagent 看不到历史对话）
   │                                        │
   │                                        ▼
   │                              自主执行：读文件/跑命令/改代码
   │                                        │
   ◀──────────── 只返回最终总结 ◀───────────┘

两个关键点：

干净上下文启动：Subagent 不继承此前的对话历史，父 Agent 必须在委派的 prompt 里带上所有必要上下文。
只回传结论：中间过程（几十次文件读取、搜索结果）留在 subagent 内部，父 Agent 只收到一条最终结果消息------这是保护主上下文的核心机制。

前台 vs 后台两种模式

模式	行为	适用场景
Foreground	阻塞父 Agent，等结果返回	串行依赖：下一步需要它的输出
Background	立即返回，subagent 独立干活	长任务、并行工作流

嵌套限制

自 Cursor 2.5 起，subagent 可以再启动子 subagent 形成协作树，但深度限制为两层：主 Agent 和它的直接 subagent 可以发起委派，subagent 的 subagent 就不能再往下派了。

成本模型（重要）

每个 subagent 有独立的上下文窗口和 token 消耗，5 个并行 subagent ≈ 5 倍 token 用量。对于简单任务，主 Agent 直接做反而更快更省------并行买的是墙钟时间，花的是 token。

三、内置的三个 Subagent

Cursor 自带三个内置 subagent，专门吃掉"上下文黑洞"型操作，无需配置：

Subagent	职责	为什么做成 subagent
Explore	搜索和分析代码库	探索产生大量中间输出，会用更快的模型跑多次并行搜索
Bash	执行一串 shell 命令	命令输出冗长，隔离后主 Agent 只看结论不看日志
Browser	通过 MCP 控制浏览器	DOM 快照和截图很吵，subagent 过滤后只回传相关结果

四、自定义 Subagent

文件格式

在项目目录 .cursor/agents/ 或用户目录 ~/.cursor/agents/ 下放 Markdown 文件，YAML frontmatter + prompt 正文：

markdown 复制代码

---
name: verifier
description: Validates completed work. Use after tasks are marked done 
             to confirm implementations are functional.
model: inherit
readonly: true
is_background: false
---

You are a skeptical validator. Your job is to verify that work claimed 
as complete actually works.

When invoked:
1. Identify what was claimed to be completed
2. Check that the implementation exists and is functional
3. Run relevant tests or verification steps
4. Look for edge cases that may have been missed

Report:
- What was verified and passed
- What was claimed but incomplete or broken
- Specific issues that need to be addressed

Do not accept claims at face value. Test everything.

Frontmatter 字段：

字段	作用
`name`	标识符，小写字母加连字符
`description`	最关键------主 Agent 靠它决定何时自动委派
`model`	`inherit`（跟父 Agent 同款）或指定模型 ID
`readonly`	为 `true` 时禁止写文件和有副作用的 shell 命令（同时会禁用 MCP）
`is_background`	为 `true` 时默认后台运行

三种触发方式

① 自动委派 ------在 description 里写上 "use proactively" / "always use for" 之类的措辞，能显著提高被自动选中的概率。

② 显式斜杠命令：

复制代码

> /verifier confirm the auth flow is complete
> /debugger investigate this error

③ 自然语言点名：

复制代码

> Use the verifier subagent to confirm the auth flow is complete

五、隔离与环境：从共享目录到独立 VM

这是实际使用中最容易踩坑的一层。默认情况下所有 subagent 共享父 Agent 的工作区（checkout）------多个 subagent 同时改文件会互相覆盖。

三档隔离方案：

级别	方式	说明
无隔离	默认	共享工作区，适合只读型 subagent（审计、搜索）
Git worktree	prompt 里要求隔离	每个 subagent 拿到独立 worktree 和分支，改动留在各自分支上等父 Agent 合并
云端 VM	`/in-cloud`	每个 subagent 起一台独立云 VM + 仓库克隆 + 独立分支

两个实用命令：

/in-cloud：下一个任务作为云端 subagent 运行，自起 VM 和分支，本地工作区保持干净------适合修 CI、调查 issue 这类长任务。
/babysit：派一个云端 subagent 盯着某个 PR，远程迭代直到可以合并，不占用本地会话。

六、使用示例

示例 1：并行审查（最常见的入门场景）

复制代码

> Review the API changes and update the documentation in parallel

主 Agent 会在同一条消息里发出多个 Task 调用，两个 subagent 同时开工。

示例 2：Verifier 模式（治"AI 说做完了但其实没做完"）

把上面的 verifier.md 放进 .cursor/agents/，然后：

复制代码

> 实现用户注册接口，完成后用 verifier 验证

主 Agent 写代码 → verifier 以只读权限独立跑测试、查边界情况 → 回传"验证通过项 / 声称完成但实际有问题的项"。因为 verifier 和实现者是不同的上下文，它能以更"怀疑"的视角挑毛病。

示例 3：编排者模式（Orchestrator）

复杂工作流由父 Agent 串联多个专职 subagent：

复制代码

Planner（分析需求出方案） → Implementer（按方案实现） → Verifier（对照需求验收）

每次交接都带结构化输出，下一个 Agent 拿到清晰的上下文。

示例 4：蜂群修 flaky test（配合 worktree 隔离）

复制代码

> Run a swarm of subagents to fix these five flaky tests, 
  each in its own environment

5 个 subagent 各占一个独立 worktree/云环境，各修各的互不踩踏，父 Agent 最后统一合并。

七、最佳实践与坑位

该做的：

职责要窄------一个 subagent 一件事，别写"万能助手"型
投资 description 字段------它是自动委派的唯一依据，写完要用实际 prompt 测试能否被正确触发
提交进版本库 ------.cursor/agents/ 进 Git，全团队共享
并行改代码时必须要求隔离------共享 checkout 下多 subagent 并发写入是事故高发区

该注意的：

Token 成本线性放大，且云端 subagent 按所选模型的 API 价格计费
MCP 继承是全量的 ：自定义 subagent 继承父 Agent 所有 MCP 工具，目前只能靠 readonly 整体封禁，不支持按 server/按工具白名单（官方已确认这个缺口，在讨论中）。
简单任务别用 subagent：生成 changelog、格式化导入这种一次完成的单用途任务，官方建议用 Skill 而不是 subagent
后台 subagent 的输出写在 ~/.cursor/subagents/，父 Agent 可以读这些文件查进度

总结

Subagent = 父 Agent 通过 Task 工具派生的"独立上下文工作单元"：干净启动、自带窗口、只回传结论。用它干三件事------隔离上下文污染、并行吞吐、专业化分工。代价是 token 线性增长，所以原则是"宽任务拆给 subagent，窄任务留给 skill，简单任务主 Agent 自己干"。