前言¶
在 DeepSeek Harness（DSH）裏裝插件，常見流程是改 profile、等 plugin-manager 落盤，然後重啓進程才確認「真的跑起來了」。官方在在線 profile 且 hmr 已組合時，對全新 bundle 安裝已經能進程內生效；但重裝同名依賴、首次 import 失敗後再改文件、或改動了 node_modules 裏同路徑的插件代碼，仍經常變成「下次啓動才生效」。若你頻繁試裝插件、本地 link: 開發，或依賴 Web 插件頁操作，這類空窗會反覆出現。
下面介紹社區維護的 Host 側插件 dsh_plugin_refresh（維護者 lixiaohao001，分類：客戶端）：它監視已安裝組合，在運行中的進程裏完成激活與深度重載，且不寫入 profile manifest 或 patch 層。插件目錄頁見 SkillHub，源碼與文檔在 GitHub（MIT，當前 package 版本 0.1.0）。
這是什麼¶
dsh_plugin_refresh 是 DSH 的 Host 插件：安裝後默認自動檢查已選中的 bundle，對「已選中但未掛載」的行走與 Web 插件頁相同的官方路徑重新驅動，並對路徑未變但文件已變的插件模塊做就地 deep reload。它不執行 npm 安裝/卸載，也不改你的 profile 文件內容。
它補齊的三類缺口¶
README 用表格歸納了沒有本插件時的典型表現，核心如下。
| 情況 | 沒有本插件時 |
|---|---|
| 依賴名在 profile 中已存在（重裝、升級、本地 re-link） | installBundle 可能在重載前返回 application: "restart-required"，選擇已保存但未掛載 |
| 插件第一次 import 失敗 | Node 緩存失敗的 module job，修文件後同 URL 仍報錯，直到重啓 |
| 插件文件在同一路徑下被改動（重建 bundle、本地開發） | 包在 node_modules 下，官方熱重載按設計忽略該目錄，進程仍跑舊代碼 |
核心能力¶
一次串行化的 pass，在啓動延遲後、每次 plugin-manager 操作後、以及監視路徑變化時觸發（事件驅動，輔以指紋輪詢）。
-
深度重載（deep reload）
對模塊文件在路徑不變前提下已變更的在線插件，按@deepseek-ai/dsh-hmr同類步驟清理 ESMloadCache（Node 24 需用Map.prototype.delete）與 CJSrequire.cache、重新 import、替換 registry 中的舊代並在原 fiber 上重新激活，儘量保留 LoaderEntry與 config。 -
自動修復（repair）
對已選中但沒有運行行的 bundle：丟棄被污染的 module job，先 import 一次以捕獲真實異常，再通過pluginManager.setBundleEnabled()重走官方組合路徑。若裸 specifier 無法解析（常見於 profile 外的link:安裝），則改用已解析的文件 URL 激活。 -
狀態上報
輸出每個 bundle 的健康表（選中、運行行、錯誤）與有界 pass 歷史，寫入日誌，並可通過 HTTP 查詢；修復詳情中的repairs[].probe.error往往比 plugin-manager 的failed to import更具體。
與社區裏其他「免重啓」方案相比，README 明確本包側重：自動、無第三方依賴（僅 node: 內置模塊）、修復首次 import 失敗、支持本地 link:；不提供瀏覽器 UI，也不代替 plugin-manager 做包操作，且會觸及 Node loader 內部實現，對 DSH / Node 版本較敏感。
安裝與啓用¶
從 GitHub 安裝（README 原文命令，無需 npm 發佈）：
dsh plugin --profile desktop add github:lixiaohao001/dsh_plugin_refresh
本地開發時可將倉庫路徑作爲 bundle 安裝（編輯即運行，無構建步驟）：
dsh plugin --profile desktop add /absolute/path/to/dsh_plugin_refresh
在 Agent 會話中，也可通過 plugin_manager 工具的 install_bundle，傳入同樣的絕對路徑。包聲明 dsh.bundle.patch，會作爲 profile bundle 插入一行 id: plugin-refresh、name: dsh_plugin_refresh。
環境要求（來自 package.json 與 README）
- Node：
^22.19.0 || >=24.0.0 - DSH peer：
@deepseek-ai/dsh >=0.2.0-rc.2 <0.3.0-0（README 徽章標註在0.2.0-rc.2的desktopprofile 上驗證） hmr、pluginManager、webServer等均爲可選依賴；缺少時插件會加載並報告無法完成的項
配置¶
在 profile 的 patch 裏爲 plugin-refresh 行覆蓋 config。常用字段默認值均爲面向「裝完即檢、即修、即重載」：
| 字段 | 默認 | 含義 |
|---|---|---|
autoCheck |
true |
啓動後與每次 plugin-manager 操作後檢查 |
autoRepair |
true |
對剛安裝/啓用但未運行行的 bundle 重驅動 |
deepReload |
true |
對同路徑下文件已變的模塊做深度重載 |
watchProfile |
true |
監視 profile patch 與 manifest |
devWatch |
[] |
額外監視的絕對路徑（開發用） |
devReload |
true |
devWatch 變化時 deep reload |
pollIntervalMs |
2000 |
指紋輪詢間隔，0 關閉 |
debounceMs |
400 |
合併短時間內的多次變更 |
startupDelayMs |
1200 |
應用就緒後首次檢查的延遲 |
route |
/api/plugin-refresh |
HTTP 前綴；空字符串關閉接口 |
verbose |
false |
是否記錄「無事可做」的 pass |
開發時監視自有插件目錄的示例：
- id: plugin-refresh
config:
devWatch:
- /absolute/path/to/my-plugin/lib
典型用法¶
日常：安裝其他插件後等待自動 pass¶
保持默認 autoCheck / autoRepair / deepReload 即可。安裝或啓用 bundle 後，無需手動重啓 DSH；若仍異常，再查狀態接口（見下）。
手動觸發檢查或重載¶
HTTP 僅綁定迴環地址，與 DSH Web server 一致；POST 需同源請求（瀏覽器）或不帶 Origin 的客戶端。
| 方法 | 路徑 | 作用 |
|---|---|---|
| GET | /api/plugin-refresh/status |
配置、最近 pass、bundle 健康、歷史 |
| GET | /api/plugin-refresh/status?detail=1 |
附加各 entry 模塊快照 |
| POST | /api/plugin-refresh/check |
立即執行一次 pass |
| POST | /api/plugin-refresh/repair?bundle=<名字> |
修復指定 bundle；省略參數則處理全部不健康 bundle |
| POST | /api/plugin-refresh/reload?path=<絕對路徑> |
對擁有該路徑的插件 deep reload |
改完插件源碼後，可 POST reload（README 示例端口爲 19387，以你本機 Web 端口爲準）：
Invoke-WebRequest -Uri 'http://127.0.0.1:19387/api/plugin-refresh/reload?path=<my-plugin>/lib' -Method POST
成功就地替換自身或其它插件時，/status 中的 generation 會變化，便於確認熱重載是否發生。
排錯時讀 status¶
- pass 級
error：檢查流程本身失敗 repairs[].probe.error：真實 import 原因repairs[].purgedModules > 0：已清除失敗 module jobrepairs[].rebound：通過解析後的 file URL 啓動health[].needsRepair === true：已選中但無運行行
適用場景與注意¶
適合：經常在同一 DSH 進程裏安裝/升級插件、用本地 link: 聯調 Host 插件、或需要改 node_modules 內同路徑 bundle 後立即驗證的行爲。
務必知曉：
- 插件以當前 DSH 進程的權限運行；安裝前請閱讀源碼與 MIT 許可證，僅從可信來源安裝。
- 若替換導致解析到的包目錄變化（例如
node_modules下換了一個版本目錄），仍可能需要重啓；同路徑文件內容變更才由 deep reload 覆蓋。 - Host 側激活後，瀏覽器模塊仍依賴
dsh-client-modules/dsh-client-hmr；客戶端未更新時，頁面可能需要手動刷新。 - 狀態路由無額外鑑權（僅 loopback），會暴露插件名與路徑；敏感環境可將
route設爲""關閉。 - 每個 bundle 的 repair 約 15 秒內限一次，避免與 plugin-manager 事件形成環路。
DSH 生態強調「一切皆插件」；SkillHub 等社區目錄獨立於 DeepSeek / 幻方，並非官方應用商店。
結尾¶
dsh_plugin_refresh 把「裝完插件還要重啓」縮成默認自動的檢查、修復與深度重載流程，並補上了首次 import 失敗與 link: 本地安裝等邊角。若你在 desktop profile 上迭代插件，可先按上文命令安裝，再用 /api/plugin-refresh/status 覈對 bundle 健康。
- 目錄頁：https://www.skillhub.cn/plugins/lixiaohao001/dsh_plugin_refresh
- 倉庫：https://github.com/lixiaohao001/dsh_plugin_refresh
