前言¶

DSH 的理念是「一切皆插件」，功能擴展基本都落在裝插件上。但安裝插件這件事本身還是手工活：手動跑安裝命令、改配置、重啓進程。重啓之後當前對話就斷了，模型要麼從頭再來，要麼你手動把上下文貼回去。更麻煩的是，如果新裝的插件破壞了啓動，dsh 直接起不來，刪依賴、還原配置全靠自己排查。

dsh-plugin-installer 把「備份 → 安裝/卸載 → 重啓 → 自動繼續對話」整條鏈路封裝成模型工具，交給模型來執行，失敗或啓動異常時自動回滾。下面介紹它的功能、用法和注意事項。

這是什麼¶

dsh-plugin-installer 是 Quophic 維護的 DSH 插件（當前版本 0.4.1，MIT 許可證），提供 install_plugin、uninstall_plugin、restart_dsh 三個模型工具，覆蓋插件的安裝、卸載和重啓。它自身是 host 半區插件，不需要瀏覽器 UI。engines 要求 Node ^22.19.0 || >=24.0.0。

三個模型工具¶

install_plugin¶

安裝持久化插件（bundle）到指定 profile，流程是固定的：

1、備份：安裝前自動把 profile 的 package.json、cordis.patch.yml、cordis.yml、settings.yaml 備份到 $DSH_HOME/backups/plugin-install-<時間戳>/，含 manifest 清單。
2、安裝：調用官方 dsh plugin --profile <名> add <包>，與 pnpm add 加 bundles reconcile 是同一路徑。
3、成功：記錄當前運行中的會話 → 自動重啓 dsh → 重啓完成後向會話注入「繼續」提示詞，對話無縫接續。
4、安裝命令失敗：自動回滾備份 → 重啓 dsh → 把問題寫入會話，讓 agent 分析並解決。
5、重啓後 dsh 起不來：由一個獨立的 detached helper 探測端口，起不來則自動回滾備份並再次重啓，隨後把回滾結果寫入會話。

uninstall_plugin¶

卸載已安裝的插件，保護與安裝對等：先備份，再調用官方 dsh plugin --profile <名> remove <包>，成功後重啓並續接對話。區別在於回滾動作——卸載命令失敗、卸載後啓動失敗或工具健康異常時，回滾備份之外還會重新安裝該插件，把包裝回去，還原卸載前的狀態（比如卸掉了被其他配置引用的包）。

restart_dsh¶

只重啓 dsh，不安裝、卸載、修改任何插件或配置。記錄當前會話 → 以隱藏控制檯方式重啓（無窗口閃出）→ 重啓後自動恢復對話。適合讓新加載的插件或最新配置生效、恢復正常進程狀態。注意它沒有安裝流程那套備份、回滾和工具健康驗證保護。

工具健康驗證：端口能起來不等於一切正常¶

這是這個插件比較關鍵的一層保護。有一類損壞寫法——比如工具的 parameters: {} 空對象、或把原始屬性映射直接傳給 ctx.tools.register（不經 defineTool 編譯）——註冊時不會報錯，但 dsh 把工具投影給 LLM 時 API 會拒絕，表現爲每次對話都報 Invalid schema for function 'X'，完全沒法聊。

所以端口起來後並不算完：新進程裏的本插件會審計所有已註冊工具的參數 schema（要求頂層 type: 'object'）。審計發現這類損壞，同樣自動回滾備份並再次重啓，並把問題詳情寫入會話。

更新插件與自更新¶

install_plugin 對任何已安裝的包（不限於本插件自己）都會自動「先卸後裝」強制刷新。之所以要先 remove 再 add，是因爲 pnpm 對 file: 依賴在版本號不變時會複用陳舊副本，直接 add 不會刷新。日常更新開發中的本地插件：

{
  "package": "file:E:/GitHub/dsh-plugins/xxx",
  "profile": "web",
  "restart": true
}

版本號沒變也沒關係，會從最新源碼重新安裝。更新本插件自己（self-upgrade）同理：

{
  "package": "file:E:/GitHub/dsh-portal/dsh-plugin-installer",
  "profile": "web",
  "restart": true
}

兩個注意事項：

• file: 路徑要用正斜槓（file:E:/...），反斜槓會被 shell 當轉義喫掉，導致找不到包。file: 源自帶版本號，version 參數只對 npm 包名生效。
• 本地源碼更新的完整流程：改 src/ → npm run build → 調用工具 → 重啓後新邏輯生效。

更新操作同樣受單次提權審批（非 danger-full-access 會話會請求主人批准）與 allowProfiles 白名單約束。

