前言¶
DeepSeek Harness（DSH）採用「一切皆插件」的擴展方式：Harness 本體與各類能力都以 bundle 形式安裝、迭代。插件一多，版本往往分散在各自目錄、pnpm-lock 與 npm registry 之間；若新版本在 package.json 裏聲明瞭 engines.dsh，還會在 DSH 版本不滿足時被安裝器擋在門外。手工逐個 pnpm update、對照 semver 與 DSH 門控，既慢也容易在「版本太新還不能裝」或「傳遞依賴根本沒動」這類細節上踩坑。下面介紹社區維護的 dsh-upgrade-assistant（GitHub：zhangrui824/dsh-upgrade-assistant）：在 DSH Web UI 的 Plugins 頁增加 Upgrades 標籤，把已安裝插件的 npm 比對、engines.dsh 預檢與就地升級收到同一界面，失敗原因用可讀文案說明。
這是什麼¶
dsh-upgrade-assistant 是面向 DSH 的升級助手插件，維護者爲 zhangrui824，在 SkillHub 目錄中歸類爲 admin-security。它在插件管理頁提供 Upgrades 標籤：對每條已安裝的 npm bundle 做更新檢查（尊重 profile 鏡像與約 5 分鐘緩存、併發 3），對 Harness 本體做 npm 最新版比對；在升級前按 DSH 同款 semver 規則評估目標版本的 engines.dsh，不滿足時顯示 Needs newer DSH 並隱藏升級按鈕；滿足條件時可一鍵就地執行升級，並在跑完後從 node_modules 回讀實際版本，避免「pnpm 成功但未真正升版」被誤報爲成功。
核心功能¶
Upgrades 標籤裏的信息結構¶
界面頂部有自檢條（例如包管理器、語言、bundle 數量、當前 DSH 版本）。主體包括：
- Harness (DSH)：當前版本 / npm 最新版，以及 Check DSH updates。
- Installed plugins：Check plugin updates 後，每行顯示 bundle 名、版本對比（如
0.77.0 → 0.78.1）、狀態（Upgrade available、Up to date、Not on npm — skipped 等），以及engines.dsh摘要。 - Version exemptions：當前生效的、可跳過 DSH 門控的
package@version許可說明。 - When an upgrade fails：四類常見失敗原因的說明。
更新檢查¶
Check plugin updates 將各已安裝 bundle 與 npm 比對（使用 profile 配置的 registry，默認 npmjs）。從 GitHub 或本地路徑安裝的 bundle 沒有 npm 版本可比，會標記 Not on npm — skipped；對這類 GitHub 來源、且帶有 npm 傳遞依賴的 bundle，可提供 Refresh bundled family，在父包 semver 允許範圍內刷新依賴，而不是誤用 --latest 去動傳遞鏈。
Check DSH updates 將當前運行的 Harness 與 npm 上最新發布比對。
就地升級機制¶
用戶點擊綠色 Upgrade available 後的 Upgrade（內聯確認後執行）：
- npm 直裝插件：執行
pnpm update --latest --config.minimumReleaseAge=0 <name>。僅在用戶點擊時關閉 pnpm 默認約 24 小時的「新版本冷卻」限制，減少「版本太新無法安裝」類失敗。 - 傳遞依賴族（由 GitHub 來源 bundle 拉入的 npm 依賴）：因
pnpm update --latest無法單獨推高傳遞依賴，插件改爲在範圍內刷新：pnpm update <deps> --config.minimumReleaseAge=0。 - 事後校驗：從
node_modules讀取實際安裝版本；若 pnpm 退出成功但未改變版本，報告爲stale，不算成功。 - 防降級：當 npm
latest標籤低於已安裝版本（官方@deepseek-ai/*等場景較常見）時拒絕更新。
engines.dsh 預檢¶
目標新版本若聲明 engines.dsh，在升級前用與 DSH 門控一致的 semver 評估（node-semver 語義，includePrerelease: true）。不滿足的 bundle 顯示 Needs newer DSH，不展示升級按鈕。解析不了的 range 語法不會阻塞升級，僅原文展示，最終以真實安裝結果爲準。
安全模型¶
自定義 Web 路由不經過 DSH Web UI 的 cookie 認證，本插件對所有路由自建信任邊界（與社區 dsh-update 同級）：
- 僅允許迴環地址（127/8、
::1）且 Host 爲迴環。 - 瀏覽器請求須同源（Origin 匹配，
sec-fetch-site非 cross-site）。 - 不信任 X-Forwarded-For；拒絕時返回
403與 JSON 原因。 - 更新路由額外要求：POST、包名 allow-list 正則（防注入與路徑穿越）、4 KB 請求體上限、single-flight（同一時刻僅一個 pnpm 操作）、10 分鐘超時並強制結束進程（Windows 用 taskkill，Unix 用進程組）。
安裝與啓用¶
從 GitHub 安裝（README 推薦方式）：
dsh plugin --profile <your-profile> add github:zhangrui824/dsh-upgrade-assistant
插件 package.json 聲明 engines.dsh: >=0.2.1-rc.2，node: >=22。許可證爲 MIT。
Host 側改動需 重啓 Harness 一次後，更新相關服務纔會就緒；僅改客戶端時刷新頁面即可。若點擊升級提示更新服務尚未就緒，通常也是 Host 未重啓所致。
典型用法¶
- 側欄進入 Plugins，打開 Upgrades 標籤。
- 點擊 Check plugin updates，查看各 bundle 與 npm 的版本差與
engines.dsh狀態。 - 對 Upgrade available 行點擊 Upgrade 完成就地升級；對 Needs newer DSH 行先升級 Harness，再回來升級插件。
- 需要時點擊 Check DSH updates 檢查 Harness 本體是否有 npm 新版本。
- 對 Not on npm — skipped 的 GitHub 來源 bundle，若存在 npm 依賴族，可使用 Refresh bundled family 刷新傳遞依賴。
與 dsh-update 的分工：dsh-update 側重其作者 @linxin666/* 族與 release notes；本插件覆蓋全局 npm bundle 視圖，並顯式區分直接依賴 --latest 與傳遞依賴 in-range 刷新兩種模式。
適用場景與注意¶
適合在本地或內網長期運行 DSH、安裝較多 npm/GitHub 混合來源插件、需要統一看版本與 DSH 兼容性的開發者與運維。插件以 當前 DSH 進程權限 執行 pnpm 與 HTTP 路由；安裝前請閱讀倉庫源碼與 MIT 許可證，自行評估是否納入環境。
已知限制（來自 README）：運行中 DSH 版本來自 DSH_CLIENT_VERSION 或從入口腳本向上查找 @deepseek-ai/dsh manifest，否則顯示 unknown（其餘功能仍可用）；需認證的私有 registry 可能失敗並顯示原因；從本地路徑安裝時插件無法升級自身（發佈到 npm 後可使用界面自舉升級）。
結尾¶
dsh-upgrade-assistant 把插件與 Harness 的版本檢查、engines.dsh 預檢和一鍵就地升級集中到 Upgrades 標籤，並對 npm 直裝與傳遞依賴族、防降級與事後校驗做了區分處理；安全上限制迴環與同源，並對升級接口做併發與超時控制。目錄頁：https://www.skillhub.cn/plugins/zhangrui824/dsh-upgrade-assistant；源碼與完整說明：https://github.com/zhangrui824/dsh-upgrade-assistant。
