From 7a54fdbc7311826efb64f44f93a000851a8299f6 Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Sat, 10 Oct 2026 16:19:14 +0800
Subject: [PATCH] =?UTF-8?q?docs(build):=20@build=20=E7=BB=9F=E4=B8=80?=
 =?UTF-8?q?=E4=B8=BA=20keil-build=20skill=EF=BC=8Cbuild.bat=20=E9=99=8D?=
 =?UTF-8?q?=E4=B8=BA=E7=AD=89=E4=BB=B7=E5=8E=9F=E7=94=9F=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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
  常量（是代码、非文档，改动需另做验证）
---
 .dsh/skills/keil-build/SKILL.md             |  7 +++++--
 .dsh/skills/new-machine-setup/SKILL.md      |  4 ++--
 .dsh/skills/new-source-file/SKILL.md        |  2 +-
 .dsh/skills/ui-verify/SKILL.md              |  2 +-
 AGENTS.md                                   |  2 +-
 MDK-ARM/README.md                           |  6 +++---
 README.md                                   |  4 ++--
 docs/UI设计/UI_中文字体生成与配置.md        |  2 +-
 docs/UI设计/UI_自动化测试流程.md            |  4 ++--
 docs/产品需求/产品需求设计文档.md           |  2 +-
 docs/子系统设计/ADC采样节拍设计说明.md      |  2 +-
 docs/架构设计/项目架构总览.md               |  2 +-
 docs/测试说明/FTP_Test_Guide.md             |  2 +-
 docs/测试说明/SD2506_Test_Guide.md          |  4 ++--
 docs/测试说明/m2_data/README.md             |  4 ++--
 docs/测试说明/实机测试实施指南.md           |  4 ++--
 docs/测试说明/测试开发标准流程.md           |  2 +-
 docs/测试说明/自动化测试流程.md             |  2 +-
 docs/测试说明/链路延迟测试说明.md           |  6 +++---
 docs/环境与部署/CI配置指南.md               |  2 +-
 docs/环境与部署/本地工具路径环境变量方案.md |  2 +-
 docs/环境与部署/项目部署环境要求.md         | 16 ++++++++--------
 scripts/stack_report.py                     |  2 +-
 23 files changed, 44 insertions(+), 41 deletions(-)

diff --git a/.dsh/skills/keil-build/SKILL.md b/.dsh/skills/keil-build/SKILL.md
index f2669f28..24033943 100644
--- a/.dsh/skills/keil-build/SKILL.md
+++ b/.dsh/skills/keil-build/SKILL.md
@@ -22,9 +22,12 @@ whenToUse: 需要编译 Keil MDK 工程、验证代码改动是否 0 错误 0 
 
 ## 本仓库
 
-仓库原生入口 `& "MDK-ARM\build.bat"`（`@build` 约定）与本 skill 脚本判定口径一致
+**`@build` = 本 skill**（2026-10-10 起为仓库文档口径）：在仓库根目录跑
+`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`。
+仓库原生入口 `& "MDK-ARM\build.bat"` 与本 skill 判定口径一致
 （先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`），
-两者任选；`@build` 文档口径不变。环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）。
+**等价可用**，但它无超时保护、UV4 只认 `DTU_KEIL_UV4`、失败时 dump 整份日志 → 默认走本 skill。
+环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）。
 
 ## 铁律与陷阱（实测教训）
 
diff --git a/.dsh/skills/new-machine-setup/SKILL.md b/.dsh/skills/new-machine-setup/SKILL.md
index 3b63667b..305d8ea0 100644
--- a/.dsh/skills/new-machine-setup/SKILL.md
+++ b/.dsh/skills/new-machine-setup/SKILL.md
@@ -33,14 +33,14 @@ whenToUse: 换新机器/新克隆要把环境搭起来、构建或烧录报"环
 4. **验收三连**（全绿才算环境就绪）：
    ```powershell
    & '.venv\Scripts\python.exe' .dsh/skills/serial-assistant/scripts/serial_tool.py selftest   # 23/23 PASS
