oh-precommit-codecheck

OH Precommit Codecheck

运行本地代码质量检查。包含门禁 CI 检查和其他仅限本地的检查。

门禁 CI 检查（与 OpenHarmony 门禁相同）：

• 版权信息：检查文件头是否存在、年份是否正确、注释风格是否符合要求（C/C++ 使用 /**）
• C/C++ 格式：clang-format（优先使用 clang-format-14，否则回退到 clang-format）
• C/C++ 质量：CodeArts Check（codecheck-ide-engine + Huawei clang-tidy：clangtidy + secfinder + fixbot）

其他本地检查（不属于门禁 CI，用于提升质量）：

• Python：pylint + flake8
• Shell：shellcheck + bashate-mod-ds
• GN：gn format --dry-run

注意事项

• 首次运行会将约 600MB 的 CodeArts 工具下载到 ~/.codecheck-tools/
• Python/Shell 代码检查工具必须预先安装（pylint、flake8、shellcheck、bashate-mod-ds）
• 如果没有 compile_commands.json，C/C++ 检查可能会遗漏一些依赖上下文的问题
• GN 格式检查要求 PATH 中包含 gn

当前限制

此技能仅涵盖完整 OpenHarmony 门禁 CI 检查的部分内容：

• 语言：仅检查 C/C++、Python、Shell 和 GN。Java、JavaScript、TypeScript、ArkTS 尚未接入（CodeArts 引擎在本地已包含这些语言的规则）。
• C++ 规则：约覆盖 163 条门禁 G.* 规则中的 114 条（约 70%）。缺失的规则主要是没有 -CPP 后缀的 C 语言变体。
• 完全未覆盖：WordsTool 敏感词检查（200 多条规则）、OAT 开源合规检查（约 10 条规则）、安全专项检查（弱加密、不安全的 IPSI）、代码指标检查（函数/文件/复杂度过大、冗余/重复代码）。
• 本地检查通过不能保证门禁检查通过——这只是尽力而为的预筛选。

快速参考

调用方式	模式	行为
/oh-precommit-codecheck（独立调用）	模式 1	检查指定文件、报告结果，并在修复前征求同意
/oh-precommit-codecheck --fix	模式 1	检查并自动修复，最多进行 3 轮
由 oh-pr-workflow 自动触发	模式 2	静默检查并自动修复，仅在仍有缺陷时报告
Pre-commit hook	模式 2	与自动触发相同

确定触发模式

检查是否设置了 $ARGUMENTS。

模式 1：用户主动调用（已设置 $ARGUMENTS 或调用了 /oh-precommit-codecheck）

解析 $ARGUMENTS，以确定文件范围和修复模式：

/oh-precommit-codecheck              → files from: git diff --cached --name-only
/oh-precommit-codecheck <commit>     → files from: git diff-tree --no-commit-id -r <commit> --name-only
/oh-precommit-codecheck <file ...>   → the listed files directly
/oh-precommit-codecheck --fix        → same file resolution + auto-fix mode

参数解析规则：

• --fix 标志可以出现在参数中的任意位置
• 如果某个参数看起来像 Git 提交（与 git rev-parse --verify <arg> 匹配），则将其视为提交
• 否则将参数视为文件路径

步骤：

1. 根据上述规则解析文件列表。仅保留现有文件。
2. 调用检查脚本运行检查：

   bash ~/.claude/skills/oh-precommit-codecheck/scripts/check.sh <file1> <file2> ...
   

3. 以简明汇总表的形式向用户展示结果。
4. 如果发现缺陷且未指定 --fix：
   • 建议：“运行 /oh-precommit-codecheck --fix 以自动修复这些问题。”
5. 如果指定了 --fix 且发现了缺陷：
   • 对于版权信息缺陷：直接修复版权文件头（添加缺失的文件头、更新年份、更改注释风格）。
   • 对于 C/C++ 缺陷：阅读每个有缺陷的文件，理解规则违规原因，并直接使用 Edit 工具修复。
   • 对于 Python 缺陷：阅读每个有缺陷的文件，理解规则违规原因，并直接使用 Edit 工具修复。
   • 对于 Shell 缺陷：阅读每个有缺陷的文件，理解规则违规原因，并直接使用 Edit 工具修复。
   • 对于 GN 格式缺陷：运行 gn format <file> 自动格式化。
   • 修复后，重新运行检查脚本进行验证。最多重复 3 轮。
   • 报告仍未修复的缺陷。

模式 2：AI 自动触发（无 $ARGUMENTS，完成代码更改后）

刚刚完成代码文件的编写或修改后，自动检查这些文件。

步骤：

1. 收集你在本次对话中刚刚修改的文件列表（从工具调用历史中查找 Edit/Write 调用）。
2. 运行检查：

   bash ~/.claude/skills/oh-precommit-codecheck/scripts/check.sh <modified_files...>
   

3. 如果没有缺陷：静默通过——除非用户询问，否则不要提及检查。
4. 如果发现缺陷： a. 自动修复每个缺陷：
   • 对于版权：添加或更新版权声明头。
   • 对于 C/C++ 机械性修复（G.FMT.11-CPP 大括号、G.EXP.35-CPP nullptr、G.FMT.05-CPP 行宽）：直接修复。
   • 对于 C/C++ 需要判断的事项（G.NAM.03-CPP 命名、G.FUN.01-CPP 大小）：不要自动修复——向用户报告。
   • 对于 Python / Shell：直接修复标准规则，报告有歧义的问题。
   • 对于 GN 格式：运行 gn format <file>。 b. 重新运行检查以验证修复。 c. 总共最多重复 3 轮。 d. 如果 3 轮后仍有缺陷，向用户报告无法修复的问题。

模式 2 与 CLAUDE.md 的交互：由提交前钩子或 oh-pr-workflow 触发时，模式 2 会自动修复，以简化提交流程。此时优先于 CLAUDE.md 中“先展示报告”的约定，因为用户已表达提交意图。如果单独调用（/oh-precommit-codecheck，且无提交上下文），则默认只报告，并在修复前征求同意。

---

以下为参考部分——修复特定类型的缺陷时请查阅。 如果只需要注意事项，请跳转到“常见错误”。

修复指南

自动修复缺陷时，请根据下方规则进行修复。如果未列出相应规则，请阅读缺陷消息并自行判断。

版权

• no-copyright：添加完整的 Apache 2.0 版权声明头（模板见 CLAUDE.md）
• wrong-year：更新年份范围，使其包含当前年份（例如，2025 → 2025-2026）
• wrong-comment-style：对于 .cpp/.c/.h/.hpp 文件，将首行改为 /**（块注释风格）

C/C++（CodeArts）

• G.FMT.11-CPP（大括号）：为单行 if/for/while/else 语句块添加 {}。
• G.NAM.03-CPP（命名）：修正变量/函数名，使其符合约定。
• G.EXP.35-CPP（nullptr）：将 NULL / 0（指针上下文）替换为 nullptr。
• G.FUN.01-CPP（参数）：无法自动修复——向用户报告。
• G.CNS.02-CPP（魔法数字）：将其提取为具名 constexpr 常量。

Python

• C0304（末尾换行）：添加末尾换行。
• C0305（末尾换行）：删除多余的尾随空行。
• C0321（多条语句）：拆分为多行。
• C0410（多个导入）：每行一个导入。
• C0411（导入顺序）：按标准库 → 第三方库 → 本地库的顺序重新排列。
• 其他 pylint/flake8 规则：阅读消息并据此修复。

Shell

• SC2086（双引号）：为变量展开添加双引号。
• SC2164（cd 失败）：在 cd 命令后添加 || exit。
• SC2148（shebang）：在文件顶部添加 #!/usr/bin/env bash。
• 其他 shellcheck 规则：阅读消息并据此修复。

GN

• 运行 gn format <file>——全自动完成，无需手动干预。

常见错误 — 绝对不要这样做

• 绝对不要对未通过 gn parse 的文件运行 gn format — 这会破坏文件。先运行 gn parse；如果失败，请先手动修复语法，再进行格式化。
• 绝对不要自动修复 G.FUN.01-CPP（函数过长） — 这需要架构层面的判断。务必向用户报告。
• 绝对不要在未阅读周边代码的情况下自动修复 G.NAM.03-CPP 命名问题 — 命名规范取决于上下文（成员变量、全局变量和函数参数有不同的规则）。
• 如果 CodeArts 引擎日志显示启动错误，绝对不要相信缺陷数为 0 — 请确认 defects.json 非空，且引擎正常退出。
• 绝对不要假设本地工具版本与门禁 CI 一致 — 版本不匹配会导致假阴性。如果结果与门禁不一致，请检查：java -version、clang-tidy --version、pylint --version。
• 如果只有一个检查器失败，绝对不要重新运行完整检查套件 — 只重新运行失败的检查器以节省时间。

错误恢复

• CodeArts 引擎无法启动：检查 java -version（需要 11+）。检查下载文件完整性：md5sum codecheck-ide-engine.jar。重新运行设置脚本：bash scripts/setup_codecheck.sh --force。
• 缺少 compile_commands.json：C++ 检查的假阴性率约为 30%。使用以下命令生成：gn gen out/default --export-compile-commands，或接受准确率降低的结果。
• pylint/flake8 版本不匹配：门禁使用特定版本。使用 pylint --version 检查，并与门禁 CI 日志进行比较。

示例输出

模式 1 的典型结果：

Codecheck Results (12 defects):
| Rule | Count | File | Auto-fixable |
|------|-------|------|-------------|
| G.FMT.11-CPP | 5 | token_test.cpp | Yes |
| G.NAM.03-CPP | 3 | token_test.cpp | Yes (with context) |
| G.EXP.35-CPP | 2 | token_test.cpp | Yes |
| G.FUN.01-CPP | 1 | token_test.cpp | No — report to user |
| G.FMT.05-CPP | 1 | token_test.cpp | Yes |

发现 12 个告警，其中 11 个可自动修复。是否修复？