前言¶

DeepSeek Harness（DSH）把能力拆成可安装的 profile 插件。升级 dsh 之后，老插件常因 peerDependencies 与当前运行时不匹配，在启动预检阶段被拒绝加载。表面现象往往很迷惑：插件仍在 dsh plugin list 里、文件也在 profile 的 node_modules 中，但整块功能消失，或 dsh 直接起不来；stderr 里通常只有一行英文告警，且只在「恰好只装那一个冲突插件」时容易看到，重启后才暴露问题，回溯成本高。

下面介绍社区插件 dsh-compat-vet（维护者 liujianqiao701，分类 admin-security）。它把兼容性检查做成主动、集中、中文、可操作的报告；装进 profile 后还会在 dsh web 页面顶部弹出横幅，支持隔离、卸载或升级等按键修复（改前自动备份、复检不过自动回滚）。体检与 CLI 默认只读，写 profile 仅发生在你于页面上明确选择修复动作之后。

这是什么¶

dsh-compat-vet 是 DSH 的 Cordis 插件，同时提供独立 CLI dsh-compat-vet。npm 包版本为 0.3.1（MIT 许可证），声明 dsh.engines.dsh: "*"，Node 需 >=20。它在不维护「dsh 版本号 → 能力」硬编码表的前提下，动态加载本机 dsh 安装目录下的 @deepseek-ai/dsh-app-boot，实测是否存在 evaluatePluginCompatibility 以及拦截行为，再对当前 profile 已装插件做审计，并标注每条发现 dsh 内置预检会不会同样发现。

核心功能¶

与 dsh 内置预检对齐，并多查几类盲区¶

dsh 的兼容性预检主要检查 peerDependencies 里以 @deepseek-ai/dsh / @deepseek-ai/dsh- 开头的键；没有 peerDependencies 字段时，预检会直接视为兼容。本插件在此基础上还会读 dsh.engines.dsh、dsh.compatibility.dsh 等非标准声明，标记「完全没有 peer 的插件」、lock 与 manifest 漂移、以及「快要不适配」（声明范围当前满足，但推算到 dsh 下一小版本或大版本会掉出范围）等情况。报告里对 dsh 是否会发现该问题使用三态标注，并写明依据是实测校准还是该版本无此检查。

措辞随本机 dsh 实测能力变化¶

若本机 dsh 会因 peer 不匹配在启动时拒绝加载，告警写「启动时会被拒绝加载」；若该版本根本没有预检、插件会照常加载，则明确写「本机 dsh 不会拦下它」；探测失败则写「本次未能实测」，并建议用 --anchor 指定 dsh 的 package.json 重跑。allow-version 类修复建议只在实测存在 compatibility.json 豁免机制时才出现；页面横幅不提供「豁免继续加载」选项，因为豁免不能让下次启动不被拦下。

四种入口¶

1. 装进 profile（推荐）：每次 dsh 启动自动体检，有问题输出中文 stderr 摘要；注册会话工具 plugin_compat_check；存在未解决问题时注入系统提示词段落，便于 agent 主动提醒。
2. 独立 CLI：不依赖 dsh 模块，适合 dsh 因冲突起不来时单独排查。
3. 程序化引用：dsh-compat-vet/audit 导出 auditProfile、auditProfileProbed 等。
4. dsh web 横幅：阻断类问题顶部横幅，1 隔离（从 bundles 摘掉、保留依赖）、2 卸载、3 升级（需联网，不保证新版兼容）、R 重新体检；阻断与「快要不适配」可通过摘要与视图切换同屏查看。

修复走 dsh 的 pluginManager（有则优先），改前备份到 profile 下 .compat-vet-backup/<时间戳>/，改后复检；HTTP 修复接口仅接受本机回环与同源请求。

安装与启用¶

从 npm 安装（README 给出的使用者路径）：

dsh plugin --profile web add dsh-compat-vet

包已发布至 npm：dsh-compat-vet（文档记载 latest = 0.3.1）。dsh plugin add 会同时写入 profile 的 dependencies 与 dsh.profile.bundles。

卸载：

dsh plugin --profile web remove dsh-compat-vet

社区目录页（与 DeepSeek / 幻方无官方从属，仅为独立收录站点）：https://www.skillhub.cn/plugins/liujianqiao701/dsh-compat-vet
源码与说明：https://github.com/liujianqiao701/dsh-compat-vet

典型用法¶

启动后看 stderr 或会话内复查¶

装进 profile 后，若存在阻断项，启动日志可能出现类似摘要（示例环境 dsh 0.2.0-rc.2）：

dsh-compat-vet: 检测到 1 个插件与 dsh 0.2.0-rc.2 存在兼容性问题：
  [阻断] dsh-cost-meter@1.7.35 — 与 dsh 0.2.0-rc.2 不兼容，启动时会被拒绝加载
      建议：dsh plugin --profile web add dsh-cost-meter@latest
  完整报告：运行 `dsh-compat-vet`，或在会话里用 plugin_compat_check 工具。

在会话中可让 agent 调用 plugin_compat_check 获取完整中文报告与可复制修复命令。

dsh 起不来时用 CLI¶

dsh-compat-vet                  # 默认 profile（$DSH_PROFILE 或 web）
dsh-compat-vet --profile web    # 指定 profile，优先于环境变量 DSH_PROFILE_DIR
dsh-compat-vet --home <目录>     # 指定 DSH 主目录
dsh-compat-vet --anchor <路径>   # 指定 dsh 的 package.json，用于校准
dsh-compat-vet --json           # JSON 输出
dsh-compat-vet --all            # 列出无问题的插件
dsh-compat-vet --quiet          # 一行结论，便于脚本

退出码：0 无问题、1 发现问题、2 体检未完成。

Web 界面按键修复¶

执行 dsh web 打开 GUI 后，存在冲突时页面顶部出现横幅。不在输入框内可直接按数字键；在输入框内需 Alt+数字。修复结果（含是否落盘、是否需重启、失败回滚）显示在横幅上。从局域网 IP 访问 GUI 时修复接口返回 403，页面其余功能仍可用。

只读预览横幅样式（不发起修复）可在源码目录执行：

npm run preview

适用场景与注意¶

适合谁：经常升级 dsh、profile 里插件较多、或曾遇到过「列表里还在、启动时被 skipping bundle」的维护者与开发者。也适合在 CI 或启动脚本里用 dsh-compat-vet --quiet 做守门。

权限与安全：插件以当前 dsh 进程的权限读写 profile；一键修复会修改 package.json 的 bundles 或触发卸载/升级。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。常规体检不联网；仅选择「升级」时会联网拉包。

能力边界（README 明确说明）：0.1.7-rc.1 之前无兼容性预检与豁免，本插件只能告知风险，无法替 dsh 拦载；它聚焦版本冲突导致的启动拒绝，不保证升级后运行时一定无 bug；@deepseek-ai/* bundle 按 dsh 安装目录实测处理，第三方占用该 scope 可能漏报。校准结论绑定「本机当前这份 dsh」；定位安装目录时优先当前进程入口，其次环境变量与 PATH 等。

结尾¶

dsh-compat-vet 把分散在 stderr 的英文预检结论，整理成中文、可执行命令与（在 web profile 下）可按键完成的修复路径，并用对本机 dsh-app-boot 的实测校准避免「写死版本号表」的维护负担。若你维护 DSH 插件组合，可先在目录页了解收录信息，再按上述命令装入 profile 或单独运行 CLI 做一次全量体检。

• 目录页：https://www.skillhub.cn/plugins/liujianqiao701/dsh-compat-vet
• GitHub：https://github.com/liujianqiao701/dsh-compat-vet