wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

docs(build): @build 统一为 keil-build skill，build.bat 降为等价原生入口

Browse Source 
- AGENTS.md 构建条：@build = keil-build skill（写明 UV4 解析链、退出码
  0/1/2/3、日志路径）；MDK-ARM/build.bat 明确为等价原生入口，并列出
  它相对 skill 缺的三项（无超时保护 / UV4 只认 DTU_KEIL_UV4 / 失败 dump 整份日志）
- keil-build SKILL.md「本仓库」段同步：skill 即 @build 口径
- 3 个 skill（new-source-file / ui-verify / new-machine-setup）与 8 篇
  docs、README、MDK-ARM/README、环境与部署 3 篇：命令示例与 @build
  标识统一改指 skill
- scripts/stack_report.py 的构建提示串改指 skill
- 环境与部署：DTU_KEIL_UV4 使用方补 keil_build.py；反向测试期望的报错
  文案对齐 skill 实际输出（BUILD_ENV_ERROR: ... is set but not a file）
- 刻意未改：docs/问题记录/项目审查与优化建议报告.md 的 P2-14/N-18
  历史审计条目（属史实记录）；test/run_all_suites.py 的 BUILD_BAT
  常量（是代码、非文档，改动需另做验证）
This commit is contained in:
Wanderingss
2026-10-10 16:19:14 +08:00
parent 43c958cac1
commit 7a54fdbc73
23 changed files with 44 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/UI设计/UI_中文字体生成与配置.md
+1 -1
View File
@@ -140,7 +140,7 @@ OK 43614 bytes -> ...\Drivers\BSP\UI\ui_font_cn_12.c
## 6. 编译验证
```bash
@build # 即 MDK-ARM\build.bat，调用 UV4 全量重建
@build # = keil-build skill（.dsh/skills/keil-build/scripts/keil_build.py），调用 UV4 全量重建
```
要求：`0 Error(s), 0 Warning(s)`。重新生成/修改字体或 `lv_conf.h` 后务必重建验证。当前已验证通过，`ui_font_cn_12.c` 正常编入。
docs/UI设计/UI_自动化测试流程.md
+2 -2
View File
@@ -19,7 +19,7 @@
cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警告）
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 1) 菜单 8 状态像素回归 + 池基线门禁
.venv\Scripts\python.exe simulator/tests/check_content_pages.py # 2) 内容页黄金参考回归 + 往返池门禁
& "MDK-ARM\build.bat" # 3) Keil 构建（BUILD_OK，0 错 0 警）
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 3) Keil 构建（BUILD_OK，0 错 0 警）
.venv\Scripts\python.exe scripts/check_coding_standard.py # 4) 代码规范机械检查（PASS）
```
@@ -27,7 +27,7 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|---|---|---|---|
| 1 | `simulator/tests/check_menu_rows.py` | 菜单 8 状态：选中行白带 / 非选行黑底白字 / 框体 1px 边框 / 往返像素一致（S3==S1、S6==S1、S7==S2）+ S0 池基线 | `PASS: 8 状态全部断言通过（8 图，池基线 4784 B）` |
| 2 | `simulator/tests/check_content_pages.py` | ① 文本级断言（字形模板匹配，50 条，独立于 `ref/`）→ ② 11 页截图与 `ref/` 黄金参考**逐字节**比对 + 开页-关页往返池水位 | `PASS: 11 内容页 + 往返池水位全部通过`（文本断言先于像素比对，失败即中止） |
| 3 | `MDK-ARM\build.bat` | MCU 端编译（UI 源码双端共用，改一端必须过另一端） | 退出码 0 = BUILD_OK |
| 3 | `keil-build` skill（`keil_build.py`） | MCU 端编译（UI 源码双端共用，改一端必须过另一端） | 退出码 0 = BUILD_OK |
| 4 | `scripts/check_coding_standard.py` | 代码规范 V1.0 机械检查 | PASS |
> **文本级断言层**（2026-09-10 新增）：`check_content_pages.py` 内置字形模板匹配——直接解析
docs/产品需求/产品需求设计文档.md
+1 -1
View File
@@ -645,7 +645,7 @@ mac=00:00:00:00:00:00
```powershell
# 构建（@build）：0 错 0 警
& "MDK-ARM\build.bat" # 退出码 0=PASS / 1=构建失败 / 2=环境错误
& '.venv\Scripts\python.exe' .dsh/skills/keil-build/scripts/keil_build.py # 退出码 0=PASS / 1=构建失败 / 2=环境错误
# 自动化测试（@test）：串口采集 → 烧录 → 日志校验
& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py # 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法错误
# 全库门禁
docs/子系统设计/ADC采样节拍设计说明.md
+1 -1
View File
@@ -175,7 +175,7 @@ t=1000 µs 下一个 TIM6 更新事件
| # | 判据 | 手段 |
|---|---|---|
| 1 | `@build` 0 错 0 警，且镜像无源文件新于 hex | `MDK-ARM/build.bat` + `find -newermt` |
| 1 | `@build` 0 错 0 警，且镜像无源文件新于 hex | `keil-build` skill（`keil_build.py`）+ `find -newermt` |
| 2 | PC9 `CONVST` 周期 = 1.000 kHz（±0.1%） | 示波器 / 逻辑分析仪 |
| 3 | PC7 `BUSY` 每周期一个脉冲，与 CONVST 相位固定 | 示波器双通道 |
| 4 | `frame_seq()` 每秒 +1000（每 10 s +10000），严格递增 | `@test` 串口 `[ADC_TASK] frames=... seq=...` |
docs/架构设计/项目架构总览.md
+1 -1
View File
@@ -297,7 +297,7 @@ flowchart LR
| 目标 | 工具链 | 验证 |
|---|---|---|
| MCU 固件 | Keil MDK-ARM v5（`MDK-ARM/build.bat`） | `@build` 0 错 0 警 → `@test` 串口闭环 |
| MCU 固件 | Keil MDK-ARM v5（`@build` = `keil-build` skill；原生入口 `MDK-ARM/build.bat` 等价） | `@build` 0 错 0 警 → `@test` 串口闭环 |
| PC 模拟器 | CMake + SDL2 + MSVC（`simulator/build/`） | `check_menu_rows.py` + `check_content_pages.py`（文本断言 + 像素黄金参考） |
**功能编译开关**：`App/app/app_cfg.h`（网络/ADC/RS485）；`test/board/test_config.h` 测试套件互斥选择（产品构建全注释）。
docs/测试说明/FTP_Test_Guide.md
+1 -1
View File
@@ -37,7 +37,7 @@
## 3. 编译与运行（固件侧）
- **默认构建即可提供 FTP Server**，无需切换测试套件。
- 任何改动后必须执行 `@build`（即 `MDK-ARM/build.bat`），确认 **0 Error(s) 0 Warning(s)** 再烧录（遵循 AGENTS.md 铁律）。
- 任何改动后必须执行 `@build`（即 `keil-build` skill：`.dsh/skills/keil-build/scripts/keil_build.py`），确认 **0 Error(s) 0 Warning(s)** 再烧录（遵循 AGENTS.md 铁律）。
- 若需跑**自动化 FTP 文件传输用例**：在 `test/board/test_config.h` 选择 `TEST_SUITE_CH395F`，并在 `test/board/ch395f_test.h` 打开 `ENABLE_PHASE8_TESTS`（文件传输阶段），重新编译烧录。
- 烧录后打开串口（115200bps）观察：
- `net_init` 完成、PHY link up；
docs/测试说明/SD2506_Test_Guide.md
+2 -2
View File
@@ -40,8 +40,8 @@
编译（要求 0 错误 0 警告）：
```bat
MDK-ARM\build.bat
```powershell
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
```
烧录后在串口（USART1, 115200bps）观察 `[RTC_TEST]` 日志。
docs/测试说明/m2_data/README.md
+2 -2
View File
@@ -10,7 +10,7 @@
| 日期 | 2026-09-22（设备 RTC 显示 2026-09-21，落后 1 天，仅显示差异；主机时间戳 = 设备 + 4s） |
| 台架 | COM6 @115200；目标 192.168.1.100:8080（Phase 13 独占 socket 2） |
| 固件 | `test/board/test_config.h` = `TEST_SUITE_CH395F`；`test/board/ch395f_test.h` = `ENABLE_PHASE13_TESTS`（仅此一项） |
| 构建 | `MDK-ARM\build.bat` → **0 错误 0 警告**（测试构建与产品构建均 0/0） |
| 构建 | `keil-build` skill（`keil_build.py`）→ **0 错误 0 警告**（测试构建与产品构建均 0/0） |
| 对端 | `.venv\Scripts\python.exe test\latency_peer.py --mode net`（纯标准库，`--wait 170`） |
| 会话顺序 | HELLO → L5_RECV → L5_SEND → L3 → L10 → L6 → L7 → DONE |
| 干扰 | 无（安静档，`ftp_stress=0`；未跑 `--ftp-stress`） |
@@ -19,7 +19,7 @@
复现命令（顺序不可反：先 `clear` 再起 peer，最后烧录）：
```powershell
& "MDK-ARM\build.bat"
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py clear
& '.venv\Scripts\python.exe' test\latency_peer.py --host 192.168.1.100 --port 8080 `
--json "docs\测试说明\m2_data\m2_quiet_runNN.json" --wait 170 # 后台作业
docs/测试说明/实机测试实施指南.md
+2 -2
View File
@@ -43,7 +43,7 @@
| # | 检查 | 命令 | 通过判据 |
|---|---|---|---|
| A1 | 工作区干净 | `git status --short` | 无输出（或有明确待提交项） |
| A2 | 产品构建 0/0 | `& "MDK-ARM\build.bat"` | 末行 `BUILD_OK: 0 errors, 0 warnings` |
| A2 | 产品构建 0/0 | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` | 末行 `BUILD_OK: 0 errors, 0 warnings` |
| A3 | 构建产物为**产品态** | 检查 `test/board/test_config.h` L30-33 | 四个 `TEST_SUITE_*` **全部注释** |
| A4 | `.map` 非测试态 | 看 `MDK-ARM/STM32F407-Demo/STM32F407-Demo.map` 的 `ER_IROM1` | 产品态基线随已接受的修复增长：262,100（初版）→ 262,836 B（10-02 round 1~6）→ 264,284 B（round 7~9）→ **264,936 B（当前，含 A2/A3/A4 补码）**；明显阶跃 ≈3.7KB 及以上（10-02 实测产品 262,836 → 套件 266,540）= 停在套件态 → 重跑 A2 |
| A5 | 全量静态门禁 | `pre-commit run --all-files` | **17/17 Passed**（2026-10-03 实测；含新增 S5 `test-cppcheck`） |
@@ -126,7 +126,7 @@
# 2) 注入：按设计说明 §10 在 netTask 循环插 while(1);（或 taskDISABLE_INTERRUPTS(); while(1);）
# —— 改完 @build，然后烧录
& "MDK-ARM\build.bat"
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
& "MDK-ARM\reset.bat" flash MDK-ARM\STM32F407-Demo\STM32F407-Demo.hex
# 3) 抓串口日志，确认 [ERR] WATCHDOG task stall + 复位原因
docs/测试说明/测试开发标准流程.md
+1 -1
View File
@@ -361,7 +361,7 @@ static void phaseN_run(void) {
cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警告）
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 1) 菜单 8 状态像素回归 + 池基线
.venv\Scripts\python.exe simulator/tests/check_content_pages.py # 2) 内容页黄金参考 + 往返池水位
& "MDK-ARM\build.bat" # 3) Keil 构建（UI 源码双端共用，改一端必过另一端）
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 3) Keil 构建（UI 源码双端共用，改一端必过另一端）
.venv\Scripts\python.exe scripts/check_coding_standard.py # 4) 代码规范机械检查
```
docs/测试说明/自动化测试流程.md
+1 -1
View File
@@ -8,7 +8,7 @@
@test 命令触发
│
├─ Step 0 预检 .venv + serial_tool（selftest/ports 确认 COM）
├─ Step 1 构建验证 MDK-ARM/build.bat (0 错误 0 警告才继续)
├─ Step 1 构建验证 keil-build skill（keil_build.py） (0 错误 0 警告才继续)
├─ Step 2 烧录 + 采集（一条命令编排：开串口 + 清日志 → 烧录 → 固件身份戳 → wait-idle → 提取 → 回读校验）
│ .dsh/skills/serial-boot-test/scripts/run_boot_test.py (内置 serial_tool + download.bat + reset.bat cmp + verify_log.py)
├─ Step 3 判定：
docs/测试说明/链路延迟测试说明.md
+3 -3
View File
@@ -237,7 +237,7 @@ DTU-RemoteLCD 客户端；输出每帧 `req2first / total / recv 批次到达时
# 0) 前置：test/board/test_config.h 已启用 TEST_SUITE_CH395F + ENABLE_PHASE12_TESTS
# （产品构建 = 全部注释掉）
# 1) 构建（0 错 0 警）
& "MDK-ARM\build.bat"
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
# 2) 一键闭环：开串口+清日志 → 烧录（reset.bat flash，Reset&Run）→ wait-idle → 标记校验
# 硬件层模式无 "Network Init" 标记（netTask 自挂起），且 TEST_REPORT 行含 "failed=0"
# → Required/Forbidden 均用下方定制集（见 §4.4）
@@ -255,7 +255,7 @@ DTU-RemoteLCD 客户端；输出每帧 `req2first / total / recv 批次到达时
```powershell
# 0) 前置：test/board/test_config.h 启用 TEST_SUITE_CH395F，test/board/ch395f_test.h 仅启用
# ENABLE_PHASE13_TESTS（Phase 13 必须独占 8080 socket，勿与其他 NET 层 Phase 同启）
& "MDK-ARM\build.bat" # 必须 0 错 0 警
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 必须 0 错 0 警
# 1) 先 clear 再起 peer（顺序不可反：wait-idle 需要看到会话活跃期）
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py clear
& '.venv\Scripts\python.exe' test\latency_peer.py --host 192.168.1.100 --port 8080 `
@@ -281,7 +281,7 @@ DTU-RemoteLCD 客户端；输出每帧 `req2first / total / recv 批次到达时
```powershell
# M3（生产路径，需要设备已烧 Phase 14 固件）
& "MDK-ARM\build.bat" # 0 错 0 警（Phase 14 构建）
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 0 错 0 警（Phase 14 构建）
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py clear
& "MDK-ARM\download.bat" # 先烧录，再起 peer（顺序不可反！）
& '.venv\Scripts\python.exe' test\latency_peer.py --mode remo --host 192.168.1.100 --port 7003 `
docs/环境与部署/CI配置指南.md
+1 -1
View File
@@ -16,7 +16,7 @@
>
> 兜底（每次改代码后必做）：
> ```powershell
> & "MDK-ARM\build.bat" # 0/0 且生成 .map
> & '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 0/0 且生成 .map
> & '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan
> ```
> 若 CI 允许在带 Keil 的 runner 上跑，则该钩子会在有 `.map` 时**照常执行**（workflow 自适应）。
docs/环境与部署/本地工具路径环境变量方案.md
+1 -1
View File
@@ -9,7 +9,7 @@
| 变量 | 必需性 | 值的形态 | 使用者 | 默认/回退 |
|---|---|---|---|---|
| `DTU_KEIL_UV4` | MCU 构建/下载机必需 | UV4.exe 完整路径，例如 `D:\Tools\Keil\UV4\UV4.exe` | `build.bat`、`download.bat` | 不设即报错（exit 2）；不从 C 盘旧路径猜测 |
| `DTU_KEIL_UV4` | MCU 构建/下载机必需 | UV4.exe 完整路径，例如 `D:\Tools\Keil\UV4\UV4.exe` | `keil_build.py`（`@build`）、`build.bat`、`download.bat` | 不设即报错（exit 2）；不从 C 盘旧路径猜测 |
| `DTU_STLINK_CLI` | 复位/烧录/回读机必需 | `ST-LINK_CLI.exe` 完整路径，例如 `C:\Program Files (x86)\STMicroelectronics\STM32 ST-LINK Utility\ST-LINK Utility\ST-LINK_CLI.exe` | `reset.bat` | 未设时回退 PATH（`where ST-LINK_CLI.exe` 首个命中）；已设但无效 = 硬报错 |
| `DTU_PRECOMMIT_PYTHON` | 可选（覆盖用） | 含 `pre_commit` 模块的 `python.exe` 完整路径 | `ci_local.py` L0、CI `l0-gates` | 未设时按 §1.1 探测（当前解释器 → `.venv` → PATH）；已设但无效 = 硬报错 |
| `DTU_GRAPHVIZ_DOT` | 可选（覆盖用） | `dot.exe` 完整路径 | `gen_refgraph.py` | 未设时只查 PATH；无 Graphviz 时降级为"生成 .dot/.json、跳过渲染" |
docs/环境与部署/项目部署环境要求.md
+8 -8
View File
@@ -65,7 +65,7 @@ Graphviz / Cppcheck 的安装位置差异一律用 `DTU_*` 环境变量表达（
| 变量 | 必需性 | 值的形态 | 使用方 |
|---|---|---|---|
| `DTU_KEIL_UV4` | **必需**（MCU 构建/Keil 下载机） | UV4.exe 完整路径 | `MDK-ARM/build.bat`、`download.bat` |
| `DTU_KEIL_UV4` | **必需**（MCU 构建/Keil 下载机） | UV4.exe 完整路径 | `keil_build.py`（`@build`）、`MDK-ARM/build.bat`、`download.bat` |
| `DTU_STLINK_CLI` | **必需**（用 ST-LINK CLI 的机器；已在 PATH 可不设） | ST-LINK_CLI.exe 完整路径 | `MDK-ARM/reset.bat`（烧录/复位/回读） |
| `DTU_PRECOMMIT_PYTHON` | 可选（pre-commit 不在 `.venv`/当前解释器时设；CI runner 建议必设） | 装有 pre-commit 的 python.exe 完整路径 | `scripts/ci_local.py`、CI L0/L0.5 |
| `DTU_CPPCHECK` | 可选（开发机入 PATH 即可；无 PATH 的 CI runner 建议设） | cppcheck.exe 完整路径 | pre-commit cppcheck 钩子、CI L0 |
@@ -91,10 +91,10 @@ Graphviz / Cppcheck 的安装位置差异一律用 `DTU_*` 环境变量表达（
| 项 | 要求 | 说明 |
|---|---|---|
| Keil MDK-ARM | **v5.x**（须含 ARMCC v5 编译器） | 工程锁定 `uAC6=0`（仅 ARMCC v5，**不支持 armclang**）；仅支持此工具链，无其他工具链 |
| 安装路径 | **任意目录** | `build.bat` / `download.bat` / `reset.bat` 经 `DTU_*` 环境变量解析工具路径（§2.1.1）；新机器装完后设置 `DTU_KEIL_UV4` / `DTU_STLINK_CLI` 即可，**无需修改仓库脚本** |
| 安装路径 | **任意目录** | `keil_build.py` / `build.bat` / `download.bat` / `reset.bat` 经 `DTU_*` 环境变量解析工具路径（§2.1.1）；新机器装完后设置 `DTU_KEIL_UV4` / `DTU_STLINK_CLI` 即可，**无需修改仓库脚本** |
| 设备支持 | STM32F407ZGTx + CMSIS Flash 算法 | 工程引用 `STM32F4xx_1024.FLM`（1MB 片内 Flash，0x08000000），由 CMSIS STM32F4 设备包提供 |
| STM32CubeMX | **6.17.0**（工程 `STM32F407-Demo.ioc` 记录的版本） | 修改外设/引脚/时钟配置并再生成 CubeMX 文件；固件包须 **STM32Cube FW_F4 V1.28.3** |
| 命令行构建 | `& "MDK-ARM\build.bat"`（即 `@build`） | 退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt` |
| 命令行构建 | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（即 `@build`；原生入口 `MDK-ARM/build.bat` 等价） | 退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt` |
| 命令行烧录 | `& "MDK-ARM\download.bat"`（即 `@download`） | flash + Reset & Run；日志出现 `Application running` 判成功 |
> ⚠ **版本一致性关键**：.ioc 记录 `MxCube.Version=6.17.0` + `FirmwarePackage=STM32Cube FW_F4 V1.28.3`，
@@ -352,7 +352,7 @@ pre-commit run --all-files # 首次全库基线扫描
**第 10 步：冒烟验证**（全过 = 环境就绪；前置：§2.1.1 的 `DTU_*` 变量已设置——未设时构建脚本会明确报出缺哪个变量及设置方法）
```powershell
& "MDK-ARM\build.bat" # → BUILD_OK: 0 errors, 0 warnings
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # → BUILD_OK: 0 errors, 0 warnings
& "simulator\build_sim.bat" # 模拟器一键构建（自动探测 VS 版本），0 警告
.\simulator\build\Debug\lvgl_sim.exe # 出 160×160 单色菜单画面
& '.venv\Scripts\python.exe' simulator\tests\check_menu_rows.py # PASS
@@ -449,7 +449,7 @@ Test-Path $env:DTU_STLINK_CLI # True
| # | 命令 | 期望 | 失败诊断 |
|---|---|---|---|
| ① | `& <任一 python> -m venv .venv` + `& '.venv\Scripts\python.exe' -m pip install -r requirements.txt` | 安装完成且含 pre-commit | pip 报 GBK 解码错 = `requirements.txt` 被污染（该文件必须纯 ASCII，不该发生） |
| ② | `& "MDK-ARM\build.bat"` | `BUILD_OK: 0 errors, 0 warnings`，exit 0 | 报错行**直接指出变量名**（如 `ENV_ERROR: DTU_KEIL_UV4 is set but does not exist: ...`）——照报错修值；新机器首次启动 UV4 需 license（90 天评估），缺 Device Pack 则下载失败（构建不受影响） |
| ② | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` | `BUILD_OK: 0 errors, 0 warnings`，exit 0 | 报错行**直接指出变量名**（如 `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: ...`）——照报错修值；新机器首次启动 UV4 需 license（90 天评估），缺 Device Pack 则下载失败（构建不受影响） |
| ③ | `& '.venv\Scripts\python.exe' scripts/ci_local.py` | L0 全钩子 Passed + L0.5 单测断言全部通过（当前 278 条），exit 0 | "找不到 MSVC" = VS 未装或装到非标准位置（设 `DTU_MSVC_CL` 可验证覆盖通道） |
| ④ | `& 'tools\refgraph\gen_refgraph.bat'` → `git status` | 重生成后 `docs/images/` **无 diff**（图内容只依赖源码，与本机工具链无关） | 出现 diff = 异常，需查 |
| ⑤ | `& "simulator\build_sim.bat"` | 自动探测 VS → 生成器匹配 → 构建成功（2026-10-02 起模拟器构建可用：配置引擎重构的文件迁移已同步进 `simulator/CMakeLists.txt`） | 报 `Cannot find source file` / `C1083` = CMakeLists 与源码目录再次失步（查文件迁移记录），与 `DTU_*` 变量无关；"未探测到 VS" 见 §2.3 |
@@ -459,8 +459,8 @@ Test-Path $env:DTU_STLINK_CLI # True
```powershell
$env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话，不动用户级值
& "MDK-ARM\build.bat"
# 期望：ENV_ERROR: DTU_KEIL_UV4 is set but does not exist: "D:\NotExist\UV4.exe"，exit 2
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
# 期望：BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: D:\NotExist\UV4.exe，exit 2
# 关键判定：没有回退去猜别的 Keil 安装，而是明确报错
# 测完重开终端即恢复（用户级值未动）
```
@@ -602,7 +602,7 @@ $env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话，不动用户级
| 现象 | 原因 | 处理 |
|---|---|---|
| `build.bat` / `download.bat` 报 `DTU_KEIL_UV4 is not set` / `does not exist` | `DTU_KEIL_UV4` 未设置或指向错误路径（**设完变量须重开终端**） | 设置/修正 `DTU_KEIL_UV4` 为 UV4.exe 完整路径（§2.1.1），重开终端重试 |
| `keil_build.py` / `build.bat` / `download.bat` 报 `DTU_KEIL_UV4` 未设/无效 | `DTU_KEIL_UV4` 未设置或指向错误路径（**设完变量须重开终端**） | 设置/修正 `DTU_KEIL_UV4` 为 UV4.exe 完整路径（§2.1.1），重开终端重试 |
| `reset.bat` 报 `ST-LINK_CLI.exe not found` / `ENV_ERROR: DTU_STLINK_CLI` | `DTU_STLINK_CLI` 未设且不在 PATH，或显式值无效 | 设置 `DTU_STLINK_CLI` 为 ST-LINK_CLI.exe 完整路径，或把其目录加入 PATH；显式值无效时**不会**回退，须修值 |
| Keil 编译报编译器不识别 | 新装 MDK 只有 armclang | 工程锁 `uAC6=0`，必须用带 **ARMCC v5** 的 MDK v5.x |
| CubeMX 再生成后出现大量 diff / 新告警 | 用了比工程记录更新的 CubeMX / 固件包版本 | 用 git 还原生成文件，按 **.ioc 记录的 CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3** 重新生成 |