企业官网建设流程全解析

接手一个带着小程序前端、管理后台、简历解析服务三类代码搅在同一个仓库里的全栈项目时，我在 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 之间的等待时间、交接信息的损耗、互相纠错带来的返工，都会把收益吃掉。

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 先输出"我对任务的理解和我打算怎么拆"，你确认过后再放行，这一条能帮你避免大量在错误方向上的执行。