Cursor 子代理怎么定义：任务分派与上下文隔离

2026-08-18

主对话开着开着就被塞满，是很多人开始关心 subagent 的直接原因。一次全仓搜索的中间结果、一串 shell 命令的完整输出、一轮浏览器操作抓回来的 DOM 快照，这些东西对最终结论几乎没有价值，却实打实占着主对话的位置。Cursor 官方文档《Subagents》页（cursor.com/docs/subagents）对 subagent 的定位写得很直白：每个 subagent 有自己独立的上下文窗口，独立干完活，只把最终结果返回给父代理。

这篇只做一件事——把这一页里能核到的配置字段和上下文隔离的粒度说清楚，其余靠感觉的部分一律不写。

一、先弄清楚它隔离的是什么

文档写明：subagent 以一个干净的上下文启动，不能访问此前的对话历史；父代理需要把必要信息一并写进给它的 prompt 里。这一句是理解整套机制的地基——所谓上下文隔离，不是”共享一份上下文再各自加料”，而是父子两边根本不共享历史，只通过”入口 prompt”和”出口最终消息”这两个窄口子通信。

文档同时列出了三个内置 subagent：

内置 subagent	用途	文档给的隔离理由
`explore`	搜索与分析代码库	代码库探索产生大量中间输出，会撑大主上下文
`bash`	跑一串 shell 命令	命令输出通常很啰嗦，隔离掉能让父代理专注在决策而非日志上
`browser`	通过 MCP 工具控制浏览器	浏览器交互会产生嘈杂的 DOM 快照与截图，由 subagent 过滤成相关结果

文档明确说这三个不需要你配置，Agent 会在合适的时候自动使用。另外文档自述这三个的设计依据是”对撞上上下文窗口上限的 agent 对话所做的分析”——这是文档自己写的理由，我照抄，不替它引申。

二、前置条件

这一段最容易被跳过，但少一条就是白折腾。

端：文档写明 subagent 可以在编辑器、CLI 和 Cloud Agents 里使用。

嵌套：FAQ 里写的是 “Since Cursor 2.5”——主代理和它的直接 subagent 可以再启动子 subagent，但由另一个 subagent 启动的 subagent 不能再往下启动，即层级有上限。文档同时写明嵌套启动还需要当前 mode 有 Task 工具的访问权限，而且 hooks 或工具策略可以阻止这种启动。所以”我写了嵌套但没跑起来”至少有三个方向要查：版本、当前 mode 的工具权限、有没有 hooks／策略挡着。

cloud subagent：文档写明它从 Cursor 桌面应用的 Agents Window 运行，使用为你的仓库配置的 environment，并且遵循与其它 Cloud Agents 相同的模型与能力规则。

模型可用性：model 字段能不能生效，取决于团队管理员是否封禁了该模型、你所在的套餐是否包含它。这条留到边界一节细说。

三、定义一个 subagent：文件放哪、写什么

3.1 文件位置与优先级

文档给了六个位置，项目级三个、用户级三个：

类型	位置	作用范围
项目 subagent	`.cursor/agents/`	仅当前项目
	`.claude/agents/`	仅当前项目（Claude 兼容）
	`.codex/agents/`	仅当前项目（Codex 兼容）
用户 subagent	`~/.cursor/agents/`	当前用户的所有项目
	`~/.claude/agents/`	当前用户的所有项目（Claude 兼容）
	`~/.codex/agents/`	当前用户的所有项目（Codex 兼容）

优先级规则文档写了两层：同名时项目级优先于用户级；多个位置有同名 subagent 时 .cursor/ 优先于 .claude/ 或 .codex/。团队里如果既有从 Claude 侧迁过来的目录又有新写的 .cursor/agents/，同名文件的胜出方是后者——这一点排查时很容易忘。

关于 Windows：文档统一用 ~/.cursor/agents/ 这种写法，没有单独给出 Windows 下的等价路径写法，本文不替它拼。这里给一条通用做法（不是官方文档内容）：先用项目级 .cursor/agents/（相对项目根目录，Windows 与 macOS/Linux 写法一致，也便于随仓库进版本控制），确认链路通了再动用户级目录。文档在最佳实践里也明确建议把 .cursor/agents/ 纳入版本控制，让团队一起受益。

3.2 五个配置字段

每个 subagent 是一个带 YAML frontmatter 的 markdown 文件，frontmatter 之后是提示词正文。文档列出的字段一共五个，全部非必填：

字段	类型	默认值	语义
`name`	string	从文件名推导	显示名与标识符，文档要求用小写字母和连字符
`description`	string	—	在 Task 工具提示里展示的简短描述，Agent 读它来决定是否委派
`model`	string	`inherit`	`inherit` 或一个具体的 model ID
`readonly`	boolean	`false`	为 `true` 时以受限写权限运行：不改文件，不执行会改变状态的 shell 命令
`is_background`	boolean	`false`	为 `true` 时在后台运行，不阻塞父代理

有两个字段值得单独拎出来。

一是 description。它不是给人看的注释，文档把它定位成委派决策的输入，最佳实践一节还专门说要在它上面花时间打磨，反面例子给的是 “Use for general tasks” 这种给不出任何信号的写法，正面例子是 “Use when implementing authentication flows with OAuth providers” 这种带触发条件的写法。想让它更容易被自动选中，文档说可以在描述里带上 “use proactively” 或 “always use for” 这类措辞。

二是 is_background。它对应文档里的两种运行模式：foreground 会阻塞直到 subagent 完成并立刻返回结果，适合你必须拿到输出才能往下走的顺序任务；background 立即返回，subagent 独立工作，适合长任务或并行工作流。注意这是运行模式的开关，不是”要不要用 subagent”的开关。

文档给的一个完整示例长这样：

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
---

