1. SubAgent 到底是什么先搞清它和普通对话的差别用 Cursor 写代码的人基本都经历过这个阶段一开始觉得它的对话补全很强后来开始玩 Chat 里的 Agent 模式让它在整个代码库范围内自主改代码、跑命令、修报错。但用久了你会发现单个 Agent 干起活来其实有点“独木难支”的意思——大一点的改造任务它一个线程串行跑下来动不动十几分钟中间还会因为上下文太长开始犯迷糊。SubAgent 就是冲着这个痛点来的。它本质上是把原来“一个全能代理从头干到尾”的模式拆成“多个子代理并行开工、各管一段、最后汇总结果”的模式。你可以把它理解成一个项目经理带着若干个小工项目经理负责理解全局、拆解任务、分配下去每个小工只盯着自己那一小块干完把结果交回来。这套机制解决了两类很典型的问题。一类是效率问题多个互不依赖的子任务并行执行比串行快很多另一类是上下文质量问题每个子代理只加载自己需要的那部分代码和说明不会被整个项目无关的文件把上下文撑爆。很多人觉得 SubAgent 只是“多了个并行的入口”其实不是它在上下文管理上的收益往往比速度上的收益更重要。这篇文章适合的人想优化 Cursor 工作效率的中高级用户、被大任务耗时长和上下文错乱折磨过的人。我后面会把入口、配置、实战场景、翻车记录全都翻出来讲能直接照着用。2. 上手实操从入口到一次完整的子任务下发2.1 入口位置和界面结构SubAgent 的入口不算隐蔽但确实有不少人没注意过。在 Cursor 的主对话框里输入框附近通常会有一个模式切换的入口你能在普通 Chat、Agent、SubAgent 几个模式之间切换。有的版本在对话窗口顶部有标签页有的版本在小图标菜单里如果找不到先看一眼你的 Cursor 版本是不是够新这个功能迭代很快老版本确实没有。进入 SubAgent 模式后界面布局和普通对话有明显的区别左侧是家主对话或者叫调度窗口右侧可以展开一个子任务面板里面会列出当前已下发、执行中、已完成的子代理任务。每个子任务都带自己的状态标识比如排队中、运行中、已完成、失败点开任意一个子任务可以看到它独立的上下文、用到的文件和最终结果。这个界面设计本身就是答案SubAgent 不是把任务混在一个对话流里而是每个子任务有自己独立的小环境。我的建议是先把界面结构摸熟再开始配置任务。不然下发了一堆并行任务都不知道去哪看结果体验会非常混乱。2.2 第一次下发一个最小可用的操作流程我们直接走一遍最简单的流程目标是让一个子代理帮我们生成某个模块的单元测试。第一步切换到 SubAgent 模式。确保当前工作区打开的是你的项目根目录因为子代理默认的工作范围就是当前项目。第二步在下发任务之前先明确你要拆什么。比如我打开一个工具类文件utils/format.ts里面有一堆时间格式化、数字格式化的函数我希望子代理只针对这个文件生成测试。第三步填写子任务描述。我一般是这样写的“你是这个项目的测试工程师。请阅读utils/format.ts中的所有函数为每个函数生成 Vitest 单元测试覆盖正常输入、边界输入和异常输入三类情况。测试代码放到tests/unit/format.test.ts。只做这一个文件不要改动其他文件。”注意这段描述里的几个关键信息——角色、范围、输出位置、约束。角色让子代理知道用什么视角干活范围防止它越界乱改成别的文件输出位置减少你事后整理的工作量约束是告诉它哪些事情绝对别做。一条合格的任务描述比你在主对话里长篇大论更有用。第四步确认配置后下发。如果同时下发多个子任务它们并行执行每个子任务都有独立的进度。等全部子任务状态变成“已完成”再回主对话统一检查结果。2.3 结果回收时的两个关键动作子代理跑完把结果 Applied 到项目里之前我强烈建议你先做两件事。第一件事临时把目标文件加入版本控制或者做个快照。因为 SubAgent 并行执行时多个任务的结果会被合并到主对话的变更集里一旦 Apply改动是批量的这时候想后悔就麻烦了。我一般用 Git 先 commit 一次或者在 Cursor 的变更列表里逐个审查文件确认没有意外改动再合并。第二件事逐个检查子任务报告。每个子任务完成时会附带它改了什么、为什么这么改、还有哪些遗留风险的说明。这些说明是子代理自己的“工作汇报”别跳过。很多时候问题就藏在“遗留风险”这一段比如“这个函数有副作用测试可能需要 mock 某个全局依赖”这种提示能帮你避免上线后炸雷。提示子任务的 Apply/Reject 是可以单独操作的不一定非要全盘接受。并行任务里如果有一个结果你不满意单独 Reject 它不影响其他子任务的合并。这一点很实用后面排查问题也会用到。3. 配置详解模型、知识库、系统提示词怎么组合才合理3.1 模型选择不是所有任务都该用最强的SubAgent 允许每个子任务单独选择模型这是很多人忽略的配置项。我的原则是“任务难度和模型能力匹配”不为所有子任务一律选最强模型。比如做代码查询、定位问题、生成注释这类轻量任务用普通的中档模型就够了速度快、成本低结果质量也不会差。而涉及跨文件重构、算法实现、复杂业务逻辑理解的重活才值得把更强的模型放上去。这里有个经验可以分享我习惯把需要创新设计的工作分配给强模型把机械性执行的工作分配给普通模型。举个例子重构一个数据访问层我会让强模型负责设计新的仓储接口让普通模型负责把旧调用点逐一替换成新接口。前者需要理解整个项目的架构风格后者只是按规则改字和调用方式。这样的组合整体速度比全上强模型快质量也不差。3.2 知识库绑定让子代理站在“懂项目”的基础上干活SubAgent 比普通 Chat 强的一点是它可以在下发任务时绑定特定文件、目录或整个代码库作为参考上下文。这个能力用好了子代理就不是“瞎猜项目结构”的临时工而是“看过你项目规范的正式员工”。具体操作上在子任务描述里可以用符号引用文件或目录也可以指定让它读取某个说明文档。我的习惯是三类东西必带一是任务涉及的核心文件二是项目里的编码规范或贡献指南文档三是与你这次改动相关的既有模式文件比如一个已实现好的相似模块。为什么要带“既有模式文件”因为大模型非常擅长模仿。你给它看一个现成的模块是怎么写的——目录结构、命名风格、导出方式、注释习惯——它写出来的新代码就会自动贴合这个风格而不是重新发明一套。我踩过这方面的坑有一次没给参考文件子代理生成的代码风格和项目完全不一致我花在调整上的时间比让它重写还久。3.3 系统提示词设计三句话讲清边界SubAgent 的配置里通常会留一个系统提示词字段相当于给子代理设定的“岗位说明书”。很多人的做法是留空或者写一句“你是一个专业的程序员”这其实浪费了能力。我自己的模板是三层结构第一层角色定位。一句话说清楚它是什么角色。比如“你是资深前端工程师负责实现 UI 组件库”。第二层工作边界。写清楚它只能动哪些文件、不能动哪些文件、不能执行哪些操作。比如“你只能修改src/components/下的文件禁止运行安装命令禁止改动配置文件”。第三层输出要求。明确输出形式。比如“完成代码修改后用列表说明改动的文件、改了什么、为什么这么改、有什么风险”。这套模板特别适合多人协作场景也适合任务拆得很细的并行场景。边界清晰了子代理就不会“自由发挥”你的审查压力会小很多。我见过有人把系统提示词写成一个很长的规章制度反而效果不好——提示词过长会挤占有效的指令空间子代理执行起来反而会犹豫。三到五句话说清楚角色、范围和输出要求足够。4. 实战场景三类我用 SubAgent 验证过的任务拆法4.1 多文件并行重构把大手术拆成小切口先说我用得最多的场景跨模块重构。一个典型的例子是把项目里所有直接操作原始 SQL 的地方全部迁移到一个新增的数据访问层上。这类任务在单 Agent 模式下很容易翻车因为改到一半Agent 会把上下文焦点放在正在改的文件上忽略之前看过的调用方约束。用 SubAgent 怎么拆我的做法是主对话先梳理出所有涉及 SQL 调用的文件清单按模块分成几组。比如用户模块一组、订单模块一组、支付模块一组然后下发三个子代理每个负责一组。每个子代理的命令里都注明数据访问层的方法签名先去读src/data/schema.ts以那里的定义为准只允许修改指定分组的文件遇到不确定的业务逻辑先跳过并在结果报告里标注不要自行假设。这样拆完三个子代理并行改三块代码大概几分钟就能全部完成。最让我满意的是“遇到不确定的逻辑先跳过”这个约束——之前单 Agent 经常自作主张乱改业务逻辑拆给子代理并加了边界之后这类问题少了很多。最后要做的事就是汇总子代理的报告把标出来的不确定项交给人工确认。4.2 自动化 Code Review省钱省时的并行审阅流程SubAgent 做代码审查是我个人最推荐的低风险用法因为它不需要真的往项目里写代码跑错了损失也小。我的操作是把待审查的代码按模块或文件拆开每个子代理分配一个清晰的审查指令要求它分别从代码正确性、性能隐患、安全漏洞、可维护性四个维度给出意见并且每条意见必须标出行号和严重级别。最后把并行产出的结果汇总按严重级别排序形成一份审查报告。这个流程我在一个大约两万行代码的中型项目上实测过一次性拆了五个子代理并行审查十几分钟就出完了全部结果。单 Agent 模式至少需要两倍时间而且越到后面越容易忘记前面文件的内容。有个细节值得注意审查任务一定要限制子代理“只读不写”。如果子代理在审查过程中顺手“优化”了几个文件那就不是审查了是乱改。我的提示词里会加一句强约束“你只能输出审查意见绝对不要修改任何代码文件。”这句话简单有效能挡住绝大部分控制不住手的问题。4.3 测试用例批量生成以量取胜的并行优势测试生成是并行收益最大的场景因为各个测试文件之间天然独立没有任何状态共享。实战过的一个项目是内部管理系统有好几个核心模块的接口测试覆盖率一直上不去。我按模块把任务拆成多个子代理每个子代理负责一个模块的接口测试给它指定对应的 API 定义文件、Mock 规则、历史测试样例。子代理各自独立生成测试代码并写入独立的测试文件互不干扰。效果非常直接一次并行生成了几百条测试用例覆盖正常流程、参数边界、鉴权失败、接口超时等场景。之前靠手写或者靠单个 Agent 生成这种量级至少要大半天SubAgent 把时间压缩到了半小时以内。我做完之后的复查发现子代理生成的测试代码质量和风格差异挺明显。有的子代理生成的测试注释非常详细有的就只写断言不多解释。这个问题靠什么解决回到 3.3 节说的系统提示词把输出格式要求写清楚风格差异就会大幅缩小。如果你发现并行产出的测试风格不统一优先检查是不是系统提示词里的输出规范写得不够细而不是逐个文件去改。5. 常见问题与排查技巧实录5.1 子任务一直“排队中”不执行并行任务一多明显能感觉到部分任务排队等待。这个通常是资源限制导致的模型调用有并发上限或者是订阅套餐里的并行额度不够用。我的排查顺序是先看其他子任务是不是都在跑如果已经有任务占用额度排队就是正常的等一会儿即可。如果所有任务都停在排队状态那就不是额度问题大概率是你下发的任务配置有问题比如同时绑定了大量文件导致上下文准备超时或者引用了不存在的目录子代理卡在执行前校验。遇到这种情况取消任务重新下发并减少引用范围。我习惯一条任务最多绑定三五个核心文件超过这个数的就再拆分。子代理需要的上下文越多准备时间越长排队风险也越高。5.2 结果和预期差很多先查描述再查上下文子代理跑出来的代码完全不是你要的东西这事我碰到过不止一次。这时候先别急着怪工具按顺序排查两个地方。第一个是任务描述。子代理对模糊表述的解读能力其实很强但也意味着它会按自己的理解去脑补。你写“优化这个模块的性能”它可能去改数据结构也可能去加缓存也可能去调整算法。问题的根源是“性能”太宽泛了。改成“将列表查询从 O(n²) 的双重遍历改为一次遍历并补充基准测试验证”结果就完全不一样。第二个是上下文引用。检查你绑定的文件里面是不是有旧版本的实现文件。有一次我给子代理绑定了包含废弃接口的文件它照着废弃接口写了一圈新代码全部白干。查上下文引用把废弃文件移除重新下发就正常了。5.3 并行任务互相干扰变更冲突怎么处理并行任务最大的坑是两个子代理同时改了同一个文件的相邻区域合并时发生冲突。我在 2.3 节里说过要先提交一次快照就是为了应对这种情况。处理思路是先逐个 Reject 冲突的变更然后手动合并或者将公共文件的修改任务合并成一个子代理执行。拆任务的时候最好明确“文件所有权”就是每个子代理独享一组文件不要有交叉。如果确实要多个子代理都碰同一个文件就在描述里限定它们各自修改的区域。还有一个偏经验的做法涉及公共依赖文件的修改永远在主对话里自己完成不要让子代理做。例如修改一个被很多模块引用的数据类型定义如果子代理改动它而你没盯住最后的冲突排查会非常痛苦。5.4 成本涨得太快怎么控制并行消耗SubAgent 并行跑起来消耗的速度确实让人肉疼。我刚开始用的那段时间某个月消耗翻了好几倍。现在我会控制几个维度。一是限制并行的任务数量同时最多四个左右再多任务的收益增长就开始下降纯属烧钱。二是轻量任务不用强模型这个前面说过模型级别直接决定成本。三是设置每个子任务的最大轮次或者输出长度限制防止子代理在一个任务上无限纠结、反复修改。四是及时关闭不再需要的子任务执行完的会话别一直挂着保持会话卡片在后台也很耗资源。注意SubAgent 的计费是以底层模型调用和后端资源占用综合计算的不是单纯按“生成的字数”计费。所以“等待时间”也是成本。一个子任务反复重试一个小时比你重发三次正常任务都贵。控制执行时间是控制成本的核心。6. 最后说点我的体会SubAgent 给我最大的感受不是“并行快”而是“边界清晰”。单 Agent 模式下一个代理既当架构师又当执行者上下文切换频繁出错率自然高。拆成 SubAgent 之后每个代理只盯着自己那一小块反而把质量提上来了。我现在的用法已经变成了一种习惯接到大任务先坐在主对话前拆任务、写描述、定边界然后一次性下发干完再逐个验收。这套流程跑顺之后我个人的代码产出效率大概提升了一半还多尤其是那些需要多文件联动、重复性很强的工作基本都交出去了。最后再分享一个小技巧把你自己常用的 SubAgent 任务模板保存下来无论是任务描述模板还是系统提示词模板都值得在本地留一份。下次接到类似任务的时候直接复制改一下就能用不用每次重新构思边界条件。我现在每次开新项目的第一天就会顺手建一份模板库省下的时间远比你想象的多。