dsh-debug-mode：DeepSeek Harness 的运行时调试证据插件

在 DeepSeek Harness (DSH) 的调试流程中，通常需要人工在浏览器控制台和服务器日志之间切换，试图定位故障。现有的日志往往包含大量噪音，难以过滤出相关的执行分支。此外，让智能体从静态快照推断问题，通常会导致猜测而非验证。DSH 的 Debug Mode 插件通过在运行时注入探针并捕获结构化 JSONL 事件来解决这个问题，使智能体能够证明失败分支、执行针对性修复并清理诊断。

这是什么¶

dsh-debug-mode 是一个用于 DeepSeek Harness 的插件，旨在提供 AI 调试的运行时证据。它由 a554878526 维护，旨在通过结构化数据捕获替代手动日志收集，使调试循环更加高效。

核心功能¶

结构化 JSONL 事件捕获：将证据作为 JSONL 流记录，便于流式处理和 grep。
统一证据：捕获来自浏览器、Electron 和 Node.js 环境的事件，无需手动合并日志。
假设聚焦的探针：录制 1-3 个与特定假设相关的探针，而非大量无关数据。
与 /debug 命令集成：与 DSH 原生调试命令协同工作。
自动化清理：提供“Fixed”操作来触发探针和日志的清理。
辅助脚本：提供用于会话生成、事件摄取、日志总结和查找工具的脚本。

安装与启用¶

在安装前，请确保已安装 Node.js ^22.19.0 || >=24.0.0、pnpm 以及 DSH 0.1.0-rc.7 或更高版本。

执行以下命令以添加插件：

dsh plugin --profile web add "github:a554878526/dsh-debug-mode#main"

安装后，请重启 dsh web 并打开一个新任务以加载插件。

典型用法¶

在 DSH 中运行 /debug 并描述遇到的 Bug。
遵循重现说明并点击 Continue。这会启动证据循环。
修复验证后，点击 Fixed 以清理诊断探针和日志。
要手动生成会话并注入事件，请使用 Python 辅助脚本：

    python3 scripts/new_debug_session.py --root .

在代码中，使用 __codexDebug 函数注入事件：

    __codexDebug({
      hypothesisId: "H1",
      location: "SessionStore.ts:restore",
      message: "cache lookup",
      data: { hit: true, entryCount: 3 },
    });

适用场景与注意¶

该插件适合需要跨浏览器、Electron 和 Node.js 运行时进行结构化调试的场景，特别是对于 UI 状态、Worker 边界、异步竞态条件和静态代码无法证明的 Bug。

注意事项：
* 依赖项：需要 Node.js ^22.19.0 || >=24.0.0、pnpm 和 DSH 0.1.0-rc.7 或更高版本。
* 进程本地状态：当前的调试状态是进程本地的。重启 DSH Host 会结束活动循环。
* 数据隐私：切勿在事件日志中记录密钥、凭据或个人身份信息 (PII)。应进行计数、采样或截断。
* 版本兼容性：0.1.1 及更早版本写入的 debug-mode/state 事件与官方 DSH 构建不兼容。如果遇到此问题，请检查并修复日志。

该工具通过提供可验证的运行时证据闭环，将调试流程从人工日志搜索转变为智能体驱动的修复。要了解更多信息或查看源代码，请访问 GitHub 仓库。