DeepSeek Harness 配置层与 patch：叠加规则详解

改 DSH 配置的人最常遇到两个困惑："我改了配置为什么不生效？""为什么改一个字段，另一个字段没了？"答案都在同一个机制里：DSH 的配置不是一份文件，而是几层叠加出来的结果。

配置树：五层从底到顶

启动时，DSH 从一棵空配置树出发，逐层叠加：

第 5 层  --patch 指定的覆盖层        ← 最高优先，一次性
第 4 层  $DSH_HOME/cordis.patch.yml  ← home 级：你机器上的全局定制
第 3 层  profile 的 cordis.patch.yml ← 该 profile 的定制
第 2 层  dsh.profile.bundles 中各组合包的 patch ← 内置能力
第 1 层  空根                        ← 起点

层越靠上，发言权越大。这带来一个直觉上的好消息：你永远不用改内置配置——所有定制都写在更上层的 patch 里，升级 DSH 时内置层变了，你的定制层还在。

patch 的写法：声明"我想怎么改这一行"

patch 文件（cordis.patch.yml）里是逐条的改动声明，每条指向配置树里的一个行（row，按 id 标识），例如禁用一个工具、覆盖一个配置：

# 例子：调整 agent-loop 的并行工具调用上限
- id: agent-loop
  config:
    maxParallelToolCalls: 4

# 例子：禁用某个你不需要的行
- id: tool-web
  disabled: true

最重要的规则：替换整行，不是深度合并

这是 DSH 配置里最容易踩的坑。当你在 patch 里写一个行的 config 时，你写的内容会整个替换该行原有的 config——而不是与内置值"合并"。

具体来说：假设内置层的 webserver 行配置是 { host: '127.0.0.1', port: 3080 }，你在 patch 里只写：

- id: webserver
  config:
    port: 8080

结果 host 字段没了（回到该字段的默认值，而不是继承 127.0.0.1）。想要保住原值，必须重述全部字段：

- id: webserver
  config:
    host: '127.0.0.1'   # 必须重述，否则丢失
    port: 8080

实践纪律：改某行前，先用下面的命令看它当前的完整 config，然后整段复制到你的 patch 里再改。

检查你的配置：dump 命令

不用猜配置最终长什么样，直接问：

dsh --dump-default-config   # 内置默认（未叠加任何 patch）
dsh --dump-config           # 叠加完所有层之后的最终结果

改完 patch 跑一次 --dump-config，一眼看出你的修改到底生效没有、有没有误伤其他字段。

常见坑与排查

现象	原因	处理
改了配置没反应	patch 没生效：层级错位（写错文件）、id 对不上	`--dump-config` 检查该行最终值
改了一个字段，别的字段回到默认	替换整行而非合并	重述该行全部字段
启动参数和 patch 打架	`--patch` 覆盖层优先于文件	明确意图：一次性用`--patch`，长期用文件
两个文件都有同一行	层越高越优先	确认自己在改的是哪一层