前言¶
DeepSeek Harness（DSH）的插件装在 profile 目录里，由 package.json 的 dsh.profile.bundles 决定启动时加载哪些。装了一个有问题的插件之后，常见情况是启动过程中抛错——窗口打不开，或者闪一下就退出。而这个插件是在 DSH 里装的，界面本身已经坏了，就没有办法在 DSH 里把它卸掉，形成死锁。
社区里已有插件管理、市场安装等能力，但那些都假设 DSH 还能正常启动。下面介绍维护者 skyjjgw 的 dsh-version-guard（DSH 版本守卫）：在 DSH 还健康时自动记录回退点，DSH 崩坏后用独立进程打开恢复页，把 profile 的配置退回上一个成功启动的版本。仓库分类为 admin-security，当前版本 0.1.1，MIT 许可。
这是什么¶
dsh-version-guard 记录插件版本与配置快照；插件冲突导致 DSH 崩坏后，可在 不加载任何 DSH 代码 的进程里回退到上一个可用状态（Out-of-process rollback）。
设计上最关键的一点：恢复能力不放在恢复对象里面。离线恢复页不 import 任何 @deepseek-ai/* 代码，只依赖 Node 与 profile 目录，因此插件把 DSH 搞坏时它照样能用。
核心功能¶
自动回退点¶
在 DSH 还健康时，每次成功启动后自动记录一个回退点，内容包括：
- 插件清单与每个插件的版本；
- 决定加载哪些插件的配置文件快照。
成功启动的判定不是「端口在监听」，而是 HTTP 服务对自身发请求并拿到响应之后，才把启动记录标记为成功并打回退点。
离线恢复¶
DSH 起不来时，通过 dsh-version-guard.cmd 或 node lib/bin/version-guard.js 启动恢复服务，在浏览器里操作。恢复页可：
- 查看当前插件版本（要求版本 / 实际安装版本 / lockfile 锁定版本、启用状态及原因）；
- 管理版本回退点（对比、回退、删除；默认保留最近 30 个）；
- 一键救援或预演（预演只计算会退回哪一版，不改文件）；
- 单插件停用 / 恢复启用 / 锁定版本；
- 显式点击才执行「同步依赖」（
pnpm install --ignore-scripts）。
回退覆盖范围¶
回退点覆盖决定 profile 是什么的文件：
| 文件 | 说明 |
|---|---|
package.json |
依赖版本 + dsh.profile.bundles |
cordis.patch.yml |
用户补丁层（插件启停与配置覆盖） |
pnpm-lock.yaml |
实际解析到的版本 |
不复制 node_modules；不碰会话、密钥、其他设置；不快照或回写 .dsh-market/state.json。插件启停以 cordis.patch.yml 为准，与官方插件管理器共用同一份状态。
组成概览¶
| 部分 | 位置 | 作用 |
|---|---|---|
| 宿主插件 | lib/host/index.js |
写启动记录、成功启动后打回退点、挂载恢复页 HTTP 接口 |
| 设置页 | lib/client/client.js |
DSH 设置里「版本守卫」页 |
| 离线恢复 | lib/recovery/ + lib/bin/version-guard.js |
脱离 DSH 进程的恢复服务 |
| 共享核心 | lib/core/ |
快照、恢复、版本识别、插件启停、pnpm 调用 |
数据写在 profile 目录下的 .dsh-version-guard/（含 boot.json、guard.lock、snapshots/）。
安装与启用¶
DSH 可用时，用官方插件命令安装到实际使用的 profile（下面以 web 为例）：
dsh plugin --profile web add github:skyjjgw/dsh-version-guard
安装后重启 DSH。仓库已包含可直接运行的 lib/，无需额外构建，也未发布到 npm。请在发生故障前保存本仓库副本，方便直接运行 dsh-version-guard.cmd 或 node lib/bin/version-guard.js；离线入口不依赖 DSH 成功启动。
也可把整个目录放到 DSH 插件目录，在 profile 的 package.json 里用 link: 依赖并在 dsh.profile.bundles 中加入 dsh-version-guard，再在 profile 目录执行 pnpm install --ignore-scripts。把 dsh-version-guard.cmd 放到顺手的位置（例如桌面）；它会去找 DSH 自带的 Node 运行时，不要求用户单独安装 Node。
运行环境要求 Node >=22.19.0（见 package.json 的 engines）。
典型用法¶
DSH 崩掉之后（推荐）¶
双击 dsh-version-guard.cmd，在浏览器离线恢复页点「一键救援」。它会找到最近一次成功启动时的回退点，先把当前状态记成新回退点，再写回 package.json、cordis.patch.yml、pnpm-lock.yaml 等；若插件版本有变化，提示点「立即同步依赖」跑 pnpm install。然后关闭页面，重新启动 DSH。
命令行¶
dsh-version-guard.cmd --rescue --dry-run :: 预演，不改任何东西
dsh-version-guard.cmd --rescue :: 直接回退
dsh-version-guard.cmd --status :: 查看各插件版本与启动健康状况
dsh-version-guard.cmd --list :: 列出所有 profile
dsh-version-guard.cmd --install :: 同步依赖（与恢复页「立即同步依赖」等价）
不想整体回退时¶
在恢复页「当前插件版本」里对可疑插件点「停用」。停用会在 cordis.patch.yml 写入对应入口的 disabled: true，不删依赖、不改 bundles、不删文件，可随时「恢复启用」。
DSH 仍可用时¶
设置里会出现「版本守卫」页，内嵌同一套恢复能力；宿主通过 /dsh-version-guard/* 路由提供写操作，并带本进程生成的请求令牌。
适用场景与注意¶
适合谁： 经常试装社区插件、担心一次冲突导致 DSH 完全无法打开、需要在 profile 层做可撤销回退的 DSH 用户。
务必知晓：
- 插件在 DSH 进程内以当前用户权限运行；安装前应阅读 GitHub 源码 与 MIT 许可证，自行判断是否信任维护者 skyjjgw。
- 不做 DSH 应用本体版本回退，只回退插件与 profile 配置。
- 依赖同步需要网络；回退点里的版本若本地已没有，须联网才能装回。
- 连续 2 次启动未完成会判定为崩溃循环，控制台会打印救援指引。
- 即使设置里没有「版本守卫」页（宿主未加载），离线恢复页依然可用。
社区插件目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本工具是社区维护的安全/运维向补充。
链接¶
- 目录页：https://www.skillhub.cn/plugins/skyjjgw/dsh-version-guard
- 仓库：https://github.com/skyjjgw/dsh-version-guard
经过上面的步骤，在 DSH 健康时装好版本守卫并保留 dsh-version-guard.cmd，相当于为 profile 留了一条不依赖 DSH 界面就能撤销插件组合变更的退路。
