宿主兼容性：验收标准与升列车 SOP
September 12, 2026 · View on GitHub
dsh 宿主频繁发布 rc 列车（如 0.1.0-rc.x → 0.1.1-rc.x），本插件的兼容性靠自动化验收保证，不靠手工记忆。本文是唯一判据。
验收判据（全绿 = 兼容通过）
| # | 判据 | 谁跑 | 命令 |
|---|---|---|---|
| 1 | peer ranges 匹配目标列车（npm semver prerelease 规则） | 人 + CI | 对照 package.json peerDependencies |
| 2 | 零依赖桩 smoke 全绿（host 114 项 + client 20 项） | CI / 本地 | node scripts/smoke.mjs && node scripts/smoke-client.mjs |
| 3 | 真实宿主 e2e 全绿（boot、HTML 预加载、settings seam、持久化） | compat 巡检 / 本地 | node scripts/e2e-host.mjs |
| 4 | 浏览器面板渲染 + 核心动作可用（备份/保存/reset） | 发版前人工抽检一次 | 隔离环境 boot 后浏览器操作 |
e2e 脚本的断言清单见 scripts/e2e-host.mjs 头注释；其中 HTML 预加载官方 client 包这条专门防"客户端列车陷阱"（见下）。
版本矩阵
| dsh-backup | 宿主列车 | 状态 | 备注 |
|---|---|---|---|
| ≤0.6.x | 0.1.0-rc.6+ | 历史版本，不再维护 | |
| 0.7.0–0.7.1 | 0.1.0-rc.8 | ⚠️ 仅 node 侧可用 | web 客户端在旧列车上报 "HTML did not preload"（陷阱②） |
| 0.7.2 | 0.1.1-rc.2 | 历史版本 | peers ^0.1.1-rc.2 |
| 0.8.0 | 0.1.1-rc.2 | 历史版本 | settings seam |
| 0.9.0 | 0.1.1-rc.2 | 历史版本 | doctor 体检/救援通道/智能备份三件/恢复保护；发版前全量兼容实测：9 个历史版本真实归档恢复 + 0.7.2/0.8.0→main 真实宿主升级 + 自动备份真定时全绿（598 断言） |
| 0.11.3（2026-09-12 已发 npm） | 0.1.5-rc.1 / rc.2 | ✅ 本地全量验收绿（2026-09-12） | peers 追加 ^0.1.5-rc.1（semver 同元组规则覆盖 rc.2）。rc.2 适配面实测为零：六个 node 侧 peer 包 rc.1↔rc.2 逐字节相同（tarball diff，导出面零增删），client 包列车未动（dsh-client-runtime 最新仍为 0.1.1-rc.2）。rc.2 真机 e2e 32/32；跨列车原地升级 e2e（rc.1 宿主 + 0.11.2 → rc.2 宿主 + 0.11.3）14/14，设置与归档无损 |
| 0.12.0（2026-09-12 已发 npm，当前 latest） | ✅ 本地全量验收绿（2026-09-12：smoke 256 + e2e-host 34 + 跨列车升级 14） | 新增迁移预检（拒绝规则校准自宿主 0.1.5-rc.2 的冻结清单：v0 51 类 / v2 51 类 / 来源 kind 15 类）与凭据哨兵；peers 不变，声明 engines.dsh |
归档格式兼容（插件自身）
归档格式变更必须双向兼容：新版本能读旧归档（新 meta 字段缺省视为旧行为，如 meta.types 缺省 = 全量归档）、旧版本遇新归档安全降级（新前缀归档如 dsh-t- 不进旧版 listBackups/轮换——看不见、不误删）、meta/边车字段只增不改。smoke.mjs 的"老归档无边车兼容"与分类型场景是这一节的回归防线。
已知陷阱（升列车前先读）
- semver prerelease 陷阱：
^0.1.0-rc.6匹配不了0.1.1-rc.2——npm 只允许同[major,minor,patch]元组的 prerelease 互相满足。每发新 rc 列车，peerDependencies 必须跟着升。 - 客户端列车陷阱：插件 web 面板依赖宿主 HTML 预加载
/plugins/<pkg>/client.js。0.1.1-rc+ 的 webserver 才生成预加载；旧列车上 node 侧一切正常但浏览器报client-modules: HTML did not preload @deepseek-ai/dsh-client-modules/client.js。peerDependencies 表达不了这个约束——e2e 判据 #3 的 HTML 断言就是它的回归防线。 - pnpm 默认 24h 冷却期：pnpm 10 在 CI 默认启用
minimumReleaseAge（供应链保护），新列车发布后 24h 内日常 CI 装 peers 会红。这是有意保留的防线：等满即可，不要在日常 CI 加豁免。compat 巡检 job 因职责是追新，显式豁免。
升列车 SOP
- 确认上游变更面：diff 新旧列车各依赖包（重点 dsh-commands / dsh-settings / typert-protocol 的导出面）。
- 升
package.jsonpeerDependencies 到新列车 → 开 PR。 - 等 pnpm 冷却期满（≤24h），CI 绿。
- 手动触发 compat workflow（Actions → Host compat → Run workflow）或等每日巡检 → e2e 绿。
- 合并 → 打 tag
vX.Y.Z自动发 npm（publish.yml）。 - 更新上面的版本矩阵。
若 compat 巡检红了而仓库代码未变：优先怀疑上游列车破坏，看 host-compat issue 里的 run 链接定位。