前言¶
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 插件生態提供了必要的“安全網”，有效降低了因配置衝突導致的啓動失敗風險。
