TaoCosmo-Dev/STM32_AutoDebug_Universal_Kit

面向 AI 代理的 STM32 闭环开发工具链：编译、烧录、实机验证、崩溃归因，全部以命令行驱动，结果以退出码交付。

• 解决的问题
• 工作示例
• 实现原理
• 能力边界
• 环境要求
• 安装
• 接入工程
• 模板工程
• 仓库文件说明
• 退出码契约
• 固件侧前提
• 进阶参考
• 常见问题

AI 编写嵌入式代码的主要障碍不在语法生成，而在缺乏执行反馈。

模型无法获知 Keil 的报错位置，无法确认固件是否在目标芯片上实际运行，也无法在发生 HardFault 时得知程序计数器的停留位置。缺少判据，模型只能反复试探，每次修改后都需要开发者手动编译、烧录、观察串口，再将结果转述回去。

本工具链补全这条反馈回路。部署后，AI 代理可自主完成：

判定标准为硬性证据：编译 0 Error、烧录成功、实机串口输出通过令牌，三者同时成立方视为通过。

代理先确认硬件参数，再输出接线表：

输入：需要读取 DHT11 温湿度，通过串口打印，LED 每秒闪烁一次。

代理：请确认以下参数 —— 外部晶振为 8MHz 还是 12MHz？DHT11 数据线连接哪个 GPIO？板载 LED 的引脚编号及点亮电平？

……（参数确认后）……

代理：请按下表接线，完成后告知。

DHT11	开发板
VCC	3V3（注意：不可接 5V）
GND	GND
DATA	PA1（需 4.7kΩ 上拉）

接线确认后，后续流程全自动执行：

>>> [第 1 轮] 步骤 1/4  正在用 Keil 编译 ...
[+] 编译通过  0 Error，0 Warning，耗时 12.3s

>>> [第 1 轮] 步骤 2/4  正在烧录到板子（烧完先让 CPU 停住不跑）...
[+] 烧录成功（下载器 0670FF...，芯片 stm32f103c8），CPU 已停在复位入口等待放行。

>>> [第 1 轮] 步骤 3/4  先打开串口监听，再放 CPU 运行 ...
[+] 已监听串口 COM6 @ 115200
  [MCU] system clock 72MHz ready
  [MCU] temp = 26.4 C  humi = 48%
  [MCU] [ALL TESTS PASSED]

>>> [第 1 轮] 步骤 4/4  判定结果并分析根本原因 ...
[+] 实机测试通过！（收到通过信号：[ALL TESTS PASSED]）

运行时崩溃不止于"程序跑飞"的模糊结论，而是定位到具体源码行：

[-] 板子崩溃了（固件通过串口自报了故障现场）
    根本原因：空指针解引用（NULL Pointer Dereference）：程序访问了 NULL 或接近 0 的地址 0x00000004。
[!] 诊断报告已写入：MDK-ARM\diagnostic_report.json

崩溃点: ../User/dht11.c:88（函数 DHT11_Read）
     86 |     /* dev 未判空 */
>>>  88 |     dev->port->BSRR = dev->pin;

本节说明工具链的工作机制。理解这部分有助于在出现异常时定位问题所在环节。

开发主机与目标芯片之间通过三条彼此独立的通道连接：

SWD 与串口的区别贯穿整个设计：串口依赖固件主动发送数据，固件停止工作即无数据可读；SWD 由主机主动发起访问，即使内核已停止运行仍可读取芯片状态。

Keil 的 UV4.exe 支持命令行调用。工具链以此方式在后台编译，不触发图形界面，因此 Keil 安装完成后无需再启动其 IDE。

编译结束后，Keil 将过程写入日志文件。工具链解析该日志，将错误信息转换为结构化字段：

..\User\dht11.c(88): error:  #20: identifier "dev" is undefined
   ↓
文件 = dht11.c   行号 = 88   错误码 = #20   描述 = identifier "dev" is undefined

代理接收到的是「文件 + 行号 + 原因」而非原始日志文本，因此可直接定位到需要修改的位置。

编译产物 .axf 文件是后续崩溃定位的依据。

