1. 为什么我要自己造一个 Mini Reviewer

1.1 从一次尴尬的线上事故说起

去年有段时间，我负责的一个 Python 服务频繁出小问题，不是那种一崩到底的大故障，而是零零碎碎的边界情况：空列表没处理、字典取值用了方括号、日志里把用户手机号原样打了出来。每次复盘都发现，这些问题在代码评审阶段其实都能被看出来，但偏偏那几周大家赶进度，评审就是走个过场，点个"同意"就合了。

后来我算了一笔账：团队里一个中等规模的仓库，每周大概有 30 到 50 个合并请求，如果每个都靠人肉仔细看，一个请求平均要花 10 到 15 分钟，一周就是 5 到 12 个小时纯评审时间。这还不算上下文切换的成本——你正写着自己的逻辑，被拉去看别人的代码，思路断了再捡回来，实际损耗远不止账面上的时间。

于是我就想，能不能做一个轻量的工具，在代码真正提交之前，先让 AI 帮我过一遍，把那些"机器一眼能看出来"的问题挡在前面，人只需要聚焦在架构、业务逻辑这些真正需要判断力的地方。这就是Mini Reviewer的由来——一个跑在本地、只审"本次准备提交的代码"的小工具，不追求大而全，只解决"提交前最后一道自动检查"这一个问题。

它适合谁？我觉得有三类人特别受用：一是独立开发者或者小团队，没有专职的代码评审流程；二是想给自己加一道保险的老手，毕竟人都会走神；三是正在学 Python、想通过 AI 反馈快速提升代码质量的新手。你不需要多深的功底，只要能跑 Python、会用 git 基本命令，就能把它搭起来。

1.2 Mini Reviewer 到底解决什么问题

先把定位说清楚，避免误解。它不是 CI/CD 流水线里的静态扫描器，也不是替代人工评审的"AI 评审员"。它的核心场景非常具体：你在本地写完代码，git add之后、git commit之前，让它看一眼这次改动的内容，给出针对性的意见。

为什么强调"本次准备提交的代码"？因为全量扫描一个几万行的仓库，既慢又吵——AI 会给你一堆跟本次改动无关的历史遗留问题，噪音太大。而只审 diff，也就是本次改动的增量部分，信息密度高，反馈精准，你改完就能立刻验证。

它主要能抓这几类问题：

• 明显的逻辑疏漏：比如循环里变量作用域搞错、异常捕获范围过宽、条件分支漏了 else。
• 安全隐患：硬编码的密钥、拼接 SQL、日志泄露敏感字段。
• 风格与可维护性：命名不一致、函数过长、重复代码块。
• Python 特有的坑：可变默认参数、is和==混用、裸except。

我实测下来，它抓"低级错误"的准确率相当高，抓"架构层面"的建议就比较一般，这符合预期——大模型擅长模式识别，不擅长理解你整个系统的设计意图。所以定位就是"提交前的自动校对"，别指望它替你做技术决策。

2. 整体设计与技术选型思路

2.1 为什么选 Python + git diff + 大模型 API

技术栈的选择其实没太多纠结，都是围绕"轻量、好改、零部署"这三个原则来的。

语言选 Python，理由很直接：git 操作有成熟的库，调用大模型 API 的 SDK 也最完善，而且团队里不管前端后端，多少都能看懂 Python 脚本，维护门槛低。你要是用 Go 或者 Node 写当然也行，但 Python 的生态在这个场景下确实最省事。

取代码用 git diff，而不是读整个文件。这里有个关键决策：审"增量"还是审"全量"。我一开始试过把整个改动文件的内容都喂给 AI，结果发现两个问题——一是 token 消耗大，二是 AI 容易被文件里已有的老代码带偏，对着历史遗留问题一顿输出。改成只取git diff --cached的内容后，反馈立刻聚焦了。--cached这个参数很关键，它取的是已经git add进暂存区、但还没提交的内容，正好对应"本次准备提交的代码"。

模型接口这块，我用的是通用的大模型对话接口，通过 HTTP 请求调用。选它的原因是接口简单、按量计费、不用自己维护模型。你也可以换成任何你手头有的模型服务，核心逻辑是一样的：把 diff 内容拼进提示词，拿到返回结果。

整个数据流是这样的：

本地改动 → git add → git diff --cached 取增量 → 拼装提示词 → 调用大模型 → 解析返回 → 终端输出评审意见

2.2 提示词设计：让 AI 说人话、说重点

工具好不好用，八成看提示词。我踩过的最大坑就是：一开始提示词写得太笼统，比如"请评审这段代码"，结果 AI 要么给你一堆泛泛而谈的夸奖，要么把每个变量名都点评一遍，全是废话。

后来我把提示词拆成了几个明确的部分，效果好了很多：

• 角色设定：告诉它你是一个严格的资深 Python 评审者，只关注本次改动。
• 输出格式：要求按"问题级别 + 行号 + 问题描述 + 修改建议"的结构输出，方便我快速扫读。
• 约束条件：明确说"如果没问题就直说没问题，不要硬凑意见"，这一条特别重要，能大幅减少噪音。
• 忽略项：告诉它不要纠结纯格式问题（那些交给格式化工具），聚焦逻辑和安全。

