dsh-hotswap：DeepSeek Harness 運行時插件熱插拔管理器

前言¶

DeepSeek Harness (DSH) 的設計理念是「一切皆插件」。在實際開發或調試過程中，如果需要啓用/停用某個插件，或者掛載/卸載一個新的 bundle，通常需要重啓 dsh web 進程，這會打斷當前的工作流。

dsh-hotswap 是一個 Web 插件熱插拔管理器，由 HongzhongL 維護。它解決了這個問題，允許你在不重啓 dsh web 的情況下，運行時啓用、停用或重啓 Cordis 插件，並自動同步 profile 中的 bundle 配置。

核心功能¶

1. 運行時熱啓停¶

插件通過調用 Loader 的 entry.update({ disabled: true/false }) 接口實現熱插拔。
* 熱停用：調用該接口後，插件當場卸載，服務、工具、監聽器等資源會被立即回收。
* 熱啓用：調用該接口後，插件會當場重新導入並啓動，包括那些啓動時處於停用狀態的插件。

2. 熱重啓與 Bundle 同步¶

熱重啓：插件支持卸載後重新加載，並盡力清除 Node ESM 模塊緩存以嘗試加載磁盤上的新代碼（此過程爲 best-effort）。
Bundle 自動同步（熱掛載）：插件會監視 profile 的 package.json 中的 dsh.profile.bundles 配置。當配置條目發生增刪時，它會通過 Include 根分組自動執行熱掛載或卸載，無需手動重啓。

3. 持久化與配置管理¶

持久化：每次開關插件的狀態，插件都會將 disabled: true 寫入 profile 的 cordis.patch.yml 文件中，並維護一個名爲 # === dsh-hotswap managed block === 的自動區塊。這樣重啓 dsh web 後，開關狀態依然生效。
外部停用識別：插件能識別 cordis.patch.yml 中手寫的 disabled: true 行。當你在界面上啓用插件時，它會同步移除該配置行，避免狀態不一致。

4. 安全護欄¶

爲了防止誤操作導致系統崩潰，插件內置了安全機制：
* 保護名單：webserver、connection、api-gateway、modules、typert*、web*、hmr 等關鍵條目以及插件自身本身不能被停用。
* 表達式控制：受 !!js 表達式控制的條目或父分組被停用的條目，不允許切換狀態。
* 一鍵恢復：提供「全部恢復」功能，重新啓用所有由管理器停用的插件。

安裝與配置¶

安裝¶

通過 DSH 的 CLI 工具安裝該插件：

dsh plugin --profile web add dsh-hotswap
# 安裝完成後，需要重啓 dsh web 才能生效
dsh web

配置（可選）¶

插件支持通過 profile 的 cordis.patch.yml 進行覆蓋配置：

- id: dsh-hotswap
  config:
    profile: web              # 持久化目標 profile（默認從 Loader baseUrl 推導）
    protected: [some-id]      # 追加不可停用的條目 id

使用方式¶

界面操作¶

安裝完成後，在 DSH Web 的 設置 → 插件 → 「插件管理」 標籤頁中，可以看到當前掛載的所有 Cordis 插件列表。列表支持搜索和篩選，並顯示每個插件的狀態燈和徽章。

每個插件條目右側提供了開關和重啓按鈕，點擊即可執行熱啓停或熱重啓操作。

配置文件修改¶

在 profile 的 package.json 中修改 dsh.profile.bundles 配置，保存後，dsh-hotswap 會自動檢測變化並執行對應 bundle 的熱掛載或卸載。

恢復關鍵插件¶

如果誤停了關鍵插件導致界面無法操作，可以編輯 UI 上顯示的持久化文件（cordis.patch.yml），手動刪除 dsh-hotswap 的自動區塊，然後重啓 dsh web 即可恢復。

注意事項與限制¶

安全風險¶

本插件暴露了同源的 HTTP 端點（/_dsh/hotswap/*），且不額外加鑑權。
* 僅本地安全：只要 Web 服務綁定在 127.0.0.1，就只有本機進程能調用，相對安全。
* 局域網風險：如果 webserver 的 host 設爲 0.0.0.0 暴露到局域網，局域網內任何設備都能控制你的插件（進而驅動 agent）。切勿暴露到不可信網絡。
* 來源校驗：來源校驗（isSameOrigin）只攔截帶 Origin 頭的跨站請求；無 Origin 頭的本機程序（如 curl）會被放行。這意味着不要與不信任的進程共享這臺機器。

兼容性¶

本插件開發/測試於 DSH 0.1.0-rc.6。
熱重啓與代碼重載依賴 Cordis Loader 的內部 API（entry._dispose / entry.refresh / loader.internal），這些不是公開契約。升級 DSH 後，這些 API 可能發生變化，升級前需確認兼容性。

已知限制¶

客戶端 UI 延遲：停用某個插件後，已經打開的頁面裏它注入的客戶端 UI（如設置頁標籤）需要刷新頁面後纔會消失。
ESM 緩存：熱重啓的「代碼重載」是 best-effort，Node ESM 模塊緩存無法被可靠失效，多數情況下只是卸載後重新 apply，未必能讀取到磁盤上的新代碼。
Headless 模式：headless profile 沒有 webServer，本插件只服務於 Web 界面，無法在 Headless 模式下工作。
持久化範圍：運行時啓停隻影響當前進程；持久化只覆蓋本管理器經手的開關。手動寫在圍欄外的配置行不會被改動（除非點擊「啓用」時順手移除）。