升级兼容卫士 zzy6-a/dsh-upgrade-guard

dsh-upgrade-guard

Download
license
dsh-plugin

DeepSeek Harness 兼容卫士。

dsh-upgrade-guard 监视 DSH 宿主版本。升级后首次启动时，它会检查所有已安装插件与新宿主的兼容性，并在你确认后升级、修复、禁用插件，或在必要时回滚到上一个宿主版本——避免一个不兼容的社区插件把整个 harness 留在"起不来"的状态。

DSH 处于开发者预览阶段，破坏性变更会持续发生。这个插件针对的是预期内的失败，而不是边缘情况。

功能

- 升级后自动巡检：宿主版本变化后的首次启动自动触发
- 声明兼容性检查：读取每个已安装插件的 engines.dsh 与 peerDependencies，与解析出的宿主/core 版本比对，沿用生态的方向性策略（低于下限、显式上界 = 风险；隐式 caret 上界 = 警告）
- 安装/加载/结构检查：Loader fiber 状态、悬空 junction、core 包遮蔽
- 组合层卫生检查：扫描 cordis.patch.yml 的重复 entry id / 失效 patch 目标，重复项可一键整理（改动前自动备份）
- 插件自检 probe：插件可声明 dsh.compat.probe，守卫在隔离子进程里执行并汇总通过/失败
- dshmarket 诊断接入：检测到市场插件时自动合并其组合诊断（重复、失效、多版本、peer 不匹配）
- 引导式修复：联网找"与当前宿主兼容的最高版本"（不是盲目 @latest）→ 安装；不行则修复本地安装；再不行则禁用
- 启动失败救援：宿主外 supervisor 在主进程起不来时仍可工作：解析启动日志、禁用故障 entry、重启宿主
- 宿主回滚：禁用仍救不回来时，从快照直接启动上一个宿主版本，无需 sudo/npm
- 手动重启：设置面板 / 弹窗里一键重启 DSH
- 中文界面与通知：巡检结果、事故、操作项展示在设置页与浮层弹窗

工作原理

一个包，三部分：

| 部分 | 位置 | 职责 |
| 宿主插件 | DSH profile bundle | 版本基线、扫描、修复链、HTTP API、settings 命名空间 |
| 客户端 UI | DSH Web 客户端 | 设置页面板、插件卡片、开关、浮层弹窗 |
| Supervisor | 独立 Node 进程 | adopt 宿主、快照宿主版本、崩溃救援、回滚、执行重启 |

运行数据在 ~/.dsh/upgrade-guard/。

组合卫生与插件自检

- 每次巡检会检查 profile 的 cordis.patch.yml：重复的顶层 - id:、dsh --dump-config 报出的失效 patch 目标；面板顶部显示「组合诊断」，有重复项时提供「整理重复项」（保留最后一次，改动前备份）。
- 如果本机装有 dsh-market，守卫会读取它的只读诊断接口并把重复/失效/多版本/peer 不匹配合并进同一块（市场不可用或需要授权时自动跳过，不影响巡检）。
- 插件作者可以声明自检钩子，守卫会在独立 Node 子进程里执行（崩溃/超时不会影响宿主）：

{
"dsh": {
"compat": {
"probe": { "file": "./lib/probe.js", "export": "probe", "timeoutMs": 20000 }
}
}
}

// lib/probe.js —— ctx: { hostVersion, profile, dshHome, pluginDir }
export async function probe(ctx) {
const ok = await checkSomethingAgainst(ctx.hostVersion)
return { ok, message: ok ? '正常' : '与当前宿主不兼容的原因' }
}

安装

GitHub Release（当前分发通道）

dsh plugin --profile web add \
https://github.com/zzy6-a/dsh-upgrade-guard/releases/download/v0.2.0/dsh-upgrade-guard-0.2.0.tgz

也可以从 Releases 页面下载 .tgz 后安装本地文件：

dsh plugin --profile web add /path/to/dsh-upgrade-guard-0.2.0.tgz

npm（发布后可用）

dsh plugin --profile web add dsh-upgrade-guard

本地源码（开发）

dsh plugin --profile web add link:/path/to/dsh-upgrade-guard

然后重启一次 DSH（设置 → 升级守卫 → 重启 DSH，或用你的启动器）。之后守卫作为 profile bundle 常驻。

