Agent Skills
返回列表
💻

Python 调试:pdb 与 debugpy

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 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