STM32F4-Base/docs/代码规范/pre-commit使用说明.md

pre-commit 自动化代码审查 — 部署与使用说明

生效前提：本机已运行过 pre-commit install（钩子写入 .git/hooks/）。 新机器/新开发者进入仓库后需执行一次 pre-commit install，详见「新机器启用」。

---

1. 部署架构

git commit
  └─ pre-commit（.git/hooks/pre-commit）
       ├─ trailing-whitespace      自动修复行尾空格
       ├─ end-of-file-fixer        自动修复文件尾换行
       ├─ check-added-large-files  阻止 >1MB 大文件
       ├─ check-merge-conflict     阻止含冲突标记的文件
       ├─ check-yaml               校验 YAML 语法
        ├─ no-mojibake             阻止 U+FFFD 乱码文件
        ├─ coding-standard        C 代码规范检查（规范V1.0 可机械校验项）
        ├─ doc-links              文档链接存在性（.md）
        ├─ task-table             FreeRTOS 任务表一致性
        ├─ mem-numbers            内存/Flash 数字一致性（体积档）
        ├─ lv-conf-sync           两份 lv_conf.h 特性子集一致性（比对生效值）
        ├─ cubemx-survival        CubeMX 重生成存活审计（易失定制清单 + 基线漂移）
        ├─ watchdog-unit-test     看门狗判定状态机主机侧单测（主机侧纯逻辑单测）
        ├─ test-suite-switch      测试套件开关=产品构建（防测试固件静默提交）
         ├─ registration-check     双端注册反向校验（uvprojx + CMakeLists，登记簿「rs485_task 白名单缺口」；含 UI 页面描述符表接线，「UI 字符集与像素回归门禁」）
          ├─ mem-budget             RAM 预算 92% 阈值门禁（登记簿条目「缩堆迁 CCM 后半（暂缓）」，2026-10-12）
           └─ font-charset           UI 字符集差集检查（防缺字白框，「UI 字符集与像素回归门禁」，2026-10-15）
  └─ commit-msg（.git/hooks/commit-msg）
       └─ gitlint                  校验 commit message 格式
  └─ manual（pre-commit --hook-stage manual；不随 git commit 跑）
       ├─ cppcheck                 全量 C 静态分析（自有代码）
       ├─ test-cppcheck            test/ 侧静态分析
       └─ test-coverage            主机单测覆盖率总闸（44 套 + 回退台账）

阶段：pre-commit 阶段拦截代码问题、commit-msg 阶段拦截格式问题，任一失败 → commit 中止；另有 manual 阶段（stages: [manual] 的慢钩子）不随 git commit 跑，由远端 CI 与 scripts/ci_local.py 的 manual 段承担（见下）。一次 git commit 实跑 48 根 = pre-commit 阶段 47 根 + gitlint 1 根。

CI 侧的同一套门禁（2026-10-01 起）：Gitea Actions（.gitea/workflows/ci.yml）在 push / PR 时 以 pre-commit run --all-files 复跑 pre-commit 阶段的 47 根（mem-numbers 在无 Keil .map 的 runner 上自适应跳过）， 再以「手动阶段门禁」步逐根 --hook-stage manual 复跑 cppcheck / test-cppcheck / test-coverage 三根 （pre_commit run a b c 不支持多 id，实测报 unrecognized arguments）。 本地提交前想跑同一套判定：& '.venv\Scripts\python.exe' scripts/ci_local.py。详见 ../测试说明/流程与规范/测试开发标准流程.md §9。

依赖清单

依赖 组件	安装方式	用途
pre-commit 4.6.2	uv tool install pre-commit	钩子框架
cppcheck 2.21.0	winget install cppcheck	C 静态分析引擎
scripts/check_mojibake.py	随仓库提交	U+FFFD 乱码检测（纯 Python，无依赖）
scripts/check_coding_standard.py	随仓库提交	代码规范检查（纯 Python，无依赖）
scripts/check_doc_links.py	随仓库提交	文档链接存在性检查（纯 Python，无依赖）
scripts/gen_task_table.py	随仓库提交	FreeRTOS 任务表生成/校验（纯 Python，无依赖）
scripts/check_mem_numbers.py	随仓库提交	内存/Flash 数字一致性（纯 Python，无依赖）
scripts/check_cubemx_survival.py	随仓库提交	CubeMX 重生成存活审计（纯 Python，无依赖）
scripts/check_test_suite.py	随仓库提交	测试套件开关门禁（纯 Python，无依赖）
scripts/check_registration.py	随仓库提交	双端注册反向校验（纯 Python，无依赖）
scripts/ram_baseline.py	随仓库提交	RAM 预算 92% 门禁 + 趋势台账（纯 Python，无依赖）
scripts/check_font_charset.py	随仓库提交	UI 字符集差集检查（纯 Python，无依赖；复用 tools/font_gen/ 两个生成器的提取与 cmap 解析规则）