-   & "MDK-ARM\build.bat"                                                   # exit 0
+   & '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # exit 0
    & "MDK-ARM\reset.bat" list                                              # 列出探针
    ```
 
 ## 实测坑（本会话两次撞上）
 
 - **agent/服务派生的 shell 不继承"服务启动之后"设置的用户级环境变量**：
-  `build.bat` 报 exit 2 先分清"真没设"还是"没继承"——查
+  `keil_build.py`（或等价的 `build.bat`）报 exit 2 先分清"真没设"还是"没继承"——查
   `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`，有值就
   `$env:DTU_KEIL_UV4 = <该值>` 注入当前会话再跑，别急着让用户重设。
   （`env_check.py` 对这种情况报 WARN 并给注入命令。）
diff --git a/.dsh/skills/new-source-file/SKILL.md b/.dsh/skills/new-source-file/SKILL.md
index 7b23c98e..0542fcd2 100644
--- a/.dsh/skills/new-source-file/SKILL.md
+++ b/.dsh/skills/new-source-file/SKILL.md
@@ -28,7 +28,7 @@ whenToUse: 新建 App/、Drivers/BSP/ 下的 .c 文件，或构建/运行报 und
 
 ```powershell
 cmake --build simulator/build --config Debug   # 0 警告
-& "MDK-ARM\build.bat"                          # BUILD_OK，0 错 0 警
+& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # BUILD_OK，0 错 0 警
 ```
 
 ## 注意
diff --git a/.dsh/skills/ui-verify/SKILL.md b/.dsh/skills/ui-verify/SKILL.md
index b2190517..370e4d2f 100644
--- a/.dsh/skills/ui-verify/SKILL.md
+++ b/.dsh/skills/ui-verify/SKILL.md
@@ -14,7 +14,7 @@ UI 相关改动完成后必须跑完 5 个门禁再提交。完整说明见 `doc
 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）
 ```
 
diff --git a/AGENTS.md b/AGENTS.md
index 4bde67e0..c12e0f66 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@ STM32F407ZGTx @168MHz（HSE 8MHz → PLL M=4/N=168/P=2）；**仅 Keil MDK-ARM v
 
 ## 构建与验证
 
-- `@build` = `& "MDK-ARM\build.bat"`（仓库根目录用**相对路径**）；退出码 0 = 0 错误 0 警告，1 = 有警告或错误（查 `MDK-ARM/build_log.txt`），2 = `DTU_KEIL_UV4` 未设/无效（换机必设，见 `docs/环境与部署/本地工具路径环境变量方案.md`）；UV4 路径经 `DTU_KEIL_UV4` 环境变量解析（**不再硬编码**；显式设置但无效会立即报错、不静默回退）
+- `@build` = **`keil-build` skill**：`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（仓库根目录执行；纯标准库，任意 python3 亦可）。退出码 0 = 0 错误 0 警告（PASS）、1 = 构建失败（打印报错行）、2 = UV4 未找到/无效、3 = 用法错误。UV4 解析链 `--uv4` > `.serialtest/config.json` 的 `uv4` > `$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但无效 = 立即报错、不静默回退**）；日志 `MDK-ARM/build_log.txt`。**仓库原生入口 `& "MDK-ARM\build.bat"` 判定口径完全一致（先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`），等价可用**——但它无超时保护、UV4 只认 `DTU_KEIL_UV4`、失败时 dump 整份日志，故默认走 skill。换机必设 `DTU_KEIL_UV4`，见 `docs/环境与部署/本地工具路径环境变量方案.md`
 - `@test` / `.dsh/skills/serial-boot-test/scripts/run_boot_test.py` 一键闭环（2026-09-20 起为纯 Python 标准库实现，替代 PowerShell 版；`& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py`）：开串口+清日志 → 烧录（`MDK-ARM/download.bat`，下载后 Reset&Run；快路径 `--flash-cmd "MDK-ARM\reset.bat flash"`）→ **固件身份戳**（从刚烧进去的 hex 里抠 `fw build: <DATE> <TIME>` 追加成 Required 标记）→ wait-idle（等 RX 静默 8s，超时 30s，首字节 12s 未到判 `no_data`）→ 提取日志 → **烧录回读校验**（`reset.bat cmp` = `-CmpFile`；不一致 = 本次运行作废 exit 2）→ `.dsh/skills/serial-boot-test/scripts/verify_log.py` 标记校验（含**启动锚点计数**：`reset cause:` 出现 0 次或 >1 次 = FAIL，`--max-boot-count` 调；Forbidden 命中**逐行打印行号+内容**；boot_log 每行带 `[+Nms]` daemon 毫秒时基 → 可查标记顺序 `--require-order` 与开机耗时 `--done-marker`/`--max-boot-ms`，实测 `net init: OK` = **+537ms**）；退出码 0=PASS / 1=FAIL / 2=采集或烧录错误（含回读不一致）/ 3=用法/预检错误
 - 默认校验标记：Required `App init OK` / `Network Init` / `net init: OK` + **自动追加的固件身份戳 `fw build: <__DATE__> <__TIME__>`**（`App/app/app_main.c` 开机打印，`run_boot_test.py` 从待烧 hex 里抠出该串当 Required——此前所有标记都是固定串，**旧镜像/错镜像照样全中**，"反复重下载、芯片一直是旧镜像"在自动闭环里不可见，2026-10-10 补；`--no-fw-check` 关闭）；Forbidden `FAIL` / `ERROR` / `HardFault` / `[ERR]`（**四个 Fault 的崩溃日志都以 `[ERR]` 开头 → 一律判 FAIL**，这是刻意的：出现 Fault 即本次运行不通过）；按模块定制标记（网络/存储/RTC/ADC/RS485/UI）见 `docs/测试说明/自动化测试流程.md`
 - ⚠️ 旧绝对路径 `D:\Code\DTU 程序\...` 出现即失效（仓库已搬迁），一律改用仓库相对路径
