wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

refactor(编号): 测试验证层级 L0/L0.5/L1/L2/L3 → 语义名（批次 3d·文档层）

Browse Source 
这族是验证层级：静态门禁 / 主机侧纯逻辑单测 / 板端测试套件 / 主机侧回归 / 人工目检。
实测它出现在 **97 个文件**（40+ 个 test/host 的 run_unit_test.py、.gitea workflow、
ci_local.py 的阶段标签、以及十来篇文档）。本批只做**文档层**，代码层单列一批（见下）。

改动：10 篇文档 110 行 + 三处收尾——
  测试开发标准流程 / 实机测试实施指南 / 主机单测覆盖率口径 / 门禁说明 README 与
  host-unit-tests / CI README 与远程CI完整指南 / docs README / 测试与架构专项 /
  pre-commit 使用说明。
映射：L0 → 静态门禁、L0.5 → 主机侧纯逻辑单测、L1 → 板端测试套件、L2 → 主机侧回归、
L3 → 人工目检；`L0b`（ci_local 的内部阶段标签）在文档里写成「提交信息门禁」。
测试层级那张表的「层级」列被删掉（名称列已承载同一信息，留着就是两列重复）。

**未做（代码层，单列批次 3d-2）**：`scripts/ci_local.py` 的阶段标签、`.gitea` workflow、
`test/host/*/run_unit_test.py` 的输出前缀、以及代码头注释里的 L0/L0.5 —— 那些是**程序标识**，
改名要连带 CI 日志格式与文档里对 `[SUMMARY] L0: ...` 的引用，属跨端改动，需单独验证。

