给 Harness 加工具插件:profile 与 patch 层
profile 不是配置文件而是插件包的有序栈。从 dump-config 层级注释到 plugin 转发 pnpm,讲清三种粒度。
目录
DSH 的扩展模型跟大多数工具不一样:它没有"插件目录",而是一个 profile 等于一组 npm 包的有序栈。搞清这一点之后,"加一个工具"变成三个不同粒度的问题——改配置、装包、写包。这篇按这三层往上写,每层都给真实命令和配置原文。
一、profile 是栈,不是文件
dsh --help 的定义:
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 会在每一段前面打注释标明来源:
# == @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 本身是空的:
# 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 写:
- 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 层支持的操作不只是"改已有条目",还能插入新条目。
同一份文件里还有另一条只改模型默认值的:
- 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:
dsh plugin --profile web add @deepseek-ai/dsh-mcp-clienthelp 原文说得很清楚: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:
{
"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 出来的真实条目归纳):
- 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 表达式:
- id: bash-sandbox
disabled: !!js process.platform === 'win32'!!js 是 YAML 自定义标签,允许在配置里跑表达式。这让"平台差异化"不需要两套配置文件——一个是非判断就够了。代价是配置文件不再是纯数据,静态分析不了。
五、热重载:hmr 的边界
配置里有:
- 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 server | cordis.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 已经够了。 我最后用的是一段程序:
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 组合上重复第五遍的时候。