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 倉庫 | 插件目錄