ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 cordis.yml id 怎么定:按 id 覆盖、按 id 禁用与诊断定位

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugincordis.ymlpatchentry id配置覆盖
同一个插件改了三层 patch 还是被覆盖?问题往往在 id。本文用覆盖、禁用、诊断三个场景讲清 id 与 name 的分工,以及 id 改动带来的连锁反应。

有个现象很典型:你在 profile 的 patch 里改了端口,重启后发现没生效;再改一层,还是原值。翻遍配置也找不到谁覆盖了谁。

这类问题十有八九不在配置值上,而在 id 上。

先看一个 DSH plugin 改不动的配置

DSH plugin 配置没生效时,先别怀疑值,要怀疑 id 对不对。 假设组合包里有一行:

yaml
- insert:
    - id: web
      name: '@deepseek-ai/dsh-web-app'
      config:
        port: 3080

用户想改成 8080,在 profile 的 patch 里写:

yaml
- id: web
  config:
    port: 8080

重启后端口还是 3080。原因有两个,任何一个都足以让改动失效:

  1. 这行 patch 没有 insert,它期望命中一个已存在的 id;如果前面的层里 id 不叫 web,就命中不了;
  2. 即使命中了,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 命中同一行,然后替换它。

正确写法要把整行需要的东西重述一遍:

yaml
- id: web
  config:
    port: 8080
    host: '127.0.0.1'

为什么必须重述? 因为 patch 替换的是目标行的整个 config 值,不做深度合并;你写几个键,最后就剩几个键,其余全部回落到 schema 默认值。这条规则对组合包作者有两个直接影响:

  1. 覆盖别层时,必须把该行需要的每个键都写出来,不能只写改动项;
  2. 给用户留的自定义空间要尽量小——默认值写进 schema,而不是写死在 config 里,用户改一个字段时才不会牵连一片。

一个实用习惯:覆盖前先 dump-config 看目标行当前的完整 config,复制过来再改。 凭记忆补键,迟早漏。

场景二:DSH plugin 按 id 禁用

按 id 禁用插件比卸载再装快,适合临时排查。 写法是给目标行加 disabled:

yaml
- id: web
  disabled: true

disabled 接受布尔值、null 和表达式标记。未设置 group: true 的禁用行可以省略必需的 config,因为 Loader 不会初始化它。

这里有个容易踩的细节: 禁用 group: true 的行时,它下面的子项仍会按启用状态校验;插入到禁用 group 的 patch 也一样——「禁用了但配置写错」仍然可能报错。临时禁用是排查手段,不是长期配置;长期不用就卸载,禁用的行会一直参与组合与校验,出问题时容易误判。

场景三:DSH plugin 诊断时按 id 定位

排查 DSH plugin 配置是否生效,最有效的一步是看组合后的配置树。 具体按下面的顺序做:

  1. 执行 <命令> --profile <名称> --dump-config;
  2. 在输出里找到你关心的 id;
  3. 看四项:path、name、status、configRef;
  4. 找不到 id,说明那行没进组合,问题在上游 patch 或 bundles 列表;
  5. 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 本地调试。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 cordis.yml 里,entry 的 id 可以省略吗?省略后会怎样?

DSH plugin 的 entry id 可以省略,Loader 会接受。但省略 id 的行无法被后续 patch 按 id 命中覆盖,也难在诊断输出里定位;缺失非空 id 的非 insert patch 会被当作无操作,并留下 Loader 警告。

按 id 覆盖插件行时,为什么只改一个字段会把其他配置弄丢?

因为 DSH plugin 的 patch 替换的是目标行的整个 config 值,不是深度合并。你只写一个键,其余键就没了。覆盖时必须重述该行需要的每一个键,或者接受其余字段回落到默认值。

改了插件 entry 的 id 之后,用户的自定义配置为什么失效了?

用户的 patch 是按 id 命中 DSH plugin 那一行的。id 一改,命中失败,用户那层就不再生效。id 属于对外契约,要改就得按破坏性变更处理,提前在版本说明里写清楚。

怎么用 dump-config 确认某个插件 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 行为参考

来源