DeepSeek Harness (DSH) 插件：dsh-updater-npm

DSH 採用「一切皆插件」的架構，這意味着核心功能的擴展通常通過插件實現。在開發和運維過程中，保持 DeepSeek Harness（DSH）核心版本的更新以及獲取官方文檔，往往是兩個需要分別處理的環節。dsh-updater-npm 插件將這兩個功能整合在一起：它既可以通過 npm 一鍵更新 DSH 本身，也能增量同步官方文檔到本地，並提供搜索與閱讀工具。

核心功能¶

該插件主要提供以下能力：

DSH 更新（npm）：自動檢查 @deepseek-ai/dsh 的最新版本，支持一鍵執行 npm install -g @deepseek-ai/dsh@latest，更新過程中顯示實時進度。
DSH 文檔（官方）：將官方 docs/ 目錄增量同步到本地（按 GitHub blob sha 跳過未變文件），支持進度條顯示，並提供 dsh_docs_search 和 dsh_docs_read 兩個模型工具。
多語言支持：界面與宿主端消息支持中文/English，自動跟隨系統語言切換。
插件自檢與閘門：插件自身會檢查版本並對照 npm 最新版，若自身版本過舊，會提示優先更新插件並禁用 DSH 更新按鈕。
運行模式檢測：自動識別當前 DSH 是通過 npm 全局安裝（npm-global）還是源碼樹模式（source）運行。
升級安全網：升級前自動備份配置、預設及會話日誌（保留最近 5 份），支持暫存安裝、回滾機制以及遺留文件清理。

安裝與啓用¶

安裝該插件需要使用 DSH 的插件管理命令。安裝完成後需重啓 DSH Web 實例，設置頁會出現「DSH 更新」和「DSH 文檔」兩個卡片。

dsh plugin --profile web add dsh-updater-npm

使用說明¶

DSH 更新流程¶

在設置頁點擊「通過 npm 更新」即可執行更新。該操作會自動檢查最新版本，檢測到新版本時，設置頁左側導航「DSH 更新」旁會顯示紅色小圓點。

更新過程會顯示實時進度，完成後出現「重啓 DSH」按鈕。點擊後，程序會按原啓動命令退出並重新拉起。

版本比較規則：版本比較遵循 semver 風格。如果本地版本比遠端新（例如 rc.7 vs rc.6），系統不會誤報更新。

插件自身版本檢查：卡片會顯示插件自身的版本號。若檢測到插件自身有新版本，會顯示紅色提示並提供更新命令，此時「通過 npm 更新」按鈕會被禁用。這是爲了防止舊版插件的升級流程存在缺陷（如依賴缺失）導致升級失敗。

DSH 文檔同步¶

文檔同步默認關閉，需在設置頁開啓「自動同步官方文檔」開關。

存儲位置：文檔同步至 $DSH_HOME/docs-sync/，索引文件爲 $DSH_HOME/docs-sync/.index.json。
搜索與閱讀：開啓後可使用 dsh_docs_search 搜索本地索引（中文查詢優先中文文檔），使用 dsh_docs_read 讀取文檔（支持按章節聚焦，80KB 截斷）。
增量同步：首次同步約 217 篇文檔，之後每 24 小時靜默增量更新。

運行模式與更新策略¶

插件會根據當前 DSH 的運行模式採取不同的更新策略：

運行模式	更新方式
npm-global	正常部署場景。Windows 上使用 staged 更新（新版本裝入獨立暫存目錄，原子替換後重啓），非 Windows 使用原地 `npm install -g`。
source	源碼樹運行模式（如 `pnpm dsh web`）。此時無法通過 npm 更新，需使用 `git pull`。

升級安全網細節：
在 Windows 環境下，插件會嘗試使用 PowerShell 7 (pwsh)。若未安裝，會提示一鍵安裝。
對於 npm-global 模式，升級前會自動備份配置文件、預設及會話日誌到 $DSH_HOME/upgrade-backups/ 目錄。
升級完成後，舊版本目錄會被重命名爲 dsh.old-* 以保留回滾點。如果升級過程中出現異常，可以根據需要手動回滾。

API 與命令¶

除了設置頁的操作，插件還提供了 HTTP 接口和對話指令：

更新檢查：GET /dsh-updater-npm/check
執行更新：POST /dsh-updater-npm/update
重啓實例：POST /dsh-updater-npm/restart
清理遺留文件：POST /dsh-updater-npm/cleanup
觸發文檔同步：POST /dsh-updater-npm/docs/sync
文檔搜索：GET /dsh-updater-npm/docs/search?q=&lang=&limit=
文檔閱讀：GET /dsh-updater-npm/docs/read?path=&section=

注意事項¶

Windows 環境：必須安裝 PowerShell 7 (pwsh)，否則更新功能可能受限。
源碼樹模式：在源碼樹模式下，無法使用 npm 更新，需使用 git pull。
配置文件：文檔同步的開關狀態保存在 $DSH_HOME/plugin-data/dsh-updater-npm/config.json。

總結¶

dsh-updater-npm 通過將 DSH 的更新管理與官方文檔的本地化同步結合，簡化了開發者的維護流程。它提供了清晰的進度反饋、完善的備份回滾機制以及對不同運行模式的適配，適合需要在本地深度集成 DSH 官方文檔並保持工具鏈更新的用戶。