diff --git a/MDK-ARM/README.md b/MDK-ARM/README.md
index 861c88f2..07a84e18 100644
--- a/MDK-ARM/README.md
+++ b/MDK-ARM/README.md
@@ -10,15 +10,15 @@
 | `STM32F407-Demo.uvprojx` | **Keil 工程文件**（源文件清单、编译选项、目标配置） |
 | `STM32F407-Demo.uvoptx` | Keil 用户选项（调试器、断点等） |
 | `startup_stm32f407xx.s` | 启动文件（**`Heap_Size EQU 0x200`（512B）在此限定**） |
-| `build.bat` | **`@build` 命令行编译**（退出码 0=0 错 0 警；日志 `build_log.txt`） |
+| `build.bat` | 命令行编译（**等价原生入口**；`@build` 现由 `keil-build` skill 承担。退出码 0=0 错 0 警；日志 `build_log.txt`） |
 | `download.bat` | 烧录（UV4 路径） |
 | `reset.bat` | **复位/烧录**（`ST-LINK_CLI`，见下） |
 
 ## 构建与烧录
 
 ```bash
-# 编译（相对路径，勿用绝对路径）
-& "MDK-ARM\build.bat"      # 退出码 0 = 0 errors, 0 warnings
+# 编译（@build = keil-build skill；相对路径，勿用绝对路径）
+& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # 退出码 0 = 0 errors, 0 warnings
 
 # 烧录 + 复位运行（推荐路径）
 & "MDK-ARM\reset.bat" flash <文件.hex|.bin>
diff --git a/README.md b/README.md
index 9b6b9592..89991374 100644
--- a/README.md
+++ b/README.md
@@ -213,8 +213,8 @@ STM32F4-Base/
 ### 编译
 
 ```bash
-# 方式一：命令行编译（推荐）
-MDK-ARM\build.bat
+# 方式一：命令行编译（推荐；= keil-build skill，等价原生入口 MDK-ARM\build.bat）
+& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
 
 # 方式二：Keil IDE
 # 打开 MDK-ARM\STM32F407-Demo.uvprojx → Build (F7)
diff --git a/docs/UI设计/UI_中文字体生成与配置.md b/docs/UI设计/UI_中文字体生成与配置.md
index 7a515051..ee93180b 100644
--- a/docs/UI设计/UI_中文字体生成与配置.md
+++ b/docs/UI设计/UI_中文字体生成与配置.md
@@ -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` 正常编入。
diff --git a/docs/UI设计/UI_自动化测试流程.md b/docs/UI设计/UI_自动化测试流程.md
index 39accf96..e1f8d4ba 100644
--- a/docs/UI设计/UI_自动化测试流程.md
+++ b/docs/UI设计/UI_自动化测试流程.md
@@ -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` 内置字形模板匹配——直接解析
diff --git a/docs/产品需求/产品需求设计文档.md b/docs/产品需求/产品需求设计文档.md
index 8956b3e8..35818f54 100644
--- a/docs/产品需求/产品需求设计文档.md
+++ b/docs/产品需求/产品需求设计文档.md
@@ -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=用法错误
 # 全库门禁
