Git Diff Reviewer：AI 代码审查拦截提交前的 Bug

为什么提交前审查如此重要

匆忙提交代码后才发现引入安全漏洞或低级 Bug，几乎是每个开发者都经历过的循环。CI/CD 失败再回头修复，或者等队友在代码审查时发现问题，时间成本都不低。Git Diff Reviewer 的思路很直接：在 git commit 触发时就把暂存区的 diff 交给 LLM 审查，问题在本地就暴露出来。

Git Diff Reviewer 项目来源与概览

这是一个基于终端的 CLI 工具，以 pre-commit hook 的形式嵌入 Git 工作流。它提取暂存区的差异，发送给 Gemini、OpenRouter、Groq 或本地 Ollama 等 LLM 提供商，然后在终端中输出结构化的审查结果。

pre-commit hook 是 Git 的一种客户端钩子机制。Git 在提交生命周期的多个节点预留了脚本执行入口，其中 pre-commit 在开发者敲下 git commit 之后、提交对象真正生成之前触发。只要该脚本以非零状态码退出，Git 就会中止这次提交。这一特性使它成为在代码进入仓库前进行拦截的理想位置：格式检查、密钥扫描、lint 和本文所述的 AI 审查都可以挂载于此。钩子脚本存放在 .git/hooks/ 目录下，默认不随仓库分发，因此像 Git Diff Reviewer 这样提供 --install-hook 命令的工具，本质上是帮用户把脚本写入本地钩子目录并赋予可执行权限，从而让每次提交自动触发审查。

核心功能与审查分类

Git Diff Reviewer 支持多提供商切换：Gemini 能力较强，Groq 延迟极低，OpenRouter 提供模型灵活性，Ollama 则满足 100% 本地隐私需求。工具通过 .reviewerignore 过滤 lockfile、构建产物和 .env 文件，避免浪费 token。

审查结果不是笼统的"这里有问题"，而是按严格分类呈现：

类别	捕获内容
严重 Bug	逻辑错误、无限循环
🔒 安全漏洞	SQL 注入、XSS、硬编码密钥（对齐 OWASP/CWE）
⚠️ 反模式	代码坏味道与不良实践
⚡ 性能瓶颈	N+1 查询、低效循环

每个问题附带文件、行号、问题说明和修复建议，部分还会给出 Before/After 代码片段。项目附带了 22 个单元测试来保证可靠性。

OWASP 与 CWE 是安全领域两套互补的漏洞分类体系。OWASP（Open Web Application Security Project）发布著名的 Top 10，从风险视角归纳 Web 应用最常见的十大安全威胁，如注入、失效的访问控制、加密失败等，偏重“风险类别”和防御建议。CWE（Common Weakness Enumeration）则由 MITRE 维护，是对软件弱点的标准化枚举，每个弱点有唯一编号，如 CWE-89 对应 SQL 注入、CWE-79 对应 XSS。二者的关系是：一个 OWASP 风险类别往往对应多个具体 CWE。AI 审查工具在报告中引用 CWE 编号，好处是漏洞类型被映射到业界公认的字典，安全工程师可以直接据此查询修复方案、对接 SAST 工具或漏洞管理系统，而不用依赖模糊的自然语言描述。

架构与工作流程

工具的执行链路清晰：

git commit -m "feat: update auth"
         ▼
Pre-commit hook (python main.py --staged)
         ▼
提取暂存 diff + .reviewerignore 过滤
         ▼
LLM Provider (Gemini | Groq | OpenRouter | Ollama)
         ▼
终端输出结构化审查

除了 --staged 审查暂存区，它还支持 --unstaged 审查未暂存改动，以及 --branch main 对比特定分支或提交。交互模式下可以引导式选择 diff 目标和提供商。大 diff 会被安全截断，避免超出模型上下文窗口，审查结果还能导出为 Markdown 文件，方便贴到 PR 评论中。

