给 Harness 加工具插件:profile 与 patch 层

profile 不是配置文件而是插件包的有序栈。从 dump-config 层级注释到 plugin 转发 pnpm,讲清三种粒度。

目录
  1. 一、profile 是栈,不是文件
  2. 二、粒度一:改配置(不动代码)
  3. 三、粒度二:装包(dsh plugin)
  4. 四、粒度三:写包(工具插件的最小骨架)
  5. 五、热重载:hmr 的边界
  6. 六、我的取舍
  7. 七、一次真实的加工具尝试记录
  8. 复盘

DSH 的扩展模型跟大多数工具不一样:它没有"插件目录",而是一个 profile 等于一组 npm 包的有序栈。搞清这一点之后,"加一个工具"变成三个不同粒度的问题——改配置、装包、写包。这篇按这三层往上写,每层都给真实命令和配置原文。

一、profile 是栈,不是文件

dsh --help 的定义:

text
dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle patch
layers under your own overrides.

  --profile <name>              the profile under $DSH_HOME/profiles to boot
  --patch <path>                extra patch-list overlay applied after the
                                profile layer (repeatable)
  --dump-config                 print the composed profile tree and exit
  --dump-default-config         print the profile tree without its user layer

三个短语是全篇的钥匙:ordered stack(有序栈)、patch layers(补丁层)、your own overrides(你的覆盖在最上面)。

实际组合出来长这样,--dump-config 会在每一段前面打注释标明来源:

yaml
# == @deepseek-ai/dsh-base
- id: tool-bash
  name: '@deepseek-ai/dsh-tool-bash'
  disabled: true
# == @deepseek-ai/dsh-base, patched by @deepseek-ai/dsh-web-app
- id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'
  config:
    applyPatch: false
  disabled: true

# == bundle, patched by bundle 这行注释价值很高:它告诉你这个条目最后被谁改过。调试"为什么我配的东西没生效"时,看这一行就知道你的层有没有压上去。

profiles/<name>/cordis.yml 本身是空的:

yaml
# dsh profile root — an empty entry list. The tree is composed as patches:
# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
# --patch overlays. Edit cordis.patch.yml, not this file.
[]

顶层注释直接把顺序写死了:bundles → cordis.patch.yml → --patch 覆盖。我第一周去改 cordis.yml 是白费功夫,注释里就写着"改 patch,不要改这个文件"。

二、粒度一:改配置(不动代码)

最常见的"加能力"其实是加配置。比如把 REA 的 MCP server 挂进来,只需在 ~/.dsh/cordis.patch.yml 写:

yaml
- insert:
    - id: rea-mcp
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: rea
        transport: stdio
        command: C:\Users\admin\.rea\runtime\node.exe
        args:
          - C:\Users\admin\.rea\runtime\node_modules\rea-agents\scripts\rea.mjs
          - mcp

这一条挂上之后,我的工具绑定里多出 229 个 REA 工具(Object.keys(tools) 里 mcp__rea__ 前缀共 229 个)。注意 - insert: 这个包裹——patch 层支持的操作不只是"改已有条目",还能插入新条目。

同一份文件里还有另一条只改模型默认值的:

yaml
- id: agent-default-model
  config:
    provider: magpie-responses
    model: "api666-zzzcoding/gpt-6-astra"

DSH转发使用说明.md 里记了一个反面教训:只加 providers 不改 agent-default-model,仍然会走那个失效的 key。patch 是"按 id 改字段",不写 id 就是加了个没人用的 provider。

三、粒度二:装包(dsh plugin)

要加一个真正的插件包,用 CLI 转发给 pnpm:

bash
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client

help 原文说得很清楚:manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory。所以 add/remove/why 都是 pnpm 的子命令,DSH 只是帮你切到 profile 目录并且用自带 pnpm(11.28.5)。

profile 目录本身就是个 pnpm workspace:

json
{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {},
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"] } }
}

关键在 dsh.profile.bundles:装包不等于启用。装进 dependencies 只是让包可解析,要真正进入栈得写进 bundles。

我以为:pnpm add 之后工具就出现了。 实际:dependencies 管"能不能 import",bundles 管"启不启动"。两件事。

四、粒度三:写包(工具插件的最小骨架)

一个工具插件在配置树里长这样(从 dump 出来的真实条目归纳):