PATH 要求：cppcheck 安装后需在 PATH 中可找到（winget 自动写入 User PATH，但当前终端不会立即生效，需重开终端）；装在非 PATH 位置时可用 DTU_CPPCHECK 环境变量指向 cppcheck.exe 完整路径（显式设置但无效 → 硬报错，不静默回退）。

---

2. 通用机制与索引（逐项详解已迁往 docs/门禁说明/）

2026-10-23 迁移：原本节 27 个"逐钩子详解"小节，已全部迁往 docs/门禁说明/——每种门禁 一篇，八段固定结构（查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线口径 / 改门禁本身）。当时 40 个 hook 的总览与"三种拦截姿态" → docs/门禁说明/README.md。 搬走的原因：只写"拦了什么"的文档会让人以为绿就是对的，而"什么时候会骗人"必须有归处。 同一事实只在一处详述（docs/文档规范.md 同此要求），所以本节不再重复逐钩子表格。

2.1 旧小节 → 新文档 对照（历史引用查号用）

旧小节编号（原手册 §2.N，已停用）	现在住在
2.1 / 2.2	docs/门禁说明/trailing-whitespace.md、docs/门禁说明/end-of-file-fixer.md
2.3 / 2.4 / 2.5	docs/门禁说明/check-added-large-files.md、check-merge-conflict.md、check-yaml.md
2.6	docs/门禁说明/cppcheck.md（含 test-cppcheck）
2.7 / 2.8	docs/门禁说明/no-mojibake.md、coding-standard.md
2.9 / 2.10 / 2.11	docs/门禁说明/doc-links.md、task-table.md、mem-numbers.md
2.12 / 2.13 / 2.14	docs/门禁说明/cubemx-survival.md、test-suite-switch.md、gitlint.md
2.15	docs/门禁说明/lv-conf-sync.md
2.16 / 2.17 / 2.20 / 2.21 / 2.22 / 2.23	docs/门禁说明/host-unit-tests.md（16 个 *-unit-test 合一篇，含各套件来历与用例规模）
2.18 / 2.19	docs/门禁说明/registration-check.md、mem-budget.md
2.24 / 2.25 / 2.26 / 2.27	docs/门禁说明/font-charset.md、id-check.md、layer-deps.md、bsp-err.md

这些编号本身不再新增引用（历史变更记录里的旧编号按"冻结历史不回改"保留，按上表查号即可）。

2.2 跨钩子的通用机制（这些事实仍归本节）

