用AI打造本地Git提交前代码审查工具：Mini Reviewer实战

1. 为什么我要自己造一个 Mini Reviewer每次提交代码前心里总有点不踏实。不是担心逻辑跑不通而是怕漏掉一些“低级但致命”的问题比如某个函数忘了处理空值、某个接口的异常分支没覆盖、某个变量名拼错了导致后续维护的人一脸懵。团队里如果有代码审查环节还好但现实往往是——要么没人审要么审的人比你还忙最后只能自己硬着头皮提交然后祈祷线上不出事。我试过不少现成的代码审查工具有商业的也有开源的但总感觉“太重了”。要么需要配置一堆规则文件要么得把代码传到别人的服务器上要么就是报告里塞满了无关紧要的格式警告真正想让它盯住的业务逻辑漏洞反而漏掉了。更关键的是这些工具大多是在代码提交之后才跑等报告出来的时候代码可能已经合并了。所以我就想能不能做一个轻量的、跑在本地、只针对“本次准备提交的代码”做审查的小工具它不需要理解整个项目的架构也不需要知道历史提交记录只需要盯着git diff里那些新增和修改的行用 AI 的能力去判断这段代码有没有明显的逻辑问题、安全隐患、或者可读性上的硬伤。这就是 Mini Reviewer 的由来。这个工具适合谁呢如果你是一个经常自己写代码、偶尔需要独立提交的开发者或者你所在的团队代码审查流程比较松散想给自己加一道“提交前自检”的防线那这套思路和实现方式应该能帮到你。它不追求大而全只追求“在提交前那几分钟里帮你多看一眼”。2. 整体设计思路与核心选型2.1 为什么是“本次准备提交的代码”而不是全量扫描全量扫描听起来很美好但实际上对于个人开发者或者小团队来说成本太高。一个中等规模的项目全量扫描一次可能要几分钟甚至更久而且大部分代码是历史遗留的、已经稳定运行的扫出来的问题你也不会去改。真正需要关注的是这次改动引入的新代码。git diff天然就是干这个的。它只显示工作区和暂存区之间的差异或者暂存区和最后一次提交之间的差异。我们只需要解析这个差异提取出新增和修改的行再结合上下文就能让 AI 聚焦在“这次改了什么”上。这样做的好处是审查速度快、噪音少、针对性强。2.2 为什么选 Python 而不是其他语言Python 在这个场景里有几个天然优势。第一git命令的调用和输出解析用 Python 的subprocess模块非常顺手标准库就能搞定不需要额外依赖。第二调用 AI 接口的 SDK 生态成熟无论是 OpenAI 风格的接口还是其他兼容接口Python 的requests库或者官方 SDK 都能几行代码搞定。第三脚本本身不需要编译改完就能跑适合这种“随手工具”的定位。如果你习惯用 Node.js 或者 Go逻辑是一样的只是解析git diff和发 HTTP 请求的写法不同。我这里用 Python 来演示是因为它最贴近“快速做一个能用的东西”这个目标。2.3 为什么用 AI 而不是静态规则静态规则引擎比如正则匹配、AST 分析能发现的问题很有限。比如“变量名不符合驼峰命名”这种规则写起来容易但误报率也高。而 AI 的优势在于它能理解代码的“意图”。比如下面这段代码def get_user(user_id): user db.query(fSELECT * FROM users WHERE id {user_id}) return user静态规则可能只会检查有没有用参数化查询但 AI 能看出来这里存在 SQL 注入风险而且能给出具体的修改建议。再比如AI 能判断一个异常捕获块是不是“吞掉了异常”而静态规则很难定义什么叫“吞掉”。当然AI 也不是万能的。它可能会产生幻觉或者对某些业务逻辑理解不到位。所以 Mini Reviewer 的定位是“辅助审查”而不是“替代人工”。它的价值在于帮你发现那些你写代码时因为惯性而忽略的问题。2.4 整体流程拆解整个工具的运行流程可以拆成四步获取差异调用git diff --cached拿到暂存区的改动如果没有暂存内容就退回到git diff拿工作区的改动。解析差异从 diff 文本里提取出文件路径、新增行号、新增内容以及每个改动块前后的上下文。构造提示词把解析出来的代码片段和审查要求组装成一段给 AI 的提示词。调用 AI 并输出报告把提示词发给 AI拿到返回结果格式化后打印到终端。这四步里最需要仔细处理的是第二步和第三步。diff 的格式虽然规整但边界情况不少比如二进制文件、重命名文件、删除文件等都需要做过滤。提示词的设计则直接决定了 AI 审查的质量。3. 核心细节解析与实操要点3.1 git diff 的输出格式与解析策略git diff的输出是统一的 diff 格式每个文件以diff --git a/xxx b/xxx开头后面跟着index行、---和行然后是若干个开头的块头每个块里包含上下文行以空格开头、新增行以开头和删除行以-开头。解析的时候我只需要关注新增行和它们所在的文件路径。但光有新增行还不够因为 AI 需要上下文才能判断这段代码的意图。所以每个块里的上下文行也要保留只是标记出来哪些是新增的。一个典型的 diff 块长这样 -10,6 10,8 def process_data(data): result [] for item in data: if item is None: continue result.append(item.transform()) return result这里 -10,6 10,8 表示旧文件从第 10 行开始有 6 行新文件从第 10 行开始有 8 行。后面的def process_data(data):是块头附带的函数上下文方便定位。解析的时候我用一个状态机来逐行读取遇到diff --git就新建一个文件对象遇到就新建一个块对象遇到开头且不是的行就记录为新增行遇到空格开头的行就记录为上下文行。删除行直接忽略因为审查的是“将要提交的代码”删除的内容不需要 AI 去评价。注意git diff的输出里 b/xxx这一行也以开头但它是文件头不是新增代码。解析时必须排除掉以和---开头的行否则会把文件路径当成代码送给 AI。3.2 提示词的设计让 AI 说人话、抓重点提示词的质量直接决定了审查结果的质量。我试过几种不同的写法最后稳定下来的版本包含以下几个部分角色设定告诉 AI 它是一个经验丰富的代码审查者关注逻辑正确性、安全性、可读性和边界条件。审查范围明确只审查新增和修改的代码不要对未改动的代码发表意见。输出格式要求按文件分组每个问题标注严重程度高/中/低并给出具体的行号和修改建议。约束条件如果某段代码没有问题不要强行找问题如果问题不确定标注为“疑似”而不是断言。一个实际使用的提示词片段是这样的你是一个资深代码审查者。请审查以下代码改动重点关注 1. 逻辑错误条件判断是否完整、循环边界是否正确、异常处理是否合理。 2. 安全隐患SQL 注入、命令注入、路径穿越、敏感信息硬编码。 3. 可读性问题命名是否清晰、函数是否过长、注释是否缺失。 4. 边界条件空值、空列表、超大输入、并发场景。 对于每个问题请给出 - 文件名和行号 - 问题描述 - 严重程度高/中/低 - 修改建议 如果某段代码没有问题不需要强行找问题。如果问题不确定标注为“疑似”。这个提示词的关键在于“如果某段代码没有问题不需要强行找问题”。如果不加这一句AI 会倾向于在每个文件里都找出点毛病来哪怕只是一些无关痛痒的风格问题。加上之后报告里的噪音明显减少。3.3 上下文窗口的控制只送必要的代码AI 的上下文窗口是有限的而且送得越多费用越高、速度越慢。所以不能把整个 diff 一股脑全塞进去。我的做法是每个块只保留块头前后各 3 行上下文加上新增行本身。如果某个文件的新增行超过 200 行就拆成多个请求分批发送。另外有些文件类型根本不需要审查比如.md、.txt、.json、.lock文件以及图片、二进制文件。这些在解析阶段就直接过滤掉不进入 AI 审查环节。还有一个细节如果 diff 里某个文件的新增行全是空行或者注释也可以跳过。AI 对纯注释的审查价值不大除非注释里包含了明显的错误信息。3.4 调用 AI 接口的工程细节调用 AI 接口看起来简单但有几个坑需要注意。第一是超时设置。代码审查的请求可能比较长尤其是当 diff 内容较多时AI 生成回复的时间可能超过默认的超时时间。我一般把超时设成 60 秒并且加上重试机制最多重试 2 次。第二是错误处理。如果接口返回 429请求过多或者 500服务器错误不能直接崩溃而是要捕获异常并给出友好的提示。如果连续失败就跳过当前文件继续审查下一个。第三是结果解析。AI 返回的文本格式可能不完全符合预期比如有时候会多出一些 Markdown 标记有时候会把多个问题写在一段里。我的做法是先用正则提取出“文件名:行号”的模式再按严重程度排序输出。如果解析失败就把原始返回内容直接打印出来让用户自己看。实操心得不要把 API Key 硬编码在脚本里。我习惯用环境变量MINI_REVIEWER_API_KEY来传递脚本里用os.environ.get()读取。这样既安全也方便在不同机器上切换。4. 完整实操流程与核心环节实现4.1 环境准备与依赖安装这个工具只依赖 Python 标准库和requests库。如果你用的是 Python 3.8 以上版本标准库里的subprocess、re、os、sys、json都够用了。requests用来发 HTTP 请求安装命令很简单pip install requests如果你还没有配置 Python 环境建议直接去 Python 官网下载最新稳定版安装时勾选“Add Python to PATH”。安装完成后在终端里运行python --version确认版本。Git 的安装和配置这里就不展开了网上教程很多核心是确保git命令在终端里能直接调用。4.2 获取 diff 的代码实现获取 diff 的函数需要处理两种情况优先读暂存区如果暂存区为空则读工作区。代码大致如下import subprocess def get_diff(): # 先尝试暂存区 result subprocess.run( [git, diff, --cached, --unified3], capture_outputTrue, textTrue ) if result.stdout.strip(): return result.stdout # 暂存区为空读工作区 result subprocess.run( [git, diff, --unified3], capture_outputTrue, textTrue ) return result.stdout--unified3表示每个改动块保留前后各 3 行上下文这个数值可以根据需要调整。如果项目里函数普遍比较长可以改成--unified5但上下文越多送给 AI 的 token 也越多。如果git diff返回空字符串说明没有改动直接提示用户“没有检测到代码改动”并退出。4.3 解析 diff 并提取新增代码解析部分我用一个简单的状态机来实现。核心逻辑是遍历每一行根据行的前缀判断当前处于什么状态import re def parse_diff(diff_text): files [] current_file None current_hunk None for line in diff_text.splitlines(): if line.startswith(diff --git): # 新文件开始 match re.search(rb/(.)$, line) if match: current_file {path: match.group(1), hunks: []} files.append(current_file) elif line.startswith(): # 新块开始 if current_file is not None: current_hunk {header: line, lines: []} current_file[hunks].append(current_hunk) elif current_hunk is not None: if line.startswith() and not line.startswith(): current_hunk[lines].append({type: add, content: line[1:]}) elif line.startswith( ): current_hunk[lines].append({type: context, content: line[1:]}) # 删除行忽略 return files解析完成后每个文件对象里包含了若干个块每个块里有新增行和上下文行。接下来要过滤掉不需要审查的文件类型SKIP_EXTENSIONS {.md, .txt, .json, .lock, .png, .jpg, .svg} def filter_files(files): return [f for f in files if not any(f[path].endswith(ext) for ext in SKIP_EXTENSIONS)]4.4 构造提示词并调用 AI构造提示词的时候我把每个文件的新增代码和上下文拼成一段文本加上文件路径和行号信息。为了控制长度每个块只保留新增行和前后各 3 行上下文。def build_prompt(files): prompt_parts [] for f in files: for hunk in f[hunks]: lines [] for item in hunk[lines]: prefix if item[type] add else lines.append(prefix item[content]) if any(item[type] add for item in hunk[lines]): prompt_parts.append(f文件: {f[path]}\n \n.join(lines)) return \n\n.join(prompt_parts)然后把这个 prompt 和前面说的审查要求拼在一起发给 AI 接口。调用部分用requests实现import requests import os def call_ai(prompt): api_key os.environ.get(MINI_REVIEWER_API_KEY) if not api_key: raise ValueError(请设置环境变量 MINI_REVIEWER_API_KEY) headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [ {role: system, content: 你是一个资深代码审查者。}, {role: user, content: prompt} ], temperature: 0.2 } resp requests.post( https://api.openai.com/v1/chat/completions, headersheaders, jsonpayload, timeout60 ) resp.raise_for_status() return resp.json()[choices][0][message][content]temperature设成 0.2 是为了让输出更稳定减少随机发挥。模型选择上gpt-4o-mini在代码审查场景下性价比不错如果对质量要求更高可以换成更大的模型。4.5 输出报告与格式化AI 返回的文本可能比较长直接打印会显得杂乱。我写了一个简单的格式化函数按文件分组每个问题用分隔线隔开def print_report(report): print( * 60) print(Mini Reviewer 审查报告) print( * 60) print(report) print( * 60)如果 AI 返回的内容里包含了 Markdown 格式终端可能显示得不太好看。可以在输出前做一次简单的清理去掉多余的**和###标记或者直接用rich库来渲染。不过为了保持脚本轻量我一般就用纯文本输出够用了。4.6 完整脚本的组装与运行把上面的函数串起来主流程就是def main(): diff_text get_diff() if not diff_text.strip(): print(没有检测到代码改动。) return files parse_diff(diff_text) files filter_files(files) if not files: print(没有需要审查的代码文件。) return prompt build_prompt(files) report call_ai(prompt) print_report(report) if __name__ __main__: main()运行的时候先在终端里git add你想审查的文件然后执行python mini_reviewer.py。脚本会自动读取暂存区的 diff调用 AI然后把审查结果打印出来。如果你只想审查工作区的改动而不想暂存直接运行脚本就行它会自动回退到git diff。实操心得我习惯在git commit之前跑一次这个脚本。如果报告里有“高”严重程度的问题就先修掉再提交。如果只有“低”级别的问题可以视情况忽略。这样既不会拖慢提交节奏又能挡住大部分明显的问题。5. 常见问题与排查技巧实录5.1 AI 返回的结果不准确怎么办AI 审查代码时偶尔会出现“误报”或者“幻觉”。比如它可能把一段正常的代码判断为有 SQL 注入风险或者建议你修改一个其实没问题的变量名。遇到这种情况先不要急着否定 AI而是仔细看看它的理由。有时候它的判断确实有道理只是你之前没意识到有时候它确实理解错了上下文。如果误报率太高可以调整提示词加上“只报告确定的问题不确定的标注为疑似”这样的约束。另外把temperature调低也能减少随机性。如果某个文件反复出现误报可以在脚本里加一个忽略列表把该文件排除在审查范围之外。5.2 diff 内容太长导致请求超时当一次提交涉及大量文件时diff 可能会非常长导致 AI 接口超时。解决办法有两个一是分批发送把文件按数量或按行数拆成多个请求二是限制每个文件的审查行数比如只审查新增行数最多的前 5 个文件。我一般用分批发送的方式每批最多 3 个文件每批之间间隔 1 秒避免触发接口的速率限制。如果某个文件特别大就单独发一批。5.3 如何处理二进制文件和重命名文件二进制文件在 diff 里通常只显示Binary files a/xxx and b/xxx differ没有具体的代码行。解析的时候直接跳过就行。重命名文件在 diff 里会显示rename from和rename to如果内容没有改动也不需要进行审查。如果重命名同时伴随内容修改diff 里会正常显示改动块按普通文件处理即可。5.4 常见问题速查表问题现象可能原因解决方法脚本报错“没有检测到代码改动”暂存区和工作区都没有改动先修改代码或执行git addAI 返回结果为空接口调用失败或超时检查 API Key 和网络增加重试报告里全是格式问题提示词没有约束审查范围在提示词里明确只关注逻辑和安全某个文件被反复误报AI 对该文件的理解有偏差把该文件加入忽略列表请求返回 429 错误调用频率过高增加请求间隔减少每批文件数5.5 几个我踩过的坑第一个坑是git diff的输出编码问题。在某些终端环境下diff 里的中文注释可能会显示为乱码。解决办法是在subprocess.run里指定encodingutf-8并且确保终端本身也支持 UTF-8。第二个坑是 AI 返回的内容里包含了 Markdown 代码块标记比如python 和直接打印出来会很难看。我在格式化函数里加了一个简单的正则替换把这些标记去掉。第三个坑是环境变量没设置导致脚本崩溃。后来我在脚本开头加了一个检查如果MINI_REVIEWER_API_KEY不存在就打印一条友好的提示告诉用户怎么设置而不是直接抛异常。第四个坑是 diff 里的行号信息不准确。块头里的行号是旧文件和新文件的行号但 AI 在报告里引用的行号可能和实际文件对不上。我的做法是在提示词里明确告诉 AI“行号以新增代码在文件中的实际行号为准”并且在解析时把新文件的行号计算出来附在每行前面。6. 后续可以扩展的方向这个 Mini Reviewer 目前只做了最核心的功能读 diff、调 AI、出报告。如果你用着觉得顺手可以考虑几个扩展方向。第一个是加一个配置文件让用户可以自定义审查规则。比如某些项目不允许使用eval()某些项目要求所有函数必须有类型注解。这些规则可以写在配置文件里脚本读取后拼接到提示词中。第二个是集成到 Git 钩子里。在.git/hooks/pre-commit里调用这个脚本如果审查发现“高”严重程度的问题就阻止提交。这样就不用每次手动跑了。第三个是支持多种 AI 接口。目前只写了 OpenAI 风格的接口实际上很多其他服务也兼容这个格式只需要改一下base_url和模型名称就行。如果用的是本地部署的模型也可以把接口地址指向本地服务。第四个是增加缓存机制。如果某个文件的 diff 内容和上次审查时一样就直接用缓存的结果不用重复调用 AI。这样可以节省费用和时间。这些扩展都不复杂核心逻辑已经跑通了剩下的就是按需添加。我自己的做法是先把核心功能用起来遇到不方便的地方再逐步改进而不是一开始就追求大而全。毕竟工具是拿来用的不是拿来炫的。