前言¶

用智能体修 bug 时，常见路径是：Agent 读代码、猜原因、改一版、你本地试、不对再猜一轮。现象偶发、路径复杂时，这种「无现场证据的推断」往往要多轮才能对上。

DeepSeek Harness（DSH）支持通过插件扩展宿主能力。社区目录 skillhub.cn 上的 dsh-plugin-debug-mode（维护者 rh666666，分类：客户端）走另一条路：先在可疑路径埋探针，由你复现一次，Agent 读日志再决定修复或继续取证。下面介绍它的定位、流程、安装与用法。

这是什么¶

dsh-plugin-debug-mode 是 npm 包 dsh-plugin-debug-mode，GitHub 仓库 rh666666/dsh-plugin-debug-mode。README 说明它是「完全由 DSH 写的 DSH 插件」，目标是 Cursor Agent 式的 Debug 模式：让 Agent 在代码库里埋可摘除的探针，把运行现场写入日志，而不是只靠静态阅读猜根因。

整条调试闭环 不依赖 Agent 执行 shell 命令；Agent 主要通过 dsh_debug_* 工具与源码改动（埋点/修复）推进，「跑起来复现」由你在本地或目标环境完成。

它解决什么问题¶

典型场景类似 README 中的例子：「点了保存之后列表偶尔不刷新。」

传统 Agent 调试容易变成多轮猜测。Debug 模式的顺序是：

1. 你描述现象（或通过 /debug 发起后补充）。
2. Agent 分析并在可疑路径埋探针（带 dsh-debug:probe 等标记，便于收尾摘除）。
3. 探针经宿主 HTTP 通道写入任务日志（默认在用户临时目录，见下文「产物位置」）。
4. 你按 Agent 给出的复现步骤操作一次。
5. Agent 通过 dsh_debug_read 读取日志摘要（异常全量、分组计数等）。
6. 输入框上方调试面板展开，你选择「问题已解决」或「问题复现，需要进一步修复」。

选「已解决」时：删除日志并移除本次全部探针代码；选「复现」时：日志保留，Agent 应先读日志再进入下一轮（dsh_debug_continue 会清空日志，哈希不变）。

怎么进入调试¶

唯一入口是斜杠命令。描述会作为你的用户消息原样发出，宿主同时注入调试模式系统准则（与 Plan 模式类似：模式走注入，输入走消息）。

/debug 保存之后列表偶尔不刷新，十几分钟出现一次

敲回车即开始；对话里不会出现你没说过的长段指令。若命令后未写描述，不会凭空发消息，可在下一条消息里说明现象、期望与复现路径。

dsh_debug_start 必须持有 /debug 签发的票据；无票调用会被宿主拒绝。插件不识别对话意图、不提供工具栏按钮——埋探针会改代码库，需你显式用 /debug 发起。

核心机制概览¶

五个信号工具¶

调试期间的改代码规则¶

• 第 1 轮默认只取证、不改行为（除非出现 dsh-debug:change 标记时闸门拒绝——埋探针本身不算改行为）。
• 第 2 轮起可先按假设修改，再埋点验证「改前复现、改后不复现」。
• 探针（dsh-debug:probe <hash>）、临时块（dsh-debug:temp）、修复（dsh-debug:change <hash>）分开记账；收尾 只删探针与临时块，不回滚你的修复；整体 git checkout 回滚被明令禁止。

探针与 HTTP 通道¶

写日志由宿主统一实现。探针向固定路径 POST JSON 即可：

curl -s 'http://127.0.0.1:<DSH 端口>/dsh-debug-mode/probe?h=<hash>'

curl -s -X POST 'http://127.0.0.1:<DSH 端口>/dsh-debug-mode/probe?h=<hash>' \
  -H 'content-type: text/plain' \
  --data-binary '{"probe":"app.py:42:enter","data":{"order_id":"A1"}}'

路径为 /dsh-debug-mode/probe，任务哈希在查询串 ?h=。地址与端口由插件根据 DSH_WEB_URL 或 webServer.port 计算；dsh_debug_start 会在任务目录生成多语言示例（含 runtime/probe.http.md）。

