DAP：让 Coding Agent 真正会调试
agent 终于可以像人一样「跑起来看」。
导语
装上 @piex-dev/dap 之后，agent 可以像人一样「跑起来看」。它替代不了测试，但会把「猜变量」变成「读变量」。
问题背景
多数 agent「修 bug」靠猜 + 改 + 再跑测试。运行时问题（调用栈、局部变量、条件断点）没有调试器就很脆。人用 IDE 开 DAP；agent 不该只会 print。
@piex-dev/dap 注册 debug 工具，把 Debug Adapter Protocol 接到 pi：launch、断点、单步、看变量。
技术原理
三层：Agent 决策 → DAP 客户端翻译 → debugpy/dlv/lldb 等 adapter 控进程。会话状态机 running / stopped / terminated；stdio 帧传 JSON-RPC。
defaults.json 按后缀与 root marker 自动选 adapter（共 14 个）。Node 移植只做 stdio，不做 TCP 远程 attach。
实现方案
client.ts 管帧；session.ts 管会话、断点队列、输出缓冲与空闲清理；工具面覆盖 launch/attach、断点、步进、栈/变量/evaluate、内存与 disassemble。
| 要点 | 做法 |
|---|---|
| 断点变更 | 串行队列，避免覆盖 |
| 输出 | 约 128KB 上限，防撑爆上下文 |
| 超时 | 5–300s 夹紧 |
| 非交互 | 注入 PAGER=cat 等，防 pager 挂死 |
设计参考
| 项目 | 机制 | piex 取舍 |
|---|---|---|
| oh-my-pi dap | 完整 DAP 客户端：stdio + TCP + WebSocket；14+ adapter；结构化输出；TUI variable explorer | 采纳：14 adapter 配置、JSON-RPC 帧协议、断点队列、输出缓冲上限、空闲回收。不采纳：TCP/WebSocket（本机够用）、TUI overlay（pi API 限制） |
| VS Code DAP | 协议规范三层模型（editor / client / adapter） | 借鉴：三层分工理念、capabilities 检查、stop 后自动附上下文摘要 |
核心取舍：只做 stdio（简单安全），不做远程 attach；先文本输出（快速落地），暂缓 TUI。
优化计划
补数据/异常断点暴露；stop 后默认附栈顶+局部变量；读 launch.json；可选 TCP；eval 挂钩 debug_success。
源稿 Markdown： docs/notes/dap.md