模拟器构建入口改VS版本自适应（新增build_sim，兼容VS2019/2022/2026）；文档同步并补SDL2 SDK下载步骤

2026-09-21 02:30:16 +08:00
parent d0ec983cdd
commit bad5ceac0d
9 changed files with 246 additions and 51 deletions
@@ -97,7 +97,7 @@ simulator/shot*.bin
 simulator/*.ppm
 simulator/__pycache__/

-# LVGL PC Simulator - SDL2 SDK (downloaded, see docs/测试说明/LVGL模拟器部署与使用说明.md)
+# LVGL PC Simulator - SDL2 SDK (downloaded, see docs/UI 设计/LVGL模拟器部署与使用说明.md §3.1 与 docs/项目部署环境要求.md 第 3 步)
 simulator/SDL2/

 # Binary / large files
@@ -99,7 +99,7 @@ STM32F407ZGTx @168MHz（HSE 8MHz → PLL M=4/N=168/P=2）；**仅 Keil MDK-ARM v

 ## LVGL PC 模拟器

- `simulator/`（CMake + SDL2 预编译库）与 MCU 端共用 UI 源码（`ui_menu.c`、`ui_font_cn_12.c`），免烧录开发 UI：`cmake -B build -G "Visual Studio 16 2019" -A x64; cmake --build build --config Debug` → 运行 `simulator\build\Debug\lvgl_sim.exe`
+- `simulator/`（CMake + SDL2 预编译库）与 MCU 端共用 UI 源码（`ui_menu.c`、`ui_font_cn_12.c`），免烧录开发 UI：`& "simulator\build_sim.bat"`（按本机 VS 自动选生成器：16=2019 / 17=2022 / 18=2026，**勿把生成器版本写死**；`build/` 缓存生成器与本机 VS 不符时自动删除重建）→ 运行 `simulator\build\Debug\lvgl_sim.exe`
 - 自检：`--cfgtest`（配置闭环）/ `--logtest`（日志引擎）/ `--standby shot.bin`（待机屏截图）/ `--idle <秒>`
 - UI 改动一律走 **`ui-verify` skill 五步门禁**；含新汉字的 UI 文案提交前先跑 **`font-regen` skill** 重生成中文字体

@@ -219,9 +219,7 @@ MDK-ARM\download.bat
 PC 端 UI 开发调试（无需烧录 MCU，与 MCU 共用 `Drivers/BSP/UI/` 源码），详见 `docs/UI 设计/LVGL模拟器部署与使用说明.md`：

 ```powershell
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug
+& "simulator\build_sim.bat"        # 一键构建（自动探测本机 VS2019/2022/2026 生成器）
 # 运行 simulator\build\Debug\lvgl_sim.exe
 ```

@@ -30,7 +30,7 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 ### 1.3 关键设计决策

 - **SDL2**：LVGL 官方 `lv_port_pc_vscode` 同款显示方案
- **CMake + MSVC**：本机使用 Visual Studio 2019 BuildTools（`Visual Studio 16 2019` / `-A x64`）
+- **CMake + MSVC**：`build_sim.ps1` 按本机 VS 版本自动选生成器（16=2019 / 17=2022 / 18=2026，取已装最高；`-A x64`）。不同机器 VS 版本不同，**勿把生成器写死**
 - **仅 UI 预览**：模拟器只跑 UI，不包含网络（netTask/ftpTask）等 MCU 业务
 - **共享代码不复制**：UI 源码直接引用 `Drivers/BSP/UI/`，MCU 与 PC 同步维护

@@ -39,7 +39,7 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 | 依赖 | 版本 | 说明 |
 |------|------|------|
 | CMake | ≥ 3.15 | 本机验证 4.3.0-rc1 |
-| MSVC | VS2019 BuildTools | `Visual Studio 16 2019` 生成器，Hostx64/x64 |
+| MSVC | VS2019 / 2022 / 2026 任一 | `build_sim.ps1` 自动探测生成器（16=2019 / 17=2022 / 18=2026，取已装最高），Hostx64/x64 |
 | SDL2 | 2.32.10 | 已解压到 `simulator/SDL2/`，无需安装 |
 | 操作系统 | Windows | 已验证 win32 |

@@ -70,11 +70,12 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 ### 3.2 配置 CMake 并构建

 ```powershell
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug
+# 仓库根目录执行（自动探测本机 VS 版本：2019/2022/2026）
+& "simulator\build_sim.bat"
 ```

+> 手动等效：`cd simulator; cmake -B build -G "Visual Studio <NN> <YYYY>" -A x64; cmake --build build --config Debug`，生成器号须与本机 VS 大版本一致（16=2019 / 17=2022 / 18=2026）。
+
 生成的可执行文件：`simulator/build/Debug/lvgl_sim.exe`（SDL2.dll 由 POST_BUILD 自动复制到同目录）。

 ### 3.3 运行
@@ -91,18 +92,13 @@ cd simulator\build\Debug
 ### 4.1 构建 + 运行

 ```powershell
-cd simulator
-cmake --build build --config Debug        # 增量编译
-.\build\Debug\lvgl_sim.exe                # 运行
+# 仓库根目录执行（增量构建；生成器变化时自动删 build/ 重建）
+& "simulator\build_sim.bat"
+.\simulator\build\Debug\lvgl_sim.exe      # 运行
 ```

-> 改 CMakeLists.txt 后需重新 `cmake -B build`；仅改 .c/.h 时直接 `cmake --build` 即可。
-> 遇到奇怪问题时先删 `build/` 全量重建：
-> ```powershell
-> Remove-Item -Recurse -Force build
-> cmake -B build -G "Visual Studio 16 2019" -A x64
-> cmake --build build --config Debug
-> ```
+> 改 CMakeLists.txt 后再跑一次 `build_sim.bat` 即可（缓存不匹配会自动重建）。
+> 遇到奇怪问题时加 `-Clean` 全量重建：`& "simulator\build_sim.bat" -Clean`

 ### 4.2 键盘操作

@@ -255,6 +251,7 @@ A: 不能。模拟器仅预览 UI，不含 CH395F/NAND/ADC 等硬件业务。
 | `simulator/lv_conf.h` | 新增 | 模拟器 LVGL 配置 |
 | `simulator/dbg_log.h` | 新增 | printf 日志 stub |
 | `simulator/CMakeLists.txt` | 新增 | 构建脚本 |
+| `simulator/build_sim.bat` / `.ps1` | 新增 | 一键构建（VS2019/2022/2026 生成器自适应；.bat 绕过 PowerShell 执行策略） |
 | `simulator/SDL2/SDL2-2.32.10/` | 新增 | SDL2 SDK（含 include/SDL2/ 子目录） |
 | `Lib/lvgl/CMakeLists.txt` | 新增 | LVGL 最小 CMake（仅模拟器用） |
 | `Drivers/BSP/UI/ui_menu.c` | 未改 | 共享 UI 代码 |
@@ -9,7 +9,7 @@

 | 项 | 说明 |
 |---|---|
-| 模拟器已构建 | 仓库根目录：`cmake --build simulator/build --config Debug`（首次需先 `cd simulator; cmake -B build -G "Visual Studio 16 2019" -A x64`，见 `simulator/README.md` §3.2） |
+| 模拟器已构建 | 仓库根目录：`& "simulator\build_sim.bat"`（自动探测本机 VS2019/2022/2026 生成器，见 `simulator/README.md` §3.2） |
 | Python | 统一入口 `.venv\Scripts\python.exe`（AGENTS.md「Python 环境」）；两个回归脚本纯标准库，任意 python3 均可，为保持一致一律用 .venv |

 ## 二、流程总览
@@ -19,7 +19,7 @@ flowchart LR
    subgraph DEV["① 开发机（Windows PC）"]
        K[Keil MDK-ARM v5<br/>MCU 编译/烧录]
        X[STM32CubeMX 6.17.0<br/>外设配置/代码再生成]
-        S[CMake + VS2019<br/>LVGL PC 模拟器]
+        S[CMake + VS2019/2026<br/>LVGL PC 模拟器]
        P[Python .venv<br/>字体/回归脚本]
        T[Python 串口助手 serial_tool<br/>串口调试/自动测试]
        G[Graphviz<br/>引用关系图渲染（可选）]
@@ -96,16 +96,14 @@ flowchart LR
 | 项 | 要求 | 说明 |
 |---|---|---|
 | CMake | ≥ 3.15 | 本机实测 4.3.0-rc1 |
-| 编译器 | **Visual Studio 16 2019**（C++ x64 工作负载） | 生成器固定 `"Visual Studio 16 2019"`、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
+| 编译器 | **VS2019 / 2022 / 2026 任一**（C++ x64 工作负载） | `build_sim.ps1` 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
 | Windows SDK | 10.0.19041 及以上 | CMake 配置时自动选用已装版本 |
-| SDL2 | 2.32.10 | **随仓库提供**（`simulator/SDL2/` 预编译 SDK，含 x64 库与头文件副本），无需系统安装 |
+| SDL2 | 2.32.10（预编译，无需系统安装） | **不在仓库**（`simulator/SDL2/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见**第 3 步** |
 | 产物 | `simulator/build/Debug/lvgl_sim.exe` | `build/` 为生成物（gitignore），可整体删除重建 |

 ```powershell
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64   # 仅首次（改 CMakeLists.txt 后需重跑）
-cmake --build build --config Debug                  # 日常增量
-.\build\Debug\lvgl_sim.exe                          # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）
+& "simulator\build_sim.bat"                          # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑）
+.\simulator\build\Debug\lvgl_sim.exe                 # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）
 ```

 > 模拟器与 MCU **共用 UI 源码**（`Drivers/BSP/UI/`），无硬件业务（网络推流除外，Winsock 版）。
@@ -205,15 +203,53 @@ winget install Git.Git
  - 固件包须 **STM32Cube FW_F4 V1.28.3**（与仓库 HAL 驱动一致；若未随附，在 CubeMX `帮助 → 管理` 下载对应包）
  - ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，**勿随意用最新版**

-**第 3 步：VS2019 + CMake**（模拟器工具链）
+**第 3 步：VS（2019/2022/2026 任一）+ CMake**（模拟器工具链）

 ```powershell
 winget install Kitware.CMake        # ≥3.15
 ```

- VS2019 Community 已下架主站，从**存档页**下载：<https://visualstudio.microsoft.com/zh-hans/vs/archives/>（直链：<https://aka.ms/vs/16/release/vs_community.exe>）
-  - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾 **Windows 10 SDK (10.0.19041)**
- **SDL2 不用装**——仓库 `simulator/SDL2/` 已含 2.32.10 预编译 SDK（仅当缺失时补：https://github.com/libsdl-org/SDL/releases ）
+- VS 版本不固定：构建入口 `simulator\build_sim.bat` 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可
+- 新装选 VS2019 的注意：Community 已下架主站，从**存档页**下载：<https://visualstudio.microsoft.com/zh-hans/vs/archives/>（直链：<https://aka.ms/vs/16/release/vs_community.exe>）；装 VS2022/VS2026 走主站下载
+  - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾对应 **Windows 10/11 SDK**
+- **SDL2 无需系统安装**（用预编译 SDK），但**不在仓库**——`simulator/SDL2/` 被 gitignore，`git clone` 后本地没有；目录不存在时按下面步骤补一次
+
+  **补 SDL2 SDK（仅当 `simulator/SDL2/` 缺失）**
+
+  ```powershell
+  # 1) 下载官方 2.32.10 VC 预编译包（GitHub Releases，约 7 MB）
+  New-Item -ItemType Directory -Force simulator\SDL2 | Out-Null
+  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+  Invoke-WebRequest -Uri "https://github.com/libsdl-org/SDL/releases/download/release-2.32.10/SDL2-devel-2.32.10-VC.zip" `
+      -OutFile simulator\SDL2\SDL2-devel-2.32.10-VC.zip -UseBasicParsing
+
+  # 2) 解压到 simulator/SDL2/；顶层目录名须为 SDL2-2.32.10
+  #    （若解压出 SDL2-devel-2.32.10/，改名为 SDL2-2.32.10/）
+  Expand-Archive simulator\SDL2\SDL2-devel-2.32.10-VC.zip -DestinationPath simulator\SDL2 -Force
+
+  # 3) 头文件复制到 include/SDL2/ 子目录（必做：LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
+  $inc = "simulator\SDL2\SDL2-2.32.10\include"
+  New-Item -ItemType Directory -Path "$inc\SDL2" -Force | Out-Null
+  Copy-Item "$inc\*.h" "$inc\SDL2\"
+
+  # 4) 校验 5 个必备文件（全 True = 就绪），然后删 zip
+  foreach ($f in @("include\SDL.h", "include\SDL2\SDL.h", "lib\x64\SDL2.lib",
+                   "lib\x64\SDL2main.lib", "lib\x64\SDL2.dll")) {
+      "{0} : {1}" -f $f, (Test-Path "simulator\SDL2\SDL2-2.32.10\$f")
+  }
+  Remove-Item simulator\SDL2\SDL2-devel-2.32.10-VC.zip
+  ```
+
+  目标目录结构：
+
+  ```
+  simulator/SDL2/SDL2-2.32.10/
+  ├── include/            ← SDL.h 及各头文件
+  │   └── SDL2/           ← 头文件副本（第 3 步；缺它编译报 C1083: cannot open include file "SDL2/SDL.h"）
+  └── lib/x64/            ← SDL2.lib / SDL2main.lib / SDL2.dll（构建与运行均从此取）
+  ```
+
+  > 内网机器连不上 GitHub：在任一台有网的机器下载 zip（release 页：<https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10>）拷过去，再走上面第 2~4 步。

 **第 4 步：Python**（`.venv` 脚本工具链）

@@ -274,10 +310,8 @@ pre-commit run --all-files          # 首次全库基线扫描

 ```powershell
 & "MDK-ARM\build.bat"                                            # → BUILD_OK: 0 errors, 0 warnings
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug                               # 0 警告
-.\build\Debug\lvgl_sim.exe                                       # 出 160×160 单色菜单画面
+& "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
 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update  # 首次生成参考图
 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py       # 再跑 → PASS
@@ -290,7 +324,7 @@ pre-commit run --all-files
 - [ ] Windows 10/11 x64 + PowerShell 5.1+
 - [ ] Keil MDK-ARM v5.x 装到 `C:\Keil_v5\`（或已同步修改两个 bat）+ CMSIS / STM32F4 DFP 包
 - [ ] STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
- [ ] VS2019（C++ x64 工作负载）+ Windows 10 SDK + CMake ≥3.15
+- [ ] VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本）
 - [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH
 - [ ] 建 `.venv` 并 `pip install -r requirements.txt`
 - [ ] `npm i -g lv_font_conv`
@@ -462,8 +496,8 @@ pre-commit run --all-files
 | `build.bat` 找不到 UV4 / 闪退 | Keil 未装在 `C:\Keil_v5\` | 装到该路径，或改 `build.bat` / `download.bat` 的 `UV4=` 行 |
 | 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** 重新生成 |
-| CMake 配置失败：找不到生成器 | 未装 VS2019 | 装 VS2019（C++ x64 工作负载）；勿改生成器（工程按 VS16 配置） |
-| 模拟器构建报 `SDL2/SDL.h` 找不到 | 头文件副本缺失 | 按 `simulator/README.md` §四.1 把 SDK 头文件复制到 `include/SDL2/`（仓库已含，仅删过 SDK 目录才需要） |
+| CMake 配置失败：找不到生成器 | 本机 VS 大版本与生成器不匹配 | 统一走 `simulator\build_sim.bat`（自动探测 VS 版本选生成器）；手动 cmake 时 `-G` 号须与本机 VS 一致（16=2019 / 17=2022 / 18=2026） |
+| 模拟器构建报 `SDL2/SDL.h` 找不到 | `simulator/SDL2/` SDK 缺失（不入库）或头文件副本没做 | 按第 3 步"补 SDL2 SDK"完整走一遍（下载 → 解压 → 头文件复制到 `include/SDL2/` → 5 文件校验） |
 | `.venv` 不存在 / 脚本 ModuleNotFound | venv 未建（不入库） | 按 §2.4 重建 + `pip install -r requirements.txt` |
 | pip 装依赖报 UnicodeDecodeError | `requirements.txt` 含中文注释 | 保持该文件**纯 ASCII**（pip 按 GBK 代码页解码） |
 | 字体生成 / 转 PNG 报缺模块 | 误用 PATH 里的 msys64 python | 一律用 `.venv\Scripts\python.exe` |
@@ -499,6 +533,8 @@ pre-commit run --all-files

 | 日期 | 变更 |
 |---|---|
+| 2026-09-21 | 更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"**随仓库提供**/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正 |
+| 2026-09-21 | 模拟器构建改为自适应：新增 `simulator/build_sim.bat/.ps1`（vswhere 自动探测本机 VS 大版本 → 生成器 16=2019 / 17=2022 / 18=2026；`build/` 生成器不符自动删除重建，删除带重试抗文件锁）；VS 版本不再固定，2019/2022/2026 兼容：总览图、§2.3、第 3 步、第 10 步冒烟、搭建清单、速查表同步更新 |
 | 2026-09-16 | 补 Graphviz（引用关系图渲染，可选）：新增 §2.8，原 §2.8/§2.9 顺延为 §2.9/§2.10（章节内步骤号不变）；总览图、搭建清单、§2.10 下载表、相关文档各补一项 |
 | 2026-09-13 | 初版：汇总开发机（Keil / VS2019+SDL2 / Python venv / 字体 / 串口工具 / pre-commit）、目标板（引脚 / 资源预算 / 下载 / 功能开关）、网络现场部署（默认参数 / 端口 / 验收清单）、远端客户端四类环境要求，附一次性搭建清单（含分步安装命令与冒烟验证）与常见环境问题速查 |
 | 2026-09-13 | §2.8 各组件补手动下载网址；新增 §2.9 手动下载来源速查表 |
