1. 从单兵作战到团队协作：多代理工作流到底解决了什么痛点

用编程助手写代码这件事，大部分人现在的用法还停留在“单代理”阶段——打开一个对话框，把需求丢进去，等它吐代码，然后自己复制粘贴、跑测试、改bug。这个模式在写小脚本、改单个函数的时候确实够用，但一旦项目规模上去，问题就暴露得很明显。

我最近在做一个中等规模的后端服务重构，涉及数据库迁移、接口兼容层、单元测试补齐三块内容。如果按老办法，我得先让助手帮我改数据模型，等它改完，我再手动把接口层的调用改掉，然后再单独开一个会话让它写测试。整个过程里，助手之间没有任何信息传递，上下文全靠我人肉搬运。更麻烦的是，当接口层改到一半发现数据模型有个字段设计不合理，我得退回去重新调整，前面接口层改的东西可能全白费。

多代理工作流的核心价值，就是让多个编程助手各自负责一块明确的职责，并且它们之间能通过某种调度机制协同起来。这有点像从“一个人干所有活”变成“一个小团队分工协作”——有人负责架构设计，有人负责具体实现，有人负责测试验证，还有人负责代码审查。Qwen Code 在这方面的尝试，是把调度能力做进了工具本身，让一个主代理可以按需唤起其他代理来完成子任务。

这里需要先厘清一个概念：多代理不等于多个模型同时跑。它更像是一个编排层，主代理根据任务类型决定“这个活该交给谁干”。比如代码生成交给一个擅长写实现的代理，代码审查交给一个专门挑毛病的代理，测试用例生成交给另一个代理。每个代理可以有独立的提示词、独立的工具权限、甚至独立的模型配置。

为什么这件事值得关注？因为在实际项目里，不同阶段对助手的能力要求是不一样的。写业务逻辑的时候你需要它理解领域模型，写测试的时候你需要它覆盖边界条件，做代码审查的时候你需要它严格挑剔。用一个通用提示词去覆盖所有场景，效果往往打折扣。多代理工作流允许你为每个场景定制最合适的“人格”和工具集，这是单代理模式做不到的。

还有一个容易被忽略的点：上下文隔离。单代理模式下，所有对话历史堆在一个会话里，聊到后面上下文越来越长，模型注意力被稀释，早期的重要约束可能被遗忘。多代理模式下，每个子代理只关心自己那部分任务，上下文干净，输出质量更稳定。主代理负责维护全局状态和任务分解，子代理负责执行具体动作，各司其职。

从热搜词也能看出来，大家现在关心的不只是“哪个模型写代码强”，而是“怎么把多个助手组织起来干活”。Git worktree、沙箱、第三方API接入这些词频繁出现，说明实际使用中大家已经在探索多代理协作的基础设施了。Qwen Code 把调度能力内置进来，相当于把这个探索过程标准化了一步。

2. Qwen Code 的调度机制拆解：主代理如何决定“叫谁干活”

要理解 Qwen Code 的多代理调度，得先搞清楚它的基本架构。它不是一个单体应用，而是一个可以加载多个“代理配置”的运行时环境。每个代理配置定义了四样东西：系统提示词、可用工具集、模型参数、以及触发条件。主代理在运行过程中，会根据当前任务的特征去匹配最合适的子代理。

2.1 任务分解与代理匹配的逻辑

主代理拿到一个用户请求后，第一步是做任务分解。比如你说“帮我把用户模块的数据库访问层从ORM改成原生SQL，并补上对应的集成测试”，主代理会把这个请求拆成几个子任务：分析现有ORM代码结构、生成原生SQL实现、生成测试用例、验证测试通过。然后它去代理注册表里找，哪个代理的触发条件匹配“代码生成”，哪个匹配“测试生成”。

触发条件的匹配方式通常有两种：一种是基于关键词或任务类型的显式规则，比如“包含‘测试’字样的子任务交给测试代理”；另一种是基于代理自描述的能力标签，主代理通过语义匹配来判断。Qwen Code 目前更偏向第一种，因为规则明确、可控性强，不容易出现代理之间互相推诿的情况。

这里有个实操细节值得注意：代理的粒度不要太细。我一开始把代理拆得特别碎，一个负责“写函数签名”，一个负责“写函数体”，结果主代理在调度时频繁切换，反而增加了协调开销。后来改成按“实现”“测试”“审查”三个粗粒度划分，效率明显提升。粒度太细的另一个问题是，子代理之间的接口约定变得复杂，容易在交接处出问题。

2.2 代理之间的通信与状态传递

