前言¶

DeepSeek Harness（DSH）採用“一切皆插件”的架構。對於仍依賴舊版 Claude Code 或 Codex 生態的插件，直接集成往往存在兼容性問題。@rvaim/dsh-compat 提供了一個兼容層，將這些舊插件作爲完整的生命週期單元接入 DSH，使其能像管理原生插件一樣被整體管理、運行和更新。

核心功能¶

Source 與 Plugin 分離管理¶

插件區分兩個概念：Source 負責獲取和緩存內容（Git 倉庫、本地目錄或壓縮包），Plugin 負責運行時行爲。一個 Source 可包含一個或多個 Plugin。

支持的來源與格式¶

支持 Git URL、github: 簡寫、本地目錄以及 ZIP/TAR/TGZ 歸檔。
支持 Claude Code、Codex Marketplace 及混合 Marketplace。無 Marketplace 時識別根目錄中的單插件。

生命週期操作¶

支持一次原子安裝一個或多個 Plugin。提供整體啓用、禁用、更新、檢查和卸載功能。安裝失敗時不會提交變更。

能力適配¶

支持 Skill、MCP（stdio 與 streamable-http 接入）、Hook（包含參數邊界、事件映射、超時控制）、Command、Agent 等能力的發現與適配。

安裝¶

通過 npm 安裝到指定 profile：

dsh plugin --profile web add @rvaim/dsh-compat@latest

首次安裝或升級後，需要重啓 profile 並重新加載 Web 頁面，因爲 DSH 的 Host/Client 插件圖發生了變化。

使用¶

Web 界面管理¶

啓動 profile 後，在 DSH Web 設置中打開“兼容插件”。點擊“添加”輸入來源（Git URL、本地路徑或歸檔）。單插件來源直接安裝，多插件來源顯示覆選列表，確認後從同一快照安裝。

使用開關在線啓用或停用插件，使用刷新按鈕檢查更新。卸載操作會移除插件。

API 調用¶

其他插件可以聲明 inject: ['compat']，然後通過 ctx.compat 調用服務 API 執行操作，例如：
- ctx.compat.sourceAdd(source, options?)
- ctx.compat.sourceRemove(sourceId)
- ctx.compat.sourceUpdate(sourceId, options?)
- ctx.compat.sourceList()
- ctx.compat.sourceInspect(sourceId)
- ctx.compat.prepareInstall(source, options?)
- ctx.compat.install(sourceOrSourceId, options?)
- ctx.compat.checkUpdates()
- ctx.compat.update(pluginId, options?)
- ctx.compat.enable(pluginId)
- ctx.compat.disable(pluginId)
- ctx.compat.uninstall(pluginId)
- ctx.compat.list()
- ctx.compat.inspect(pluginId)

架構與數據¶

轉換流程¶

來源解析器將 Git/歸檔解析爲 Source，Plugin 解析器將 Source 中的內容解析爲具體的 Skill/MCP/Hook，最後由 CompatPlugin 適配到 DSH 的運行時。

存儲佈局¶

數據存儲在 $DSH_HOME/dsh-compat/ 下，分爲 sources（緩存源內容）和 installed（管理插件狀態）。

安全模型¶

安裝階段不執行構建腳本，Git 不創建工作樹，僅進行讀取和解析。歸檔檢查路徑穿越、符號鏈接等風險。敏感配置使用引用而非明文寫入。

適用場景與注意¶

適合需要統一管理舊版 Claude Code/Codex 插件的工作流開發者。使用時需注意：插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。不執行構建腳本和 Command/Agent。

總結¶

@rvaim/dsh-compat 通過分離 Source 與 Plugin 模型，爲舊版插件提供了標準化的接入方式，並提供了完整的生命週期管理。