前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的架构：宿主与社区插件各自维护版本线。每次桌面端提示有新版本，常见顾虑是：点更新后，一批插件会不会静默失效，而往往要到真正要用时才发现。

已有做法多半是凭经验猜、或更新后再逐个排查。dsh-compat-gate（维护者 Elevaene，社区分类为工作流）做的是另一件事：在更新前、以及装市场新插件前，用离线静态方式读各插件 package 里的兼容声明，给出逐插件结论和整体建议；不加载、不试跑第三方插件。下面介绍它解决什么问题、怎么用，以及使用时要注意的边界。

这是什么¶

dsh-compat-gate 是 DSH 的兼容闸门插件：Check whether your installed dsh plugins still work before you install a dsh update（安装 dsh 更新之前，检查已装插件是否仍可用）。

• 维护者：Elevaene
• 仓库：https://github.com/Elevaene/dsh-compat-gate
• 社区目录：https://www.skillhub.cn/plugins/Elevaene/dsh-compat-gate
• 许可证：MIT（见仓库 README）
• 当前 package 版本：0.2.9（以仓库 package.json 为准）

宿主与插件版本不同步时，它把「要不要更新」从赌一把换成可核对的清单；每条结论会标出依据的声明原文与范围，而不是猜测。

核心功能¶

更新前判定 check¶

读取宿主目录中的 app-update.yml 定位更新源，拉取目标版本，逐个已装插件比对兼容声明，结果写入账本（ledger）。

更新后复核 audit¶

用当前真实运行的宿主版本重算全部插件，与账本上一次的结论对比；「上次相容 → 现在会失效」的条目会进入实证失效清单。dsh 更新后首次启动会自动跑一次（与账本里记录的宿主版本比对），Web 面板可直接显示「确认失效」列表。若未触发复核（宿主版本未变），面板仍显示账本上次的宿主信息，不会退化成空白占位。

会失效时的升级提示¶

当市场最新版声明能覆盖目标 dsh 版本时，输出可复制的一行安装命令，形如 dsh plugin --profile <name> add <包>@<版本>；覆盖不了则不给出命令，避免误导。

历史账本 ledger¶

每次检查的宿主版本、目标版本、逐插件结论都会留档，可回看。

发布时效预警 freshness¶

判定某个 npm 版本是否仍在 pnpm 的 minimumReleaseAge 等待期内，并说明豁免清单与 registry 的读取来源。check 会顺带查这条信息；若新版仍在等待期，面板与徽章会标出「现在装会被拒」类提示。

Web 面板与徽章¶

会话视图增加「兼容闸门」标签页；当确有插件会失效时，输入框上方会出现小徽章（例如「兼容闸门 · N 个会失效」）。仅有「无法判断」、或全部相容时，徽章不出现，避免噪音。面板可一键调用桌面宿主自带的更新流程（window.dshDesktop.updates.open()），检查与下载由宿主完成，插件不自行实现更新。

实现上的几个要点（与判定可信相关）¶

• 零依赖：仅使用 node:* 内置模块，不 import @deepseek-ai/*（profile 经 symlink 安装时宿主 node_modules 不可见）。
• 自带 semver 子集，并与 node-semver 做差分测试（README 记载 1184 组、0 处不一致）。
• 对 dsh 预发布线固定 includePrerelease: true，避免把 0.2.x-rc.N 误判为不满足。
• 兼容声明支持三种写法：dsh.compatibility.dsh、engines.dsh、peerDependencies["@deepseek-ai/dsh*"]；并校验 cordis / schemastery 的 peer 声明配对。
• 每个插件三态：相容、会失效、无法判断（无 dsh 兼容声明时 deliberately 不报推测结论，也不试加载）。
• 整体四档：update、caution、update-plugins-first、defer。

安装与启用¶

环境要求（来自 README 与 package.json）：

• Node.js >= 20.3.0
• dsh >= 0.2.1-rc.1

官方安装命令如下。装完后重启 dsh；若 profile 的 dsh.profile.bundles 未自动追加，可在 $DSH_HOME/profiles/<name>/package.json 末尾手动加入 "dsh-compat-gate"。

dsh plugin --profile web add github:Elevaene/dsh-compat-gate

重启后在会话中执行：

/compat check

离线或本地开发时，可用目录联接挂进 profile（README 以 Windows PowerShell 为例）；联接后同样要把 "dsh-compat-gate" 写入 bundles。注意：之后在该 profile 跑 pnpm install 可能清掉联接。

典型用法¶

两种入口能力相同：斜杠命令与工具 compat_gate。

斜杠命令示例：

/compat                 同 /compat check
/compat check
/compat 0.3.0           只判定指定版本，不碰网络
/compat audit           用真实宿主复核，并与上次对比
/compat ledger          看账本
/compat freshness       发布时效总览
/compat freshness 包名  只查一个包

工具 compat_gate 的 action 对应：check（默认）、audit、ledger、freshness；可选 target 指定版本，persist 控制是否写账本（默认 true）。自然语言提问（例如「dsh 要更新了，我的插件会坏吗」）也可触发同类能力。

命令输出会列出宿主与目标版本来源、profile 路径、逐插件版本与结论说明，以及整体判定档（如 caution）与简短说明。README 中有完整样例，此处不重复粘贴。

面板里「我已知晓」会按指纹（宿主版本 + 目标版本 + 各插件名字@版本:结论）抑制徽章，直到 dsh、目标版本或任一插件结论变化；数据经会话投影下发，不经过模型，查看面板不消耗额度。

适用场景与注意¶

适合谁

• 经常跟随 dsh nightly / rc 线更新，且 profile 里插件较多、依赖各插件 engines / peer / dsh.compatibility 声明的开发者。
• 在市场装插件前，想确认是否撞上 pnpm minimumReleaseAge 等待期（默认 README 写 1440 分钟）或 lockfile 连带校验问题的人。

务必知晓

• 插件在当前 dsh 进程权限下运行；安装前请自行阅读仓库源码与 MIT 许可证，确认可接受其行为（读更新 feed、registry 文档、本地 profile 与账本文件等）。
• 它不回答「这次更新有没有安全修复或大功能」——更新 feed 只有版本、日期、大小、校验信息。
• 无兼容声明的插件只会标「无法判断」，不会试跑加载；误报比漏报更伤信任，这是产品设计上的取舍。
• freshness 依赖 registry 的 time 字段与本地 pnpm 配置，结论会随时间变化；registry 不可达时会明确说查不到，不臆造剩余小时数。
• 在纯浏览器打开 profile、未暴露 dshDesktop 时，面板仍给静态结论，但无法代为触发桌面更新，并会打印现场诊断行便于区分环境。

结尾¶

dsh-compat-gate 把「更新 dsh 会不会弄坏插件」和「市场新版本现在能不能装上」拆成可核对的离线步骤与账本对比，并在 Web 会话里用标签页和条件徽章展示结果。若你要在动宿主版本前先看清插件相容性，可从社区目录或 GitHub 查看说明并安装：

• https://www.skillhub.cn/plugins/Elevaene/dsh-compat-gate
• https://github.com/Elevaene/dsh-compat-gate