前言¶
DeepSeek Harness（DSH）的插件裝在 profile 目錄裏，由 package.json 的 dsh.profile.bundles 決定啓動時加載哪些。裝了一個有問題的插件之後，常見情況是啓動過程中拋錯——窗口打不開，或者閃一下就退出。而這個插件是在 DSH 裏裝的，界面本身已經壞了，就沒有辦法在 DSH 裏把它卸掉，形成死鎖。
社區裏已有插件管理、市場安裝等能力，但那些都假設 DSH 還能正常啓動。下面介紹維護者 skyjjgw 的 dsh-version-guard（DSH 版本守衛）：在 DSH 還健康時自動記錄回退點，DSH 崩壞後用獨立進程打開恢復頁，把 profile 的配置退回上一個成功啓動的版本。倉庫分類爲 admin-security，當前版本 0.1.1，MIT 許可。
這是什麼¶
dsh-version-guard 記錄插件版本與配置快照；插件衝突導致 DSH 崩壞後，可在 不加載任何 DSH 代碼 的進程裏回退到上一個可用狀態（Out-of-process rollback）。
設計上最關鍵的一點：恢復能力不放在恢復對象裏面。離線恢復頁不 import 任何 @deepseek-ai/* 代碼，只依賴 Node 與 profile 目錄，因此插件把 DSH 搞壞時它照樣能用。
核心功能¶
自動回退點¶
在 DSH 還健康時，每次成功啓動後自動記錄一個回退點，內容包括：
- 插件清單與每個插件的版本；
- 決定加載哪些插件的配置文件快照。
成功啓動的判定不是「端口在監聽」，而是 HTTP 服務對自身發請求並拿到響應之後，才把啓動記錄標記爲成功並打回退點。
離線恢復¶
DSH 起不來時，通過 dsh-version-guard.cmd 或 node lib/bin/version-guard.js 啓動恢復服務，在瀏覽器裏操作。恢復頁可：
- 查看當前插件版本（要求版本 / 實際安裝版本 / lockfile 鎖定版本、啓用狀態及原因）；
- 管理版本回退點（對比、回退、刪除；默認保留最近 30 個）；
- 一鍵救援或預演（預演只計算會退回哪一版，不改文件）；
- 單插件停用 / 恢復啓用 / 鎖定版本；
- 顯式點擊才執行「同步依賴」（
pnpm install --ignore-scripts）。
回退覆蓋範圍¶
回退點覆蓋決定 profile 是什麼的文件：
| 文件 | 說明 |
|---|---|
package.json |
依賴版本 + dsh.profile.bundles |
cordis.patch.yml |
用戶補丁層（插件啓停與配置覆蓋） |
pnpm-lock.yaml |
實際解析到的版本 |
不復制 node_modules；不碰會話、密鑰、其他設置；不快照或回寫 .dsh-market/state.json。插件啓停以 cordis.patch.yml 爲準，與官方插件管理器共用同一份狀態。
組成概覽¶
| 部分 | 位置 | 作用 |
|---|---|---|
| 宿主插件 | lib/host/index.js |
寫啓動記錄、成功啓動後打回退點、掛載恢復頁 HTTP 接口 |
| 設置頁 | lib/client/client.js |
DSH 設置裏「版本守衛」頁 |
| 離線恢復 | lib/recovery/ + lib/bin/version-guard.js |
脫離 DSH 進程的恢復服務 |
| 共享核心 | lib/core/ |
快照、恢復、版本識別、插件啓停、pnpm 調用 |
數據寫在 profile 目錄下的 .dsh-version-guard/（含 boot.json、guard.lock、snapshots/）。
安裝與啓用¶
DSH 可用時，用官方插件命令安裝到實際使用的 profile（下面以 web 爲例）：
dsh plugin --profile web add github:skyjjgw/dsh-version-guard
安裝後重啓 DSH。倉庫已包含可直接運行的 lib/，無需額外構建，也未發佈到 npm。請在發生故障前保存本倉庫副本，方便直接運行 dsh-version-guard.cmd 或 node lib/bin/version-guard.js；離線入口不依賴 DSH 成功啓動。
也可把整個目錄放到 DSH 插件目錄，在 profile 的 package.json 裏用 link: 依賴並在 dsh.profile.bundles 中加入 dsh-version-guard，再在 profile 目錄執行 pnpm install --ignore-scripts。把 dsh-version-guard.cmd 放到順手的位置（例如桌面）；它會去找 DSH 自帶的 Node 運行時，不要求用戶單獨安裝 Node。
運行環境要求 Node >=22.19.0（見 package.json 的 engines）。
典型用法¶
DSH 崩掉之後（推薦）¶
雙擊 dsh-version-guard.cmd，在瀏覽器離線恢復頁點「一鍵救援」。它會找到最近一次成功啓動時的回退點，先把當前狀態記成新回退點，再寫回 package.json、cordis.patch.yml、pnpm-lock.yaml 等；若插件版本有變化，提示點「立即同步依賴」跑 pnpm install。然後關閉頁面，重新啓動 DSH。
命令行¶
dsh-version-guard.cmd --rescue --dry-run :: 預演，不改任何東西
dsh-version-guard.cmd --rescue :: 直接回退
dsh-version-guard.cmd --status :: 查看各插件版本與啓動健康狀況
dsh-version-guard.cmd --list :: 列出所有 profile
dsh-version-guard.cmd --install :: 同步依賴（與恢復頁「立即同步依賴」等價）
不想整體回退時¶
在恢復頁「當前插件版本」裏對可疑插件點「停用」。停用會在 cordis.patch.yml 寫入對應入口的 disabled: true，不刪依賴、不改 bundles、不刪文件，可隨時「恢復啓用」。
DSH 仍可用時¶
設置裏會出現「版本守衛」頁，內嵌同一套恢復能力；宿主通過 /dsh-version-guard/* 路由提供寫操作，並帶本進程生成的請求令牌。
適用場景與注意¶
適合誰： 經常試裝社區插件、擔心一次衝突導致 DSH 完全無法打開、需要在 profile 層做可撤銷回退的 DSH 用戶。
務必知曉：
- 插件在 DSH 進程內以當前用戶權限運行；安裝前應閱讀 GitHub 源碼 與 MIT 許可證，自行判斷是否信任維護者 skyjjgw。
- 不做 DSH 應用本體版本回退，只回退插件與 profile 配置。
- 依賴同步需要網絡；回退點裏的版本若本地已沒有，須聯網才能裝回。
- 連續 2 次啓動未完成會判定爲崩潰循環，控制台會打印救援指引。
- 即使設置裏沒有「版本守衛」頁（宿主未加載），離線恢復頁依然可用。
社區插件目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係；DSH 生態是「一切皆插件」，本工具是社區維護的安全/運維向補充。
鏈接¶
- 目錄頁：https://www.skillhub.cn/plugins/skyjjgw/dsh-version-guard
- 倉庫：https://github.com/skyjjgw/dsh-version-guard
經過上面的步驟，在 DSH 健康時裝好版本守衛並保留 dsh-version-guard.cmd，相當於爲 profile 留了一條不依賴 DSH 界面就能撤銷插件組合變更的退路。
