# 宿主兼容机制

从 0.5.2 起，插件不再将 DSH 的发行版本号作为启动条件。0.5.1 的 14 个 DSH peer dependencies 精确锁在 `0.2.1-rc.2`，即使服务接口没有变化，宿主更新到 `rc.3` 也会拒绝加载。

## 声明与实际接口

- `engines.dsh: "*"` 使用 DSH 的独立插件兼容声明；DSH 的判定器允许预发布版本。
- 所有 `@deepseek-ai/dsh-*` peers 使用 `"*"`，保留服务依赖名称。尚未实现 `engines.dsh` 优先判定的旧宿主，也可通过 peer 回退判定。
- `@deepseek-ai/cordis: "^4.0.4"` 保留插件内核依赖范围。开发链接脚本会校验这个范围；DSH 的版本兼容判定器自身不校验 Cordis ABI。
- 服务端和客户端在注册资源之前检查实际使用的方法。缺少接口时，错误会列出方法路径；检查不依赖宿主版本号，也不调用模型或创建工程。已按可选能力处理的接口继续保持可选。

因此，宿主更新但插件依赖的内核及服务契约保持兼容时，无需为新的 DSH 版本重新改包。未来宿主若更改方法语义、参数或返回结构，仍可能需要更新适配；方法存在性检查不能预测这种行为变化。

## 可重复验证

在插件目录安装锁定的开发依赖后，链接要测试的官方宿主并执行：

```sh
node scripts/link-host-dependencies.mjs "<宿主目录>/node_modules"
DSH_HOST_NODE_MODULES="<宿主目录>/node_modules" npm run verify:compat
```

`verify:compat` 执行类型检查、测试、构建与官方宿主兼容判定器回归。判定矩阵覆盖旧版、当前版与若干未来版本号，同时验证 `engines.dsh` 和 peer 回退路径，并以旧版精确锁定声明重现 `rc.3` 拒绝加载。

未来版本号矩阵只验证清单不再拦截这些版本号，并不表示未来 DSH 的实际代码已完成验证。运行期接口测试、实际宿主启动和桌面界面操作提供另外的证据。

CI 在三种操作系统上分别安装固定基线宿主、官方 `latest` 与 `next`。固定版本用于发现已有兼容性退步，`latest` 和 `next` 分别跟踪默认发行渠道与预发布渠道的接口变化；CI 配置存在不等于对应任务已经通过。