大家平时用 WorkBuddy 搭工作台多半是从单个 Agent 开始的让它读资料、写代码、整文档一条链路跑到底。用久了你会发现单 Agent 就像一个人干三个人的活指令一复杂就开始东拉西扯回答质量明显下降。这时候就该上多 Agent 了。多 Agent 这个词听起来玄乎说白了就是把一个大任务拆成几个小任务让不同的 Agent 各管一段有人负责想方案有人负责写代码有人负责挑毛病最后再汇总成一个结果。WorkBuddy 在这块的设计思路和 Cursor、CodeBuddy 那套单 Agent 对话模式不一样它更强调“搭台子”你定义好几个 Agent 的角色、职责和协作方式然后丢一个复杂任务进去让它们自己分工推进。这篇我把自己折腾多 Agent 的完整过程、配置思路、踩过的坑和排查心得整理一遍给想从单 Agent 升级到多 Agent 的朋友一份能直接抄作业的参考。1. 先搞清楚多 Agent 到底解决了什么问题1.1 单 Agent 的瓶颈在哪里先说个我自己的例子。之前我让单个 Agent 做一个完整的网页项目从需求分析到页面设计再到后端接口它一开始还能跟上节奏但到了中后期就开始“失忆”前面定好的技术方案到后面被它自己改得面目全非。这不是 WorkBuddy 的问题而是单 Agent 架构的通病上下文窗口有限任务目标一多注意力就被稀释了。单个 Agent 干活有几个典型毛病上下文污染前置任务的关键结论被后置任务的中间过程冲掉导致前后逻辑不一致。职责不分同一个 Agent 既要当产品经理又要当程序员还要当测试角色切换成本高输出风格不稳定。错误难定位出了问题你不知道是需求理解错了、代码写错了还是环境配置错了因为所有环节都是同一个 Agent 干的。并行能力为零一个 Agent 只能顺序干活不能同时做“分析需求”和“准备环境”这类互相独立的事情。多 Agent 的核心价值不是“多个模型一起跑”而是把不同能力边界的人组织成一条流水线。你不需要一个全知全能的超级 Agent你需要的是几个各司其职的专家 Agent让它们通过明确的接口协作。1.2 WorkBuddy 多 Agent 的架构思路WorkBuddy 的多 Agent 机制本质上是一个导演-演员结构。你可以创建一个调度型 Agent或者叫 Manager Agent它不直接干活负责拆解任务、派活、检查结果和决定下一步。干活的是若干执行型 Agent每个执行型 Agent 有自己独立的系统提示词、工具集和记忆空间。我用一个生活化的类比来解释你装修房子不会让一个工人从设计到刷墙到装电路全包。你会有设计师、水电工、木工和监理每个工种有自己擅长的领域和工具监理负责协调进度和验收。WorkBuddy 的多 Agent 就是把这套工程管理逻辑搬到了 AI 工作台里。这个设计解决了前面说的四个问题上下文隔离了每个 Agent 有自己的上下文、职责清晰了、错误定位方便了哪个 Agent 出的问题一目了然、还可以并行推进任务之间如果没有依赖关系可以同时跑。2. 环境准备和基础配置2.1 安装和版本要求工欲善其事必先利其器。多 Agent 功能对 WorkBuddy 版本有要求老版本只有单 Agent 模式需要先升级到支持工作流编排的版本。我自己用的是通过命令行安装的方式安装过程不复杂# 使用包管理器安装或更新到最新版本 npm install -g workbuddylatest # 或者如果你之前装过直接升级 npm update -g workbuddy装完之后用workbuddy --version确认一下版本号。这里有个小坑如果系统里同时装过 CodeBuddy它们的配置文件目录可能会混我建议两个工具用不同的环境变量隔离比如WORKBUDDY_HOME单独指一个目录别用默认配置。2.2 模型和 API Key 准备多 Agent 模式下每个 Agent 都可以单独指定模型。我的做法是分类施策Agent 角色推荐模型理由调度/规划 Agent更强推理的模型需要做任务分解和逻辑判断编码 Agent代码能力均衡的模型主要干活速度要快审查 Agent细节敏感度高的模型挑错需要耐心和细心文档 Agent综合能力即可写说明文档不需要太强的推理API Key 方面WorkBuddy 支持通过环境变量配置也支持在配置文件中指定。我建议不要在多个 Agent 里重复使用同一个 Key 写死在代码里而是统一放在环境变量里Agent 配置引用环境变量名即可。这样换 Key 的时候不用到处改。export WORKBUDDY_API_KEY你的密钥 export WORKBUDDY_MODEL_DEFAULT默认模型名2.3 配置文件的结构WorkBuddy 的配置通常在workbuddy.config.js或workbuddy.json中多 Agent 的配置核心是agents节点。先看一个最小可用的例子{ agents: [ { name: planner, role: 任务规划与拆解, systemPrompt: 你是项目经理负责理解用户需求拆分任务并分配给其他 Agent, model: reasoning-model }, { name: coder, role: 代码实现, systemPrompt: 你是资深程序员负责根据需求文档编写代码注重代码质量和可维护性, model: coding-model } ] }我建议第一次配置先别搞太复杂两个 Agent 起步一个规划一个执行跑通了再往上加角色。很多新手一上来就配置五六个 Agent结果 Agent 之间互相等消息、上下文传递混乱体验还不如单 Agent。3. 多 Agent 的核心机制拆解3.1 任务分发与调度逻辑理解了配置结构接下来最关键的是明白 WorkBuddy 是怎么把任务分给不同 Agent 的。这部分的机制设计直接决定了你的多 Agent 是“真协同”还是“假切换”。WorkBuddy 的调度逻辑是一个两层的消息传递机制。当你向调度 Agent比如 planner提交一个任务时planner 会先对任务做一次分析生成一个任务执行计划。这个计划不是写给人看的文档而是一个结构化的任务列表每个任务项包含执行 Agent 的名称、任务输入、期望输出和依赖关系。然后 WorkBuddy 的运行时根据这些依赖关系构建执行图有依赖的串行跑没依赖的并行跑。{ tasks: [ { agent: analyzer, depends: [], prompt: 分析用户需求的业务逻辑输出需求文档 }, { agent: coder, depends: [analyzer], prompt: 根据需求文档实现核心功能模块 }, { agent: reviewer, depends: [coder], prompt: 检查核心功能模块的代码质量给出修改建议 } ] }这个设计有一个隐含的好处每个 Agent 只在它被分配的那一段上下文里工作。analyzer 看到的只有用户原始需求coder 看到的只有需求文档reviewer 看到的只有代码。上下文隔离让每个 Agent 的注意力更集中回答质量自然更高。但也带来了一个挑战信息传递的完整性。如果 analyzer 输出的需求文档写得太粗糙coder 能拿到的有效信息就有限最终质量直接受影响。所以我后来总结出一个经验调度 Agent 的任务描述必须包含“必须输出的内容结构”比如要求分析 Agent 必须输出“业务目标、功能清单、非功能约束”三个板块缺一不可。3.2 Agent 之间的协作模式WorkBuddy 支持几种协作模式我实际使用中比较常用的是这三种流水线模式上一个 Agent 的输出作为下一个 Agent 的输入典型场景就是“需求分析 → 代码生成 → 代码审查”。这种模式适合流程稳定的常规任务缺点是整条链路耗时取决于最慢的那个 Agent。并行模式把互不依赖的任务同时丢给多个 Agent。比如写一份技术方案文档可以同时让一个 Agent 查相关资料另一个 Agent 整理项目现状第三个 Agent 列方案草稿。等三个结果都回来之后再由汇总 Agent 整合。这种模式能显著缩短总耗时但对任务的可拆分性要求高。协商迭代模式两个 Agent 之间来回传递消息比如编码 Agent 写完代码后审查 Agent 提意见编码 Agent 根据意见修改再让审查 Agent 复检。这种模式适合对质量要求极高的场景但要注意设置迭代次数上限防止两个 Agent 陷入死循环。我在实际项目里最常用的是“先并行后汇总”的结构先让 2-3 个执行 Agent 并行处理独立子任务最后用一个整合 Agent 将所有结果合并成完整交付物。这比纯流水线快得多也比纯并行更适合需要统一风格的任务。3.3 上下文和记忆的隔离策略多 Agent 模式下有一个容易被忽视的问题每个 Agent 的记忆是独立的。你在这个 Agent 里说的信息不会自动出现在另一个 Agent 的上下文里必须通过任务交接来传递。这既是一个优点也是一个坑。优点是互相不干扰不会出现前面 Agent 的错误结论影响后面 Agent 的判断坑是如果你忘了把关键信息写进交接文档后面的 Agent 就会“失忆”。我的做法是维护一份“项目状态文件”每次任务交接时不只传递原始输入还要传递一份结构化的状态摘要## 项目状态快照 - 当前阶段代码实现 - 已完成需求评审通过技术方案已定 - 技术栈React Node.js - 关键约束不支持 IE 浏览器需要移动端适配 - 待办核心功能模块编码我把这个快照作为系统提示词的一部分注入到每个 Agent 里或者通过交接任务的 prompt 首部附上。实测下来这个习惯能减少大量“你猜错了”的来回。4. 实操搭建一套完整的多 Agent 工作台4.1 第一步明确你的目标流程动手配置之前先把你要跑的流程画清楚。我曾经犯过一个错误流程没想明白就急着配置结果配了五个 Agent实际跑起来只有两个在工作其他三个闲等着。以“写一篇技术博客并配代码示例”这个流程为例我把它拆成以下步骤选题和定位确定文章要解决什么问题面向什么读者。技术调研确认技术方案的可行性收集关键资料。写作初稿根据调研结果输出文章主体。代码验证把文中的代码实际跑一遍修正错误。审校优化检查逻辑、术语和表达输出终稿。这五个步骤对应四个 Agent 角色就够了调研 Agent、写作 Agent、代码 Agent、审校 Agent。选题和定位我倾向于自己定不交给 Agent因为机器对“读者痛点”的感知还是不如人。4.2 第二步定义 Agent 角色和提示词角色定义是整套配置的灵魂。WorkBuddy 的 Agent 配置里最重要的字段是systemPrompt这个提示词决定了这个 Agent 的行为方式和输出风格。我写了几版沉淀下来的提示词模板调研 Agent你是一名技术调研专家。你的任务是围绕给定主题收集信息、分析可行性、整理关键结论。 你必须输出一份结构化的调研报告包含 1. 核心概念解释用通俗语言 2. 主流方案对比至少3个方案用表格形式 3. 推荐方案及理由 4. 参考资料链接真实可访问的 注意不要直接给出最终解决方案你的职责是提供信息和选项而不是做决策。写作 Agent你是一名技术博主擅长把复杂技术讲得通俗易懂。你的写作风格是 - 口语化表达像朋友聊天不堆砌术语 - 每段不超过200字 - 必须包含至少一个亲身经历或踩坑故事 - 善用类比和示例解释概念 你的任务是根据调研报告撰写文章初稿要求逻辑清晰、有个人观点、有实操细节。代码 Agent你是一名资深开发工程师负责编写和验证示例代码。你的代码要求 - 可直接运行无语法错误 - 注释完整说明每个关键步骤的意图 - 使用主流最佳实践 - 输入(1) 文章初稿 (2) 需要验证的代码片段 你的输出可运行的完整代码 运行说明。你会发现我给每个 Agent 的提示词都明确了“输入什么、输出什么、遵循什么标准”。这是多 Agent 协作的关键任务边界越清楚协作越顺畅别指望 Agent 自己猜。4.3 第三步配置执行图和交接规则配置好角色之后在 WorkBuddy 中创建一个执行图{ workflow: { name: 博客生产流水线, description: 从选题到成稿的完整流程, agents: [researcher, writer, coder, reviewer], graph: [ { from: start, to: researcher }, { from: researcher, to: writer }, { from: writer, to: coder }, { from: coder, to: writer, loop: 代码有误时返回修改 }, { from: writer, to: reviewer } ] } }这里有个巧妙的设计coder和writer之间的循环边允许文章在写作和代码验证之间来回迭代。我第一次跑的时候没配这条循环边结果代码 Agent 发现代码有问题只能输出建议让写作 Agent 自己改写作 Agent 又看不懂代码细节来回折腾了好几轮。加了循环边之后代码 Agent 可以直接修改自己验出的错误再回传给写作 Agent 更新文章。实际运行后的日志记录大致是这样的[14:02:31] 任务启动博客生产流水线 [14:02:33] researcher 开始执行技术调研 [14:04:12] researcher 完成输出调研报告 (3428字4个方案对比) [14:04:13] writer 开始执行文章初稿 [14:05:47] writer 完成输出初稿 (2865字含2个代码片段) [14:05:48] coder 开始执行代码验证 [14:06:52] coder 发现2处代码问题已修复输出修改说明 [14:06:53] writer 更新文章根据代码修改同步内容 [14:07:26] reviewer 开始执行终稿审校 [14:08:13] reviewer 完成输出审校意见和最终版本 [14:08:14] 任务完成总耗时 5分43秒4.4 第四步参数调优和结果评估第一版跑完之后不要急着用先检查各环节输出质量。我总结了一个简单的四维评估法完整性最终交付物是否覆盖了所有需求点有没有遗漏的环节一致性各 Agent 输出的风格、术语、数据是否统一准确性代码能否运行技术细节是否过关参考文献是否真实存在效率总耗时是否可接受有没有某个环节特别慢拿上面的博客流程来说实测跑一篇文章大约 5-8 分钟比纯人工写快得多但比单 Agent 直接写要慢一些。这个时间差是合理的因为多 Agent 牺牲了一些速度换取了质量。真实对比同样一个中等复杂度的技术任务单 Agent 平均 3 分钟写完但有 20% 概率出现前后矛盾多 Agent 要 6 分钟但前后一致性和代码可运行率都明显更高。4.5 进阶自定义 Skill 增强 Agent 能力网络热词里一直在提 WorkBuddy Skill这个 Skill 本质上是一段可复用的能力模块你可以把它注入到 Agent 里让它具备特定能力。多 Agent 模式下Skill 的分配策略很重要。我的分配原则是通用类 Skill 放共享区专业类 Skill 绑定到对应 Agent。比如“代码风格检查”这个 Skill 只绑定给 coder 和 reviewer不要给 writer“SEO 关键词优化”这个 Skill 只绑定给负责内容发布的 Agent。举个例子给文章审校 Agent 配置一个“技术准确性检查”的 Skill{ name: tech-accuracy-check, description: 检查技术文档中的概念准确性、版本号正确性和代码示例可运行性, trigger: reviewer 完成审校后自动执行, actions: [ 提取文章中的所有技术名词和版本号, 与知识库中的权威信息对比, 运行所有代码示例记录运行结果, 输出修正建议列表 ] }配置了这种 Skill 之后审校 Agent 就不再是“看起来在检查”而是真的会去执行代码、比对信息。这个能力是普通对话式 AI 做不到的。5. 多 Agent 的典型应用场景5.1 技术方案设计场景这是我最常用的场景。以前写一份完整的技术方案需要自己查资料、构思架构、评估选型大概要半天时间。现在用多 Agent 流水线场景分析 Agent解读业务需求抽取功能性和非功能性要求。技术调研 Agent针对关键选型做横向对比输出对比表。架构设计 Agent基于调研结果设计系统架构画出模块分层关系。风险审查 Agent评估方案的技术风险、成本风险和进度风险给出备选方案。一轮下来大概 10 分钟能拿到一份结构清晰的技术方案初稿。注意这只是初稿最终的决策还是要人来拍板。多 Agent 能帮你把素材和思路整理好但不能替代人的商业判断。5.2 代码项目开发场景多 Agent 做开发我的玩法是规划 Agent 负责把需求拆成任务栈多个编码 Agent 并行开发互不依赖的模块。比如一个 Web 应用有用户模块、支付模块和管理后台三个独立模块我可以让三个编码 Agent 并行开工各写各的模块代码最后由集成 Agent 合并处理模块间接口。这里有个必须注意的点模块间的接口定义要在开工前就定好不能边写边改。我在实践中吃过亏两个 Agent 各写各的最后在接口对接时发现数据格式不匹配重新对齐又花了很多时间。所以现在我在拆分任务时会把“接口契约文档”作为前期必备产物每个编码 Agent 都必须遵循。5.3 知识管理场景这个场景网上讨论得不多但我试下来觉得很有价值。把 WorkBuddy 当知识库管理工具用多 Agent 来做资料整理搜集 Agent爬取或导入相关文档提取基础元数据。摘要 Agent为每篇文档生成结构化摘要目标、方法、结论、局限。关系梳理 Agent分析文档之间的引用、对比和延伸关系生成知识图谱。问答 Agent基于整理后的知识库回答具体问题。这套流程跑下来整理一个 50 篇论文的专题库从原始文档到结构化知识体系大概二十分钟左右。这对做科研或者做行业调研的人来说能省不少时间。6. 常见问题与排查技巧实录6.1 Agent 之间互相“打架”表现A Agent 的输出被 B Agent 认为不合格B 退回后 A 重新生成然后又被退回形成一个循环。排查思路先看是不是提示词里没有定义“什么算合格”。我之前遇到循环就是因为审校 Agent 说“代码风格不符合规范”但规范是什么没写清楚编码 Agent 改了两版还是不知道标准在哪。解决方法在提示词里明确验收标准。比如审校 Agent 的提示词要明确“必须给出具体修改点和修改建议禁止泛泛地提意见”编码 Agent 的提示词要明确“必须按照团队 ESLint 规则和命名规范编码”。有了明确的验收标准和修改指引类似死循环的问题基本都能避免。6.2 上下文传递丢失表现前面的 Agent 明确给出的关键约束到后面的 Agent 那边就没了导致输出不符合要求。排查思路检查交接文档到底传了什么。WorkBuddy 的任务交接依赖的是 prompt 中的内容不是隐式的记忆。解决方法写交接模板。我在配置里为每个 Agent 定义了固定的输出结构比如调研 Agent 必须输出关键约束、推荐方案、风险点三个字段写作 Agent 必须在开头读取这三个字段并复述一遍。这样的强制结构能有效防止上下文丢失。6.3 效率反而不如单 Agent表现配好了多 Agent但总耗时比单 Agent 还长多花的时间都消耗在 Agent 间的等待上了。排查思路查看执行日志看哪些环节是串行的其实可以并行。解决方法重构任务依赖关系。我遇到过一次配置了三个 Agent但它们都在等待同一个前置结果这是典型的过度串行化。正确做法是把前置任务拆开让三个 Agent 各自独立调研不同方面然后汇总。6.4 模型选择不当导致质量下降表现用了推荐的配置但某个 Agent 输出质量明显偏低。排查思路看这个 Agent 的任务类型和它使用的模型是否匹配。比如你要规划 Agent 做复杂逻辑推理却配了只擅长代码补全的轻量模型输出质量自然上不去。解决方法按任务类型重新选模型。我的配置建议是任务类型模型选择建议逻辑推理/规划优先选推理能力最强的模型代码生成选代码专项模型文本写作/总结选综合能力即可别浪费算力分类/抽取轻量模型即可速度更快6.5 缓存目录和账号切换问题实际使用中WorkBuddy 的多 Agent 配置会占用一定的磁盘缓存特别是每个 Agent 的会话记录都独立存储。如果发现系统提示“磁盘空间不足”检查一下缓存的存储位置。WorkBuddy 支持修改系统缓存目录我建议把它指到一个剩余空间比较大的盘别放在系统盘默认位置。# Linux / macOS export WORKBUDDY_CACHE_DIR/path/to/large/disk/workbuddy-cache # Windows PowerShell $env:WORKBUDDY_CACHE_DIR D:\workbuddy-cache另外换账号的时候之前账号的多 Agent 配置和记忆是跟账号走的不会自动迁移。如果你想把旧账号的配置迁移到新账号直接把配置目录下的 agent 定义文件复制过去即可但每个 Agent 的独立会话记录一般不建议复制因为里面可能有隐私信息。7. 多 Agent 的进阶玩法与扩展思路7.1 从固定流程到动态编排我前面讲的都是固定流程。WorkBuddy 支持更高级的动态编排也就是让调度 Agent 根据任务内容实时决定调用哪些 Agent、以什么顺序调用。这在任务类型经常变化、难以预定义流程的场景下非常有用。举个例子我搭建过一个“通用需求处理台”用户丢进来一个需求不指定类型。调度 Agent 先判断需求属于开发类、文档类还是咨询类。如果是开发类它自动拉取编码 Agent 和审查 Agent 的流程如果是文档类它只调用写作 Agent 和审校 Agent。用户完全不感知内部流程只看到最终结果。这种动态编排对调度 Agent 的推理能力要求很高如果任务判断错了流程整体结果质量会很差。我的经验是先跑固定流程积累信心再逐步放开动态调度能力。7.2 多 Agent 结合外部工具WorkBuddy 的 Agent 可以挂载外部工具比如让编码 Agent 直接调用 Git 命令提交代码、让调研 Agent 调用浏览器工具搜索网页。这个能力配合多 Agent 使用效果倍增。我的一个实际场景是调研 Agent 调用搜索工具获取信息编码 Agent 调用终端工具实测代码审校 Agent 调用文档工具做格式校验。每个 Agent 用自己擅长的工具效率比单 Agent 拿着所有工具手忙脚乱高得多。7.3 减少“AI 味”的多 Agent 思路网上很多人问怎么让 AI 写出来的内容减少 AI 味。我的经验是与其在一个 Agent 的提示词里反复强调“不要像 AI”不如用多 Agent 加一个人工环节让写作 Agent 写初稿、审校 Agent 做“去 AI 味”处理、再让人读一遍做一些语言微调。审校 Agent 被专门赋予去除套话任务的配置效果比我以前在单 Agent 里写“请用人类口吻”好得多。8. 一些实在的体会与建议写到这里我再分享几点实际操作中的体会。多 Agent 不等于配置越多越好。我最初觉得 Agent 越多越专业结果五个 Agent 跑一个简单任务调度开销比干活时间还长。根据任务复杂度选择合适的 Agent 数量两三个最常见。如果你遇到“多 Agent 结果比单 Agent 还差”的情况大概率不是多 Agent 的问题而是配置不合理。提示词的质量决定了多 Agent 的上限。在多 Agent 模式下提示词不再只约束一个 Agent 的行为而是通过交接文档影响着下游所有 Agent。一个含糊的提示词可能导致整条流水线跑偏。花在打磨提示词上的时间是值得的尤其是每个 Agent 的输入输出格式一定要写清楚。多 Agent 方案要和工具链匹配。我见过一些朋友把 WorkBuddy 的多 Agent 配得很好但实际任务根本不需要杀鸡用牛刀。判断标准其实很简单任务是否可以被拆成独立子任务子任务之间是否有清晰的交接物如果答案是否那单 Agent 反而更合适。多 Agent 适合复杂任务和可并行的场景不适合简单问答。我在实际使用中踩了挺多坑才把这套多 Agent 流程跑顺最核心的一条心得是从单 Agent 到多 Agent 的切换不是换个配置就行的事而是工作方法的重新设计。把这里面的经验总结成这套流程希望能帮你少走点弯路。多 Agent 是一个很大的话题我这套方案主要基于自己的项目实践后续如果大家有比较好的配置思路欢迎一起交流。