我用的提示词模板大致长这样，你可以直接拿去改：

SYSTEM_PROMPT = """你是一位严格的资深 Python 代码评审者。 你只评审用户提供的 git diff 增量代码，不要评论未改动的部分。 请按以下格式输出，每条问题包含： [级别] 行号 - 问题描述 - 修改建议 级别分为：严重 / 警告 / 建议。 如果本次改动没有明显问题，直接回复"本次改动未发现明显问题"。 不要纠结纯代码格式（缩进、空格），聚焦逻辑错误、安全隐患、可维护性。 """

这里有个经验：级别分类一定要有。没有级别，AI 会把"变量名不够好"和"SQL 注入风险"并列输出，你扫一眼根本分不清轻重。有了严重/警告/建议三档，我通常只看"严重"和"警告"，"建议"有空再瞄。

2.3 成本与性能的权衡

调用大模型是要花钱的，虽然单次很便宜，但天天用也得算账。我的做法是控制输入长度：diff 超过一定行数（比如 500 行）就截断或者分段，因为一次提交改几百行本身就不健康，应该拆成多个小提交。

另外，模型选择上有个取舍。能力强的模型判断准但贵、慢；轻量模型快、便宜但容易漏。我的策略是：日常提交用轻量模型快速过一遍，遇到重要模块或者大改动，手动切到强模型再仔细审一次。这个切换做成一个命令行参数就行，不用搞复杂。

实测下来，一个 100 行左右的 diff，轻量模型大概 3 到 5 秒返回，成本可以忽略不计。这个延迟完全可以接受，不会打断你的提交节奏。

3. 核心实现：从取 diff 到出报告

3.1 环境准备与依赖安装

先把地基打好。你需要的东西不多：Python 3.8 以上、git、一个能用的模型 API Key。

Python 安装这块，Windows 用户去官网下载安装包，记得勾选"Add Python to PATH"，不然命令行里敲python会提示找不到。装完在终端敲python --version验证一下。macOS 用户系统自带 Python，但版本可能偏老，建议用包管理器装个新的。

git 的安装和配置是绕不开的。Windows 下载安装包一路下一步即可，装完在终端配置一下身份：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两条命令是必须的，否则后面git commit会报错。验证 git 是否装好，敲git --version看有没有版本号输出。

然后是 Python 依赖。我建议用虚拟环境，避免污染全局：

python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate

激活后安装依赖：

pip install requests

就这一个核心依赖。requests用来发 HTTP 请求调用模型接口。如果你用官方 SDK，那就装对应的包，但用requests更通用，换任何模型服务都不用改代码结构。

提示：虚拟环境激活后，命令行前面会出现(venv)字样，看到它就说明环境对了。如果没看到，检查一下激活命令的路径对不对。

3.2 用 git diff 精准拿到本次改动

这是整个工具的核心环节，取错了内容，后面全白搭。我把它单独封装成一个函数：

import subprocess def get_staged_diff(): """获取暂存区（已 git add）的改动内容""" try: result = subprocess.run( ["git", "diff", "--cached", "--unified=3"], capture_output=True, text=True, check=True ) return result.stdout except subprocess.CalledProcessError as e: print(f"获取 diff 失败：{e}") return ""

几个参数解释一下，都是踩坑踩出来的：

• --cached：只取暂存区的改动。如果你还没git add，这里会是空的，所以用之前一定要先 add。
• --unified=3：控制上下文行数，默认就是 3 行。上下文太少 AI 看不懂改动意图，太多又浪费 token，3 行是个平衡点。
• check=True：命令失败时抛异常，方便捕获。比如你在一个非 git 目录里跑，就会走到异常分支。

这里有个新手常犯的错：直接跑git diff不带--cached，取到的是"工作区 vs 暂存区"的差异，也就是你改了但还没 add 的内容。而我们要的是"暂存区 vs 上次提交"，所以--cached不能省。

如果你想把改动拆开审，比如只想审某个文件，可以加路径参数：

git diff --cached -- path/to/file.py

3.3 拼装提示词并调用模型

拿到 diff 之后，就是拼提示词、发请求。我把这部分也封装好：

import requests API_URL = "你的模型服务接口地址" API_KEY = "你的密钥" def review_code(diff_text): if not diff_text.strip(): return "暂存区没有改动，先 git add 再试。" user_prompt = f"请评审以下 git diff 增量代码：\n\n{diff_text}" payload = { "model": "你的模型名", "messages": [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_prompt} ], "temperature": 0.2 } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } resp = requests.post(API_URL, json=payload, headers=headers, timeout=60) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"]

temperature设成 0.2 是有讲究的。这个参数控制输出的随机性，值越高越发散。代码评审要的是稳定、可复现的判断，所以调低。你要是设成 1.0，同一段代码两次评审可能给出完全不同的意见，那就没法用了。

