前言¶

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 仓库。