出海助手-Python调试 / Python Debugpy

> 本技能改造自开源技能 python-debugpy（来源：openclaw/openclaw，openclaw 开源技能生态）。已完整保留原始运行文件（scripts/references/assets 与 LICENSE），并新增中文出海使用说明。原始英文说明见文末「English (Original)」与同目录 SKILL.original.md。

功能说明 / Functional Overview

用 debugpy 对 Python 程序进行断点调试，支持远程与容器场景。

适用场景 / Use Cases

• Python 服务远程调试
• 容器内断点排查
• 复杂逻辑逐步执行

使用方法 / How to Use

1. 按原技能说明挂载 debugpy，技能会协助设置断点与变量检查。

示例 / Examples

• 「Python 服务远程调试」——用自然语言把任务交给本技能即可。

限制说明 / Limitations

• 需要外部服务/凭证的技能，请先完成授权配置后使用。
• 本技能为开源技能的中文本地化版本，核心逻辑与原技能一致；如遇专业术语，正文保留英文原词（如 Shopify、SEO、GA4 等）。

English (Original) / 英文原文（完整保留）

> The section below is the original skill definition, preserved verbatim for traceability and full functionality.

Python Debugpy

Use when Python code needs interactive debugging: hidden locals, confusing state mutation, failing tests, subprocesses, long-running services, or remote/headless attach.

Pick the smallest debugger that reaches the bad frame.

Choose

• breakpoint(): local code, source edits ok, fastest path.
• python3 -m pdb: no source edit, launch from the beginning.
• python3 -m pdb -c continue: stop at an unhandled exception.
• debugpy: remote/headless process, DAP client, already-running PID, or service startup race.

Commands

python3 -m pdb path/to/script.py arg1
python3 -m pdb -c continue path/to/script.py
python3 -c "import debugpy" || python3 -m pip install debugpy
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module
python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>

For source-edit attach:

import debugpy

debugpy.listen(("127.0.0.1", 5678))
debugpy.wait_for_client()
debugpy.breakpoint()

For post-mortem:

import pdb, sys

try:
    run()
except Exception:
    pdb.post_mortem(sys.exc_info()[2])
    raise

pdb

• Flow: n, s, r, c, q.
• Stack/source: w, u, d, a, l, ll.
• Values: p expr, pp expr, display expr.
• Breakpoints: b file.py:42, b func, b file.py:42, condition, cl <num>.
• Mutate/evaluate: !statement; full REPL: interact.

Rules

• Reproduce with the smallest command/test first.
• Disable parallel test workers for pdb; interactive stdin usually breaks inside worker pools.
• Keep debugpy in the active env; do not add it as a project dependency unless the project already wants it.
• Bind debug servers to 127.0.0.1; do not expose 0.0.0.0 unless isolated or tunnelled.
• Use unique ports for parallel sessions.
• Treat debugpy --pid as injection; avoid security-sensitive or production targets unless explicitly approved.
• If PID attach fails on Linux, check ptrace/container privileges before changing the target.
• Cleanup before commit: rg -n 'breakpoint\\(|pdb\\.set_trace|debugpy\\.' --type py.
• Rerun the normal project test/gate without the debugger.
• PYTHONBREAKPOINT=0 disables breakpoint().
• If a process is stuck after debugger detach, confirm it is not still paused at a breakpoint.