v2.4.0 — 补上「进入闭环之前」的短板

来自首位外部用户在另一台电脑上的实战复盘：从零点亮 F103C8T6 + OLED 共约 27 分钟，其中 Keil 真正编译约 1 分钟。闭环引擎本身零故障，时间全部消耗在进入闭环之前 —— 而其中多数故障在动手前就能确定，却都指向了错误的方向。

🐛 修复

AC5 源码编码陷阱（约占本次 27% 的时间）

armcc 按本机代码页解析源文件（中文 Windows 上是 GBK），UTF-8 中文字面量会报：

main.c(42): error:  #8: missing closing quote

报错指向引号而非编码，会把排查引向语法方向，怎么查都查不出来。

• 写入 AGENTS.md 嵌入式黄金准则第 8 条
• --check-firmware 扫描字符串字面量，点名文件与行号
• 注释不检查：注释不参与字面量解析，误报会让这项检查在有中文注释的工程里无法使用

preflight 提前拦截确定性故障

未插调试器、缺 CMSIS 器件包，此前都要等到编译成功之后才以 pyOCD 异常的形式出现。

• 现在提前检查，且仅在调用方声明将访问硬件时执行 —— --no-flash 只编译，不该要求插探针
• 提示直接给出可复制的命令，例如 python -m pyocd pack install stm32f103c8，而非仅描述问题

<Target> 匹配截断导致调试信息开关静默失效

复盘报告称 project_editor.py 已修好、builder.py 是未同步的旧实现。逐行核查发现报告所说的修复函数并不存在 —— 两处都是同一份朴素正则 <Target>.*?</Target>。

uVision 在 <TargetOption><DebugOption> 内还嵌套了一个 <Target> 元素。实测该结构下：

	旧实现	新实现
App 目标块长度	232 字节（被截断）	330 字节
含 <CreateExecutable>	❌	✅

<CreateExecutable> 正是 ensure_debug_information 插入调试信息开关的锚点。锚点落在块外 → 修改静默失效 → 编译产物不含 DWARF → 崩溃无法定位到源码行。

改为按深度计数的单一实现 iter_target_spans()，两处共用，不会再漂移。

其它

• install_skill.py 补 .workbuddy —— 此前 WorkBuddy 用户安装显示成功，但 skill 从未被加载
• 构建管道补 encoding="utf-8", errors="replace" —— text=True 单独使用时按本机 ANSI 代码页解码，UV4 输出一个非 GBK 字节即抛 UnicodeDecodeError 中断构建
• CM_BACKTRACE_PROVIDE_HANDLER 补注释 —— == 1 表示由本文件定义 HardFault_Handler，与字面理解相反

🧪 测试

新增 tests/test_onboarding_fixes.py（18 项），离线自测 96 → 114。

⏳ 未完成：模板工程

复盘报告将「提供最小可编译模板工程」列为第一优先，这一判断成立。但它需要真实的 CMSIS Core 与标准外设库文件才有意义 —— 凭空构造一个，正是 v2.3.0 移除 --create-project 的原因：看起来正确、实际编译不过的脚手架。留待取得可用工程文件后单独处理。

---

Full Changelog: v2.3.3...v2.4.0