验证：三篇主文档的层号残留 = 0；doc-links 通过；mojibake / git diff --check 干净；
表格列数已收敛为 3 列（名称 / 载体 / 抓住什么）。
This commit is contained in:
Wanderingss
2026-10-28 13:20:28 +08:00
parent b9f5df5d28
commit 599f05be22
10 changed files with 114 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CI/README.md
+4 -4
View File
@@ -8,7 +8,7 @@
> 日常改代码**不需要读本目录**：提交前的等价自查是本地门禁，runner 在不在线都照样跑——
>
> ```powershell
> & '.venv\Scripts\python.exe' scripts/ci_local.py # L0 静态 + L0b 提交信息 + L0.5 主机单测
> & '.venv\Scripts\python.exe' scripts/ci_local.py # 静态门禁静态 + 提交信息门禁 提交信息 + 主机侧纯逻辑单测主机单测
> ```
>
> 只有在这三种情况下才需要进来：**① 换机/重装后要重新部署 runner；② CI 不出任务或莫名
@@ -71,7 +71,7 @@
## 相关文档
- 测试分层与门禁决策（L0~L3 各层由谁把关）：[`../测试说明/测试开发标准流程.md`](../测试说明/测试开发标准流程.md)
- 测试分层与门禁决策（静态门禁~人工目检各层由谁把关）：[`../测试说明/测试开发标准流程.md`](../测试说明/测试开发标准流程.md)
- workflow 本体：[`../../.gitea/workflows/ci.yml`](../../.gitea/workflows/ci.yml)
- 本地等价脚本：[`../../scripts/ci_local.py`](../../scripts/ci_local.py)
- runner 机器的工具链环境要求：[`../环境与部署/项目部署环境要求.md`](../环境与部署/项目部署环境要求.md)
@@ -81,9 +81,9 @@
| 日期 | 变更 |
|---|---|
| 2026-10-12 | 🐛 **首次真跑出 run**：`L0.5` **成功**（`10 runner(s), 647/647, fail=0`，与本地逐字一致）；`L0` **假失败**——gitlint 因 runner 无 git 身份而 `exit 254`（`Missing git configuration: please set user.name`），旧文案把它说成"提交信息违规"，且该步 `exit 1` 连带让 26 个钩子全部没跑。已在 `ci_gitlint_range.ps1` 用 `GIT_CONFIG_*` 注入一次性身份（不写文件）并区分 254/1 退出码。另记：**新建分支的首次 push 不触发 run**，需 `workflow_dispatch` 或再推一个非文档提交。详见指南 §7 |
| 2026-10-12 | 🐛 **首次真跑出 run**：`主机侧纯逻辑单测` **成功**（`10 runner(s), 647/647, fail=0`，与本地逐字一致）；`静态门禁` **假失败**——gitlint 因 runner 无 git 身份而 `exit 254`（`Missing git configuration: please set user.name`），旧文案把它说成"提交信息违规"，且该步 `exit 1` 连带让 26 个钩子全部没跑。已在 `ci_gitlint_range.ps1` 用 `GIT_CONFIG_*` 注入一次性身份（不写文件）并区分 254/1 退出码。另记：**新建分支的首次 push 不触发 run**，需 `workflow_dispatch` 或再推一个非文档提交。详见指南 §7 |
| 2026-10-12 | 🔀 本轮 CI 修复随 `master` **合入 `v2-on-ui`**（该分支另有 21 个功能提交；冲突仅 `AGENTS.md` 与 `docs/README.md` 两处，解法是"保留其新版结构 + 把 CI 指针搬进对应位置"）。因该分支门禁更多（**26 钩子 / 10 单测套件** vs master 的 18 / 3），指南里写死的数字已改为**规则 + 分分支快照**，见指南 §6 / §7 / §10 |
| 2026-10-12 | ✅ 双看门狗缺陷**实测收敛**（管理员 `-StartNow` 清掉 3 个残留 → 单实例、链路恢复、runner online）。另修两处：daemon 日志走 stderr 被 PS 5.1 `2>&1` 包成 ErrorRecord（2 行真日志写成 8 行，每 4 行 3 行噪声）→ 启动器改 `ForEach-Object { "$_" }`；`-Status` 诚实化（非管理员读不到 SYSTEM 进程命令行 → 明说需提权而非谎报"无看门狗"；重启循环判据改看进程存活时长，不再靠不轮转日志的尾部字符串报假警）。详见指南 §7.3 |
| 2026-10-12 | 🔴 **修复"双看门狗抢 `.runner.lock`"缺陷**：`Unregister-ScheduledTask` 不停旧实例进程 → 孤儿看门狗养着旧 daemon 占锁，新看门狗每 10 秒失败一次，而 runner 网页照样 online、`-Status` 也说"在跑"。现 `-StartNow` 先清残留进程再启动、`-Status` 报重复实例与锁冲突。同日清理机器侧：`config.yaml` 头部错误指引（"改用 sc.exe / New-Service"）改为看门狗口径，删除已废弃的 `deploy_runner_task.ps1` 与 `run_runner.cmd`，`check_env.ps1` 提示同步改指 bootstrap |
| 2026-10-12 | **单一口径清理**：合并稿初版对 4 处分歧"两说并存"，现统一为本机实测现状——注册口径（`gitea-runner v4.0.1` / `D:\Docker\act_runner` / `127.0.0.1:3001`，旧 `act_runner v0.2.11` + `C:\act_runner` 段删去可复制命令只留警示）、`config.yaml`（`fetch_timeout: 1m0s`、`timeout: 30m0s`）、常驻方式（只认看门狗，`deploy_runner_task.ps1` 标废弃）、验收数字（L0.5 `288/288`，历史数字标注为快照）。并补"机器侧遗留脚本勿误用"警示 |
| 2026-10-12 | **单一口径清理**：合并稿初版对 4 处分歧"两说并存"，现统一为本机实测现状——注册口径（`gitea-runner v4.0.1` / `D:\Docker\act_runner` / `127.0.0.1:3001`，旧 `act_runner v0.2.11` + `C:\act_runner` 段删去可复制命令只留警示）、`config.yaml`（`fetch_timeout: 1m0s`、`timeout: 30m0s`）、常驻方式（只认看门狗，`deploy_runner_task.ps1` 标废弃）、验收数字（主机侧纯逻辑单测 `288/288`，历史数字标注为快照）。并补"机器侧遗留脚本勿误用"警示 |
| 2026-10-12 | **新建本目录**：远程 CI 内容原先散在 `docs/环境与部署/`（两篇互相重叠的指南）、`docs/测试说明/测试开发标准流程.md` §9、`AGENTS.md` 提交门禁节共 4 处，约 2000 行；现合并为单一指南并把 `AGENTS.md` 压成一行指针。动因：远程 CI 只涉及本机一台 runner，与日常开发规范混在一起每次会话都被读，造成困惑 |
docs/CI/远程CI完整指南.md
+33 -33
View File
@@ -6,7 +6,7 @@
> 日常改代码的等价自查是本地跑 [`scripts/ci_local.py`](../../scripts/ci_local.py)
> （与 CI 同一套判定），**不依赖远程 CI 是否在线**——runner 掉线不影响本地门禁。
> **适用**：为 STM32F4-Base 部署 / 排障 CI（`.gitea/workflows/ci.yml`，L0 + L0.5）。
> **适用**：为 STM32F4-Base 部署 / 排障 CI（`.gitea/workflows/ci.yml`，静态门禁 + 主机侧纯逻辑单测）。
> **前置阅读**：[docs/测试说明/测试开发标准流程.md §9](../测试说明/测试开发标准流程.md)（CI 覆盖边界与判定细节）、
> [docs/环境与部署/项目部署环境要求.md §2.11](../环境与部署/项目部署环境要求.md)（runner 环境要求）。
> 本文只讲**怎么配**，不重复"为什么这么设计"。
@@ -43,9 +43,9 @@
> `@build` → 该钩子在远端只会被跳过（现以 `SKIP` 名单诚实显示 Skipped，不再伪装 Passed）。
> 补上的强制路径 = **同码凭证**：本地 `@build` 0/0 后 `ram_baseline.py --update` 顺手盖
> `scripts/size_attestation.json`（三道前置：`.map` 可解析 / `.map` 不早于指纹内源码 mtime /
> 受管区 ≤92%）；CI 无需 Keil，L0 作业末尾的「体积门禁」步用 `scripts/check_size_gate.py --ci`
> 受管区 ≤92%）；CI 无需 Keil，静态门禁作业末尾的「体积门禁」步用 `scripts/check_size_gate.py --ci`
> 复核两件事——**工作树指纹 == 凭证指纹**（改了代码从没测过 = 拦）+ **按凭证数字复跑 92% 红线**。
> 主干 push 拦红，其余事件 `--warn-only`；本地 `ci_local.py` 的 L0c 步无条件 fail-closed。
> 主干 push 拦红，其余事件 `--warn-only`；本地 `ci_local.py` 的 静态门禁c 步无条件 fail-closed。
>
> 仍守不住的三项（正文唯一口径 = `scripts/check_size_gate.py` docstring）：CI 不重算绝对数字
> （只复核同码性与红线复算）；编译器选项（`.uvprojx`）不在指纹内；凭证由本地真实构建产生，
@@ -64,7 +64,7 @@
│ │ │
└────────────┬───────────┴──────────────────────────────┘
▼
push / PR 触发 → runner 拉起容器/壳 → 跑 L0 + L0.5 → 结果回显到提交
push / PR 触发 → runner 拉起容器/壳 → 跑 静态门禁 + 主机侧纯逻辑单测 → 结果回显到提交
```
**三者缺一，CI 就是空转的**（workflow 存在但永不执行 / 执行但拉不到 runner）。
@@ -113,7 +113,7 @@
| Windows runner | 已注册且 **labels 含 `windows`**；装有 Python 3.x、cppcheck、pre-commit、MSVC（VS2019/2022 C++ 工具链 + Windows SDK） |
| **runner 必须有看门狗** | `gitea-runner` v4 的 `daemon` **无服务支持、且首次 Declare 失败就直接退出进程** → Gitea 重启一次，CI 就静默停摆（2026-10-11 实测：run 16~21 共 12 个 job 零日志）。用 **`scripts/ci_runner_bootstrap.ps1`** 装"等 Gitea 就绪 + 崩溃自拉起"的看门狗 + 计划任务，见 §2.4 |
| 机器级工具变量 | runner 以 **SYSTEM** 运行，看不见交互用户的 PATH/用户级 site。用 `ci_runner_bootstrap.ps1 -SetEnv` 写入 **MACHINE** 级 `DTU_PRECOMMIT_PYTHON` / `DTU_CPPCHECK` / `DTU_MSVC_CL`，见 §4.1.3 |
| 缺 MSVC 时 | L0.5 降级为 WARNING 跳过（不硬失败），但**等于该层裸奔**，须尽快补装 |
| 缺 MSVC 时 | 主机侧纯逻辑单测降级为 WARNING 跳过（不硬失败），但**等于该层裸奔**，须尽快补装 |
---
@@ -363,7 +363,7 @@ log:
runner:
file: .runner # 注册凭据（由 register 生成，勿手改）
capacity: 1 # 并行 job 数；单机建议 1（cppcheck 吃 CPU）
timeout: 30m0s # 单 job 超时；L0+L0.5 约 1~3 分钟
timeout: 30m0s # 单 job 超时；静态门禁+主机侧纯逻辑单测约 1~3 分钟
fetch_timeout: 1m0s # 🔴 不得超过 RPC timeout(1m0s)：原写 5m0s 会被自动截断并刷告警，2026-10-02 已改
fetch_interval: 2s
# 🔴 标签：windows 必须与 workflow 的 runs-on: windows 逐字一致
@@ -656,9 +656,9 @@ runner 是一台干净的 Windows，**下面这些必须装**，否则 job 会
| **Python 3.x** | 🔴 必需 | `l0-gates` 环境自检失败 → **job 硬失败** | `winget install Python.Python.3.12` |
| **cppcheck** | 🔴 必需 | 同上（`cppcheck --version` 探测不过） | `winget install Cppcheck.Cppcheck` |
| **pre-commit** | 🔴 必需 | 同上（`python -m pre_commit --version` 探测） | `pip install pre-commit` 或 `uv tool install pre-commit` |
| **MSVC（VS + Windows SDK）** | 🟡 建议 | 缺则 `l05-host-unit-tests` **告警降级跳过**（不硬失败，但 L0.5 裸奔） | `winget install Microsoft.VisualStudio.2022.BuildTools`，勾"使用 C++ 的桌面开发" |
| **MSVC（VS + Windows SDK）** | 🟡 建议 | 缺则 `l05-host-unit-tests` **告警降级跳过**（不硬失败，但 主机侧纯逻辑单测裸奔） | `winget install Microsoft.VisualStudio.2022.BuildTools`，勾"使用 C++ 的桌面开发" |
| Keil / ST-LINK | ⛔ 不需要 | CI 刻意不跑 `@build` | — |
| 开发板 / 串口 | ⛔ 不需要 | L1/L2/L3 不上 CI | — |
| 开发板 / 串口 | ⛔ 不需要 | 板端测试套件/主机侧回归/人工目检不上 CI | — |
Git 另算：`git --version` 任意版本即可（你已在用）。
@@ -679,10 +679,10 @@ runner 以 **SYSTEM 服务/计划任务**运行，它看到的 PATH 与 site-pac
| 你以为 | SYSTEM 实际看到 | 后果 |
|---|---|---|
| `python` 在 PATH 里 | PATH 上是 `C:\msys64\ucrt64\bin\python.exe`，**没有 pre-commit** | L0 环境自检失败 |
| `python` 在 PATH 里 | PATH 上是 `C:\msys64\ucrt64\bin\python.exe`，**没有 pre-commit** | 静态门禁环境自检失败 |
| `pip install --user pre-commit` 装好了 | **用户级 site 对 SYSTEM 完全不可见**（换任何 python 路径都没用） | 同上 |
| 仓库里有 `.venv` | `.venv` 已 `.gitignore`，runner 全新工作区**根本没有** | 同上 |
| `cppcheck` 在 PATH 里 | 机器 PATH 无 `C:\Program Files\Cppcheck` | L0 环境自检失败 |
| `cppcheck` 在 PATH 里 | 机器 PATH 无 `C:\Program Files\Cppcheck` | 静态门禁环境自检失败 |
> 机制补充（2026-10-02 实测）：计划任务以 **`SYSTEM`** 账户运行时，继承的是**系统级 PATH**
> （注册表 `HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment` 的 `Path`），
@@ -719,7 +719,7 @@ python -m pre_commit --version
#### 4.1.1 ⚠️⚠️ 关键坑：`pre-commit` 必须在「全局 site-packages」，装到用户态等于没装
这是 2026-10-02 排查 **L0 job 反复失败**（`::error::no Python with a SYSTEM-visible pre-commit`）的真正根因，
这是 2026-10-02 排查 **静态门禁 job 反复失败**（`::error::no Python with a SYSTEM-visible pre-commit`）的真正根因，
也是本环境最隐蔽的一个坑。
**现象**：`pre-commit` 在你自己的终端里好好的（`pre-commit --version` 有输出），
@@ -836,9 +836,9 @@ workflow 已改为统一消费 `DTU_*` 接口（见 [本地工具路径环境变
| 变量 | 作用 | 未设置时的回退 |
|---|---|---|
| `DTU_PRECOMMIT_PYTHON` | 指向装有 pre-commit 的 python.exe（L0/L0.5 用） | PATH 的 `python` → 工作区 `.venv`（干净克隆里通常没有） |
| `DTU_CPPCHECK` | 指向 cppcheck.exe（L0 钩子用） | SYSTEM 的 PATH（用户级 PATH 不可见） |
| `DTU_MSVC_CL` | 指向 x64 `cl.exe`（L0.5 用） | `%ProgramFiles%`/`%ProgramFiles(x86)%` 推导的 VS 标准根自动探测 |
| `DTU_PRECOMMIT_PYTHON` | 指向装有 pre-commit 的 python.exe（静态门禁/主机侧纯逻辑单测用） | PATH 的 `python` → 工作区 `.venv`（干净克隆里通常没有） |
| `DTU_CPPCHECK` | 指向 cppcheck.exe（静态门禁钩子用） | SYSTEM 的 PATH（用户级 PATH 不可见） |
| `DTU_MSVC_CL` | 指向 x64 `cl.exe`（主机侧纯逻辑单测用） | `%ProgramFiles%`/`%ProgramFiles(x86)%` 推导的 VS 标准根自动探测 |
设置（**必须管理员**；scope 用 `Machine` 才能被 SYSTEM 任务看到）：
@@ -870,7 +870,7 @@ Start-ScheduledTask -TaskName GiteaActionsRunner
**本机实测命中第 1 条（2026-10-02）**：
`C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\bin\Hostx64\x64\cl.exe` ✅
> ⚠️ **装在完全非标准位置（如 D 盘自定义目录）会探测不到** → 被当成"没装 MSVC"跳过 L0.5（仅告警）。
> ⚠️ **装在完全非标准位置（如 D 盘自定义目录）会探测不到** → 被当成"没装 MSVC"跳过 主机侧纯逻辑单测（仅告警）。
> 处置（二选一）：设机器级 `DTU_MSVC_CL` 指向 `cl.exe`（推荐；值无效会硬报错），
> 或把 VS 装回标准位置（探测按 `%ProgramFiles*` 推导，换盘符的标准布局仍命中）。
>
@@ -971,8 +971,8 @@ github.com 会在 checkout 步骤卡住/失败。三种处置：
| 层 | 汇总行 |
|---|---|
| L0 | `L0: pre-commit hooks -- passed=N failed=M skipped=K (log: ci-artifacts\l0-pre-commit.log)` |
| L0.5 | `L0.5: <K> runner(s), <A>/<B> assertions passed, fail=<F>`（逐模块另有 `::notice::<模块>: N/M PASSED (failed=0)`） |
| 静态门禁 | `静态门禁: pre-commit hooks -- passed=N failed=M skipped=K (log: ci-artifacts\l0-pre-commit.log)` |
| 主机侧纯逻辑单测 | `主机侧纯逻辑单测: <K> runner(s), <A>/<B> assertions passed, fail=<F>`（逐模块另有 `::notice::<模块>: N/M PASSED (failed=0)`） |
> ⚠️ **`ci-artifacts/` 已加入 `.gitignore`**：它是 runner 工作区的运行时产物，不要提交。
>
@@ -988,11 +988,11 @@ github.com 会在 checkout 步骤卡住/失败。三种处置：
| job | `runs-on` | 步骤要点 |
|---|---|---|
| `l0-gates` | `windows` | checkout（`fetch-depth: 0`，gitlint/cubemx 需完整历史）→ 环境自检（**Python 探测走 `scripts/ci_find_python.ps1`**、cppcheck 按 `DTU_CPPCHECK` → PATH → 标准安装目录，缺则 `::error::` + exit 1）→ `pre_commit install --install-hooks` → **提交信息门禁 `scripts/ci_gitlint_range.ps1`**（见 §7 排障表"钩子条数对不上"行）→ **决定跳过哪些钩子**（探测 `.map`，写入 `GITHUB_OUTPUT`；无 `.map` 时 `::warning::` 声明体积门禁未跑）→ `pre-commit run --all-files --show-diff-on-failure`（`env: SKIP`，输出 `Tee` 到 `ci-artifacts/l0-pre-commit.log`）→ 打印 `::notice::L0: passed/failed/skipped` 汇总行 → 归档日志说明 |
| `l05-host-unit-tests` | `windows` | checkout → **探测 MSVC**（按 VS_ROOTS 找 `Hostx64\x64\cl.exe`）→ 遍历 `test/host/**/run_unit_test.py` 逐个跑（输出 `Tee` 到 `ci-artifacts/l05-<模块>.log`；解析各模块 `N/M PASSED` 汇总行 → 聚合 `::notice::L0.5: K runner(s), A/B assertions passed`；失败 `::error::` 并置退出码）；**未探测到 MSVC 时打印醒目 WARNING 并降级跳过**（不硬失败，避免"没装 VS 的 runner 全红"） |
| `l0-gates` | `windows` | checkout（`fetch-depth: 0`，gitlint/cubemx 需完整历史）→ 环境自检（**Python 探测走 `scripts/ci_find_python.ps1`**、cppcheck 按 `DTU_CPPCHECK` → PATH → 标准安装目录，缺则 `::error::` + exit 1）→ `pre_commit install --install-hooks` → **提交信息门禁 `scripts/ci_gitlint_range.ps1`**（见 §7 排障表"钩子条数对不上"行）→ **决定跳过哪些钩子**（探测 `.map`，写入 `GITHUB_OUTPUT`；无 `.map` 时 `::warning::` 声明体积门禁未跑）→ `pre-commit run --all-files --show-diff-on-failure`（`env: SKIP`，输出 `Tee` 到 `ci-artifacts/l0-pre-commit.log`）→ 打印 `::notice::静态门禁: passed/failed/skipped` 汇总行 → 归档日志说明 |
| `l05-host-unit-tests` | `windows` | checkout → **探测 MSVC**（按 VS_ROOTS 找 `Hostx64\x64\cl.exe`）→ 遍历 `test/host/**/run_unit_test.py` 逐个跑（输出 `Tee` 到 `ci-artifacts/l05-<模块>.log`；解析各模块 `N/M PASSED` 汇总行 → 聚合 `::notice::主机侧纯逻辑单测: K runner(s), A/B assertions passed`；失败 `::error::` 并置退出码）；**未探测到 MSVC 时打印醒目 WARNING 并降级跳过**（不硬失败，避免"没装 VS 的 runner 全红"） |
> 🔴 **两条 Python 探测链必须同序同步**：本地 `scripts/ci_local.py` 与 CI 侧
> `scripts/ci_find_python.ps1` 的候选顺序要一致。2026-10-11 那次 L0 全灭，就是 workflow
> `scripts/ci_find_python.ps1` 的候选顺序要一致。2026-10-11 那次 静态门禁全灭，就是 workflow
> 单方面把候选收窄成"PATH 上的 python + 仓库 `.venv`"（而 runner 上这两条**都是死路**：
> PATH python 没装 pre-commit、`.venv` 被 gitignore 根本不存在）导致的。改一边必须改另一边。
@@ -1009,10 +1009,10 @@ github.com 会在 checkout 步骤卡住/失败。三种处置：
| 3 | `scripts\ci_runner_bootstrap.ps1 -Status` | 计划任务已注册 / daemon 在跑 / Gitea 可达 / 三个 `DTU_*` 已设——**四项全绿** |
| 4 | runner 上 `python --version` / `cppcheck --version` / `python -m pre_commit --version` | 三条全通（且对 SYSTEM 成立，见 §4.1） |
| 5 | `git push` 一次（或页面 Run workflow） | Actions 页出现运行中任务 |
| 6 | `l0-gates` 日志 | `using python (…)` + `runner environment check passed`；`::notice::L0: pre-commit hooks -- passed=.. failed=0 skipped=..`；无 `.map` 时见 `::warning::` 体积门禁未跑 |
| 6 | `l0-gates` 日志 | `using python (…)` + `runner environment check passed`；`::notice::静态门禁: pre-commit hooks -- passed=.. failed=0 skipped=..`；无 `.map` 时见 `::warning::` 体积门禁未跑 |
| 7 | `l0-gates` 的 **提交信息门禁** 步骤 | `::notice::gitlint: N commit message(s) checked, 0 failed`（**这一行以前根本不存在**，见 §7） |
| 8 | `l05-host-unit-tests` 日志 | `::notice::L0.5: <N> runner(s), A/A assertions passed, fail=0`。**`N` = `test/host/` 下 `run_unit_test.py` 的个数**（2026-10-12 实测：`master` 3 个 / 288 断言，`v2-on-ui` 10 个）；断言总数随单测增减而变，判定只看 **`fail=0` 且 A==B**，不要拿历史数字当基准 |
| 9 | job 运行页的 **Summary** 区块 | 出现 "L0 static gates" / "Commit message gate (gitlint)" / "L0.5 host-side unit tests" 小标题与汇总行 |
| 8 | `l05-host-unit-tests` 日志 | `::notice::主机侧纯逻辑单测: <N> runner(s), A/A assertions passed, fail=0`。**`N` = `test/host/` 下 `run_unit_test.py` 的个数**（2026-10-12 实测：`master` 3 个 / 288 断言，`v2-on-ui` 10 个）；断言总数随单测增减而变，判定只看 **`fail=0` 且 A==B**，不要拿历史数字当基准 |
| 9 | job 运行页的 **Summary** 区块 | 出现 "静态门禁 static gates" / "Commit message gate (gitlint)" / "主机侧纯逻辑单测 host-side unit tests" 小标题与汇总行 |
| 10 | 提交记录旁出现 ✅ | CI 全绿 |
**本地先自查**（与 CI 同一套判定，避免推上去才发现问题）：
@@ -1067,8 +1067,8 @@ date +%s # 对比 last_online
| `checkout` 步骤卡住/超时 | 拉不到 `actions/checkout@v4`（内网） | 见 §5.3 |
| `l05` 日志出现 `::warning::runner 未安装 MSVC` | VS 装在非默认路径或未装 | 见 §4.2（默认路径 / 同步改两处根目录） |
| `mem-numbers` 显示 `Skipped` | 正常（CI 无 Keil，无 `.map`） | 无需处理；但注意 **CI 未守体积门禁**（见 §0.0），改代码后本地 `@build` + `check_mem_numbers.py --scan` 兜底 |
| L0.5 显示 `2 runner(s), X/Y ...` 但 X<Y | 有单测用例未通过 | 看该模块的 `::error::unit test failed` 行与其 `ci-artifacts/l05-<模块>.log` |
| L0.5 报 `produced no '=== ... N/M PASSED ===' summary line` | 该模块运行器未输出汇总行（改了 harness 或运行器崩溃） | 核对 `test/host/common/unit_test_harness.py` 的 `summary_marker` 与该模块 `TestBuild` 是否一致 |
| 主机侧纯逻辑单测显示 `2 runner(s), X/Y ...` 但 X<Y | 有单测用例未通过 | 看该模块的 `::error::unit test failed` 行与其 `ci-artifacts/l05-<模块>.log` |
| 主机侧纯逻辑单测报 `produced no '=== ... N/M PASSED ===' summary line` | 该模块运行器未输出汇总行（改了 harness 或运行器崩溃） | 核对 `test/host/common/unit_test_harness.py` 的 `summary_marker` 与该模块 `TestBuild` 是否一致 |
| `Tee-Object` 步骤报 `TerminatorExpectedAtEndOfString` / 字符串缺少终止符 | `run:` 块混入了非 ASCII（GBK 解码错位） | 见文件头 🔴🔴；`run:` 内必须纯 ASCII |
| `l05` 报 `fatal error C1083: 无法打开包括文件 "stdio.h"` | Windows SDK 缺失 | 装 VS 时勾"使用 C++ 的桌面开发"+ SDK |
| 单测退出码 2 | 环境错误（多为无 MSVC） | 同上 |
@@ -1208,8 +1208,8 @@ runner 的日志走 **stderr**，于是上面两个日志文件都栽在这两
- **钩子集变化**（`.pre-commit-config.yaml` 增删钩子）：CI 自动跟随，无需改 workflow；
但**必须核对条数**——`pre-commit run --all-files` 只跑 `pre-commit` stage，
`commit-msg` stage 的钩子（gitlint）不在其中，靠 `ci_gitlint_range.ps1` 单独守（见 §7）；
- **`@build` / L1 / L2**：永远留在本地，不要往 CI 加（需 Keil 授权与真机）；
- **runner 长时间不可用**时：CI 只是"多一道网"，**提交前的本地 `ci_local.py` 仍是 L0 的唯一保障**，
- **`@build` / 板端测试套件 / 主机侧回归**：永远留在本地，不要往 CI 加（需 Keil 授权与真机）；
- **runner 长时间不可用**时：CI 只是"多一道网"，**提交前的本地 `ci_local.py` 仍是 静态门禁的唯一保障**，
不能因"已经配了 CI"放宽（见 [docs/任务规划/登记簿.md](../任务规划/登记簿.md) 的条目「CI 远端闭环未验证」）。
---
@@ -1352,18 +1352,18 @@ powershell -ExecutionPolicy Bypass -File scripts\ci_runner_bootstrap.ps1 -DryRun
| 日期 | 变更 |
|---|---|
| 2026-10-25 | 🔒 **A-5 残余销项联动（§0.0 重写）**：体积门禁由"CI 不守"改为**同码凭证强制**——本地 `@build` 0/0 后 `ram_baseline.py --update` 盖 `scripts/size_attestation.json`，L0 作业末尾 `check_size_gate.py --ci` 复核同码性 + 红线复算（runner 无需 Keil）；主干 push 拦红、其余事件 warn-only；`mem-budget` 补进 SKIP 名单诚实显示。指纹取 git 索引 blob（跨 checkout 稳定，修 7c4628b）；三项仍守不住的口径唯一正文 = 脚本 docstring |
| 2026-10-12 | 🐛 **第一次真跑出 run，当场暴露 gitlint 门禁空转**：把本轮修复推到新分支 `v2-on-ui-ci` 后拿到 task 31/32——**L0.5 成功**（`10 runner(s), 647/647 assertions passed, fail=0`，与本地逐字一致），**L0 失败**却与提交信息毫无关系：`exit code: 254` + `Missing git configuration: please set user.name`。根因是 `actions/checkout` 把 HOME 指向每次任务的临时目录、SYSTEM 账号没有 git 身份，gitlint 在读到规则之前就配置错误退出；旧脚本还把失败原因**写死**成"标题超 100 字符"，加上该步 `exit 1` 让后面 26 个钩子**一个都没跑**。修法：脚本先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（不写文件、不碰开发者机器），并区分 254（门禁没跑起来 → `exit 2`）与真实违规（→ `exit 1`）。另记一条新坑：**新建分支的首次 push 不产生 run**（§7 排障表 ④） |
| 2026-10-12 | 🔀 **随 `master` 合入 `v2-on-ui`：数字口径改为分支中立**。本指南原先写死 master 的数字（18 钩子 / 17 报告、3 runner / 288 断言），而 `v2-on-ui` 是 **26 钩子 / 10 套件**——同一篇文档在两个分支上必然有一个是错的。§6 验收第 8 行、§7 排障表、§10 验收标准三处改为讲规则（**报告数 = 定义数 − 1**；**runner 数 = `test/host/` 下 `run_unit_test.py` 个数**）+ 分分支实测快照。本次合并只带文档与脚本，**零 C 代码改动**；合并后本分支 `@build` 0 错 0 警、`ci_local.py` 全绿（L0 25 钩子 + L0.5 10 runner / 647 断言） |
| 2026-10-25 | 🔒 **A-5 残余销项联动（§0.0 重写）**：体积门禁由"CI 不守"改为**同码凭证强制**——本地 `@build` 0/0 后 `ram_baseline.py --update` 盖 `scripts/size_attestation.json`，静态门禁作业末尾 `check_size_gate.py --ci` 复核同码性 + 红线复算（runner 无需 Keil）；主干 push 拦红、其余事件 warn-only；`mem-budget` 补进 SKIP 名单诚实显示。指纹取 git 索引 blob（跨 checkout 稳定，修 7c4628b）；三项仍守不住的口径唯一正文 = 脚本 docstring |
| 2026-10-12 | 🐛 **第一次真跑出 run，当场暴露 gitlint 门禁空转**：把本轮修复推到新分支 `v2-on-ui-ci` 后拿到 task 31/32——**主机侧纯逻辑单测成功**（`10 runner(s), 647/647 assertions passed, fail=0`，与本地逐字一致），**静态门禁失败**却与提交信息毫无关系：`exit code: 254` + `Missing git configuration: please set user.name`。根因是 `actions/checkout` 把 HOME 指向每次任务的临时目录、SYSTEM 账号没有 git 身份，gitlint 在读到规则之前就配置错误退出；旧脚本还把失败原因**写死**成"标题超 100 字符"，加上该步 `exit 1` 让后面 26 个钩子**一个都没跑**。修法：脚本先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（不写文件、不碰开发者机器），并区分 254（门禁没跑起来 → `exit 2`）与真实违规（→ `exit 1`）。另记一条新坑：**新建分支的首次 push 不产生 run**（§7 排障表 ④） |
| 2026-10-12 | 🔀 **随 `master` 合入 `v2-on-ui`：数字口径改为分支中立**。本指南原先写死 master 的数字（18 钩子 / 17 报告、3 runner / 288 断言），而 `v2-on-ui` 是 **26 钩子 / 10 套件**——同一篇文档在两个分支上必然有一个是错的。§6 验收第 8 行、§7 排障表、§10 验收标准三处改为讲规则（**报告数 = 定义数 − 1**；**runner 数 = `test/host/` 下 `run_unit_test.py` 个数**）+ 分分支实测快照。本次合并只带文档与脚本，**零 C 代码改动**；合并后本分支 `@build` 0 错 0 警、`ci_local.py` 全绿（静态门禁 25 钩子 + 主机侧纯逻辑单测 10 runner / 647 断言） |
| 2026-10-12 | ✅ **双看门狗缺陷实测收敛** + 修掉日志里的 PS 5.1 stderr 包装噪声与 `-Status` 假警。① 管理员 `-StartNow` 杀掉 3 个残留（孤儿看门狗 26900/19716 + 占锁 daemon 53848）→ `daemon up: pid 40360 (single instance)`，监管链 `svchost → 看门狗 → daemon`，看门狗日志 25 秒零增长、runner 回 online。② 新坑：daemon 日志写 **stderr**，PS 5.1 的 `2>&1` 把每行包成 ErrorRecord → `gitea-runner.exe : ` 前缀 + 4 行 `CategoryInfo` 块，实测 2 行真日志写成 8 行（**每 4 行有 3 行是噪声**，且就在文档让大家第一个打开的文件里）。启动器改为 `2>&1 \| ForEach-Object { "$_" } \| Out-File -Encoding utf8`（实测与 cmd 包装等价但免引号剥离坑，`$LASTEXITCODE` 不受影响）；§7.2 方式 B 的示例原本正是 `> log 2>&1`（UTF-16LE + 包装双坑），已改；新增 §7.3 汇总这两条。③ `-Status` 两处诚实化：非管理员**读不到 SYSTEM 进程命令行**（`CommandLine` 为 null → 过滤器静默匹配 0 个），改为明说"需提权"而不是谎报"没有看门狗"；重启循环判据不再靠"日志尾部有没有错误串"（文件不轮转，修好后旧失败仍在尾部 → 对健康 runner 报假警），改看 **daemon 进程存活时长**（CIM `CreationDate` 非管理员可读，`Process.StartTime` 对 SYSTEM 进程不可读） |
| 2026-10-12 | 🔴 **实测揪出"双看门狗抢锁"缺陷并修复** + 机器侧清理。① 现象：runner 网页 online、`-Status` 说 daemon 在跑，但 `runner-watchdog.log` 每 10 秒刷 `starting daemon → daemon exited, exit code 1`，daemon 日志 `runner file is already locked by another process`。② 根因：`Unregister-ScheduledTask` **不停旧实例启动的进程**——13:22 重跑 bootstrap 时旧看门狗(12:53 起)成孤儿并继续养着旧 daemon、占住 `.runner.lock`，新看门狗永远抢不到锁，任务实际谁也没管，日志以约 20 MB/天在刷。③ 修复：`ci_runner_bootstrap.ps1` 的 `-StartNow` 现在**先停孤儿看门狗与残留 daemon 再启动**并回显单实例确认；`-Status` 新增重复实例计数与锁冲突检测。④ 机器侧清理：`config.yaml` 头部那句**错误指引**（"常驻改用 Windows sc.exe / New-Service"，正是 §3.0 证伪的路）改为看门狗口径并指向本文；删除已废弃的 `deploy_runner_task.ps1` 与 `run_runner.cmd`（§3.2），`check_env.ps1` 指向它们的提示同步改指 bootstrap。⑤ 核实：`config.yaml` 改后 YAML 可解析且**所有配置值与改前逐项一致**（只动注释）；`check_env.ps1` 带 BOM 且语法 0 错；删除前确认计划任务动作目标是 `run_runner_watchdog.ps1`，删除不影响在跑 runner |
| 2026-10-12 | 🧹 **单一口径清理（以本机实测现状为准）**：合并稿初版对 4 处分歧采取"两说并存 + 衔接注"，本次统一。① 注册口径——`act_runner v0.2.11` + `C:\act_runner` + 公网域名 instance 一段**删除可复制命令**，只留"勿照抄"警示（核实 `C:\act_runner` 至今不存在，本机是 `gitea-runner v4.0.1` + `D:\Docker\act_runner` + `127.0.0.1:3001`）；② `config.yaml` 示例 `fetch_timeout` 由 `5m0s` 改为磁盘实际值 **`1m0s`**、`timeout` 统一 `30m0s`，并补"不得超过 RPC timeout(1m0s)"；③ 常驻口径统一为看门狗——§3.2 `deploy_runner_task.ps1` 标为**已废弃**并说明失效机理（单次 daemon = 正常退出，失败重启永不触发），§3.3 手动等价命令**重写为看门狗版任务对象**（旧版会教人手搓出坏配置），§10 TL;DR 第 4 步改指 `ci_runner_bootstrap.ps1`；④ 数字口径——L0.5 期望值更新为 **288/288**（run#8 的 39/39 与 278/278 标注为历史快照，判定只看 `fail=0` 与 A==B），钩子数按现行 18 定义 / 17 报告。另同步：健康三查与排障表改用现行日志名（`runner-daemon.log` / `runner-watchdog.log`，`runner-stdout.log` 标为遗留且说明其混编码）、BOM 示例对象换成 `check_env.ps1` 并注明看门狗是纯 ASCII 无需 BOM、配套脚本表补 `run_runner_watchdog.ps1` 并标出磁盘上仍存的废弃脚本建议删除、补 `Next Run Time` 为空属正常的说明 |
| 2026-10-12 | 🧹 **单一口径清理（以本机实测现状为准）**：合并稿初版对 4 处分歧采取"两说并存 + 衔接注"，本次统一。① 注册口径——`act_runner v0.2.11` + `C:\act_runner` + 公网域名 instance 一段**删除可复制命令**，只留"勿照抄"警示（核实 `C:\act_runner` 至今不存在，本机是 `gitea-runner v4.0.1` + `D:\Docker\act_runner` + `127.0.0.1:3001`）；② `config.yaml` 示例 `fetch_timeout` 由 `5m0s` 改为磁盘实际值 **`1m0s`**、`timeout` 统一 `30m0s`，并补"不得超过 RPC timeout(1m0s)"；③ 常驻口径统一为看门狗——§3.2 `deploy_runner_task.ps1` 标为**已废弃**并说明失效机理（单次 daemon = 正常退出，失败重启永不触发），§3.3 手动等价命令**重写为看门狗版任务对象**（旧版会教人手搓出坏配置），§10 TL;DR 第 4 步改指 `ci_runner_bootstrap.ps1`；④ 数字口径——主机侧纯逻辑单测期望值更新为 **288/288**（run#8 的 39/39 与 278/278 标注为历史快照，判定只看 `fail=0` 与 A==B），钩子数按现行 18 定义 / 17 报告。另同步：健康三查与排障表改用现行日志名（`runner-daemon.log` / `runner-watchdog.log`，`runner-stdout.log` 标为遗留且说明其混编码）、BOM 示例对象换成 `check_env.ps1` 并注明看门狗是纯 ASCII 无需 BOM、配套脚本表补 `run_runner_watchdog.ps1` 并标出磁盘上仍存的废弃脚本建议删除、补 `Next Run Time` 为空属正常的说明 |
| 2026-10-12 | **文档合并**：本次把 `CI配置指南.md` 与 `Gitea_Runner部署指南.md` 合并为本篇（`docs/CI/远程CI完整指南.md`）并迁入 `docs/CI/`，去重（runner 注册 / config.yaml / 装软件 / 排障表两篇均有）、补入 runner 看门狗与机器级变量实测教训；相对链接按新位置改写，原两篇互引改为本文内部引用 |
| 2026-10-11 | **bootstrap 自身修复**：`StartWhenAvailable` 误设到**触发器**上（该属性属**任务设置**，触发器没有）→ 脚本在"已注销旧任务、尚未注册新任务"之间抛 `SetValueInvocationException`，把 runner 任务删没了。现改为①先构建 action/trigger/settings、**后**注销旧任务，②`Register-ScheduledTask` 失败时显式告警"旧任务已删、CI 裸奔"，③新增 **`-DryRun`**（免管理员即可全量校验任务对象），④`-Status` 在非管理员下额外提示"看不见任务 ≠ 任务不存在"。同时更正根因：旧任务其实存在，但跑的是**单次** `daemon`——daemon 属"正常退出"而非"失败"，计划任务的失败重启**救不到**它，必须用看门狗循环重拉 |
| 2026-10-11 | **修"很多任务不执行"（runner 静默停摆）+ 补 gitlint 门禁**：① §2.4 重写——`gitea-runner` v4 的 `daemon` **无服务支持、首次 Declare 失败即退出进程**（日志实证），Gitea/机器重启一次 CI 就停摆，**run 16~21 共 12 个 job 零日志**（`cancelled`/`queued`，叠加 `cancel-in-progress` 后表现为"任务凭空消失"而非失败）；新增 **`scripts/ci_runner_bootstrap.ps1`**（等 Gitea 就绪 + 崩溃自拉起的看门狗 + 开机计划任务 + `-SetEnv` 写机器级 `DTU_*` + `-Status` 只读体检）。② §3.1 重写——SYSTEM 可见性三重坑（PATH python 是 msys64 无 pre-commit / 用户级 site 对 SYSTEM 不可见 / `.venv` 已 gitignore）是 run 14~15 L0 全灭根因（`33a4aa4` 把候选收窄成这两个、又删了 cppcheck 目录兜底，而机器级 `DTU_*` 从未设置）；探测收进 **`scripts/ci_find_python.ps1`**（两 job 共用、可离线自测、失败列出全部候选）并恢复机器级安装兜底。③ 新增 **gitlint 提交信息门禁**：钩子定义数比 CI 报告条数多 **1**（当时 17/16，master 并入 `test-cppcheck` 后为 18/17），缺的正是 gitlint——其 `stages: [commit-msg]` 声明在**上游** `.pre-commit-hooks.yaml`（`--all-files` 跑不到，且表现为全绿 → 长期无人发现）→ **`scripts/ci_gitlint_range.ps1`** 逐条校验本次 push/PR 范围（消息文件须写在仓库内 + UTF-8 无 BOM）。④ `GITHUB_ENV/PATH/OUTPUT` 写入统一显式 `-Encoding ascii`（PS 5.1 `Out-File -Append` 默认 **UTF-16LE**，实测落盘 `42 00 42 00 42 00 3D 00 31 00`）。§5 清单 8→10 条、§6 排障表 +5 行、§7 维护项重写 |
| 2026-10-11 | **修"很多任务不执行"（runner 静默停摆）+ 补 gitlint 门禁**：① §2.4 重写——`gitea-runner` v4 的 `daemon` **无服务支持、首次 Declare 失败即退出进程**（日志实证），Gitea/机器重启一次 CI 就停摆，**run 16~21 共 12 个 job 零日志**（`cancelled`/`queued`，叠加 `cancel-in-progress` 后表现为"任务凭空消失"而非失败）；新增 **`scripts/ci_runner_bootstrap.ps1`**（等 Gitea 就绪 + 崩溃自拉起的看门狗 + 开机计划任务 + `-SetEnv` 写机器级 `DTU_*` + `-Status` 只读体检）。② §3.1 重写——SYSTEM 可见性三重坑（PATH python 是 msys64 无 pre-commit / 用户级 site 对 SYSTEM 不可见 / `.venv` 已 gitignore）是 run 14~15 静态门禁全灭根因（`33a4aa4` 把候选收窄成这两个、又删了 cppcheck 目录兜底，而机器级 `DTU_*` 从未设置）；探测收进 **`scripts/ci_find_python.ps1`**（两 job 共用、可离线自测、失败列出全部候选）并恢复机器级安装兜底。③ 新增 **gitlint 提交信息门禁**：钩子定义数比 CI 报告条数多 **1**（当时 17/16，master 并入 `test-cppcheck` 后为 18/17），缺的正是 gitlint——其 `stages: [commit-msg]` 声明在**上游** `.pre-commit-hooks.yaml`（`--all-files` 跑不到，且表现为全绿 → 长期无人发现）→ **`scripts/ci_gitlint_range.ps1`** 逐条校验本次 push/PR 范围（消息文件须写在仓库内 + UTF-8 无 BOM）。④ `GITHUB_ENV/PATH/OUTPUT` 写入统一显式 `-Encoding ascii`（PS 5.1 `Out-File -Append` 默认 **UTF-16LE**，实测落盘 `42 00 42 00 42 00 3D 00 31 00`）。§5 清单 8→10 条、§6 排障表 +5 行、§7 维护项重写 |
| 2026-10-02 | **S3 + S14**：新增 §0.0「CI 不覆盖的体积门禁」醒目声明；新增 §4.4「产物存档与结果汇总」（零依赖 `Tee-Object` + `$GITHUB_STEP_SUMMARY` + `::notice::` 汇总行，不用 `actions/upload-artifact`；记录 `$ErrorActionPreference='Stop'` 与 `2>&1 \| Tee-Object` 的陷阱及处置）。§5 验证清单（7→8 条）与 §6 排障表同步更新 |
| 2026-10-02 | **workflow 接入 `DTU_*` 机器级变量**（`本地工具路径环境变量方案.md` 实施）：`l0-gates` 的 Python 探测改为 `DTU_PRECOMMIT_PYTHON`（显式，无效即硬失败）→ PATH → `.venv`（删除 `C:\ProgramData\anaconda3` 固定候选）；cppcheck 改为 `DTU_CPPCHECK` 优先 → PATH（**移除 `C:\Program Files\Cppcheck` 固定回退**）；`l05` 的 MSVC 探测改为 `DTU_MSVC_CL` 优先 → `%ProgramFiles*` 推导的标准根（与 `unit_test_harness.py` 同步，不再写死盘符）；新增 §5.1.3 机器级变量设置方法（`Machine` scope + 重启任务）、§5.2 与 check_env 样例、排障表 cppcheck 行、TL;DR 5b 步骤。§5.1.1 的报错原文标注为历史记录 |
| 2026-10-02 | ✅ **首次 CI 全绿（run#8：L0 + L0.5 双 job Success）**。定位并修复最后两个拦路虎：① **§5.1.1 用户态 site-packages 陷阱**——`pre-commit` 只装在 `%APPDATA%\Roaming\Python\...`（SYSTEM 不可见）；且提权 `pip install --no-user` 会因 pip 扫**整个 `sys.path`**、见 user-site 已满足而**静默跳过**全局安装（9 依赖中唯 `cfgv` 因版本相同被跳过→`-s` 下 `ModuleNotFoundError`）。修法：提权 + `--force-reinstall --no-deps` 强制落全局，并以 `-s` 复验。② **§5.1.2 doc-links 假阳性**——文档引用了 gitignore 的运行时文件 `.dsh/skills/serial-assistant/scripts/state/meta.json`，本地存在、干净克隆无 → 按《文档规范》§3.3 加同状态词「运行时未创建」。排障表补 6 条（pre-commit 不可见 / GBK 中文 / pwsh / cppcheck / doc-links / MSVC 降级）。新增配套脚本 `install_precommit_global.ps1`、`install_precommit_global2.ps1`、`fix_cfgv_global.ps1` |
| 2026-10-02 | ✅ **首次 CI 全绿（run#8：静态门禁 + 主机侧纯逻辑单测双 job Success）**。定位并修复最后两个拦路虎：① **§5.1.1 用户态 site-packages 陷阱**——`pre-commit` 只装在 `%APPDATA%\Roaming\Python\...`（SYSTEM 不可见）；且提权 `pip install --no-user` 会因 pip 扫**整个 `sys.path`**、见 user-site 已满足而**静默跳过**全局安装（9 依赖中唯 `cfgv` 因版本相同被跳过→`-s` 下 `ModuleNotFoundError`）。修法：提权 + `--force-reinstall --no-deps` 强制落全局，并以 `-s` 复验。② **§5.1.2 doc-links 假阳性**——文档引用了 gitignore 的运行时文件 `.dsh/skills/serial-assistant/scripts/state/meta.json`，本地存在、干净克隆无 → 按《文档规范》§3.3 加同状态词「运行时未创建」。排障表补 6 条（pre-commit 不可见 / GBK 中文 / pwsh / cppcheck / doc-links / MSVC 降级）。新增配套脚本 `install_precommit_global.ps1`、`install_precommit_global2.ps1`、`fix_cfgv_global.ps1` |
| 2026-10-02 | 🔴 **常驻方式重大修正（实测推翻）**：`Start-Service gitea-runner` 必然失败。经二进制逆向确认 `gitea-runner v4.0.1` **无任何服务管理代码**（命令集仅 `bug-report/cache-server/config/daemon/exec/register`，无 `service.go`；`OpenSCManagerW` 等符号来自 Docker SDK，非服务安装代码），`daemon` 是纯控制台程序、不向 SCM 回报 `SERVICE_RUNNING`。**§4 全节重写为「任务计划程序」方案**（新增 §4.0 根因分析、§4.2 `deploy_runner_task.ps1`、§4.3 手动命令 + 72h 超时警示、§4.5 清理遗留服务、§4.6 提权）；删除失效的 `deploy_runner.ps1`/`install_service.ps1`；排障表补「错误 1053」「LastTaskResult 非 0」「72 小时被杀」3 条；拓扑图/§5.1/§7 日志/§10 TL;DR 同步更新。另修 `config.yaml` 的 `fetch_timeout` 5m→1m（超出 RPC 1m 会被截断并告警） |
| 2026-10-02 | **修 `.ps1` 编码坑（实测）**：无 BOM 的 UTF-8 脚本被 WinPS 5.1 按 GBK 解读 → 中文乱码（`鐒跺悗鎵ц`）并撞坏引号配对，报 `源文本中包含无法识别的标记`/`字符串缺少终止符`。**新增 §7.1「给含中文的 `.ps1` 加 UTF-8 BOM」**（两种修法 + 解析器校验命令）；排障表补该条目；配套脚本已统一加 BOM |
| 2026-10-02 | **按实测修正为 v4.0.1**：act_runner 已更名 **`gitea-runner`**，发布页迁至 `gitea.com/gitea/runner`。**v4 移除 `daemon install/start/stop/status`**；**v4 `log` 段无 `file` 键**（§3 改用 `log.job.dir`）；补 §1.3 命令集对照、§6.1 MySQL 直查核验、排障表（`accepts at most 0 arg(s)` / `unknown config key log.file` 等） |