DSH plugin 的 cordis.yml id 怎么定:按 id 覆盖、按 id 禁用与诊断定位
有个现象很典型:你在 profile 的 patch 里改了端口,重启后发现没生效;再改一层,还是原值。翻遍配置也找不到谁覆盖了谁。
这类问题十有八九不在配置值上,而在 id 上。
先看一个 DSH plugin 改不动的配置
DSH plugin 配置没生效时,先别怀疑值,要怀疑 id 对不对。 假设组合包里有一行:
- insert:
- id: web
name: '@deepseek-ai/dsh-web-app'
config:
port: 3080
用户想改成 8080,在 profile 的 patch 里写:
- id: web
config:
port: 8080
重启后端口还是 3080。原因有两个,任何一个都足以让改动失效:
- 这行 patch 没有
insert,它期望命中一个已存在的 id;如果前面的层里 id 不叫web,就命中不了; - 即使命中了,
config是整行替换——你只写了port,其他字段全没了,行为可能比「没生效」更奇怪。判断标准很简单:id对不上,patch 就是一段没人读的文本。
DSH plugin 的 id、name、包名,三个东西别混
DSH plugin 里三者的分工完全不同,混用会让 patch 打偏。 初学者最容易在这里绕晕:
| 名字 | 回答什么 | 例子 |
|---|---|---|
| 包名 | 从哪加载模块 | @deepseek-ai/dsh-web-app |
name | 这一行指向哪个模块 | @deepseek-ai/dsh-web-app |
id | 这一行是谁,供覆盖与诊断使用 | web |
name 和包名在多数情况下相同,因为模块通常就是包入口;但本地开发时可以写成相对路径,两者就分开了。
id 与它们都无关,它是给「行」用的,不是给「模块」用的。 同一个模块可以被挂两行,只要 id 不同;反过来,同一个 id 在最终组合里只应出现一次。
省略 id 是允许的,但会失去三样东西: 后续 patch 无法按 id 命中、诊断输出里不方便定位、重复行的判断只能靠 name。
场景一:DSH plugin 按 id 覆盖
在 DSH plugin 里,id 最主要的作用就是被后续 patch 命中并覆盖。 后应用的 patch 按 id 命中同一行,然后替换它。
正确写法要把整行需要的东西重述一遍:
- id: web
config:
port: 8080
host: '127.0.0.1'
为什么必须重述? 因为 patch 替换的是目标行的整个 config 值,不做深度合并;你写几个键,最后就剩几个键,其余全部回落到 schema 默认值。这条规则对组合包作者有两个直接影响:
- 覆盖别层时,必须把该行需要的每个键都写出来,不能只写改动项;
- 给用户留的自定义空间要尽量小——默认值写进 schema,而不是写死在 config 里,用户改一个字段时才不会牵连一片。
一个实用习惯:覆盖前先 dump-config 看目标行当前的完整 config,复制过来再改。 凭记忆补键,迟早漏。
场景二:DSH plugin 按 id 禁用
按 id 禁用插件比卸载再装快,适合临时排查。 写法是给目标行加 disabled:
- id: web
disabled: true
disabled 接受布尔值、null 和表达式标记。未设置 group: true 的禁用行可以省略必需的 config,因为 Loader 不会初始化它。
这里有个容易踩的细节: 禁用 group: true 的行时,它下面的子项仍会按启用状态校验;插入到禁用 group 的 patch 也一样——「禁用了但配置写错」仍然可能报错。临时禁用是排查手段,不是长期配置;长期不用就卸载,禁用的行会一直参与组合与校验,出问题时容易误判。
场景三:DSH plugin 诊断时按 id 定位
排查 DSH plugin 配置是否生效,最有效的一步是看组合后的配置树。 具体按下面的顺序做:
- 执行
<命令> --profile <名称> --dump-config; - 在输出里找到你关心的 id;
- 看四项:path、name、status、configRef;
- 找不到 id,说明那行没进组合,问题在上游 patch 或 bundles 列表;
- status 异常,说明该行被拒绝或只部分生效。
path比 id 更细: 同一个 group 下的子项,path 会带索引;当你的插件被包在 group 里时,靠 id 可能定位不到,需要顺着 path 找。
诊断顺序建议固定:先看行在不在,再看 config 对不对,最后才看运行时行为。 反过来查,会在一个根本没进组合的配置上耗很久。
DSH plugin 的 id 命名与稳定性规则
最后是几条可以当 DSH plugin id 规范用的建议。
用名词和短横线,不用动词。 web、tool-bash、memory 都比 doInit、handleRequest 稳定,因为后者描述行为,行为会变。
id 不要带版本号或环境名。 web-v2、web-dev 会让每次升级都变成一轮批量替换;环境差异交给 profile 或 patch 层,不要塞进 id。
把 id 当成公开接口。 用户可能按 id 覆盖你的行,组合包之间也可能按 id 互相补丁。改 id 前先确认没有外部 patch 依赖它。
同一行只出现一次。 如果 dump-config 里看到两个相同 id,说明有两层都插入了它;这时不是覆盖问题,而是重复插入,行为取决于组合顺序。
id 看起来只是一个字符串,实际决定了「谁能改这一行、改完能不能被发现」。定名字时多花一分钟,能省掉后面几小时的覆盖排查。想看层顺序与整行替换的完整规则,读 DSH plugin 打包成 bundle;想看 Config 与默认值怎么设计,读 DSH plugin 配置;想看诊断命令怎么组合,读 DSH plugin 本地调试。
常见问题
DSH plugin 的 entry id 可以省略,Loader 会接受。但省略 id 的行无法被后续 patch 按 id 命中覆盖,也难在诊断输出里定位;缺失非空 id 的非 insert patch 会被当作无操作,并留下 Loader 警告。
因为 DSH plugin 的 patch 替换的是目标行的整个 config 值,不是深度合并。你只写一个键,其余键就没了。覆盖时必须重述该行需要的每一个键,或者接受其余字段回落到默认值。
用户的 patch 是按 id 命中 DSH plugin 那一行的。id 一改,命中失败,用户那层就不再生效。id 属于对外契约,要改就得按破坏性变更处理,提前在版本说明里写清楚。
用 dump-config 看组合后的 DSH plugin 配置树,每一项都会带 path、可选 id、name、status 与 configRef。找不到你的 id,说明那一行没进组合;status 异常则说明该行被拒绝或部分生效。
相关术语
- entry
- entry 是 cordis.yml 里的一行插件配置,描述加载哪个模块、用什么 id、传什么 config 以及是否禁用。— DeepSeek Harness CLI 行为参考
- id
- id 是 entry 的稳定标识,用于后续 patch 命中同一行、诊断输出定位,以及判断该行是否进入组合。— DeepSeek Harness CLI 行为参考
- patch
- patch 是叠加在配置树上的覆盖层,按顺序应用,后应用的层按行胜出,并整行替换目标 config。— DeepSeek Harness CLI 行为参考
- dump-config
- dump-config 是不启动服务、直接打印组合后配置树的命令,输出包含每个 entry 的 path、id、name 与 status。— DeepSeek Harness CLI 行为参考
来源
- DeepSeek Harness CLI 行为参考· deepseek-ai
- DeepSeek Harness 开发文档:打包与安装插件· deepseek-harness
- DeepSeek Harness 开发文档:插件配置· deepseek-harness