1. 多代理工作流到底在解决什么问题第一次看到“Qwen Code 开始调度其他编程助手”这个说法我脑子里冒出来的不是兴奋而是疑问一个编程助手已经够用了为什么还要让它去调度别的助手这不是脱裤子放屁吗直到我在一个真实项目里被坑了一次才彻底理解这套思路的价值。当时我在做一个前后端分离的中型项目前端要改组件库的样式后端要调接口的返回结构同时数据库那边还有个字段类型需要迁移。我用的编程助手在单个任务上表现很好但当我试图让它一次性处理这三个跨模块的改动时它开始犯迷糊——改完前端忘了后端调完接口又漏了数据库迁移脚本。更麻烦的是它把三个任务的上下文混在一起导致生成的代码风格都不统一了。这就是单代理模式的根本瓶颈上下文窗口是有限的而真实项目的任务边界是模糊的。当你把所有需求塞给一个代理它就像一个同时接了三通电话的客服每通电话都听了一半最后三件事都办得稀碎。多代理工作流的核心思路说白了就是分而治之。让一个主代理在 Qwen Code 的场景里就是它自己充当“调度员”的角色把大任务拆成若干个子任务每个子任务交给一个专门的子代理去处理。每个子代理只关心自己那一亩三分地上下文干净、目标明确、产出可控。主代理负责协调、汇总、验收。这套模式并不是 Qwen Code 独创的。在分布式系统里这就是经典的 Master-Worker 架构在项目管理里这就是“拆解-分配-跟进-交付”的标准流程。只不过现在把它搬到了 AI 编程助手的协作场景里。那为什么偏偏是现在这个时间点火起来了我觉得有三个原因。第一编程助手的能力已经足够强单个代理能独立完成一个完整的子任务不需要人类频繁介入。第二多代理协作的通信协议和工具链逐渐成熟代理之间可以传递结构化的上下文而不是靠人类复制粘贴。第三像 Git Worktree 和沙箱这类隔离机制越来越易用让多个代理可以并行工作而不互相踩脚。如果你现在还在用“一个对话框解决所有问题”的方式使用编程助手那多代理工作流可能是你下一步最值得花时间研究的效率提升点。2. 核心角色拆解谁在调度谁在被调度2.1 主代理的职责边界主代理在整个工作流里扮演的是“技术负责人”的角色而不是“全栈工程师”。这个定位非常关键因为很多人第一次尝试多代理时会不自觉地让主代理也去写代码结果又回到了单代理的老路上。主代理应该做的事情包括接收人类的需求描述把需求拆解成可独立执行的子任务为每个子任务分配合适的子代理定义每个子任务的输入输出规范监控子任务的执行状态最后把各个子任务的产出合并成完整的交付物。主代理不应该做的事情包括亲自写业务代码、陷入某个子任务的具体实现细节、在子任务执行过程中频繁干预。我见过有人让主代理一边调度一边自己也写一个模块结果主代理的上下文被自己的代码占满了调度逻辑反而开始出错。2.2 子代理的类型与选型子代理不是随便找一个编程助手就行不同类型的子任务需要不同特长的代理。根据我的实践经验至少可以把子代理分成以下几类子代理类型擅长任务典型工具选择上下文需求代码生成型从零写新模块、新函数Qwen Code、Claude Code需要完整的接口定义和业务逻辑描述代码审查型检查代码质量、发现潜在bug专门的lint工具AI审查需要被审查的代码和项目规范重构型改善现有代码结构支持大范围编辑的助手需要理解现有代码的依赖关系测试型生成单元测试、集成测试测试框架AI生成需要被测代码和测试覆盖率要求文档型生成API文档、注释文档生成工具需要代码签名和业务背景选型的核心原则是让子代理的上下文窗口刚好装下它需要的信息不多也不少。装多了浪费装少了干不好活。2.3 代理之间的通信机制代理之间怎么传递信息这是多代理工作流里最容易出问题的地方。我踩过的坑包括主代理用自然语言描述子任务子代理理解偏了子代理返回的结果格式不统一主代理解析不了两个子代理同时修改同一个文件产生冲突。比较稳妥的做法是定义一套结构化的通信协议。主代理给子代理的任务描述应该包含任务ID、任务类型、输入文件列表、输出文件列表、验收标准、依赖关系。子代理返回的结果应该包含任务ID、执行状态、产出文件列表、变更摘要、遇到的问题。这套协议不需要很复杂用JSON或者YAML就能描述清楚。关键是双方都要严格遵守不能主代理随便写一段话就扔过去也不能子代理返回一堆自然语言让主代理去猜。3. Worktree 与沙箱多代理并行的基础设施3.1 Git Worktree 为什么比 Branch 更适合多代理很多人第一次听到 Worktree 会问这和 Branch 有什么区别我用一个生活化的类比来解释。Branch 就像你在同一张桌子上换了一本笔记本写东西。桌子还是那张桌子你只是换了个本子。如果你同时想写两本笔记就得来回切换本子而且桌子上的其他东西比如参考书、草稿纸是共享的容易搞混。Worktree 则是给你在同一个房间里又搬了一张新桌子。每张桌子有自己的笔记本、自己的参考书、自己的草稿纸。你可以在这张桌子上写前端代码在那张桌子上写后端代码互不干扰。写完了再把两张桌子的成果合并到一起。对于多代理工作流来说Worktree 的优势非常明显文件系统隔离每个子代理在自己的 Worktree 里工作不会意外修改其他代理的文件并行执行多个子代理可以同时运行不需要排队等待独立回滚某个子代理搞砸了直接删掉它的 Worktree 就行不影响其他人清晰的合并路径每个 Worktree 对应一个明确的分支合并时冲突范围可控创建 Worktree 的命令很简单# 为前端任务创建一个 Worktree git worktree add ../project-frontend -b feature/frontend-update # 为后端任务创建另一个 Worktree git worktree add ../project-backend -b feature/backend-update每个子代理在自己的目录里工作主代理在原始目录里负责协调。3.2 沙箱环境的选择与配置沙箱解决的是另一个维度的问题执行安全。子代理生成的代码可能包含危险操作比如删除文件、修改系统配置、发起网络请求。如果直接在宿主机上执行风险很大。沙箱的选择要根据任务类型来定。如果是纯代码生成和静态分析不需要执行代码那用容器级别的隔离就够了。如果需要运行测试、执行脚本那就需要更严格的沙箱。我常用的方案是 Docker 容器加资源限制docker run --rm \ --memory2g \ --cpus1.5 \ --networknone \ -v $(pwd)/worktree:/workspace \ -w /workspace \ code-sandbox:latest \ python -m pytest tests/这个配置的含义是限制内存2G、CPU 1.5核、禁用网络、只挂载当前 Worktree 目录。这样即使子代理生成了恶意代码影响范围也被限制在容器内。注意沙箱的隔离级别要和任务的信任级别匹配。对于完全可信的代码生成任务可以放宽限制对于执行未知来源代码的任务必须严格隔离。3.3 资源调度与并发控制多个子代理同时运行会争抢 CPU、内存、磁盘IO。如果不加控制可能导致系统卡死或者某个代理被饿死。我的做法是设置一个简单的并发上限。比如同时最多运行3个子代理超出的任务排队等待。这个数字取决于你的机器配置和任务类型。代码生成类任务对CPU要求不高可以多开几个测试执行类任务对CPU和内存要求高要少开几个。另外要注意磁盘空间。每个 Worktree 都会占用一份完整的代码副本如果项目很大几个 Worktree 下来磁盘就满了。定期清理已完成的 Worktree 是个好习惯# 查看所有 Worktree git worktree list # 删除已完成的 Worktree git worktree remove ../project-frontend4. 完整实操从需求到交付的多代理流程4.1 需求拆解与任务分配假设我们要给一个电商项目加一个“优惠券”功能。这个需求涉及数据库加表、后端加接口、前端加页面、测试加用例。如果让单个代理做它可能会在数据库迁移脚本里写错字段类型或者前端调用的接口路径和后端定义的不一致。用多代理工作流第一步是拆解数据库任务创建优惠券表包含字段 id、code、discount_type、discount_value、expire_at、status后端任务实现优惠券的创建、查询、核销接口前端任务实现优惠券列表页和创建表单测试任务为后端接口写集成测试每个任务分配给一个子代理主代理负责定义接口契约。比如后端和前端之间的接口路径、请求参数、返回格式必须在任务开始前就确定好写进任务描述里。4.2 子代理的启动与监控启动子代理的方式取决于你用的工具。如果是 Qwen Code 调度其他助手通常是通过命令行调用或者API调用。每个子代理启动时要给它指定工作目录对应的 Worktree、任务描述文件、输出目录。监控子代理的状态我建议至少记录以下信息任务ID和子代理ID启动时间和预计完成时间当前状态运行中/已完成/失败已修改的文件列表遇到的错误或警告这些信息可以写到一个简单的日志文件里主代理定期读取并判断是否需要干预。4.3 结果汇总与冲突处理所有子代理完成后主代理需要把各个 Worktree 的改动合并到主分支。合并顺序很重要先合并数据库迁移脚本再合并后端代码最后合并前端代码。因为前端依赖后端的接口定义后端依赖数据库的表结构。如果出现合并冲突主代理需要判断冲突原因。常见的冲突包括两个子代理修改了同一个配置文件、接口定义不一致、依赖版本冲突。处理方式是让相关的子代理重新协商或者由主代理做出裁决。4.4 验收与回滚策略合并完成后要跑一遍完整的测试套件。如果测试通过说明多代理协作成功。如果测试失败需要定位是哪个子代理的产出有问题。回滚策略要提前准备好。最简单的回滚是保留合并前的分支指针一旦出问题就重置回去。更细粒度的回滚是只撤销某个子代理的改动保留其他子代理的成果。# 查看合并历史 git log --oneline --graph # 回滚到合并前的状态 git reset --hard HEAD~1 # 或者只撤销某个文件的改动 git checkout HEAD~1 -- path/to/file5. 常见问题与排查技巧实录5.1 子代理理解偏差怎么办这是最常见的问题。子代理把任务理解错了生成的代码完全不是你要的。排查思路是先看任务描述是否足够清晰再看子代理的上下文里有没有干扰信息。我的经验是任务描述里要包含正例和反例。比如“创建一个返回JSON的接口”不如“创建一个返回JSON的接口格式为 {code: 0, data: {...}, message: success}不要返回XML格式”。反例能有效防止子代理自由发挥。5.2 Worktree 切换导致的依赖问题每个 Worktree 是独立的目录但依赖包比如 node_modules、venv不会自动复制。如果子代理在 Worktree 里直接运行代码可能会因为缺少依赖而失败。解决方案有两种一是每个 Worktree 单独安装依赖缺点是慢且占空间二是用符号链接共享依赖目录缺点是可能有版本冲突。我通常选择第一种因为多代理工作流本来就是为了隔离共享依赖会破坏隔离性。5.3 沙箱内网络受限导致的任务失败有些任务需要访问外部服务比如拉取依赖包、调用API。如果沙箱禁用了网络这些任务就会失败。处理方式是按需开放网络。可以在沙箱配置里加一个白名单只允许访问特定的域名或IP。或者把依赖提前下载好挂载到沙箱里。5.4 多代理并发写同一文件的冲突虽然 Worktree 隔离了文件系统但如果两个子代理的任务有重叠合并时还是会冲突。预防措施是在任务分配阶段就做好文件级别的划分确保没有两个子代理会修改同一个文件。如果无法避免重叠就要定义修改优先级。比如配置文件由主代理统一修改子代理只提交修改建议不直接改文件。5.5 常见问题速查表问题现象可能原因排查步骤解决方案子代理产出不符合预期任务描述模糊检查任务描述是否包含验收标准补充正例反例明确输出格式子代理执行超时任务过大或资源不足查看任务日志和资源占用拆解任务或增加资源配额合并时大量冲突任务边界重叠检查各子代理修改的文件列表重新划分任务边界沙箱内命令找不到依赖未安装在沙箱内执行 which 命令安装依赖或挂载依赖目录Worktree 磁盘占用过大未清理旧 Worktree执行 git worktree list删除已完成的 Worktree6. 我踩过的坑和总结的经验第一个坑是过度拆解。我一开始把任务拆得太细一个简单的CRUD接口拆成了“定义路由”“写控制器”“写服务层”“写数据访问层”四个子任务结果四个子代理各自为政接口对不上。后来我调整了粒度一个子代理负责一个完整的垂直切片比如“优惠券的创建接口”从路由到数据库操作全部由它完成问题就少多了。第二个坑是忽略上下文传递。子代理不是孤立工作的它需要知道项目的整体约定。比如代码风格、命名规范、错误处理方式。如果不在任务描述里说明每个子代理都会按自己的习惯来最后合并的代码风格五花八门。我的做法是准备一个“项目约定”文件每个子代理启动时都加载它。第三个坑是没有设置超时。有个子代理卡在一个死循环里跑了两个小时把CPU占满了其他子代理全部饿死。后来我给每个子代理设置了硬性超时比如10分钟没完成就强制终止并报告状态。第四个坑是合并顺序错误。我先合并了前端代码再合并后端代码结果前端调用的接口在后端还不存在测试全部失败。正确的顺序应该是先合并底层依赖再合并上层调用。关于工具选型我的建议是Qwen Code 作为主代理调度器是合适的因为它对中文需求的理解比较好拆解任务时不容易跑偏。子代理可以根据任务类型灵活选择代码生成用 Qwen Code 或 Claude Code代码审查用专门的lint工具测试生成用测试框架自带的AI功能。最后分享一个提高成功率的小技巧让子代理先输出计划再执行。在任务描述里加一句“先列出你打算修改的文件和修改内容确认后再执行”。这样你可以在子代理真正动手之前发现理解偏差避免浪费时间和资源。这个技巧看起来简单但能减少至少一半的返工。