diff --git a/docs/子系统设计/ADC采样节拍设计说明.md b/docs/子系统设计/ADC采样节拍设计说明.md
index 9d2a8fc8..cf802f90 100644
--- a/docs/子系统设计/ADC采样节拍设计说明.md
+++ b/docs/子系统设计/ADC采样节拍设计说明.md
@@ -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=...` |
diff --git a/docs/架构设计/项目架构总览.md b/docs/架构设计/项目架构总览.md
index 65d48d92..4c8edb13 100644
--- a/docs/架构设计/项目架构总览.md
+++ b/docs/架构设计/项目架构总览.md
@@ -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` 测试套件互斥选择（产品构建全注释）。
diff --git a/docs/测试说明/FTP_Test_Guide.md b/docs/测试说明/FTP_Test_Guide.md
index 739b868b..9349ea73 100644
--- a/docs/测试说明/FTP_Test_Guide.md
+++ b/docs/测试说明/FTP_Test_Guide.md
@@ -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；
diff --git a/docs/测试说明/SD2506_Test_Guide.md b/docs/测试说明/SD2506_Test_Guide.md
index 32d529b6..fb68d2ca 100644
--- a/docs/测试说明/SD2506_Test_Guide.md
+++ b/docs/测试说明/SD2506_Test_Guide.md
@@ -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]` 日志。
diff --git a/docs/测试说明/m2_data/README.md b/docs/测试说明/m2_data/README.md
index 2025fa9f..9fb7204f 100644
--- a/docs/测试说明/m2_data/README.md
+++ b/docs/测试说明/m2_data/README.md
@@ -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      # 后台作业
diff --git a/docs/测试说明/实机测试实施指南.md b/docs/测试说明/实机测试实施指南.md
index b59bf103..34c13e06 100644
--- a/docs/测试说明/实机测试实施指南.md
+++ b/docs/测试说明/实机测试实施指南.md
@@ -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 + 复位原因
diff --git a/docs/测试说明/测试开发标准流程.md b/docs/测试说明/测试开发标准流程.md
index 351de92f..8dcb9ada 100644
--- a/docs/测试说明/测试开发标准流程.md
+++ b/docs/测试说明/测试开发标准流程.md
@@ -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) 代码规范机械检查
 ```
 
diff --git a/docs/测试说明/自动化测试流程.md b/docs/测试说明/自动化测试流程.md
index 741cddc9..fae97b6c 100644
--- a/docs/测试说明/自动化测试流程.md
+++ b/docs/测试说明/自动化测试流程.md
@@ -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  判定：
diff --git a/docs/测试说明/链路延迟测试说明.md b/docs/测试说明/链路延迟测试说明.md
index 6e51a5ed..ffee70da 100644
--- a/docs/测试说明/链路延迟测试说明.md
+++ b/docs/测试说明/链路延迟测试说明.md
@@ -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 `
diff --git a/docs/环境与部署/CI配置指南.md b/docs/环境与部署/CI配置指南.md
index 2fa9db57..0ef41c37 100644
--- a/docs/环境与部署/CI配置指南.md
+++ b/docs/环境与部署/CI配置指南.md
@@ -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 自适应）。
diff --git a/docs/环境与部署/本地工具路径环境变量方案.md b/docs/环境与部署/本地工具路径环境变量方案.md
index ea5660fc..1bc35760 100644
--- a/docs/环境与部署/本地工具路径环境变量方案.md
+++ b/docs/环境与部署/本地工具路径环境变量方案.md
@@ -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、跳过渲染" |
diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md
index d5f00993..d1ee207b 100644
--- a/docs/环境与部署/项目部署环境要求.md
+++ b/docs/环境与部署/项目部署环境要求.md
@@ -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** 重新生成 |
diff --git a/scripts/stack_report.py b/scripts/stack_report.py
index 5d9714a6..29bd9b76 100644
--- a/scripts/stack_report.py
+++ b/scripts/stack_report.py
@@ -159,7 +159,7 @@ def main():
     html_path = pathlib.Path(args.html)
     if not html_path.is_file():
         print(f'ERROR: call graph HTML not found: {html_path}', file=sys.stderr)
-        print('       build first: & "MDK-ARM\\build.bat"', file=sys.stderr)
+        print('       build first: .venv\\Scripts\\python.exe .dsh\\skills\\keil-build\\scripts\\keil_build.py', file=sys.stderr)
         return 2
 
     meta, functions = parse_callgraph(html_path)