dsh plugins 与 DeepSeek Harness 版本怎么对齐：兼容矩阵、锁定与升级顺序

判断 dsh plugins 能不能配当前 DeepSeek Harness，先别翻版本号，先回答四个问题。 peer 依赖说明它声明支持谁，engines 说明环境够不够，changelog 说明行为改了什么，回退路径说明坏了能不能退。四个答案凑齐，矩阵才有东西可写。

peer 依赖：这个 DeepSeek Harness 插件声明支持谁

peer 依赖是插件作者亲手写下的兼容边界，先读它，能排除掉一半的盲目升级。

从 DSH Plugin Hub 打开条目详情，先记下完整包名，再去 npm 看 peerDependencies。 它通常写成宿主版本范围，例如只接受某个大版本。落在范围之外就别装，先找兼容版本或升级本体。

范围的宽窄也要读。^ 比精确版本宽松，但宽松只代表作者有信心，不代表你测过。 把结论写成「某插件 1.4 支持本体 3.x」，比写「应该可以」有用得多，因为前者能复查，后者只能重猜。

peer 依赖为空或写成 * 时，不要理解成兼容一切。 它往往只说明作者没有声明，风险要靠实测补上。中文搜索里常见的 DSH插件、DeepSeek插件 写法只是入口，条目字段仍是英文包名，别把标题当成兼容声明。

还有一种容易被忽略的情况：插件声明了宿主范围，却把某个可选能力写成必需依赖。 装上之后功能缺失，回头看声明才发现它要的宿主版本比你高一档。遇到这种条目，先按声明降级，不要靠改配置硬撑。

engines：dsh plugins 在你的 Node 上够不够用

engines 是硬门槛，不满足时不是「可能有问题」，而是装上也起不来。

读 engines 字段时，重点看 Node 的最低版本与可选上限。 然后在本机执行 node -v，注意要看实际运行 dsh 的那个 Node，而不是另一个版本管理器里的版本。两者经常不是同一个。

部分平台能力还依赖系统库或构建工具，engines 不会写这些。 插件说明里的附加要求要一起看，尤其是需要原生模块的插件。缺了系统依赖，版本全对也加载失败。

为了插件升级 Node 之前，先看本体自己的 engines 范围。 别为了迁就一个插件，把本体跑到不支持的环境里。验证标准是插件能加载到 ACTIVE 并保持住，而不是加载后立刻退出。

changelog：dsh plugins 这一版改了什么行为

changelog 回答的是「升级后哪里会不一样」，跳过它，矩阵里的「通过」就是假的。

先扫破坏性变更：配置字段改名、默认值改变、接口移除。 这三类最容易让旧用法失效，而且往往在启动时不报错，只在你用到某个功能时才暴露。看到其中任何一类，都要把验证范围扩大一圈。

再看修复项与依赖变化。 正在困扰你的 bug 是否被点名修复，这是升级最正当的理由；新版本是否提高了宿主或 Node 要求，则决定它能不能落在你当前的环境里。两项都清楚，升级收益才算得出来。

发布时间的信号也值得看一眼。 刚发布几小时的版本，除非修的是你的阻塞问题，否则先等一等。没有 changelog 的插件只能靠小范围实测，这时更要把测试范围压小，别一次铺到全团队。

读完写一句影响判断，例如「升级后需要改配置键名」。 这句话比版本号有用，因为它会直接变成验证清单里的一项。写不出来，说明这次升级你还没想清楚。

回退路径：dsh plugins 出事后还能不能退

回退能力是升级决策的一部分；退不回去的升级不叫升级，叫单向迁移。

先确认旧版本仍可解析：npm 上还在、条目还能装，才叫可回退。 如果旧版本已被撤包，升级前就该知道这一点，而不是出事之后才发现无路可走。撤包之后再去讨论回退，只能临时换插件或等作者重新发版。

升级前把插件配置与本体版本各留一份，并保留 lockfile。 lockfile 是你回到旧组合的最短路径，前提是它没有被顺手更新掉。备份不需要多复杂，能还原就够了。

本体也要能退。插件退了、本体没退，组合仍然可能不兼容。 在隔离 profile 里先试一次退回，确认真的能退，再把它当成方案。四个问题里最容易被跳过的是这一问，代价通常也最大。

把四个答案写成一张 dsh plugins 兼容矩阵

矩阵不是全量清单，是你在用组合的体检表；行少、列少、证据具体。

行写本体版本，列写插件版本，格子里只填三种状态：通过、失败、未测。 失败必须附一句现象，否则下一次看到这个格子，没人知道它为什么失败。状态写模糊了，表格就会从证据退化成印象。

表格不求全，先覆盖你实际在用的插件与最近两个本体版本。 没装的插件不进表，进表就要有人维护。格子里的状态必须来自实际运行，不能来自「看起来没问题」。

1. 行只放当前、上一个与候选新版三个本体版本。
2. 列只放你实际在用的插件，没装的不进表。
3. 格子只写通过、失败、未测，失败附一句现象。
4. 证据写在备注里，日志位置和复现命令比形容词有用。
5. 每次升级更新一行，矩阵跟着版本走。

同事只看这张表，就应该能判断这次能不能升；做不到，说明表里缺的是证据，不是行数。矩阵的价值在更新频率，不在版面大小。每次升级后花五分钟改一行，比季度末重做一遍更可靠。

升级顺序由 dsh plugins 的声明决定

先升谁，看兼容窗口朝哪边开，不看「一般都先升本体」这种习惯。

插件已声明支持新本体时，先升本体，再逐个插件验证。 窗口是插件提前开好的，顺着走风险最低。反过来先动插件，会让旧插件面对新本体。

插件的新版本先支持新本体时，先升插件，再升本体。 两边都没声明时，在隔离 profile 里一起升，一次验证，不要在生产环境做这个实验。顺序不是规矩，是声明推导出来的结果。

锁版本时，本体与插件分别锁，并记录锁的原因和复查时间。 临时锁定很容易变成永久停留，等到下一个大版本发布，问题会一次性找上门。复查时间到了就重新评估，而不是等出事再想起这行备注。

升级后至少验证三件事：插件进入 ACTIVE、核心工具能调用、新会话能正常创建。 三项都过，才把矩阵里的「未测」改成「通过」。兼容性不是一次判断，是一条需要持续维护的线。

来源：插件与生命周期、开发第一个插件、npm @deepseek-ai/dsh。