Files

T

wandering1 a7f526569a perf(mem): R-9 落地——LVGL 池 40→16 KB，SRAM1 74.9%→56.1%

取值依据是实测水位，不是预估：菜单根框 5,368 B、开页-关页往返
5,448 B、最重页面峰值 6,568 B（占 16 KB 的 40%）、真机开机
used=3,192 B。注意 16,384 B 建池后 lv_mem_monitor 报的 total 是
15,020 B（TLSF 控制块与对齐元数据 ≈1,364 B），核算余量用后者。

两端 lv_conf.h 同步改值（lv-conf-sync 生效值比对 163 项 PASS），
Lib/lv_conf.h 的 UTF-8 BOM 已按原样补回（Edit 会静默剥掉）。

验证：
- @build 0 错 0 警；ZI 154,456 → 129,880，精确 −24,576 B
- SRAM1 98,144/74.9% → 73,568/56.1%（余 57,504 B）；CCM 不变 87.9%
- 模拟器菜单回归 PASS（8 状态像素 + 池基线 5,368 B 未变）；11 页
  黄金参考逐字节 10/11 一致，往返池水位 5,448 B 分毫未变
- 唯一差异 netcfg_save 保存态：用 40 KB 旧池做 A/B 复测同样失败，
  确认与本改动无关（属 506eccc 的 cfg_file 行为变化），未刷黄金
  参考掩盖，留给该改动属主处置
- @test PASS：fw build Oct 15 2026 07:31:34，无 [ERR]/Fault，
  开机 622 ms 到 net init: OK，menu build done: used=3192
- 本地 CI 全绿（L0 + L0.5，15 runner / 955 断言）
- 台账受管区与内存快照区已 --write 回填，mem-budget / mem-numbers
  由红转绿

连带结论：R-2 后半待迁体量 54,146 → 29,570 B，瓶颈由 SRAM1 换到
CCM（只剩 7,904 B）；解锁链第 ① 步完成，下一步只差缩堆 56→32 KB
（B5 是反向扩容，缩回前须重跑 stack_report.py + 上板 min_ever）。

文档同步 20 处：本报告按修复即销项删除 R-9 行，并改写 §0.2/§0.3/
§0.4/§5.1/§5.2/§5.3/§6.4 与变更记录、去处表；RAM使用分析 §2.6.2
新增实测水位表、阶段 1.1 标已执行；台账 §3 解锁链、登记簿 N-27、
任务规划 README W3 行与链路图；UI 四篇、产品需求、内存内容分配
策略、运行与自检记录、项目部署环境要求、测试开发标准流程、
simulator/README、ui-verify skill 常量。顺带订正三处与脚本不符的
旧值：池水位常量 4784/4864 → 5368/5448、FreeRTOS 堆 48 → 56 KB。

2026-10-15 09:56:15 +08:00

54 KiB

Raw Blame History

项目部署环境要求

版本：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 构建机）	UV4.exe 完整路径	`keil_build.py`（`@build`）
`DTU_STLINK_CLI`	必需（用 ST-LINK CLI 的机器；已在 PATH 可不设）	ST-LINK_CLI.exe 完整路径	`stlink_flash.py`（烧录/复位/回读）
`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 用机器级变量注入（见 docs/CI/远程CI完整指南.md §4.1.3）。

2.2 MCU 构建工具链（必需）

项	要求	说明
Keil MDK-ARM	v5.x（须含 ARMCC v5 编译器）	工程锁定 `uAC6=0`（仅 ARMCC v5，不支持 armclang）；仅支持此工具链，无其他工具链
安装路径	任意目录	`keil_build.py` / `stlink_flash.py` 经 `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`）	退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt`
命令行烧录	`& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py flash`（即 `@download`）	烧后 `-Rst -Run`；判据 `Programming Complete` + 回读 `No difference found`

⚠ 版本一致性关键：.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` 注入（见 `docs/CI/远程CI完整指南.md` §4.1.3）
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 硬件才执行）`& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py 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 内存池 16 KB（静态占用，2026-10-15 由 40 KB 收缩）；FreeRTOS 堆 56 KB（CCM）
任务栈预算（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 下载与调试

项	说明
下载方式	`& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py flash`（ST-LINK_CLI：烧写 + 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 核实）：三个宏全库零消费点，各模块一律编译进产品；"能否裁剪"取决于产品定义（docs/任务规划/README.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` 报 `DTU_KEIL_UV4` 未设/无效	`DTU_KEIL_UV4` 未设置或指向错误路径（设完变量须重开终端）	设置/修正 `DTU_KEIL_UV4` 为 UV4.exe 完整路径（§2.1.1），重开终端重试
`stlink_flash.py` 报 `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/CI/README.md`（远程 CI 唯一入口：服务端 / Runner 部署与保活 / workflow / 排障，仅本机一台 runner，日常开发不必读）· `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-12	远程 CI 文档迁出本目录：`CI配置指南.md` 与 `Gitea_Runner部署指南.md` 合并为 `docs/CI/远程CI完整指南.md`（入口 `docs/CI/README.md`），本文三处引用改指新路径与新章节号（§4.1.3 机器级变量、§7 相关文档登记）。原因：远程 CI 只涉及本机一台 runner，不应与"任何机器都要过"的部署核对清单混在一起
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 页

54 KiB Raw Blame History Unescape Escape