暂存区（staging area）是 Git 三棵树模型中的关键一层。Git 维护工作区（working directory）、暂存区（index/staging area）和版本库（repository）三个区域。git add 把工作区的改动写入暂存区，git commit 再把暂存区的内容固化为一次提交。因此“暂存区 diff”即 git diff --staged 所展示的、即将被提交的那部分改动。Git Diff Reviewer 默认只审查这一部分，而不是整个工作区，正是为了聚焦于本次提交真正会引入的变更——未被 git add 的临时改动不会被误报。与之相对的 --unstaged 审查的是工作区中尚未暂存的改动，--branch main 则对比当前分支与目标分支的差异，三者对应不同的审查场景。

安装与配置

配置流程分五步：克隆仓库、创建虚拟环境、安装依赖、配置环境变量、安装 Git hook。

git clone https://github.com/humammoin09-blip/git-diff-reviewer.git
cd git-diff-reviewer
python -m venv .venv
source .venv/bin/activate   # Windows 用 .\\.venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
cp .env.example .env

在 .env 中配置提供商，例如 Gemini：

LLM_PROVIDER=gemini
GEMINI_API_KEY=your_api_key_here

如果追求完全隐私，把 LLM_PROVIDER 设为 ollama 并运行本地模型即可。最后执行 python main.py --install-hook 安装钩子。此后的每次提交都会自动触发 AI 审查。

实际效果示例

假设你写了这样一段代码：


**参数化查询是防御 SQL 注入的根本手段**。SQL 注入的成因是把用户输入直接拼接进 SQL 语句字符串，使攻击者可以闭合原有语义并注入任意命令。上面示例中 `f"SELECT * FROM users WHERE id = {user_id}"` 就是典型错误写法。参数化查询（prepared statement）把 SQL 语句的结构与数据分离：先用占位符（如 `?` 或 `%s`）定义语句模板，数据库预先编译执行计划，再把用户输入作为纯数据绑定进去，输入中即使含有引号或 SQL 关键字也不会被当作代码解析。主流语言和驱动都原生支持，例如 Python 的 `db.execute("SELECT * FROM users WHERE id = ?", (user_id,))`。这是 OWASP 推荐的注入防御首选方案，因此 AI 在审查中把它作为标准修复建议。
# auth.py
def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    return db.execute(query)

提交时 AI 会立即标记：

=== AI CODE REVIEW ===

[CRITICAL] SQL Injection vulnerability detected
File: auth.py, Line 42
Issue: User input directly interpolated into SQL query.
Fix: Use parameterized queries.
CWE-89: Improper Neutralization of Special Elements used in an SQL Command

[WARNING] Hardcoded secret detected
File: config.py, Line 15
Issue: API_KEY = "sk-abc123..."
Fix: Move to environment variable.

问题在生产环境之前就被拦下。这种基于 CWE 编号的引用方式，让安全工程师能快速定位漏洞类型，而不是只得到一个模糊的"不安全"提示。

已知局限

作者对工具的局限给出了坦诚说明，这一点值得肯定：

LLM 幻觉：AI 偶尔会误报。应把它当作"第二双眼睛"，而非绝对真理。
上下文窗口限制：极大的 diff 可能超出模型处理能力。
离线限制：除非使用本地 Ollama，否则需要网络连接。

这三点揭示了当前 AI 代码审查工具的共性边界——它们擅长发现模式化问题，但在需要完整项目上下文才能判断的场景中仍有不足。

后续规划

v2 路线图包括：GitHub Action 集成（自动 PR 审查）、多文件上下文理解、自定义规则引擎（定义自己的 linting 规则）。GitHub Action 集成和自定义规则引擎是社区呼声较高的方向，前者能把审查从本地延伸到 PR 流程，后者则让团队可以沉淀自己的代码规范。

项目的核心价值不在于替代人工审查，而是把最容易遗漏的安全问题和反模式拦截在提交之前，降低修复成本。对于个人开发者和希望快速引入 AI 辅助审查的团队，这是一个门槛较低的选择。