ARM Cortex-M 芯片内部集成了一块独立于 CPU 内核的调试电路。该电路拥有独立的供电与时钟，通过 SWDIO / SWCLK 两根信号线对外，可访问芯片的任意存储地址与全部内核寄存器，并可控制内核暂停或继续执行。

该电路的运行不依赖 CPU 内核是否正常。内核进入异常、死循环或完全停止后，调试电路仍可正常响应主机请求。这是崩溃归因功能得以成立的硬件基础。

烧录过程即通过 SWD 完成：暂停内核 → 向 Flash 写入机器码 → 复位。

芯片复位后数十毫秒内即完成启动信息的输出，而主机打开串口需要经历设备枚举与参数配置，耗时更长。

若执行顺序为「烧录 → 释放内核 → 打开串口」，启动阶段的输出将在串口就绪前完成，通过令牌无法被捕获。表现为固件逻辑正确但闭环始终超时。

正确顺序为：

烧录 → 保持内核暂停 → 打开串口监听 → 释放内核 → 捕获输出

引擎源码的首行注释即为此设计的说明：Ordering is the whole trick.

第一阶段：读取故障现场

Cortex-M 内核在进入异常时由硬件自动将现场压栈，其中程序计数器 PC 记录了异常发生时正在执行的指令地址。同时，以下故障状态寄存器记录异常原因：

工具链通过 SWD 读取上述寄存器。此时内核已停止运行，但调试电路仍然可用。

BFAR 仅在 CFSR 声明其有效时采信。无效时报告明确记录"故障地址无效"，不作推测。

第二阶段：地址到源码行的转换

编译器在生成机器码的同时，将地址与源码位置的对照表（DWARF 调试信息）写入 .axf 文件：

0x08001A3C ~ 0x08001A48  ←→  dht11.c 第 88 行，函数 DHT11_Read
0x08001A48 ~ 0x08001A50  ←→  dht11.c 第 89 行

工具链解析 .axf 读取该表，以二分查找定位 PC 所属区间，并提取对应源码片段写入诊断报告。

因此工具链在每次编译前强制启用工程的调试信息输出选项。该选项关闭时编译器不生成对照表，崩溃信息将只剩地址数值。

备用通道：工具链可向固件植入 cm_backtrace_lite 模块，由芯片在异常发生时通过串口主动输出故障现场。两条通道互为备份。

异常处理流程中不可使用 printf 或 HAL_UART_Transmit。二者的超时判定依赖 SysTick，而 HardFault 的异常优先级高于 SysTick，导致其无法进入中断、计数器不再递增，最终在输出首字节前进入死等。工具链生成的输出函数采用轮询方式直接操作串口寄存器。

退出码作为唯一判据。 脚本返回整数而非文本结论。文本需要语义理解，存在误判空间；退出码不存在歧义。

失败指纹用于识别停滞。 每次失败生成一个指纹（编译错误为 文件:行号:错误码:描述，运行时异常为 故障类型|PC|CFSR）。同一指纹在窗口期内重复出现，表明上一次修改未产生实际效果，此时应更换排查方向；持续重复则终止自动修复，转交人工判断。

• 自动修复编译错误，附带文件名与行号
• 自动定位运行时崩溃至源码行，并给出根本原因分类
• 自动判定固件是否实际通过测试（需串口）
• 自动修改 Keil 工程结构：添加源文件、包含路径、预处理宏、崩溃追踪器，全程无需启动 uVision
• 识别修复停滞并主动终止，交由人工判断

可完成错误排查，但无法完成验收。

需要特别说明的是，多数缺陷既非编译错误亦非运行时崩溃：帧解析偏移、时钟配置错误导致延时失准、I2C 从机地址错误、状态机分支遗漏等，程序均可正常运行，仅执行结果不符合预期。缺少串口时，代理对这一类问题完全不可见，且会因持续判定为失败而继续修改本已正确的代码。

串口连接仅需三根线（TX / RX / GND），多数开发板的 ST-Link 已集成虚拟串口，或板载 CH340 等 USB-UART 芯片。建议接入。

v2.3.2 起默认不再预装器件包。 此前脚本会一次性下载 10 个 STM32 系列的器件包（合计约 250 MB），是首次安装耗时的主要来源，而其中绝大多数用户并不会用到。pyOCD 在首次烧录时会自动下载目标芯片对应的包，因此预装并非必要。

