前言¶

DeepSeek Harness (DSH) 採用插件化架構，允許在 Web composer 中擴展能力。在智能體開發中，排查故障往往依賴靜態代碼或模糊的日誌。dsh-debug-mode 旨在爲 Web 環境引入調試能力，通過提供多種運行模式和運行時埋點，幫助 agent 獲取可驗證的故障證據。

插件介紹¶

dsh-debug-mode 是 DeepSeek Harness 的 Debug Mode Bundle。

• 目標：在 Web composer 中提供 Normal、Plan、Debug 模式，並通過運行時埋點或後端調試器輔助故障排查。
• 維護者：svcgv
• 許可證：MIT
• 目錄：DeepSeek Harness 插件目錄
• 倉庫：GitHub

核心功能¶

該插件提供了一套完整的調試鏈路能力：

• 多模式支持：在 Web composer 中提供 Normal、Plan、Debug 模式切換，支持通過 Debug/Normal 開關控制。
• 命令與投影：支持 /debug 命令與視圖投影。
• 前端插樁：提供前端 Local Log 和 Listener 插樁功能。
• 後端調試：支持 Node/CDP 與 Python/DAP 後端，提供進程輔助與清理工具。
• 運行時工具：提供 debug_control 工具與 traceTransport 支持，以及 reproductionScope 支持（用於控制復現範圍）。

安裝與啓用¶

安裝過程通過 Harness 的 Web 啓動腳本完成。

1. 複製 config.example.ini 爲本地 config.ini。
2. 在 [deepseek] 節下填寫 api_key。
3. 運行 pnpm config:check 檢查配置（該腳本僅檢查 key 長度，不會打印 key）。
4. 設置 DSH_HARNESS_DIR（默認使用相鄰的 ../deepseek-harness 目錄），運行 pnpm harness:web。

執行 pnpm harness:web 會在 .dev/dsh-home 的臨時 profile 安裝當前打包的插件，並以 DEEPSEEK_API_KEY 啓動 Harness Web。

典型用法¶

在配置完成後，可以通過以下方式使用調試功能：

Trace Transport 配置
* 默認情況下，前端 debug_start 使用 traceTransport: 'listener'。探針通過插件服務採集事件並保存到當前運行的 .dsh-debug/<runId>/trace.jsonl 文件中，供 debug_control 讀取。
* 僅在需要只查看 console 或 terminal 時，才使用 traceTransport: 'local-log'。該模式不啓動服務且不生成日誌文件。

復現範圍
* debug_start 命令支持 reproductionScope 參數，取值爲 local、lan 或 auto。模型會根據用戶描述決定通告的端點範圍（例如 local 僅通告 127.0.0.1，lan 通告局域網地址）。

適用場景與注意¶

• 適用場景：適用於需要在 Web composer 環境中對智能體行爲進行調試的開發者，特別是涉及 Node.js 或 Python 後端聯調的場景。
• 注意：
  • 插件必須以 window.__ModuleLoader__.load({ id, factory }) 的工廠格式產出 Client bundle。
  • Flutter 未在真實工程中跑通。
  • 後端“停掉既有服務→調試→恢復”閉環未實現，當前對同腳本的普通服務採取安全失敗提示（不自動停服）。
  • Harness Web 完整端到端復現（埋點/斷點取證）尚未在瀏覽器會話內完全閉環。

結語¶

dsh-debug-mode 爲 DeepSeek Harness 的 Web 開發提供了模式切換與運行時調試能力。通過配置 traceTransport 和 reproductionScope，開發者可以更方便地定位問題。更多細節請參考 GitHub 倉庫。