机制	口径
三个阶段	pre-commit 阶段 48 个钩子 + commit-msg 阶段 gitlint（= 一次 git commit 实跑 49）+ manual 阶段 3 根（cppcheck / test-cppcheck / test-coverage：git commit 不跑，只在远端 CI 的「手动阶段门禁」步与 scripts/ci_local.py 的 manual 段跑；三根实测合计约 165 s ≈ 一次带代码提交耗时的三分之二）→ 口径 = YAML 解析后的 hook 条目数 51；自查命令与「声明 / 文档 / 实跑」三数同源核对 → docs/门禁说明/README.md §2；default_install_hook_types: [pre-commit, commit-msg] 是显式声明的——换机后 pre-commit install 才会带上 commit-msg 钩子
一根钩子在输出里出现两次	未声明 stages: 的钩子默认属于所有阶段，pre-commit 与 commit-msg 两遍都会列出它；第二遍的"文件"是提交信息文件，几乎必然 (no files to check)Skipped。只看输出结尾会把"实跑通过"读成"没跑"——判某钩子跑没跑要认它第一次出现的那行（实测 2026-10-24：只改 .pre-commit-config.yaml 的提交里 test-coverage 与 bsp-err 都是 Passed，尾巴那一遍是 Skipped）
stash 陷阱	pre-commit 跑钩子前会 stash 未暂存改动，钩子看到的是"没有你中间状态"的树。改代码 + 同时更新基线/受管区的，必须先 git add 再跑钩子，否则会拿到假报警（本仓踩过，docs/门禁说明/bsp-err.md §4 记了现场）。它藏不住什么，见下一行
stash 覆盖面：只覆盖已跟踪文件的未暂存改动（2026-10-26 读源码定案，对所有钩子通用）	机制在 pre-commit 的 staged_files_only._unstaged_changes_cleared()：git diff-index <tree> 取补丁 → git checkout -- . → 跑完 git apply 还原。所以「钩子实跑 = 只看到 HEAD + 本笔 staged」这句对已跟踪文件成立、对未跟踪文件不成立：未跟踪文件压根不在 diff-index 里，不会被藏；git add -N（intent-to-add）也救不了——pre-commit 只 git rm --cached 把它撤下索引（_intent_to_add_cleared()），文件本体仍在盘上。后果：别人写了尚未入库的文件（新页面实例 / 新单测目录 / 新文档）躺在树里时，任何一笔碰到该文件所属钩子 files: 的提交都会被这份半成品拖红——红的内容没错，但账不该记在这笔提交上。实测：ui_page_clock.c、ui_page_reset.c 处于未跟踪且未绑 #page 期间，generated-fresh 对所有人的 UI 提交都会 FAIL（现场日志 docs/门禁说明/generated-fresh.md §6 第 8 条）。三条结论：① 提交排序——会让全树变红的半成品要么先落地（绑引用 + 重跑生成器）要么先挪出工作树；② 凡「判定基准取工作区」的钩子（重跑比对类、全库统计类）在多人同树下必须配静默窗口；③ 真要 --no-verify 抢跑，正文必须点名是哪几个未跟踪文件拖的红，别让它被读成「钩子不可信」
always: true 已废	pre-commit 4.x 对 local 钩子里这个键只告警 Unexpected key(s) 然后忽略 → "想总是跑"只能把 files: 写全（教训 → §5.5）
改写型与只读型的豁免不对称	YAML 锚点 &cubemx-generated 只豁免 trailing-whitespace 与 end-of-file-fixer；cppcheck / no-mojibake / cubemx-survival / task-table / mem-numbers 仍覆盖 Src/、Inc/
增量拦截三段式	规则恒生效 + 存量钉在基线/台账 + --prune 点名"已还清、请删行"；脚本刻意没有 --write（不提供"一条命令把现状洗成合法"的入口）。使用者（2026-10-26 实跑核对）：layer-deps（基线内 3 + ALLOW 永久豁免 3，共见 6 处）、bsp-err（38 条）、~~已退役的 id-check~（工作区台账已还清 = 0 条指纹 / 0 处；HEAD 那版是 303 条指纹 / 651 处）。原写「layer-deps(6)」「id-check 台账 640 处」都是没跟着还账更新的旧数
没有 .map 即跳过	mem-numbers / mem-budget 在无 Keil 构建的机器（含远端 CI）上是跳过，不是"通过"——别把跳过读成有余量
配置自己坏 = 全部静默不跑	改完 .pre-commit-config.yaml 的验收不是过 check-yaml，而是实跑 -m pre_commit run --all-files，确认目标钩子出现在输出里且状态不是 Skipped
范围策略	第三方与生成物只靠 .gitignore 与顶层 exclude（不在各钩子里重复写目录名）；权威口径 → AGENTS.md 提交门禁一节 + §5.5
新增一个门禁的三步	① 配置落地并做一次注入自证（故意违反一次，看它是否当场 FAIL）；② 在 docs/门禁说明/ 落一篇，"限制与盲区"一节不许留空；③ 在 docs/门禁说明/README.md 索引加一行

2.3 快速自查入口

• 提交前等价自查（静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测）：scripts/ci_local.py（用 .venv 解释器跑）。
• 单独跑某一条：-m pre_commit run <hook-id> --files <改动的文件>；全库：--all-files。
• 临时跳过只在紧急情况，且必须在提交说明里写明跳过了什么、为什么、随后怎么补——跳之前先跑 §2.4 自查表（--no-verify 一次跳过 47 条，连 gitlint 一起跳 = 48 条，见 §2.2「三个阶段」行）。

