From 401908c06237eeadfe02355b5f6d605037452c81 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Fri, 2 Oct 2026 22:29:49 +0800 Subject: [PATCH] =?UTF-8?q?=E7=8E=AF=E5=A2=83=E6=96=87=E6=A1=A3=E5=A2=9E?= =?UTF-8?q?=E8=A1=A5=E8=B7=A8=E6=9C=BA=E9=AA=8C=E8=AF=81=E6=B8=85=E5=8D=95?= =?UTF-8?q?=EF=BC=9A=E9=A1=B9=E7=9B=AE=E9=83=A8=E7=BD=B2=E7=8E=AF=E5=A2=83?= =?UTF-8?q?=E8=A6=81=E6=B1=82=E6=96=B0=E5=A2=9E=C2=A72.12=EF=BC=88?= =?UTF-8?q?=E5=8F=98=E9=87=8F=E9=85=8D=E7=BD=AE+=E5=85=AD=E6=AD=A5?= =?UTF-8?q?=E9=AA=8C=E8=AF=81=E9=93=BE+=E5=8F=8D=E5=90=91fail-fast?= =?UTF-8?q?=E6=B5=8B=E8=AF=95+=E9=80=9A=E8=BF=87=E5=88=A4=E5=AE=9A?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E6=96=B9=E6=A1=88=E6=96=87=E6=A1=A3=E5=BE=85?= =?UTF-8?q?=E5=8A=9E=E9=A1=B9=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/环境与部署/本地工具路径环境变量方案.md | 2 +- docs/环境与部署/项目部署环境要求.md | 44 +++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/环境与部署/本地工具路径环境变量方案.md b/docs/环境与部署/本地工具路径环境变量方案.md index 81c22ad5..fa870f9d 100644 --- a/docs/环境与部署/本地工具路径环境变量方案.md +++ b/docs/环境与部署/本地工具路径环境变量方案.md @@ -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 阶段迁移及离线/实机验收范围。未改工具调用代码 | diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md index 2babc4e5..b35f7e7c 100644 --- a/docs/环境与部署/项目部署环境要求.md +++ b/docs/环境与部署/项目部署环境要求.md @@ -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` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 |