From ed81a97442bc46960f0b63330c3981ba1000886b Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Tue, 1 Sep 2026 13:26:40 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84pre-commit=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=EF=BC=9A=E8=A1=A5=E5=85=85cppcheck=E8=AF=A6?=
 =?UTF-8?q?=E8=A7=A3=EF=BC=8C=E6=9B=B4=E6=96=B0no-mojibake=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/pre-commit使用说明.md | 100 ++++++++++++++++++++++++-------------
 1 file changed, 64 insertions(+), 36 deletions(-)

diff --git a/docs/pre-commit使用说明.md b/docs/pre-commit使用说明.md
index da5938e0..61c46372 100644
--- a/docs/pre-commit使用说明.md
+++ b/docs/pre-commit使用说明.md
@@ -86,29 +86,73 @@ git commit
 
 ### 2.6 cppcheck — C 静态分析
 
-| 项 | 说明 |
+cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法分析和数据流推理发现潜在缺陷。
+
+**工作原理**：逐个读取 C 文件 → 分析语法/数据流/控制流 → 发现问题则报错。
+
+#### 本项目开启的检查类别
+
+| 类别 | 含义 | 典型问题 |
+|---|---|---|
+| `warning` | 通用警告 | 变量未使用、除零风险、空指针解引用、 unreachable code |
+| `performance` | 性能问题 | 不必要的值拷贝、字符串重复查找、低效的函数调用 |
+| `portability` | 可移植性问题 | 不同平台行为不一致的代码、隐式类型转换 |
+
+#### 不开启的常见类别
+
+| 类别 | 为什么不开 |
 |---|---|
-| **触发条件** | C 文件含 warning / performance / portability 级别缺陷 |
-| **处理方式** | **阻止提交** |
-| **扫描范围** | `App/`、`Src/`、`Inc/`、`Drivers/BSP/` 下的 .c 文件（排除第三方库） |
-| **已知抑制** | `missingInclude`、`invalidPrintfArgType_sint/uint`（项目安全使用，非真正缺陷） |
-| **典型报错** | `path/to/file.c:42: warning: ...` |
-| **修复方式** | 根据 cppcheck 报告修复代码缺陷；若为误报可在 `.pre-commit-config.yaml` 的 args 中添加 `--suppress=规则名` |
+| `style` | 太多噪音（未使用函数、未用参数），会淹没真正问题 |
+| `error` | 严重错误（数组越界、内存泄漏），cppcheck 默认已包含，不需要显式加 |
+| `information` | 信息类（未解析的头文件等），无实际价值 |
 
-**排除目录**（不参与 cppcheck 扫描）：
+#### 配置参数说明
 
 ```
-Drivers/CMSIS/          # ARM CMSIS（第三方）
-Drivers/STM32F4xx_HAL_Driver/  # ST HAL（第三方）
-Drivers/BSP/UI/         # LVGL UI 层（第三方）
-Drivers/BSP/NET/lftpd/  # LwIP FTP（第三方）
-Drivers/BSP/dhara/      # NAND FTL（第三方）
-Lib/                    # LVGL 库
-Middlewares/            # FreeRTOS
-MDK-ARM/                # Keil 工程文件
-test/                   # 测试代码
+--std=c99                    # 按 C99 标准检查（Keil 工程常用）
+--error-exitcode=1           # 发现问题返回非零退出码（pre-commit 用来拦截提交）
+--quiet                      # 只报问题，不显示扫描进度
+--suppress=missingInclude    # 抑制"找不到头文件"（HAL/CMSIS 路径在 Keil 工程配置里，cppcheck 不知道）
+--suppress=invalidPrintfArgType_sint  # printf 的 %d 传 uint32_t —— 实际安全，非真正缺陷
+--suppress=invalidPrintfArgType_uint  # printf 的 %u 传 int —— 实际安全，非真正缺陷
+-I Inc -I App -I Drivers/BSP  # 指定头文件搜索路径，让 cppcheck 能解析 #include
 ```
 
