Harness 配置的「分层叠加」：Profile、Bundle、Patch 怎么分工

DeepSeek dsh 把一个跑起来的 Harness 描述成「启动时按顺序叠插件树」：profile 里列出 bundle，再依次应用 profile 补丁、用户主目录补丁、命令行 --patch 参数。这条路径对我启发很大——不是因为必须上 dsh，而是因为它把 Harness 配置从「改代码发版」变成了「分层声明 + 可观测组合结果」。

很多团队已经有类似需求：开发环境要宽松超时，生产要紧权限；A 项目用 DeepSeek，B 项目用混元；个人开发者想加本地工具，但不能污染团队基线。问题往往不是缺配置项，而是缺分层语义——谁覆盖谁、最终生效的是什么，说不清。

一、四层各自管什么

借用 dsh 的分层，映射到通用 Harness 实践：

Bundle 列表（平台/框架维护）

• 典型内容：模型适配、工具集、循环实现、UI
• 覆盖范围：按顺序挂载，后挂可扩展先挂

Profile 补丁（团队维护）

• 典型内容：项目默认模型、超时、允许工具白名单
• 覆盖范围：该 profile 下所有会话

用户/机器补丁（开发者维护）

• 典型内容：个人 API Key、本地路径、调试开关
• 覆盖范围：仅本机

CLI 一次性补丁（单次运行）

• 典型内容：实验性 loop、临时禁某工具
• 覆盖范围：仅当前进程

关键不在层级数量本身，而在顺序即语义：bundle 先定骨架，patch 后做微调。没有顺序规则，就会出现「生产配置被本地 patch 意外覆盖」的经典事故。

二、一个概念性的配置示例

下面不是某框架的完整语法，而是把分层意图写清楚的最小示意：

# bundles.yaml — 平台维护，顺序不可随意打乱

bundles:

  - id: harness-core  # 权限、审计、验收、超时熔断

  - id: model-deepseek

  - id: tools-devkit

  - id: loop-react



# profile.team-a.yaml — 团队维护

patch:

  - target: model-deepseek

    set:

      default_model: deepseek-v4-flash

      max_tokens: 8192

  - target: harness-core

    set:

      tool_timeout_s: 30

      require_evaluator: true



# local.yaml — 开发者维护

patch:

  - target: tools-devkit

    insert:

      - name: local_linter

        path: /home/dev/bin/lint



# CLI: exp-no-browser.yaml — 单次实验

patch:

  - target: tools-devkit

    remove: [browser]

读这段配置的要点：mandatory 的 harness-core 永远在前；团队 patch 只能调参数，不应 remove 验收；CLI 层适合 A/B，但不应关掉审计。

三、生产里最容易踩的三个坑

坑 1：静默覆盖。两层 patch 都改了 tool_timeout_s，最后生效的是谁？如果没有「打印最终插件树 / 最终配置合并结果」的命令，排障只能靠猜。

坑 2：把不变量放进可卸载 bundle。一旦验收或权限被打包成「可选 bundle」，某个 profile 漏挂载就等于裸奔。不变量应进 mandatory 层，且 patch 不允许 remove。

坑 3：bundle 顺序被业务随意调整。先挂 UI 再挂权限，可能出现 UI 已渲染但工具尚未被闸门约束的窗口期。顺序规则要文档化，最好启动时校验。

四、落地时的分工建议

• 平台组：维护 mandatory bundle + bundle 顺序规范 + print-effective-config 类工具
• 业务组：维护 profile，只 patch 模型、工具白名单、超时等业务参数
• 个人：本地 patch 仅限密钥、路径、调试；禁止 override 验收与权限
• CI：对 profile 做 schema 校验，禁止 remove mandatory 字段

五、怎么判断分层是否有效

三个自检问题：

1. 新人 clone 项目后，能否只靠 profile 跑起来，而不改源码？
2. 线上事故时，能否在 5 分钟内打印出「最终生效配置」？
3. 关掉所有 CLI patch，权限和验收是否仍在？

三条都能答是，说明分层在起作用；任一条否，说明你还只是在堆配置文件。

结语

Profile / Bundle / Patch 不是 dsh 专属技巧，而是 Harness 走向工业化的必经之路：把「能跑」和「敢跑」拆开配置。模型和工具可以继续插件化、继续换，但合并规则必须稳定、可观测、可审计——否则插件越多，系统越不可信。