用AI在git提交前自动审查代码：Mini Reviewer搭建实践

代码提交前的自查很多人靠的是再扫一眼和应该没问题吧这两样东西。我干过太多次这种事本地跑通了测试也过了git push一按CI 红了一片回头一看是个变量名拼错、一个边界条件没处理、或者干脆把调试用的print带上去了。后来我想既然大模型现在读代码的能力已经够用为什么不把它接进提交链路里让它在git commit之前先帮我审一遍本次改动的 diff这就是我做 Mini Reviewer 的起点。这个工具做的事情很聚焦拿到你本次准备提交的代码变更调用 AI 做一轮结构化审查把问题按严重程度列出来让你在提交前决定是修还是忽略。它不替代 CI也不替代人工 review它解决的是提交前最后一道自检这个空档。适合有一定 Python 基础、日常用 git 管理代码、想给自己加一道自动化防线的开发者。下面我把整个搭建过程、设计取舍和踩过的坑完整讲一遍。1. 先想清楚 Mini Reviewer 到底该审什么动手写代码之前最容易犯的错是什么都想审。我第一版就是这么干的把整个仓库丢给模型让它全面审查代码质量结果返回一堆泛泛而谈的建议什么建议增加注释考虑模块化全是废话还烧了不少 token。后来我重新定义了它的职责边界工具才真正有用。1.1 只审本次 diff不审全仓库这是最核心的设计决策。全仓库审查有两个致命问题一是上下文太长模型注意力被稀释真正的问题反而被淹没二是每次提交都重复审同样的老代码纯属浪费。而本次 diff 恰好是你刚刚改动的部分是风险最集中的区域也是你最该关注的地方。获取 diff 的命令很简单git diff --cached注意这里用的是--cached也就是暂存区。为什么不是git diff因为git diff显示的是工作区和暂存区的差异而--cached显示的是暂存区和上次提交的差异也就是你这次真正要提交的内容。这个区别很关键用错了审的就不是同一批代码。1.2 审查维度要收敛到可执行的几类我把审查维度收敛成四类每类都要求模型给出具体的行号和修改建议而不是泛泛而谈正确性缺陷空指针、越界、类型不匹配、逻辑分支遗漏、异常未处理安全隐患硬编码密钥、SQL 拼接、命令注入、不安全的反序列化性能问题循环内的重复计算、N1 查询、不必要的全量拷贝可维护性命名混乱、魔法数字、重复代码、调试残留关键点在于每一类都要求模型指出具体位置 说明为什么是问题 给出修改方向。如果它给不出具体位置那这条建议就丢弃。这个约束能过滤掉绝大部分空话。1.3 输出要能直接指导行动我要求输出是结构化的每条问题包含文件路径、行号、严重等级高/中/低、问题描述、修改建议。这样我扫一眼就知道哪些必须改、哪些可以放一放。严重等级用高/中/低三档就够了分太细反而增加判断成本。提示审查维度不要贪多。我试过加到七八个维度结果模型每条都蜻蜓点水反而不如聚焦四类来得深。维度少而深比多而浅有用得多。2. 用 Python 把 git diff 和 AI 调用串起来工具的主体就是一个 Python 脚本逻辑不复杂但有几个细节处理不好就会翻车。我按数据流顺序讲先拿 diff再清洗再构造 prompt最后调模型。2.1 拿到干净的 diff 文本直接subprocess调 git 就行但要注意编码和空 diff 的处理import subprocess def get_staged_diff(): result subprocess.run( [git, diff, --cached, --unified3], capture_outputTrue, textTrue, encodingutf-8 ) if result.returncode ! 0: raise RuntimeError(fgit diff 执行失败: {result.stderr}) return result.stdout这里--unified3是控制上下文行数的默认就是 3显式写出来是为了明确意图。上下文太少模型看不懂改动意图太多又浪费 token3 行是个经过验证的平衡点。拿到 diff 后第一件事是判断它是不是空的。如果暂存区没东西直接提示用户没有待提交的改动别傻乎乎地去调模型。2.2 diff 太长怎么办分块而不是截断这是踩过坑的地方。有一次我改了一个大文件diff 有几千行直接丢给模型结果它只审了开头一部分后面的全忽略了。截断更糟等于假装审了实际没审。正确做法是按文件分块。diff 的结构天然以diff --git开头分文件可以据此切分def split_diff_by_file(diff_text): chunks [] current [] for line in diff_text.splitlines(): if line.startswith(diff --git): if current: chunks.append(\n.join(current)) current [line] else: current.append(line) if current: chunks.append(\n.join(current)) return chunks每个文件块单独送审这样既不会超上下文也不会漏审。如果单个文件的 diff 还是太长比如超过 800 行可以再按 hunk开头细分。实测下来按文件分块已经能覆盖绝大多数场景。2.3 构造 prompt 的几个讲究prompt 写得好不好直接决定审查质量。我反复调整后固定成这个结构SYSTEM_PROMPT 你是一名严格的代码审查员。你只审查用户提供的代码 diff 不要评价未出现在 diff 中的代码。对每个问题必须给出 1. 文件路径和行号 2. 严重等级高/中/低 3. 问题描述一句话说清 4. 修改建议具体到怎么改 如果某段 diff 没有问题不要强行找问题。 USER_TEMPLATE 请审查以下代码变更 {file_diff} 请按以下格式输出每条问题一行 [等级] 文件:行号 - 问题描述 | 建议修改方向 几个关键点第一明确告诉它只审 diff 里的代码否则它会去猜上下文然后瞎编第二明确说没问题就别硬找否则模型有讨好倾向会编出一些不存在的问题第三输出格式固定成一行一条方便后续解析。2.4 调用模型与结果解析调用部分用标准的 HTTP 请求即可这里不绑定具体厂商任何提供对话接口的服务都能接。核心是把 system prompt 和 user prompt 传进去拿到文本结果。解析时按行处理用正则提取等级、位置、描述import re PATTERN re.compile(r\[(高|中|低)\]\s*(.?):(\d)\s*-\s*(.?)\s*\|\s*建议(.)) def parse_findings(text): findings [] for line in text.splitlines(): m PATTERN.match(line.strip()) if m: findings.append({ level: m.group(1), file: m.group(2), line: m.group(3), issue: m.group(4), suggestion: m.group(5), }) return findings解析不出来的行直接丢弃不要试图猜模型的意思。宁可漏报不可误报因为误报会消耗你对工具的信任。3. 把它挂到 git 提交链路上工具写完了如果每次都要手动跑用不了几天就懒得用了。真正让它产生价值的是自动化——挂到 git hook 上提交时自动触发。3.1 用 pre-commit hook 拦截提交git 的pre-commithook 在git commit执行时、真正生成提交对象之前运行。如果 hook 返回非零退出码提交就会被中止。这正是我们需要的拦截点。在仓库的.git/hooks/目录下创建pre-commit文件注意没有扩展名#!/bin/sh python /path/to/mini_reviewer.py exit $?然后给它执行权限chmod x .git/hooks/pre-commit这样每次git commit都会先跑一遍审查。但这里有个体验问题如果审查发现问题就中止提交会打断你的工作流。我的做法是分级处理——只有高等级问题才中止提交中低等级只打印警告。3.2 退出码的设计退出码是 hook 和脚本之间的通信语言设计清楚很重要退出码含义对提交的影响0无问题或仅有低等级问题允许提交1存在高等级问题中止提交2脚本自身出错如网络失败中止提交并提示这里有个细节脚本自身出错时我选择中止提交而不是放行。理由是如果审查没跑成功你却以为跑了这种虚假的安全感比不审查更危险。当然如果你赶时间可以加一个--skip-review参数手动绕过。3.3 网络失败与超时的兜底调用外部服务必然会有失败的时候。我遇到过网络抖动导致请求超时结果提交被卡住很烦。后来加了超时和重试import time def call_with_retry(fn, retries2, timeout30): for i in range(retries 1): try: return fn(timeouttimeout) except TimeoutError: if i retries: raise time.sleep(2 ** i)超时设 30 秒重试 2 次指数退避。超过就报错退出让用户自己决定是重试还是跳过。不要无限重试那会让提交卡死。注意hook 里跑网络请求会让提交变慢。如果你一天提交几十次这个延迟会累积。我的建议是只在改动较大时才启用自动审查小改动比如改个文案手动跳过。4. 实测中暴露的问题和调优工具跑起来只是开始真正让它好用是在一轮轮实测中磨出来的。下面这几个问题都是我实际遇到的每个都值得单独说。4.1 误报太多会毁掉信任第一版跑下来模型报了一堆问题其中一半是误报。比如它把if x is None报成应该用把正常的日志输出报成调试残留。误报多了你就会开始无视所有报告工具就废了。我的解决办法是在 prompt 里加反例约束明确列出哪些不算问题。比如日志输出不算调试残留显式的 None 判断是推荐写法。加了这些约束后误报率明显下降。另一个办法是让模型对每个问题给出置信度只展示高置信度的。4.2 上下文缺失导致的假问题diff 只有改动部分模型看不到完整的函数上下文有时会误判。比如你删了一行模型以为你漏写了其实那行是被移到别处了。这种问题没法完全避免但可以缓解在 prompt 里附上改动所在函数的完整定义。获取函数上下文可以用git diff的-U参数加大上下文行数或者用git show拿到改动后的完整文件再截取相关函数。我选的是后者虽然多一步但准确率高不少。4.3 token 成本和速度的平衡按文件分块送审虽然准但文件多了调用次数就多成本和延迟都上去了。我的优化是小文件diff 少于 50 行合并成一批送审大文件单独送。这样既控制了单次请求的规模又减少了请求次数。另外审查结果可以缓存。如果同一个文件的 diff 哈希没变直接复用上次结果不用重复调用。这个优化在反复提交调试时特别有用。4.4 别让它变成橡皮图章最危险的情况是工具说没问题你就真的不看了。AI 审查有盲区它可能漏掉业务逻辑错误、架构层面的问题。我始终把它定位成第一道筛子而不是最终裁判。高等级问题必须人工确认中低等级可以快速扫过。这个心态摆正了工具才能真正帮到你而不是让你变懒。5. 几个让工具更顺手的扩展方向基础版跑通后我陆续加了几个小功能用起来顺手很多。这些不是必须的但如果你打算长期用值得考虑。5.1 按严重等级着色输出终端里用 ANSI 颜色码给不同等级上色高等级红色、中等级黄色、低等级灰色扫一眼就知道重点在哪。实现很简单COLORS {高: \033[91m, 中: \033[93m, 低: \033[90m} RESET \033[0m def format_finding(f): color COLORS.get(f[level], ) return f{color}[{f[level]}] {f[file]}:{f[line]} - {f[issue]}{RESET}5.2 生成审查报告存档每次审查的结果存成 Markdown 文件放在.review_history/目录下按时间戳命名。这样你可以回溯上次这个问题是不是提过也能看到自己的代码质量趋势。我坚持存了几个月发现某些类型的问题反复出现就针对性地调整了编码习惯。5.3 支持自定义规则不同项目关注点不同。比如做数据处理的脚本特别在意异常处理做 Web 服务的特别在意输入校验。我加了一个配置文件允许按项目指定重点审查的维度focus: - 异常处理 - 输入校验 ignore_patterns: - tests/ - *.md这样同一个工具在不同项目里能自动切换关注点不用每次改代码。5.4 和 CI 的配合本地 hook 是提交前的防线CI 是提交后的防线两者不冲突。我把审查脚本也接进了 CI但 CI 里只跑高等级问题检查作为合并前的最后一道关卡。本地 hook 可以跳过CI 不能跳过这样既保证了灵活性又守住了底线。6. 关于这套方案我踩过的几个真实坑最后说几个具体的坑都是我在实际使用中撞过的希望能帮你少走弯路。第一个坑是编码问题。Windows 上subprocess默认用系统编码遇到中文注释的 diff 会乱码导致模型看不懂。解决办法是显式指定encodingutf-8并且在 git 配置里设置core.quotepath false避免中文路径被转义。第二个坑是hook 里的工作目录。git hook 执行时的工作目录不一定是仓库根目录如果你脚本里用了相对路径就会找不到文件。稳妥做法是在脚本开头os.chdir到仓库根目录或者所有路径都用绝对路径。第三个坑是大文件二进制 diff。如果暂存区里有图片、编译产物这类二进制文件git diff会输出一堆乱码送给模型纯属浪费。要在分块后过滤掉二进制块判断依据是 diff 里是否包含Binary files字样。第四个坑是模型对 diff 格式的误解。diff 里的和-前缀模型有时会理解反把删除的行当成新增的。解决办法是在 prompt 里明确说明开头是新增行-开头是删除行并给一个例子。这个说明加上之后理解错误基本消失了。这套工具我从最初几十行的脚本慢慢磨到现在能稳定用前后大概花了两个周末。它没有多高深的技术核心就是把git diff 获取AI 结构化审查hook 自动触发这三件事串好再在细节上反复打磨。真正让它有价值的不是 AI 本身而是你对审什么、怎么审、审完怎么办这些问题的思考。工具是死的判断是活的把它当成一个不知疲倦的初级审查员而不是一个权威你的代码质量会实实在在地提升。