STM32F4-Base/docs/环境与部署/项目部署环境要求.md

项目部署环境要求

版本：v1.0　日期：2026-09-13 适用工程：STM32F4-Base（STM32F407ZGTx + CH395F 以太网 / LVGL UI / FreeRTOS） 用途：新机器搭建、环境交接、现场部署时的一站式环境核对清单——开发机软件环境、 目标板硬件与资源预算、网络/服务现场部署、远端客户端环境、验收步骤与常见环境问题。 文中所有版本/参数/数值均取自仓库内配置或本机实测（AGENTS.md、MDK-ARM/*.bat、 simulator/README.md、docs/内存管理/、docs/子系统设计/网络配置说明.md、docs/测试说明/ 等）， 换机器时以仓库文件为准逐项核对。

---

一、环境总览

本项目涉及三类环境，部署前按 §二~§五 逐一核对：

flowchart LR
    subgraph DEV["① 开发机（Windows PC）"]
        K[Keil MDK-ARM v5<br/>MCU 编译/烧录]
        X[STM32CubeMX 6.17.0<br/>外设配置/代码再生成]
        S[CMake + VS2019/2026<br/>LVGL PC 模拟器]
        P[Python .venv<br/>字体/回归脚本]
        T[Python 串口助手 serial_tool<br/>串口调试/自动测试]
        U[MSVC (VS2022 生成工具)<br/>主机侧单元测试 cl.exe]
        G[Graphviz<br/>引用关系图渲染（可选）]
    end
    subgraph TGT["② 目标板（DTU 硬件）"]
        M[STM32F407ZGTx @168MHz<br/>1MB Flash / 192KB SRAM]
        H[CH395F / GD5F2GQ5UE<br/>TPAFE5160 / RS-485 / LED×6]
    end
    subgraph RMT["③ 远端客户端（PC/浏览器）"]
        C[DTU-RemoteLCD<br/>或任意 TCP 客户端]
    end

    DEV -- "USB：下载器（ST-Link 等）" --> TGT
    DEV -- "USB 串口 USART1<br/>COMx @115200 调试日志" --> TGT
    TGT -- "以太网（CH395F）<br/>FTP:21 / 对时:8888 / 显示:7003" --> RMT

环境	角色	必需性
① 开发机	MCU 编译/烧录、UI 模拟器、脚本工具链	开发/测试必需
② 目标板	运行固件的 DTU 硬件	上机必需
③ 远端客户端	远程看图/按键、对时推送、FTP 文件操作	现场使用必需

---

二、开发机环境（Windows）

2.1 操作系统与基础

项	要求	说明
系统	Windows 10/11 x64	全部工具链均为 Windows 形态（Keil / VS / SDL / COM 口）；本机实测 Win11
终端	PowerShell 5.1+	构建/测试脚本均为 .bat / .ps1
版本控制	git	提交受 pre-commit 钩子门禁（§2.7）
磁盘	≥10 GB 空闲	Keil 工程 + VS 模拟器 build/ + 工具链

2.1.1 本地工具路径环境变量（DTU_* 系列，新机器必配项见下表）

仓库脚本不含本机绝对工具路径：Keil / ST-LINK / pre-commit Python / MSVC / Windows SDK / Graphviz / Cppcheck 的安装位置差异一律用 DTU_* 环境变量表达（完整契约与解析语义见 docs/环境与部署/本地工具路径环境变量方案.md）。新机器装完工具后按表配置：

变量	必需性	值的形态	使用方
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
DTU_MSVC_CL	可选（VS 标准位置时自动探测）	x64 cl.exe 完整路径	主机侧单测、CI L0.5
DTU_WINDOWS_KITS_ROOT	可选（SDK 标准位置时自动探测）	Windows Kits\10 根目录	主机侧单测
DTU_VSWHERE	可选（VS 标准位置时由 %ProgramFiles(x86)% 自动推导）	vswhere.exe 完整路径	simulator/build_sim.ps1
DTU_GRAPHVIZ_DOT	可选（PATH 可发现时不设）	dot.exe 完整路径	tools/refgraph 渲染

# 用户级设置（无需管理员；★ 设完必须重开终端/IDE 才生效）
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4',   'D:\Tools\Keil\UV4\UV4.exe', 'User')      # 示例路径
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', 'D:\Tools\STLink\ST-LINK_CLI.exe', 'User') # 示例路径
# 其余可选项按实际安装位置补充；验证：$env:DTU_KEIL_UV4 后 Test-Path / 跑对应命令

统一解析语义：变量显式设置但无效 → 立即报错（指出变量名与收到的路径），不静默回退到别的安装； 未设置 → 按工具走 PATH / 标准布局自动发现（可选工具允许降级，如 Graphviz 缺失只跳渲染）。 CI runner 以 SYSTEM 服务运行，用户级变量对其不可见——runner 用机器级变量注入（见 Gitea_Runner部署指南.md 环境变量节）。

2.2 MCU 构建工具链（必需）

项	要求	说明
Keil MDK-ARM	v5.x（须含 ARMCC v5 编译器）	工程锁定 uAC6=0（仅 ARMCC v5，不支持 armclang）；仅支持此工具链，无其他工具链
安装路径	任意目录	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
命令行构建	& '.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， 再生成代码必须用此组合——用更新版本的 CubeMX 会把仓库内 HAL 驱动升级、产生大量无关 diff（见 §六 速查）。 自定义代码只写 USER CODE BEGIN/END 区域内（再生成时保留，KeepUserCode=true），勿手改生成文件的非 USER CODE 区域。

Keil 初始化配置（机器侧项，非项目自带）：

项	配置方法	说明
License	首次启动 UV4 自动生成 90 天评估 license；长期使用需购买正式 license	license 绑定机器、不在仓库；Options for Target → License 查看/输入
Device Pack	Pack Installer 安装 Keil::STM32F4xx_DFP（pack 源 https://www.keil.com/pack/ ）	工程引用的 Flash 算法 STM32F4xx_1024.FLM 就来自此 pack（.uvoptx 的 $$Device:STM32F407ZGTx$ 变量解析到 pack 目录 <Keil安装目录>\PACK\Keil\STM32F4xx_DFP\<ver>\CMSIS\Flash\，如 C:\Keil_v5\...）；pack 缺失则下载失败。Keil::CMSIS pack 不需要：核心头文件由仓库 Drivers/CMSIS/ 提供，.uvprojx 只引用 DFP pack（2026-10-02 本机实测：未装 CMSIS pack 构建 0/0 通过；且 keil.com 的 CMSIS pack 直链（5.7.0~6.1.0）均已下架 404，无从安装）
下载器驱动	工程已配 UL2CM3 调试驱动 + Flash 算法参数（.uvoptx 自带，调试时钟 10 MHz）	物理下载器（ST-Link 等）需装 USB 驱动（见第 8 步）；现场换其他下载器在 Keil Options for Target → Debug → Settings 切换

项目自带、新机器无需重配（随仓库同步）：编译器与目标选项（.uvprojx：ARMCC v5 / 设备 STM32F407ZGTx / Cortex-M4+FPU）、 调试与下载参数（.uvoptx）、Run-Time Environment（MDK-ARM/RTE/）、启动文件 startup_stm32f407xx.s、构建/下载 bat、 RAM/Flash 链接布局（见下）。

RAM / Flash 链接布局（项目自带，自动同步，新机器无需在 Keil 里重设）：

• 链接器使用手动 scatter 文件 MDK-ARM/STM32F407-Demo/STM32F407-Demo.sct（在仓库，.uvprojx 已启用 useFile=1）：
  • ER_IROM1 0x08000000，1 MB（代码 + 只读数据）
  • RW_IRAM1 0x20000000，128 KB（SRAM1 112K + SRAM2 16K 连续；SRAM3/CCM 故意未映射——克隆芯片可能无 SRAM3）
• Keil Options for Target → Target 页显示的片上内存来自 .uvprojx 的 <Cpu> 行（IRAM 112 KB / IRAM2 16 KB / IROM 1 MB，同样在仓库）+ Device Pack
• ⚠ 新机器不要在 GUI 里重填 RAM 区，也勿改 Target 页（会回写共享的 .uvprojx 影响他人）；确需调整内存布局（如日后启用 SRAM3/CCM）时修改 .sct 并提交

2.3 PC 侧编译环境（模拟器 + 主机侧单元测试，必需）

⚠ 本节涵盖两类都要 MSVC 的 PC 侧构建：① LVGL 模拟器（C++，产物 lvgl_sim.exe）； ② 主机侧单元测试（C，批量离线编译真实生产源码，见 §2.10 与 docs/测试说明/看门狗单元测试说明.md）。两者共用同一套 VS 安装，无需装两次。

项	要求	说明
CMake	≥ 3.15	本机实测 4.3.0-rc1；仅模拟器需要，单元测试不用 CMake
编译器	VS2019 / 2022 / 2026 任一（C++ x64 工作负载）	build_sim.ps1 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、-A x64；CMakeLists 已加 /utf-8 消中文注释告警
MSVC C 工具链	同上（cl.exe）	主机侧单元测试的必需项：test/host/<模块>/run_unit_test.py 用 cl.exe 离线编译真实源码。只要装了 VS 就有（VC\Tools\MSVC\<ver>\bin\Hostx64\x64\cl.exe），不额外装东西
Windows SDK	10.0.19041 及以上	CMake 配置与 cl.exe 编译（stdio.h 等）都从这里取；随 VS 工作负载勾选安装
SDL2	2.32.10（预编译，无需系统安装）	不在仓库（simulator/SDL2/ 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见第 3 步。仅模拟器需要
产物	simulator/build/Debug/lvgl_sim.exe	build/ 为生成物（gitignore），可整体删除重建

& "simulator\build_sim.bat"                          # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑）
.\simulator\build\Debug\lvgl_sim.exe                 # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）

# 主机侧单元测试（示例：看门狗判定状态机；纯逻辑、零硬件、秒级）
& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py   # 退出码 0=PASS / 1=FAIL / 2=环境错误

模拟器与 MCU 共用 UI 源码（Drivers/BSP/UI/），无硬件业务（网络推流除外，Winsock 版）。 详见 simulator/README.md、docs/UI设计/LVGL模拟器部署与使用说明.md。

2.4 Python 环境（脚本工具链）

项	要求	说明
统一入口	仓库 .venv\Scripts\python.exe	一切依赖第三方库的脚本（字体生成、截图转 PNG、RemoDispBus 回归）都用它
解释器版本	Python ≥ 3.10（任意发行版）	种子解释器仅用于建 venv 一次；本机为 3.12.4
依赖	fonttools==4.51.0、pillow==10.3.0、pyserial==3.5、pre-commit==4.6.2	清单 = 仓库根 requirements.txt（必须保持纯 ASCII：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError）；pre-commit 入 .venv 后，重建 venv 即可直接跑 L0 门禁（scripts/ci_local.py 自动选用）
入库情况	.venv/ 已 gitignore	换机/首次必须重建

# 重建（<种子python> 换成本机任一 python ≥3.10）
& <种子python> -m venv .venv
& '.venv\Scripts\python.exe' -m pip install -r requirements.txt

⚠ PATH 里默认 python 可能是 msys64 的（无第三方库）——禁止用它跑字体生成 / Pillow 脚本； 纯标准库脚本（UI 回归测试、extract_cn.py）任意 python3 均可。

2.5 中文字体生成依赖

项	要求	说明
Node.js + npm	任意近期版本	一次性：npm i -g lv_font_conv（字体位图转换）
fontTools	仓库 .venv（§2.4）	make_font.py 依赖

python tools/font_gen/extract_cn.py                        # 任意 python3：扫 UI 源码 → ui_cn_chars.txt
& '.venv\Scripts\python.exe' tools/font_gen/make_font.py   # 宋体 12px 1bpp + 字符集 → ui_font_cn_12.c

任何 UI 文案新增汉字后必须走此流程（缺字 = 屏幕空白块），详见 docs/UI设计/UI_中文字体生成与配置.md。

2.6 串口调试 / 自动化测试工具

项	要求	说明
Python 串口助手	.dsh/skills/serial-assistant/scripts/serial_tool.py（仓库内置，.venv + pyserial）	常驻 daemon + 薄 CLI + 全量日志文件；无需单独安装，pip install -r requirements.txt 即就绪
调试串口	USART1（PA9 TX / PA10 RX），115200 8N1	端口单一配置源 .serialtest/config.json（本机 COM6）；换端口只改这个文件
一键测试	.dsh/skills/serial-boot-test/scripts/run_boot_test.py（即 @test，& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py）	开串口 + 清日志 → 烧录 → wait-idle（静默 8s/超时 30s）→ 提取 → 标记校验；默认端口取 .serialtest/config.json / 115200，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法错误

采集 = 端口常开 + daemon 全量日志（.dsh/skills/serial-assistant/scripts/state/serial.log），无采集窗口/first-byte/EOF 重试仪式。 命令契约与陷阱见 docs/测试说明/串口助手设计说明.md、docs/测试说明/自动化测试流程.md。

2.7 代码审查钩子（pre-commit）

项	要求	说明
pre-commit	已安装并 pre-commit install	提交门禁（pre-commit + commit-msg 两类钩子）
cppcheck	在 PATH 中	本地钩子直接调 cppcheck --enable=warning,performance,portability,style（language: system）
python	在 PATH 中	本地钩子调 scripts/check_mojibake.py（U+FFFD 乱码）、scripts/check_coding_standard.py（规范 V1.0，纯标准库）
MSVC cl.exe	装了 VS 即有（§2.3）	watchdog-unit-test 钩子必需：改 App/util/task_watchdog.* 或 test/host/watchdog/** 时触发，用 cl.exe 离线编译真实源码跑单测。未装 VS 时该钩子报环境错误（退出码 2）→ 拦截提交
gitlint	随 pre-commit 自动拉取	commit message 格式（宽松规则，兼容中文标题）

检查范围仅项目自有代码；Lib/、Middlewares/、Drivers/BSP/UI、lftpd、dhara、test/ 等被排除。 全库扫描：pre-commit run --all-files。详见 docs/代码规范/pre-commit使用说明.md、docs/代码规范/cppcheck使用说明.md。

⚠ 新增 L0.5 单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"： 只要装了 VS（§2.3）就自动具备，无需额外安装；但完全未装 VS 的机器在改动看门狗相关文件时会被钩子拦截。

2.8 引用关系图渲染（Graphviz，可选）

项	要求	说明
Graphviz	winget install Graphviz.Graphviz（本机实测 16.1.0）	tools/refgraph 引用关系图生成器的渲染引擎；dot 从 PATH 查找（winget 安装自动入 PATH）；非标准安装目录用 DTU_GRAPHVIZ_DOT 指向 dot.exe（§2.1.1）
必需性	可选	未装时工具自动跳过渲染（仍产出 .dot/.json，装好后重跑即出图）；不影响编译/测试/审查门禁
产物	docs/images/引用关系图.*	文件级 + 模块级 .svg/.dot/.json（随工具提交入库）；PNG 仅本地预览（docs/images/*.png 已 gitignore）

winget install Graphviz.Graphviz
& 'tools\refgraph\gen_refgraph.bat'    # → docs/images/引用关系图.*（.dot/.svg/.png/.json）+ 生成报告

图例、语义（文本层引用/未解析归外部）、更新流程与已知限制见 docs/架构设计/引用关系图说明.md。 Keil 工程包含路径解析自 MDK-ARM/*.uvprojx（自动跟随）；模拟器包含路径变化需同步脚本 SIM_INCLUDE_DIRS。

2.9 开发机一次性搭建（分步安装命令）

以下命令在 PowerShell 中直接执行（新机器从零搭建，全程约 1~2 小时），逐步对照文末清单打勾。

第 1 步：git

winget install Git.Git

手动下载：https://git-scm.com/download/win （Git for Windows）

第 2 步：Keil MDK-ARM v5 + STM32CubeMX（GUI 安装，无命令行方式）

• 下载页：https://www.keil.com/arm/mdk.htm（MDK-ARM v5.x；90 天评估 license 可先开发；必须含 ARMCC v5 编译器——工程锁 uAC6=0，armclang 不行）
• 安装目录任意（装完设置 DTU_KEIL_UV4 = UV4.exe 完整路径，§2.1.1；默认安装位置即可）
• 装完打开 Pack Installer → 安装 Keil::STM32F4xx_DFP（提供 STM32F407ZGTx 设备 + STM32F4xx_1024.FLM Flash 算法；pack 源 https://www.keil.com/pack/ ，Pack Installer 自动拉取）——必装，否则烧录失败（FLM 从 pack 目录解析，不在仓库）。Keil::CMSIS pack 不需要：核心头文件由仓库 Drivers/CMSIS/ 提供（.uvprojx 只引用 DFP pack；CMSIS pack 已被 keil.com 下架，2026-10-02 实测各版本直链均 404）
• License：首次启动 UV4 自动生成 90 天评估 license（长期使用需购买正式 license；license 绑定机器、不在仓库）
• STM32CubeMX 6.17.0：下载页 https://www.st.com/en/tools/stm32cubemx.html （直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe ）
  • 用途：打开仓库 STM32F407-Demo.ioc → 改外设/引脚/时钟 → 生成代码（仅重写 CubeMX 区域，USER CODE 区域保留）
  • 固件包须 STM32Cube FW_F4 V1.28.3（与仓库 HAL 驱动一致；若未随附，在 CubeMX 帮助 → 管理 下载对应包）
  • ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，勿随意用最新版

第 3 步：VS（2019/2022/2026 任一）+ CMake（模拟器工具链 + 主机侧单元测试编译器 MSVC）

winget install Kitware.CMake        # ≥3.15（仅模拟器用；单元测试不用 CMake）

• VS 版本不固定：构建入口 simulator\build_sim.bat 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可

• 这一个 VS 同时提供两样东西：① 模拟器的 C++ 工具链 + CMake 生成器；② 主机侧单元测试的 cl.exe（§2.3 / §2.10）——装一次即可，不需要为单测另装编译器

• 新装选 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（cl.exe 编 stdio.h 等标准头也依赖此处安装的 SDK）

• SDL2 无需系统安装（用预编译 SDK），但不在仓库——simulator/SDL2/ 被 gitignore，git clone 后本地没有；目录不存在时按下面步骤补一次

  补 SDL2 SDK（仅当 simulator/SDL2/ 缺失）

  # 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 脚本工具链）

winget install Python.Python.3.12   # 或任一 ≥3.10；手动：https://www.python.org/downloads/windows/
# 仓库根目录建 venv（种子解释器用刚装的 python 即可）
python -m venv .venv
& '.venv\Scripts\python.exe' -m pip install -r requirements.txt

python 不可用时改用完整路径 & "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe" -m venv .venv。 requirements.txt 必须保持纯 ASCII；之后一切依赖第三方库的脚本只用 .venv\Scripts\python.exe。

第 5 步：Node.js + 字体工具

winget install OpenJS.NodeJS.LTS     # 手动：https://nodejs.org/ （选 LTS）
npm i -g lv_font_conv                # 手动：https://www.npmjs.com/package/lv_font_conv

第 6 步：pre-commit + cppcheck（提交门禁）

winget install astral-sh.uv
uv tool install pre-commit
winget install cppcheck             # 2.21.0（安装位置任意；入 PATH 或用 DTU_CPPCHECK 指向）
# ★ 重开终端（PATH 才生效），然后：
pre-commit install
pre-commit run --all-files          # 首次全库基线扫描

手动下载：uv → https://astral.sh/uv/ （一行安装 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"）· pre-commit → https://pre-commit.com/ · cppcheck 2.21.0 → https://github.com/CppQA/cppcheck/releases （2.21.0 tag 的 Windows x64 zip，解压至任意目录并加入 PATH，或用 DTU_CPPCHECK 指向 cppcheck.exe）

第 7 步：Python 串口助手（串口调试 / 自动测试，仓库内置）

无需单独安装：.dsh/skills/serial-assistant/ 随仓库提供，依赖 pyserial（已入 requirements.txt，第 4 步建 .venv 时一并安装）。建成后验证：

& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py selftest   # → SELFTEST PASS
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py ports      # 枚举 COM 口

第 8 步：下载器驱动（ST-Link）

• ST 官网下载 STM32CubeProgrammer 运行一次（自动安装 ST-Link USB 驱动）：https://www.st.com/en/development-tools/stm32cubeprog.html
• 仅需要 ST-Link V2 驱动时：https://www.st.com/en/development-tools/stm321025.html （ST-LinkV2-USB-Driver 包）
• Keil Options for Target → Debug 确认驱动与实物一致（工程已配 UL2CM3 框架）

第 9 步：串口配置

& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py ports   # 查 COM 号

把查到的端口写入 .serialtest\config.json 的 portName（唯一配置源，换口只改这里）。

第 10 步：冒烟验证（全过 = 环境就绪；前置：§2.1.1 的 DTU_* 变量已设置——未设时构建脚本会明确报出缺哪个变量及设置方法）

& '.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
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update  # 首次生成参考图
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py       # 再跑 → PASS
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py selftest     # → SELFTEST PASS
& '.venv\Scripts\python.exe' test\host\watchdog\run_unit_test.py            # 主机侧单测 → 39/39 PASSED（退出码 0）
pre-commit run --all-files

搭建清单汇总（随步骤逐项打勾）：

• Windows 10/11 x64 + PowerShell 5.1+
• Keil MDK-ARM v5.x 已装（任意目录，DTU_KEIL_UV4 已设 UV4.exe 完整路径，§2.1.1）+ STM32F4 DFP 包（CMSIS pack 不需要，见 §2.2）
• STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
• VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本；同一 VS 提供主机侧单测所需的 cl.exe，见 §2.3 / §2.10）
• git clone 仓库 → pre-commit install；cppcheck 入 PATH
• 建 .venv 并 pip install -r requirements.txt
• npm i -g lv_font_conv
• 写好 .serialtest/config.json（本机 COM 口），serial_tool selftest PASS
• 下载器（ST-Link 等）USB 驱动已装，Keil Options for Target → Debug 驱动一致
• 第 10 步冒烟验证全部通过（含 test/host/watchdog/run_unit_test.py → PASSED）
• （可选）Graphviz 已装（引用关系图渲染：winget install Graphviz.Graphviz，见 §2.8）

2.10 手动下载来源速查

§2.9 中需下载组件的官方下载地址汇总（正文的 winget / 命令行方式优先；网络受限时按本表手动下载）：

组件	官方下载页	版本 / 说明
Git for Windows	https://git-scm.com/download/win	最新稳定版
Keil MDK-ARM	https://www.keil.com/arm/mdk.htm	v5.x，须含 ARMCC v5；安装目录任意（DTU_KEIL_UV4 设 UV4.exe 完整路径）
STM32F4xx DFP	https://www.keil.com/pack/	在 Keil Pack Installer 内装 Keil::STM32F4xx_DFP（CMSIS pack 不需要/已下架，见 §2.2）
STM32CubeMX	https://www.st.com/en/tools/stm32cubemx.html	6.17.0（与 .ioc 一致）；直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe
STM32Cube FW_F4（固件包）	https://www.st.com/en/embedded-software/stm32cube-f4.html	V1.28.3（与仓库 HAL 驱动一致）
Visual Studio 2019	https://visualstudio.microsoft.com/zh-hans/vs/archives/	直链：https://aka.ms/vs/16/release/vs_community.exe
Visual Studio 2022 / 2026	https://visualstudio.microsoft.com/zh-hans/downloads/	任一版本均可（模拟器构建 + 主机侧单测 cl.exe，二者共用）
CMake	https://cmake.org/download/	≥ 3.15
Python	https://www.python.org/downloads/windows/	≥ 3.10，推荐 3.12
Node.js	https://nodejs.org/	LTS
lv_font_conv	https://www.npmjs.com/package/lv_font_conv	一般 npm i -g lv_font_conv
uv	https://astral.sh/uv/	powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
pre-commit	https://pre-commit.com/	一般 uv tool install pre-commit
cppcheck	https://github.com/CppQA/cppcheck/releases	2.21.0 的 Windows x64 zip（cppcheck-2.21.0-windows-x64.zip 形式），解压入 PATH
STM32CubeProgrammer	https://www.st.com/en/development-tools/stm32cubeprog.html	含 ST-Link USB 驱动
ST-Link V2 驱动	https://www.st.com/en/development-tools/stm321025.html	ST-LinkV2-USB-Driver 包
SDL2（仅仓库预编译库缺失时）	https://github.com/libsdl-org/SDL/releases	2.32.10，一般不需要
Graphviz	https://graphviz.org/download/	一般 winget install Graphviz.Graphviz；未装时引用关系图工具跳过渲染（§2.8），不阻塞其他工具链

获取渠道优先级：① winget（自动校验、免手动）→ ② 上表官方页 → ③ 网络受限时自行选可信镜像； Keil / ST 官网访问受限时可走代理。

2.11 CI runner 环境（Gitea Actions，2026-10-01 T-6）

CI 跑 L0 静态门禁 + L0.5 主机侧单测（不含 L1/L2/L3——需真机 + ST-LINK，只在本地）。 workflow 见 .gitea/workflows/ci.yml；覆盖边界与判定细节见 ../测试说明/测试开发标准流程.md §9。

项	要求	说明
Gitea 版本	≥ 1.21（实测远程 1.25.4）	workflow 置于 .gitea/workflows/，兼容 GitHub Actions 语法
Actions 开关	实例 [actions] ENABLED = true	site admin 配置；未开启则 push 不触发任何 job
runner OS	Windows（runs-on: windows）	labels 须含 windows；与开发机同平台，避免脚本语法分叉
runner 软件	Python 3.x、cppcheck、pre-commit、MSVC（VS C++ 工具链 + Windows SDK）	前三个缺 → l0-gates 硬失败（::error::）；MSVC 缺 → l05-host-unit-tests 降级跳过并告警（不硬失败，但等于 L0.5 裸奔）。runner 以 SYSTEM 服务运行，用户级 PATH/变量不可见：自动发现失败时用机器级 DTU_PRECOMMIT_PYTHON / DTU_CPPCHECK / DTU_MSVC_CL 注入（见 Gitea_Runner部署指南.md 环境变量节，§2.1.1）
Keil	不需要	刻意不跑 @build（需授权）；.map 缺失时 mem-numbers 钩子自动跳过
mem-numbers	有 .map 就跑，无则 SKIP	Keil 构建产物 .map 已 gitignore；自建带 Keil 的 runner 会照常跑该钩子

runner 就绪前的过渡：CI 只是"多一道网"，不能替代本地门禁。提交前仍须在本地跑：

& '.venv\Scripts\python.exe' scripts/ci_local.py    # 与 CI 同一套判定（L0 + L0.5）

2.12 跨机验证（第二台机器 / 换机验收清单）

验收判据（对应 本地工具路径环境变量方案.md 的最终验收）：新电脑只按 §2.1.1 配置本机 DTU_* 变量，clone 仓库后不修改任何 .bat/.py/.ps1/.yml 中的本机路径即可运行开发命令。 工具安装清单同 §2.9 第 1~8 步（刻意指定与旧机不同的安装目录，才能真正验证跨路径）； 按下表顺序执行，任一步不达预期即停下排查。

第 1 步：配置变量 + sanity check

# 用户级（无需管理员）；值填本机实际安装路径
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4',   '<本机 UV4.exe 完整路径>', 'User')
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', '<本机 ST-LINK_CLI.exe 完整路径>', 'User')
# ★ 关闭并重开终端（旧终端持有设置前的环境快照——最常见的"假失败"来源）
# 重开后验证：
Test-Path $env:DTU_KEIL_UV4     # True
Test-Path $env:DTU_STLINK_CLI   # True

第 2 步：验证链（每步有明确期望；①②③④ 全过 = 该机器验证通过）

#	命令	期望	失败诊断
①	& <任一 python> -m venv .venv + & '.venv\Scripts\python.exe' -m pip install -r requirements.txt	安装完成且含 pre-commit	pip 报 GBK 解码错 = requirements.txt 被污染（该文件必须纯 ASCII，不该发生）
②	& '.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
⑥	（有 ST-LINK 硬件才执行）& "MDK-ARM\reset.bat" list	列出探针 SN	只跑 list，不烧录不复位；无硬件跳过不扣分

第 3 步：反向测试（验证"显式值无效 = 硬报错、不静默回退"语义，约 1 分钟）

$env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe'   # 仅当前会话，不动用户级值
& '.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 安装，而是明确报错
# 测完重开终端即恢复（用户级值未动）

通过判定：①②③④ 全过 = 该机器验证通过（⑤ 的既有 CMake 问题、⑥ 无硬件跳过均不扣分）。 两台不同安装路径的机器都通过 = 环境变量方案的跨机验收闭环（方案阶段 C 出口标准）。

---

三、目标板环境（DTU 硬件）

3.1 主芯片

项	值	说明
MCU	STM32F407ZGTx	Cortex-M4（双精度 FPU / TrustZone），LQFP144
主频	168 MHz	HSE 8 MHz → PLL M=4 / N=168 / P=2（Inc/stm32f4xx_hal_conf.h）
Flash	1 MB（0x08000000）	片内
SRAM	192 KB（128 KB 主 + 64 KB CCM）	当前仅用主 SRAM 128 KB；SRAM3/CCM 未映射（§3.3）
RTOS	FreeRTOS V10.3.1（CMSIS-RTOS V2）	HAL 时基 TIM7，tick = 1 ms；NVIC 4 位抢占，外设中断优先级 ≥5

3.2 外设硬件要求（引脚级）

外设	接口	引脚	备注
CH395F 以太网	SPI2	PB12 CS / PB13 SCK / PB14 SDO / PB15 SDI	PHY 强制 100M 全双工；SPI 分频系数必须为 8（PCB 设计约束，速度受限）
GD5F2GQ5UE NAND（2 Gbit）	SPI1	PE0 CS / PB3 SCK / PB4 MISO / PB5 MOSI / PB8 WP / PE1 HOLD	FatFS（FAT32）+ dhara FTL；上电无卷自动 f_mkfs
TPAFE5160 ADC	并行 16 位	PG0~PG15 数据 / PD3 RD / PD4 CONVST / PD7 BUSY	编译期常驻（app_cfg.h 的 APP_ADC_ENABLE 为未接线占位，不门控本模块）
USART1（调试串口）	UART	PA9 TX / PA10 RX	115200 8N1；printf 日志 + @test 采集通道
UART5（RS-485）	UART	PC12 TX / PD2 RX / PD0 DE	半双工；编译期常驻（APP_RS485_ENABLE 为未接线占位）
状态 LED ×6	GPIO	PC4 / PC5 / PB1 / PB2 / PF11 / PF12	低电平点亮

3.3 资源预算（部署红线）

实测（2026-09-11 快照口径，现汇总于 docs/内存管理/RAM使用分析与优化方案.md）：

资源	已用	总量	利用率	余量	红线说明
Flash	232,000 B（226.6 KB）	1 MB	22.1%	~798 KB	充裕
主 SRAM（静态区+堆）	125,104 B（122.2 KB）	128 KB	95.4%	5.8 KB	极度紧张：新增任何静态缓冲/任务栈前必须先核算 RAM 余量

• LVGL 内存池 40 KB（静态占用）；FreeRTOS 堆 48 KB
• 任务栈预算（words，1 word = 4 B）：

任务	栈大小	优先级
defaultTask	1024	Normal
netTask	960	Normal
ftpTask	1024	Normal
testTask	2048	BelowNormal
uiTask	4096	BelowNormal
timeSyncTask	512	Normal

上表由 scripts/gen_task_table.py 同源（唯一来源 Src/freertos.c / .ioc 的 FREERTOS.Tasks01）； 2026-10-10 栈整改未改任何栈值，靠削调用链达标（详见 docs/内存管理/RAM使用分析与优化方案.md）。

挖潜方向（未实施）：SRAM3 64 KB / CCM 64 KB 未映射——详见 docs/内存管理/。 部署侧含义：不要做任何需要额外 RAM 的固件定制，新增功能先过内存预算。

3.4 下载与调试

项	说明
下载方式	& "MDK-ARM\download.bat"（Keil 命令行：烧写 + Reset & Run）
下载器	工程已配 UL2CM3 调试驱动 + STM32F4xx_1024 Flash 算法；物理下载器按现场选择（本机为 ST-Link——不占 COM 口，可与串口调试并存）；新机器在 Keil Options for Target → Debug → Settings 选择与硬件一致的驱动
调试日志	USART1 115200；抓开机日志必须先武装采集再复位（.dsh/skills/serial-boot-test/scripts/run_boot_test.py --flash-cmd 已保证顺序）

3.5 功能配置开关

开关	位置	当前值	说明
APP_NET_ENABLE / APP_ADC_ENABLE / APP_RS485_ENABLE	App/app/app_cfg.h	全定义	未接线占位，不门控任何代码（P2-12，2026-10-04 核实）：三个宏全库零消费点，各模块一律编译进产品；"能否裁剪"取决于产品定义（待处理内容.md §2 阶段 B0），落定后再接入真实门控。不要把它们当开关
TEST_SUITE_*	test/board/test_config.h	全注释（产品构建）	测试套件互斥：一次构建只开一个（CH395F / 存储 / GD5F / RTC）；全注释 = 正常产品固件

---

四、网络与现场部署

4.1 网络参数

参数	工厂默认	修改方式
IP	192.168.1.100（静态，无 DHCP）	屏幕 通讯参数 → 网口设置（修改密码 123）保存后立即生效（网络重建约 1~3 s）；或预置 /config.ini（INI；旧版 /cfg/netcfg.bin 不再读取——存在则忽略、不迁移，配置回落工厂默认，2026-10-10 起）
子网掩码	255.255.255.0（/24）	同上
默认网关	192.168.1.1	同上
MAC	全零 = 芯片内置 MAC	同上（全零是"使用芯片内置 MAC"的哨兵，不是"MAC 为 0"）
PHY	强制 100M 全双工	固件固定，不可配

• 配置持久化：NAND 上通用配置文件 /config.ini（INI [network] 段；缺失/损坏回退工厂默认并重建模板，不带崩网络）
• 立即生效机制：保存 → netTask 重建网络 → 代次号递增 → 三个 TCP 服务自动重建监听（既有连接会断开，属预期）

4.2 服务端口（现场连通性核对）

服务	协议/端口	用途	核对方法
远程显示（RemoDispBus）	TCP 7003	远端看图（160×160 1bpp，3200 B/帧，客户端 LCDMEM 拉取）+ 远端导航按键	DTU-RemoteLCD 或任意 TCP 客户端连 7003 收帧
墙钟对时	TCP 8888	PC 主动推送时间到设备	对时推送后核对设备时间 / 日志时间戳
FTP	TCP 21	文件上传/下载（根目录 /，NAND 存储）	任意 FTP 客户端列目录/读写

现场组网要求：设备与客户端同网段（默认 .100/24、网关 .1）；跨网段部署先按 §4.1 改 IP 再上线。

4.3 存储与运行时

• 文件系统：FatFS（FAT32）挂 NAND；上电无卷自动格式化（f_mkfs）；格式化会清除卷上全部文件（含网口配置 /config.ini）
• RTC：SD2506 芯片（驱动 Drivers/BSP/SD2506/）提供墙钟基准与日志时间戳；首次使用建议先经 8888 对时
• 启动时序：app_main_init（存储 → 时钟 → RS485 → NAND → ADC → 启动转换）→ 就绪屏障（STORAGE / NET / FTP / TIMESYNC 事件）→ 六任务运行；详见 docs/架构设计/项目启动顺序管理.md、docs/架构设计/项目架构总览.md

4.4 现场验收清单

#	项目	方法	通过标准
1	上电自启动	断电上电 + 串口采集	@test PASS：Required App init OK;Network Init;net init: OK;PHY: 100M FULL，无 FAIL/ERROR/HardFault
2	网络连通	PC ping 192.168.1.100	通（PHY 100M FULL）
3	远程显示	DTU-RemoteLCD 连 7003	出图（160×160 1bpp）+ 远端菜单导航可用
4	FTP	FTP 客户端连 :21	列目录 / 读写 / 下文件
5	UI 功能	屏幕 / 远端操作	菜单 7 项导航、内容页、密码（查看 000 / 修改 123）、网口设置保存后立即生效
6	对时	PC 推送 8888	设备墙钟更新、日志时间戳正确
7	掉电保持	写文件 / 改网口配置 → 重启	数据仍在（/config.ini 按新值生效）
8	LED 状态	目检	6 路 LED 随系统状态变化（低电平点亮）

---

五、远端客户端环境

项	要求	说明
操作系统	任意（Windows / Linux / macOS，有浏览器或 Python 即可）	与设备同网段
远程显示客户端	DTU-RemoteLCD（独立项目：Flask + WebSocket 参考实现）或任意符合 RemoDispBus 协议的 TCP 客户端	连设备 TCP 7003；协议见 docs/UI设计/RemoDispBus协议与接收设计说明.md
对时工具	任意可 TCP 推送的工具/脚本	向设备 8888 推送
FTP 客户端	任意（资源管理器 / FileZilla 等）	设备端 lftpd，端口 21
浏览器	Chrome / Edge	查看参考客户端 Web 页；开发期浏览文档 SVG 图

客户端侧无强制版本依赖——协议是纯 TCP 字节流（[TAG][CMD][LEN][DATA][CRC] 帧）， 任何语言均可实现；单连接模型（同一时刻一个客户端）。

---

六、常见环境问题速查

现象	原因	处理
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 重新生成
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 文件校验）
run_unit_test.py 退出码 2 / 报"找不到 MSVC cl.exe"	本机未装 VS（C++ 工作负载）	按 §2.3 装 VS2019/2022/2026（勾"使用 C++ 的桌面开发"），装完即有 cl.exe；提交看门狗相关改动时该钩子会拦截，必须装
run_unit_test.py 编译报 C1083: 无法打开包括文件 "stdio.h"	VS 未勾选 Windows SDK，或 cl.exe 路径异常	在 VS Installer 里补勾 Windows 10/11 SDK；脚本已按本机 VS/SDK 目录自动拼 INCLUDE/LIB，无需手动 vcvars64.bat（其内部 reg.exe 在受限机器上会被安全策略拦截）
.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
内容页回归 exit 2（参考缺失）	tests/ref/ 是本地生成物、不入库	先 check_content_pages.py --update 生成参考，再跑回归
串口采集不到 / 端口占用	COM 号变化 / 上一进程未释放	改 .serialtest/config.json；serial_tool.py ports 查实际端口，open 占用 ≤1s 报 port busy
烧录失败	下载器未选 / USB 驱动缺失	Keil Options for Target → Debug 选对驱动；安装下载器 USB 驱动
下载报 Flash 算法 / FLM 文件找不到	未安装 Keil::STM32F4xx_DFP pack（FLM 来自 pack 目录，不在仓库）	Pack Installer 安装该 pack 后重新下载
UV4 启动弹 license 窗口 / 无法编译	90 天评估 license 过期或未激活	Options for Target → License 查看/输入；长期使用购买正式 license
提交被钩子拦截	cppcheck / 规范 / 乱码 / gitlint 任一失败	按 pre-commit 输出逐项修复；禁止 --no-verify 跳过门禁
改代码后"没生效"	新 .c 漏双端注册 / 模拟器缓存	走 new-source-file 双端注册流程；cmake --build 增量或删 simulator/build/ 重建

---

七、相关文档

主题	文档
项目全景架构	docs/架构设计/项目架构总览.md
启动顺序 / 就绪屏障	docs/架构设计/项目启动顺序管理.md
内存预算详析 / 优化方案 / 栈观测	docs/内存管理/RAM使用分析与优化方案.md（主文档）· docs/内存管理/内存内容分配策略.md（区域与 DMA 规则）
网口配置 / 生效链路	docs/子系统设计/网络配置说明.md
远程显示协议	docs/UI设计/RemoDispBus协议与接收设计说明.md
LVGL 模拟器部署	docs/UI设计/LVGL模拟器部署与使用说明.md、simulator/README.md
串口调试 / 自动化测试	docs/测试说明/串口助手使用指南.md、docs/测试说明/串口助手设计说明.md、docs/测试说明/自动化测试流程.md
测试分层 / L0.5 主机侧单测	docs/测试说明/测试开发标准流程.md（分层与门禁）· docs/测试说明/看门狗单元测试说明.md（L0.5 范式：MSVC 离线编译 + 平台桩）
CI（Gitea Actions）	docs/环境与部署/Gitea_Runner部署指南.md（Runner 端部署全流程：下载 / 注册 / 常驻 / 排障，针对本机原生 Gitea 定制）· docs/环境与部署/CI配置指南.md（服务端 + workflow 全流程）· docs/测试说明/测试开发标准流程.md §9（覆盖边界）
pre-commit / cppcheck	docs/代码规范/pre-commit使用说明.md、docs/代码规范/cppcheck使用说明.md
引用关系图（文件引用）	docs/架构设计/引用关系图说明.md（生成工具 tools/refgraph；渲染依赖 Graphviz，§2.8）
各模块测试指南	docs/测试说明/CH395F_Test_Guide.md、GD5F2GQ5UE_Test_Guide.md、SD2506_Test_Guide.md、FTP_Test_Guide.md
已知硬件陷阱	docs/问题记录/CH395F_Trap_Records.md 等

---

变更记录

日期	变更
2026-10-10	删除旧档 NCFG 迁移（升级/迁移口径变更）：旧固件遗留的 /cfg/netcfg.bin 不再"首启自动迁移"——旧档若存在则被忽略（不读、不删、不迁移），配置直接回落工厂默认（/config.ini [network] 段模板）。net_cfg_legacy.c/h 与 cfg_store_legacy_path() 已移除；携带旧档的设备升级后需经 UI 或 FTP 重新配置网口。§五 现场部署 IP 行同步
2026-10-02	模拟器构建修复（配置引擎重构遗留）：simulator/CMakeLists.txt 的配置文件引擎引用同步到迁移后位置——包含目录 App/→App/cfg/（cfg_file.h/cfg_file_store.h）、源文件 App/cfg_file.c→App/cfg/cfg_file.c、包含目录 test/→test/board/（test_config.h/net_latency_test.h）；全量 include 离线核查无其他断链，模拟器全量构建恢复（--cfgtest 四场景 PASS，rc=0）。§2.12 验证链 ⑤ 行同步更新
2026-10-02	更正 Device Pack 必装范围：Keil::CMSIS pack 不再列为必装项——本工程不依赖它（核心头文件由仓库 Drivers/CMSIS/ 提供，.uvprojx 只引用 DFP pack；2026-10-02 本机实测未装 CMSIS pack 构建 0/0 通过），且其 keil.com 直链（5.7.0~6.1.0）均已下架 404；必装的只有 Keil::STM32F4xx_DFP（3.1.1，与 .uvprojx PackID 一致）。§2.2 / 第 2 步 / 搭建清单 / §2.10 同步更正
2026-10-02	新增 §2.12「跨机验证（第二台机器 / 换机验收清单）」：变量配置 + sanity check → 六步验证链（含期望结果与失败诊断，含模拟器既有 CMake 问题标注）→ 反向 fail-fast 测试 → 通过判定，作为方案跨机验收的标准操作
2026-10-02	本地工具路径环境变量方案落地（本地工具路径环境变量方案.md）：仓库脚本不再含本机绝对工具路径——10 处调用点（build/download/reset.bat、_build.cmd 退役、ci_local.py、ci.yml、gen_refgraph.py、unit_test_harness.py、build_sim.ps1、make_font.py）统一改为"DTU_* 变量优先 + 自动发现回退"（显式设置但无效 = 硬报错，不静默回退）；新增 §2.1.1 变量清单/设置方法/解析语义；Keil 安装路径、Graphviz、cppcheck、VS/SDK 自动探测、Python 重建示例与速查表同步改为变量口径；requirements.txt 增 pre-commit（重建 .venv 即可直接跑 L0 门禁）；本机已按 §2.1.1 配置用户级 DTU_KEIL_UV4/DTU_STLINK_CLI 并全链路验证（@build 0/0、ci_local L0+L0.5 全绿、refgraph 重生成、reset 探针识别）
2026-10-02	新增 Gitea_Runner部署指南.md：针对本机 Gitea 原生部署（D:\Docker\Gitea\gitea.exe + Windows 服务 + 127.0.0.1:3001）定制的 Runner 端全流程——下载 / register（--instance 用回环、--labels "windows:host" 必须精确匹配 runs-on）/ config.yaml / daemon install 常驻 / 软件与 PATH 坑 / MSVC 路径约束 / 内网 action 零依赖改法 / 排障表 / check_env.ps1 自检脚本；§七相关文档登记
2026-10-01	新增 CI配置指南.md（Gitea Actions 配置全流程：服务端 [actions] ENABLED / Windows runner 注册（--labels "windows:host"）/ runner 软件环境与 PATH / workflow 位置与触发 / 内网拉不到 actions/checkout 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记
2026-10-01	新增 §2.11 CI runner 环境（Gitea Actions，T-6）：Gitea ≥1.21（实测 1.25.4）+ [actions] ENABLED + Windows runner（装 Python/cppcheck/pre-commit/MSVC）；不需要 Keil（刻意不跑 @build，无 .map 时 mem-numbers 自动跳过）；补"CI 不能替代本地门禁"与 scripts/ci_local.py 过渡命令
2026-10-01	补主机侧单元测试（L0.5）环境要求：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确同一套 VS 的 cl.exe 同时服务模拟器与单测，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 watchdog-unit-test 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 cl.exe 缺失与 C1083 stdio.h 两条）/ 相关文档同步；总览拓扑图加 MSVC cl.exe 节点
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 手动下载来源速查表
2026-09-15	串口调试/自动测试工具由 serial-mcp-server 切换为仓库内置 Python 串口助手（serial_tool，.venv + pyserial，免安装）：§2.4 依赖清单、§2.6、§2.8 第 7/9/10 步、搭建清单、§2.9 下载表（去 Rust/serial-mcp-server）、速查表、相关文档同步
2026-09-13	补 STM32CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3（与 .ioc 一致）：拓扑图 / §2.2 / 第 2 步 / §2.9 / 搭建清单，常见问题速查增加再生成版本不匹配条目
2026-09-13	新增"Keil 初始化配置（机器侧项，非项目自带）"：license / Device Pack（含 FLM 来源解析路径）/ 下载器驱动，并列出项目自带免配置项；§六 速查补 FLM 缺失、license 过期两条
2026-09-13	补 RAM/Flash 链接布局说明：手动 scatter 文件 STM32F407-Demo.sct（在仓库）为链接依据（128KB = SRAM1+SRAM2，SRAM3/CCM 未映射），新机器无需重设、勿改 GUI Target 页