dsh-compat-guardian：DeepSeek Harness 插件兼容性检查与隔离工具

前言¶

DeepSeek Harness (DSH) 的核心架构由插件构成。当插件间发生依赖冲突、版本不匹配或全局资源争用时，往往会导致宿主无法启动或功能异常。直接排查过程繁琐，且在崩溃状态下难以进行。dsh-compat-guardian 是一款专注于插件兼容性检测、隔离与恢复的插件。它通过侧边栏界面和独立命令行工具，帮助开发者在插件管理页、Web 界面或 CLI 中识别冲突、自动隔离异常插件并尝试修复。

核心功能¶

该插件提供多层次的兼容性检查与修复机制：

• 环境与版本检查：检查 DSH 版本要求、Node.js 与系统环境。
• 声明式冲突检测：解析插件的 dshCompat 元数据，检查声明的依赖、互斥关系、全局独占工具与服务，以及重复的顶层条目。
• 运行时监控：监控 Loader 的连续加载失败情况。
• 隔离与恢复：支持自动隔离冲突插件（默认策略）或自动卸载。提供恢复功能，可基于记录 ID 重新启用已隔离的插件。
• 独立诊断：提供独立的检查与离线修复命令，可在 DSH 宿主无法启动时使用。

安装与启用¶

在 DSH 插件管理页的安装框中输入以下包名：

dsh-compat-guardian@0.2.1

或使用 Desktop 命令行安装（Web 用户请将 desktop 改为 web）：

dsh plugin --profile desktop add dsh-compat-guardian@0.2.1 --save-exact --ignore-scripts

安装后，侧边栏会出现“兼容守护”入口。默认情况下，检测到冲突时会自动隔离插件，卸载需在策略中选择。

典型用法¶

Web 界面操作¶

打开侧边栏“兼容守护”可查看检查结果、插件列表和恢复记录。支持升级预检（不实际升级 DSH，仅计算兼容性）。

通过 cordis.patch.yml 配置自动策略，例如设置为 remove 以自动卸载冲突插件：

- id: compat-guardian
  config:
    policy: quarantine
    intervalMs: 30000
    failureThreshold: 2

命令行工具¶

Guardian 提供了独立的 CLI 工具，可在宿主崩溃时使用。

查看帮助：

npx --yes --package=dsh-compat-guardian@0.2.1 dsh-compat-guardian --help

常用命令：

• check：检查当前已安装和运行中的插件。
• history：查看隔离、卸载和恢复记录。
• restore：恢复已隔离插件（需提供 recordId）。
• rescue：离线修复，备份配置并停用冲突 bundle。

适用场景与注意¶

此工具适用于 DSH 0.2.0-rc.2 及后续（Peer 声明范围 >=0.2.0-rc.2 <0.3.0-0）的开发与维护场景。

注意事项¶

• dshCompat 不是官方标准：这是本插件自定义的元数据字段，用于声明互斥关系。插件作者应在 package.json 中添加该字段。
• 权限限制：Guardian 以当前 DSH 进程权限运行，无法拦截 process.exit()、原生崩溃或启动早期的宿主退出。此类情况需使用独立 CLI 进行处理。
• 配置位置：自动策略配置保存在 profile 的 .compat-guardian/preferences 目录下。
• 源码构建：如需自行构建源码，需执行 npm ci, typecheck, test, build 等步骤。

总结¶

dsh-compat-guardian 为 DSH 插件生态提供了必要的“安全网”，有效降低了因配置冲突导致的启动失败风险。

• GitHub 仓库
• 插件目录