SKILL.md
GDB OpenOCD 调试
适用场景
- 用户希望通过 OpenOCD 调试 Cortex-M 类目标。
- 工作区中已有
ELF和与 OpenOCD 兼容的探针信息。 - 烧录或串口监视流程表明，需要进一步查看断点、停核控制、寄存器或回溯信息。
- 需要在调试前确认 OpenOCD 和 GDB 环境是否就绪。
必要输入
- 一份带符号的
ELF，或包含artifact_path的Project Profile。 - OpenOCD 配置信息，或足以安全解析配置的工作区线索。
- 可选调试模式：
download-and-halt、attach-only、crash-context。 - 可选的 GDB 可执行文件路径。
自动探测
- 默认模式为
download-and-halt；只有用户显式要求附着调试或崩溃现场检查时才切换。 - GDB 由脚本自动探测，优先级为：显式用户输入、
Project Profile、arm-none-eabi-gdb、gdb-multiarch。 - 探针由脚本自动探测，优先级与
flash-openocd保持一致。 - 做符号级调试必须有
ELF。若只有HEX或BIN，应阻塞并要求提供匹配ELF。
执行步骤
- 先阅读 [references/debug-playbook.md](references/debug-playbook.md) 中的决策树，判断应使用条件断点、普通断点还是 OpenOCD Telnet。
- 再阅读 [references/usage.md](references/usage.md)，确认本次是环境探测，还是执行调试会话。
- 若不确定环境是否就绪，先运行自带脚本 [scripts/gdbdebugger.py](scripts/gdbdebugger.py) 的
--detect模式确认。 - 根据用户意图选择调试模式：
download-and-halt（默认）、attach-only或crash-context。 - 使用
--elf指定符号文件，配合--interface+--target或--config启动调试。 - 读取脚本输出的调试结果，重点关注寄存器状态、回溯帧和 Fault 寄存器（crash-context 模式）。
- 将调试配置和关键观察写回
Project Profile，并在需要时交给下游 skill。
失败分流
- 当缺少
openocd或兼容 GDB 时，返回environment-missing。 - 当没有可用的
ELF时，返回artifact-missing。 - 当 OpenOCD 或 GDB 无法连接目标板时，返回
connection-failure。 - 当 OpenOCD 配置或符号文件与目标不一致时，返回
project-config-error。 - 当会话可以建立，但无法停核、加载或得到可信回溯时，返回
target-response-abnormal。 - 当存在多个同样合理的探针、配置或符号文件时，返回
ambiguous-context。
平台说明
- 自带脚本使用 Python 标准库和 subprocess 调用 openocd 和 gdb，因此调试调度路径本身是跨平台的。
- 输出中应将 OpenOCD 与 GDB 命令分开列出，方便用户在其他 shell 或 IDE 中复现。
- Windows 宿主机可能需要解析
.exe后缀，但逻辑流程与其他平台一致。
输出约定
- 输出调试模式、OpenOCD 命令、GDB 可执行文件、
ELF路径和关键观察结论。 - 在
Project Profile中保留artifactpath、artifactkind、gdbexecutable、openocdconfig。 - 当复位后或继续运行后下一步是观察运行行为时，推荐
serial-monitor。
交接关系
- 当目标恢复运行后，需要继续观察运行期日志时，将成功会话交给
serial-monitor。