DAP 调试器 hy-sde/dsh-tool-debug

[!NOTE]
📦 这个插件放在 dsh-plugins 单体仓库里 —— 提 issue 和 pull request 请到那里。
npm：@hy-sde-org/dsh-dap · @hy-sde-org/dsh-tool-debug

dsh-tool-debug —— 给 DeepSeek Harness 用的真 DAP 调试器

两个独立包，可以作为一个插件装进 DeepSeek Harness 命令行：

| 包 | 作用 | 用户要装吗？ |
| @hy-sde-org/dsh-dap | 独立的 Debug Adapter Protocol 接缝：DAP 客户端 + 会话管理器（launch/attach、断点、单步、帧/作用域/变量、求值、内存、模块、输出、终止） | 不用 —— 传递依赖 |
| @hy-sde-org/dsh-tool-debug | 插件本体：面向模型的 debug 工具（28 个操作），结果渲染成 launch/breakpoint/step/stack/evaluate | 要 |

debug 工具是把 oh-my-pi 的 coding-agent debug 工具按 harness 工具契约（ctx.tools、ctx.dap、ctx.systemPrompt）对等移植过来的。DAP 接缝会把真正的调试适配器（debugpy、lldb-dap、gdb、dlv、js-debug……）当本地二进制拉起，走 stdio 或预留的 TCP 端口；适配器不可用时，会解析成结构化的「不可用」错误，并给出安装命令；每个操作都返回一份会话快照，这样智能体看到的调试器状态始终一致。在现成的 DeepSeek Harness 发行版上全部可用，上游零改动。

为什么做这个。 编码智能体调试，大头在 harness：一个能单步、能下断点的真调试器 —— 而不是「插 print 再重跑」—— 决定了你是在审问故障，还是在故障周围打桩。这个插件把一套久经考验的 DAP 调试器搬进模型的工具面，并以可安装插件的形式发布。

安装

pnpm install --global @deepseek-ai/dsh

直接从 npm 装（已发布）

两个包都已发布到 npm registry 的 hy-sde-org 组织下（@hy-sde-org/dsh-dap 和 @hy-sde-org/dsh-tool-debug，版本 0.1.2-rc.1）。直接从 npm 装插件即可 —— registry 会自动解析 dap 库依赖和 DeepSeek Harness 的 peer 包：

one command; @hy-sde-org/dsh-dap comes in as a transitive dependency
dsh plugin --profile web add @hy-sde-org/dsh-tool-debug

只装这个 bundle 绝不会弄坏启动，也不会在宿主平面上占用任何名字 —— harness 本来就没有 debug 工具可被遮蔽。等你挂上提供的 agent preset 行，工具才会可用。

从 git 检出装（发布前 / 开发）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins
pnpm install
pnpm --filter @hy-sde-org/dsh-tool-debug build
symlink both packages into your harness's plugin lookup
dsh plugin --profile web link ../dsh-tool-debug/packages/tool-debug

验证

bash
pnpm -r check && pnpm -r test && pnpm -r build
bash scripts/release-public.sh --check # clean tree + checks + tests + pack

要做实时调试器往返测试，就把测试套件指向装了 debugpy 的 Python： bash
DSH_DEBUGPY_PYTHON=/path/to/python pnpm --filter @hy-sde-org/dsh-dap test

卸载 bash
dsh plugin --profile web remove @hy-sde-org/dsh-tool-debug

给智能体装上 debug 工具

packages/tool-debug/examples/agent-preset/ 里有一份可直接复制的用户预设。把 agent.cordis.yml 和 preset.yml 复制到 ~/.dsh/.agent-presets/<id>/，在 Web UI 的预设选择器里选中它（或者用 dsh agent 命令行），该预设下的智能体就能拿到 debug 工具。预设把 dap 服务挂载在它自己隔离的领域里，这样每个智能体各自持有适配器进程和断点状态，tool-debug 就放在它旁边： yaml
- id: debug
name: cordis:group
group: true
isolate:
dap: true
config:
- id: dap
name: '@hy-sde-org/dsh-dap'
- id: tool-debug
name: '@hy-sde-org/dsh-tool-debug'

这个 bundle 做了什么

- 不插入任何行，也不禁用任何东西。 官方 harness 没有 debug 工具，所以不存在需要处理的冲突——bundle 的补丁是一个有文档记录的空操作，让这个包能作为普通插件安装。
- 挂载在智能体平面。 上面那行预设是模型唯一能看到的界面；它按会话划分作用域。
- 适配器是本地二进制文件。 debugpy（pip install debugpy）、gdb、lldb-dap、dlv 和 vscode-js-debugger 都在运行时通过 PATH/DSH_DEBUGPY_PYTHON 环境发现；不可用会返回结构化错误，而不是崩溃。

工具操作

launch · attach · set_breakpoint · remove_breakpoint · set_function_breakpoint · remove_function_breakpoint · set_instruction_breakpoint · remove_instruction_breakpoint · data_breakpoint_info · set_data_breakpoint · remove_data_breakpoint · disassemble · read_memory · write_memory · modules · loaded_sources · custom_request · continue · pause · step_in · step_out · step_over · threads · stack_trace · scopes · variables · evaluate · get_output · terminate · sessions · capabilities

开发 bash
pnpm install
pnpm -r check # typecheck both packages
pnpm -r build # tsc -> dist for both

目录结构

packages/dap/ @hy-sde-org/dsh-dap (the DAP seam/engine)
src/client.ts DAP client + Content-Length framing
src/session.ts DapSessionManager
src/config.ts adapter resolution + launch defaults
src/defaults.ts omp default adapter configuration
src/env.ts python/debugpy probing
tests/ framing + session specs + live debugpy round trip
packages/tool-debug/ @hy-sde-org/dsh-tool-debug (the debug tool plugin)
src/index.ts tool plugin entry (schema, config, dispatch)
src/render.ts result rendering the model reads
src/session.ts per-call dispatch over ctx.dap
yaml
cordis.patch.yml zero-effect install patch
examples/agent-preset/ ready-to-copy user preset

来源说明见 THIRD-PARTY-NOTICES.md，贡献与发布流程见 CONTRIBUTING.md。