如需一次性装齐以便离线使用，执行 setup_env.bat --with-packs。

git clone https://github.com/TaoCosmo-Dev/STM32_AutoDebug_Universal_Kit.git
cd STM32_AutoDebug_Universal_Kit

双击 setup_env.bat，或执行 powershell -ExecutionPolicy Bypass -File setup_env.ps1。

脚本依次执行：检测 Python、安装依赖、跳过器件包预装、环境自检、安装 Agent Skill。

[4/5] 自检：工具链 / 探针 / 串口 / 离线单元测试

  Keil UV4   : C:\Keil_v5\UV4\UV4.exe
下载器（调试探针）：
  - STM32 STLink  [050051000E00004D43504D4E]
串口：
  - COM6 - USB-SERIAL CH340 (COM6)

[5/5] 安装 Agent Skill（让 AI 在任意工程里自动加载本套件）
  [*] 已安装  C:\Users\you\.agents\skills     共享约定（Cursor / Codex CLI / Gemini CLI）
  [*] 已链接  C:\Users\you\.claude\skills     Claude Code / Claude Desktop

上述三项均有输出即表示环境就绪。NOT FOUND、探针为空、串口为空分别对应 Keil 未安装、调试器未连接或被占用、缺少 USB-UART 驱动。

无需修改配置文件。 Keil 安装路径、调试器型号、串口号均自动识别；配置中的固定路径在本机不存在时会自动回退至探测结果。

setup_env 执行完毕即已生效，无需额外操作。用 AI 编辑器打开任意 Keil 工程，直接描述需求：

我要实现：<用自然语言描述功能>

代理将自动加载规范，缺少会影响正确性的硬件参数时先向你确认，然后编码并执行闭环。

工作机制：setup_env 最后安装的 Skill 即为入口。SKILL.md 是开放标准，Claude Code、Cursor、Codex CLI、Gemini CLI、Cline、Windsurf、Copilot、Zed 等均可读取，一次安装覆盖全部工具链。

引擎无需置于工程目录内：其全部路径均自 --project 参数推导，诊断报告、状态目录、崩溃追踪器均生成于目标工程中，工具链目录不受影响。

适用于两种情形：需将工具链随工程一并提交版本库，供协作者直接使用；或所用编辑器尚不支持 Agent Skill。

将工程文件夹拖放至 inject_to_project.bat：

  [+] AGENTS.md（AI 规范）
  [+] run_autodebug.py
  [+] autodebug/ 引擎
  [+] autodebug.config.yaml（本工程配置）
  [+] mcu_support/cm_backtrace_lite.c
  找到 Keil 工程：MDK-ARM\Demo.uvprojx

此方式下需在对话开始时指示代理读取规范：

读一下 AGENTS.md，按里面的规范来。
我要实现：<用自然语言描述功能>

手头没有现成工程时，可以下载 STM32F103C8T6 的模板，解压后直接进入闭环。两个版本的硬件配置相同，只是所用的库不同：

HAL 版的 NVIC 配置中取消了四个故障中断的「Generate IRQ handler」，因此在 CubeMX 里改完外设重新生成代码后，崩溃追踪器、工程设置和 USER CODE 区块内的代码都不会丢失（已实测）。v1.1 起还带全部 HAL 驱动，配合 --enable-hal 在没装 CubeMX 的电脑上也能直接启用新外设。

只插一根 USB 线、用板载 ST-Link 的虚拟串口时，先确认开发板把它接到了 MCU 的哪个 USART。独立的最小系统板通常没有这条线：串口打得开，却一个字节都收不到。

也可以让代理自行下载（Windows 10 及以上自带 curl.exe）：

curl.exe -L -o template.zip https://github.com/TaoCosmo-Dev/STM32_AutoDebug_Universal_Kit/releases/download/template-f103c8-hal-v1.1/STM32F103C8_HAL_Template.zip
python -m zipfile -e template.zip .

解压用 python -m zipfile，任何终端都能用；Git Bash 里的 tar 是 GNU tar，不认 zip。