浏览器调试静态页时，可使用宿主提供的脚本桩（GET /dsh-debug-mode/stub.js?h=<hash>），对 file:// 页面同样可用，无需为调试单独起本地 Web 服务（若 CSP 限制需调整 script-src 或粘贴 runtime/probe.browser.js）。

产物放在哪¶

默认：os.tmpdir()/dsh-debug-mode/tasks/<hash>/，与仓库分离，任务结束会删除。

• 临时目录不可写时回退到 <仓库>/.dsh/debug-mode/，面板与工具返回中会提示。
• 环境变量 DSH_DEBUG_MODE_TMP 或工具参数 tempDir 可改临时根路径。
• 系统清理临时目录可能导致在途任务无法继续，需重新 /debug。

交互面板¶

任务存续期间，输入框上方有一张可折叠卡片：Agent 埋点时常收起；轮到你复现并选择时会展开，展示一句话结论、复现步骤，以及「问题已解决」「问题复现，需要进一步修复」按钮。只有你在面板上做过选择，Agent 才被允许 dsh_debug_end 收尾。

安装与启用¶

推荐在 DSH 插件侧边栏的安装框输入包名：

dsh-plugin-debug-mode

命令行等价：

dsh plugin --profile web add dsh-plugin-debug-mode

指定版本时在包名后加版本号，例如：

dsh plugin --profile web add dsh-plugin-debug-mode@0.21.0

也可从 GitHub 安装：

dsh plugin --profile web add github:rh666666/dsh-plugin-debug-mode

安装期无需构建、无需 node_modules（零运行时依赖）。package.json 要求 Node >=18、DSH >=0.1.5-rc.1，许可证 MIT。装完后 /debug 会出现在宿主命令面板。

注意：插件以当前 DSH 进程权限运行，会在工作区写入探针与可能的回退目录；安装前建议查看仓库源码与许可证，确认符合你的安全与合规要求。社区目录站点与 DeepSeek / 幻方无官方从属关系，属于 DSH「一切皆插件」生态中的第三方条目。

典型用法¶

1. 在任意会话执行 /debug，后跟现象描述（或随后补充）。
2. 等待 Agent 调用 dsh_debug_start 并完成埋点、dsh_debug_report。
3. 按面板复现步骤操作程序一次。
4. Agent 读取日志后给出结论；你在面板选择是否已解决。
5. 若未解决，Agent 在读完日志后 dsh_debug_continue 进入下一轮。

README 也说明：若 Agent 读代码即可确定根因（明显空指针、拼写错误、缺 await 等），应直接修复而非强行走探针流程；/debug 票据会过期，需要时再发起即可。

适用场景与限制¶

适合：间歇性 bug、需要运行轨迹才能定因的问题、多语言/浏览器/远程进程（通过 HTTP 探针或文档中的文件桩方案）等需要「先取证再改」的场景。

不适合或需知：

• 热路径需聚合后再 POST，避免每帧上千次 HTTP。
• 大仓库收尾扫描有文件数/时间预算（默认 DSH_DEBUG_MODE_SCAN_MAX_FILES 为 20000）；不完整时 dsh_debug_end 可能返回 scanIncomplete: true，已报备的 probeFiles 仍会完整扫描。
• 未清干净的任务会出现在欠账看板 /dsh-debug-mode/board。

仓库 README 标注实现状态为 v0.21 时测试全绿；当前 npm 版本以 package.json 为准（如 0.22.1）。GUI 面板上的真实点击验证需人在宿主界面完成。

结尾¶

dsh-plugin-debug-mode 把 Debug 模式收成「埋探针 → 你复现 → 读日志 → 面板决策 → 摘除探针、保留修复」的固定流程，并硬性约束「不靠 Agent 跑命令」以避免权限与环境阻断整个调试链。

• 目录页：https://www.skillhub.cn/plugins/rh666666/dsh-plugin-debug-mode
• GitHub：https://github.com/rh666666/dsh-plugin-debug-mode
• npm：https://www.npmjs.com/package/dsh-plugin-debug-mode