DeepSeek Harness 兼容卫士：dsh-upgrade-guard

前言¶

DeepSeek Harness (DSH) 采用“一切皆插件”的理念，宿主与插件通过接口解耦。但在宿主升级过程中，破坏性变更时有发生，这可能导致社区插件与新宿主不兼容，进而引发宿主启动失败。

dsh-upgrade-guard 是为了解决这一痛点设计的兼容性巡检插件。它作为宿主常驻插件，在宿主升级后首次启动时自动触发巡检，能够判断插件兼容性，提供修复建议，并在宿主无法启动时，通过宿主外的 Supervisor 进程进行救援或回滚到上一个宿主版本。

是什么¶

这是一个独立社区项目，由 zzy6-a 维护，遵循 MIT 许可证。它并不修改宿主升级流程，也不篡改插件源码，而是作为一层“守卫”，在宿主升级后自动审计已安装插件的兼容状态，并通过修改配置文件来修复或禁用故障插件，从而避免宿主陷入“起不来”的状态。

核心能力¶

1. 升级后自动巡检与声明兼容性检查¶

宿主升级后首次启动时，插件会自动运行。它读取每个已安装插件的 engines.dsh 与 peerDependencies，与解析出的宿主/core 版本比对。如果插件未声明兼容信息，则无法提前判定，只能在运行期兜底。

2. 组合层卫生检查¶

插件会扫描宿主的 cordis.patch.yml，检查是否存在重复的 entry id 或失效的 patch 目标。如果发现重复项，可以一键整理（保留最后一次修改，操作前自动备份到 ~/.dsh/upgrade-guard/backups/）。此外，它还能接入 dshmarket 的诊断接口，合并市场插件的重复、失效、多版本或 peer 不匹配问题。

3. 插件自检 Probe¶

插件作者可以在插件包中声明 dsh.compat.probe。守卫会在独立的 Node 子进程中执行该 probe 并汇总通过/失败结果。这种设计确保了插件自身的兼容性检查不会影响宿主主进程的稳定性。

4. 启动失败救援与宿主回滚¶

如果插件树加载失败导致宿主无法启动，插件内所有机制都无法生效，此时由宿主外的 Supervisor 兜底：
* 救援：读取最近的启动日志，匹配 failed to apply loader entry 错误，利用 dsh --dump-config 将包名映射为 entry id，备份 patch 并写入 disabled: true，随后重启宿主。
* 回滚：如果救援无效，守卫会从 ~/.dsh/upgrade-guard/host-snapshots/<version>/ 启动上一个宿主版本。快照是宿主目录的完整拷贝（约 300MB），默认保留最近 2 份。

安装与启用¶

通过以下命令将插件添加到 DSH 的 Web profile：

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

安装完成后，重启 DSH，守卫即作为 profile bundle 常驻。你可以通过设置面板中的“升级守卫”卡片来启用、检查状态或手动重启 DSH。

配置与使用¶

cordis.patch.yml 默认配置¶

守卫支持在 cordis.patch.yml 中进行默认配置：

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

插件自检 Probe 示例¶

插件开发者可以通过声明 dsh.compat.probe 来定义兼容性检查逻辑：

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

对应的实现文件 lib/probe.js 示例：

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

注意事项¶

文件修改：守卫会修改 cordis.patch.yml，并在修复过程中调用包管理器命令。每次写入前都会自动备份到 ~/.dsh/upgrade-guard/backups/。
权限与范围：守卫不拦截宿主升级，也不修改插件源码。如果没有兼容版本，只能通过禁用或回滚宿主来解决。
Windows 兼容性：Windows 环境做了代码层兼容，但未做完整实机验证。遇到问题请附带 ~/.dsh/upgrade-guard/ 日志提 issue。
项目性质：这是一个独立社区项目，不是 DeepSeek 官方产品。