本 skill 提供 J-Link 探针的设备探测、固件烧录、内存读写、寄存器查看、目标复位、RTT 日志读取，以及轻量在线调试和 GDB 源码级调试能力。
配置
环境级配置（skill/config.json）：包含工具路径、端口号等，首次使用前需确认 exe 路径正确。字段包括 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 命令数组）、operation_mode（1 直接执行 / 2 输出风险摘要但不阻塞 / 3 执行前确认）。
工程级配置（.embeddedskills/config.json）：设备参数统一在此管理，jlink 下含 device（芯片型号，如 STM32F407VG、GD32F470ZG）、interface（调试接口 SWD 或 JTAG，默认 SWD）、speed（调试速率 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（查看调用栈和局部变量）、gdb break/continue/next/step/finish/until（one-shot 控制执行流）、gdb frame/print/watch/disassemble/threads/crash-report（one-shot 源码级诊断），依赖 arm-none-eabi-gdb。
执行流程
读取 skill/config.json 确认 exe 路径有效；读取 .embeddedskills/config.json 获取工程级配置；读取 .embeddedskills/state.json 获取历史状态；按优先级解析参数；若当前动作需要 device 且仍为空，直接要求用户补充，绝不猜测；多探针场景未指定 serial_no 时列出探针让用户选择；按 operation_mode 决定是否需要确认后执行；使用模板生成临时 .jlink 命令文件，调用 JLink.exe 时带 -NoGui 1 -ExitOnError 1 -AutoConnect 1；解析输出和返回码返回结构化结果；成功后写回确认配置。
脚本调用
jlink_exec.py：基础操作 + 轻量调试。示例：python <skill-dir>/scripts/jlink_exec.py info --device GD32F470ZG --json；flash --file build/app.hex；flash .bin 时必须提供 --address（如 0x08000000）；read-mem --address 0x08000000 --length 256；write-mem --address 0x20000000 --value 0x12345678；regs；reset；halt；go；step --count 3；run-to --address 0x08001234 --timeout-ms 3000。通用可选参数：--interface SWD|JTAG、--speed 4000、--serial-no、--exe。
jlink_rtt.py：读取 RTT 日志。示例：python <skill-dir>/scripts/jlink_rtt.py --device GD32F470ZG --json。可选参数：--serial-no、--channel、--encoding、--rtt-port、--gdbserver-exe、--rtt-exe。工作原理为先通过 JLinkGDBServerCL.exe 建立调试连接，再启动 JLinkRTTClient.exe 读取 RTT 数据，--json 模式输出 JSON Lines。
jlink_swo.py：包装外部 SWO viewer 为统一事件流。可使用 config.json 里的 swo_command，或显式传入 viewer 命令。它不直接实现 SWO 协议，而是把外部 viewer 的 stdout/stderr 统一包装成 JSON Lines。
jlink_gdb.py：GDB 源码级调试（需 arm-none-eabi-gdb）。支持自定义 GDB 命令序列，以及 backtrace、locals 等快捷命令。GDB 调试需要 ELF 文件才能进行源码级调试（断点到函数名、查看变量），没有 ELF 时仍可使用地址级调试。
输出格式
所有脚本以 JSON 格式返回，基础字段为 status（ok/error）、action、summary、details，并可能附带 context、artifacts、metrics、state、next_actions、timing。流式观测命令使用 JSON Lines，并统一输出 source、channel_type、stream_type。
核心规则
不自动猜测 device 芯片型号，缺失时必须询问用户；多探针场景不自动选择探针，必须让用户指定序列号；.bin 文件必须显式提供烧录地址，缺失时报错；连接失败时给出排查建议（检查连线、供电、接口类型、速度），不自动尝试更激进参数；烧录、写内存、复位在参数完整且用户意图明确时直接执行；run-to 的断点在单次 JLink 会话内完成设置和清除；结果回显中始终包含目标芯片、接口类型和执行动作；产物路径不进入工程配置，仍只依赖 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。