From 49cddac0dd17bc03eb4f2055f25e631606d68a13 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Thu, 29 Oct 2026 08:54:41 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E9=97=A8=E7=A6=81=E8=AE=A1=E6=95=B0):=20?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E6=A0=91=E6=96=B9=E6=A1=88=E7=9A=84=E3=80=8C?= =?UTF-8?q?31=20=E9=92=A9=E5=AD=90=E3=80=8D=E6=94=B9=E5=9B=9E=E5=A3=B0?= =?UTF-8?q?=E6=98=8E=E7=9A=84=2051=E2=80=94=E2=80=94=E5=90=8C=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E7=AC=AC=2022=20=E8=A1=8C=E6=9C=AC=E5=B0=B1=E5=86=99?= =?UTF-8?q?=E7=9D=80=2051?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 真值三源互证：YAML 解析条目数 51（仓库口径的自查命令）、带 stages:[manual] 的 3 根、AGENTS.md 的 「共 51 个钩子 / 提交期实跑 48 根」、门禁说明 README 的「声明的 51」与「51 个 hook → 28 篇」、 pre-commit 使用说明的「51 声明数，一次 git commit 实跑 48 根」——全部一致，唯一离群值就是方案文档 那条表格行里的 31；而同一份文档第 22 行自己写着 51，属文档内部自相矛盾，这是最硬的判据。 :248 取 51 而不是 48：该行主语是 ci_local，本次实跑日志实证它覆盖静态 passed=47 + manual 三根 rc=0 + gitlint 十条，正好是声明的 51 根全跑；48 是「一次 git commit 实跑」的口径（47 静态 + gitlint）， 两个数分列、不许混写。同时把裸数字改成带出处指向的写法，下次加钩子这里少一个查不到来源的数。 远程CI 指南那处只加「当时」两个字：26 是 2026-10-12 那次 gitlint 环境事故的观测值，数字本身不算错， 但句子是现在语气，会被读成今天静态段的条数（现 47）。按计数同步 playbook 的最小动作加注，不重述数字。 冻结并写明类别：pre-commit 使用说明的「当时 40 个 hook」、主机单测覆盖率口径的 39/16（句中已有 「当时」）；同数不同义不动——run_boot_test.py 的「31 份 boot_log」是日志份数、verify_log.py 的 rec[31:59] 是字节偏移；命中面之外不动——.venv/ 与 Lib/ 第三方、.git/ 内的 stray 报告。 邻族实测自洽、本轮未碰：22 根专属钩子 + 19 套无专属 = 41 套、28 篇索引、51/48/47 三分列。 门禁：编号门禁 [OK]；doc-links --all --sections-strict RC=0（2602 处引用、无法判定 0、194 文档， 章节引用 +1 就是新增的这处 §2 指向）；两文件无 BOM、CR=0、无 U+FFFD、无行尾空格、结尾单 LF、 表格仍为 5 列；旧形态复扫「31 钩子 / 31 个钩子 / 31钩子」全仓命中 0。改动不落体积门禁指纹面， 不需要 @build。 --- docs/CI/远程CI完整指南.md | 2 +- docs/环境与部署/并行任务工作树方案.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CI/远程CI完整指南.md b/docs/CI/远程CI完整指南.md index 03a8d52c..ed934749 100644 --- a/docs/CI/远程CI完整指南.md +++ b/docs/CI/远程CI完整指南.md @@ -1060,7 +1060,7 @@ date +%s # 对比 last_online | `static-gates` 报 `no Python with a SYSTEM-visible pre-commit` | runner 是 SYSTEM：PATH 上的 python 无 pre-commit、用户级 site 不可见、`.venv` 未入库（§4.1 三重坑） | `ci_runner_bootstrap.ps1 -SetEnv` 写机器级 `DTU_PRECOMMIT_PYTHON`，或把 pre-commit 装进机器级解释器；**改完必须重启 runner** | | `static-gates` 报 `runner missing cppcheck` | 机器 PATH 无 Cppcheck 且无机器级 `DTU_CPPCHECK` | `-SetEnv`（会自动发现 `C:\Program Files\Cppcheck`）或装 `Cppcheck.Cppcheck` | | **钩子条数对不上**（CI 的 `--all-files` 报告条数 = 定义数 − 1 − 3 manual：定义数 **51** → 报告 **47** 行，另由「手动阶段门禁」步跑 3 根；2026-10-12 **当时**实测 `master` 18 定义 / 17 报告，`v2-on-ui` 26 定义 / 25 报告——**增删钩子的分支必须重算这个差值**） | 两处都不进 `--all-files` 报告：`gitlint` 的 `stages: [commit-msg]` 写在**上游** `.pre-commit-hooks.yaml`（项目 `.pre-commit-config.yaml` 里 grep 不到，别据此断定"没限制"）；`cppcheck` / `test-cppcheck` / `test-coverage` 带 `stages: [manual]`，只由「手动阶段门禁」步逐根 `--hook-stage manual` 跑。都会表现为全绿——静默空转 | commit-msg 阶段已由 `scripts/ci_gitlint_range.ps1` 单独校验、manual 三根已由「手动阶段门禁」步兜住；**以后增删钩子必须核对"定义数 == 日志条数 + gitlint + manual 三根"** | -| gitlint 步骤 **Failed 但提交信息其实合规**（同一条命令在本地全绿），日志里是 `exit code: 254` + `Missing git configuration: please set user.name` | `actions/checkout` 把 HOME 临时指向每次任务的临时目录，而 SYSTEM 账号没有全局 git 身份 → gitlint **在读到任何规则之前**就因配置错误退出（**254 不是规则违规**）。旧脚本末尾那句 `::error::...rule: single-line Chinese title, < 100 chars` 是**写死的猜测文案**，把环境问题伪装成"提交信息不合格"；且该步 `exit 1` 会让后面的 `--all-files` **整个不跑**——看着像"门禁拦住了"，实际 26 个钩子一个都没执行 | `ci_gitlint_range.ps1` 先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（**不写任何文件**，开发者机器不受影响），并把 254 与真实违规分开报（**2 = 门禁没跑起来**，1 = 信息确实违规）。实测同一命令：空 HOME 下改前 254、改后 `0 failed`（2026-10-12 task 31 首次暴露） | +| gitlint 步骤 **Failed 但提交信息其实合规**（同一条命令在本地全绿），日志里是 `exit code: 254` + `Missing git configuration: please set user.name` | `actions/checkout` 把 HOME 临时指向每次任务的临时目录，而 SYSTEM 账号没有全局 git 身份 → gitlint **在读到任何规则之前**就因配置错误退出（**254 不是规则违规**）。旧脚本末尾那句 `::error::...rule: single-line Chinese title, < 100 chars` 是**写死的猜测文案**，把环境问题伪装成"提交信息不合格"；且该步 `exit 1` 会让后面的 `--all-files` **整个不跑**——看着像"门禁拦住了"，实际当时 26 个钩子一个都没执行 | `ci_gitlint_range.ps1` 先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（**不写任何文件**，开发者机器不受影响），并把 254 与真实违规分开报（**2 = 门禁没跑起来**，1 = 信息确实违规）。实测同一命令：空 HOME 下改前 254、改后 `0 failed`（2026-10-12 task 31 首次暴露） | | push 后 Actions 页**空白/无任务** | ① 服务端开关未开 ② workflow 没 push 到远程 ③ 只改了 `docs/**`（被 `paths-ignore` 滤掉） ④ **新建分支的首次 push**（实测 2026-10-12：创建 `v2-on-ui-ci` 那次 push 没产生 run——runner 在线空闲、job 日志零新增；紧接着一次普通 push 立刻出 task。原因：`before` 是全零 SHA，变更文件集算不出来，`paths-ignore` 求值时被滤空） | ①②③ 逐条核对 §1 / §5.1 / §5.2；④ 用 `workflow_dispatch` 手动触发，或再推一个非文档路径的提交 | | 任务一直 **Waiting / 排队** | 没有 label 匹配 `windows` 的 runner | 检查 `--labels "windows:host"`；Settings→Runners 是否 Idle | | `static-gates` 报 `::error::runner 缺少：Python, cppcheck` | runner 没装或不在 PATH | 装完后**重启 runner 服务**（新进程才吃到新 PATH） | diff --git a/docs/环境与部署/并行任务工作树方案.md b/docs/环境与部署/并行任务工作树方案.md index a7939027..1f451c4e 100644 --- a/docs/环境与部署/并行任务工作树方案.md +++ b/docs/环境与部署/并行任务工作树方案.md @@ -245,7 +245,7 @@ D:/Code/DTU Code/ | 道 | 资源 | 并行性 | 锁 / 机制 | |---|---|---|---| | **台架道** | COM6 / ST-LINK / 设备（§7.1） | **串行**——约束资源，**永不空转**（约束优先，TOC）：代码道在跑时必须为下一个台架任务备料 | `bench.lock` | -| **代码道** | CPU / 源码 | **并行**——worktree 独立空间；前提 = 写范围互不相交 + 强门禁（31 钩子 `ci_local`，同 Linux 内核子系统树并行而能合回的逻辑，见 `docs.kernel.org/process/2.Process.html` 的 subsystem tree 模型） | 无锁；分支 ≤2 天、绿即合（trunk-based 短分支） | +| **代码道** | CPU / 源码 | **并行**——worktree 独立空间；前提 = 写范围互不相交 + 强门禁（`ci_local` 跑满声明的 51 根、含 manual 段，口径 → `docs/门禁说明/README.md` §2；同 Linux 内核子系统树并行而能合回的逻辑，见 `docs.kernel.org/process/2.Process.html` 的 subsystem tree 模型） | 无锁；分支 ≤2 天、绿即合（trunk-based 短分支） | | **外部窗口** | 标准源 / 第三方主站等外部设备 | **Fixed Date 类**（Kanban 服务分类）：窗口一到全道让路；窗口前 2 日特性冻结（只修稳定，Zephyr RC 语义 → `docs.zephyrproject.org/latest/project/release_process.html`） | `bench.lock` + 外部预约 | **四条规则**：