前言¶
在 DeepSeek Harness 裏裝插件，常見路徑是「發現」裏訂閱索引、對話框裏填 github:owner/repo，或在命令行用 dsh plugin add。插件一多，來源分散、版本要對上 engines.dsh、啓停和更新各走各的入口，缺少一層統一視圖。PlugBox 面向所有支持自定義插件的引擎層與智能體層工具，在同一套界面裏瀏覽、安裝、更新、啓用或停用插件；宿主差異封裝在適配器裏，核心只處理「插件是什麼」。它目前以 DSH 組合包形式分發，並維護可被任意 DSH 實例訂閱的插件索引。
下面介紹它的定位、分層設計、在 DSH 上的安裝方式，以及面板裏能做什麼。
這是什麼¶
PlugBox（中文定位：插件適配與管理工具）由維護者 Wcof 發佈，倉庫爲 Wcof/PlugBox，許可證 MIT，npm 包名 plugbox。SkillHub 分類爲工作流。
它不做第二份插件數據庫：列表來自宿主真實的 pluginManager / pluginMarket 服務。同時對外發布精選索引 index.json 與從 dsh-plugin.org 覈實後同步的社區目錄 community.json——社區目錄是獨立生態的整理，與 DeepSeek / 幻方無官方從屬關係，不能當作官方應用商店。
在 DSH 側，組合包 patch 的 id 爲 plugbox，側欄模塊 id 爲 plugbox，宿主掛載前綴 /plugbox，RPC 端點 /plugbox/api/rpc。
核心架構：核心層與適配層¶
插件生態的差異在於各宿主如何描述清單、註冊 UI、命名 RPC、交付能力結構。PlugBox 因此分成兩層，避免在覈心代碼裏堆 if (宿主 === …)。
核心層（與引擎無關）¶
位於 src/core/，提供統一的插件協議、清單解析與生成、註冊與發現、生命週期，以及插件資源抽象。例如 protocol/plugin.ts 定義 CanonicalPlugin 等宿主無關類型；manifest/index.ts 負責 readManifest / toCanonical / writeManifest / toInstallSpec。兼容要求寫成帶命名空間的 requirements['<宿主id>/<要求名>']（DSH 上如 'dsh/dsh'），核心不認識具體宿主的原始字段名。
適配層（每個宿主一個適配器）¶
src/adapters/ 裏每個目標宿主實現 HostAdapter 契約：UI 掛載、來源標籤、索引格式、清單雙向轉換、資源映射、RPC 方法名、安裝參數等。新增宿主等於新增適配器並在 registry 登記，原則上不必改核心層。
當前支持矩陣（以 README 爲準）：
| 宿主 | 適配器 id | 是否實測 |
|---|---|---|
| DeepSeek Harness | dsh |
已實測（驗收環境 DSH 0.2.1-rc.5） |
| zcode 的 DeepSeek Harness | zcode-dsh |
未實測 |
表中沒有的宿主即尚未對接；DSM Harness 沒有對應適配器，不能推斷支持面。
核心功能¶
插件管理¶
頂部爲來源統計卡，點擊可篩選。卡片顯示標題、包名、來源、運行狀態與插件行數；「詳情」進入逐行啓停。
插件市場¶
按索引源分組展示條目，卡片標註來源、狀態（可安裝 / 已安裝 / 可更新 / 版本不符）與當前版本。工具欄支持搜索、來源篩選、創作者多選與多種排序。索引超過 100 條時按 nextOffset 續頁；超過加載上限會在列表上方提示「索引共 N 個，已加載 M 個」。
來源標籤三檔：宿主官方（DSH 下展示爲「DSH 官方」）、PlugBox 收錄（索引 metadata.keywords 含 plugbox）、第三方。「PlugBox 收錄」是倉庫維護者的整理，不代表宿主官方背書。
按分支安裝¶
點擊卡片左下角版本號，可查看倉庫分支列表：顯示分支名、包內版本、該宿主要求的兼容範圍等。未聲明對應宿主插件字段的分支（DSH 上爲 dsh.bundle）不可安裝；已裝版本會標「當前已裝」，換分支需先卸載。安裝的是分支當前頭提交，上游推送會改變所指提交；要固定版本需釘 commit 或等 tag 後正常安裝。
檢查更新¶
頁面打開時會靜默比對索引與已裝版本；可點「檢查更新」強制刷新索引緩存。
索引源¶
精選索引推薦訂閱：
https://raw.githubusercontent.com/Wcof/PlugBox/main/index.json
也可使用 jsDelivr 鏡像 https://cdn.jsdelivr.net/gh/Wcof/PlugBox@main/index.json。社區目錄：
https://raw.githubusercontent.com/Wcof/PlugBox/main/community.json
可在 DSH「發現 → Index sources」訂閱，或在 PlugBox 面板工具欄點「社區目錄」一鍵訂閱。社區條目較多，搜索比逐頁翻更高效；條目只表示倉庫確爲目標宿主插件包，行爲與兼容性仍由宿主按 engines.dsh 判定。
安裝與啓用¶
PlugBox 以 DSH 組合包分發（package.json 中 dsh.bundle.patch 指向 cordis.patch.yml）。任選一種方式安裝後，需重啓 DSH 窗口（Host 端代碼在啓動時加載）。
方式一：從索引源安裝（推薦）¶
- 打開 DeepSeek Harness「發現」，在 Index sources 中添加：
https://raw.githubusercontent.com/Wcof/PlugBox/main/index.json - 搜索
plugbox並安裝。 - 重啓 DSH 窗口。
方式二：從 GitHub 安裝¶
在「安裝插件」對話框填入 github:Wcof/PlugBox，或釘到某次提交：git+https://github.com/Wcof/PlugBox#<commit-sha>。
命令行示例（--profile 換成實際 profile，資料示例爲 web）：
dsh plugin --profile web add github:Wcof/PlugBox
方式三：本地目錄（開發）¶
在「安裝插件」中填寫本倉庫絕對路徑；從 git 安裝不會執行構建，改前端後需自行 npm run build 並提交 web/。
典型用法¶
安裝並重啓後，從側欄進入 PlugBox（掛載前綴 /plugbox）。
- 統一管理已裝插件：在插件管理頁按來源篩選，在詳情頁逐行啓用或停用。
- 從市場安裝：在插件市場選擇索引源，用搜索與排序找到條目，按卡片狀態安裝或更新；版本不符時對照分支列表或
engines.dsh。 - 訂閱社區目錄：添加上述
community.json地址，或在面板一鍵訂閱後搜索目標插件。 - 推薦收錄：在 GitHub 倉庫開 issue，附倉庫地址、目標版本與許可證；精選索引當前收錄約 10 個插件，覆蓋閱讀、學習、效率、界面增強、工具、模型等分類。
插件作者若寫兼容範圍，README 建議用 semver 區間（如 >=0.2.1-rc.2 <0.3.0-0），避免枚舉每個預發佈號；詳見倉庫 docs/article-engine-incompatible.md。
適用場景與注意¶
適合誰：經常在 DSH 裏裝多個插件、訂閱多個索引源，希望在一個界面裏看來源、啓停、更新與市場狀態的開發者。
權限與安全：PlugBox 與所管理的插件在當前 DSH 進程權限下運行。安裝前請自行查看源碼與 MIT 許可證，社區目錄條目僅做過倉庫級覈實，不代表行爲或兼容性已驗證。
邊界（README 已說明）：
- 兼容判定在宿主側：
engines.dsh存在時按 semver 判斷（含預發佈），規則由 DSH 適配器實現。 - 不提供插件配置界面；配置 schema 在模型側（如
Config.listConfigs）。 - 索引每個插件通常只登記一個已發佈版本；其他版本走分支安裝或等索引升版。
- zcode-dsh 適配器尚未在真實環境驗證，不要當作已支持能力宣傳。
結尾¶
PlugBox 用「核心協議 + 宿主適配器」把插件管理從單一引擎裏抽出來：在 DSH 上已實測可用，併發布精選索引與社區目錄供訂閱。若你需要統一瀏覽、安裝與更新插件，而不是隻在各處重複搜索引，可以按上文索引源或 GitHub 方式安裝。
- SkillHub 目錄頁：https://www.skillhub.cn/plugins/Wcof/PlugBox
- GitHub：https://github.com/Wcof/PlugBox
- 項目介紹頁：https://wcof.github.io/PlugBox/
