DeepSeek Harness 插件診斷工具：dsh-composition-doctor

前言¶

DSH 採用“一切皆插件”的架構。在開發或維護 DSH 實例時，安裝或升級插件後遇到啓動失敗是常見問題。當 Web UI 無法打開時，定位根因（例如重複加載器 ID、缺失補丁或配置衝突）通常比較困難。

dsh-composition-doctor 旨在解決這個問題。它將已知的失敗模式鏈接到 Bundle、Patch 或 Profile 層，告訴你下一步應該檢查哪個來源，而無需啓動 DSH 實例。

是什麼¶

dsh-composition-doctor 是一個由 lemonxiny55 維護的客戶端診斷工具。它通過分析靜態元數據來解釋 DSH 插件故障，包括重複插入、缺失補丁、對等依賴不匹配等。目前版本爲 0.4.0。

安裝¶

使用 npm 安裝全局 CLI（注意忽略構建腳本）：

npm install -g dsh-composition-doctor@0.4.0 --ignore-scripts

安裝後，驗證版本：

dsh-doctor --version

前置條件：運行環境需滿足 Node.js >= 20。

核心功能¶

1. 只讀與離線：默認離線診斷，不自動修復配置，不訪問網絡，不啓動 DSH 進程。
2. 故障檢測：能夠檢測以下問題：
   • 重複加載器 ID。
   • 捆綁包不可用。
   • 缺失或無效的捆綁包補丁。
   • 目標聲明缺失。
   • 對等版本/依賴不匹配。
   • 配置替換或覆蓋。
3. 輸出支持：支持管道傳輸和結構化輸出（如 JSON 或 Markdown）。
4. Web 探索器：提供可選的 Web 界面查看報告。

使用示例¶

基礎檢查¶

檢查指定配置文件的靜態元數據：

dsh-doctor check --profile "$HOME/.dsh/profiles/web"

診斷日誌¶

結合錯誤日誌進行診斷：

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --log ./minimal-error.log

結構化輸出¶

輸出 JSON 格式的結構化結果：

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --format json

查看來源與影響¶

查看特定行（row）的來源鏈，或查看特定 Bundle 的影響範圍：

dsh-doctor why row tool-bash --profile C:\path\to\profile
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile

工作原理與注意¶

• 靜態分析：check 和 diagnose 命令僅檢查靜態元數據，不會導入插件代碼、運行生命週期腳本或訪問網絡。
• 健康狀態誤判：如果輸出結果爲 unknown、no-match 或退出代碼爲 0，並不代表配置是健康的。這可能意味着插件無法檢測到已知的失敗模式。
• 無自動修復：該工具僅提供診斷信息，不會自動修改你的 Profile 配置。

總結¶

dsh-composition-doctor 是一個用於排查 DSH 插件故障的實用 CLI 工具。它通過分析靜態元數據，幫助你在 DSH 無法啓動時快速定位問題根源。

• GitHub 倉庫: lemonxiny55/dsh-composition-doctor
• 插件目錄: dsh-composition-doctor