timeout=60也别省。网络请求没有超时，遇到服务卡住会一直挂着，体验极差。60 秒对代码评审足够了，超了就说明有问题。

注意：API Key 千万别硬编码在代码里然后提交到仓库。我见过太多人把密钥写死在脚本里，一 push 上去就等于公开了。正确做法是读环境变量，或者放在.env文件里并加进.gitignore。

3.4 主流程串起来

把上面的零件组装成完整脚本：

def main(): diff = get_staged_diff() if not diff.strip(): print("暂存区为空，请先执行 git add") return print("正在评审本次改动，请稍候...\n") report = review_code(diff) print("=" * 50) print("Mini Reviewer 评审结果") print("=" * 50) print(report) if __name__ == "__main__": main()

用起来就三步：改代码、git add、跑脚本。整个流程不到十秒，比等人工评审快太多了。

如果你想更顺手，可以把它做成 git 的钩子，比如pre-commit，这样每次git commit自动触发。但我不建议一上来就上钩子，因为 AI 偶尔会误报，钩子强制拦截会让人烦躁。先用命令行手动跑一段时间，摸清它的脾气，再决定要不要自动化。

4. 实战中的问题排查与避坑经验

4.1 常见问题速查表

用了一段时间，我把遇到的问题整理成了一张表，方便你对照排查：

最后那条msvcp140.dll找不到，是 Windows 上很典型的问题，很多 Python 库依赖这个运行库。解决办法是去装一个微软官方的 Visual C++ Redistributable，装完重启终端就好。这个坑我帮好几个人解决过，跟代码本身没关系，纯粹是系统环境缺东西。

4.2 三个我踩过的坑

第一个坑：diff 太大导致模型"失忆"。有一次我一次性提交了 800 多行改动，结果 AI 的评审意见前后矛盾，前面说某个函数没问题，后面又说它有问题。原因是输入太长，模型注意力被稀释了。后来我定了个规矩：diff 超过 300 行就拆提交。这其实也是好习惯，小提交本来就更容易评审和回滚。

第二个坑：把格式化问题当逻辑问题。早期提示词没约束好，AI 老是纠结"这里应该空两格""这行太长"，全是格式噪音。后来我在提示词里明确写"不要评论纯格式问题"，世界清净了。格式的事交给 black、flake8 这些工具，各司其职。

第三个坑：过度信任 AI 的判断。有次 AI 说某段代码有"空指针风险"，我差点就改了，仔细一看那是 Python，根本没有空指针这回事，是模型把其他语言的思维带过来了。所以 AI 的意见一定要过脑子，它是助手不是裁判。尤其是涉及业务逻辑的地方，它不懂你的上下文，判断经常不准。

4.3 让评审更准的几个实操技巧

想让 Mini Reviewer 更好用，这几个技巧亲测有效：

• 提交信息写清楚：虽然 diff 里没有 commit message，但你可以在提示词里带上本次改动的意图，比如"本次改动是为了修复登录超时"，AI 有了上下文，判断会准很多。
• 分文件评审：大改动按文件拆开审，每个文件单独调用一次，反馈更聚焦。
• 建立自己的忽略清单：有些文件（比如自动生成的、测试数据）不需要审，在取 diff 时用git diff --cached -- . ':(exclude)*.json'这类路径过滤排除掉。
• 定期回顾误报：把 AI 报错但实际没问题的案例记下来，回头优化提示词。提示词是迭代出来的，不是一次写好的。

提示：如果你在团队里推广这个工具，别一上来就强制所有人用。先自己用出效果，在评审时把 AI 抓到的真实问题拿出来分享，大家看到价值自然会跟进。强推只会招来抵触。

5. 还能怎么扩展

工具跑通之后，我陆续加了些小功能，都是顺手就能做的。

一个是结果落盘。把每次评审结果追加到一个日志文件里，时间长了能看出自己常犯哪类错误，针对性改进。我发现自己早期老是忘记处理异常，看到统计后就有意识地去补。

另一个是和编辑器结合。VS Code 里可以配个任务，绑定快捷键，选中代码直接触发评审，不用切到终端。这个稍微要折腾一下配置，但用起来很爽。

再进一步，可以做成提交前自动跑的钩子，但前面说了，建议先用顺手了再自动化。还有个思路是接入代码托管平台的接口，在合并请求上自动评论，不过那就偏向团队协作了，超出了"Mini"的范畴。

我个人觉得，这个工具最大的价值不在于它多智能，而在于它把"提交前自查"这个动作变得足够便宜——便宜到你愿意每次都做。很多质量问题不是发现不了，而是没人愿意在提交前多花那十分钟。当这十分钟被压缩到十秒钟，习惯就养成了。

最后分享一个小技巧：如果你用的是轻量模型，可以在提示词里加一句"请用中文回答，简洁直接"，能明显减少啰嗦的输出。模型越轻，越需要你把要求说死，别指望它自己领会。这套东西我前后迭代了大概两个月，现在基本稳定了，日常提交前跑一下，心里踏实不少。