DeepSeek Harness 兼容衛士：dsh-upgrade-guard

前言¶

DeepSeek Harness (DSH) 採用“一切皆插件”的理念，宿主與插件通過接口解耦。但在宿主升級過程中，破壞性變更時有發生，這可能導致社區插件與新宿主不兼容，進而引發宿主啓動失敗。

dsh-upgrade-guard 是爲了解決這一痛點設計的兼容性巡檢插件。它作爲宿主常駐插件，在宿主升級後首次啓動時自動觸發巡檢，能夠判斷插件兼容性，提供修復建議，並在宿主無法啓動時，通過宿主外的 Supervisor 進程進行救援或回滾到上一個宿主版本。

是什麼¶

這是一個獨立社區項目，由 zzy6-a 維護，遵循 MIT 許可證。它並不修改宿主升級流程，也不篡改插件源碼，而是作爲一層“守衛”，在宿主升級後自動審計已安裝插件的兼容狀態，並通過修改配置文件來修復或禁用故障插件，從而避免宿主陷入“起不來”的狀態。

核心能力¶

1. 升級後自動巡檢與聲明兼容性檢查¶

宿主升級後首次啓動時，插件會自動運行。它讀取每個已安裝插件的 engines.dsh 與 peerDependencies，與解析出的宿主/core 版本比對。如果插件未聲明兼容信息，則無法提前判定，只能在運行期兜底。

2. 組合層衛生檢查¶

插件會掃描宿主的 cordis.patch.yml，檢查是否存在重複的 entry id 或失效的 patch 目標。如果發現重複項，可以一鍵整理（保留最後一次修改，操作前自動備份到 ~/.dsh/upgrade-guard/backups/）。此外，它還能接入 dshmarket 的診斷接口，合併市場插件的重複、失效、多版本或 peer 不匹配問題。

3. 插件自檢 Probe¶

插件作者可以在插件包中聲明 dsh.compat.probe。守衛會在獨立的 Node 子進程中執行該 probe 並彙總通過/失敗結果。這種設計確保了插件自身的兼容性檢查不會影響宿主主進程的穩定性。

4. 啓動失敗救援與宿主回滾¶

如果插件樹加載失敗導致宿主無法啓動，插件內所有機制都無法生效，此時由宿主外的 Supervisor 兜底：
* 救援：讀取最近的啓動日誌，匹配 failed to apply loader entry 錯誤，利用 dsh --dump-config 將包名映射爲 entry id，備份 patch 並寫入 disabled: true，隨後重啓宿主。
* 回滾：如果救援無效，守衛會從 ~/.dsh/upgrade-guard/host-snapshots/<version>/ 啓動上一個宿主版本。快照是宿主目錄的完整拷貝（約 300MB），默認保留最近 2 份。

安裝與啓用¶

通過以下命令將插件添加到 DSH 的 Web profile：

dsh plugin --profile web add https://github.com/zzy6-a/dsh-upgrade-guard/releases/download/v0.2.0/dsh-upgrade-guard-0.2.0.tgz

安裝完成後，重啓 DSH，守衛即作爲 profile bundle 常駐。你可以通過設置面板中的“升級守衛”卡片來啓用、檢查狀態或手動重啓 DSH。

配置與使用¶

cordis.patch.yml 默認配置¶

守衛支持在 cordis.patch.yml 中進行默認配置：

- id: dsh-upgrade-guard
  config:
    autoScanMs: 0        # 自動掃描間隔（毫秒），0 = 僅啓動/升級/手動
    supervisor: true     # 宿主外救援 / 回滾 / 重啓
    snapshotHost: true   # 保留宿主快照用於回滾

插件自檢 Probe 示例¶

插件開發者可以通過聲明 dsh.compat.probe 來定義兼容性檢查邏輯：

{
  "dsh": {
    "compat": {
      "probe": { "file": "./lib/probe.js", "export": "probe", "timeoutMs": 20000 }
    }
  }
}

對應的實現文件 lib/probe.js 示例：

// lib/probe.js —— ctx: { hostVersion, profile, dshHome, pluginDir }
export async function probe(ctx) {
  const ok = await checkSomethingAgainst(ctx.hostVersion)
  return { ok, message: ok ? '正常' : '與當前宿主不兼容的原因' }
}

注意事項¶

文件修改：守衛會修改 cordis.patch.yml，並在修復過程中調用包管理器命令。每次寫入前都會自動備份到 ~/.dsh/upgrade-guard/backups/。
權限與範圍：守衛不攔截宿主升級，也不修改插件源碼。如果沒有兼容版本，只能通過禁用或回滾宿主來解決。
Windows 兼容性：Windows 環境做了代碼層兼容，但未做完整實機驗證。遇到問題請附帶 ~/.dsh/upgrade-guard/ 日誌提 issue。
項目性質：這是一個獨立社區項目，不是 DeepSeek 官方產品。