宿主升级后会发什么

1. 对比当前宿主版本与上次记录的版本
2. 审计所有已安装的社区/本地插件
3. 无风险：轻提示"升级后兼容检查通过"
4. 有风险：弹窗列出插件、原因、建议动作
5. 确认后执行修复链，每一步改动前都自动备份：
- 安装与当前宿主兼容的最高版本；否则
- 修复本地安装（pnpm install、有构建脚本则重建）；否则
- 在 cordis.patch.yml 写入 disabled 覆盖行（可在面板恢复）
6. 需要重启生效的改动会附一键重启

启动失败救援与回滚如果插件树加载失败，任何宿主内插件都救不了——这时由宿主外 supervisor 兜底：

- 读取最近的启动日志，匹配 failed to apply loader entry ()
- 用 dsh --dump-config（只读）把包名映射成 entry id，备份 patch，写入 disabled: true，重启
- 仍失败或无法归因到插件：从 ~/.dsh/upgrade-guard/host-snapshots// 启动上一个宿主版本，并记录回滚
- 所有动作写入 incidents/，下次成功启动后由插件弹窗展示

快照是宿主目录的完整拷贝（每份约 300MB，保留最近 2 份）。

设置

设置 → 插件 → 插件配置 里的升级守卫卡片：

- 启用升级守卫：软开关；关闭后不自动巡检/提醒，但保留插件、手动检查和 supervisor
- 自动巡检：默认每 5 分钟轻量检查一次
- 当前状态 + 立即检查
- 组合诊断：重复 entry / 失效 patch / 市场诊断摘要；重复项可一键整理
- 卸载升级守卫

cordis.patch.yml 支持组合层默认配置：

- id: dsh-upgrade-guard
config:
autoScanMs: 0 # 自动扫描间隔（毫秒），0 = 仅启动/升级/手动 supervisor: true # 宿主外救援 / 回滚 / 重启 snapshotHost: true # 保留宿主快照用于回滚

HTTP API

仅限本机同源：

- GET /dsh-upgrade-guard/api/state
- POST /dsh-upgrade-guard/api/check
- POST /dsh-upgrade-guard/api/repair { name?, dryRun? }
- POST /dsh-upgrade-guard/api/toggle { name, enabled }
- POST /dsh-upgrade-guard/api/uninstall { name, allowSelf? }
- POST /dsh-upgrade-guard/api/config { enabled?, autoScan? }
- POST /dsh-upgrade-guard/api/patch-fix（整理重复 patch entry，返回备份目录）
- POST /dsh-upgrade-guard/api/restart
- POST /dsh-upgrade-guard/api/alert/ack | alert/ack-all

环境要求

- DSH >= 0.1.5-rc.1
- Node.js >= 22.19
- UI 功能需要 Web profile（其他 profile 仍可执行巡检）

Windows

- 原生 Windows 与 WSL 2 都可用（DSH 官方开发文档两种都支持）
- 守卫只用 Node API；拉起进程加了 windowsHide；Windows 下重启用 taskkill /PID /T /F 杀进程树
- Electron / DSH Desktop 宿主由桌面外壳管理生命周期：守卫跳过 supervisor，重启按钮会提示你使用桌面应用
- Windows 做了代码层兼容，但未做完整实机验证；遇到问题请附 ~/.dsh/upgrade-guard/ 日志提 issue

开发

npm install
npm run typecheck
npm test
npm run build # host: tsc -> lib，client: tsdown -> lib/client.js
npm pack # 产出 dsh-upgrade-guard-.tgz

Supervisor 源码在 scripts/supervisor.mjs，构建时复制进 lib/。

安全与边界

- 守卫会修改文件：cordis.patch.yml，修复过程中会调用包管理器命令；每次写入前都备份到 ~/.dsh/upgrade-guard/backups/
- 不拦截宿主升级，也不修改插件源码；没有兼容版本时只能禁用或回滚
- 未声明兼容信息的插件无法提前判定，只能运行期兜底
- 这是一个独立社区项目，不是 DeepSeek 官方产品

Contributors / 致谢

- zzy6-a — 作者
- DeepSeek V4.1 — 架构设计、实现、测试与发布流程

License

MIT