前言¶

DeepSeek Harness（DSH）採用「一切皆插件」的擴展方式：裝得多了之後，啓停、找版本、批量升級往往要反覆打開插件市場或敲 plugin_manager 命令，分組與排序也沒有統一入口。Plugin Shelf（dsh-plugin-shelf，側欄名「插件書架」）是一個客戶端 bundle，面向已經裝進當前 profile 的插件，在側欄面板裏做排序、分組、篩選、一鍵啓停，以及基於 npm registry 的檢查和批量更新。維護者爲 QYF-888；社區目錄見 SkillHub 插件頁，源碼在 GitHub。SkillHub 爲社區獨立站點，與 DeepSeek / 幻方無官方從屬關係。

這是什麼¶

Plugin Shelf 是 DSH 第三方 bundle：host 半在 webServer 上註冊精確路由 /plugin-shelf/api，彙總 pluginManager.listBundles() 並讀寫本地狀態；client 半註冊側欄「插件書架」與主頁面板，數據全部經該 API 獲取。它不替代插件市場的「發現與首次安裝」，而是把已安裝列表當成可編排的書架來管。

兼容範圍（README / package.json）：dsh >= 0.2.0-rc.1 < 0.3.0；profile 支持 desktop / web / headless。當前包版本 1.1.2，許可證 MIT。

核心功能¶

下面按 README 功能表歸納，均可在面板中操作。

瀏覽與整理¶

• 排序：按名稱、安裝時間、大小排序，可切換升序 / 降序。
• 分組：新建任意分組；分組支持行內重命名（✎）、上下移序、摺疊、刪除；插件可移入某組或回到「未分組」。
• 未分組：「未分組」區也可重命名、摺疊，狀態會持久化。
• 移出分組：分組內每行行首紅色「−」，點擊後回到未分組；未分組行無此按鈕。
• 加插件浮窗：分組頭「+ 加插件」或新建分組後彈出；只列出當前不在任何分組的插件，支持搜索、全選、清空、勾選後加入。
• 篩選：狀態下拉（全部 / 已啓用 / 已停用）、分組下拉、「只看可更新」，與搜索框疊加；計數行顯示命中 / 總數，可「清空篩選」。
• 顯示範圍：默認只列 installed === true 且 availability === 'profile' 的插件；可選「顯示內置」查看 DSH 自帶包（不可管理）。

啓停¶

• 每個插件單獨開關。
• 每個分組可「啓用本組 / 停用本組」。
• 頂部可「全部啓用 / 全部停用」。

更新¶

• 版本探測：不依賴 pluginManager.inspect（對已裝包會 refused('already-installed')），改爲讀 npm registry 的 dist-tags.latest；默認源 https://registry.npmjs.org，面板可改並寫入 state.autoUpdate.registry。
• 自動更新：定時對比 registry 與本地版本；可只檢查或自動安裝，可限定只處理某些分組；host 側每 60 秒檢查是否到點（面板關閉仍會繼續）。
• 一鍵更新：自動更新卡片右側「一鍵更新（N）」；第一次點擊變爲「確認一鍵更新？」，4 秒內未確認則復原；確認後對 profile 內插件逐個執行 removeBundle → installBundle，彙總成功 / 總數 / 排隊 / 失敗。
• 更新失敗：展示原因、pendingBuilds 時可「批准並重試」；restart-required 會明確提示。
• 中斷修復：更新過程寫 journal（pending-updates.json），面板頂部可一鍵續裝；橫幅可關閉或清理記錄。

單次更新採用「移除再安裝」：當前 DSH 的 installBundle 對已安裝包會拋 already-installed，無法原地升級。失敗會回滾；若 removeBundle 因 bundle-in-use 失敗，會停用並排隊，重啓後由 repairUpdates 完成安裝。

卸載¶

