环境文档增补跨机验证清单：项目部署环境要求新增§2.12（变量配置+六步验证链+反向fail-fast测试+通过判定），方案文档待办项交叉引用
This commit is contained in:
@@ -178,5 +178,5 @@ Test-Path -LiteralPath $env:DTU_KEIL_UV4
|
||||
## 变更记录
|
||||
| 日期 | 变更 |
|
||||
|---|---|
|
||||
| 2026-10-02 | **实施完成**：阶段 A~D 落地。① 10 处调用点全部改为"`DTU_*` 变量优先 + 自动发现回退"（显式值无效 = 硬报错、不静默回退）：`build/download/reset.bat`（goto 标签式解析，纯 ASCII）、`ci_local.py`（`DTU_PRECOMMIT_PYTHON` 严格校验）、`ci.yml`（`DTU_PRECOMMIT_PYTHON`/`DTU_CPPCHECK`/`DTU_MSVC_CL`/`DTU_WINDOWS_KITS_ROOT`，run 块纯 ASCII）、`gen_refgraph.py`（`DTU_GRAPHVIZ_DOT`→PATH，保留无渲染降级）、`unit_test_harness.py`（`DTU_MSVC_CL`/`DTU_WINDOWS_KITS_ROOT` + `%ProgramFiles*` 推导取代静态盘符列表）、`build_sim.ps1`（`DTU_VSWHERE`→`%ProgramFiles(x86)%` 推导，去字面 C 盘回退）、`make_font.py`（`%WINDIR%` 推导）；`_build.cmd` 确认零调用后删除。② 本机按 §5.2 配置用户级 `DTU_KEIL_UV4`/`DTU_STLINK_CLI`（其余工具本机均可自动发现，未设变量），验证：`@build` BUILD_OK 0/0、`ci_local.py` L0 15 钩子 + L0.5 278/278 断言全绿、refgraph 重生成（含修复 `引用关系图.json` 末尾换行缺失导致的 end-of-file-fixer 抖动，生成器补 `f.write("\n")`）、`build_sim.ps1` vswhere 推导命中 VS2026（模拟器 CMake 配置期暴露**既有**问题：`App/cfg_file.c` 已移入 `App/cfg/` 但 `simulator/CMakeLists.txt` 仍指旧路径——与本改造无关，留待配置引擎重构方处理）、`reset.bat list` 识别探针。③ 文档收口：`AGENTS.md`/`MDK-ARM/README.md`/`项目部署环境要求.md`（新增 §2.1.1）/`Gitea_Runner部署指南.md`（新增 §5.1.3 机器级变量）/`CI配置指南.md`/`pre-commit使用说明.md`/字体/测试流程/引用图说明/ST-LINK 说明/实机规划/`scripts/README.md` 共 12 篇同步为变量口径。④ `requirements.txt` 增 `pre-commit==4.6.2`（重建 `.venv` 即可跑 L0）。⑤ 全量 `pre-commit --all-files` + `ci_local.py` 通过。待办：新 workflow 推送远程后跑一次 CI 两 job 闭环验证；第二台不同安装路径机器的交叉验证 |
|
||||
| 2026-10-02 | **实施完成**：阶段 A~D 落地。① 10 处调用点全部改为"`DTU_*` 变量优先 + 自动发现回退"（显式值无效 = 硬报错、不静默回退）：`build/download/reset.bat`（goto 标签式解析，纯 ASCII）、`ci_local.py`（`DTU_PRECOMMIT_PYTHON` 严格校验）、`ci.yml`（`DTU_PRECOMMIT_PYTHON`/`DTU_CPPCHECK`/`DTU_MSVC_CL`/`DTU_WINDOWS_KITS_ROOT`，run 块纯 ASCII）、`gen_refgraph.py`（`DTU_GRAPHVIZ_DOT`→PATH，保留无渲染降级）、`unit_test_harness.py`（`DTU_MSVC_CL`/`DTU_WINDOWS_KITS_ROOT` + `%ProgramFiles*` 推导取代静态盘符列表）、`build_sim.ps1`（`DTU_VSWHERE`→`%ProgramFiles(x86)%` 推导，去字面 C 盘回退）、`make_font.py`（`%WINDIR%` 推导）；`_build.cmd` 确认零调用后删除。② 本机按 §5.2 配置用户级 `DTU_KEIL_UV4`/`DTU_STLINK_CLI`（其余工具本机均可自动发现，未设变量），验证：`@build` BUILD_OK 0/0、`ci_local.py` L0 15 钩子 + L0.5 278/278 断言全绿、refgraph 重生成（含修复 `引用关系图.json` 末尾换行缺失导致的 end-of-file-fixer 抖动，生成器补 `f.write("\n")`）、`build_sim.ps1` vswhere 推导命中 VS2026（模拟器 CMake 配置期暴露**既有**问题：`App/cfg_file.c` 已移入 `App/cfg/` 但 `simulator/CMakeLists.txt` 仍指旧路径——与本改造无关，留待配置引擎重构方处理）、`reset.bat list` 识别探针。③ 文档收口：`AGENTS.md`/`MDK-ARM/README.md`/`项目部署环境要求.md`（新增 §2.1.1）/`Gitea_Runner部署指南.md`（新增 §5.1.3 机器级变量）/`CI配置指南.md`/`pre-commit使用说明.md`/字体/测试流程/引用图说明/ST-LINK 说明/实机规划/`scripts/README.md` 共 12 篇同步为变量口径。④ `requirements.txt` 增 `pre-commit==4.6.2`（重建 `.venv` 即可跑 L0）。⑤ 全量 `pre-commit --all-files` + `ci_local.py` 通过。待办：新 workflow 推送远程后跑一次 CI 两 job 闭环验证；第二台不同安装路径机器的交叉验证（操作清单已固化入 `项目部署环境要求.md` §2.12） |
|
||||
| 2026-10-02 | 初版规划：盘点 BAT/Python/PowerShell/Gitea workflow 中机器相关工具路径；定义 `DTU_*` 变量清单、优先级、用户级与 SYSTEM runner 配置边界；规划 4 阶段迁移及离线/实机验收范围。未改工具调用代码 |
|
||||
|
||||
@@ -425,6 +425,49 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测
|
||||
& '.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**
|
||||
|
||||
```powershell
|
||||
# 用户级（无需管理员）；值填本机实际安装路径
|
||||
[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，不该发生） |
|
||||
| ② | `& "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' 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 → 生成器匹配 → 构建 0 警告 | ⚠️ 已知既有问题：CMake 配置期报 `Cannot find source file: .../App/cfg_file.c`（文件已移入 `App/cfg/`，`simulator/CMakeLists.txt` 未同步，配置引擎重构遗留）——**与环境变量改造无关**，勿误判为变量问题 |
|
||||
| ⑥ | （有 ST-LINK 硬件才执行）`& "MDK-ARM\reset.bat" list` | 列出探针 SN | 只跑 `list`，**不烧录不复位**；无硬件跳过不扣分 |
|
||||
|
||||
**第 3 步：反向测试**（验证"显式值无效 = 硬报错、不静默回退"语义，约 1 分钟）
|
||||
|
||||
```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
|
||||
# 关键判定：没有回退去猜别的 Keil 安装，而是明确报错
|
||||
# 测完重开终端即恢复（用户级值未动）
|
||||
```
|
||||
|
||||
**通过判定**：①②③④ 全过 = 该机器验证通过（⑤ 的既有 CMake 问题、⑥ 无硬件跳过均不扣分）。
|
||||
两台不同安装路径的机器都通过 = 环境变量方案的跨机验收闭环（方案阶段 C 出口标准）。
|
||||
|
||||
---
|
||||
|
||||
## 三、目标板环境（DTU 硬件）
|
||||
@@ -603,6 +646,7 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测
|
||||
|
||||
| 日期 | 变更 |
|
||||
|---|---|
|
||||
| 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` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 |
|
||||
|
||||
Reference in New Issue
Block a user