dsh-debug-mode

English | 中文

DeepSeek Harness 的独立运行时优先 Debug Mode 插件。


安装

前置条件：Node.js ^22.19.0 || >=24.0.0、PATH 中可用的 pnpm，以及 DSH 0.1.0-rc.7 或更高版本。

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

重启 web profile，新建一个任务，执行 /debug，然后描述问题。卸载命令：

dsh plugin --profile web remove dsh-debug-mode

恢复 0.1.1 及更早版本写入的历史

0.1.1 及更早版本写入了必需的 debug-mode/state 事件，正式 DSH 在重新打开历史时不认识该事件。先停止 dsh web，再运行仓库中的修复 helper。未传 --apply 时只读检查；apply 模式会先备份每个需要修改的压缩日志，再原子替换原文件。

python3 scripts/repair_debug_mode_sessions.py
python3 scripts/repair_debug_mode_sessions.py --apply

后续 agent 能否使用内置脚本？

可以。插件会把四个 Python helper 全部发布到 scripts/。Host 加载 lib/index.js 时，通过 import.meta.url 找到当前已安装插件的 scripts/ 绝对目录，并把它注册为 debug-mode skill 的 directory resourceBase。DSH 随后会给 agent 渲染绝对的 <skill_resources> 目录，skill 再要求 agent 从该目录执行 helper。因此通过 Git 依赖、打包产物或本地 checkout 安装时都不依赖开发机源码路径。

插件必须在 DSH 进程启动前完成安装；重启后请新建任务，让 agent 获取新注册的 skill。Host 还需要提供 Python 3，helper 才能运行。

开发

pnpm install
pnpm run check

在仓库 checkout 中可用下面的命令安装到本地 profile，之后重启该 profile：

dsh plugin --profile web add .

运行时优先的 Debug Mode，一个双面（host + client）包。宿主半面注册 debug-mode skill、/debug 与进程内阶段约束；浏览器半面通过输入区始终可用的「命令」菜单提供该命令，并在启用后通过 conversation.input.dock 渲染循环控制条。

执行 /debug 会启用进程内 setup 状态、立即打开控制条，并把 canonical debug-mode skill 正文排入下一条真实用户消息；它自身不会唤醒模型。模型无需自行选择 skill 工具就能收到快速启动契约。控制条提交 继续分析、已修复，请清理调试日志和插桩代码 或 退出 Debug Mode。已修复会在清理回合前关闭宿主约束；退出则关闭约束且不发起模型请求。插件不再写入自定义 session event，因此独立安装不会导致 DSH 历史无法读取。

scripts/ 下随包提供四个受支持的辅助脚本（new_debug_session.py、debug_ingest_server.py、summarize_debug_log.py、find_instrumentation.py）。运行时 skill 从 import.meta.url 解析当前已安装插件的脚本目录，并把它发布为 directory resourceBase，因此源码 checkout、打包发布、pnpm Git 依赖与独立插件仓库都使用相同的相对名称，不依赖机器固定路径。skill 要求优先使用这些脚本，只有脚本缺失或执行失败时才允许使用内联回退。

启动路径以取得第一条非空日志为目标：运行会话脚本、启动它打印的 ingest 命令、只读取足以放置 1-3 个探针的代码，再输出确切的 <debug_reproduction_handoff> 包装。setup 不设 Debug Mode 工具次数上限。宿主从成功的 helper 结果提取 session id、日志路径与 ingest URL，观察成功的 server 命令，并且只允许绑定这些事实的 edit/write 内容。仅写 console 的探针、普通修复、失败写入和不匹配的交接都不能进入 waiting-for-repro。

helper 可能输出绝对日志路径，而 handoff 使用文档约定的仓库相对路径 .codex-debug/...。宿主会把两者作为同一条 Debug Mode 日志比较；如果日志文件名确实不同，则返回专门的路径不匹配错误，不再误报“没有插桩”。

setup 与 analyzing 响应经过宿主强制执行的 llm/stream 过滤器。过滤器会缓存完整 setup 响应，保留中间 reasoning、工具调用与用量以供 thinking provider 回放，并且只在首次交接前移除普通文本。analyzing 期间普通验证报告保持原样，新的交接则像首轮一样经过校验与渲染。每一轮都必须建立新的 helper/server/probe 事实，并使用此前 waiting-for-repro 状态未使用过的日志路径。首次 waiting 前继续分析会被拒绝；之后每次点击只消费一条 waiting 消息，直到下一轮 waiting 消息出现才重新启用。

在已修复之前，宿主 guard 会保留完整证据链：analyzing 不能停止 ingest 任务、删除 .codex-debug，也不能在没有替换为下一轮 transport-backed 探针时移除探针。根因已证明时只发布验证报告并保持 analyzing；只有已修复会记录 inactive 并允许清理所有轮次的日志与任务。

证据到达前，skill 禁止写复现测试、跑类型检查或构建、做宽泛静态分析以及修复。Browser/Electron 探针必须通过 fetch 把事件发送给运行中的 ingest server，由它写入 JSONL；仅写 console 的探针无效。每份生成模板只内联一行 JSON.stringify replacer，把 BigInt 转成十进制字符串。

模型体验

运行时阶段与循环控制

#### 模型看到什么

/debug 会记录 setup，并排入与 skill loader 返回值相同的 <skill_content name="debug-mode"> 块；该上下文与下一条真实用户消息一起进入模型历史，而不是单独开启回合。模型输出交接包装，但只有宿主渲染的复现说明会进入会话日志。控制条会在首条说明前禁用继续分析，点击时消费该 waiting 消息 seq，并要求出现更晚的说明后才能再次继续。每次点击都会在用户消息进入请求前记录 analyzing。已修复会在清理消息进入前记录 inactive；退出会记录 inactive，并在模型请求前拒绝这个控制回合。

#### Token 影响

/debug 会给下一次真实请求增加渲染后的 skill 上下文，但自身不消耗模型请求。有效交接会增加一条紧凑的宿主渲染 assistant 消息；继续分析与已修复各增加一条短用户消息，退出不增加模型 token。

#### KV Cache 影响

渲染后的 skill 上下文与宿主交接并入请求追加后缀；继续分析与已修复各追加一条用户消息。Debug Mode 不新增工具 schema，退出不改变缓存输入。

已知限制与后续工作

• Debug Mode 状态只存在于当前进程 —— 重启 Host、刷新页面或重新打开 session 都会结束当前循环；再次执行 /debug 可恢复控制条并重新开始 setup。这样可以避免写入当前 DSH 持久化 API 无法标记为 ignorable 的外部事件类型。
• 退出不会撤回已排队上下文 —— 如果用户在发送下一条真实消息前退出，即使宿主约束已关闭，已排队的激活上下文仍会进入下一次请求。
• setup 输出有意延迟 —— 每次模型响应完成后才显示工具活动，从而阻止被丢弃的诊断文本流入 UI。
• 清理发生在下一轮模型回合 —— 已修复 提交一条消息而不是自己删除文件；由 skill 指引模型移除探针并删除 .codex-debug/ 日志。因此机械化清理由模型完成，而非宿主服务。
• helper 与 server 通过已打包命令名识别 —— 宿主约束会识别成功的 new_debug_session.py 与 debug_ingest_server.py 调用，再把探针内容和交接数据绑定到 helper 输出。其他传输方式必须使用已打包回退约定，或扩展该识别逻辑。