每行行尾紅色「✕」：第一次點擊變爲「確認卸載」，5 秒內再點一次才執行；host 調用 pluginManager.removeBundle，並清理分組記錄與 journal。內置插件（removable === false）按鈕禁用。插件仍被掛載時，管理器會先停用並寫 step: 'uninstall' 的 journal，重啓後由 repairUpdates 完成卸載。

安裝與啓用¶

裝完後重啓 DSH，側欄應出現「插件書架」。官方 README 給出四種方式，任選其一：

1. 從 npm 裝（推薦：npm 來源才能被本插件的自動更新接管）：

plugin_manager install_bundle target=dsh-plugin-shelf

2. 插件市場：在 DSH 插件市場搜索 dsh-plugin-shelf 或「插件書架」，一鍵安裝。

3. 從 GitHub 裝：

plugin_manager install_bundle target=github:QYF-888/dsh-plugin-shelf

4. 本地目錄（開發時）：

plugin_manager install_bundle target=D:\path\to\dsh-plugin-shelf

說明：若 profile 內來源爲 file: / link: / git+ / github: 等，自動更新會跳過並在結果中標記 non-npm-source，其餘管理功能仍可用。README 還提到：本機依賴須爲 1.1.2 或 link: 指向源碼目錄；若被「一鍵更新」換成 git+https://github.com/QYF-888/dsh-plugin-shelf.git 且該地址停在舊提交，面板可能回退到舊客戶端行爲。

典型用法¶

日常整理¶

1. 打開側欄「插件書架」。
2. 用排序與搜索縮小列表，按項目新建分組並重命名。
3. 通過「+ 加插件」把未分組插件批量加入某組；需要時用行首「−」移回未分組。
4. 用狀態下拉或分組下拉配合「只看可更新」做例行檢查。

批量啓停¶

實驗或排障時，可先對單個分組「停用本組」，確認無問題後再「啓用本組」；全局切換用頂部「全部啓用 / 全部停用」。

檢查與更新 npm 來源插件¶

1. 在自動更新卡片配置 registry（如需非默認源）、是否自動安裝、限定分組等。
2. 使用「只檢查」或等待定時任務；對可更新項使用「一鍵更新（N）」並按二次確認流程執行。
3. 若出現 build-blocked，在面板「批准並重試」；若提示 bundle-in-use 或 restart-required，按面板說明停用、重啓或續裝。
4. 面板可展開運行日誌，查看每次檢查與安裝結果。

自測（維護者腳本）¶

倉庫提供 host Harness 自測，不依賴完整 DSH 桌面環境：

node test/host-harness.mjs

腳本在假 profile 上掛載真實 index.js，覆蓋更新、回滾、跨源拒絕等分支，見 README「自測」一節。

數據、權限與注意¶

• 狀態與日誌：$DSH_HOME/plugin-shelf/state.json（未設置 DSH_HOME 時爲 ~/.dsh/plugin-shelf/state.json）；更新中斷記錄爲同目錄下 pending-updates.json。UI 篩選等偏好雙寫服務端 state 與瀏覽器 localStorage['dsh-plugin-shelf:ui-prefs']。
• API 安全：路由帶 Origin 時需與 Host 同源，否則 403。
• 更新範圍：僅處理 availability === 'profile' 且來源爲 npm-like 的包；file: / link: / workspace: / portal: / git+ / github: / http(s): 等會跳過。
• 運行權限：插件以當前 DSH 進程權限讀寫本機 DSH_HOME、調用 pluginManager 與 registry；安裝前請自行查看源碼與 MIT 許可證，確認符合你的環境策略。
• Node：package.json 要求 node ^22.19.0 || >=24.0.0。

結尾¶

Plugin Shelf 把「已裝插件列表」收成一塊可排序、可分組、可篩可搜的書架，並把啓停與 npm 側的版本檢查、批量「移除再安裝」更新接到同一面板；適合插件數量較多、需要按場景分組或定期統一升級的 DSH 用戶。

• 社區目錄：https://www.skillhub.cn/plugins/QYF-888/dsh-plugin-shelf
• GitHub：https://github.com/QYF-888/dsh-plugin-shelf