+#### 扫描范围
+
+通过 `types: [c]` + `exclude` 控制：
+
+**检查**：`App/`、`Src/`、`Inc/`、`Drivers/BSP/` 下的 .c 文件
+
+**不检查**（第三方库，问题不是我们的）：
+
+```
+Drivers/CMSIS/              # ARM CMSIS
+Drivers/STM32F4xx_HAL_Driver/  # ST HAL
+Drivers/BSP/UI/             # LVGL UI 层
+Drivers/BSP/NET/lftpd/      # LwIP FTP
+Drivers/BSP/dhara/          # NAND FTL
+Lib/                        # LVGL 库
+Middlewares/                # FreeRTOS
+MDK-ARM/                    # Keil 工程文件
+test/                       # 测试代码
+```
+
+#### 如何抑制误报
+
+如果 cppcheck 对某段代码报了误报，在 `.pre-commit-config.yaml` 的 cppcheck `args` 中添加：
+
+```yaml
+args: [--suppress=规则名, ...]
+```
+
+常用可抑制规则：`uninitvar`（未初始化变量，但你确定后续会赋值）、`knownConditionTrueFalse`（条件恒真/假，但你故意这么写）。
+
+#### 日常速度
+
+- **增量扫描**（`git commit` 时）：只检查 staged 文件，通常 <1 秒
+- **全库扫描**（`pre-commit run --all-files`）：约30秒，仅在配置变更后使用
+
 ### 2.7 no-mojibake — U+FFFD 乱码拦截
 
 | 项 | 说明 |
@@ -117,15 +161,9 @@ test/                   # 测试代码
 | **处理方式** | **阻止提交**（不可逆，必须修复） |
 | **检测原理** | `scripts/check_mojibake.py` 以二进制读取文件，检测 `0xEF 0xBF 0xBD` 字节序列 |
 | **典型报错** | `U+FFFD replacement chars found (encoding corrupted, irreversible!): path/to/file.c` |
-| **修复方式** | 从 git 历史中找到最后一个干净版本（`git log` + `git show HEAD~N:path/to/file.c > file.c`），手动恢复损坏区域 |
+| **修复方式** | 从 git 历史中找到最后一个干净版本，手动恢复损坏区域 |
 
-**已知豁免**（`exclude` 配置）：
-
-```
-Drivers/BSP/TPAFE5160/tpafe5160.c   # 历史遗留乱码，待修复后取消豁免
-```
-
-> ⚠️ **编码铁律**：U+FFFD 是不可逆损坏。若发现新文件出现 U+FFFD，必须排查写入方式（禁用 Get-Content / Set-Content 重写中文文件）。
+> ⚠️ **编码铁律**：U+FFFD 是不可逆损坏（无法从替换符反推原始中文字符）。若发现新文件出现 U+FFFD，必须排查写入方式（禁用 Get-Content / Set-Content 重写中文文件）。
 
 ### 2.8 gitlint — Commit Message 格式
 
@@ -237,16 +275,6 @@ pre-commit run --all-files
 $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
 ```
 
-### 5.2 tpafe5160.c 乱码
-
-**状态**：已知历史遗留，HEAD（`e06d849`）已含 131 处 U+FFFD。no-mojibake 钩子已豁免该文件。
-
-**修复计划**：从 `fe107ea`（干净版本）恢复注释区，完成后取消 `.pre-commit-config.yaml` 中的 `exclude` 条目。
-
-### 5.3 LVGL 文档移动未提交
-
-**状态**：工作区有 `docs/测试说明/LVGL模拟器部署与使用说明.md` 的删除（D）和 `docs/LVGL模拟器部署与使用说明.md` 的未跟踪（??），为用户历史操作，不在 pre-commit 管理范围内。
-
 ### 5.4 clang-format 未启用
 
 **原因**：全库 222 个 .c/.h 文件大概率不满足 clang-format 默认格式，启用后会批量重写。
@@ -263,7 +291,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
 | `.gitlint` | 仓库根 | gitlint 规则（宽松，兼容中文） |
 | `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 |
 | `docs/自动化代码审查实施.md` | docs/ | 实施规划文档（Route A/B 设计） |
-| `docs/测试说明/pre-commit使用说明.md` | 本文档 | 部署与使用说明 |
+| `docs/pre-commit使用说明.md` | 本文档 | 部署与使用说明 |
 
 ---