2.4 抢跑自查表（--no-verify 之前自己跑一遍：只读、不 stash、别人正在写盘也安全）

--no-verify 跳过的不是「一条格式检查」，是全部 47 条（外加 commit-msg 阶段的 gitlint，共 48 条）。 2026-10-26 本仓连着抢了三笔，放走三条本该被拦的真问题，都在提交正文里可复核：

抢跑那笔	本该由谁拦下	后果什么时候才看得见
e7136cbe	coding-standard（5 条 CODE-RULE-17：模块 .c/.h 配对）+ end-of-file-fixer（2 个文件缺尾换行）	靠下一笔补；还漏提了 test/host/console_log/run_unit_test.py ⇒ HEAD 里代码已改成「整行独占」、旁边 runner 的文档串却还写着「无锁直发」——比少一条断言更坏，下一个人会被它教出错误心智模型
1d4b6a17	scripts/stack_report.py（不在钩子里，只能靠人跑）：控制台「整行独占」给 dbg_console 共享尾段加深 80 B 帧 → iec104Task 静态最坏链 1,544、margin 1,016 < 1,024 ISR 底线 → 退出码 1（实测差 8 B 过线）	这是安全边界，不是风格问题。2026-10-26 21:3x 用本机 20:39 那次构建的 .htm 复跑，iec104Task 仍是 1016 / 39% / FAIL、脚本退出码 1 ⇒ 这笔债还挂着（谁来还：抬 iec104Task 栈要过 mem-budget 与 docs/内存管理/ 台账，或把日志帧深压回去）

所以纪律不是「以后别抢跑」，而是：跳闸前把下面 A 组自己跑一遍——它们全部只读、不 stash、别人正在写盘时 也能安全跑。对照 §2.2「stash 覆盖面」那一行：真提交会把你自己未暂存的改动藏起来，所以手跑通常比真提交 更严（不是更松）；而别人未跟踪的半成品两边都藏不住 ⇒ 红了先认是谁的文件，既别替人背账，也别顺手把 别人的账混进你这一笔。

A. 抢跑前必跑（每条都是实跑验证过的入口）

