dap — 让 Coding Agent 真正会调试

简介

多数 coding agent 的「修 bug」路径是：读代码猜原因 → 改几行 → 用 bash 再跑测试 → 失败就再猜。一碰到「只有运行时才暴露」的问题就很脆：空指针在哪层调用栈？局部变量当时是什么？断点能不能停在条件分支上？

DAP 是 VS Code 那套调试协议。@piex-dev/dap 把它接到 pi 上：模型调用 debug 工具，就能 launch、下断点、单步、看变量。

技术原理

三层分工：Agent（pi + LLM 决策）→ DAP 客户端（@piex-dev/dap 翻译成标准 DAP 请求）→ Debug Adapter（debugpy/dlv/lldb-dap 真正控制进程）。会话状态机 running/stopped/terminated，模型每次拿到的是会话摘要 + 格式化文本，而非原始 JSON-RPC。

launch/attach → spawn adapter(stdio) → initialize
→ running → stopped(断点/步进/异常)
→ stack_trace/variables/evaluate
→ continue/step_* → terminate

适配器选择：defaults.json 按启动命令、语言后缀、项目根标记、launch/attach 默认参数配置；launch 时按文件后缀 + 工作区根标记自动挑 adapter。Node 移植只做 stdio（本机够用、省 socket 生命周期），不支持远程 TCP attach。

使用说明

安装

pi install npm:@piex-dev/dap

仓库源码：extensions/dap

前提条件

扩展负责协议与会话，不负责替你装调试器。对应语言还要装 adapter 本体：

pip install debugpy        # Python
brew install llvm           # lldb-dap
go install github.com/go-delve/delve/cmd/dlv@latest  # Go

已支持 14 个 adapter：gdb、lldb-dap、codelldb、debugpy、dlv、js-debug-adapter、netcoredbg、kotlin-debug-adapter、rdbg、php-debug-adapter、bash-debug-adapter、dart-debug-adapter、flutter-debug-adapter、elixir-ls-debugger。

配置

默认配置在 extensions/dap/defaults.json。无需手写配置，扩展按文件后缀 + 项目根标记自动选 adapter；模型也可显式指定 adapter 名称。

典型用法

debug(action=launch, program=./main.py)
debug(action=set_breakpoint, path=main.py, line=42)
debug(action=continue)
# 命中后
debug(action=stack_trace)
debug(action=variables, variablesReference=…)
debug(action=evaluate, expression="user.id")

验证

pi -e ./extensions/dap/src/dap.ts -p "what is 1+1" --no-session

实现方案

dap.ts 注册 debug 工具分发 action；client.ts 处理 Content-Length 帧 + JSON-RPC；session.ts 管会话、断点队列、输出缓冲、空闲清理；config.ts 读 defaults.json 选择 adapter。

能力按 adapter 上报的 capabilities 检查：不支持的操作直接报错，避免 silently no-op。工程细节：断点变更串行化、输出环形缓冲（~128KB）、空闲回收、超时夹紧（5s–300s，默认 30s）、非交互环境变量注入（PAGER=cat）。

设计参考

核心取舍：只做 stdio（简单安全），不做远程 attach；先文本输出，暂缓 TUI；capabilities 驱动能力面，不一次铺满。

迭代记录

路线图

产品向：停住即给上下文（stop 自动附栈顶 + 关键变量）；launch 可项目化（读 .vscode/launch.json）；评测挂钩（debug_success 可复现任务量）。

版本记录