dsh-plugin-safety：插件健康告警与自动修复

DSH（DeepSeek Harness）采用“一切皆插件”的理念，随着插件生态的扩展，管理插件健康状态成为日常运维的必要环节。插件可能会因依赖缺失、代码错误或配置问题而失效。dsh-plugin-safety 提供了故障防控的最后两环：启动前的预检与运行时的自动修复。

是什么¶

这是一个由 Seryta 维护的 DSH 插件，核心功能是插件健康告警：预检失败自动禁用后页面持久弹窗；出现不可用插件告警即自动创建 headless 修复会话。

许可证：MIT
依赖：零第三方依赖，仅使用 Node/Python 标准库

核心功能¶

预检失败自动禁用并落盘告警：在 dsh-web 启动前，预检脚本会检查 profile 中未禁用的插件，对 import 失败的插件自动写入 disabled: true（bundle 则移除 bundle），并落盘告警。
持久告警 + 自动创建修复会话：浏览器端渲染红色告警卡片，刷新或重开页面都会重现；Host 端在返回告警前，会为每个告警 action 创建修复会话。
一致性修复：只要出现“不可用插件已被禁用/需人工处理”的告警，Host 端就会自动创建修复会话。无论告警是来自预检脚本还是直接写入 notice.json，均遵守此规则。

工作原理¶

Host 端与 Client 端分离。Host 端通过 GET /plugins/dsh-plugin-safety/notice 返回告警前，会检查 fixActionIds 是否覆盖全部 action。如果未覆盖，调用 check-profile-plugins.py --ensure-fix 补启动修复会话。

为防止并发重复启动，系统使用文件锁机制。修复会话为 headless 任务，自身失败不会阻塞 host。

组件¶

文件	职责
`index.js`	Host 端：告警读写端点 + 返回前 ensure-fix
`client.js`	浏览器端：持久弹窗、× 关闭（POST 清除）
`scripts/check-profile-plugins.py`	预检、自动禁用、告警落盘、修复会话启动
`cordis.patch.yml`	bundle patch：把插件挂进 profile
`dsh.plugin.json`	DSH 插件元数据

告警文件¶

告警数据存储在 $DSH_HOME/storages/plugin-safety/notice.json（默认为 ~/.dsh/storages/plugin-safety/notice.json）。

{
  "at": 1786799000000,
  "actions": [
    {
      "id": "some-plugin",
      "name": "some-plugin",
      "kind": "patch",
      "reason": "Cannot find package 'some-plugin'",
      "disabledAt": 1786799000000,
      "autoDisabled": true,
      "profile": "/home/me/.dsh/profiles/web"
    }
  ],
  "fixStartedAt": 1786799001000,
  "fixActionIds": ["some-plugin"],
  "fixWorkspace": "/home/me/.dsh/plugin-maintenance",
  "fixLogFile": "/home/me/.dsh/plugin-maintenance/plugin-safety-fix.log"
}

用户通过 POST 同一端点清除告警，文件重置为 {"at": 0, "actions": []}；下一条新告警会重新生成。

安装与启用¶

通过 DSH 插件命令安装：

dsh plugin --profile web add github:Seryta/dsh-plugin-safety

安装后重启 dsh-web（Host 端需要进程重新 import；Client 端是静态服务，重启前刷新页面也能拿到新逻辑）。

启动前预检（推荐）¶

将随包脚本放到 $DSH_HOME/scripts 并挂到 systemd ExecStartPre：

mkdir -p ~/.dsh/scripts
cp ~/.dsh/profiles/web/node_modules/dsh-plugin-safety/scripts/check-profile-plugins.py \
   ~/.dsh/scripts/check-profile-plugins.py

在 systemd 服务配置中添加：

ExecStartPre=-/home/<you>/.dsh/scripts/check-profile-plugins.py

- 前缀表示预检失败不阻断启动；脚本对能自动禁用的失败返回 0，对无法自动禁用且需人工处理的失败返回 1。

验证¶

npm test                       # host/脚本/客户端逻辑测试，全部使用假 dsh，不创建真实会话
node --check index.js
python3 -m py_compile scripts/check-profile-plugins.py

注意事项¶

浏览器 Poll 机制：浏览器只在页面加载时 poll 一次；页面开着期间新写入的告警会在下次刷新时出现。
Headless 任务：自动修复会话是 headless DSH 任务；它本身无法修复时会在会话内报告阻塞原因，host 不会阻塞重试。
DSH_HOME：$DSH_HOME 会被 host 与预检脚本一致尊重；systemd 预检通常不设置该变量，因此走默认 ~/.dsh。

总结¶

dsh-plugin-safety 通过脚本预检和自动修复会话，解决了插件失效时的自动化恢复问题。它不依赖第三方库，保持了轻量级。安装后重启服务即可生效，若需更严格的启动前检查，可参考上方集成 ExecStartPre 的示例。

GitHub 仓库 | 插件目录