1. 这次更新到底改了什么从单打独斗到多智能体协作DeepSeek Harness 这次更新的核心用一句话概括就是把过去需要手动配置、手动拼接的多智能体协作流程直接做成了官方插件。Codex 和 Claude Code 这两个子智能体进入官方插件列表意味着你不再需要自己写胶水代码去调度它们装好插件就能用。同时加入的 Git 工作树支持和思考翻译功能分别解决的是多任务并行时工作区互相污染和推理过程可读性差这两个长期痛点。我先把这次更新的四个核心变化拆开说清楚后面再逐个深入。第一个变化Codex 子智能体官方化。过去想让 Harness 调用 Codex 做代码生成或补全你得自己写适配层处理输入输出格式转换、错误重试、上下文传递。现在官方插件直接封装了这些逻辑你只需要在配置里声明启用Harness 就能把任务分派给 Codex 子智能体拿回结果后继续主流程。第二个变化Claude Code 子智能体官方化。和 Codex 类似Claude Code 擅长的是长上下文理解、复杂重构建议、代码审查这类任务。官方插件化之后Harness 可以在同一个工作流里同时调度 Codex 和 Claude Code让它们各干各擅长的部分。第三个变化Git 工作树支持。这个功能解决的是多智能体并行时的文件冲突问题。以前多个子智能体同时改同一个仓库很容易出现互相覆盖、合并冲突。Git 工作树允许每个子智能体在独立的工作树里操作互不干扰最后再统一合并。第四个变化思考翻译。子智能体的推理过程往往是内部表示直接输出可读性很差。思考翻译功能把这些推理步骤转成自然语言方便你审查它的决策逻辑也方便调试。注意官方插件列表里的子智能体不是装了就能完美协作它们之间仍然需要主智能体做任务编排。插件解决的是通信和格式问题不解决该把什么任务分给谁的问题。适合谁来参考这篇内容如果你已经在用 Harness 做多步骤代码生成、自动化重构、或者多仓库并行开发这次更新直接影响你的工作流设计。如果你还没上手 Harness但正在寻找多智能体协作的落地方案这篇可以帮你判断它是否适合你的场景。2. 多智能体协作的架构逻辑为什么是插件化而不是内置2.1 插件化背后的设计取舍把 Codex 和 Claude Code 做成插件而不是内置模块这个选择不是随意的。内置意味着 Harness 核心团队要维护这些子智能体的适配代码一旦子智能体那边接口变了Harness 就得跟着发版。插件化之后适配层由插件维护核心保持稳定子智能体升级时只需要更新插件。另一个原因是可选性。不是每个用户都需要 Codex 或 Claude Code。有人只用 Harness 做主流程编排子智能体用别的方案。插件化让这些用户不必背负不需要的依赖。从工程角度看插件化还带来一个好处隔离故障。某个子智能体插件出问题不会拖垮整个 Harness 核心。你可以单独禁用某个插件其他功能照常跑。2.2 主智能体与子智能体的职责划分这里要理清一个概念Harness 本身是主智能体负责理解你的意图、拆解任务、决定调用哪个子智能体、汇总结果。Codex 和 Claude Code 是子智能体负责执行具体子任务。为什么要这样分因为不同模型在不同任务上的表现差异很大。有的模型代码生成强但长上下文弱有的反过来。主智能体做编排可以把任务路由到最合适的子智能体整体效果比单模型硬扛要好。实际配置时你需要在 Harness 的配置文件里声明启用哪些子智能体插件以及它们的优先级。比如代码生成任务优先给 Codex代码审查优先给 Claude Code。这个路由规则可以按任务类型配也可以按文件类型配。2.3 Git 工作树为什么是多智能体协作的关键基础设施多智能体并行操作同一个 Git 仓库最大的问题是工作区竞争。子智能体 A 正在改的文件子智能体 B 可能也在改两边都基于旧版本合并时冲突。更糟的是如果它们直接操作同一个工作目录可能互相覆盖未提交的更改。Git 工作树git worktree允许同一个仓库挂载多个工作目录每个工作树有独立的分支和索引。子智能体各自在自己的工作树里干活完成后把分支合并回主工作树。这样并行操作不会互相干扰。Harness 这次把工作树管理集成进来意味着你不需要手动为每个子智能体创建工作树、切换分支、清理临时工作树。Harness 会自动分配和回收。提示工作树虽然隔离了文件操作但合并时仍然可能冲突。建议给每个子智能体分配明确不重叠的文件范围从源头减少冲突。3. 实操配置从零搭建多智能体协作环境3.1 环境准备与插件安装先确认你的 Harness 版本支持插件系统。打开配置文件找到插件相关段落。如果你是从旧版本升级注意备份原配置因为插件配置的格式可能和旧的手动适配配置不兼容。安装 Codex 子智能体插件通常是在配置里加一段声明指定插件名称和版本。Claude Code 插件同理。两个插件可以同时启用Harness 会根据路由规则决定用哪个。配置示例具体字段名以你所用版本为准plugins: - name: codex-subagent enabled: true priority: 10 task_types: [code_generation, code_completion] - name: claude-code-subagent enabled: true priority: 8 task_types: [code_review, refactoring, long_context_analysis]priority 数字越大优先级越高。task_types 声明这个子智能体擅长哪些任务类型Harness 路由时会参考。3.2 Git 工作树的初始化与分配策略启用 Git 工作树支持后Harness 会在需要并行时自动创建临时工作树。你需要配置的是工作树的根目录和清理策略。工作树根目录建议放在仓库同级的一个独立目录不要放在仓库内部否则 Git 会把它当成未跟踪文件。清理策略建议设为任务完成后自动清理避免临时工作树堆积占磁盘。分配策略上有两种模式按任务分配和按文件范围分配。按任务分配是每个子任务一个工作树适合任务之间文件重叠少的情况。按文件范围分配是每个子智能体一个工作树适合子智能体要连续处理多个相关任务的情况。我实测下来按文件范围分配在大多数场景下更高效因为减少了工作树创建和销毁的开销。但如果两个子智能体的文件范围有重叠还是得用按任务分配来隔离。3.3 思考翻译的开启与输出格式思考翻译功能默认可能是关闭的需要在配置里显式开启。开启后子智能体的推理过程会以自然语言形式输出到日志或指定文件。输出格式一般有两种流式和汇总式。流式是推理步骤实时输出适合调试时观察。汇总式是任务完成后一次性输出完整推理链适合事后审查。thinking_translation: enabled: true output_mode: streaming output_target: ./logs/thinking.log verbosity: detailedverbosity 控制详细程度。detailed 会输出每一步推理concise 只输出关键决策点。调试阶段用 detailed生产环境用 concise 减少日志量。4. 核心环节实现任务编排与结果合并4.1 任务拆解与路由规则设计主智能体拿到你的指令后第一步是拆解任务。比如你说重构这个模块并补充测试它会拆成分析模块结构生成重构方案执行重构生成测试用例运行测试等子任务。拆解粒度很关键。太粗子智能体一次要处理太多容易出错。太细编排开销大子智能体之间传递上下文的成本高。我的经验是每个子任务对应一个明确的、可独立验证的输出。比如生成重构方案的输出是一份方案文档执行重构的输出是改完的代码。路由规则按任务类型匹配子智能体的 task_types。代码生成类任务给 Codex代码审查和重构建议给 Claude Code。如果两个子智能体都声明支持某任务类型按 priority 决定。4.2 子智能体并行执行与工作树隔离任务拆解和路由完成后Harness 为每个需要并行的子任务创建工作树。子智能体在自己的工作树里执行读写文件都限制在工作树范围内。这里有个细节子智能体之间的上下文传递。比如执行重构需要生成重构方案的输出作为输入。这种有依赖关系的任务不能并行必须串行。Harness 会根据任务依赖图决定哪些能并行、哪些要串行。并行执行时每个子智能体的进度和中间结果会汇总到主智能体。主智能体负责监控如果某个子智能体失败决定是重试、跳过还是终止整个流程。4.3 结果合并与冲突处理所有子任务完成后Harness 把各工作树的结果合并回主工作树。合并策略有两种自动合并和人工确认。自动合并适合冲突概率低的场景比如各子智能体改的文件完全不重叠。人工确认适合冲突概率高的场景Harness 会列出冲突文件你决定怎么合。合并时的冲突处理和普通 Git 合并一样只是冲突来源是多个子智能体而不是多个人。我建议在路由阶段就尽量让子智能体的文件范围不重叠从源头减少合并冲突。注意合并前一定要检查各工作树是否有未提交的更改。Harness 通常会自动提交但如果子智能体执行过程中出错可能留下未提交状态合并时会丢失这些更改。5. 常见问题与排查技巧实录5.1 子智能体插件加载失败最常见的原因是版本不匹配。Harness 核心版本和插件版本有兼容性要求版本差太多会加载失败。排查时先看日志里的版本检查信息确认核心和插件版本在兼容范围内。另一个原因是配置文件格式错误。YAML 对缩进敏感插件声明段落缩进错了会导致解析失败。用 YAML 校验工具检查一下配置文件。如果插件加载成功但子智能体不响应检查 task_types 配置是否和实际任务类型匹配。任务类型字符串拼写错误会导致路由不到任何子智能体。5.2 Git 工作树创建失败工作树创建失败通常是路径问题。工作树根目录如果不存在Harness 可能不会自动创建。手动创建目录后再试。另一个原因是仓库状态不干净。有未提交的更改时创建工作树可能失败。先提交或暂存当前更改。如果工作树创建成功但子智能体在里面操作报错检查工作树的分支是否正确挂载。有时候工作树创建了但分支没切过去子智能体在错误的分支上操作。5.3 思考翻译输出乱码或截断乱码通常是编码问题。检查输出文件的编码设置确保和子智能体的输出编码一致。UTF-8 是通用选择。截断可能是输出缓冲区太小。流式输出时如果缓冲区满了没及时刷新后面的内容会丢。调大缓冲区或改用汇总式输出。如果思考翻译的内容和实际推理对不上可能是翻译层和子智能体的版本不匹配。翻译层需要理解子智能体的推理格式格式变了翻译就会出错。更新翻译层到匹配版本。5.4 多智能体协作效率反而下降有时候启用多个子智能体后整体效率反而比单智能体低。原因通常是编排开销超过了并行收益。任务拆得太细子智能体之间传递上下文的成本很高。解决办法是调整拆解粒度让每个子任务有足够的处理量摊薄编排开销。另外检查路由规则确保任务分给了真正擅长的子智能体而不是随机分配。还有一个容易被忽略的点子智能体的启动开销。每次调用子智能体都有启动成本如果任务本身很小启动开销占比就很高。这种情况下把小任务合并成一个大任务给一个子智能体处理反而更快。问题现象可能原因排查方向插件加载失败版本不匹配或配置格式错误检查版本兼容性和 YAML 缩进子智能体不响应task_types 配置错误核对任务类型字符串工作树创建失败路径不存在或仓库不干净手动建目录、提交更改思考翻译乱码编码不一致统一用 UTF-8协作效率下降编排开销过大调整拆解粒度6. 进阶用法把思考翻译变成调试利器思考翻译不只是看推理过程还可以用来做决策审计。子智能体为什么选择这个方案而不是那个推理链里都有。你可以定期审查推理链发现子智能体的决策偏差调整路由规则或提示词。另一个用法是训练数据生成。子智能体的推理链加上最终结果可以作为训练数据用来微调更小的模型。这样小模型能学到子智能体的决策模式以后简单任务直接用小模型复杂任务才调子智能体降低成本。思考翻译的输出还可以接入监控系统。如果某个子智能体的推理链里频繁出现不确定需要更多信息这类表述说明它的任务分配可能不合理或者提示词需要优化。我在实际使用中发现思考翻译的详细程度要按场景调。调试新工作流时用 detailed跑稳定后用 concise。一直开 detailed 会让日志膨胀得很快磁盘吃不消。7. 工作树策略的实战调优工作树的数量不是越多越好。每个工作树占一份磁盘空间而且 Git 操作在工作树多了之后会变慢。我的经验是并行子智能体数量控制在 3 到 5 个比较合适超过这个数合并冲突的概率和合并成本都上升得很快。工作树的清理策略也要注意。自动清理虽然省事但如果任务失败需要保留现场排查自动清理会把证据也清掉。建议配置成成功时自动清理失败时保留兼顾效率和可排查性。如果你们的仓库很大创建工作树的耗时可能比较明显。这种情况下可以考虑用浅克隆或者稀疏检出减少工作树的数据量。Harness 的工作树配置里通常有相关选项具体字段名看版本文档。还有一个坑工作树和子模块的配合。如果仓库有子模块工作树创建时子模块不会自动初始化。需要在工作树创建后手动初始化子模块或者配置 Harness 自动处理。这个细节官方文档不一定写但实际用大仓库时很容易碰到。8. 子智能体选型Codex 和 Claude Code 各适合什么Codex 在代码生成和补全上表现稳定尤其是它见过的语言和框架。给它明确的函数签名和注释它能生成质量不错的实现。但它在长上下文理解上相对弱一些给它一个几千行的文件让它理解整体结构效果会打折扣。Claude Code 在长上下文和复杂重构上更强。给它一个模块的完整代码让它提重构建议它能抓住跨文件的依赖关系。代码审查也是它的强项能发现一些隐蔽的逻辑问题。实际编排时我通常这样分新功能实现给 Codex因为它生成快已有代码的重构和审查给 Claude Code因为它理解深。测试用例生成两边都能做看哪个的 task_types 配了。如果两个子智能体都适合某任务可以都调一遍然后让主智能体对比结果选优。这样成本翻倍但质量更有保障适合对质量要求高的场景。提示子智能体的能力会随版本更新变化定期重新评估路由规则别一套规则用到底。9. 我踩过的几个坑和对应的解法第一个坑是工作树分支命名冲突。Harness 自动创建的工作树分支名如果和已有分支重名创建会失败。解法是配置分支名前缀加上任务 ID 或时间戳保证唯一。第二个坑是思考翻译拖慢执行。detailed 模式下每步推理都要翻译和写日志IO 开销不小。任务量大时这个开销会累积。解法是只在需要调试的子智能体上开 detailed其他用 concise 或关闭。第三个坑是合并时丢失未提交更改。子智能体执行中途失败工作树里有未提交的更改合并时这些更改不会被带过来。解法是配置 Harness 在子智能体失败时自动提交或暂存保留现场。第四个坑是插件优先级配置反了。priority 数字大的优先级高我一开始以为数字小的优先结果任务都路由到了不擅长的子智能体。核对文档确认优先级方向后再配。第五个坑是工作树磁盘占满。并行任务多、工作树没及时清理磁盘很快满。解法是配监控工作树目录使用率超阈值时告警同时检查清理策略是否生效。这些坑大多和配置有关不是功能本身的缺陷。花点时间把配置调对后面就顺了。 
长河君 · 2026/10/16 4:43:49 · 阅读 1.2k DeepSeek Harness 多智能体协作插件化：Codex 与 Claude Code 官方集成实战
1. 这次更新到底改了什么从单打独斗到多智能体协作DeepSeek Harness 这次更新的核心用一句话概括就是把过去需要手动配置、手动拼接的多智能体协作流程直接做成了官方插件。Codex 和 Claude Code 这两个子智能体进入官方插件列表意味着你不再需要自己写胶水代码去调度它们装好插件就能用。同时加入的 Git 工作树支持和思考翻译功能分别解决的是多任务并行时工作区互相污染和推理过程可读性差这两个长期痛点。我先把这次更新的四个核心变化拆开说清楚后面再逐个深入。第一个变化Codex 子智能体官方化。过去想让 Harness 调用 Codex 做代码生成或补全你得自己写适配层处理输入输出格式转换、错误重试、上下文传递。现在官方插件直接封装了这些逻辑你只需要在配置里声明启用Harness 就能把任务分派给 Codex 子智能体拿回结果后继续主流程。第二个变化Claude Code 子智能体官方化。和 Codex 类似Claude Code 擅长的是长上下文理解、复杂重构建议、代码审查这类任务。官方插件化之后Harness 可以在同一个工作流里同时调度 Codex 和 Claude Code让它们各干各擅长的部分。第三个变化Git 工作树支持。这个功能解决的是多智能体并行时的文件冲突问题。以前多个子智能体同时改同一个仓库很容易出现互相覆盖、合并冲突。Git 工作树允许每个子智能体在独立的工作树里操作互不干扰最后再统一合并。第四个变化思考翻译。子智能体的推理过程往往是内部表示直接输出可读性很差。思考翻译功能把这些推理步骤转成自然语言方便你审查它的决策逻辑也方便调试。注意官方插件列表里的子智能体不是装了就能完美协作它们之间仍然需要主智能体做任务编排。插件解决的是通信和格式问题不解决该把什么任务分给谁的问题。适合谁来参考这篇内容如果你已经在用 Harness 做多步骤代码生成、自动化重构、或者多仓库并行开发这次更新直接影响你的工作流设计。如果你还没上手 Harness但正在寻找多智能体协作的落地方案这篇可以帮你判断它是否适合你的场景。2. 多智能体协作的架构逻辑为什么是插件化而不是内置2.1 插件化背后的设计取舍把 Codex 和 Claude Code 做成插件而不是内置模块这个选择不是随意的。内置意味着 Harness 核心团队要维护这些子智能体的适配代码一旦子智能体那边接口变了Harness 就得跟着发版。插件化之后适配层由插件维护核心保持稳定子智能体升级时只需要更新插件。另一个原因是可选性。不是每个用户都需要 Codex 或 Claude Code。有人只用 Harness 做主流程编排子智能体用别的方案。插件化让这些用户不必背负不需要的依赖。从工程角度看插件化还带来一个好处隔离故障。某个子智能体插件出问题不会拖垮整个 Harness 核心。你可以单独禁用某个插件其他功能照常跑。2.2 主智能体与子智能体的职责划分这里要理清一个概念Harness 本身是主智能体负责理解你的意图、拆解任务、决定调用哪个子智能体、汇总结果。Codex 和 Claude Code 是子智能体负责执行具体子任务。为什么要这样分因为不同模型在不同任务上的表现差异很大。有的模型代码生成强但长上下文弱有的反过来。主智能体做编排可以把任务路由到最合适的子智能体整体效果比单模型硬扛要好。实际配置时你需要在 Harness 的配置文件里声明启用哪些子智能体插件以及它们的优先级。比如代码生成任务优先给 Codex代码审查优先给 Claude Code。这个路由规则可以按任务类型配也可以按文件类型配。2.3 Git 工作树为什么是多智能体协作的关键基础设施多智能体并行操作同一个 Git 仓库最大的问题是工作区竞争。子智能体 A 正在改的文件子智能体 B 可能也在改两边都基于旧版本合并时冲突。更糟的是如果它们直接操作同一个工作目录可能互相覆盖未提交的更改。Git 工作树git worktree允许同一个仓库挂载多个工作目录每个工作树有独立的分支和索引。子智能体各自在自己的工作树里干活完成后把分支合并回主工作树。这样并行操作不会互相干扰。Harness 这次把工作树管理集成进来意味着你不需要手动为每个子智能体创建工作树、切换分支、清理临时工作树。Harness 会自动分配和回收。提示工作树虽然隔离了文件操作但合并时仍然可能冲突。建议给每个子智能体分配明确不重叠的文件范围从源头减少冲突。3. 实操配置从零搭建多智能体协作环境3.1 环境准备与插件安装先确认你的 Harness 版本支持插件系统。打开配置文件找到插件相关段落。如果你是从旧版本升级注意备份原配置因为插件配置的格式可能和旧的手动适配配置不兼容。安装 Codex 子智能体插件通常是在配置里加一段声明指定插件名称和版本。Claude Code 插件同理。两个插件可以同时启用Harness 会根据路由规则决定用哪个。配置示例具体字段名以你所用版本为准plugins: - name: codex-subagent enabled: true priority: 10 task_types: [code_generation, code_completion] - name: claude-code-subagent enabled: true priority: 8 task_types: [code_review, refactoring, long_context_analysis]priority 数字越大优先级越高。task_types 声明这个子智能体擅长哪些任务类型Harness 路由时会参考。3.2 Git 工作树的初始化与分配策略启用 Git 工作树支持后Harness 会在需要并行时自动创建临时工作树。你需要配置的是工作树的根目录和清理策略。工作树根目录建议放在仓库同级的一个独立目录不要放在仓库内部否则 Git 会把它当成未跟踪文件。清理策略建议设为任务完成后自动清理避免临时工作树堆积占磁盘。分配策略上有两种模式按任务分配和按文件范围分配。按任务分配是每个子任务一个工作树适合任务之间文件重叠少的情况。按文件范围分配是每个子智能体一个工作树适合子智能体要连续处理多个相关任务的情况。我实测下来按文件范围分配在大多数场景下更高效因为减少了工作树创建和销毁的开销。但如果两个子智能体的文件范围有重叠还是得用按任务分配来隔离。3.3 思考翻译的开启与输出格式思考翻译功能默认可能是关闭的需要在配置里显式开启。开启后子智能体的推理过程会以自然语言形式输出到日志或指定文件。输出格式一般有两种流式和汇总式。流式是推理步骤实时输出适合调试时观察。汇总式是任务完成后一次性输出完整推理链适合事后审查。thinking_translation: enabled: true output_mode: streaming output_target: ./logs/thinking.log verbosity: detailedverbosity 控制详细程度。detailed 会输出每一步推理concise 只输出关键决策点。调试阶段用 detailed生产环境用 concise 减少日志量。4. 核心环节实现任务编排与结果合并4.1 任务拆解与路由规则设计主智能体拿到你的指令后第一步是拆解任务。比如你说重构这个模块并补充测试它会拆成分析模块结构生成重构方案执行重构生成测试用例运行测试等子任务。拆解粒度很关键。太粗子智能体一次要处理太多容易出错。太细编排开销大子智能体之间传递上下文的成本高。我的经验是每个子任务对应一个明确的、可独立验证的输出。比如生成重构方案的输出是一份方案文档执行重构的输出是改完的代码。路由规则按任务类型匹配子智能体的 task_types。代码生成类任务给 Codex代码审查和重构建议给 Claude Code。如果两个子智能体都声明支持某任务类型按 priority 决定。4.2 子智能体并行执行与工作树隔离任务拆解和路由完成后Harness 为每个需要并行的子任务创建工作树。子智能体在自己的工作树里执行读写文件都限制在工作树范围内。这里有个细节子智能体之间的上下文传递。比如执行重构需要生成重构方案的输出作为输入。这种有依赖关系的任务不能并行必须串行。Harness 会根据任务依赖图决定哪些能并行、哪些要串行。并行执行时每个子智能体的进度和中间结果会汇总到主智能体。主智能体负责监控如果某个子智能体失败决定是重试、跳过还是终止整个流程。4.3 结果合并与冲突处理所有子任务完成后Harness 把各工作树的结果合并回主工作树。合并策略有两种自动合并和人工确认。自动合并适合冲突概率低的场景比如各子智能体改的文件完全不重叠。人工确认适合冲突概率高的场景Harness 会列出冲突文件你决定怎么合。合并时的冲突处理和普通 Git 合并一样只是冲突来源是多个子智能体而不是多个人。我建议在路由阶段就尽量让子智能体的文件范围不重叠从源头减少合并冲突。注意合并前一定要检查各工作树是否有未提交的更改。Harness 通常会自动提交但如果子智能体执行过程中出错可能留下未提交状态合并时会丢失这些更改。5. 常见问题与排查技巧实录5.1 子智能体插件加载失败最常见的原因是版本不匹配。Harness 核心版本和插件版本有兼容性要求版本差太多会加载失败。排查时先看日志里的版本检查信息确认核心和插件版本在兼容范围内。另一个原因是配置文件格式错误。YAML 对缩进敏感插件声明段落缩进错了会导致解析失败。用 YAML 校验工具检查一下配置文件。如果插件加载成功但子智能体不响应检查 task_types 配置是否和实际任务类型匹配。任务类型字符串拼写错误会导致路由不到任何子智能体。5.2 Git 工作树创建失败工作树创建失败通常是路径问题。工作树根目录如果不存在Harness 可能不会自动创建。手动创建目录后再试。另一个原因是仓库状态不干净。有未提交的更改时创建工作树可能失败。先提交或暂存当前更改。如果工作树创建成功但子智能体在里面操作报错检查工作树的分支是否正确挂载。有时候工作树创建了但分支没切过去子智能体在错误的分支上操作。5.3 思考翻译输出乱码或截断乱码通常是编码问题。检查输出文件的编码设置确保和子智能体的输出编码一致。UTF-8 是通用选择。截断可能是输出缓冲区太小。流式输出时如果缓冲区满了没及时刷新后面的内容会丢。调大缓冲区或改用汇总式输出。如果思考翻译的内容和实际推理对不上可能是翻译层和子智能体的版本不匹配。翻译层需要理解子智能体的推理格式格式变了翻译就会出错。更新翻译层到匹配版本。5.4 多智能体协作效率反而下降有时候启用多个子智能体后整体效率反而比单智能体低。原因通常是编排开销超过了并行收益。任务拆得太细子智能体之间传递上下文的成本很高。解决办法是调整拆解粒度让每个子任务有足够的处理量摊薄编排开销。另外检查路由规则确保任务分给了真正擅长的子智能体而不是随机分配。还有一个容易被忽略的点子智能体的启动开销。每次调用子智能体都有启动成本如果任务本身很小启动开销占比就很高。这种情况下把小任务合并成一个大任务给一个子智能体处理反而更快。问题现象可能原因排查方向插件加载失败版本不匹配或配置格式错误检查版本兼容性和 YAML 缩进子智能体不响应task_types 配置错误核对任务类型字符串工作树创建失败路径不存在或仓库不干净手动建目录、提交更改思考翻译乱码编码不一致统一用 UTF-8协作效率下降编排开销过大调整拆解粒度6. 进阶用法把思考翻译变成调试利器思考翻译不只是看推理过程还可以用来做决策审计。子智能体为什么选择这个方案而不是那个推理链里都有。你可以定期审查推理链发现子智能体的决策偏差调整路由规则或提示词。另一个用法是训练数据生成。子智能体的推理链加上最终结果可以作为训练数据用来微调更小的模型。这样小模型能学到子智能体的决策模式以后简单任务直接用小模型复杂任务才调子智能体降低成本。思考翻译的输出还可以接入监控系统。如果某个子智能体的推理链里频繁出现不确定需要更多信息这类表述说明它的任务分配可能不合理或者提示词需要优化。我在实际使用中发现思考翻译的详细程度要按场景调。调试新工作流时用 detailed跑稳定后用 concise。一直开 detailed 会让日志膨胀得很快磁盘吃不消。7. 工作树策略的实战调优工作树的数量不是越多越好。每个工作树占一份磁盘空间而且 Git 操作在工作树多了之后会变慢。我的经验是并行子智能体数量控制在 3 到 5 个比较合适超过这个数合并冲突的概率和合并成本都上升得很快。工作树的清理策略也要注意。自动清理虽然省事但如果任务失败需要保留现场排查自动清理会把证据也清掉。建议配置成成功时自动清理失败时保留兼顾效率和可排查性。如果你们的仓库很大创建工作树的耗时可能比较明显。这种情况下可以考虑用浅克隆或者稀疏检出减少工作树的数据量。Harness 的工作树配置里通常有相关选项具体字段名看版本文档。还有一个坑工作树和子模块的配合。如果仓库有子模块工作树创建时子模块不会自动初始化。需要在工作树创建后手动初始化子模块或者配置 Harness 自动处理。这个细节官方文档不一定写但实际用大仓库时很容易碰到。8. 子智能体选型Codex 和 Claude Code 各适合什么Codex 在代码生成和补全上表现稳定尤其是它见过的语言和框架。给它明确的函数签名和注释它能生成质量不错的实现。但它在长上下文理解上相对弱一些给它一个几千行的文件让它理解整体结构效果会打折扣。Claude Code 在长上下文和复杂重构上更强。给它一个模块的完整代码让它提重构建议它能抓住跨文件的依赖关系。代码审查也是它的强项能发现一些隐蔽的逻辑问题。实际编排时我通常这样分新功能实现给 Codex因为它生成快已有代码的重构和审查给 Claude Code因为它理解深。测试用例生成两边都能做看哪个的 task_types 配了。如果两个子智能体都适合某任务可以都调一遍然后让主智能体对比结果选优。这样成本翻倍但质量更有保障适合对质量要求高的场景。提示子智能体的能力会随版本更新变化定期重新评估路由规则别一套规则用到底。9. 我踩过的几个坑和对应的解法第一个坑是工作树分支命名冲突。Harness 自动创建的工作树分支名如果和已有分支重名创建会失败。解法是配置分支名前缀加上任务 ID 或时间戳保证唯一。第二个坑是思考翻译拖慢执行。detailed 模式下每步推理都要翻译和写日志IO 开销不小。任务量大时这个开销会累积。解法是只在需要调试的子智能体上开 detailed其他用 concise 或关闭。第三个坑是合并时丢失未提交更改。子智能体执行中途失败工作树里有未提交的更改合并时这些更改不会被带过来。解法是配置 Harness 在子智能体失败时自动提交或暂存保留现场。第四个坑是插件优先级配置反了。priority 数字大的优先级高我一开始以为数字小的优先结果任务都路由到了不擅长的子智能体。核对文档确认优先级方向后再配。第五个坑是工作树磁盘占满。并行任务多、工作树没及时清理磁盘很快满。解法是配监控工作树目录使用率超阈值时告警同时检查清理策略是否生效。这些坑大多和配置有关不是功能本身的缺陷。花点时间把配置调对后面就顺了。