@@ -12,6 +12,7 @@
 ```
 simulator/
 ├── CMakeLists.txt          # 构建脚本（CMake + MSVC，x64）
+├── build_sim.bat / .ps1    # 一键构建入口（自动探测 VS2019/2022/2026 生成器，x64；.bat 绕过执行策略）
 ├── main.c                  # 入口：SDL 初始化 → LVGL → 菜单 → 主循环
 ├── sim/                    # 平台层（PC 专用实现；MCU 端对应实现在各 BSP 目录）
 │   ├── sim_port.c / .h     # 显示/输入端口（SDL 窗口 + 键盘 + mono 主题），替代 MCU 端 ui_port.c
@@ -49,6 +50,7 @@ simulator/
 | `sim/cfg_file_store_sim.c` | 通用配置文件存储后端：本地文件 `sim_config.ini`（`fopen`/`rename` 原子写），替代 MCU 端 `App/cfg_file_store_mcu.c`（FatFS）；旧档 `sim_netcfg.bin` 首启自动迁移进 `sim_config.ini` |
 | `lv_conf.h` | 模拟器专用 LVGL 配置。与 MCU 端 `Lib/lv_conf.h` 的关键差异见 §3.3 |
 | `dbg_log.h` | MCU 版 `dbg_log.h` 依赖 `sys_clock.h`（RTC 时间戳），PC 无法编译。此 stub 把 `DBG_INFO/ERROR/DEBUG` 映射到 `printf`；因 `simulator/` 在 include 路径最前，**优先生效**覆盖 MCU 版 |
+| `build_sim.bat` / `build_sim.ps1` | 一键构建入口：vswhere 探测本机 VS 大版本（16=2019 / 17=2022 / 18=2026，取已装最高）→ 映射 CMake 生成器；`build/` 缓存生成器与本机不符（换机/升级 VS）时自动删除重建（带重试，抗文件锁）。**构建入口一律走它，文档/命令中勿写死生成器版本**；`.bat` 仅负责绕过 PowerShell 执行策略并转交 `.ps1` |
 | `CMakeLists.txt` | 收集 LVGL 源码（`../Lib/lvgl`）+ 共享 UI 源码（`../Drivers/BSP/UI`）+ 通用配置文件引擎（`../App/cfg_file.c`、`../Drivers/BSP/NETCFG` 的 net_cfg/net_cfg_legacy）+ `sim/` 平台层，链接预编译 SDL2，产出 `lvgl_sim.exe` |
 | `i1_to_png.py` | 把 `--screenshot` 产出的 I1(1bpp) 原始位图转成 PNG，便于离线比对设计稿。详见 §3.5 |
 | `tests/` | 无头回归脚本（菜单 8 状态像素回归、内容页文本断言 + 黄金参考回归）；`ref/` 为**本地生成物、不入库**（首次 `--update` 生成）。详见 §3.6 |
@@ -118,7 +120,7 @@ LVGL 场景（同一份 ui_menu.c）
 ### 2.4 关键设计决策

 1. **SDL2**：LVGL 官方 PC 端口同款显示方案；使用仓库内预编译 SDK（`SDL2/SDL2-2.32.10/`），无需系统安装
-2. **CMake + MSVC**：`Visual Studio 16 2019` 生成器，`-A x64`；MSVC 下加 `/utf-8` 消除中文注释的 C4819 警告
+2. **CMake + MSVC**：`build_sim.ps1` 按本机 VS 版本自动选生成器（16=2019 / 17=2022 / 18=2026；不同机器版本不同，**勿写死**），`-A x64`；MSVC 下加 `/utf-8` 消除中文注释的 C4819 警告
 3. **共享 UI 源码**：`ui_menu.c` / `ui_font_cn_12.c` 直接编译 `Drivers/BSP/UI/` 原件，改一处两端同时生效
 4. **纯键盘导航**：不创建鼠标/触摸设备，与 MCU 端 keypad 操作语义一致（↑↓←→ / Enter / Esc）
 5. **UI 为主**：不含 CH395F 网络 / NAND 存储 / ADC 等硬件业务；通用配置文件引擎（`cfg_file`）与 `net_cfg` 核心为纯软件，配置加载/保存/旧档迁移可在模拟器离线验证（`sim_config.ini` / `sim_netcfg.bin`）
@@ -132,27 +134,27 @@ LVGL 场景（同一份 ui_menu.c）
 | 依赖 | 版本 | 说明 |
 |------|------|------|
 | CMake | ≥ 3.15 | 本机验证 4.3.0-rc1 |
-| MSVC | VS2019 BuildTools | `Visual Studio 16 2019` 生成器，Hostx64/x64 |
+| MSVC | VS2019 / 2022 / 2026 任一 | `build_sim.ps1` 自动探测生成器（16=2019 / 17=2022 / 18=2026，取已装最高），Hostx64/x64 |
 | SDL2 | 2.32.10 | 已内置于 `SDL2/`，无需安装 |
 | 操作系统 | Windows | 已验证 win32 |

 ### 3.2 构建命令

 ```powershell