模板以 Release 附件的形式发布，没有放进仓库代码：标准库版中的 ST 标准库使用 SLA0044 许可证，不能并入本仓库的 MIT 许可范围；HAL 版体积较大，也保持一致。压缩包内附各部分的许可证原文。

日常使用涉及的文件仅 setup_env.bat 与 AGENTS.md 两个，其余由代理调用或供查阅。

更新工具链或变更其存放位置后须重新执行 setup_env.bat。 Skill 以文件副本形式分发至各编辑器目录，源文件变更不会自动同步至副本。启用 Windows 开发者模式后，安装脚本将改用符号链接，此后无需手动同步。

python run_autodebug.py --project MDK-ARM/App.uvprojx              # 完整闭环
python run_autodebug.py --project MDK-ARM/App.uvprojx --no-flash   # 仅编译，不访问硬件
python run_autodebug.py --project MDK-ARM/App.uvprojx --json       # 机器可读输出
python run_autodebug.py --project MDK-ARM/App.uvprojx --check-firmware   # 固件契约自检
python run_autodebug.py --project MDK-ARM/App.uvprojx --add-source User/new.c
python run_autodebug.py --project MDK-ARM/App.uvprojx --enable-hal adc i2c   # HAL 工程启用新外设
python run_autodebug.py --project MDK-ARM/App.uvprojx --install-tracer --uart USART1
python run_autodebug.py --list-devices                             # 列出调试探针与串口

脚本的退出码即为结论，不依据日志文本判断。

结构化诊断写入 .uvprojx 所在目录的 diagnostic_report.json，历史与状态在同目录的 .autodebug/（CubeMX 工程中即 MDK-ARM/）。失败时两个路径都会打印在日志中。

测试通过后还有一道时基自检。 通过令牌只能说明测试跑完了，不能说明时间是对的：FreeRTOS 里多定义一行 configSYSTICK_CLOCK_HZ，SysTick 就会慢 8 倍，所有延时都被拉长，固件却照样打印通过令牌。因此闭环在收到令牌后，会经 SWD 读两次 uwTick（HAL）与 xTickCount（FreeRTOS），与电脑时钟对比；偏差超过 5% 即判 TIMEBASE_SKEW，并在报告中附上 SysTick 寄存器现场。读内存不会暂停内核，整个过程约 0.5 秒，可用 loop.timebase_check: false 关闭。

多数"运行无响应"的情形并非业务逻辑错误，而是固件未产生可判定的输出。工程配置由代理通过命令完成，但以下两项需在源码中显式实现：

1. 通过令牌：在测试通过路径上输出 [ALL TESTS PASSED]。未输出该令牌时闭环无法判定成功。
2. cm_backtrace_init()：在 main() 的外设初始化之前调用，以启用子异常分类与除零陷阱。

此外，--check-firmware 会扫描源码中含非 ASCII 字符的字符串字面量。Keil AC5（armcc）按本机代码页解析源文件（中文 Windows 上为 GBK），UTF-8 中文串会报 #8: missing closing quote —— 该报错指向引号而非编码，极易把排查引向语法方向。中文应只出现在注释中。

执行 --check-firmware 将逐项列出未满足的条件。闭环超时时亦会自动附加该清单，并置于诊断报告 next_actions 的首位。

python run_autodebug.py --project MDK-ARM/App.uvprojx --install-tracer --uart USART1

[tracer] 已拷入 mcu_support/: cm_backtrace_lite.c, cm_backtrace_lite.h
[tracer] 已生成 cm_backtrace_port.c（USART1，SR/DR 寄存器组）
[tracer] 已加入工程组 AutoDebug [App]: cm_backtrace_lite.c, cm_backtrace_port.c
[tracer] 已加入包含路径 [App]: ..\mcu_support
[tracer] 已开启调试信息 [App]
[tracer] 已注释 stm32f1xx_it.c 中的空处理函数: HardFault_Handler

python -m unittest discover -s tests     # 169 项离线自测，无需硬件

每次 push 与 Pull Request 由 GitHub Actions 在 Windows + Python 3.10 / 3.12 环境下自动执行，并校验版本号三处一致性与测试数量徽章。

MIT。个人与商业用途均可免费使用、修改、分发。

问题反馈请提交 Issue。