企业官网建设流程全解析

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: detailed

verbosity 控制详细程度。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 多智能体协作效率反而下降

有时候启用多个子智能体后，整体效率反而比单智能体低。原因通常是编排开销超过了并行收益。任务拆得太细，子智能体之间传递上下文的成本很高。

解决办法是调整拆解粒度，让每个子任务有足够的处理量，摊薄编排开销。另外检查路由规则，确保任务分给了真正擅长的子智能体，而不是随机分配。

还有一个容易被忽略的点：子智能体的启动开销。每次调用子智能体都有启动成本，如果任务本身很小，启动开销占比就很高。这种情况下，把小任务合并成一个大任务给一个子智能体处理，反而更快。

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 数字大的优先级高，我一开始以为数字小的优先，结果任务都路由到了不擅长的子智能体。核对文档确认优先级方向后再配。

第五个坑是工作树磁盘占满。并行任务多、工作树没及时清理，磁盘很快满。解法是配监控，工作树目录使用率超阈值时告警，同时检查清理策略是否生效。

这些坑大多和配置有关，不是功能本身的缺陷。花点时间把配置调对，后面就顺了。