docs(CI): §5.3 重写并记录覆盖率工具链落地，更正 §1.2.1 与本会话先前的错判
补上今天两件 CI 工作的落地记录，并把错误结论改对（历史行不动，只在上方加行）。 新增 §4.4「覆盖率工具链（mscoverage）与 VS2026 BuildTools」。为什么只能装： 那个 exe 没有免安装的独立发行版——实测 NuGet 两个候选包， Microsoft.Testing.Extensions.CodeCoverage 18.12.0 的 109 个条目里 .exe 数为 0， Microsoft.CodeCoverage 18.11.0 只有老版 CodeCoverage.exe（CLI 语法还不同）， 所以它只随 Visual Studio 本体分发。安装入口是 aka.ms/vs/18/stable/ vs_buildtools.exe（release 那条短链不存在，会掉到"未找到"页）；组件 ID Microsoft.VisualStudio.PackageGroup.TestTools.CodeCoverage 由 18.11 的 VisualStudio.vsman 解析得到（清单里唯一引用 DynamicCodeCoverage 与 CodeCoverage.Console.Targeted 的组）。含可直接粘贴的三条管理员命令、-Force 陷阱、Restart-Service Schedule 判据，以及「装在非默认盘 = 门禁与 CI 都看不见」 的成因：Find-MsvcCl 与 _default_vs_roots 都只由 %ProgramFiles% 派生根。 §5.3 整节重写：本仓库已移除 uses:，记录六项实测（A/B/C/D/E/F，其中 E 是执行 从 ci.yml 抽出的正文、测的就是文件里那份字节）与两条自查命令，并明标两条 **未证边界**：PR 的 refs/pull/<n>/merge 兜底在本实例无法证实（0 个 PR、 ls-remote 该命名空间为空）；Basic 令牌那一支本地验证不了（公开仓库匿名即过， 伪造令牌只能证明坏的会被拒）。旧版那段"可直接抄"的示例标为禁抄：shell: pwsh 在 runner 上 PATH 无 pwsh 会直接失败，--depth 1 让 base..head 报 unknown revision，两条都会让下一个照抄的人多红一轮。 更正两处过时/错误说法：① §1.2.1 表第三行——自定义 DEFAULT_ACTIONS_URL 在 1.25.4 已无可用取值，旧写法会把排障的人引向一个不存在的开关；② 我自己先前 写的「旧探测会把机器级变量覆回 C 盘 14.29」——本机实情是 C 盘 VS2019 已于 10-27 01:00 卸载（C 盘 x64 cl.exe 实测 0 个），旧探测的行为是「找不到 → 只 Warn → 不写」，于是变量一直指着失效路径。§7 的 checkout 行相应改为「看见此 症状＝有人把 uses: 加回来了」。 另：口径文档 §7 第 8 条加实测补注（「CI runner 与本机同一台」对量基线那台不 成立，本机当日 vswhere 只有 VS2019）；新增 remote-ci-ops skill 并接上 AGENTS 与 docs/CI/README 两处指针；指南与 README 各加变更记录。纯文档，按 workflow 的 paths-ignore 不触发 CI。
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
---
|
||||
name: remote-ci-ops
|
||||
description: 远程 CI（Gitea Actions + 本机 Windows 自建 runner）运维闭环：runner 保活与抢锁清理、"没有 run / 任务消失"的四因定位、红因三分法（job 没跑起来 / runner 缺环境 / 真门禁失败）、无令牌时用 Gitea 的 MySQL 直查 runner 在线与历次 run/job 时长与红绿史（含 status 枚举定死办法）、用 gitea-runner.exe generate-config 枚举 runner 真实配置键而不猜键名、本地对照日志落 ci-artifacts/、门禁数字口径、gitlint 在 CI 的两种空转（含 runner 无 git 身份致 exit 254 假失败）、PS 5.1 原生 stderr 与编码陷阱、改 workflow / 门禁脚本的红线与改后验收清单。背景与全部实测细节在 docs/CI/远程CI完整指南.md，本 skill 只给操作顺序与判据。
|
||||
whenToUse: CI 没跑、run 被取消或零日志、页面报的失败时长/红绿史跟本地或日志对不上、"这 job 到底跑没跑起来"、门禁假绿/假红、runner 显示 online 却每 10 秒重启、自建 runner 有哪些可用配置项（cache 之类，不确定键名）、要改 .gitea/workflows/ci.yml 或 scripts/ci_*.ps1|py、或没有 API 令牌却要判断 CI 状态时。
|
||||
---
|
||||
|
||||
# remote-ci-ops — 远程 CI 运维闭环
|
||||
|
||||
**权威细节**：`docs/CI/远程CI完整指南.md`（部署、全部实测坑、章节导航），唯一入口 `docs/CI/README.md`。
|
||||
本 skill 只回答两件事：**出问题时按什么顺序查**、**动手前后各验什么**。同一事实不在两处详述。
|
||||
|
||||
> **TODO（待同步回指南）**：`docs/CI/远程CI完整指南.md` §6.1 目前只写 `action_runner.last_online` 的在线核验与 `mysql.exe` CLI；
|
||||
> 本轮把同一通道扩到 `action_run` / `action_run_job` / `action_task` 的历史与时长，且实际驱动是
|
||||
> **pymysql**（不是 mysql.exe）。下面 §4.3 / §7 是本轮实测口径，落定后应并回`docs/CI/远程CI完整指南.md` §6.1 与 §2.3。
|
||||
|
||||
**本机事实**（变了就改指南，别改这里）：runner `win-stm32-ci`（`gitea-runner` v4.0.1，labels `[windows]`，与 `runs-on: windows` 匹配）；目录 `D:\Docker\act_runner\`；Gitea 1.25.4 监听 `127.0.0.1:3001`，数据库 MySQL `127.0.0.1:3306`/gitea（凭据在 `D:\Docker\Gitea\custom\conf\app.ini` 的 `[database]`，**口令不进脚本、不进报告**）；本仓库 `repository.id = 10`（`wandering1/stm32f4-base`，另一仓 stm32f103 = 13）；**CI 只跑这一台机器**，与其他机器无关。
|
||||
|
||||
## 0. 先分层，别一上来读 workflow
|
||||
|
||||
**分层之前先做 §1**：一次红很可能压根不是"门禁内容"问题，直接读 workflow 会白绕一圈。
|
||||
|
||||
| 层 | 就位判据 | 不在位的症状 |
|
||||
|---|---|---|
|
||||
| ① 服务端 Actions 开关 | `docs/CI/远程CI完整指南.md` §1.1 | push 后 Actions 页**完全空白** |
|
||||
| ② runner 在线且工具链对 SYSTEM 可见 | `docs/CI/远程CI完整指南.md` §4.1 + 下面 §4 | run 建了但一直排队；或 L0 死在"环境自检"、一个钩子都没跑 |
|
||||
| ③ workflow 与门禁 | `scripts/ci_local.py` 本地全绿 | 具体 job 红/绿与本地不一致 |
|
||||
|
||||
**本地永远先跑这个**（runner 掉线也不影响它，是 L0 的唯一保障；日志落法见 §5）：
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' scripts/ci_local.py --keep-going # L0 + L0b + L0.5
|
||||
```
|
||||
|
||||
## 1. 第一步：这个 job 到底跑没跑起来（红因三分法）
|
||||
|
||||
**只看一条判据**：runner 侧那份 job 日志（`D:\Docker\act_runner\log\job\*-task-NN.log`）里
|
||||
**有没有出现任何一条钩子名（`cppcheck.......Passed`）或 `pre-commit hooks -- passed=A failed=B skipped=C` 汇总行**。
|
||||
|
||||
| 类 | 判据（日志里的证据行） | 结论与动作 |
|
||||
|---|---|---|
|
||||
| **A. job 没跑起来** | checkout 步骤报拉不到 `actions/checkout` / 连 `github.com` 超时，**通篇零钩子输出** | 门禁内容无罪。内网无公网时的三种处置在 `docs/CI/远程CI完整指南.md` §5.3（推荐零依赖纯 git checkout）。**先修它再谈别的**，否则后面所有"红"都不可读 |
|
||||
| **B. runner 机器缺环境** | `::warning::runner 未安装 MSVC`、`no Python with a SYSTEM-visible pre-commit`、`runner missing cppcheck`、`test-coverage` 因缺 **mscoverage** 组件而 FAIL（按用户裁定缺件即 FAIL，不 skip） | 也是"非代码问题"，但**别改成 skip 蒙过去**：按`docs/CI/远程CI完整指南.md` §4.1/§4.2 补机器级工具链或 `DTU_*`，改完重启 runner |
|
||||
| **C. 真门禁失败** | 钩子清单完整且 `failed>0` 或某条 `Failed`，**且 §5 的本地同命令复现同样的红** | 这才轮到读 workflow / 门禁脚本，按失败钩子逐条定位 |
|
||||
|
||||
**顺序不能反**：A/B 两类在本地都是"全绿"，用"本地绿 + CI 红"直接推"环境问题"也推不出是 A 还是 B——只有钩子输出能把它们分开。本轮实测：页面报的红看着像门禁失败，实际是 A（checkout 联网超时），而 A 修好之后 L0 还会再红两次——一条 C、两条 B。
|
||||
|
||||
## 2. 症状 → 一条判据 → 动作
|
||||
|
||||
| 症状 | 判据（跑这一条就够） | 结论 / 动作 |
|
||||
|---|---|---|
|
||||
| Actions 页空白、无 run | 看改了啥 + 怎么推的 | 四因：①服务端开关未开 ②workflow 没推到远程 ③**纯文档**（`paths-ignore: docs/**`、`**/*.md`）④**新建分支的首次 push**——`before` 是全零 SHA，变更文件集算不出来被 `paths-ignore` 滤空。④ 的实测：建分支那次 push 无 run，紧接着一次普通 push 立刻出 task；绕法 `workflow_dispatch` 或再推一个非文档提交 |
|
||||
| **页面报的时长/红数与本地或日志对不上** | §4.3 查 `action_run`/`action_run_job` 的 created/started/stopped | **页面时长不可照抄**。本轮实测页面写 `Failing after 6m49s`，库里 41 次 run **最长 ≈4m33s**，run 41 总时长 95 s（L0 45 s / L0.5 43 s）——**没有任何一条记录对得上 6m49s**（多半掺了排队/重试/页面自身口径）。以库里的 `total=stopped-created`、`run=stopped-started`、`queue=started-created` 三个数为准 |
|
||||
| run 全 **cancelled**、零日志 | `& '.\scripts\ci_runner_bootstrap.ps1' -Status` | runner 掉线；且 `ci.yml` 的 `concurrency.cancel-in-progress: true` 会把排队 run 被下次 push 取消 → **症状是"任务消失"而不是"任务失败"**（历史上 16–21 连续 12 个 job 零日志即此） |
|
||||
| runner 显示 **online** 却每 10 秒重启、日志暴涨（实测 ~20 MB/天） | daemon 日志出现 `another gitea-runner process is already using ".runner"` | **双看门狗抢锁**：`Unregister-ScheduledTask` **不会**停掉旧实例起的进程 → 孤儿看门狗养着旧 daemon → 它持 `.runner.lock` → 新任务里的 daemon 起不来，而**服务端仍显示 online**（旧 daemon 在服务）。修：管理员 `-StartNow`（它**先杀看门狗、再杀 daemon**，顺序反了会被 10 秒内复活） |
|
||||
| L0 失败但**本地同一条命令全绿**，日志 `exit code: 254` + `Missing git configuration: please set user.name` | 看是不是 254 | **不是提交信息问题**：`actions/checkout` 把 HOME 指向每次任务的临时目录，SYSTEM 无全局 git 身份 → gitlint 在读规则**之前**就配置错误退出。已由 `scripts/ci_gitlint_range.ps1` 用 `GIT_CONFIG_*` 注入一次性身份修掉；**254 = 门禁没跑起来（exit 2），1 = 信息真违规（exit 1）**，别把两者混成一句 |
|
||||
| 钩子条数对不上 | `grep -c 'id:' .pre-commit-config.yaml` | **报告数 = 定义数 − 1**（gitlint 属 `commit-msg` stage，`--all-files` 跑不到且表现为全绿 = 静默空转）。增删钩子后重算这个差值 |
|
||||
| `test-coverage` 恒 `[ENV] exit 2`（缺 `Microsoft.CodeCoverage.Console.exe`），或换 VS 世代后大面积假红 | `& '.venv\Scripts\python.exe' scripts/check_test_coverage.py --list` 看它探到几个根；再看机器级 `DTU_MSVC_CL` 指的是哪套 cl | 该 exe **只随 VS 分发**（NuGet 实测拿不到）；装在非默认盘还要显式指 `DTU_MSVC_CL`。安装入口 + 组件 ID + 三条管理员命令在 `docs/CI/远程CI完整指南.md` §4.4 |
|
||||
| `mem-numbers` 报"文档与 .map 不一致"，但**没改过代码也没改过那篇文档** | `.map` 的 mtime 是否早于最近一次切分支 | **跨分支假象**：`.map` 是 gitignored 的 Keil 产物，切分支后它仍属于另一分支的代码。重新 `@build` 即一致，不要去改文档数字 |
|
||||
| 明明设了 `DTU_KEIL_UV4` 却报 `UV4.exe not found` | `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')` | 会话没继承用户级变量。**回填时别按"进程里已有的变量名"枚举**——Machine 轮会把只在 User 定义的变量置空（PS 赋空值 = 删除），User 轮就再也看不到它。正确：名字取 Machine/User **并集**，且只在取到值时写入 |
|
||||
| 日志里出现 `gitea-runner.exe : …` + 4 行 `CategoryInfo`/`FullyQualifiedErrorId` | 实测 2 行真日志写成 8 行 | PS 5.1 的 `2>&1` 把每条原生 stderr 包成 ErrorRecord。修：`2>&1 \| ForEach-Object { "$_" }`（等价于原始行，且 `$LASTEXITCODE` 不受影响）。详见`docs/CI/远程CI完整指南.md` §7.3 |
|
||||
| 日志文件半 UTF-8 半乱码 | 文件头是否 `FF FE` | `>` / `*>>` 在 PS 5.1 = `Out-File` = **默认 UTF-16LE**；与 `Add-Content -Encoding ascii` 混用会一个文件两种编码 |
|
||||
|
||||
## 3. runner 保活与注册（唯一入口脚本）
|
||||
|
||||
```powershell
|
||||
# 免管理员预演，先看它会做什么
|
||||
& '.\scripts\ci_runner_bootstrap.ps1' -DryRun
|
||||
# 正式：写机器级 DTU_* + 装看门狗任务 + 立即起（需管理员）
|
||||
powershell -ExecutionPolicy Bypass -File scripts\ci_runner_bootstrap.ps1 -SetEnv -StartNow
|
||||
# 体检（非管理员会明说哪些项读不到，而不是谎报）
|
||||
& '.\scripts\ci_runner_bootstrap.ps1' -Status
|
||||
```
|
||||
|
||||
要点（细节与理由见 `docs/CI/远程CI完整指南.md` §2.4）：
|
||||
|
||||
- **不能只起 daemon**：v4 无服务支持，且**首次 Declare 失败就退出** → 一次 Gitea 重启就永久静默掉线。
|
||||
- **不能用 Windows 服务**（服务化方案已被实测推翻，见 `docs/CI/远程CI完整指南.md` §3.0）；任务计划程序的"失败后重启"**永不触发**，因为 daemon 的退出是**正常退出**。
|
||||
- 任务对象：`-AtStartup` + `Delay=PT1M`、`ExecutionTimeLimit` 为零、`RestartCount 999`、`MultipleInstances IgnoreNew`、`$settings.StartWhenAvailable=$true`——⚠ `StartWhenAvailable` 是**任务设置**属性，挂到 trigger 上会抛异常（曾因此注册崩溃）。
|
||||
- `0x41301` = `SCHED_S_TASK_RUNNING`（不是失败）；`-AtStartup` 的任务"下次运行时间"为空是正常的。
|
||||
- 改完 bootstrap 脚本里的启动器模板，**磁盘上的看门狗要下次 `-StartNow` 或开机才刷新**——不必为此专门重启 runner。
|
||||
|
||||
## 4. 没有 API 令牌时怎么判断状态
|
||||
|
||||
匿名调 `/api/v1/repos/.../actions/runs` 是 **401**。三条不依赖令牌的路，按"在线 → 落没落地 → 历史与时长"排。
|
||||
|
||||
### 4.1 在线核验（查 `action_runner`）
|
||||
|
||||
`action_runner.last_online` 与当前 Unix 秒相差 **< 30 秒**即在正常心跳；`agent_labels` 应为 `["windows"]`（不含 windows 就是标签配错）。口径见 `docs/CI/远程CI完整指南.md` §6.1。
|
||||
|
||||
### 4.2 看 runner 侧（最直接，能证明"job 真落到本机了"）
|
||||
|
||||
```powershell
|
||||
$d = 'D:\Docker\act_runner\log'
|
||||
# 日志被 daemon 占着，必须共享读打开（ReadAllBytes 会 IOException）
|
||||
$fs = [System.IO.File]::Open("$d\runner-daemon.log",'Open','Read','ReadWrite')
|
||||
# 关键行：declare successfully / writing the log of task N to … / Running job with …
|
||||
Get-ChildItem "$d\job" -File | Sort-Object LastWriteTime -Descending | Select-Object -First 5
|
||||
```
|
||||
|
||||
判读：`declare successfully` 后长时间零输出 = **在线且空闲**；`log\job\*.log` 出现新文件 = 有 task 落地；每个 job 结束时 `[runner] task N finished: success|failure`。**这份 `finished:` 行也是 §4.3 里校验 status 枚举的裁判**（§1 的三分法同样从这些文件起手）。
|
||||
|
||||
⚠ 非管理员**读不到 SYSTEM 进程的 `CommandLine`**（返回 `$null` → 过滤器静默匹配 0 个）→ 绝不能据此说"没有看门狗"。`Process.StartTime` 对 SYSTEM 也不可读，但 CIM 的 `CreationDate` 可读 → 用**进程存活时长**对比 10 秒重启间隔来判断重启循环，**不要 grep 不轮转的日志尾部**（旧失败一直在尾部，会对健康 runner 报假警）。
|
||||
⚠ 查询进程自己的命令行含关键字会**自匹配**：把模式拆开写，如 `'run_runner_watch' + 'dog\.ps1'`。
|
||||
|
||||
### 4.3 查 run / job 历史与时长（推翻页面上的说法）
|
||||
|
||||
**驱动就认 pymysql**：本机 `C:/ProgramData/Anaconda3/python.exe` 实测 `pymysql=True`、`MySQLdb=False`、`mysql.connector` **缺失**（import 直接 `ModuleNotFoundError`）→ `docs/CI/远程CI完整指南.md` §6.1 的 `mysql.exe` CLI 路线本机走不通，改 pymysql 连 `127.0.0.1:3306`/gitea。
|
||||
|
||||
**口令只从 app.ini 运行时读**：`[database]` 段里 `HOST` 是 `host:port` 一体要拆开，`NAME`/`USER`/`PASSWD` 直接用；**绝不要把口令写进脚本字面量、报告、截图或提交**（本轮就是这么漏的一次）。同段还有 `PATH = ...gitea.db`，但 `DB_TYPE = mysql` → **别去读那个 sqlite 文件**。`token`/`PASSWD` 一类行在打印任何配置文件时统一 redact。
|
||||
|
||||
```python
|
||||
# 写成文件跑（ci-artifacts/_q.py），别内联，见 §6
|
||||
import re, pymysql
|
||||
ini = open(r'D:/Docker/Gitea/custom/conf/app.ini', encoding='utf-8').read()
|
||||
sec = ini.split('[database]')[1].split('\n[', 1)[0]
|
||||
kv = dict(re.findall(r'(?m)^(\w+)\s*=\s*(.*)$', sec))
|
||||
host, port = kv['HOST'].split(':')
|
||||
db = pymysql.connect(host=host, port=int(port), user=kv['USER'], password=kv['PASSWD'],
|
||||
database=kv['NAME'], charset='utf8mb4',
|
||||
cursorclass=pymysql.cursors.DictCursor)
|
||||
cur = db.cursor()
|
||||
cur.execute("SHOW TABLES LIKE 'action%'") # → action_run / action_run_job / action_task /
|
||||
# action_run_index / action_runner / action_task_step …
|
||||
cur.execute("SHOW COLUMNS FROM action_run_job") # 🔴 列名以这里为准，别凭记忆 SELECT
|
||||
```
|
||||
|
||||
**取数（本仓库务必带 `repo_id=10`，否则混进 stm32f103 的 run）**：
|
||||
|
||||
- `action_run`：`id, repo_id, status, title, ref, sha, event, created, started, stopped`，`ORDER BY id DESC`；
|
||||
- `action_run_job`：按 run 关联到 `id, status, attempt, task_id, created, started, stopped`（本轮 run 41 → job 85/86）。
|
||||
**`task_id` 就是 job 日志文件名的 `task-NN`** → `action_run_job.task_id = 66` ↔ `log/job/20261025-133227-task-66.log`，这是 DB 与 runner 日志互校的唯一把手；
|
||||
- 时长三个数：`total = stopped-created`、`run = stopped-started`、`queue = started-created`（本轮实测 queue 普遍 1 s，所以页面 6m49s 不可能是排队）。时间戳是 **Unix 秒**，`datetime.datetime.fromtimestamp(x)` 再打印；
|
||||
- **连续红次数按 job 数、不按 run**：把同一 job 历次 `status` 从新到旧排，数连续非"成功"的长度（本轮据此得出 L0 自上线 **13 次全红、从未绿过**，run 28~41）。
|
||||
|
||||
**status 枚举：先定死再下结论**（本轮最大的误判源）。
|
||||
|
||||
| 码 | 含义 | 依据 |
|
||||
|---|---|---|
|
||||
| 0 | Unknown / 未开始 | 本轮映射试错后才定 |
|
||||
| 1 | Success | 同上 |
|
||||
| 2 | **Failure** | run 41 = 2 → Failure，与页面红、与 runner 日志 `task finished: failure` 三方一致 |
|
||||
| ≥3 | **本轮未核实** | 试错时猜过 `3=Failure`/`4=Cancelled`/`5=Skipped`，**都没有交叉验证** → 用到之前先拿一条已知结局的 run 反推（TODO：从 Gitea 源码定死，别再靠猜） |
|
||||
|
||||
- **写查询时同时打印原始数字和映射名**；`action_run` 与 `action_run_job` **默认按同一套码处理是危险假设**，跨到别的表要重验。
|
||||
- 判据：同一个 run 换一套映射后红绿翻转（本轮 step 53 判 `Success`、step 56 判 `Failure`）→ 说明你还没定死枚举，**这时任何"红绿史"都不许出口**。
|
||||
- 中文标题在 bash 终端回显成乱码（本轮 `'docs(log): ???'`）只是**显示**问题，库里数据没坏 → **认 run 用 `id`/`sha`/`ref`，不要用标题文本匹配**；要看中文就把结果写文件再按 UTF-8 读。
|
||||
|
||||
## 5. 本地对照：日志一律落 `ci-artifacts/`
|
||||
|
||||
判"本地绿 CI 红"必须有同一份可引用的本地日志。落点在仓库内 gitignored 的 `ci-artifacts/`（`.gitignore`:159），**不要写仓库外绝对路径**：
|
||||
|
||||
```bash
|
||||
mkdir -p ci-artifacts && .venv/Scripts/python.exe scripts/ci_local.py --keep-going \
|
||||
> ci-artifacts/local_ci_$(date +%Y%m%d).log 2>&1; echo EXIT=$? >> ci-artifacts/local_ci_$(date +%Y%m%d).log
|
||||
```
|
||||
|
||||
**本轮实测的替换**：先写到 `D:/Code/_sync_backup_20261026/ci_local_*.log`（仓库外）在后台 bash job 里直接 `No such file or directory` → 改落 `ci-artifacts/` 才跑通。跑门禁这类分钟级任务用后台 job 起，再 `job_output` 收，别占着前台。Keil 构建对照同理落 `ci-artifacts/local_build_*.log`。
|
||||
|
||||
## 6. 脚本层：写查询与批量探测的规矩（本轮踩点集中在这里）
|
||||
|
||||
- **一段 Python 查询写成 JS 模板字符串会炸**（本轮两次：`Expected unicode escape`、`Expected ';', '}' or <eof>`）。正确做法：按行存字符串数组 → `join('\n')` → 落盘 `ci-artifacts/_qN.py` → 用 `C:/ProgramData/Anaconda3/python.exe` 跑 → **收尾统一 `fs.rmSync` 删掉**（临时查询脚本不入库，也别留在仓库里）。
|
||||
- **`run_code` 里不能用 `import x from '…'`**（`'import', and 'export' cannot be used outside of module code`）→ `const fs = await import('node:fs')`。
|
||||
- **批量探测拆小批**：一次调用塞 4 条 Windows 探测（worktree / 目录 / 服务枚举 / app.ini）撞过 120 s deadline，只拿到部分输出。一次 1~2 条，慢源（`Get-ChildItem -Recurse`、`Get-CimInstance Win32_Service` 全量、`generate-config`）单独跑并显式 `timeoutMs`。
|
||||
- **别对全部 runner job 日志一把梭 grep**：日志混合编码（UTF-16LE / CP936），逐文件返回一堆 `[ERR …]`。要么单文件 `head`/`sed -n 'A,Bp'`/`grep`（本轮有效路径），要么解析时逐文件 try/catch 容错。
|
||||
- **`pwsh`/`read`/`subagent` 这类工具只能在 `run_code` 程序里 `await tools.xxx()` 调**，直接当工具名调会 `unknown tool`；每次调用**都要带 `description`**（漏了会 `missing required property "description"`）。
|
||||
|
||||
## 7. runner 有哪些配置项：先 `generate-config`，别猜键名
|
||||
|
||||
**判断"这个键存不存在"的唯一凭据是 runner 自己 dump 出来的默认配置文本**，全程只读——不写 `config.yaml`、不删 `.runner`（那是注册凭据，删了要重新 register）、不重启/注销 runner（只有改 `runner.labels` 才必须重启，`docs/CI/远程CI完整指南.md` §2.3.2）。
|
||||
|
||||
```powershell
|
||||
& 'D:\Docker\act_runner\gitea-runner.exe' generate-config 2>&1 | Out-String -Width 160
|
||||
```
|
||||
|
||||
- 从输出里 **grep 目标键名**（本轮实测清单含 `cache` / `capacity` / `container` / `default_image` / `action_shallow_clone` / `access_key_file` / `addr` / `allocate_pty` / `bind_workdir` / `bucket` / `docker_host` / `docker_timeout` / `enabled` / `endpoint` / `env_file` / `envs` / `external_secret` / `external_secret_file` …，以及 `#set_act_env: true`）。
|
||||
- **dump 里绝大多数键是带 `#` 的注释行** → "在清单里" ≠ "本机已启用"；是否被显式覆盖要跟 `config.yaml` 逐行比：**注释=默认值生效，非注释=本机写死了**。
|
||||
- **别拿段名当 grep 锚点**：本轮找 `[actions]` 段和 `DEFAULT_ACTIONS_URL` 时段名锚点落空、上下文打出来的是 `log_report_*` 那几行 → 直接按**键名** grep。另外服务端的 `DEFAULT_ACTIONS_URL` 是 app.ini 的键（`docs/CI/远程CI完整指南.md` §1.2.1），不要当成 runner 的键去 `config set`。
|
||||
- 老教训仍然成立：v4 的 `log` 段只有 `level` 和 `job`，**没有 `file`**，`config set log.file …` 会 `unknown config key`（`docs/CI/远程CI完整指南.md` §2.3.2）→ 改键前以 `generate-config` 输出为准；写完用 `gitea-runner.exe config get <键>` 自证。
|
||||
|
||||
## 8. 门禁口径：讲规则，不讲数字
|
||||
|
||||
数字随分支和提交漂移（实测同一句"18 个钩子"在另一分支是 26，master 后来涨到 33；单测从 3 套件/288 断言涨到 10 套件/647）。**只有规则稳定**：
|
||||
|
||||
- L0：`pre-commit hooks -- passed=A failed=B skipped=C`，其中 **A+B+C = 定义数 − 1**；`skipped` 本机唯一常见项是 `mem-numbers`（无 `.map` 即跳过，并以 `::warning::` 明示"CI 不守体积门禁"，见`docs/CI/远程CI完整指南.md` §0.0）。
|
||||
- L0b：`gitlint: N commit message(s) checked, 0 failed`。
|
||||
- L0.5：`<N> runner(s), A/A assertions passed, fail=0`，**N = `test/host/` 下 `run_unit_test.py` 的个数**。
|
||||
- **判定只看 `failed=0`、`fail=0`、A==A**；抄历史数字当基准必然误判。
|
||||
|
||||
## 9. 改 workflow / 门禁脚本的红线
|
||||
|
||||
`.gitea/workflows/ci.yml`：
|
||||
|
||||
- `shell: powershell`，**不是 `pwsh`**（Windows 自带只有 5.1，`pwsh` 会 `Cannot find: pwsh in PATH`）。
|
||||
- **`run:` 块内必须纯 ASCII**：runner 把每块写成无 BOM 临时 `.ps1` 交给 5.1 → 按 CP936 解码 → 中文导致"字符串缺少终止符"（报错行号正好在含中文那行，极易误判为逻辑错）。中文只写在 YAML 的 `name:`/注释里。
|
||||
- 写 `GITHUB_ENV` / `GITHUB_PATH` / `GITHUB_OUTPUT` 必须显式 `-Encoding ascii`（`Out-File -Append` 默认 UTF-16LE）。
|
||||
- 零依赖存档：`Tee-Object` 到 `ci-artifacts/*.log` + `$GITHUB_STEP_SUMMARY` + `::notice::`；**不用 `actions/upload-artifact`**（内网可能拉不到外层 action，`docs/CI/远程CI完整指南.md` §5.3）。
|
||||
- 工具链探测收在 `scripts/ci_find_python.ps1`（可离线自测 + 机器级安装兜底）；`DTU_*` 最高优先级，且**显式设置就必须有效、不静默回退**。
|
||||
|
||||
`scripts/ci_*.ps1`：纯 ASCII（含中文的 `.ps1` 才需要 BOM，见`docs/CI/远程CI完整指南.md` §7.1）；`-Encoding utf8NoBOM` 是 **PS 7 才有的**，5.1 要写文件用 `[System.IO.File]::WriteAllText($p, $s, (New-Object System.Text.UTF8Encoding($false)))`。
|
||||
|
||||
gitlint 专属：消息文件必须写在**仓库内**（跨盘符被 pre-commit 拒 `path is on mount 'C:', start on mount 'D:'`）且 **UTF-8 无 BOM**（BOM 占标题 1 字符，扭曲 100 上限）。
|
||||
|
||||
## 10. 改完必须验（顺序别省）
|
||||
|
||||
```powershell
|
||||
# .ps1：纯 ASCII + 语法
|
||||
$b=[System.IO.File]::ReadAllBytes($p); @($b|?{$_ -gt 127}).Count # 必须 0
|
||||
$e=$null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $p),[ref]$null,[ref]$e)|Out-Null; @($e).Count # 必须 0
|
||||
|
||||
# .yml：可解析 + 全部 run: 块纯 ASCII + 无 BOM + LF
|
||||
& '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open(r'.gitea/workflows/ci.yml',encoding='utf-8'));print(list(d))"
|
||||
|
||||
# 文档：链接与章节引用
|
||||
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all
|
||||
|
||||
# 全量门禁（等价 CI 的两个 job）
|
||||
& '.venv\Scripts\python.exe' scripts/ci_local.py --keep-going
|
||||
```
|
||||
|
||||
提交信息：标题 ≤100、**正文每行 ≤80**、UTF-8 无 BOM、`git commit -F <文件>`；**先程序化数一遍长度再提交**（中文标题最容易超，`-m` 还会被终端代码页转码）。
|
||||
|
||||
推送后到 runner 侧确认（§4.2）：两个 job 各自的 `SUMMARY` 行 + `finished: success`。**"推送成功"不等于"CI 跑过"**。
|
||||
|
||||
**汇报口径**：说"红了几次 / 跑了多久"必须写明**来源**（库里的 `action_run_job` 时长，还是 runner 日志，还是页面）与**所用的 status 映射**；三者不一致时以库 + 日志为准并说清页面为什么不可信。只读排查就全程只读——不改文件、不 commit/push、不动 runner 注册状态。
|
||||
|
||||
## 11. 分支与发布（走通的做法）
|
||||
|
||||
- 预演冲突面，不动工作区：`git merge-tree --write-tree --name-only <a> <b>`（exit 1 = 有冲突）。
|
||||
- 数字口径类冲突的正确解法：**改成规则 + 分分支快照**，而不是选一边留数字——否则同一篇文档在另一分支上必错，下次合并再撞一次。
|
||||
- 变更记录是**历史，永不改写**，只在最上方按日期加行。
|
||||
- 想验证 CI 又不想动主干：复制一条分支推上去（`git branch <copy> <src>` → `git push -u origin <copy>`），跑完再删。注意**新建分支的首次 push 不触发 run**（§2 症状表第 1 行）。
|
||||
- 主干落后很多时先同步再排障：备份脏文件 → 只 stash 被跟踪的改动 → `checkout` → `merge --ff-only` → `stash pop`，同步完再跑 §1（本轮本地落后 248 个提交，先同步才看得出真实红因）。
|
||||
- 删分支前先算独有提交：`git rev-list --count origin/master..<branch>`，**> 0 就别删**（删了只能靠 SHA 找回）；本地一律 `git branch -d`（未合并它会自己拒绝）。
|
||||
- `git commit` / `git push` 都是"先问"动作（AGENTS.md 边界节），不是任何任务的隐含步骤。
|
||||
Reference in New Issue
Block a user