查什么	命令（仓库根执行）	判据 / 退出码
栈与最坏链（今天漏的就是这条）	& '.venv\Scripts\python.exe' scripts/stack_report.py	判据 margin = cfg − max(静态最坏, 运行峰值) ≥ max(1024 B ISR, 30% × cfg)；0=全过 / 1=有任务不过 / 2=解析失败
RAM 静态占用	& '.venv\Scripts\python.exe' scripts/ram_report.py	涨了的段要能指到具体模块与函数
RAM 总量红线（mem-budget 的入口）	& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate	>92% 即 1；⚠ 0 包含「没有 .map 就跳过」——跳过不等于有余量
代码规范（含 CODE-RULE-17 / 20）	& '.venv\Scripts\python.exe' scripts/check_coding_standard.py <本笔的 .c/.h>	有违规即 1
BOM 漂移	& '.venv\Scripts\python.exe' scripts/check_bom_drift.py --all	HEAD 有 BOM 而工作区没有 → 1；⚠ 别用「有 BOM 就是错」的外行判据——Drivers/BSP/UI/*、App/task/ui_task.c 等本就该带 BOM（§2.2 与 AGENTS 铁律）
乱码 U+FFFD	& '.venv\Scripts\python.exe' scripts/check_mojibake.py <本笔文件>	出现即 1
字节卫生 = 改写型钩子的只读等价	下面的一行式 + git diff --check	一次查完**待提交清单（含未跟踪新文件）**的 CR / 缺尾换行 / U+FFFD / 行尾空格，全程不写盘
受影响模块的主机单测	& '.venv\Scripts\python.exe' test/host/<模块>/run_unit_test.py	只跑你碰的那几套；改过骨架 test/host/common/unit_test_harness.py 就要跑全套（等价 22 根钩子同时触发）
全量单测 + 覆盖率	& '.venv\Scripts\python.exe' scripts/check_test_coverage.py	0=全过且覆盖率未回退 / 1=有失败或回退 / 2=环境（缺 cl.exe / mscoverage）
编号	& '.venv\Scripts\python.exe' scripts/archive/id_gate/check_ids.py --strict	增量拦截：台账之外新错即 1；顺带核「可判定比例」与「不可判定绝对数」两行（2026-10-26 余量只剩 12 处）
文档链接与章节	& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all	0 通过 / 1 有问题（钩子还多带 --sections-strict）
生成器幂等	& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py	重跑到临时目录逐字节比对；必须 .venv 解释器，否则字库链假红 → docs/门禁说明/generated-fresh.md §4
一把梭（上面多数静态项 + 主机单测）	& '.venv\Scripts\python.exe' scripts/ci_local.py	非 0 就别抢跑（但它不含 stack_report / ram_baseline，数字与安全边界要另跑）

⚠ 这张表为什么必须存在：stack_report 与 ram_baseline --gate 这类根本不在钩子清单里（它们要 Keil 构建产物， 只能靠人在 /keil-build 后跑），所以「人漏跑一次」直接等于「这道检查这一次不存在」。想机械化，先要解决「磁盘上的 .htm / .map 属于最后一次构建的人」这个归因问题——与 §2.2「stash 覆盖面」那条同源，不是加一根钩子就完事 （mem-budget 今天红在「台账与 .map 不同码」正是同一个形状）。

一行式字节卫生（整条刻意写成纯 ASCII——粘进 PowerShell 与存成 .ps1 两种方式实测都过；含中文版在 Windows PowerShell 5.1 下按 ANSI 读 .ps1 会碎成语法错误，所以别加中文标签）。 实测 2026-10-26：全树 39 个待提交文件（含 ?? 未跟踪）→ problems 0，退出码 0：

& '.venv\Scripts\python.exe' -c "import subprocess as sp,os,sys;st=sp.run(['git','status','--porcelain'],capture_output=True,text=True,encoding='utf-8',errors='replace').stdout.splitlines();ext=('.c','.h','.py','.md','.txt','.yaml','.json');fs=[l[3:].strip().strip(chr(34)) for l in st if l[3:].strip().endswith(ext)];fs=[p for p in fs if os.path.isfile(p)];bad=[];[bad.append((p,''.join(t).strip())) for p in fs for b in [open(p,'rb').read()] for t in [[('CR ' if b'\r' in b else '')+('NOEOL ' if not b.endswith(b'\n') else '')+('FFFD ' if b'\xef\xbf\xbd' in b else '')+('TWS ' if any(x.endswith(b' ') or x.endswith(b'\t') for x in b.split(b'\n')) else '')]] if t[0]];print('byte-hygiene: checked',len(fs),'files (incl untracked), problems',len(bad));[print('   ',p,'=>',t) for p,t in bad]"

B. 手跑代替不了真提交的三类，抢跑时得自己补

类别	为什么不等价	抢跑时怎么做
改写型钩子 trailing-whitespace / end-of-file-fixer	它们会改文件。真提交里改的是 stash 之后的树；而手跑 --files 不 stash（§2.2 那两行），直接落在工作区——列了别人在飞的文件就等于替人改文件	只列自己的文件：-m pre_commit run <id> --files <自己的文件>；或先用 A 组的一行式查出问题自己修，别让钩子替你动盘
要靠 stash 才能正确归因的判定：mem-numbers / mem-budget（读磁盘 .map）、stack_report（读磁盘 .htm）、ui-golden / uinav-selftest（要模拟器 exe 与台架锁）、test-coverage（会编译，可能撞别人的 .obj）	磁盘上的 .map / .htm / .exe 属于最后一次构建的人，不是你的 ⇒ 手跑红常常是替别人背账（今天 mem-budget 就红在「台账与 .map 不同码」，因为 .map 里混着三条在飞源码道）	照样要跑（宁可多跑），但红先归因：git status --porcelain 看是谁在飞、.htm 的时间戳是哪次构建；确认不属本笔就在提交正文点名，不要改基线数字去凑绿
只有真提交才会碰到的面：gitlint（commit-msg 阶段）与未声明 stages: 会跑两遍的钩子	手跑脚本查不到提交信息规范（标题 ≤100、正文每行 ≤80）	提交信息一律 git commit -F <UTF-8 无 BOM 文件> 并自查最长行；或先老实提交一次让 gitlint 说话，再改成 --no-verify
manual 阶段的三根（cppcheck / test-cppcheck / test-coverage）	pre-commit run --all-files 只跑 pre-commit 阶段（47 根），不会碰它们——漏跑不会报红，只会静默少一道门禁	抢跑时补：& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual <hook-id>，一次一个 id（见 §2.2「三个阶段」行）

C. 抢跑之后（三条都来自今天的真事，不是设想）

1. 对交付清单：git show --stat --oneline HEAD 与提交正文声明的文件逐条对上；再 git status --porcelain， 里面不该再出现你声明过的文件（含 ?? 未跟踪）——「漏提 runner」正是这一步才会发现的。
2. 正文点名三件事：哪些门禁没跑、为什么没跑、当时谁在飞。今天三笔都写了，保留为强制，不是可选项。
3. 静默窗口补一次全量：& '.venv\Scripts\python.exe' -m pre_commit run --all-files。⚠ --all-files 同样不 stash，而且会让改写型钩子当场改全库文件——只能在确认没人写盘的窗口跑，跑完 git status 复核被改动的是不是只有你那几笔（别人在飞时跑它 = 替人改文件，比重跑生成器更危险）。

---

2.5 写进提交信息与文档的每条归因，必须带可复核证据（2026-10-27 立，当天三次真实返工换来的）

钩子拦得下形态错，拦不下归因错。下面四条没有一条是机器能自动判的，但每一条当天都真的 发生过，代价从「别人返工」到「公开怪错一个道」都有：

1. 数字必须钉产物身份：写一个数，就同时写它出自哪份产物（路径）+ 哪一次构建或运行时刻 （静态链写 Linker run 时刻，脚本类写日期 + 命令）。重跑同一个报告脚本不算新测量——产物 没变，数字必然不变，那只是复述；写成「我复验过」就是假凭证。 ⚠ 本仓真实坑：scripts/stack_report.py 的 REPO_ROOT 跟着 __file__ 走（不看 cwd），所以 「cd 进别的 worktree 再跑主仓的脚本」量的还是主仓产物。要量哪棵树，就用那棵树自己的 scripts/、从那棵树的根起跑。
2. hash 不是稳定身份，tree + 父提交才是：--amend 与重写正文都会换 hash。出「按 hash 复核」 的回执之前先 git reflog 看一眼有没有人被重写过；反过来说，先请别人按 hash 复算、自己再去 重写 hash 是顺序错误（2026-10-26 真实发生，等于让对方的回执一出生就过期）。要证明「只换了 正文」，用「git diff 旧 新 为空 + tree hash 相同」两条，比任何口头都硬。
3. 归因之前先确认这个数字来自哪棵树、哪一次运行：并发时序不是谁的错。当天有过一次把「文件 mtime 晚于构建」误判成某个道「删了实现才去注册」，实际只是两条道同时在写、构建读到中间态； 更正时把两个道都点到名，并把这条写成硬规矩，而不是悄悄改口。
4. 「我核过」不等于机器核过：当天两次真实反例——「6 个文件 BOM 逐个核过」随后被 bom-guard 抓到丢 BOM；自写的扫描脚本报「0 处嵌套注释」，是脚本自己有 bug 的假绿。结论一律附上可复跑 的命令与退出码（或门禁名 + 实测数字），不写「已确认无误」这种无法反驳的话。

同族第二条：注释与文档必须陈述事实，而不是意图。 ui_data_maint_ready() 的头注释写着「页面用 它决定这页能不能操作——未注入时按钮一律拒并按 LOCK 显示」，而页面从来没用过它：全仓零消费者， 只有它自己的用例在读。这条值得单列，是因为它解释了失效机制——评审读的是意图陈述，门禁读的是 可达路径，两者都不反驳「意图未实现」，所以一个假接口能活过一整轮评审。写法要求：接口注释要么 描述当前真实的消费者与真实行为，要么显式写「尚无消费者，等待某件事落地」；禁止用将来式或能力式 语气陈述未实现的行为（那会让下一个人在它上面继续盖楼）。能被机器兜的那一半已经兜住了——死代码 靠 bsp-err 的 consume-result 与覆盖率总闸暴露，「改了生成器没重跑生成物」靠 generated-fresh 拦； 但注释里的意图陈述没有任何钩子能证伪，只能靠写的人自觉，所以才把它写在这里。

3. 日常工作流

3.1 正常提交（秒级完成）

git add .
git commit -m "修复网络超时重连逻辑"

全部钩子自动运行，只检查本次 staged 的文件（增量扫描）。通常 <5 秒完成。

3.2 钩子失败后的处理

# 提交被拦截，查看报错信息
# 修复后重新 add + commit
git add .
git commit -m "修复网络超时重连逻辑"

常见失败场景与处理：

钩子	失败表现	处理步骤
trailing-whitespace	Fixing xxx.c → 需要重新 git add	钩子已自动修复文件，git add 后重新提交
end-of-file-fixer	同上	同上
cppcheck	报 warning/performance/portability/style	根据报告修复代码；误报用行内抑制或 --suppress（详见 docs/代码规范/cppcheck使用说明.md）
no-mojibake	U+FFFD replacement chars found	从 git 历史恢复干净版本（不可逆！）
coding-standard	L行号 [Sx x.x.x] 规则说明	按违规项修复（命名加前缀/大写化、补函数注释、sprintf 改 snprintf 等）
gitlint	Title exceeds max length	精简 commit message 标题

3.3 全库扫描（配置变更后）

pre-commit run --all-files

仅在以下场景使用：

• 首次 pre-commit install 后确认基线
• 修改 .pre-commit-config.yaml 后验证
• cppcheck 新增 suppress 规则后验证

日常提交不需要跑 --all-files，pre-commit 会自动只检查 staged 文件。

3.4 手动运行单个钩子

pre-commit run cppcheck --all-files       # 只跑 cppcheck
pre-commit run trailing-whitespace --files path/to/file.c  # 只检查单个文件
pre-commit run no-mojibake --files path/to/file.c
pre-commit run gitlint --hook-stage commit-msg --commit-msg-filename .git/COMMIT_EDITMSG

3.5 临时跳过钩子（紧急情况）

git commit -m "紧急修复" --no-verify
# 或跳过特定钩子
SKIP=cppcheck git commit -m "紧急修复"

⚠️ 不推荐：--no-verify 一次跳过 47 条（连 gitlint 一起 = 48 条；manual 阶段三根本来不随提交跑），不是「跳过格式检查」。跳之前必须先跑 §2.4 抢跑自查表 （尤其 stack_report.py——它不在钩子清单里，只有人会跑；数字与安全边界类问题不会自己冒出来）。跳之后按 §2.4 C 组 补齐三件事：git status 对交付清单、正文点名「哪些没跑 / 为什么 / 谁在飞」、静默窗口补一次 run --all-files。

---

4. 新机器启用

# 1. 安装 pre-commit（需要 uv）
uv tool install pre-commit

# 2. 安装 cppcheck（需要 winget）
winget install cppcheck
# 重开终端使 PATH 生效

# 3. 进入仓库，安装钩子
cd D:\Code\DTU Code\STM32F4-Base
pre-commit install

# 4. 首次全库扫描（确认基线）
pre-commit run --all-files

---

5. 已知问题与注意事项

5.1 cppcheck 找不到

现象：Executable cppcheck not found

原因：cppcheck 安装后 PATH 更新在注册表，已运行的终端不会刷新。

解决：重开终端即可。若需在当前会话临时修复：

$env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")

5.4 clang-format 未启用

原因：全库 222 个 .c/.h 文件大概率不满足 clang-format 默认格式，启用后会批量重写。

计划：Route B —— 全库统一格式化后形成独立基线 commit，再启用 clang-format 钩子。启用时取消 .pre-commit-config.yaml 中的注释即可。

5.5 顶层 exclude 曾整目录豁免 simulator/（2026-10-11 已修）

现象：改 simulator/ 下任何文件（含 simulator/lv_conf.h）的提交一个钩子都不跑——pre-commit run --files simulator/lv_conf.h 里所有钩子都是 (no files to check) Skipped。

根因：顶层 exclude 写了 simulator/。当初是为了挡 SDL2 预编译库、build/、截图产物，但这些已在 .gitignore 里，本就进不了 git 索引；pre-commit 只看索引中的文件，所以那条豁免唯一实际效果是把本项目自研的 21 个 tracked 文件（main.c、sim/*.c|h、tests/*.py、lv_conf.h、dbg_log.h、3 个 README）整体挡在门禁之外。

为什么必须修：模拟器与固件共用同一套 UI 源码，且它是 UI 回归唯一的像素级证据来源——它落在门禁外，等于验证链的地基不受检。

纳入后的实测收益（当天）：cppcheck 立刻揪出 sim_syslog.c 一处真实空指针解引用（if (p_epoch == NULL || …) { *p_epoch = 0u; … }——判空分支里紧接着解引用），另有 2 处 localtime_s 未初始化告警、1 处 px 可加 const；coding-standard 报出 61 处（44 处函数左大括号 Allman 风格、8 处缺函数注释、3 处缺文件头注释、2 处 __ 前缀保护宏、2 处 sprintf、2 处 CODE-RULE-11 误报），已全部处理。

顺带修掉的规则缺陷：CODE-RULE-11 原实现把任何含 / 的 include 判违规，误伤 <sys/stat.h> 这类系统头；已按 include 形态细化，判定见 docs/门禁说明/coding-standard.md §1。

教训：exclude 只写真正不该进钩子的路径。已被 .gitignore 覆盖的生成物不需要再挡一遍——写上去只会连带豁免同一目录里的自研代码。

---

6. 文件清单

文件	位置	说明
.pre-commit-config.yaml	仓库根	钩子配置（52 个钩子声明数，一次 git commit 实跑 49 根；口径 = YAML 解析后的 hook 条目数，自查命令 → docs/门禁说明/README.md §2。声明数与一次提交的实跑数分列，勿混写；计数改动的完整台账只记在 AGENTS.md 提交门禁节与本目录 README §2，本行不重述）。逐项详解在 docs/门禁说明/（索引 docs/门禁说明/README.md；主机侧单测 22 根合一篇，含各套件来历与「22 套无专属钩子」台账（现值 2026-10-29） docs/门禁说明/host-unit-tests.md §6；UI 侧另有 font-charset 与 ui-golden 两篇）
.gitlint	仓库根	gitlint 规则（宽松，兼容中文）
.cubemx_survival_baseline.json	仓库根	CubeMX 易失定制基线（哈希；--write 重建）
scripts/check_mojibake.py	scripts/	U+FFFD 检测脚本
scripts/check_coding_standard.py	scripts/	代码规范检查脚本（规范 V1.0 可机械校验项）
scripts/check_doc_links.py	scripts/	文档链接存在性检查
scripts/gen_task_table.py	scripts/	FreeRTOS 任务表生成/校验
scripts/check_mem_numbers.py	scripts/	内存/Flash 数字一致性（体积档）
scripts/check_cubemx_survival.py	scripts/	CubeMX 重生成存活审计
scripts/check_lv_conf_sync.py	scripts/	两份 lv_conf.h 特性子集一致性（比对生效值 + 无效宏名 + 重复定义）
scripts/check_test_suite.py	scripts/	测试套件开关门禁（防测试固件静默提交）
scripts/check_font_charset.py	scripts/	UI 字符集差集检查（复用 tools/font_gen/ 提取与 cmap 解析规则，防缺字白框）
scripts/check_layer_deps.py	scripts/	分层方向门禁（BSP 反向 include App 的增量拦截，存量基线只减不增）
scripts/check_bsp_err.py	scripts/	BSP 错误码与超时命名门禁（三条规则的增量拦截，存量 19 条基线只减不增；--emit-baseline 建基线）
docs/代码规范/嵌入式C语言代码规范_V1.0.md	docs/代码规范/	代码规范原文（CODE-RULE-01~CODE-RULE-20 规则来源；CODE-RULE-20 出处不在规范正文而在 AGENTS.md 平台约束，见 docs/门禁说明/coding-standard.md）
docs/代码规范/cppcheck使用说明.md	docs/代码规范/	cppcheck 钩子详解（规则/配置/抑制）
docs/文档规范.md	docs/	文档体系规范（链接形态/命名/门禁要求）
docs/代码规范/pre-commit使用说明.md	本文档	部署与使用说明

---

7. 快速参考卡片

提交代码:        git add . && git commit -m "描述"
全库扫描:        pre-commit run --all-files
单钩子扫描:      pre-commit run <hook-id> --all-files
扫描单个文件:    pre-commit run <hook-id> --files <path>
跳过钩子:        git commit --no-verify  (紧急；跳之前先跑 §2.4 自查表)
查看已安装钩子:  ls .git/hooks/
卸载钩子:        pre-commit uninstall
更新钩子版本:    pre-commit autoupdate

CubeMX 重生成后立刻执行（检查定制是否被覆盖）：

python scripts/check_cubemx_survival.py            # 列"被覆盖了哪几处"+修复提示
python scripts/check_cubemx_survival.py --write    # 确认无误后重建基线