多代理工作流里最容易出问题的环节就是状态传递。主代理把任务派给子代理A，A干完活之后，结果怎么传给子代理B？Qwen Code 的做法是通过一个共享的工作区（workspace）来传递中间产物。每个子代理在完成任务后，会把输出写入工作区的指定位置，下一个子代理从那里读取。

这个设计的好处是解耦——子代理之间不需要直接通信，都通过工作区这个“黑板”来交换信息。但坏处也很明显：如果工作区的数据结构没有约定好，后续代理可能读不懂前面代理的输出。我踩过的一个坑是，实现代理输出的代码文件里包含了它自己的注释风格，测试代理读取时把这些注释也当成了待测试逻辑的一部分，生成了一堆无意义的测试用例。

解决办法是在代理配置里明确定义输入输出的schema。比如实现代理的输出必须是一个包含files数组的JSON，每个文件有path和content字段；测试代理只读取files里的content，忽略其他元数据。这个约定看起来简单，但如果不提前定好，后期调试会很痛苦。

2.3 调度策略：串行、并行还是混合

Qwen Code 支持三种调度模式，实际用下来各有适用场景：

我大部分时候用的是混合模式。比如“实现+测试”是串行的，测试必须等实现完成；但“文档生成”和“代码审查”可以并行，它们都只依赖实现结果，互不干扰。Qwen Code 的调度器允许你在代理配置里声明依赖关系，它自动决定哪些能并行跑。

注意：并行调度时一定要给工作区加锁或者用版本控制。我有一次让两个代理同时往同一个文件写内容，结果后写的覆盖了先写的，排查了半天才发现是并发写入的问题。

3. 把 Worktree 和沙箱用起来：多代理协作的基础设施

多代理工作流要跑得稳，光有调度逻辑不够，还得有配套的基础设施。热搜词里反复出现的 Git worktree 和沙箱，就是两个关键支撑。

3.1 Git worktree 在多代理场景下的正确用法

很多人分不清 Git worktree 和 Git branch 的区别。简单说，branch 是同一个工作目录下的不同提交线，worktree 是同一个仓库下的不同工作目录。你可以在同一个仓库里创建多个 worktree，每个 worktree 检出不同的分支，它们共享同一个.git对象库，但文件系统是隔离的。

这个特性在多代理场景下特别有用。假设主代理要同时跑“重构实现”和“回归测试”两个子任务，如果它们都在同一个工作目录里操作，测试代理跑测试的时候，实现代理可能正在改文件，测试结果就不可靠了。用 worktree 给每个子代理分配独立的工作目录，互不干扰。

具体操作上，主代理在派发任务前，先为每个需要独立工作目录的子代理创建一个 worktree：

# 为主代理创建主工作区 git worktree add ../main-workspace main # 为实现代理创建独立工作区，基于feature分支 git worktree add ../impl-workspace feature/refactor # 为测试代理创建独立工作区，基于同一个feature分支 git worktree add ../test-workspace feature/refactor

这里有个细节：实现代理和测试代理虽然基于同一个分支，但 worktree 是独立的，实现代理的修改不会立即反映到测试代理的目录里。这看起来是缺点，实际上是优点——测试代理可以在一个稳定的快照上跑测试，不会因为实现代理的中间状态导致测试结果抖动。等实现代理完成并提交后，测试代理再拉取最新代码重新跑。

提示：worktree 的数量不要太多，每个 worktree 都会占用磁盘空间。一般控制在3-5个以内，用完及时用git worktree remove清理。

3.2 沙箱环境：让代理放心执行危险操作

编程助手在执行任务时，经常需要跑命令——安装依赖、执行测试、启动服务。如果这些操作直接在你本机的环境里跑，风险很大。万一助手生成的代码里有rm -rf之类的操作，或者安装了一个有冲突的依赖版本，你的开发环境可能就废了。

沙箱的作用就是给每个代理一个隔离的执行环境。Qwen Code 支持把代理的命令执行限制在沙箱内，沙箱可以是容器、虚拟机、或者轻量级的进程隔离。我目前用的是容器方案，每个代理跑在一个独立的容器里，容器挂载了对应的 worktree 目录，代理在容器里怎么折腾都不会影响宿主机。

沙箱的配置有几个关键点：

• 文件系统挂载：只挂载代理需要访问的目录，不要挂载整个 home 目录。比如实现代理只需要访问代码仓库，不需要访问你的 SSH 密钥。
• 网络策略：默认禁止外网访问，只允许访问必要的包管理镜像。如果代理需要调用外部API，单独开白名单。
• 资源限制：给每个沙箱设置CPU和内存上限，防止某个代理跑飞了把整台机器拖垮。
• 生命周期管理：任务完成后自动销毁沙箱，避免残留进程占用资源。

