前言¶
在 DeepSeek Harness（DSH）裏，插件和 Skill 會隨 profile 演進頻繁增減、升級。常見做法是手工改配置或憑記憶對照「上次裝過什麼」，一旦升級後行爲異常，很難說清楚磁盤上實際版本、聲明規格與加載狀態是否一致，也未必能在更新前留下可覈對的證據。
DSH Version Manager 面向正在運行的 profile，提供已安裝清單、更新預覽、更新前可驗證快照，以及僅在可行時纔給出的恢復路徑。它與「整包備份」或「一鍵回滾一切」不同：恢復範圍有明確邊界，Git、tarball 與本地產源還需要重放證據。下文按安裝與使用順序說明其能力與限制。
這是什麼¶
DSH Version Manager（npm 包名 dsh-version-manager）是 maintainer Tang Yixiao（GitHub：tangyixiao）維護的 DSH 插件，歸類爲 admin-security。當前資料中的源版本爲 0.1.3（以倉庫 package.json 爲準），軟件許可證爲 MIT，通過 npm 與 GitHub Releases 分發。
插件自述目標可以概括爲四點：對「實際安裝了什麼」做誠實的清單；預覽一次更新會改什麼；在變更前記錄可驗證的快照；只有在恢復路徑確實能工作時才向用戶提供該路徑。
核心功能¶
真實安裝清單¶
界面側強調三類信息對齊：聲明的規格（Declared specs）、磁盤上的版本（disk versions）以及加載狀態（load state）。便於在動手升級前，先覈對當前 profile 裏插件與 Skill 的真實情況，而不是僅看配置裏的寫法。
更新預覽¶
在執行更新前，可先查看從當前狀態到目標狀態的精確變化（README 中表述爲 from → to）。先預覽再改，降低「升完才發現依賴或版本不符合預期」的成本。
可驗證快照¶
在更新前寫入快照，並能讀回 SHA-256 等證據鏈（README 示意圖主題爲「Snapshot before update: Write and read back SHA-256 evidence」）。目的是讓「更新前那一刻」的狀態有據可查，而不是依賴口頭或零散筆記。
顯式恢復邊界¶
恢復能力單獨說明：已知狀態與可用的恢復路徑；不能恢復時不會假裝可以。README 明確寫道：Restore is not a full backup——恢復某一插件版本並不會自動回滾配置、依賴樹或 agent presets。對 Git、tarball 和 local sources，還需要 replay evidence。這與「整環境時光機」類產品要區分開。
安裝與啓用¶
環境要求¶
| 項 | 要求（資料來源） |
|---|---|
| DSH | >=0.2.2-rc.1 |
| Node.js | >=22 |
| 插件版本 | 0.1.3（當前記錄） |
Desktop¶
在資料給出的路徑下，通過 Extensions → Plugin Management → Add Plugin 安裝 release 提供的 .tgz 包。
可控的 Web profile¶
對你明確掌控的 Web profile，使用官方文檔中的命令（版本號與包名須與發佈一致）：
dsh plugin --profile web add dsh-version-manager@0.1.3
安裝到已有的 Desktop 或 Web profile 後，打開 Version manager。若是新建的空 profile，資料還提醒：除本插件外通常還需要 Web app bundle。
更細的用法、配置與排錯見倉庫內 docs/guide.en.md（英文）。
典型用法（README 級流程）¶
README 給出的入門路徑較短，可按下面順序操作，細節以界面與 guide 爲準：
- 按上一節完成安裝，進入 Version manager。
- 先審閱 inventory（已安裝清單），確認聲明規格、磁盤版本與加載狀態。
- 若要升級，先查看 from → to 的更新預覽，再決定是否執行變更。
- 在真正更新前，利用快照能力留下可回讀的證據；若之後需要恢復，僅在插件判定的可行範圍內操作，並理解配置與依賴等不會隨「插件版本恢復」一併回滾。
倉庫 package.json 中 dsh.client 配置爲 Web 平臺且 immediately: true，表示客戶端側與 Web 側的集成方式以清單爲準，具體交互以運行中的 DSH 版本爲準。
適用場景與注意¶
適合誰： 經常在同一 profile 上迭代插件與 Skill、希望在升級前有清單與預覽、並需要在變更前留下可覈驗快照的 DSH 用戶；關心 admin-security 類能力、希望對「能恢復什麼」有明確預期的維護者。
使用邊界： 不要把它當作全量備份或配置/依賴一鍵回滾工具。對來自 Git、壓縮包或本地的來源，恢復敘事與 replay evidence 綁定，使用前應在 guide 中核對術語與步驟。
安全與信任： 插件在當前 DSH 進程權限下運行，能接觸 profile 內的插件與 Skill 相關信息。安裝前建議閱讀 LICENSE、SECURITY.md 與源碼；社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，生態遵循 DSH「一切皆插件」的擴展方式，本插件爲社區維護的獨立組件。
參與開發與質量門禁時，維護者在 README 中給出的本地檢查包括：
npm test
node tools/check-repository.mjs
結尾¶
DSH Version Manager 把「看清楚裝了什麼、升級會改什麼、升級前留下可驗證快照、只在可行時談恢復」串成一條可操作的版本管理路徑，並坦誠標註恢復不能覆蓋配置與依賴等範圍。需要進一步瞭解分類、簡介與鏈接時，可打開社區目錄頁 tangyixiao/dsh-version-manager；源碼、Releases 與 issue 見 GitHub 倉庫。