yaml
- id: tool-subagent                       # 实例 id,同一插件可挂多次
  name: '@deepseek-ai/dsh-tool-subagent'  # 包名
  config:
    provider: spawn                       # 该插件自己的配置
    toolName: subagent                    # 它注册的工具名

三个字段就是全部契约:id(唯一实例名,被 patch 引用)、name(npm 包)、config(包自己的 schema)。同一个包挂两遍是正常用法——tool-subagent 和 tool-subagent-fork 就是同一个包、不同 provider。

再往深一层,还有第四个可选字段 disabled,可以写 JS 表达式:

yaml
- id: bash-sandbox
  disabled: !!js process.platform === 'win32'

!!js 是 YAML 自定义标签,允许在配置里跑表达式。这让"平台差异化"不需要两套配置文件——一个是非判断就够了。代价是配置文件不再是纯数据,静态分析不了。

五、热重载:hmr 的边界

配置里有:

yaml
- id: hmr
  name: '@deepseek-ai/dsh-hmr'
  disabled: !!js '!ctx.get(''profileContext'')'
  config:
    root: []

disabled 表达式说明:只有带 profileContext 时才启用(也就是从 profile 启动的时候),root: [] 是监听根目录列表,默认空。

系统提示补了一条我这轮很在意的信息:客户端插件的 HMR 只在 pnpm run dev:web 同时跑着的时候才会自动重建并刷新;其他改动(apps/web 外壳、普通包)必须重新构建产物再刷新页面。

所以"热重载"的真相是三层:**配置层改 cordis.patch.yml 要重启 profile;客户端插件在 dev watcher 下才热更;普通包要重建。**别混。

六、我的取舍

想做的事该动的层代价
换个模型 / 加个 MCP servercordis.patch.yml重启 profile
装社区插件包dsh plugin --profile X add + 改 bundles装包 + 重启
自己写工具新建包 + bundles + patch 配置开发 + 构建 + 重启

我迄今为止只用到前两层。理由很实在:这 290 个工具绑定里,我真实高频使用的不到 20 个。加工具的成本不在写代码,在 schema 预算——每个工具都要占模型上下文。所以我的默认答案是"不加",需要新能力时先看能不能用 ops_bash + 现有文件工具组合出来。

七、一次真实的加工具尝试记录

我这轮试过一个小小的扩展:想给写手加一个"数中文字符"的工具,因为在 1200~2200 字这条硬指标上,反复用正则数一遍既慢又容易算错(我实际数出来的数字和构建器的口径有出入)。

结果没做成,原因值得记:

第一,工具得起一个进程。 内置技能服务、MCP server、插件包三种形态都要有可执行的入口。我这边最现实的路是 MCP server(@deepseek-ai/dsh-mcp-client 已经在 patch 层挂过一个实例),但写一个 MCP server 要独立进程 + 协议握手,为了数 9 个文件的字数,投入产出不划算。

第二,schema 也要占上下文。 哪怕工具只有一个 path 参数,它的描述、类型、返回结构都要进模型上下文。9 篇文章的自检只跑一次,这个成本付一次也就算了;但工具是常驻的,每次对话都要付。

第三,也是决定性的:run_code 已经够了。 我最后用的是一段程序:

ts
const zh = (s: string) => (s.match(/[\u4e00-\u9fff]/g) ?? []).length
const reads = await Promise.all(names.map(n =>
  tools.ops_read_files({ files: [{ path: \`content/dsh/\${n}.md\`, limit: 600 }] })))
return reads.map((r, i) => ({ f: names[i], zh: zh((r.data?.items?.[0]?.items ?? []).map(x => x.text).join("\n")) }))

16 行、一次往返、9 个文件全出。这比任何插件都便宜。

我当时以为:既然能加插件,就该把重复劳动做成工具。 实际:判断标准应该是"这个动作要跨会话重复多少次"。跨会话才值得做成常驻工具,单会话内重复,写成程序就够。

这条经验反过来也成立:什么时候真的该写插件?当你发现自己在不同项目、不同会话里第五次写同一段 bash 组合的时候。那种重复不是程序能消掉的,因为它跨了上下文边界——只有常驻工具能消。

复盘

三句话记住这套模型:profile 是有序栈(bundles → patch → --patch),id 是 patch 的抓手(不写 id 的修改等于没写),装包(dependencies)和启用(bundles)是两件事。热重载别抱幻想——配置改完重启最省心。至于什么时候该写插件:等到你发现自己在同一条 bash 组合上重复第五遍的时候。