我实测下来，容器方案的启动开销在可接受范围内（大约2-3秒），对于动辄跑几分钟的代码生成任务来说，这点开销可以忽略。如果你追求更轻量的方案，可以用firejail或者bubblewrap这类进程级沙箱，启动更快，但隔离性稍弱。

3.3 工作区与沙箱的配合方式

Worktree 和沙箱不是二选一的关系，而是配合使用。典型的组合方式是：每个子代理分配一个 worktree，worktree 挂载到对应的沙箱容器里。代理在沙箱内操作 worktree 里的文件，执行命令，完成后把结果提交到分支上。

这样做的另一个好处是审计方便。每个代理的操作都留在了对应的 worktree 和分支上，出了问题可以回溯是哪个代理在哪一步做了什么。我有一次遇到测试代理生成的测试用例全部失败，通过查看它的 worktree 提交记录，发现是它在读取实现代码时误把测试文件的模板当成了实现代码，导致生成的测试逻辑完全错位。

4. 实战：搭一套能跑通的多代理工作流

理论说再多不如跑一遍。下面是我实际搭的一套多代理工作流，用于“给现有项目补充单元测试”这个场景。选这个场景是因为它足够典型：需要理解现有代码、生成测试、验证测试、审查测试质量，正好对应四个代理角色。

4.1 代理角色定义与提示词设计

我定义了四个代理，每个代理的配置包含名称、系统提示词、工具权限、以及触发条件。

分析代理（Analyzer）的职责是读取指定目录下的源代码，输出一份结构化的代码摘要，包括每个函数的签名、参数类型、返回值、以及可能的边界条件。它的系统提示词重点是“只做分析，不写代码”，工具权限只给文件读取，不给写入。

测试生成代理（TestWriter）接收分析代理的输出，为每个函数生成对应的测试用例。它的提示词里我特意加了一条：“优先覆盖边界条件和异常路径，正常路径的测试每个函数最多一个”。这是经验之谈——如果不加这条约束，助手会生成大量重复的正常路径测试，覆盖率上去了但实际价值不高。

测试执行代理（TestRunner）负责在沙箱里跑测试，收集失败信息。它的工具权限包括命令执行和文件读取，但不包括文件写入——它不能修改测试代码，只能报告结果。

审查代理（Reviewer）检查测试代码的质量，重点看是否有断言不明确、是否有测试之间相互依赖、是否有硬编码的魔法数字。它的输出是一份审查报告，列出需要修改的地方。

这四个代理的触发条件分别是：分析代理匹配“分析/理解/摘要”类任务，测试生成代理匹配“生成测试/写测试”类任务，以此类推。主代理在接到“给XX模块补测试”的请求后，会自动按顺序调度这四个代理。

4.2 调度流程与依赖声明

在 Qwen Code 的配置里，我用YAML声明了代理之间的依赖关系：

agents: analyzer: triggers: ["分析", "理解代码", "代码摘要"] tools: ["read_file", "list_dir"] outputs: ["code_summary.json"] test_writer: triggers: ["生成测试", "写测试用例"] tools: ["read_file", "write_file"] depends_on: ["analyzer"] inputs: ["code_summary.json"] outputs: ["test_files/"] test_runner: triggers: ["执行测试", "跑测试"] tools: ["read_file", "execute_command"] depends_on: ["test_writer"] inputs: ["test_files/"] outputs: ["test_report.json"] reviewer: triggers: ["审查测试", "测试质量检查"] tools: ["read_file"] depends_on: ["test_writer"] inputs: ["test_files/"] outputs: ["review_report.md"]

这个配置里，test_runner和reviewer都依赖test_writer，但它们之间没有依赖关系，所以可以并行调度。主代理会先跑analyzer，然后test_writer，等test_writer完成后同时启动test_runner和reviewer。

实际跑下来，一个包含20个函数的模块，整个流程大约需要8-12分钟。其中分析代理耗时约1分钟，测试生成代理耗时约5分钟（生成40多个测试用例），测试执行和审查并行，各耗时2-3分钟。如果串行跑，总时间会多出2-3分钟。

4.3 跑通之后遇到的三个意外情况

第一个意外是分析代理的输出格式不稳定。有时候它输出纯JSON，有时候在JSON外面包了一层Markdown代码块标记。这导致测试生成代理解析失败。解决办法是在分析代理的提示词里明确要求“只输出JSON，不要任何额外格式”，同时在解析端加了容错逻辑，自动剥离代码块标记。

