DeepSeek Harness 插件安装与加载顺序

加载顺序：生效配置的四层叠加

上一章做出了 hello-plugin 组合包，本章把它装进一个 profile，同时回答一个关键问题：多个组合包的配置叠加时，谁覆盖谁？答案由生效配置的加载顺序决定——配置在空根之上按固定顺序逐层组合，后应用的层按行胜出：

1. profile 的 dsh.profile.bundles 列表：先是 @deepseek-ai/dsh-base，再按各组合包的加入顺序应用其 patch；
2. profile 自己的 cordis.patch.yml：用户 profile 级 patch 层；
3. home 级的 $DSH_HOME/cordis.patch.yml：各 profile 共享的机器本地偏好；
4. 每个 --patch <path> overlay：按 argv 顺序。

应用参数不是另一层 patch，表层组合包可以通过普通应用自有服务解析它们。另一个要点：patch 会整行替换目标行的整个 config 值，而不是深度合并各键。

动手：安装 hello-plugin 进 profile

dsh plugin --profile <name> <args...> 会在 profile 目录内把参数转发给 pnpm，因此所有 pnpm 子命令都可用。在包含 hello-plugin 的目录中执行：

dsh plugin --profile demo add ./hello-plugin

首次使用会初始化 profile，@deepseek-ai/dsh-base 自动成为第一个组合包。pnpm 链接该 checkout，而 dsh 因为这个包声明了 dsh.bundle，把它追加进 dsh.profile.bundles。生成的 profile package.json 大致如下：

{
  "name": "dsh-profile-demo",
  "private": true,
  "dependencies": {
    "dsh-hello-plugin": "link:/path/to/hello-plugin"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "dsh-hello-plugin"
      ]
    }
  }
}

其中 dependencies 是由 pnpm 链接的树外插件依赖，dsh.profile.bundles 的数组顺序就是加载顺序。先不启动、只验证叠加结果，再正式启动：

dsh --profile demo --dump-config   # 输出中应出现 "# == dsh-hello-plugin" 层标记
dsh --profile demo

--dump-config 会打印叠加后的生效配置，方便核对每一层来自哪个组合包。移除插件同样一条命令：

dsh plugin --profile demo remove dsh-hello-plugin   # 依赖与对应配置层一并移除

patch 按 id 整行替换的两个推论

dsh 采用的是“按 id 整行替换 config 值”而非深度合并，这对组合包作者意味着：

• 你的 patch 可以按 id 覆盖前面各层的行（就像 dsh-web-app 覆盖 dsh-base 的行那样），但必须重述该行需要的每一个键，只写改动的那个键会丢掉其余配置；
• 用户可以在自己 profile 的 cordis.patch.yml 里覆盖你的行而无需改动你的包，所以请把用户大概率会保留的值设为默认配置，其余交给 schema 承担。

内置组合包名称始终从 dsh 安装目录本身解析，pnpm 只管理树外的包，因此你的组合包可以放心依赖 @deepseek-ai/dsh-base 存在且与安装保持一致。

小结

安装插件就是往 profile 的 bundles 列表追加一个声明了 dsh.bundle 的包；生效配置按 bundles → profile patch → home patch → --patch overlay 的顺序逐层叠加，后者整行胜出。