權限控制¶

安裝、卸載、重啓都是敏感動作，插件內置了兩層約束：

• 提示詞層：插件注入一段 systemPrompt section，明確告訴模型「安裝/升級持久化插件必須調用 install_plugin、卸載必須調用 uninstall_plugin，不要直接跑 pnpm/dsh 命令」。
• 審批層：默認開啓單次提權審批。若調用會話不是 danger-full-access 沙箱模式，工具不硬拒，而是通過 approval seam（ctx.approval.request）向主人發起單次提權審批——批准（allowed-once）後本次調用放行；拒絕、取消或審批通道不可用則 fail closed。這與沙箱 bash 工具的 sandbox_permissions 升權是同一套機制。

配置寫在 profile 的 cordis.patch.yml 本插件行上：

requireApproval: false   # 關閉審批（任何模式都可直接調用）
allowAuto: true          # 完全放行 LLM 自動調用（跳過審批）
allowProfiles: ['web']   # 只允許安裝/卸載到這些 profile；空數組 = 不限

即使放行，execute 內仍有 allowProfiles 白名單二次校驗。

重啓與回滾的實現¶

瞭解機制有助於排查問題：

• 重啓採用 Node 原生方式：spawn 一個 detached helper，等待舊進程退出並釋放端口後，以相同 argv/cwd 重新拉起 dsh，輸出追加到 %TEMP%/dsh-install-*.log。
• helper 輪詢 web 端口（DSH_WEB_URL 或默認 3080），120 秒內起不來判定爲啓動失敗，自動回滾備份文件並再拉起一次。
• 工具健康驗證協議：端口起來後 helper 繼續等待 $DSH_HOME/dsh-install-verify.json（最多 60 秒）。新進程裏的本插件通過 ctx.tools.schemas() 枚舉全部已註冊工具逐個校驗；tools/change 事件會觸發防抖複查加最多 6 次重試，覆蓋加載晚的插件。結論寫入 verify 文件，ok: false 則回滾後再拉起。
• 自動繼續對話：重啓前把運行中的會話 id 寫入 $DSH_HOME/dsh-install-resume.json，重啓後對恢復的會話注入 followup（安裝成功是繼續提示，回滾則是問題詳情加解決指引）。
• 所有操作寫入 $DSH_HOME/dsh-install.log，便於排查。

安裝與啓用¶

README 給出的安裝命令是本地 file: 源的形式：

dsh plugin --profile web add file:E:/GitHub/dsh-portal/dsh-plugin-installer

裝完重啓一次 dsh，bundle 補丁層在啓動時加載，之後三個模型工具即可使用。

典型用法¶

三個工具的參數都比較短。安裝：

{
  "package": "dsh-xxx",
  "profile": "web",
  "version": "0.1.0",
  "restart": true,
  "delayMs": 2000
}

package 支持 npm 包名、file: 路徑、git URL；profile 默認 web；version 是可選版本號；restart 默認 true；delayMs 是重啓前等待（結果回傳時間），默認 2000。

卸載：

{
  "package": "dsh-xxx",
  "profile": "web",
  "restart": true,
  "delayMs": 2000
}

直接重啓：

{
  "profile": "web",
  "delayMs": 2000
}

restart_dsh 的 profile 僅作記錄，重啓不針對單個 profile。需要伴隨安裝/更新（含備份回滾保護）時，用 install_plugin 並把 restart 留默認 true；只是讓改動生效時用 restart_dsh。

適用場景與注意¶

適合經常折騰 DSH 插件的人：維護自己的插件需要反覆刷新本地 file: 源，或者希望把裝插件的備份、回滾、續聊流程交給模型託管。

幾點使用上的注意：

• restart: false 時不會重啓，也就無法做工具健康驗證（響應裏會註明），新插件要等下次重啓才生效。
• 回滾時會恢復 settings.yaml 等插件配置類文件，安裝失敗不會留下半修改的配置。
• 備份目錄會累積在 $DSH_HOME/backups/ 下，可定期清理。
• 插件以當前 dsh 進程的權限運行，能改動你的 profile 配置和已裝插件。安裝或更新任何插件前，應先檢查其源碼與許可證（本插件爲 MIT）。
• 引擎要求 Node ^22.19.0 || >=24.0.0。

結尾¶

經過上面的步驟，裝插件從手工操作變成一次帶備份、回滾和續聊的工具調用，裝壞了 dsh 也能自己恢復回來。插件目錄頁見 https://www.skillhub.cn/plugins/Quophic/dsh-plugin-installer ，源碼見 https://github.com/Quophic/dsh-plugin-installer 。