1. 从一问一答到任务闭环多 Agent 编排到底解决了什么用 Claude Code 写代码的人大概都经历过这个阶段打开终端敲一句需求等它吐出一段代码看一眼不满意再补一句这里改一下再等再改。整个过程像在跟一个反应很快但记性一般的实习生对话——单步、线性、上下文越聊越乱聊到第十轮的时候它已经忘了你第一轮说的约束条件。这就是单步聊天模式的天花板。它不是模型能力不够而是交互范式的问题所有信息都挤在一条对话流里规划、执行、验证、修正四个动作互相污染谁也没法专心干好自己的事。多 Agent 编排要解决的就是这个。它的核心思路很朴素把一件复杂的事拆成几个角色每个角色只对自己那一段负责角色之间通过明确的输入输出契约传递信息。规划的人不写代码写代码的人不做验收验收的人不负责修 bug——听起来像把一个人的活分给一个小组但关键在于这个小组的协作规则是你用脚本和配置写死的不依赖临场发挥。我自己的体感是单步聊天适合我知道要什么只是懒得敲的场景而多 Agent 编排适合我知道目标但路径需要探索、需要反复验证的场景。前者是打字加速器后者才是真正的工程化助手。1.1 单步模式的三个隐性成本很多人觉得单步聊天够用了是因为没算清楚它的隐性成本。我把它拆成三块上下文污染成本。一条对话流里你前面随口说的一句用 Python 写会一直挂在上下文里。等到后面你想让它生成一段 shell 脚本时它可能还在纠结 Python 的语法。上下文越长这种历史包袱越重模型的注意力被稀释输出质量肉眼可见地下降。验证缺失成本。单步模式下模型说改好了你只能自己去看、自己去跑。它没有动力去验证自己的输出因为对话范式里根本没有验证这个环节。结果就是你要反复当人肉编译器一遍遍把它的代码贴到终端里跑。状态丢失成本。聊到一半关掉终端或者上下文超限被截断之前积累的所有决策就没了。下次打开你得重新交代一遍背景。这在长任务里是致命的。1.2 多 Agent 编排的本质把对话变成流水线多 Agent 编排的本质是把非结构化的对话转换成结构化的流水线。每个 Agent 是一个处理节点节点之间有明确的输入输出格式整个流程可以被脚本驱动、被日志记录、被重复执行。这里有个关键认知Agent 之间的通信不应该是自然语言闲聊而应该是结构化的数据。比如规划 Agent 输出的不是一段我觉得你应该先做 A 再做 B的散文而是一个 JSON 数组里面每个元素包含任务描述、依赖关系、验收标准。执行 Agent 拿到这个数组逐条处理输出带状态标记的结果。验证 Agent 再拿着验收标准去核对。这种设计的好处是任何一环出问题你都能定位到具体的节点和具体的字段而不是在一大段对话里大海捞针。1.3 什么任务值得上多 Agent不是所有任务都值得。我的判断标准是三条任务能被拆成有依赖关系的子任务。如果一件事就是生成一段正则那单步就够了拆了反而增加开销。子任务之间有明确的验收标准。比如这个函数要能通过这三个测试用例标准越硬验证 Agent 越有用。任务需要多轮迭代。一次成型的事不需要闭环需要反复试错的事才需要。举个我实际用过的例子给一个老项目补单元测试。这件事天然可以拆成扫描代码找未覆盖函数 → 为每个函数生成测试 → 跑测试看是否通过 → 失败的重新生成。四个阶段每个阶段都有明确产出这就是典型的多 Agent 场景。2. 拆解 Claude Code 的多 Agent 编排骨架Claude Code 本身是一个终端里的编码助手它的多 Agent 能力不是靠一个多 Agent 按钮实现的而是靠子 Agent 调用 任务分解 结果聚合这套机制拼出来的。理解这套骨架比记住某个命令重要得多。2.1 主 Agent 与子 Agent 的职责边界在 Claude Code 的体系里主 Agent 扮演的是调度者角色子 Agent 扮演执行者角色。这个分工不是随便定的背后有明确的工程考量。主 Agent 掌握全局上下文知道整个任务的目标、约束、当前进度。它的职责是分解任务、分配任务、汇总结果。子 Agent 则被赋予一个相对封闭的子任务它不需要知道全局只需要把手头这件事做到位然后返回结构化结果。为什么要这样切因为上下文窗口是稀缺资源。如果所有子任务都在主 Agent 的上下文里执行那主 Agent 的上下文会被大量中间过程塞满很快就超限了。把子任务下放给子 Agent相当于给每个子任务开了一个临时工作区用完即弃主 Agent 的上下文始终保持清爽。我踩过的一个坑是一开始我让主 Agent 事无巨细地记录每个子 Agent 的完整输出结果跑了三个子任务上下文就爆了。后来改成子 Agent 只返回结论 关键证据主 Agent 只保留结论上下文压力立刻降下来。2.2 任务分解的粒度控制任务分解的粒度是个技术活。分得太粗子 Agent 还是得做一堆事等于没拆分得太细调度开销和通信开销会吃掉所有收益。我的经验法则是一个子任务应该能在一次独立的模型调用里完成且产出物可以用一两句话描述清楚。比如为 user_service.py 里的三个函数生成 pytest 测试就是一个合适的粒度重构整个后端就太粗给 login 函数加一行注释就太细。还有一个容易被忽略的点子任务之间尽量保持无状态。也就是说子 Agent A 的输出不应该依赖子 Agent B 的中间状态而应该依赖主 Agent 明确传给它的输入。这样做的好处是子任务可以并行、可以重试、可以替换整个流程的鲁棒性会高很多。2.3 结果聚合与冲突消解多个子 Agent 跑完之后结果汇总到主 Agent 这里经常会出现冲突。比如两个子 Agent 都改了同一个文件或者一个子 Agent 说这个函数没问题另一个说这个函数有 bug。这时候主 Agent 需要一套冲突消解规则。我常用的策略是优先级 证据权重验证类 Agent 的结论优先于生成类 Agent 的结论因为验证是后置的、更接近事实的带具体证据比如测试输出、报错信息的结论优先于纯主观判断。如果冲突实在无法自动消解主 Agent 应该把冲突点明确抛出来交给人来判断而不是自己瞎猜一个。这一点很重要——自动化流程最怕的不是报错而是悄悄做了一个错误的决定。3. 闭环自愈让 Agent 自己发现并修复问题多 Agent 编排如果只做到分解任务、并行执行、汇总结果那它只是一个批处理系统。真正让它从批处理升级到智能体的是闭环自愈——Agent 能自己发现执行结果不符合预期并主动发起修复。3.1 自愈闭环的四个环节一个完整的自愈闭环包含四个环节执行 → 检测 → 诊断 → 修复。执行环节产出结果检测环节判断结果是否达标诊断环节分析为什么不达标修复环节针对原因做修正。四个环节首尾相接形成一个循环直到检测通过或者达到重试上限。这里的关键是检测环节必须有客观标准。如果检测靠模型自己感觉对不对那闭环就是假的因为模型很容易自我感觉良好。客观标准可以是测试用例是否通过、编译是否成功、lint 是否报错、输出是否符合预定义的 schema。我见过不少人搭的自愈流程检测环节就是让模型自己说一句看起来没问题然后流程就结束了。这种自愈等于没有因为模型根本不会主动承认自己错了。3.2 检测信号的来源设计检测信号从哪来我总结了几个可靠的来源按可靠性从高到低排信号来源可靠性适用场景注意事项测试用例执行结果极高有测试覆盖的代码测试本身要可信编译/构建结果极高强类型语言只验证语法不验证逻辑Lint/静态检查高代码规范规则要配置合理Schema 校验高结构化输出schema 要覆盖关键字段模型自评低无客观标准的场景只能作为辅助信号实际用的时候我一般会组合两到三种信号。比如代码生成任务先用编译结果做第一道筛再用测试用例做第二道筛最后用 lint 做风格检查。三道都过了才算通过。3.3 诊断环节从报错到根因检测环节告诉你失败了诊断环节要告诉你为什么失败。这两件事的难度差了一个数量级。诊断的核心方法是把失败信息结构化。比如测试失败不要只把AssertionError丢给模型而要把失败的测试名、期望值、实际值、相关代码片段一起打包。信息越完整诊断越准确。我常用的一个技巧是让诊断 Agent 先复述问题再给假设。具体做法是要求它先用自己的话描述发生了什么然后列出可能的原因最后给出最可能的原因及验证方法。这个复述步骤能显著降低它瞎猜的概率因为复述过程本身就是在强迫它理解问题。3.4 修复策略重试、回退还是换路诊断出原因之后修复策略有三种重试原因明确且是偶发的比如网络超时、临时资源占用直接重跑就行。回退当前路径走不通退回到上一个稳定状态换一种方式再试。比如某个函数怎么改都过不了测试那就回退到原始版本换一个实现思路。换路整个方案有问题需要重新规划。这时候要把控制权交回主 Agent让它重新分解任务。这三种策略的选择我一般设一个简单的规则同一原因连续失败两次就升级策略。第一次失败重试第二次失败回退第三次失败换路。这样能避免在死胡同里无限重试。提示重试次数一定要设上限。我见过有人设了 10 次重试结果一个死循环跑了半小时烧了一堆 token 什么也没产出。我的习惯是单点重试不超过 3 次整体循环不超过 5 轮。4. Routine 脚本化把一次性编排变成可复用资产多 Agent 编排搭好之后如果每次都要手动敲一遍流程那它的价值就大打折扣。Routine 脚本化的意义是把编排流程固化成可重复执行的脚本让它从一次性操作变成可复用资产。4.1 为什么需要脚本化而不是记住流程有人会说流程我都记住了每次照着做不就行了。问题在于人记住的流程是模糊的脚本记录的流程是精确的。模糊的流程里检查一下代码质量这句话今天你可能检查了 lint明天可能只看了两眼。而脚本里写死的检查步骤每次执行都一模一样。这种一致性是自动化流程可靠性的基础。另外脚本化之后流程可以被版本管理。你今天优化了一个检测步骤明天可以对比优化前后的效果。这种可迭代性是手动流程给不了的。4.2 Routine 的结构触发、步骤、退出条件一个 Routine 脚本我一般拆成三部分触发条件什么情况下启动这个 Routine。可以是手动触发也可以是某个事件触发比如检测到新提交的代码。步骤序列Routine 的主体一系列有序的 Agent 调用和数据处理步骤。每一步都要明确输入、输出、失败处理。退出条件什么情况下结束。正常结束是所有步骤成功完成异常结束是达到重试上限或遇到不可恢复错误。这三部分里退出条件最容易被忽略但最重要。没有明确退出条件的 Routine很容易变成僵尸流程卡在那里既不出结果也不报错。4.3 参数化让一个 Routine 适配多种场景写死的 Routine 只能干一件事参数化的 Routine 能干一类事。参数化的关键是把变化的部分抽出来把不变的部分固化。比如一个代码审查Routine不变的是扫描 → 分析 → 生成报告这个流程变化的是扫描哪些文件用什么规则分析报告输出到哪。把这些变化的部分做成参数一个 Routine 就能适配不同的项目。参数设计有个原则参数要少而精。参数太多调用的时候容易搞混参数太少灵活性不够。我的经验是一个 Routine 的核心参数控制在 3 到 5 个比较合适。4.4 一个可落地的 Routine 骨架示例下面是我常用的一个 Routine 骨架用伪代码表示你可以根据自己的工具链替换具体实现def code_review_routine(target_path, rules, max_retry3): # 步骤1扫描目标文件 files scan_files(target_path) if not files: return {status: empty, message: 没有找到待审查文件} # 步骤2逐文件分析 results [] for f in files: retry 0 while retry max_retry: analysis analyze_agent(f, rules) if validate_schema(analysis): results.append(analysis) break retry 1 else: results.append({file: f, status: failed, reason: 分析结果不符合schema}) # 步骤3汇总报告 report aggregate_agent(results) return {status: done, report: report}这个骨架里validate_schema就是检测环节while retry就是自愈闭环aggregate_agent就是结果聚合。三个机制串起来就是一个最小可用的 Routine。5. 实战中的坑编排、自愈、脚本化各自的雷区理论讲完了说说实战。这三块我都在真实项目里踩过坑有些坑还挺隐蔽的。5.1 编排的坑子 Agent 越权与信息泄漏子 Agent 越权指的是子 Agent 做了超出它职责范围的事。比如一个生成测试的子 Agent顺手把被测函数也改了。这种越权在单步模式下不明显但在多 Agent 模式下会引发连锁反应——下游的验证 Agent 拿到的是被改过的代码验证结果就不可信了。防范方法是给子 Agent 明确的权限边界。在 prompt 里写清楚你只能修改测试文件不能修改被测代码并且在流程层面做检查——如果发现被测代码被改了直接判定这一步失败。信息泄漏是另一个坑。子 Agent 之间如果共享了不该共享的信息会导致结果互相污染。比如两个子 Agent 都在做代码审查如果它们能看到对方的中间结论就可能产生从众效应第二个 Agent 倾向于附和第一个。解决办法是子 Agent 之间不直接通信所有信息通过主 Agent 中转。5.2 自愈的坑无限循环与假性通过无限循环前面提过这里说个更隐蔽的假性通过。假性通过是指检测环节显示通过但实际上问题没解决。常见原因有三种检测标准太松、检测覆盖不全、检测本身有 bug。我遇到过一次测试用例全过了但上线后立刻出问题。排查发现测试用例是我让模型生成的而模型生成的测试用例恰好避开了有 bug 的分支。这就是典型的检测覆盖不全——测试通过了但没测到关键路径。防范假性通过的方法是引入独立的验证源。比如模型生成的测试用例再用另一套规则做交叉验证或者关键路径上强制要求人工确认。自动化流程里任何单一检测源都不应该被完全信任。5.3 脚本化的坑硬编码与版本漂移脚本化最常见的坑是硬编码。路径写死、模型名写死、参数写死换个环境就跑不起来。比硬编码更隐蔽的是版本漂移。脚本里调用的某个工具升级了接口变了脚本没跟着改跑起来就报错。或者模型的行为变了之前能通过的检测现在过不了。应对版本漂移我的做法是在脚本里加版本检查。启动时先检查依赖工具的版本不符合要求就明确报错而不是跑到一半才崩。另外关键流程的脚本要定期回归测试确保它还能正常工作。6. 从单步到编排我的迁移路径与取舍最后说说迁移。从单步聊天迁移到多 Agent 编排不是一蹴而就的我自己的路径大概分了三步。6.1 第一步把重复的单步操作脚本化最开始不要急着上多 Agent。先观察自己哪些单步操作是重复的把它们脚本化。比如生成测试 → 跑测试 → 报告结果这个流程如果每天都要做就值得写成一个脚本。这一步的收益是立竿见影的而且风险低——脚本化只是把手动操作自动化不涉及多 Agent 的复杂性。6.2 第二步引入验证环节建立最小闭环脚本化之后下一步是引入验证。在脚本的关键节点加上检测让流程能自己判断这一步做对了没有。这一步的难点在于设计检测标准。我的建议是从最硬的检测开始比如编译结果、测试结果这些不需要模型判断直接看退出码就行。等硬检测跑通了再逐步引入软检测。6.3 第三步拆分角色引入多 Agent有了闭环之后再考虑拆分角色。把执行和验证拆成两个 Agent让它们各司其职。这一步的收益是质量提升但成本也上来了——多一个 Agent 就多一份调用开销和协调复杂度。我的取舍标准是只有当单 Agent 的上下文压力明显影响质量时才拆多 Agent。如果单 Agent 能搞定就别拆。多 Agent 不是目的是手段。6.4 什么情况下应该退回单步最后说个反直觉的有些场景应该从多 Agent 退回单步。比如任务很简单、一次就能做对的事上多 Agent 纯属浪费。或者任务需要高度创造性的探索多 Agent 的流程约束反而会限制发挥。再或者调试阶段你需要快速试错多 Agent 的流程太重不如单步来得灵活。我自己的判断是多 Agent 适合流程明确、需要反复验证的任务单步适合探索性强、一次成型的任务。两者不是替代关系是互补关系。工具箱里两把工具都有看菜下饭才是正道。这套东西我陆陆续续搭了小半年最大的体会是编排的价值不在于 Agent 多而在于每个环节的职责清晰、接口明确、验证可靠。一个设计良好的三 Agent 流程比一个混乱的十 Agent 流程有用得多。如果你刚开始尝试建议从一个最小的闭环做起——哪怕只有执行 检测两个环节只要检测是硬的、闭环是通的它就已经比单步聊天强了。