第二个意外是测试执行代理在沙箱里跑测试时超时。原因是沙箱默认没有安装项目依赖，测试执行代理第一次跑的时候花了大量时间在下载依赖上。后来我在沙箱镜像里预装了常用依赖，并且给测试执行代理加了“先检查依赖是否完整，不完整则先安装”的前置步骤。

第三个意外是审查代理和测试执行代理的结论冲突。审查代理认为某个测试用例的断言太宽松，建议加强；但测试执行代理报告这个测试通过了。主代理收到两个冲突的信号后，默认选择了“以审查代理为准”，把测试打回给测试生成代理修改。这个策略是我在配置里显式设置的——当审查和执行结果冲突时，优先信任审查代理，因为执行通过不代表测试质量合格。

5. 多代理工作流的边界与常见误区

多代理不是银弹，用不好反而比单代理更折腾。我总结了几个实际使用中容易踩的误区，以及对应的规避方法。

5.1 什么任务不适合拆成多代理

强实时交互的任务不适合。比如你在IDE里让助手帮你补全一行代码，这种场景下启动多代理调度的时间开销远大于收益。多代理适合的是“批处理”型任务——任务本身耗时较长，且可以分解成相对独立的子任务。

子任务之间耦合度极高的任务不适合。如果两个子任务需要频繁交换中间状态，拆成多代理后通信开销会吃掉并行带来的收益。判断标准很简单：如果两个子任务需要来回修改同一份数据超过三次，就不应该拆开。

探索性任务不适合。比如“帮我看看这个项目该怎么重构”，这种任务没有明确的目标结构，主代理很难做有效的任务分解。这种场景还是单代理边聊边探索更合适。

5.2 代理数量与调度开销的平衡

代理数量不是越多越好。每增加一个代理，主代理就多一份调度决策的负担，工作区的状态管理也更复杂。我实测下来，3-5个代理是比较舒服的区间。少于3个，并行收益不明显；多于5个，调度开销和调试难度上升很快。

如果你确实需要更多角色，可以考虑分层调度——主代理下面设几个“组长代理”，每个组长代理再管理几个“组员代理”。但分层调度会引入额外的通信层级，除非任务规模真的很大，否则不建议。

5.3 如何判断多代理是否真的提升了效率

不要凭感觉判断，要看数据。我一般关注三个指标：

• 端到端耗时：从任务发起到最终结果产出，多代理比单代理快了多少。如果快得不多（低于20%），说明任务分解或并行策略有问题。
• 返工率：子代理的输出被下游代理打回修改的比例。返工率高说明代理之间的接口约定不清晰，或者提示词需要优化。
• 人工介入次数：整个流程中你需要手动干预的次数。理想情况下，跑通之后应该接近零干预。如果经常需要你手动调整，说明调度逻辑还有硬伤。

我自己的经验是，多代理工作流在“代码生成+测试+审查”这类有明确阶段划分的任务上，效率提升最明显，端到端耗时能比单代理串行减少30%-40%。但在“调试一个复杂bug”这类需要反复试错的任务上，多代理反而更慢，因为每个代理都要重新建立上下文。

6. 从 Qwen Code 看编程助手协作的下一步

Qwen Code 把调度能力内置进来，释放了一个信号：编程助手正在从“单点工具”向“协作平台”演进。以前我们关心的是“哪个模型写代码强”，现在开始关心“怎么把多个助手组织起来干活”。这个转变背后是实际需求的推动——项目越来越复杂，单一助手很难在所有环节都保持高质量输出。

从热搜词也能看出，大家已经在自发探索多助手协作的各种基础设施：用 worktree 做工作区隔离，用沙箱做执行隔离，用第三方API接入不同模型来取长补短。Qwen Code 把这些零散的实践标准化了一步，但离“开箱即用”还有距离。

我目前的使用感受是，多代理工作流的上手门槛主要在配置和调试阶段。第一次搭的时候，光是调通代理之间的状态传递就花了大半天。但一旦跑通，后续复用就很省心了。如果你也在用类似的工作流，建议先把代理角色定义清楚，接口约定好，再开始写调度逻辑。顺序反了的话，后面改起来会很痛苦。

另外一个小技巧：给每个代理的输出加一个“置信度”字段。代理在输出结果时，顺便标注它对这个结果的把握程度（高/中/低）。主代理在调度下游任务时，可以根据置信度决定是否需要额外验证。比如测试生成代理对某个测试用例标注了“低置信度”，主代理可以自动触发审查代理重点检查那部分。这个机制我用了之后，返工率明显下降。