DeepSeek Harness 插件版本兼容：engines、核心包漂移与升级顺序与排查步骤

插件兼容不是「版本号差不多就行」。 它由 engines、核心包版本与依赖解析共同决定；看错其中一项，就会出现「装上了但加载失败」。

兼容由什么决定

三个变量共同决定能不能跑。

engines 是声明，不是保证。 它告诉安装器「需要什么环境」，但不会自动修复不匹配。

核心包版本决定接口。 插件调用的方法随核心变化；版本差太多，运行时会缺方法。

依赖解析决定实例。 同一个核心包被装了两份，插件与宿主可能各用一份，行为不一致（来源）。

三类不兼容症状

症状不同，排查方向也不同。

1. 加载失败： 包解析错误、入口找不到、engines 不满足。
2. 功能异常： 加载成功但调用报错，常见于接口变化。
3. 行为不一致： 同一操作结果不同，常见于重复核心包。

加载失败最先看版本，功能异常要看调用栈，行为不一致最难查。 解析错误通常在启动日志里有明确记录；缺方法是接口变化，参数错误是签名变化，两者修法不同；行为不一致先确认核心包是否只有一份，dsh --dump-config 与依赖树都能看。

版本漂移怎么查

三步确认漂移，不靠猜。

1. 记录当前核心版本与插件版本。
2. 看插件声明的兼容区间，确认是否落在范围内。
3. 看依赖树，确认核心包是否重复或版本不一致。
4. 对照最近一次升级，判断问题是否由升级引入。
5. 用最小插件集复测，排除其他插件干扰。

兼容区间是第一个判据，依赖树是第二个判据。 超出范围不代表一定坏，但需要额外验证。重复核心包是常见根因；只升级插件不解决，需要调整依赖声明。

最小集复测是第三个判据。 多个插件同时装时，问题可能来自组合，而不是单个插件。

升级顺序

顺序错了，兼容问题会叠加。

1. 先备份： 记录版本、插件清单与配置。
2. 升核心： 到目标版本，先跑最小功能。
3. 升插件： 按兼容声明逐个升级，一次一个。
4. 验证： 每个插件装完就跑一次最小功能。
5. 回退： 出问题时只回退这一层，不要整体重装。

核心先行的原因是接口。 插件依赖核心接口；核心没到位，插件升了也可能不兼容。

一次一个插件。 批量升级出问题时，无法判断是哪一个；逐个升级，问题范围最小。

插件作者视角

减少不兼容，从声明与依赖开始。

1. 声明 engines： 写清 Node.js 与核心版本范围。
2. 核心包用 peer： 避免把核心打进自己的依赖，造成重复。
3. 声明 dsh.bundle： 让 profile 能正确识别组合包。
4. 避免私有 API： 只调用公开接口，减少版本变化影响。
5. 写兼容说明： README 里写清支持范围与已知限制。

peer 依赖是关键。 它要求宿主提供核心包，避免插件自带一份；重复核心包是很多「行为不一致」的根源。

兼容说明比版本号有用。 用户看说明能判断能不能装，不用猜。

用户视角

用户不需要读源码，但要知道三件事。

1. 装前看兼容： 插件说明里的支持范围。
2. 升级看顺序： 先核心后插件。
3. 出问题看日志： 第一处失败比最后一条报错有用。

不要用「最新版」当默认。 最新核心配旧插件、旧核心配新插件，都可能不兼容；按声明配对。

保留回退版本。 记录升级前组合，出问题能退回去；没有记录，只能从头试。

排查清单

按清单走，避免漏项。

1. 核心版本与插件版本各是多少。
2. 插件的 engines 与兼容区间是否覆盖当前版本。
3. 依赖树里核心包是否只有一份。
4. 启动日志的第一处失败是什么。
5. 最小插件集是否仍复现。
6. 回退到上一组合是否恢复。

六项都过，问题基本定位。 清单的价值是顺序固定，不会在错误方向反复。

记录结果。 版本、症状、处理方式；下次遇到同类问题可以直接复用。

下一步

先看声明，再看依赖，最后看日志。 想看插件版本兼容的规范说明，看《DSH plugin 版本兼容》；想看核心包漂移，看《核心包版本漂移》；想写第一个插件，看《照着插件市场写第一个 DSH plugin》。

来源：DeepSeek Harness 官方文档 - 打包与安装插件、dsh CLI README、deepseek-harness 仓库