前言¶
在 DSH 開發中，修改配置、主機代碼或前端資源後，通常需要重啓才能生效。這種“改了沒反應”或“必須重啓”的情況容易打斷開發思路，且排查原因往往需要人工介入。本文介紹 dsh-plugin-debugging 插件，它爲 DSH 智能體提供了運行時診斷與就地修復的能力，讓智能體可以自主檢查環境狀態並執行修復操作。
插件定位¶
dsh-plugin-debugging 是由 dsh-plugin-lab 維護的插件。它旨在解決 DSH 插件開發中的運行時調試問題，讓智能體能夠自檢自修其身處的運行時環境。
核心功能¶
安裝後，智能體獲得一組工具和技能文檔。這些工具分爲只讀診斷和狀態變更兩類：
- dsh_list_instances
列出當前機器上運行的 DSH 主機。僅探測本地端口。 - dsh_check_auth
區分服務“未運行”與“未認證”兩種狀態。 - dsh_diagnose_plugin_load
檢查插件是否成功加載，包括 bundle 成員、掛載形式和 loader 樹。 - dsh_check_effect_mode
探測當前運行 profile，判斷修改是立即生效、需要重啓還是需要熱重載。 - dsh_dump_config
顯示 profile 解析後的配置樹及診斷信息。 - dsh_sign_cookie
爲瀏覽器會話 cookie 簽名，使腳本或 CLI 客戶端能夠訪問 DSH 實例。 - dsh_hot_reload
將掛載的 entry 交換到磁盤上的最新代碼，失敗時自動回滾，無需重啓。 - dsh_restart
在真正需要時重啓主機。（注意：此功能默認關閉）。
安裝與啓用¶
插件支持通過 npm 或源碼安裝。
- 通過 npm 安裝
使用官方插件管理命令添加插件：
dsh plugin --profile web add dsh-plugin-debugging
- 從源碼安裝
如果需要修改或調試插件源碼：
git clone https://github.com/dsh-plugin-lab/dsh-plugin-debugging.git
cd dsh-plugin-debugging
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"
前置要求：
* Node.js 版本 >= 20
* DSH 版本需滿足 package.json 中定義的版本範圍
注意事項：
* 不要跳過 pnpm install，否則可能導致依賴缺失。
* 安裝後需要重啓 dsh --profile web 才能生效。
典型用法¶
安裝完成後，智能體可以通過斜槓命令調用技能。以下是常見操作場景：
- 檢查生效模式
在修改配置或代碼後，使用dsh_check_effect_mode檢測當前環境，決定是使用熱重載還是需要重啓。 - 熱重載代碼
使用dsh_hot_reload交換代碼，避免進程中斷。 - 強制重啓
當確認需要重啓時，使用dsh_restart（需確保功能已開啓）。
適用場景與安全邊界¶
該插件適用於需要頻繁調整配置、插件邏輯或前端資源的開發場景。使用時需注意以下幾點安全與行爲邊界：
- 權限限制：除
dsh_restart外，其他工具均不會重啓進程、重寫配置文件或向主機數據目錄寫入內容。唯一例外是插件自身的命名空間。 - 默認行爲：
dsh_restart功能默認是關閉的，使用前需確認配置。 - 認證狀態：
dsh_check_auth返回 401 並不總是意味着會話過期。無 cookie 的請求會被拒絕，需在瀏覽器中驗證服務狀態。 - 熱重載限制：
dsh_hot_reload可能導致資源泄漏（如未跟蹤的定時器或 socket）。
總結¶
dsh-plugin-debugging 通過提供運行時診斷與修復工具，降低了 DSH 插件開發的調試成本。它讓智能體具備了自我檢查和自我修復的能力，是提升開發效率的有效手段。
- GitHub 倉庫：https://github.com/dsh-plugin-lab/dsh-plugin-debugging