You are a security expert auditing code for vulnerabilities.

When invoked:
1. Identify security-sensitive code paths
2. Check for common vulnerabilities (injection, XSS, auth bypass)
3. Verify secrets are not hardcoded
4. Review input validation and sanitization

3.3 `model` 字段与方括号参数

model 只有两类取值：inherit（跟父代理同一个模型，也是默认值），或者一个具体的 model ID。文档给的选择建议是——需要和父代理同等推理能力就用 inherit；不管父代理用什么都必须是某个特定模型的能力时，才写死具体 ID。

比较容易被忽略的是方括号参数：在 model ID 后面追加方括号，可以设置速度、推理强度、上下文窗口这类按模型区分的选项，写法是 id=value，多个选项用逗号分隔。文档给的例子里，空方括号本身也有含义——它会选中标准变体而不是 fast 变体；另外还有显式写 fast=false 选标准变体、用 effort=high 设推理强度的写法，多个选项可以组合。文档同时说明：可用选项取决于具体模型，与 SDK 的 model parameters 用同一套 id=value 语法。

文档里带方括号的 frontmatter 示例是这样的：

---
name: planner
description: Plans complex changes before implementation.
model: claude-opus-5[effort=high]
---

Break the task into a clear, ordered implementation plan.

上面的 model ID 是官方文档当时的示例值，平台上有哪些模型 ID、每个模型支持哪些方括号选项都在变，别把它当成清单用；具体取值以官方文档最新内容为准。

3.4 怎么把它叫起来

文档给了三条路径。自动委派由任务复杂度与范围、项目里的自定义 subagent 描述、当前上下文与可用工具共同决定。显式调用用 /name 语法：

> /verifier confirm the auth flow is complete
> /debugger investigate this error
> /security-auditor review the payment module

也可以自然语言点名，比如 “Use the verifier subagent to confirm the auth flow is complete”。并行的写法则是在一条消息里让它同时干几件事，文档解释说 Agent 会在单条消息里发出多个 Task 工具调用，于是这些 subagent 同时跑。

四、边界：哪些地方文档划了线

model 写了不一定用。文档列了三种被覆盖的情况：团队管理员封禁了该模型；旧的按请求计费套餐下该模型需要 Max Mode 而你没开；你当前套餐不含该模型。这些情况下 Cursor 会回退到一个兼容模型。FAQ 里还有更细的一条：在没有 Max Mode 的旧版按请求计费套餐上，无论 model 怎么配，subagent 都用 Composer 运行；如果管理员又把 Composer 封了，则只有开启 Max Mode 才能运行 subagent。所以看到”模型没按我配的走”，先查套餐与管理员策略，再怀疑配置文件。

cloud subagent 的 MCP 来源不一样。文档写明 subagent 会继承父代理的全部工具，包括已配置服务器的 MCP 工具——但 cloud subagent 是例外：它跑在云端 VM 上，用的是团队在 cursor.com/agents 配置的 MCP 服务器，不是你本地会话里的那套。本地跑通不等于云端跑通，这条差异值得写进团队文档。

readonly 的边界只到文档写的那两句：不做文件编辑、不执行会改变状态的 shell 命令。它对网络访问、对 MCP 工具调用还有没有别的约束，官方文档没有说明这一点，所以别把 readonly 当成完整的安全隔离来用。

代价是实打实的。文档自己列了三组权衡：上下文隔离对应启动开销（每个 subagent 要自己收集上下文）、并行对应更高的 token 用量（多个上下文同时在跑）、专注对应延迟（简单任务上可能比主代理更慢）。文档还专门写了一句：subagent 的好处是上下文隔离，不是速度。

什么时候不该用。文档给了 subagent 与 skills 的对照：需要长研究的上下文隔离、多路并行、跨多步的专业能力、想要一次独立复核，用 subagent；单一目的、一次性完成、不需要独立上下文窗口的，用 skills 或命令。反面模式一节说得更直接：别造几十个描述含糊的通用 subagent，起步就配少数几个职责清晰的即可。

本页没有标 beta / preview / deprecated。除了 “Since Cursor 2.5” 这一处版本限定外，这一页没有把上述功能标成实验性；但产品迭代频繁，这些字段与默认值随版本变动，请以官方文档最新内容为准。

五、怎么验证配对了

文档里能核到的验证手段有这么几条，按从轻到重排：

看目录。文档说查看项目里的 .cursor/agents/ 目录就能知道配置了哪些 subagent，Agent 会把所有自定义 subagent 纳入它的可用工具。
显式调用一次简单任务。FAQ 里”如何调试行为异常的 subagent”给的做法是：先检查这个 subagent 的 description 与提示词，确认指令是具体且无歧义的；也可以显式调用它跑一个简单任务。顺序上先确认它能被叫起来，再谈行为对不对。
测委派是否被触发。最佳实践里写的是：给出一些 prompt，检查是不是正确的那个 subagent 被触发了——这是专门验证 description 写没写对的动作。
后台任务读输出文件。FAQ 写明 background subagent 把输出写到 ~/.cursor/subagents/，父代理可以读这些文件查看进度；文档还说 background subagent 边跑边写状态。
失败与续跑。subagent 失败时会向父代理返回一个错误状态，父代理可以重试、带上补充上下文续跑，或另行处理。每次 subagent 执行会返回一个 agent ID，把这个 ID 传回去就能带着完整上下文续跑，比如 Resume agent abc123 and analyze the remaining test failures（abc123 是文档中的示例 ID）。

以上命令与配置片段均原样取自官方文档；组合使用时以官方文档与实际输出为准。最后补一句文档里的实用建议：如果你需要 subagent 产出结构化的输出文件，文档建议考虑用 hooks 来统一处理和保存结果，而不是让每个 subagent 各写各的。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。