Python 调试:pdb 与 debugpy
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_96b3f16c/python-debugpy。
技能介绍
你真正卡在哪
单元测试红了,但 pytest -vv --tb=long 仍看不出某个变量为何不对;或者 tui_gateway、Hermes gateway 这类长驻进程已经跑坏,却不能随便重启。更麻烦的是 bug 落在 子进程(PTY worker、_SlashWorker)里,主进程日志只有半截调用栈。
这时靠 print() 或再加两条 logging.debug 往往要反复改代码、重跑整套流程,成本太高。
技能如何组织调试手段
技能把 Python 调试拆成三种工具,按场景选,而不是堆协议名词:
breakpoint()+ pdb:本地改源码、正常启动,到行即停,成本最低;文档强调默认从这里开始。python -m pdb:不改文件,把整个脚本挂进 pdb,适合快速探针。- debugpy:远程 / 无头 / attach 已在跑的进程,走 DAP,适合 gateway、daemon;终端侧也可配合
remote-pdb。
正文给出 pdb 命令速查(n/s/w/interact/!stmt 等)、pytest 直接跑 --pdb(绕过会吞交互的 run_tests.sh 子进程包装)、sys.excepthook 式 post-mortem,以及 debugpy 的三种模式:源码 listen+wait_for_client、-m debugpy 启动、按 PID attach。针对 Hermes 生态还写了 run_agent.py、tui_gateway 子进程、Gateway (gateway/run.py)、SlashWorker 的落点与 recipe。
适用边界
- 一分钟内
print能定性、或 pytest 自带 locals 已够用 → 不必上 pdb。 - pytest-xdist / 捕获输出的并行跑法下 pdb 会静默挂死,需对单文件直接跑 pytest。
breakpoint()勿提交;留意PYTHONBREAKPOINT=0。- attach 可能受
ptrace_scope限制;多线程、fork 子进程要按技能里的分项处理。
使用场景
- 单测失败但堆栈看不出某个 dict/list 为何取值异常,需要用 pdb 单步看集合变化
- Hermes 或 tui_gateway 长驻进程行为异常且不能重启,需 attach 或 remote-pdb 连上现网进程
- 在 scripts/run_tests.sh 包装的套件里 pdb 无响应,需改对单文件直接 pytest --pdb 交互调试
- SlashWorker 或 PTY 子进程才是崩溃点,需在 worker 执行路径设 remote-pdb 再从终端 nc 接入
适合人员
- 维护 Hermes gateway / tui_gateway 的后端工程师,需要在不重启的前提下盯住 handler 与子进程
- 编写 asyncio 业务逻辑的 Python 开发者,handler 偶发死锁要用栈与 pending tasks 交叉验证
- 负责 CI 测试基建的同学,要区分并行跑测与可交互 pdb 的边界避免「假挂死」
- 在 Ink/子进程架构里排障的工程师,需要在 post-mortem 或 remote attach 下看 crash 现场 locals