词元之母TOK.MOM - 平台充值汇率 1:1 即 1 人民币充值到账 1 美元，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"Python Debugpy — 调试 Python：pdb REPL + debugpy 远程（DAP）"
Python Debugpy
Skill 元数据
| 来源 | 内置（默认安装） |
| 路径 | skills/software-development/python-debugpy |
| 版本 | 1.0.0 |
| 作者 | Hermes Agent |
| 许可证 | MIT |
| 平台 | linux, macos |
| 标签 | debugging, python, pdb, debugpy, breakpoints, dap, post-mortem |
| 相关 skill | systematic-debugging, node-inspect-debugger, debugging-hermes-tui-commands |
参考：完整 SKILL.md
信息
Python 调试器（pdb + debugpy）
概述
| 工具 | 适用场景 |
|---|---|
breakpoint() + pdb | 本地、交互式、最简单。在源码中添加 breakpoint()，正常运行，在该行进入 REPL。 |
python -m pdb | 无需修改源码，直接在 pdb 下启动已有脚本。适合快速探查。 |
debugpy | 远程 / 无头 / "附加到已运行进程"。使用 DAP 协议，可从终端脚本化操作，适用于长期运行的进程（gateway、daemon、PTY 子进程）。 |
breakpoint() 开始。 这是最低成本的可行方案。使用时机
_SlashWorker、PTY bridge worker）才是实际的 bug 所在print() / logging.debug 一分钟内能解决的问题，或 pytest -vv --tb=long --showlocals 已经能揭示的问题。pdb 快速参考
(Pdb)）下：| 命令 | 操作 |
|---|---|
h / h cmd | 帮助 |
n | 下一行（步过） |
s | 步入 |
r | 从当前函数返回 |
c | 继续执行 |
unt N | 继续执行直到第 N 行 |
j N | 跳转到第 N 行（仅限同一函数） |
l / ll | 列出当前行附近的源码 / 完整函数 |
w | 当前位置（调用栈跟踪） |
u / d | 在调用栈中上移 / 下移 |
a | 打印当前函数的参数 |
p expr / pp expr | 打印 / 格式化打印表达式 |
display expr | 每次停止时自动打印 expr |
b file:line | 设置断点 |
b func | 在函数入口处断点 |
b file:line, cond | 条件断点 |
cl N | 清除断点 N |
tbreak file:line | 一次性断点 |
!stmt | 执行任意 Python 语句（包括赋值） |
interact | 在当前作用域中进入完整 Python REPL（Ctrl+D 退出） |
q | 退出 |
interact 命令最为强大——可以导入任何模块、检查复杂对象，甚至调用会改变状态的方法。局部变量默认只读；在 (Pdb) 提示符下使用 !x = 42 进行修改。方案 1：本地断点
breakpoint() 所在行停下，可完整访问局部变量。breakpoint()。 使用 git diff 或 pre-commit grep：方案 2：在 pdb 下启动脚本（无需修改源码）
方案 3：调试 pytest 测试
scripts/run_tests.sh 默认使用 xdist（-n 4），pdb 在 xdist 下无法正常工作。请添加 -p no:xdist 或使用 -n 0 运行单个测试：方案 4：对任意异常进行事后分析
方案 5：使用 debugpy 进行远程调试（附加到运行中的进程）
安装
模式 A：修改源码——进程在启动时等待调试器
wait_for_client()。模式 B：无需修改源码——使用 -m debugpy 启动
模式 C：附加到已运行的进程
/proc/sys/kernel/yama/ptrace_scope）。修复方法：从终端连接客户端
debugpy 自带 CLI REPL — 并非官方功能，而是一个小型 DAP 客户端脚本：launch.json：{
"name": "Attach to Hermes",
"type": "debugpy",
"request": "attach",
"connect": { "host": "127.0.0.1", "port": 5678 },
"justMyCode": false,
"pathMappings": [
{ "localRoot": "${workspaceFolder}", "remoteRoot": "/home/bb/hermes-agent" }
]
}remote-pdb — 通常这才是终端 agent 真正需要的：debugpy 的 DAP 协议过于繁重时，remote-pdb 是最适合 agent 的选择。仅在确实需要 IDE 集成时才使用 debugpy。调试 Hermes 特定进程
测试
-p no:xdist 或在不使用 xdist 的情况下运行单个测试。run_agent.py / CLI — 一次性运行
breakpoint()，然后正常运行 hermes。控制权将在暂停点返回到你的终端。tui_gateway 子进程（由 hermes --tui 启动）
hermes --tui。TUI 将显示为冻结状态（其后端正在等待）。附加客户端后，执行在你 continue 时恢复。remote-pdb：nc 127.0.0.1 4444。_SlashWorker 子进程
exec 路径中使用 remote-pdb 的 set_trace()。该 worker 在多次 slash 命令间持续存在，因此第一次触发会阻塞直到你连接；后续 slash 命令正常通过，除非你重新设置断点。Gateway（gateway/run.py）
remote-pdb，或者如果你本来就要重启 gateway，则使用带 --wait-for-client 的 debugpy。常见陷阱
1.
-p no:xdist 或 -n 0。2.
breakpoint() 在 CI / 非 TTY 环境中会挂起进程。 本地使用没问题；永远不要提交它。添加 pre-commit grep 作为安全网。3.
PYTHONBREAKPOINT=0 会禁用所有 breakpoint() 调用。如果断点未触发，请检查环境变量：4.
debugpy.listen 仅在同时调用 wait_for_client() 时才会阻塞。 不调用的话，执行会继续，你的第一个断点可能在客户端附加之前就已触发。5.
ptrace_scope=1（Ubuntu 默认值）仅允许对同用户的子进程进行 ptrace。解决方法：echo 0 > /proc/sys/kernel/yama/ptrace_scope（需要 root 权限），或从一开始就在 debugpy 下启动。6.
pdb 只调试当前线程。对于多线程代码，使用 debugpy（支持线程感知的 DAP）或为每个线程设置 threading.settrace()。7.
pdb 可在协程中工作，但在 pdb 内部使用 await 需要 Python 3.13+ 或在旧版本的 interact 模式下使用 await。对于 3.11/3.12，使用 asyncio.run_coroutine_threadsafe 技巧，或通过 asyncio.ensure_future 配合 !stmt 方式进行 await。8.
scripts/run_tests.sh 会剥离凭据并设置 HOME=<tmpdir>。 如果你的 bug 依赖用户配置或真实 API 密钥，在 wrapper 下将无法复现。先用原始 pytest 复现，再在 wrapper 下确认。9.
breakpoint() 或 set_trace()。对于 Hermes 子 agent，每次只调试一个进程。验证清单
pip install debugpy 后确认：python -c "import debugpy; print(debugpy.__version__)"ss -tlnp | grep 5678PYTHONBREAKPOINT=0、在 xdist 下运行，或执行在附加前已结束）where / w 显示预期的调用栈breakpoint() / set_trace() / debugpy.listen一次性速查方案
nc 127.0.0.1 4444，然后用 w 查看挂起的帧，用 !import asyncio; asyncio.all_tasks() 查看其他待处理任务。修改于 2026-05-31 00:25:01