DeepSeek Harness 插件：本地插件開關 (`dsh-local-plugin-switch`)

前言¶

DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。在本地開發環境中，通過配置文件管理插件的狀態（disabled 字段）是標準做法，但這通常需要手動編輯 YAML 文件並重啓實例。對於頻繁調試或需要快速啓停某些 Loader 條目（fiber）的開發者來說，缺乏可視化的控制手段會增加操作成本。

dsh-local-plugin-switch 是一個用於在 DSH 設置頁增加「本地插件開關」分區的插件。它列出了當前 profile 中已安裝的非分組插件，允許用戶通過點擊開關實時啓停對應的 fiber，並將狀態持久化寫入配置文件。

核心能力¶

實時開關與持久化¶

插件宿主通過調用 entry.update({ disabled: true | null }, false, true) 立即停止或啓動目標條目的 fiber，無需重啓 DSH 實例。同時，它會將操作結果以 - id: <rowId>\n disabled: true|false 的形式追加到當前 profile 的 cordis.patch.yml 文件中。重啓實例後，插件會讀取該文件並保持關閉狀態。

自包含補丁編輯器¶

插件不依賴外部市場（dsh-market），在 lib/index.js 中內置了一個最小化的 YAML 讀寫邏輯。它採用啓發式匹配來處理行級補丁寫入（例如識別 - id: X 後緊跟兩空格縮進的 disabled 字段），支持追加新行和刪除舊行。

標記與篩選¶

原生/宿主識別：模塊名以 @deepseek-ai/ 或 cordis: 開頭的條目會顯示「原生」標籤；命中受保護清單的條目顯示「宿主」，且不可關閉（受保護清單硬編碼在 lib/index.js 中，防止誤關基礎設施導致頁面失效）。
分組過濾：插件列表僅包含 entry.options.group 爲 false 的非分組條目。
收藏置頂：支持在行首添加 ☆ 或 ★ 進行收藏，狀態保存在瀏覽器的 localStorage 中，刷新後收藏項會排在最前。

零依賴架構¶

宿主側僅使用 Node.js 內置模塊（node:fs, node:path, node:os, node:url），不引入 YAML 解析庫，降低了依賴複雜度。

接口與插槽¶

宿主路由¶

插件在宿主註冊了兩條精確路由（kind: 'exact'），掛載在 ctx.effect 上隨 fiber 釋放：

路由	方法	說明
`/dsh-local-plugin-switch/list`	GET / HEAD	返回所有非分組條目列表（包含 `entryId`, `moduleName`, `enabled`, `fiberPhase`, `protected`）。
`/dsh-local-plugin-switch/toggle`	POST	接收 `{name, enabled}` 請求體。請求體上限 4096 字節。支持同源校驗，任意工具可直接 POST。

設置頁插槽¶

客戶端通過註冊 settings.section 插槽（id: local-plugin-switch）在設置頁面生成分區。該分區包含條目列表、開關控件以及基於 fiberPhase 的狀態着色（0 pending / 1 loading / 2 active / 3 failed / 4 null / 5 unloading）。

部署與啓用¶

本插件目前沒有標準安裝命令，需按以下步驟手動掛載：

拷貝文件：將插件目錄拷貝到 profile 的 node_modules 下。

    Copy-Item -Recurse -Force .\dsh-local-plugin-switch $env:DSH_HOME\profiles\web\node_modules\

掛載插件：在 profile 的 cordis.patch.yml 末尾追加本包自帶的掛載行（即包內 cordis.patch.yml 的內容）：

    - insert:
        - id: dsh-local-plugin-switch
          name: dsh-local-plugin-switch

重啓與刷新：重啓 DSH web 實例，並在瀏覽器執行硬刷新（Ctrl+F5）。

典型用法¶

部署完成後，在 DSH 設置頁會出現「本地插件開關」分區。用戶可以：
* 查看當前所有本地插件及其狀態。
* 點擊開關實時停用插件（宿主側服務立即下線）。
* 刷新頁面後，再次打開設置頁，之前關閉的插件狀態保持關閉。

對於標記了客戶端半（dsh.client）的插件，關閉後頁面通常會提示「已切換，刷新頁面生效」。

限制與注意事項¶

補丁解析限制：補丁寫回邏輯是啓發式的，並非完整的 YAML 解析器。它只識別特定格式的行，行 ID 需匹配正則 /^[A-Za-z0-9_.-]+$/，否則寫入會失敗。
安全邊界：toggle 路由僅做同源校驗，這意味着本機任意工具都可以直接向該接口發送 POST 請求來開關插件。
代碼不一致：客戶端代碼中聲明瞭 @deepseek-ai/dsh-client-ui-primitives 等依賴，但實際實現中並未使用這些模塊（均爲手寫 UI），這屬於聲明與實現的不一致，不影響運行。

總結¶

dsh-local-plugin-switch 爲 DSH 本地開發提供了一個輕量級的插件管理入口。它通過原生插槽和 HTTP 路由，在無需引入重型依賴的情況下，實現了可視化的開關控制和配置持久化。適合需要在本地環境中頻繁調試或管理 Loader 狀態的開發者。

項目主頁: GitHub
目錄頁: SkillHub