用途:go-debug 用于在单一上下文中交互式调试 Go 程序,通过 tmux 驱动 Delve(dlv),不委派给子智能体。当仅阅读源码不足以定位问题时使用:只在运行期复现的缺陷(panic、错误取值、挂起);测试失败但原因隐藏;集成测试挂起、死锁或与单元测试行为不同;长期运行服务(如 lnd、eclair)预热后才异常;需要逐 goroutine 检查的并发缺陷;需要单步确认复杂分支控制流。若 bug 用 grep 即可看出或写单元测试更快,则不适用。
前提:dlv 在 PATH 中(go install github.com/go-delve/delve/cmd/dlv@latest),tmux 在 PATH 中。macOS 上 attach 要求目标进程可被当前用户调试;Linux 上 ptrace 可能需要 sudo 或 kernel.yama.ptrace_scope=0。
使用方式:所有会话管理通过 ~/.claude/skills/go-debug/scripts/dlv-session.sh 进行,一次管理一个活动会话,状态存于 $TMPDIR/claude-dlv/current,剥离 ANSI 噪声,并在每条命令后等待下一个 (dlv) 提示符。命令包括 start(启动并等待首个提示符)、send(发送一条命令并返回新输出,默认超时 DLV_SEND_TIMEOUT 300 秒)、send-raw、output、status、stop。调试循环为读—发—观察:启动会话、设置断点、continue、检查状态(print、locals、args、stack、goroutines)、单步(step/next)、验证假设,停止会话后再编辑代码。
可用启动模式:debug(调试 main 包)、test(调试测试,常用 -test.run 收窄)、attach(附加到运行中进程)、connect(连接 dlv headless 服务端)、core(对 core dump 做事后分析)。常用 dlv 命令包括 break、continue、next、step、print、locals、args、whatis、stack、goroutines、condition、trace 等。
限制与注意:源码修改不会反映到当前运行的二进制,改代码后需停止并重启;用 -ldflags="-s -w" 构建的二进制无调试符号,无法调试;attach 时目标进程会被暂停;会话结束须用 stop 清理,否则会占用 tmux 槽并保持进程暂停;路径与符号解析、macOS 代码签名、CI 全局超时等问题需注意。