J-Link 下载与在线调试
本 skill 提供 J-Link 探针的设备探测、固件烧录、内存读写、寄存器查看、目标复位、RTT 日志读取，以及轻量在线调试和 GDB 源码级调试能力。
配置
环境级配置（skill/config.json）
skill 目录下的 config.json 包含环境级配置（工具路径、端口号等），首次使用前确认 exe 路径正确：
json{ "exe": "C:\\Program Files\\SEGGER\\JLink\\JLink.exe", "gdbserver_exe": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe", "rtt_exe": "C:\\Program Files\\SEGGER\\JLink\\JLinkRTTClient.exe", "gdb_exe": "C:\\Program Files\\Arm\\GNU Toolchain mingw-w64-x86_64-arm-none-eabi\\bin\\arm-none-eabi-gdb.exe", "serial_no": "", "rtt_telnet_port": 0, "swo_command": [], "operation_mode": 1 }
exe：JLink.exe 完整路径（必填）gdbserver_exe：JLinkGDBServerCL.exe 路径，RTT 和 GDB 调试需要rtt_exe：JLinkRTTClient.exe 路径gdb_exe：arm-none-eabi-gdb 路径，GDB 源码级调试需要serial_no：默认探针序列号，多探针场景下使用rtt_telnet_port：RTT 端口，0 表示使用工具默认值swo_command：可选，完整 SWO viewer 命令数组，供jlink_swo.py包装operation_mode：1直接执行 /2输出风险摘要但不阻塞 /3执行前确认
工程级配置（.embeddedskills/config.json）
设备参数（device/interface/speed）统一在工作区的 .embeddedskills/config.json 中管理：
json{ "jlink": { "device": "STM32F407VG", "interface": "SWD", "speed": "4000" } }
device：芯片型号（如 STM32F407VG、GD32F470ZG）interface：调试接口，SWD 或 JTAG，默认 SWDspeed：调试速率 kHz，默认 4000
参数解析优先级：CLI 显式参数 > .embeddedskills/config.json（工程级）> skill/config.json（环境级）> .embeddedskills/state.json > 默认值/报错
成功执行后，确认过的 device/interface/speed 会自动写回工程配置。
子命令
基础操作
| 子命令 | 用途 | 风险 |
|---|---|---|
info | 探测探针与目标连通性 | 低 |
flash | 烧录固件（.hex / .bin / .elf） | 高 |
read-mem | 读取内存区域 | 低 |
write-mem | 写入内存 | 高 |
regs | 查看 CPU 寄存器 | 低 |
reset | 复位目标芯片 | 高 |
rtt | 读取 RTT 日志输出 | 低 |
swo | 包装外部 SWO viewer 为统一事件流 | 低 |
在线调试（JLink Commander）
| 子命令 | 用途 | 风险 |
|---|---|---|
halt | 暂停 CPU，返回寄存器状态 | 低 |
go | 恢复 CPU 运行 | 低 |
step | 单步执行（支持指定步数），返回执行的指令和寄存器 | 低 |
run-to | 设置断点并运行，等待命中后返回状态 | 低 |
GDB 源码级调试
| 子命令 | 用途 | 依赖 |
|---|---|---|
gdb backtrace/locals | 查看调用栈和局部变量 | arm-none-eabi-gdb |
gdb break/continue/next/step/finish/until | one-shot 控制执行流 | arm-none-eabi-gdb |
gdb frame/print/watch/disassemble/threads/crash-report | one-shot 源码级诊断 | arm-none-eabi-gdb |
执行流程
- 读取
skill/config.json，确认exe路径有效 - 读取
.embeddedskills/config.json获取工程级配置（device/interface/speed） - 读取
.embeddedskills/state.json获取历史状态 - 参数解析优先级：CLI 显式参数 >
.embeddedskills/config.json（工程级）>skill/config.json（环境级）>.embeddedskills/state.json> 默认值/报错 - 若当前动作需要
device且仍为空，直接要求用户补充，绝不猜测 - 多探针场景未指定
serial_no时，列出探针让用户选择，不自动选择 - 按
operation_mode决定是否需要确认后执行 - 使用模板生成临时
.jlink命令文件，调用 JLink.exe 时带-NoGui 1 -ExitOnError 1 -AutoConnect 1 - 解析输出和返回码，返回结构化结果
- 成功执行后，将确认过的 device/interface/speed 写回
.embeddedskills/config.json
脚本调用
skill 目录下有四个 Python 脚本，使用标准库实现，无额外依赖。
jlink_exec.py — 基础操作 + 轻量调试
bash# 探测连通性 python <skill-dir>/scripts/jlink_exec.py info --device GD32F470ZG --json # 烧录固件 python <skill-dir>/scripts/jlink_exec.py flash --file build/app.hex --device GD32F470ZG --json # 烧录 .bin（必须提供地址） python <skill-dir>/scripts/jlink_exec.py flash --file build/app.bin --device GD32F470ZG --address 0x08000000 --json # 读取内存 python <skill-dir>/scripts/jlink_exec.py read-mem --address 0x08000000 --length 256 --device GD32F470ZG --json # 写入内存 python <skill-dir>/scripts/jlink_exec.py write-mem --address 0x20000000 --value 0x12345678 --device GD32F470ZG --json # 查看寄存器 python <skill-dir>/scripts/jlink_exec.py regs --device GD32F470ZG --json # 复位目标 python <skill-dir>/scripts/jlink_exec.py reset --device GD32F470ZG --json # 暂停 CPU python <skill-dir>/scripts/jlink_exec.py halt --device GD32F470ZG --json # 恢复运行 python <skill-dir>/scripts/jlink_exec.py go --device GD32F470ZG --json # 单步执行（3 步） python <skill-dir>/scripts/jlink_exec.py step --device GD32F470ZG --count 3 --json # 运行到断点地址 python <skill-dir>/scripts/jlink_exec.py run-to --device GD32F470ZG --address 0x08001234 --timeout-ms 3000 --json
通用可选参数：--interface SWD|JTAG、--speed 4000、--serial-no <序列号>、--exe <JLink.exe路径>
jlink_rtt.py — RTT 日志读取
bashpython <skill-dir>/scripts/jlink_rtt.py --device GD32F470ZG --json
可选参数：--serial-no、--channel、--encoding、--rtt-port、--gdbserver-exe <路径>、--rtt-exe <路径>
RTT 工作原理：脚本先通过 JLinkGDBServerCL.exe 建立调试连接，再启动 JLinkRTTClient.exe 读取 RTT 数据。--json 模式输出 JSON Lines。
jlink_swo.py — SWO 事件流包装
bash# 使用 config.json 里的 swo_command python <skill-dir>/scripts/jlink_swo.py --json # 或显式传入 viewer 命令 python <skill-dir>/scripts/jlink_swo.py \ --viewer-cmd JLinkSWOViewerCL.exe -device GD32F470ZG -itf SWD -speed 4000 \ --json
jlink_swo.py 不直接实现 SWO 协议，而是把外部 viewer 的 stdout/stderr 统一包装成 JSON Lines，便于上层 workflow 或 AI 继续消费。
jlink_gdb.py — GDB 源码级调试（需要 arm-none-eabi-gdb）
bash# 执行自定义 GDB 命令序列 python <skill-dir>/scripts/jlink_gdb.py run \ --gdbserver-exe <路径> --gdb-exe <arm-none-eabi-gdb路径> \ --device GD32F470ZG --elf build/app.elf \ --commands "break main" "continue" "backtrace" "info locals" --json # 快捷：获取调用栈 python <skill-dir>/scripts/jlink_gdb.py backtrace \ --gdbserver-exe <路径> --gdb-exe <路径> \ --device GD32F470ZG --elf build/app.elf --json # 快捷：查看局部变量 python <skill-dir>/scripts/jlink_gdb.py locals \ --gdbserver-exe <路径> --gdb-exe <路径> \ --device GD32F470ZG --elf build/app.elf --json
GDB 调试需要 ELF 文件才能进行源码级调试（断点到函数名、查看变量）。没有 ELF 时仍可使用地址级调试。
输出格式
所有脚本以 JSON 格式返回，基础字段为 status（ok/error）、action、summary、details，并可能附带 context、artifacts、metrics、state、next_actions、timing。流式观测命令使用 JSON Lines，并统一输出 source、channel_type、stream_type。
成功示例：
json{ "status": "ok", "action": "halt", "summary": "已暂停，PC=0x08049ABC", "details": { "device": "GD32F470ZG", "registers": { "PC": "0x08049ABC", "R0": "0x00000004", "..." : "..." } } }
step 示例（包含执行的指令）：
json{ "status": "ok", "action": "step", "summary": "单步3次，PC=0x08049AB4", "details": { "steps": [ { "address": "0x08049AB8", "opcode": "80 1B", "instruction": "SUBS R0, R0, R6" }, { "address": "0x08049ABA", "opcode": "A8 42", "instruction": "CMP R0, R5" }, { "address": "0x08049ABC", "opcode": "FA D3", "instruction": "BCC #-0x0C" } ], "registers": { "PC": "0x08049AB4", "..." : "..." } } }
run-to 示例（断点命中）：
json{ "status": "ok", "action": "run-to", "summary": "断点命中 @ 0x08049AB4，PC=0x08049AB4", "details": { "bp_address": "0x08049AB4", "bp_hit": true, "registers": { "PC": "0x08049AB4", "..." : "..." } } }
核心规则
- 不自动猜测
device芯片型号，缺失时必须询问用户 - 多探针场景不自动选择探针，必须让用户指定序列号
- 参数解析优先级为：CLI 显式参数 >
.embeddedskills/config.json（工程级）>skill/config.json（环境级）>.embeddedskills/state.json> 默认值/报错 .bin文件必须显式提供烧录地址，缺失时报错- 连接失败时给出排查建议（检查连线、供电、接口类型、速度），不自动尝试更激进参数
- 烧录、写内存、复位在参数完整且用户意图明确时直接执行
run-to的断点在单次 JLink 会话内完成设置和清除，不存在跨会话 handle 问题- 结果回显中始终包含目标芯片、接口类型和执行动作
- 产物路径（elf/file）不进入工程配置，仍只依赖
state.json last_flash/last_debug等运行状态继续写入state.json
调试典型工作流
快速排查（JLink Commander）
halt → regs → read-mem → step → go
适合查看当前执行位置、寄存器状态、内存值，无需 ELF 和 GDB。
断点调试（JLink Commander）
run-to(address) → regs → read-mem → go
在指定地址设置断点并等待命中，查看此时的状态。
源码级调试（GDB）
gdb run --elf app.elf --commands "break main" "continue" "backtrace" "info locals"
需要 ELF 文件和 arm-none-eabi-gdb，支持函数名断点和变量查看。
参考
遇到芯片型号问题时可查阅 references/common_devices.md。
