前五篇聊了 WorkBuddy 的基础操作、Skill 编写、记忆管理和常见调度方式这篇集中写多 Agent。说老实话我并不是一开始就看好多 Agent真正把 WorkBuddy 切换到多 Agent 模式是被一个内部项目逼出来的。当时要做的是一个带后台管理的工具站前端、后端、数据结构、文档四块工作全压在一个 Agent 上跑了三天对话一长就开始掉链子经常出现前面定好的接口约定到后面完全忘记的情况。后来冷静复盘才发现问题不在模型能力而在上下文管理方式。于是我把整个流程拆成多个 Agent 协作用 WorkBuddy 搭了一个“四人小团队”效果完全不一样。这篇文章会把“为什么单 Agent 容易崩、多 Agent 角色怎么设计、实战如何编排、跑起来有哪些坑、什么时候该切回单 Agent”这几个问题一次讲透。适合已经过了新手期、正在用 WorkBuddy 跑真实项目的人。1. 为什么单 Agent 跑不动复杂任务我的切机过程1.1 上下文窗口是稀缺资源不是无限仓库很多人在单 Agent 模式下遇到效果变差第一反应是“模型不行”或者“提示词不够好”我一开始也这么想直到把日志翻出来才意识到真正的问题是上下文窗口被垃圾占满了。WorkBuddy 的单 Agent 会话里所有需求讨论、技术方案、多轮代码、报错信息都会一直留在上下文中。模型处理长上下文时会不断做注意力分配每一轮都要扫描一遍全部历史早期被稀释的细节就越容易被忽略。你可以把它想象成一个会议室里十个人同时讲话主持人刚开始还能记住谁说过什么聊到后半场基本只记得最近几句话。我印象最深的一次做一个带后台的博客系统一开始明确说了“Cookie 统一走 HttpOnly”但经过三小时的交互、改了七个文件、贴了两次报错日志之后我让 Agent 继续加权限模块它直接把 Cookie 改成了可被脚本读取的模式。不是它不懂而是那条早期约束在所有历史里已经变得不显眼了。1.2 任务链越长单 Agent 的状态管理越脆弱另一个问题是任务链。多步骤任务天然有状态先做需求分析再出技术方案然后编码、测试、回归、写文档。单 Agent 跑完一个环节又跑下一个环节中间的状态全靠对话上下文去记一旦某个环节被打断后面所有环节都会受影响。更重要的是角色深度。一个 Agent 在同一套上下文中既当项目经理又当前端又当后端又当测试评审本质上是在不停切换思考方式。人的团队里没人会这样干因为角色切换是有损耗的。模型也一样做需求分析时要发散、要补全边界写代码时要聚焦实现细节做评审时要挑毛病。这几种思维模式互相干扰结果就是每一样都做不深。我当时做了一个很粗糙的实验同一个需求分别用单 Agent 和多 Agent 跑。单 Agent 花了两小时中间出错三次多 Agent 用了一小时四十分钟中间出错一次。这个对比不够严谨但足以说服我。多 Agent 不是把事情变复杂而是把一个超长任务切成几个短任务每个 Agent 只保留局部上下文反而更接近模型擅长的工作方式。1.3 多 Agent 的本质不靠记忆靠交接我后来理解了一件事多 Agent 真正解决的是“记忆交接”而不是“人越多越好”。单 Agent 里信息靠模型上下文去追多 Agent 里信息靠结构化文件、目录、协议去传递。这就像团队里做交接我不会靠嘴说而是写文档、列清单、留记录后面接手的人只看需要看的部分。所以判断一个任务要不要上多 Agent最核心的指标不是“它复不复杂”而是“它的中间状态是不是需要被反复交接”。如果从头到尾一个人能盯完单 Agent 就够如果像专业团队一样需要不同角色在不同阶段接手多 Agent 才有真正的价值。2. WorkBuddy 多 Agent 工作台的角色设计与 Skill 配置2.1 主 Agent 与子 Agent 的分工模型WorkBuddy 里的多 Agent 编排我习惯按“项目制”来理解一个主 Agent 当项目经理下面挂若干个专家子 Agent。主 Agent 不亲自写业务代码它的职责是接收需求、拆解任务、分派给合适的子 Agent、在结果冲突时做裁决、最后汇总产出。子 Agent 的职责是把自己负责的那一块做到位输出规范的交接物。这个分工的关键是克制。很多人在搭多 Agent 时最容易犯的错就是让主 Agent 既当协调者又顺手干点活。一旦主 Agent 开始写代码它就会失去对全局任务状态的注意力拆解和调度很快就会乱。我在 WorkBuddy 里给主 Agent 的 Skill 开头就写了一句你负责协调不负责执行你只能通过分派和汇总来推进任务。下面是我目前比较常用的角色清单供参考角色核心职责建议 Skill上下文关注重点主 Agent协调者需求拆解、分派、冲突裁决、汇总任务编排 Skill全局任务清单与状态需求分析 Agent产出需求文档PRD、验收标准文档生成 Skill业务背景与边界约束前端 Agent页面结构与交互前端开发 Skill设计稿、接口约定后端 Agent接口与数据处理后端开发 Skill数据结构、鉴权规则评审 Agent代码审查与回归验证代码审查 Skill改动清单、测试用例刚上手的人我建议先按这个结构来不要一开始就搞十几个角色。角色越多协调成本越高后面你会发现自己整天在处理 Agent 之间的吵架而不是在推进任务。2.2 Skill 的真实作用把岗位说明书写进能力包Skill 在单 Agent 模式下可能只是“增强某个方向的能力”但在多 Agent 模式下它是角色的岗位说明书和工作纪律。一个 Skill 里除了告诉模型领域知识和工具用法还必须包含职责边界、输入来源、输出格式、禁区和交接规则。我举个例子。给前端 Agent 配的 Skill我开头会写清楚“你只负责 web/ 目录下的页面与交互修改 server/ 目录属于越权遇到需要后端配合的情况你写在交接单里不要自己去改接口实现”。这些约束写在 Skill 里比每次对话单独交代可靠得多因为 Skill 是和角色绑定的Agent 每次启动加载的都是同一套纪律。输出格式也很重要。多 Agent 协作时子 Agent 的输出往往不是给用户看的而是给下一个 Agent 用的。这时候没有统一格式后续 Agent 解析起来就会很痛苦。我会让每个子 Agent 的输出都包含四块任务编号、改动文件清单、验证结果、遗留风险这个结构可以沉淀成一个交接单模板用 Markdown 放在项目 docs/ 目录里所有子 Agent 共用。2.3 记忆与缓存换账号、换目录的底层逻辑WorkBuddy 里记忆大致分三层账号级记忆全局偏好、项目级记忆当前项目上下文、Agent 级记忆单个角色自己的对话历史和积累。缓存目录承载 Skill 数据、临时输出和部分知识库内容。理解这三层才不会在换账号、换目录时把记忆弄丢。先聊更改缓存目录。不同版本的入口不一样桌面版通常在“设置-存储”里可以指定路径命令行版可以通过环境变量指定缓存目录。改目录前有三件事必须做停掉正在运行的会话、备份原目录、确认新目录有足够空间。直接把还在写文件的目录挪走轻则丢失几段会话记录重则导致 Skill 加载异常。再聊换账号后的记忆迁移。很多人换账号后抱怨“Agent 变傻了”其实就是项目目录下的记忆文件没有跟着走。在本地目录结构里账号级记忆一般存在用户主目录项目级记忆和 Agent 级记忆通常和项目路径绑定。迁移时不要只拷对话记录要把项目目录下与记忆、知识库、Skill 配置相关的文件夹完整拷贝到新账号对应的项目路径下再检查导入后路径是否正确。这里有一个容易踩的坑如果你用的是云端数据与本地目录分离的版本本地缓存目录和账号是绑定的拷贝错地方等于没拷。我现在的习惯是每完成一个阶段就手动把项目的整个 WorkBuddy 工作目录压缩备份一份既解决了换账号迁移的问题也相当于给项目状态做了版本控制。3. 实战用 WorkBuddy 多 Agent 跑通一个周报自动收集工具3.1 为什么用这个项目当示例周报自动收集工具是我用来演示多 Agent 流程的一个标准样例。它技术栈常见简单表单页、后端接口、数据存储、汇总逻辑、使用文档不算大但任务链完整前端、后端、数据结构、文档写作四种角色都涉及。这个规模是测试多 Agent 编排的理想复杂度太小看不出协作价值太大又容易在演示时翻车。具体需求是做一个内部页面员工填写本周完成事项、阻塞问题、明日计划三项内容后端接收提交后写入本地数据文件每周五生成一份汇总报告按部门归类输出。整体就这三个功能点但足够看出协作流程。3.2 先让协调 Agent 开“需求评审会”搭多 Agent 工作台最容易犯的错是一上来就派活写代码。我的习惯是让主 Agent 先走一轮“需求评审会”也就是先让需求分析 Agent 产出 PRD确认验收标准再开始分工。很多项目做偏方向问题都出在需求没有提前收敛。给主 Agent 的初始化指令可以这样写你是一个项目协调者。下面这个需求先不要直接写代码。 第一步调用需求分析Agent产出PRD文档内容必须包含 功能清单、数据字段定义、验收标准。 第二步PRD确认后将任务分派给前端Agent和后端Agent。 你只负责跟踪与汇总不亲自写业务代码。这样写的原因很直接主 Agent 如果跳过 PRD 直接分派前端 Agent 和后端 Agent 各按各的理解做最后一定对不上。先让需求分析 Agent 把边界定清楚后续每个角色读同一份 PRD协作才有一个准确参照。3.3 子 Agent 的交接协议与目录授权子 Agent 的分派指令要明确三件事输入什么、输出什么、边界在哪。比如前端 Agent 的指令你负责 web/ 目录下的页面与交互开发。 禁止修改 server/ 目录下的任何文件。 你的输入来自 tasks/req.mdPRD摘要 输出写到 tasks/frontend_done.md内容包括 改动文件清单、运行方式、需要后端配合的事项。后端 Agent 的指令类似只是目录换成 server/ 和 data/。这里有一个非常关键的动作每个子 Agent 只拿到它需要的目录授权。前端 Agent 不需要读 server/config.py后端 Agent 也不需要关心页面样式。最小权限原则在多 Agent 场景下比单 Agent 重要得多因为越权操作是协作混乱的第一来源。3.4 从配置到跑通一份实操顺序清单我在 WorkBuddy 里的搭建顺序大概是这样新建主 Agent绑定协调 Skill准备初始化指令。新建需求分析 Agent、前端 Agent、后端 Agent、评审 Agent。创建项目目录结构tasks/、docs/、web/、server/、data/。把原始需求写成 tasks/req.md作为唯一需求入口。在主 Agent 会话里下发初始化指令启动协作流程。评审 Agent 对照 PRD 验收标准逐项检查代码输出通过/不通过清单。主 Agent 汇总所有子 Agent 产出形成最终交付说明。第一次跑的时候评审 Agent 查出了一个非常典型的问题前端 Agent 通过表单提交的字段名为 project_date后端 Agent 读的字段名却是 date两边都没有对错但就是接不上。这个问题的价值在于它证明了独立评审机制的必要性写的人容易按自己的既定思路往下走看的人反而能发现不一致。3.5 协作流转尽量用数据驱动别靠自然语言喊话多 Agent 协作里最有效的交接方式不是 Agent 之间通过自然语言互相喊话而是通过共享目录里的文件状态来流转。需求分析 Agent 把 PRD 写到 docs/prd.md前端 Agent 和后端 Agent 去读这个文件前端 Agent 做完后写 tasks/frontend_done.md评审 Agent 读取 PRD 和两个 done 文件输出 review.md主 Agent 根据 review.md 决定返工还是收尾。这份文档流转设计的核心是让数据在固定位置出现、被固定角色消费。主 Agent 不需要每次都把任务内容复述一遍它只需要记录“哪个文件由谁负责更新”协作效率会高很多。4. 多 Agent 跑起来之后三类故障排查链路4.1 故障一Agent 越权改文件根因是目录授权太宽现象前端 Agent 修改了 server/config.py导致后端接口在联调时直接崩掉。排查过程并不复杂先看前端 Agent 的完整会话日志确认它打开过哪些文件、是什么指令引导它打开了 server/config.py。我当时翻日志发现前端 Agent 之所以去改后端配置是因为我在分派指令里写了“参考后端配置确保接口能通”这句话。它理解为“需要改动配置”于是顺手改了。根因是双重的Skill 里没有声明边界分派指令里又有模糊表述。修复分两步。第一步在前端 Agent 的 Skill 中增加“只操作 web/ 目录不修改 server/ 目录”的硬性限制第二步把分派指令里的“参考后端配置”改为“接口约定见 docs/api.md以该文件为准”。改完后再跑一遍这个问题再没出现过。预防措施就是最小目录权限。只给子 Agent 它负责的子目录不用的目录不给不要让 Agent 拥有整个项目根目录的读写权。越权这件事靠 Agent 自觉是管不住的只能靠权限设计。4.2 故障二两个 Agent 写同一个文件后写的覆盖先写的现象前端 Agent 和后端 Agent 同时修改了项目根目录的 README.md最终版本只剩后端 Agent 写的内容前端说明全部丢失。排查时我先看了文件修改时间两个 Agent 的写入时间只差几十秒说明是并行任务导致的文件级冲突。根因是公共文件没有明确的归属权。修复方式有两种一是把 README.md 这类公共文件的编辑权指定给某一个 Agent比如文档 Agent其他 Agent 只读不写二是需要多角色共同维护的文件在任务描述里明确声明“此文件已被 xx Agent 占用其他 Agent 不要写入”。后来我把所有公共文件的归属清单放在了 tasks/ownership.md并让主 Agent 在编排时按这份清单做读写判断。之后这类覆盖问题基本绝迹。4.3 故障三评审 Agent 和开发 Agent 来回纠缠形成死循环现象评审 Agent 提出修改意见开发 Agent 改完评审 Agent 再审又提出新意见再来一轮。最严重的一次前端模块在评审 Agent 和前端 Agent 之间反复了七轮两个 Agent 互相都很有礼貌地认为对方应该再调整一下实际进度完全停滞。排查时看协作记录发现付费的根因是初始编排里没有设置迭代上限。修复方式是给主 Agent 加一条裁决规则如果某个任务已经返工超过两轮停止自动往返。 第三轮由主Agent收集双方意见整理成人工决策清单 等待人工介入处理。这条规则非常有效因为它把兜底责任交回了人。多 Agent 再自动化关键节点上依然需要人工裁决尤其是设计和实现之间有分歧的时候。多 Agent 的故障多数不是模型跑飞而是边界和终止条件没定清楚。把边界写进 Skill把终止条件写进编排能解决大半问题。5. 什么场景该用多 Agent、什么场景该切回单 Agent5.1 用一张表判断单 Agent 还是多 Agent我经常被问“什么任务适合多 Agent”下面这张表是我自己的判断标准维度用单 Agent用多 Agent任务长度几个文件、一次对话能完成跨模块多阶段需要交接角色复杂度一个人能覆盖需要设计、开发、测试、文档多个专业角色并行需求低多个独立任务块可以同时进行评审需求低需要独立评审角色把关质量上下文压力小容易上下文爆炸成本敏感高可以接受更高的调用消耗简单脚本、一次性问答、短对话场景别用多 Agent。多 Agent 最适合的是流程型项目也就是有开始、有结束、中间有清晰阶段边界的工程任务。5.2 WorkBuddy、Cursor、CodeBuddy 三者思路的差异把 WorkBuddy 与经常被同时提到的 Cursor、CodeBuddy 放在一起看会更清楚自己的选择。Cursor 本质上是编程编辑器强项是在代码现场做补全、局部重写、解释报错它更适合“写代码这个动作本身”。如果你只是想在编辑器里高效改代码Cursor 是贴身协作者。CodeBuddy 的定位更偏向代码生成和代码解释适合把零散需求快速变成代码片段或算法实现对单点问题很高效。WorkBuddy 更像“工作台/指挥官”它的核心能力是调度多个 Agent、管理 Skill 和知识库、组织跨阶段流程。它不是用来替代编程编辑器的而是把多个环节串成一个工作流。我现在的用法是组合在 Cursor 里写代码和局部重构把需要跨模块协调的任务交给 WorkBuddy 多 Agent 编排遇到想要快速生成的算法片段用 CodeBuddy 处理。这三者不是竞争关系而是工序上的搭配。6. 多 Agent 模式下几个让我改变习惯的细节6.1 输出规范能显著减少“AI 味”让每个子 Agent 按固定结构输出结论做了什么、发现了什么问题→ 依据引用文件与行号或数据来源→ 改动清单 → 待办。最后让汇总 Agent 再做一轮“去模板词”检查把“首先、其次、总之、需要注意的是”这类词过滤掉对“通过…可以…”这类句式做重写。实测下来生成的方案和文档读起来自然很多这也是所有角色共用同一套输出模板的最大好处。6.2 成本与规模平衡3 到 5 个角色是甜点区刚上手的人总想把角色拉满我不建议。主 Agent 加需求分析、前端、后端、评审这 5 个角色就能覆盖大部分中大型项目。如果跑科研场景把前端后端替换成文献综述 Agent 和实验方法 Agent结构保持不变。角色再多协调开销会吃掉收益而且冲突概率指数级上升。6.3 我的几点体会第一个体会多 Agent 不是模型变聪明了而是把任务加工成了模型更擅长处理的小块。每个子 Agent 的上下文更干净、边界更清晰效果自然会稳定。第二个体会给 Agent 限权比给 Agent 赋能更关键。先说不能做什么再说做什么这个顺序不要反。边界清楚协作才稳。第三个体会定期导出整理记忆目录。既解决换账号迁移的问题也相当于给项目状态做了版本控制这个习惯让我少丢了很多重要上下文。多 Agent 这套玩法本质上是在用工程化的方式管理模型能力。WorkBuddy 提供了角色、Skill、记忆与编排这些基础件怎么组织成一支高效的团队还是得靠你在真实项目里反复调整边界和协议。