前言¶
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 豁免機制時纔出現；頁面橫幅不提供「豁免繼續加載」選項，因爲豁免不能讓下次啓動不被攔下。
四種入口¶
- 裝進 profile（推薦）：每次 dsh 啓動自動體檢，有問題輸出中文 stderr 摘要；註冊會話工具
plugin_compat_check；存在未解決問題時注入系統提示詞段落，便於 agent 主動提醒。 - 獨立 CLI：不依賴 dsh 模塊，適合 dsh 因衝突起不來時單獨排查。
- 程序化引用：
dsh-compat-vet/audit導出auditProfile、auditProfileProbed等。 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
