★ FEATURED ARTICLE 1. 从单步对话到多 Agent 协作这套架构到底解决了什么问题如果你用过一段时间的 Claude Code大概率经历过这样的场景让它改一个稍微复杂点的功能你得先让它读文件、再让它分析、然后让它改代码、接着让它跑测试、最后还得自己盯着它有没有改错。整个过程就像带一个实习生每一步都要你手动推一下。单步聊天模式的效率瓶颈不在于模型不够聪明而在于整个交互范式是“你问我答”的线性结构缺少任务分解、并行执行和失败重试的机制。我最初接触 Claude Code 的时候也是这么用的一个终端窗口敲一句指令等它回复再敲下一句。后来项目复杂度上来了一个需求涉及五六个文件、两三个模块的联动修改这种单步模式就彻底不够用了。你会在反复的“确认-执行-检查”循环里消耗大量时间而且一旦某一步出错整个上下文就乱了得从头再来。多 Agent 编排要解决的核心问题就是这个。它把一个大任务拆成若干子任务每个子任务交给一个独立的 Agent 去执行Agent 之间通过消息传递和状态共享来协作。更关键的是它引入了闭环自愈机制——某个 Agent 执行失败后系统能自动检测错误、分析原因、重新分配任务或调整策略而不是直接把错误抛给你。Routine 脚本化则是把这套流程固化下来让重复性的工作可以一键触发不用每次重新编排。这套架构适合谁如果你只是偶尔用 Claude Code 写个脚本、改个配置单步模式完全够用。但如果你在维护一个中等规模以上的代码库每天有大量重复性的开发任务比如代码审查、测试生成、依赖更新、文档同步或者你在构建需要多步骤推理的自动化流程那多 Agent 编排带来的效率提升是数量级的。我实测下来一个原本需要手动操作二十多分钟的代码重构任务编排好之后三分钟左右就能跑完而且中间不需要人工干预。下面我会从架构设计、核心组件、实操配置、问题排查几个维度把这套东西拆开讲清楚。内容会涉及 Claude Code 的安装配置、多 Agent 的编排逻辑、闭环自愈的实现方式、Routine 脚本的编写技巧以及我在实际使用中踩过的坑和总结的经验。2. 多 Agent 编排的架构设计与核心思路2.1 为什么单 Agent 模式会撞墙单 Agent 模式的本质是一个“请求-响应”循环。你给一个指令模型生成回复你看了回复再给下一个指令。这个模式在简单任务上没问题但遇到复杂任务时会出现几个致命问题。第一个问题是上下文窗口的浪费。当你让一个 Agent 同时处理“读代码、分析逻辑、修改实现、跑测试”这四件事时它需要在一次对话里承载所有信息。代码文件的内容、分析结论、修改方案、测试输出全部堆在上下文里很快就会把窗口撑满。一旦窗口满了早期的关键信息就被挤掉了模型开始“失忆”改出来的代码跟前面的分析对不上。第二个问题是错误传播。单 Agent 模式下如果第一步读文件读错了比如读了一个过时的版本后面的分析、修改、测试全部建立在错误的基础上。你很难在中间某个环节发现这个问题往往要等到最后跑测试失败了才回头查排查成本很高。第三个问题是无法并行。有些子任务之间没有依赖关系比如“给模块 A 写单元测试”和“给模块 B 写单元测试”完全可以同时进行。但单 Agent 是线性的只能一个一个来时间全浪费在等待上。多 Agent 编排就是针对这三个问题的解法。每个 Agent 有自己独立的上下文窗口只关注自己负责的那部分信息Agent 之间有明确的输入输出契约一个 Agent 的输出是另一个 Agent 的输入错误可以在交接点被检测到无依赖的 Agent 可以并行执行整体耗时取决于最长的那个分支而不是所有步骤的总和。2.2 编排层的三种典型拓扑在实际落地中多 Agent 的编排拓扑主要有三种串行链、并行扇出、以及带条件分支的 DAG。串行链是最简单的Agent A 的输出直接喂给 Agent BB 的输出喂给 C。适合有严格先后依赖的任务比如“先分析代码结构再根据分析结果生成修改方案最后执行修改”。这种拓扑的优点是逻辑清晰、调试容易缺点是没有任何并行度总耗时是各步骤之和。并行扇出是指一个调度 Agent 把任务拆成多个子任务分发给多个执行 Agent 同时处理最后再汇总结果。比如代码审查场景可以同时启动三个 Agent分别检查代码风格、安全漏洞、性能问题最后合并成一份审查报告。这种拓扑的耗时取决于最慢的那个 Agent理论上比串行快很多。带条件分支的 DAG 是最灵活的Agent 之间的依赖关系形成一个有向无环图某些 Agent 只在特定条件下才触发。比如“如果测试失败则启动修复 Agent如果测试通过则直接进入部署 Agent”。这种拓扑最接近真实开发流程但编排逻辑也最复杂需要仔细设计状态机和条件判断。我自己的项目里用得最多的是并行扇出加条件分支的混合模式。主干流程是串行的但在代码审查和测试生成这两个环节会扇出多个 Agent 并行处理然后根据测试结果决定是否触发修复分支。2.3 Agent 之间的通信机制Agent 之间怎么传递信息这是编排架构里最关键的细节之一。常见的方式有三种共享文件系统、消息队列、以及共享内存状态。共享文件系统是最直观的。每个 Agent 把自己的输出写到指定的文件里下一个 Agent 从文件里读。优点是实现简单、可追溯所有中间结果都落盘了、跨进程也能用。缺点是 I/O 开销大而且需要约定好文件格式和路径规范不然容易乱。消息队列适合 Agent 数量多、通信频繁的场景。每个 Agent 监听一个队列收到消息就处理处理完把结果发到下一个队列。优点是解耦彻底、支持异步、容易扩展。缺点是需要额外维护消息中间件对于小规模项目来说有点重。共享内存状态是性能最好的所有 Agent 读写同一块内存区域。但实现复杂度高需要处理并发读写的问题而且一旦进程崩溃状态就丢了。我在实际项目中用的是共享文件系统加轻量级状态文件的组合。每个 Agent 的输出写到artifacts/目录下用一个state.json记录当前流程走到哪一步、哪些 Agent 已完成、哪些失败了。这个方案的好处是调试特别方便出问题了直接去看文件就行不用去翻日志或者查队列。注意不管用哪种通信机制一定要给 Agent 之间的消息定义严格的 schema。我早期偷懒没定义格式结果上游 Agent 输出的是 Markdown 列表下游 Agent 以为是 JSON 数组去解析直接报错。后来强制用 JSON Schema 校验这类问题就再也没出现过。3. 闭环自愈机制的实现细节3.1 什么是闭环自愈为什么需要它闭环自愈指的是系统在检测到 Agent 执行失败后能够自动分析失败原因、调整执行策略、重新尝试直到成功或者达到重试上限。这个机制的价值在于把“人工介入”从流程中移除让自动化流程真正能无人值守地跑下去。没有闭环自愈的编排系统本质上还是一个“半自动”工具。Agent 跑失败了你得去看日志、分析原因、手动修改参数、重新触发。如果失败率有百分之二三十那省下来的时间又都花在排查上了。闭环自愈的核心组件有三个失败检测、原因分析、策略调整。失败检测负责判断一个 Agent 是不是真的失败了有时候 Agent 会“假装成功”输出一堆看起来像结果但实际上是废话的内容原因分析负责从错误信息、日志、输出内容里推断失败的根本原因策略调整负责根据原因决定下一步怎么做——是重试、换一个 Agent、还是回退到上一个步骤重新来。3.2 失败检测的三种信号失败检测不能只看 Agent 有没有抛异常。很多失败是“软失败”——Agent 正常返回了但返回的内容不符合预期。我通常从三个维度来检测失败。第一个维度是退出码和异常。这是最直接的信号Agent 进程非零退出、抛了未捕获的异常、或者超时了都算硬失败。这类失败容易检测但只占所有失败的一部分。第二个维度是输出格式校验。Agent 的输出必须符合预定义的 schema比如必须是合法的 JSON、必须包含某些必填字段、字段类型必须正确。如果输出格式不对说明 Agent 没有按照预期执行即使它没报错也算失败。第三个维度是内容质量校验。这个最难自动化但可以用一些启发式规则来近似。比如检查输出是否为空、是否包含“我无法完成”“抱歉”之类的拒绝性语言、是否和输入高度重复说明 Agent 没做实质处理。我还会用一个小模型或者规则引擎对输出做快速打分低于阈值就判定为失败。3.3 原因分析与策略调整检测到失败之后下一步是分析原因。我把失败原因分成几类每类对应不同的处理策略。第一类是瞬时错误比如网络超时、API 限流、临时文件锁冲突。这类错误重试就能解决策略就是简单重试加上指数退避。第二类是输入问题比如上游 Agent 输出的内容格式不对、缺少必要信息、或者内容本身有歧义。这类错误重试没用需要回退到上游 Agent 重新生成或者插入一个“修复 Agent”来修正输入。第三类是能力问题比如当前 Agent 的模型能力不足以完成这个任务、prompt 写得不够清晰、或者任务本身超出了预设范围。这类错误需要换 Agent、换模型、或者调整 prompt 后重试。第四类是环境问题比如依赖缺失、权限不足、磁盘满了。这类错误需要先修复环境再重试。我在实现的时候给每种失败原因定义了一个处理函数检测到失败后先分类再调用对应的处理函数。分类的逻辑可以用规则匹配根据错误信息里的关键词也可以用一个小模型来做判断。规则匹配更快更可控我目前主要用规则匹配只有规则覆盖不到的情况才 fallback 到模型判断。3.4 重试上限与熔断机制闭环自愈不能无限重试否则一个死循环能把资源全耗光。我一般设置三层保护。第一层是单个 Agent 的重试上限默认三次。同一个 Agent 连续失败三次就不再重试了直接标记为失败并向上报。第二层是流程级别的重试上限默认两次。整个流程如果跑了两遍还是失败就停止自愈把控制权交还给人工。第三层是熔断机制。如果某个 Agent 在短时间内失败率超过阈值比如五分钟内失败了十次就自动熔断暂停所有相关任务避免雪崩。实操心得重试的时候一定要记录每次重试的输入和输出。我遇到过一个问题Agent 重试了三次都失败但每次失败的原因都不一样第一次是超时第二次是格式错误第三次是内容质量不达标。如果不记录每次的详情根本没法定位根因。后来我在 state.json 里加了一个retry_history字段每次重试都追加一条记录排查效率高了很多。4. Routine 脚本化把编排流程固化下来4.1 Routine 的本质是什么Routine 脚本化说白了就是把编排好的多 Agent 流程写成一个可重复执行的脚本。你定义好任务拆解逻辑、Agent 之间的依赖关系、失败处理策略然后把它保存成一个文件。下次遇到类似的任务直接运行这个脚本就行不用重新编排。这听起来简单但实际做的时候有几个关键决策点。第一个是脚本的粒度——是每个具体任务写一个脚本还是写一个通用的脚本模板通过参数来适配不同任务第二个是脚本的触发方式——是手动运行还是绑定到某个事件上自动触发第三个是脚本的版本管理——流程改了之后怎么追踪变更、怎么回滚我的做法是通用逻辑写成模板具体任务通过配置文件来定义。比如我有一个code_review.routine模板里面定义了“读取变更文件 - 并行执行风格检查/安全检查/性能检查 - 汇总报告 - 如果发现问题则生成修复建议”这个流程。具体使用时通过一个 YAML 配置文件指定要审查哪些文件、用哪些检查规则、报告输出到哪里。这样模板可以复用配置可以灵活调整。4.2 脚本的结构设计一个 Routine 脚本通常包含四个部分元信息、Agent 定义、流程定义、以及错误处理策略。元信息部分记录脚本的名称、版本、作者、适用场景。这部分看起来是形式主义但实际很有用。当你有几十个 Routine 脚本的时候没有元信息根本记不住哪个是干什么的。Agent 定义部分声明这个流程里用到了哪些 Agent每个 Agent 的类型、模型、prompt 模板、输入输出 schema。这部分是脚本的核心Agent 定义得好不好直接决定流程能不能跑通。流程定义部分描述 Agent 之间的依赖关系和执行顺序。我用的是一种类似 DSL 的写法用简单的关键字来描述串行、并行、条件分支。比如sequence表示串行parallel表示并行if表示条件分支。错误处理策略部分定义每个 Agent 失败后怎么处理是重试、跳过、还是终止整个流程。这部分可以继承全局默认策略也可以针对特定 Agent 覆盖。4.3 一个完整的 Routine 脚本示例下面是一个代码审查场景的 Routine 脚本示例用 YAML 格式编写。这个脚本定义了“读取 Git 变更 - 并行执行三个检查 Agent - 汇总结果 - 如果有严重问题则生成修复建议”的完整流程。routine: name: code_review version: 1.2.0 description: 对 Git 暂存区的变更执行多维度代码审查 agents: - name: diff_reader type: file_reader config: source: git_staged output_format: json output_schema: files: array total_lines: integer - name: style_checker type: code_analyzer prompt_template: prompts/style_check.md input_from: diff_reader output_schema: issues: array severity: string - name: security_checker type: code_analyzer prompt_template: prompts/security_check.md input_from: diff_reader output_schema: vulnerabilities: array risk_level: string - name: performance_checker type: code_analyzer prompt_template: prompts/performance_check.md input_from: diff_reader output_schema: bottlenecks: array impact: string - name: report_aggregator type: aggregator input_from: [style_checker, security_checker, performance_checker] output_format: markdown - name: fix_suggester type: code_generator condition: report_aggregator.has_critical_issues true input_from: report_aggregator output_format: diff flow: - sequence: - diff_reader - parallel: - style_checker - security_checker - performance_checker - report_aggregator - fix_suggester error_handling: default: retry: 3 backoff: exponential on_final_failure: abort overrides: - agent: style_checker on_final_failure: skip - agent: fix_suggester on_final_failure: notify_only这个脚本里diff_reader先读取 Git 暂存区的变更输出结构化的文件列表和行数信息。然后三个检查 Agent 并行执行分别从风格、安全、性能三个维度分析代码。report_aggregator把三个检查结果汇总成一份 Markdown 报告。最后fix_suggester只在报告里包含严重问题时才触发生成修复建议的 diff。错误处理部分默认策略是重试三次、指数退避、最终失败则终止流程。但style_checker被覆盖为“最终失败则跳过”因为风格问题不是阻塞性的。fix_suggester被覆盖为“最终失败只通知不终止”因为修复建议是锦上添花失败了也不影响主流程。4.4 脚本的触发与调度Routine 脚本写好了怎么触发它我目前用了三种方式。第一种是手动触发直接在终端里运行claude-code routine run code_review。适合开发阶段调试和临时使用。第二种是绑定到 Git hook 上。比如在pre-commit钩子里调用代码审查 Routine每次提交前自动跑一遍有问题就阻止提交。这种方式能把质量控制前置避免有问题的代码进入仓库。第三种是定时调度。比如每天凌晨跑一遍依赖更新检查的 Routine有更新就自动生成 PR。这种方式适合那些不需要实时响应、但需要定期执行的任务。注意绑定到 Git hook 的时候一定要设置超时。我遇到过 Routine 卡住导致 commit 一直挂起的情况后来加了 60 秒超时超时后自动跳过检查并给出警告不阻塞正常提交。5. 环境搭建与 Claude Code 配置实操5.1 安装 Claude Code 的几种方式Claude Code 的安装方式取决于你的操作系统和使用场景。我分别在 macOS、Ubuntu 和 Windows 上都装过下面把每种方式的要点说一下。macOS 上最简单的方式是用 Homebrew。一条命令brew install claude-code就能搞定装完之后claude --version验证一下。如果你用 npm 生态比较多也可以用npm install -g anthropic-ai/claude-code来装。两种方式我都试过Homebrew 装的好处是升级方便brew upgrade就全搞定了npm 装的好处是版本切换灵活可以用 nvm 管理多个版本。Ubuntu 上推荐用官方的安装脚本或者直接下载二进制包。用脚本安装的话它会自动检测系统架构、下载对应的二进制、配置环境变量。手动装的话下载下来解压把可执行文件放到/usr/local/bin/下面然后chmod x给执行权限。Ubuntu 上需要注意的是依赖库的问题如果提示缺少libssl之类的用apt-get install补上就行。Windows 上的情况稍微复杂一点。官方提供了桌面版安装包直接下载 exe 文件双击安装就行。但如果你习惯用命令行可以在 WSL2 里面按照 Ubuntu 的方式装。我两种都试过WSL2 里面的体验更接近 Linux 原生环境脚本兼容性更好桌面版的好处是跟 Windows 文件系统的集成更顺畅不用折腾路径映射。5.2 VS Code 插件的配置要点Claude Code 的 VS Code 插件是我日常用得最多的形态因为它能直接读取当前打开的文件和光标位置交互效率比纯终端高很多。安装插件之后第一件事是配置 API 连接。在 VS Code 的设置里搜索claude-code找到Api Endpoint和Api Key两个配置项。如果你用的是官方服务Endpoint 保持默认就行Key 填你自己的。如果你要接入第三方模型或者本地模型Endpoint 改成对应的地址。这里重点说一下接入本地模型的配置。我试过用 LM Studio 跑本地模型然后让 Claude Code 调用配置方式是在 VS Code 设置里把 Endpoint 改成http://localhost:1234/v1LM Studio 的默认端口然后在模型名称那里填你在 LM Studio 里加载的模型标识。需要注意的是不是所有本地模型都能很好地支持 Claude Code 需要的 function calling 和长上下文我实测下来 7B 以下的模型基本没法用13B 以上的效果会好一些但跟云端模型还是有差距。还有一个常见问题是插件版本和 CLI 版本不匹配。VS Code 插件有时候会自带一个内置的 CLI如果你系统里也装了一个 CLI两个版本不一致就会出各种奇怪的问题。我的做法是统一用系统安装的 CLI在插件设置里把Use System CLI打开避免版本冲突。5.3 多 Agent 编排的依赖准备要跑多 Agent 编排除了 Claude Code 本身还需要准备几样东西。第一是任务队列或者状态管理工具。我用的是最简单的文件系统方案但如果你要跑大规模的并行 Agent建议上 Redis 或者 SQLite 来做状态管理。Redis 的好处是快、支持原子操作、有现成的队列数据结构SQLite 的好处是零依赖、单文件、方便备份。第二是日志收集。多 Agent 并行跑的时候日志是混在一起的没有好的收集机制根本没法排查问题。我的做法是每个 Agent 的日志写到独立文件文件名里带上 Agent 名称和时间戳然后用一个汇总脚本把所有日志按时间线合并。第三是资源隔离。多个 Agent 同时跑的时候如果它们都要读写同一批文件很容易冲突。我的做法是给每个 Agent 分配独立的工作目录Agent 之间的文件传递通过显式的复制操作来完成而不是让它们直接操作同一份文件。5.4 一个最小可用的多 Agent 编排配置下面是一个最小可用的多 Agent 编排配置示例展示了如何用 Claude Code 的 CLI 来启动多个 Agent 并让它们协作。#!/bin/bash # multi_agent_demo.sh # 一个最小可用的多 Agent 编排示例 WORK_DIR./agent_workspace mkdir -p $WORK_DIR/{input,output,logs} # Agent 1: 读取并分析代码 claude --agent-name analyzer \ --input $WORK_DIR/input/source.py \ --output $WORK_DIR/output/analysis.json \ --prompt 分析这个 Python 文件的代码结构输出 JSON 格式的分析结果 \ --log $WORK_DIR/logs/analyzer.log ANALYZER_PID$! # Agent 2: 生成测试用例依赖 Agent 1 的输出 wait $ANALYZER_PID if [ $? -ne 0 ]; then echo Analyzer failed, aborting exit 1 fi claude --agent-name test_generator \ --input $WORK_DIR/output/analysis.json \ --output $WORK_DIR/output/tests.py \ --prompt 根据代码分析结果生成单元测试 \ --log $WORK_DIR/logs/test_generator.log TEST_PID$! # Agent 3: 生成文档与 Agent 2 并行 claude --agent-name doc_generator \ --input $WORK_DIR/output/analysis.json \ --output $WORK_DIR/output/README.md \ --prompt 根据代码分析结果生成文档 \ --log $WORK_DIR/logs/doc_generator.log DOC_PID$! wait $TEST_PID $DOC_PID echo All agents completed这个脚本展示了串行和并行的混合编排。analyzer先跑它的输出是后面两个 Agent 的输入。test_generator和doc_generator并行执行因为它们之间没有依赖关系。每个 Agent 的日志写到独立文件方便排查。实操心得wait命令在 bash 里等的是进程退出但 Claude Code 的 Agent 有时候会正常退出但实际没完成任务比如输出了错误信息但退出码是 0。所以光靠wait和退出码不够还需要在 Agent 完成后检查输出文件是否存在、内容是否符合预期。我在脚本里加了一个validate_output函数来做这个检查。6. 常见问题与排查技巧实录6.1 Agent 输出格式不符合预期这是最常见的问题表现是下游 Agent 解析上游输出时报错。根因通常是上游 Agent 的 prompt 没有把输出格式约束清楚或者模型没有严格遵循格式要求。排查思路先看上游 Agent 的实际输出是什么跟预期的 schema 对比找出差异点。如果是格式完全不对检查 prompt 里有没有明确指定输出格式如果是格式基本对但某些字段缺失检查 prompt 里有没有说明这些字段是必填的。解决方法是双管齐下一方面在 prompt 里用更明确的指令约束格式比如“输出必须是合法的 JSON不要包含任何 Markdown 代码块标记不要添加解释性文字”另一方面在下游 Agent 里加格式校验和自动修复逻辑比如用 JSON Schema 校验校验失败时尝试自动修复去掉代码块标记、补全缺失字段的默认值。6.2 Agent 执行超时超时的原因有很多模型响应慢、任务太复杂、网络问题、或者 Agent 陷入了死循环。排查的时候先看日志确定超时发生在哪个阶段。如果是模型调用阶段超时检查网络连接和 API 限流情况如果是 Agent 内部处理超时检查是不是任务拆解得不够细单个 Agent 承担了太多工作。我的处理策略是分层设置超时单个模型调用超时 60 秒单个 Agent 总执行时间超时 300 秒整个流程超时 1800 秒。任何一层超时都触发对应的处理逻辑——模型调用超时则重试Agent 超时则标记失败并进入自愈流程流程超时则终止并通知。6.3 并行 Agent 之间的资源冲突多个 Agent 同时读写同一批文件时会出现文件锁冲突、内容覆盖、状态不一致等问题。我踩过的一个坑是两个 Agent 同时往同一个日志文件里写结果日志内容交错在一起完全没法看。后来改成每个 Agent 写独立日志文件问题就解决了。另一个坑是两个 Agent 同时修改同一个代码文件后写的覆盖了先写的。这个问题的解法是给文件加锁或者让 Agent 操作文件的副本最后再合并。我目前用的是副本方案每个 Agent 在自己的工作目录里操作完成后由汇总 Agent 统一合并。6.4 自愈机制误判自愈机制有时候会把正常的输出误判为失败触发不必要的重试。比如 Agent 输出了一段包含“无法”这个词的正常文本但检测规则里把“无法”当成了失败信号。解决方法是让检测规则更精确。不要用单个关键词来判断而是用组合条件。比如“输出为空”或者“输出包含‘我无法完成’且长度小于 50 字符”才判定为失败。另外给自愈机制加一个“人工确认”模式在不确定的时候先暂停让人来判断是不是真的失败了。6.5 常见问题速查表问题现象可能原因排查方法解决方案下游 Agent 解析失败上游输出格式不对查看上游实际输出加强 prompt 格式约束加 schema 校验Agent 执行超时任务太复杂或网络慢查看日志确定超时阶段拆分任务分层设置超时文件内容被覆盖并行 Agent 写同一文件检查文件修改时间使用独立工作目录最后合并自愈频繁误触发检测规则太宽松查看误判案例收紧检测条件加人工确认模式Agent 输出为空prompt 不清晰或模型问题检查 prompt 和模型状态优化 prompt换模型重试流程卡住不结束某个 Agent 死循环查看进程状态和日志设置流程级超时强制终止6.6 几个我踩过的坑和对应的解法第一个坑是 Agent 名称冲突。我早期给 Agent 起名字很随意结果两个不同的 Routine 里用了同一个 Agent 名称状态文件互相覆盖。后来强制要求 Agent 名称全局唯一命名规范是routine_name.agent_name。第二个坑是日志文件无限增长。跑了一段时间之后日志文件涨到了几个 G磁盘直接满了。后来加了日志轮转每个日志文件最大 100MB超过就自动切分保留最近七个文件。第三个坑是环境变量污染。我在一个终端里设置了 API Key 的环境变量然后在这个终端里跑了多个 Agent结果所有 Agent 都用了同一个 Key。后来改成每个 Agent 启动时显式传入配置不依赖全局环境变量。第四个坑是重试时的状态残留。Agent 失败后重试但上一次执行留下的临时文件还在导致重试时读到了脏数据。后来在每次重试前加了一个清理步骤把该 Agent 工作目录下的临时文件全部删掉再重新开始。7. 从单步到编排的迁移路径建议如果你现在还在用单步模式想迁移到多 Agent 编排我的建议是不要一步到位分三个阶段来。第一阶段是“半自动化”。保持单步交互但把重复性的操作写成脚本。比如每次都要执行的“读文件-分析-改代码-跑测试”这个流程写成一个 shell 脚本用 Claude Code 的 CLI 来调用。这个阶段的目标是熟悉 CLI 的用法和参数理解 Agent 的基本行为。第二阶段是“串行编排”。把脚本里的多个步骤拆成独立的 Agent用串行的方式串联起来。每个 Agent 只做一件事输出写到文件里下一个 Agent 从文件里读。这个阶段的目标是理解 Agent 之间的通信和依赖关系学会定义输入输出 schema。第三阶段是“并行加自愈”。在串行编排的基础上把无依赖的 Agent 改成并行执行加上失败检测和重试逻辑。这个阶段的目标是掌握并行调度的资源管理和闭环自愈的策略设计。每个阶段大概需要一到两周的实践来熟悉。不要跳过第一阶段直接上并行因为没有对单个 Agent 行为的深入理解并行编排出问题的时候根本不知道怎么排查。我在实际迁移过程中最大的体会是编排的复杂度应该跟任务的复杂度匹配。一个简单的任务用单 Agent 加脚本就够了硬上多 Agent 编排反而增加维护成本。只有当任务确实需要多步骤推理、多维度分析、或者高并发处理的时候多 Agent 编排的价值才能体现出来。判断标准很简单——如果你发现自己在反复做“等待-检查-再等待”的循环那就是时候考虑编排了。
阅读完成 · 觉得有帮助？