-# 首次（配置 + 构建）
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug
-
-# 日常（仅改 .c/.h 时增量编译）
-cmake --build build --config Debug
+# 一键构建（仓库根目录执行；自动探测本机 VS2019/2022/2026 生成器，
+# build/ 缓存生成器与本机不符时自动删除重建）
+& "simulator\build_sim.bat"

 # 运行
-.\build\Debug\lvgl_sim.exe
-# 或：cmake --build build --config Debug --target run
+.\simulator\build\Debug\lvgl_sim.exe
+# 或：cmake --build simulator\build --config Debug --target run
+
+# 全量重建
+& "simulator\build_sim.bat" -Clean
 ```

-> 改 `CMakeLists.txt` 后需重新 `cmake -B build`；遇到奇怪问题先删 `build/` 全量重建。
+> 改 `CMakeLists.txt` 后再跑一次 `build_sim.bat` 即可（缓存不匹配会自动重建）；遇到奇怪问题加 `-Clean` 全量重建。
+> 手动 CMake 等效：`cd simulator; cmake -B build -G "Visual Studio <NN> <YYYY>" -A x64; cmake --build build --config Debug`，生成器号须与本机 VS 大版本一致（16=2019 / 17=2022 / 18=2026）。

 ### 3.3 `lv_conf.h` 与 MCU 端的关键差异

@@ -0,0 +1,24 @@
+@echo off
+rem ============================================================
+rem  LVGL PC simulator one-shot build (VS2019/2022/2026 auto-detect, x64)
+rem  Usage (from repo root, any shell):
+rem    & "simulator\build_sim.bat"                  incremental build
+rem    & "simulator\build_sim.bat" -Clean           full rebuild
+rem    & "simulator\build_sim.bat" -Config Release  Release build
+rem  Logic lives in build_sim.ps1 (vswhere probe -> generator mapping);
+rem  this bat only bypasses the PowerShell execution policy and
+rem  forwards the arguments. Exit code = build result (0 ok / 1 fail / 3 env).
+rem  NOTE: keep this file PURE ASCII - cmd parses .bat in the ANSI
+rem  codepage; UTF-8 Chinese here corrupts the command lines.
+rem ============================================================
+setlocal
+
+where pwsh >nul 2>nul
+if %errorlevel%==0 (
+    pwsh -NoProfile -ExecutionPolicy Bypass -File "%~dp0build_sim.ps1" %*
+    goto :done
+)
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0build_sim.ps1" %*
+
+:done
+exit /b %errorlevel%
@@ -0,0 +1,138 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    LVGL PC 模拟器一键构建（Visual Studio 版本自适应，x64）。
+
+.DESCRIPTION
+    不同开发机安装的 VS 版本不同，CMake 生成器必须与本机 VS 大版本一致，
+    因此构建入口不写死生成器：本脚本用 vswhere 自动探测本机 Visual Studio
+    （VS / BuildTools 均可），按大版本映射 CMake 生成器，取已安装的最高版本：
+        16 = "Visual Studio 16 2019"
+        17 = "Visual Studio 17 2022"
+        18 = "Visual Studio 18 2026"
+    若 build/ 目录缓存的生成器与探测结果不一致（换机/升级 VS 后），
+    自动删除 build/ 重新配置，避免 MSBuild 报生成器不匹配。
+
+    退出码：0=成功；1=构建失败；3=环境预检失败（无 cmake / 无 VS / VS 版本过新）。
+
+.PARAMETER Config
+    构建配置，默认 Debug（可选 Release）。
+
+.PARAMETER Clean
+    强制删除 build/ 后全量重建。
+
+.EXAMPLE
+    & 'simulator\build_sim.ps1'                  # 仓库根目录执行，日常增量构建
+    & 'simulator\build_sim.ps1' -Clean           # 全量重建
+    & 'simulator\build_sim.ps1' -Config Release  # Release 构建
+#>
+param(
+    [ValidateSet('Debug', 'Release')]
+    [string]$Config = 'Debug',
+    [switch]$Clean
+)
+
+$ErrorActionPreference = 'Stop'
+
+# 本脚本位于 simulator/ 目录
+$simDir = $PSScriptRoot
+$buildDir = Join-Path $simDir 'build'
+
+# --- 1. 环境预检 -----------------------------------------------------------
+$cmake = Get-Command cmake -ErrorAction SilentlyContinue
+if (-not $cmake) {
+    Write-Host '[build_sim] 预检失败：PATH 中找不到 cmake' -ForegroundColor Red
+    exit 3
+}
+
+# vswhere 随 Visual Studio / BuildTools 自带
+$pf86 = ${env:ProgramFiles(x86)}
+if (-not $pf86) { $pf86 = 'C:\Program Files (x86)' }
+$vswhere = Join-Path $pf86 'Microsoft Visual Studio\Installer\vswhere.exe'
+if (-not (Test-Path $vswhere)) {
+    Write-Host '[build_sim] 预检失败：未找到 vswhere（本机未安装 Visual Studio / BuildTools）' -ForegroundColor Red
+    exit 3
+}
+
+# --- 2. 探测 VS 大版本 → 选择生成器 ----------------------------------------
+$raw = & $vswhere -products * -format json
+$instances = @($raw | ConvertFrom-Json)          # 单实例时 PS5.1 返回裸对象，@() 统一成数组
+$instances = $instances | Where-Object { $_ -and $_.installationVersion }
+if (-not $instances) {
+    Write-Host '[build_sim] 预检失败：vswhere 未返回任何 VS 实例' -ForegroundColor Red
+    exit 3
+}
+$best = $instances |
+    Sort-Object { [version]$_.installationVersion } |
+    Select-Object -Last 1
+$major = [version]$best.installationVersion
+
+switch ($major.Major) {
+    16 { $generator = 'Visual Studio 16 2019' }
+    17 { $generator = 'Visual Studio 17 2022' }
+    18 { $generator = 'Visual Studio 18 2026' }
+    default {
+        Write-Host "[build_sim] 预检失败：不支持的 VS 大版本 $($major.Major)（$($best.installationPath)），仅支持 16/17/18" -ForegroundColor Red
+        exit 3
+    }
+}
+Write-Host "[build_sim] 探测到 VS $($best.installationVersion) -> 生成器 '$generator'"
+
+# 删除 build/ 目录（带重试：抗杀软瞬时锁/文件占用；彻底失败则提示用户）
+function Remove-BuildDir([string]$Dir) {
+    for ($i = 1; $i -le 3; $i++) {
+        try {
+            Remove-Item $Dir -Recurse -Force -ErrorAction Stop
+            return $true
+        } catch {
+            if ($i -lt 3) {
+                Write-Host "[build_sim] build/ 删除失败（可能有文件被占用），重试 $i/3 ..."
+                Start-Sleep -Seconds 2
+            }
+        }
+    }
+    Write-Host '[build_sim] 无法删除 build/：若模拟器窗口仍开着，请先关闭再重试' -ForegroundColor Red
+    return $false
+}
+
+# --- 3. 生成器一致性检查（缓存不匹配则删 build/ 重建）-----------------------
+if ($Clean -and (Test-Path $buildDir)) {
+    if (-not (Remove-BuildDir $buildDir)) { exit 3 }
+    Write-Host '[build_sim] -Clean：已删除 build/'
+}
+$cache = Join-Path $buildDir 'CMakeCache.txt'
+if (Test-Path $cache) {
+    # CMake 缓存中 CMAKE_GENERATOR 的类型随版本为 STRING 或 INTERNAL，统一按行首匹配
+    $cached = (Select-String -Path $cache -Pattern '^CMAKE_GENERATOR:' |
+        Select-Object -First 1).Line -replace '^CMAKE_GENERATOR:[A-Z]+=', ''
+    if ($cached -cne $generator) {
+        Write-Host "[build_sim] build/ 由 '$cached' 配置，与本机 '$generator' 不符 -> 删除重建"
+        if (-not (Remove-BuildDir $buildDir)) { exit 3 }
+    }
+}
+
+# --- 4. 配置 + 构建 ---------------------------------------------------------
+if (-not (Test-Path (Join-Path $buildDir 'CMakeCache.txt'))) {
+    Write-Host '[build_sim] CMake 配置 ...'
+    & cmake -S $simDir -B $buildDir -G $generator -A x64
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host '[build_sim] CMake 配置失败' -ForegroundColor Red
+        exit $LASTEXITCODE
+    }
+}
+
+Write-Host "[build_sim] 构建（$Config）..."
+& cmake --build $buildDir --config $Config
+if ($LASTEXITCODE -ne 0) {
+    Write-Host '[build_sim] 构建失败' -ForegroundColor Red
+    exit $LASTEXITCODE
+}
+
+$exe = Join-Path $buildDir (Join-Path $Config 'lvgl_sim.exe')
+if (Test-Path $exe) {
+    Write-Host "[build_sim] OK：$exe" -ForegroundColor Green
+    exit 0
+}
+Write-Host "[build_sim] 构建退出码 0 但未找到 $exe" -ForegroundColor Red
+exit 1
+