接手一个带着小程序前端、管理后台、简历解析服务三类代码搅在同一个仓库里的全栈项目时我在 WorkBuddy 里第一次把任务拆给了三个 Agent 并行处理。起初只是想省时间后来发现多 Agent 模式真正解决的不是快而是乱。这篇实战记录是《WorkBuddy 实战蓝皮书》系列的第六篇重点拆解多 Agent 的角色划分、上下文隔离和任务编排把我踩过的坑和验证过的配置方式一并写出来。适合已经会用 WorkBuddy 做单 Agent 任务、但面对复杂项目时总觉得上下文不够用的人参考。1. 单 Agent 撑不住时别急着加模型先拆角色我最初用 WorkBuddy 单 Agent 模式一路往下推前两周很顺让它写接口、补页面、修样式基本一句话一个任务。到了第三周开始失控让它改简历解析服务里的 PDF 提取逻辑它顺手贴心地重构了管理后台的鉴权代码改完跑测试才发现两个模块互相踩了对方的变量。把上下文拉回历史会话一看这个 Agent 记忆里已经塞了太多东西——仓库结构、旧需求、临时调试信息全混在一起它分不清哪些是当前任务的约束哪些只是早期探索的边角料。那段时间我反复在同一个 Agent 里来回拉扯只改这一段别动其他文件刚才说的不算。每次纠正都会再消耗一部分上下文窗口模型越来越忘事到后面它连自己上午刚给的接口签名都记不住。我意识到问题不在模型能力而在任务形态——一个 Agent 同时扮演架构师、代码工人、测试员三四个角色所有上下文又全堆在同一会话里不乱才怪。拆完多 Agent 之后这类问题开始明显减少因为每个 Agent 只需要关心自己的那一段。1.1 多 Agent 的适用边界拆之前先判断值不值得拆。凡是任务链条长、涉及多个代码模块、且每步需要不同专业视角的工作都值得拆成多 Agent。最典型的特征是中途需要换视角——比如先设计再编码先实现再审查。换视角本身就会产生大量上下文切换成本单 Agent 会把成本全部摊在一个记忆力有限的会话里。我后来给自己做了一张排查表每次接任务先过一遍判断维度适合多 Agent不适合多 Agent任务链长度超过三四个环节每环节依赖前环节输出一条命令能描述完的小任务涉及模块数两个以上模块改动互相有影响单个文件内的局部修改专业视角需要设计、编码、测试等多角色视角单一明确的机械性操作变更频率需求经常调整需要反复评审一次性静态修改用这个表筛过之后我定下原则五句话能说清的改动绝不拆 Agent只有任务明确被拆成规划—实现—审查三段时才上多 Agent。盲目拆分的代价比想象中大因为 Agent 之间的等待时间、交接信息的损耗、互相纠错带来的返工都会把收益吃掉。1.2 拆几个 Agent 最合适拆几个这个问题我试出来的经验值是 2 到 4 个最稳。少于 2 个等于没拆多于 4 个编排成本开始吞噬收益Agent 之间互相等待和反复确认会很拖节奏。我最常用的是三角色配置规划者Planner负责理解需求、拆解任务、定义接口契约和验收标准。它不写实现代码只输出方案。执行者Coder负责按规划者的契约写代码、改文件。它不重新设计只负责落地。审查者Reviewer负责检查执行者的改动是否满足契约跑测试挑问题并分级反馈。三角色各管一段上下文范围内的事都能处理得比较干净而且任一段出问题定位起来非常快。我在给 Agent 写角色定义时还发现一个关键点职责必须写边界而不是只写目标。光说审查者检查代码质量没用模型会把风格问题、性能问题、安全问题全搅进来然后和规划者吵起来。我后来明确写审查者只对是否满足规划者给定的接口契约和是否破坏现有测试负责。边界越窄Agent 之间的一致性越高。2. WorkBuddy 多 Agent 协作背后的三个机制多 Agent 不是几个面板同时在后台瞎跑它背后有一套协作机制。搞清楚这三件事配置的时候心里才有底。2.1 角色即上下文边界WorkBuddy 里的角色不只是人设本质上是一个独立的上下文容器。每个 Agent 有自己的系统提示、可用工具、甚至独立的缓存目录。这意味着我可以在规划者里放整个项目的架构说明在执行者里只放当前要改的模块结构在审查者里放测试命令和契约清单——三者各看各的资料不会互相污染。这个设计最直接的好处是执行者不会被架构文档里的大量背景信息带偏。我对比过同一需求在单 Agent 和分离角色模式下的表现分离模式下改动范围明显收敛。出问题时定位也更快因为你知道怪脾气是哪个 Agent 的上下文造成的直接只调它就行不用把整条链路都翻一遍。但角色隔离也有代价隔离太彻底后续 Agent 会缺乏必要前置信息。比如执行者只知道接口契约却不知道这个模块的历史包袱老接口不能破坏、旧数据要兼容就容易写出漂亮但无法落地的实现。所以边界要隔离的是过程信息而不是关键约束。2.2 任务流转会话级交接第二个机制是任务流转。WorkBuddy 多 Agent 本质上是会话级交接——上一个 Agent 的输出经过处理后作为一个新会话的输入注入给下一个 Agent。这里的处理很关键因为原始对话里常夹带大量推导过程、中间尝试、语气词、失败日志直接全丢给下一个 Agent等于把污染也搬了过去。我自己习惯在交接处加一个结构化交付物约定。规划者的输出必须是任务清单加接口契约不允许自由散文执行者的输出必须是变更文件列表和关键代码片段审查者的输出必须是测试结果和问题分级。结构一固定交接就稳了。这条算是我在多 Agent 上收益最大的一条习惯后面第 3 节会展开讲具体怎么做。2.3 共享记忆与会话记忆的分级第三个机制是记忆分级。WorkBuddy 里的记忆我分成两类全局记忆和会话记忆。全局记忆是多个 Agent 共享的项目级背景比如技术栈、目录约定、命名规范、部署流程会话记忆则是某个 Agent 自己的任务上下文。配置要点是全局记忆要短只放规则不放过程会话记忆放过程但任务一结束就要清理。我遇到过的最典型翻车是把一次排错的完整过程写进了全局记忆结果所有 Agent 都以为那是项目规范后续生成的代码风格全被那一次排错的临时方案带偏。后来我把全局记忆精简成一份项目事实清单每一条都是当前仍然有效的客观约束跟具体某次任务无关。这样共享记忆才不会变成公共垃圾场。3. 实操搭一套规划—实现—审查三 Agent 工作流理论说多了容易飘直接上一套能跑的配置。下面是我在 WorkBuddy 里实测过多次的三 Agent 工作流完整搭建过程。3.1 定义三个 Agent 的职责边界我习惯先给每个 Agent 写角色说明书而不是直接在界面上点几个选项。下面是精简过的定义文本可以直接套用。规划者的角色定义你是规划者。你的任务是把用户需求拆解为可执行的实现清单。 你只输出以下内容 1. 目标描述不超过 3 句话 2. 任务清单按执行顺序排列每项带验收标准 3. 接口契约输入输出格式、边界条件、兼容性要求 4. 禁止事项明确列出本任务不允许改动的模块 你不写代码不讨论实现细节。 你输出的每一条内容都必须足够具体让执行者无需重新提问即可开工。执行者的角色定义你是执行者。你只做规划者任务清单里列出的事项。 你的工作方式是 1. 读取任务清单和接口契约 2. 按顺序实现每完成一项标记一项 3. 在输出中列出所有改动的文件路径和关键代码片段 4. 如果发现任务清单中的某项无法实现立即停止并说明原因 你不修改契约不扩大改动范围不做契约之外的顺手优化。审查者的角色定义你是审查者。你的职责是核对执行者的输出是否满足契约。 你只做三件事 1. 检查接口契约的每一项是否落实 2. 运行约定的测试命令并输出结果 3. 给出问题清单按【阻塞/非阻塞】分级 你不提风格建议不做代码重构不修改契约。这三份定义的共同点是每一条都约定了不做什么。多 Agent 之间的大部分冲突都源于某个 Agent 越界做了别人该做的事把边界写进角色说明书能直接砍掉一半问题。3.2 配置流转规则和交接产物角色建好后下一步是配置流转规则。WorkBuddy 里我把交接方式设成显式传递也就是前一个 Agent 的输出保存成项目文件后一个 Agent 通过指定路径读取而不是靠对话转述。具体操作是这样规划者完成任务后我把它的输出存成docs/tasks/current_plan.md。执行者一上线我先让它读取这个文件再对照清单开工。执行者完成后会把变更信息写进docs/tasks/change_log.md。审查者读取这两个文件后开始核对最后输出docs/tasks/review_report.md。引入文件作为交接中间层之后效果立竿见影。之前靠对话转述时后一个 Agent 经常把前一个 Agent 的犹豫过程当成结论比如执行者说这段代码可能有兼容性问题但暂时先这么写到审查者那里就变成了这段代码有兼容性问题需要改。中间加一层文件后规划者只把明确的结论写进去犹豫和猜测都留在对话里不参与交接。3.3 一次完整的执行过程复盘拿真实需求走一遍我当时要往管理后台加一个批量导出用户数据的功能涉及后端接口、前端页面、权限校验三块。规划者收到需求后大概跑了几分钟输出了一份任务清单其中有一个关键决策批量导出不直接走查询接口而是新建异步任务避免大查询把服务拖死。这个决策被写进了接口契约。执行者拿到清单后按顺序实现了后端异步任务、前端导出按钮、权限标识。过程中它发现权限校验字段在现有代码里没有预留但没有自己硬造而是在输出里标了一笔需要补充权限标识已有字段无法满足契约。审查者看到这一笔后把它列为阻塞项同时把其他已完成项的测试结果写进报告。问题被卡在权限标识没地方放这个点上。我回头改了需求在用户表加了一个字段再让执行者补上。整个过程没有出现执行者自作主张改表结构、或审查者纠缠代码风格的事。帮我省下最多时间的是把每步的产物边界钉死了——谁输出什么、下一个谁读什么完全照固定路径走人和 Agent 都轻松。4. 多 Agent 协作里最容易翻车的三个场景及排查链路配置跑顺之后日子不会一直太平。我在多 Agent 模式下碰到过几次比较经典的翻车这里把完整排查链路写出来遇到类似情况可以照着查。4.1 场景一后一个 Agent 被前一个 Agent 的错误带偏现象是执行者和审查者都做完了测试也跑了结果交付的功能和需求完全对不上。查下来发现源头在规划者——它定义接口契约时把导出格式为 CSV写成了导出格式为 JSON执行者和审查者都忠实执行了错误契约于是整条链路一本正经地做出了错东西。我做排查时先看了review_report.md没发现问题于是往前翻执行者的change_log.md发现执行者还专门写了一句按契约 JSON 格式实现导出。这时意识到要追到源头打开current_plan.md一看果然是契约本身就错了。根因是契约错误没有被任何环节拦截。规划者写完契约后直接进入执行阶段没有校验环节。我的修复方案是在流转规则里加了一步契约自检规划者输出契约后先自己读一遍模拟执行者视角检查契约是否完整、是否有歧义确认没问题再交接。这一步成本很低但拦截率很高。从那以后规划者写契约的严谨度明显提升因为它知道自己写的字会被执行者一字不差地照着做。4.2 场景二Agent 陷入无休止的自我纠错循环现象是审查者多次打回执行者的结果执行者改了再报审查者又打回来回四五轮双方在同一个问题上反复拉锯消耗了大量时间甚至可能绕过人类确认直接进入循环。第一次遇到时我以为审查者太严就下调了它的审查标准。结果下一批任务质量直接崩了放过了不少明显问题。后来仔细看了几轮对话记录才发现循环的触发点不是严格程度而是反馈不够具体。审查者最初的反馈是导出接口的并发处理有问题。执行者收到后不知道具体是哪一段代码、哪种并发场景只能凭猜测改改完审查者又说不对。循环的症结在于反馈不具备可操作性。修复方案是在审查者的角色定义里加了一条所有反馈必须附带上定位信息比如文件路径、函数名、复现步骤、失败日志片段。如果给不出这些就不允许打回。这条规则加上后循环出现频率降到了接近零因为大多数时候审查者写着写着就发现其实问题还没确认清楚主动降级为普通提示而非打回。4.3 场景三生成结果之间互相冲突现象是两个执行者并行处理互相关联的任务各自完成后合并代码时发现改了同一个文件甚至定义了同名函数测试直接编译失败。我的配置里曾经有两个执行者共同负责一个模块的不同子任务比如一个改导出功能一个改导入功能它们的代码都会碰到用户的模块。单看各自都能跑合到一起就冲突。查的时候我先看了change_log.md发现两个执行者都动了user_control.py这个文件而且都在文件顶部加了自己的工具函数。根因是我给两个执行者划的边界是基于功能而不是基于文件。功能边界在任务描述里看得很清晰但落到代码层面同一个文件被两边同时改Git 合并时就炸了。修复方案是把边界写成文件级明确每个执行者允许改动的文件路径列表属于同一文件的任务只分配给一个 Agent。调整之后冲突问题基本绝迹代价是任务分配时要多做一步文件归属梳理但比起合并地狱还是省心太多。5. 让多 Agent 长期稳定运作的几个习惯多 Agent 跑顺之后维护的功夫主要在平时几个习惯上。下面这几条是我踩过不少坑之后总结下来的。5.1 用结构化输出作为交接协议交接是重灾区但也是收益最明显的优化点。我现在给每个 Agent 的输出都定了固定格式规划者必须输出目标/任务清单/契约/禁止事项四段执行者必须输出变更文件/关键代码/未完成项三段审查者必须输出测试结果/阻塞项/非阻塞项三段。一开始会觉得这些格式限制很啰嗦Agent 的输出似乎更自由了才好。但实际跑起来结构化输出让后一个 Agent 的解析开销骤降它不用费劲从散文里猜重点直接按段读就行。更重要的是格式本身会倒逼流程完整——比如执行者输出未完成项这一栏时它就很难假装所有事都做完了。5.2 给关键 Agent 加只读视角有些 Agent 容易手痒明明任务是审查却忍不住改代码。我后来在 WorkBuddy 里把审查者设成只读权限它只能读取文件、运行测试命令没有写文件的权限。这个改动让审查者彻底断了边审边改的念头只能发现问题、记录问题把修改交还给执行者。单个 Agent 的权限边界越清楚多 Agent 的整体协作就越不容易乱。如果你用的工具支持细粒度权限强烈建议把写文件这个动作收敛到执行者一个角色上。5.3 定期清理 Agent 缓存与会话最后一条是维护关键。多 Agent 跑一段时间后每个 Agent 的会话都会积累大量中间内容执行者尤其明显——它每轮任务带来的临时调试代码、失败尝试、废弃方案都堆在会话记忆里。我不定期清的话最直接的感受是 Agent 响应越来越发散老是提一些和当前任务无关的旧线索。后来我养成一个习惯每个任务结项后手动清理执行者和审查者的会话缓存只保留规划者的契约文件和项目的最终交付文档。清理周期和任务周期对齐一次一清。刚开始觉得麻烦但对比清理前后的稳定度值回票价。多 Agent 模式真正改变的是任务拆解思维在 WorkBuddy 里用多 Agent 的这几个月我最大的体会是多 Agent 没有让我少动脑反而逼着我把任务拆得更细。以前单 Agent 时我一句话甩过去就能等结果看似省事实际上模型在替我做大量错误的决策。现在拆成规划、实现、审查三段我必须先想清楚契约是什么、边界在哪里、验收标准是什么Agent 只是把我想清楚的东西高效落地。如果你刚开始尝试多 Agent我建议别一上来就搞五六个角色的复杂编排先跑三角色把交接协议和文件清单做扎实观察几轮再逐步加角色。多 Agent 的收益不是线性叠加的角色越多编排成本涨得越快。把基础链路打磨顺比堆角色数量重要得多。最后再分享一个小技巧每次任务开场时让第一个 Agent 先输出我对任务的理解和我打算怎么拆你确认过后再放行这一条能帮你避免大量在错误方向上的执行。