1. 为什么我要自己搭一套 open-code-review团队里代码评审这件事做了几年之后你会发现一个很尴尬的现实评审质量高度依赖评审人当天的状态。同一个 MR周一早上看和周五下午看给出的意见可能完全不是一个深度。更麻烦的是有些问题反复出现——命名不规范、异常没处理、日志打太多、边界条件漏判——每次都要人肉去指出来评审人累提交人也烦。open-code-review这个项目就是冲着这个痛点去的。它的核心思路很直接把代码评审里那些机械但重要的部分交给 LLM Agent 去做人只负责判断业务逻辑和架构层面的东西。整套东西跑在 CLI 里跟 Git 深度绑定提交前或者提 MR 前先跑一遍把低级问题和常见坑先过滤掉。它解决的不是替代人评审而是让人评审的时候不用再重复说废话。适合谁来用我总结下来是三类人一是小团队里没有专职代码评审角色的开发者二是想给自己代码加一道自动防线的独立开发者三是想研究 LLM Agent 怎么跟 Git 工作流结合的技术同学。哪怕你只是刚学会git commit照着本文的步骤也能把这套东西跑起来。我先把结论放前面这套方案的门槛比想象中低一台能跑命令行的机器、一个能调用的模型接口、一个 Git 仓库就能开工。真正花时间的不是搭环境而是调提示词和定规则——这部分才是决定它好不好用的关键。2. 整体设计与思路拆解2.1 为什么是 CLI 而不是插件或 Web 服务很多人第一反应是为啥不做成 IDE 插件。我一开始也这么想但实际用下来CLI 有三个绕不开的优势。第一是跟 Git 天然贴合。代码评审的输入本质上是 diff而 diff 是 Git 的原生产物。CLI 里一句git diff就能拿到变更不需要经过 IDE 的抽象层。你在终端里、在 CI 里、在 pre-commit 钩子里拿到的都是同一份 diff行为一致。第二是可组合。CLI 的输出可以管道给别的工具可以写进文件可以在脚本里判断退出码。比如评审不通过就exit 1直接卡住提交。这种能力插件很难给。第三是不绑定编辑器。团队里有人用 VS Code有人用 JetBrains有人就爱 Vim插件方案要维护多套。CLI 一套搞定谁都能用。提示如果你的团队已经在用某种 CI 平台CLI 方案可以直接塞进流水线不需要额外适配。2.2 LLM Agent 在这里扮演什么角色这里要先把几个容易混的概念理清楚因为热词里问得特别多Agent、LLM、AI 模型到底啥区别。AI 模型是最底层的比如 DeepSeek、GPT 系列、Claude 系列它们本质是输入文本、输出文本的函数。DeepSeek 就属于这一类是一个具体的大语言模型。LLM是大语言模型这个类别的统称DeepSeek、GPT 都是 LLM 的实例。Agent是在 LLM 之上加了一层决策 行动的循环。它不只是回答还会决定我要不要读这个文件我要不要跑这条命令结果不对我要不要再试一次。open-code-review里用的是 Agent 模式而不是单纯的把 diff 丢给模型让它点评。区别在哪单纯调用模型你只能得到一段文字评价Agent 模式可以让它主动去读被改动的文件的完整上下文甚至去查相关的调用方然后再给意见。这个差别在实际使用中非常大——很多问题只看 diff 是看不出来的必须结合上下文。2.3 整体架构的取舍我把这套东西拆成四层来看理解了这个分层后面配置就不容易乱层级职责常见实现采集层拿到待评审的代码变更git diff、git worktree上下文层补充变更周边的信息读文件、读历史提交推理层调用 LLM Agent 分析模型接口 提示词输出层格式化评审结果终端输出、写文件、退出码采集层我强烈建议用git worktree而不是直接在当前工作区操作。原因很简单评审过程可能会让 Agent 去读文件、切分支如果直接在开发工作区搞容易把你的未提交改动搅乱。git worktree能开一个独立的目录指向同一个仓库互不干扰。这个坑我踩过当时 Agent 读文件读到一半我切了分支结果评审结果全乱了。3. 核心细节解析与实操要点3.1 环境准备Git 和 CLI 工具链先把地基打好。Git 的安装和配置是绕不过去的热词里问得最多的也是这块。Windows 上装 Git直接去官网下安装包一路下一步就行但有两个选项要注意一是默认编辑器建议选你熟悉的别选 Vim 除非你真会用二是换行符处理选 Checkout as-is, commit as-is 最省事避免跨平台协作时满屏的换行符 diff。装完之后配置身份这是提交的前提git config --global user.name 你的名字 git config --global user.email 你的邮箱如果你用 Gitee 或者自建 Git 服务还要配 SSH 密钥ssh-keygen -t ed25519 -C 你的邮箱然后把~/.ssh/id_ed25519.pub的内容贴到平台的密钥设置里。这一步很多人卡住是因为复制的时候漏了开头或结尾或者复制成了私钥文件。公钥是.pub结尾的那个别搞错。注意git config有三个作用域——--system、--global、--local。项目里如果要用不同的身份就在项目目录下用--local单独配别全局改来改去。3.2 拿到干净的 diffworktree 的用法前面说了用git worktree隔离具体怎么操作# 在仓库根目录执行创建一个评审用的工作区 git worktree add ../review-workspace HEAD # 进入这个工作区 cd ../review-workspace这样你就有了一个干净的、指向当前提交的目录。评审 Agent 在这里面怎么折腾都不影响你的主工作区。评审完删掉git worktree remove ../review-workspace如果你要评审的是某个分支相对主干的变更可以这样git diff main...feature-branch changes.diff把 diff 存成文件再喂给 Agent。这样做的好处是可复现——同样的 diff 文件任何时候跑结果都一致方便对比不同提示词的效果。3.3 提示词设计决定成败的地方这部分是整套方案里最需要花心思的。我试过好几版提示词总结下来有几个原则。第一明确角色和边界。不要只说帮我评审代码要说清楚你是一个资深工程师只关注以下几类问题其他不要提。边界越清晰输出越聚焦。第二给出问题分类。我一般分四类正确性逻辑错误、边界条件、安全性注入、敏感信息泄露、可维护性命名、重复代码、复杂度、性能明显的低效写法。让 Agent 按类别输出方便后续处理。第三要求给出具体位置和理由。只说这里有问题没用要让它指出文件、行号、为什么有问题、建议怎么改。这样评审意见才有可操作性。一个我实际在用的提示词骨架你是一名资深代码评审工程师。请评审以下代码变更。 评审范围仅限 1. 正确性逻辑错误、边界条件、空值处理 2. 安全性输入校验、敏感信息、权限 3. 可维护性命名、重复、复杂度 4. 性能明显的低效实现 对每个问题输出 - 文件与行号 - 问题类别 - 问题描述 - 修改建议 不要评论代码风格偏好不要提与变更无关的问题。 如果某类没有问题明确说无。这个骨架的关键在于**不要评论代码风格偏好**这一句。不加这句Agent 会疯狂输出建议这里加个空行变量名可以更短之类的噪音把真正重要的问题淹没掉。3.4 模型接口的接入方式Agent 要调用模型就得有接口。常见的有两种一种是官方 SDK一种是兼容 OpenAI 格式的接口。后者通用性更好很多模型服务都支持这个格式切换模型时改动最小。配置的时候密钥千万别硬编码在代码里。用环境变量export REVIEW_API_KEY你的密钥 export REVIEW_BASE_URL接口地址 export REVIEW_MODEL模型名称然后在代码里读环境变量。这样做的好处是本地开发和 CI 环境可以用不同的密钥代码本身不用改。注意密钥泄露是高频事故。提交前一定检查.gitignore里有没有把配置文件、.env排除掉。我见过有人把密钥直接写进代码提交上去第二天就被人扫到了。4. 实操过程与核心环节实现4.1 从零跑通一次评审假设你已经装好 Git、配好密钥、准备好了模型接口下面是从零跑通的完整流程。第一步克隆或者进入你的项目git clone 你的仓库地址 cd 项目目录第二步创建评审工作区git worktree add ../review-ws HEAD cd ../review-ws第三步生成待评审的 diff。假设你要评审最近一次提交git diff HEAD~1 HEAD /tmp/review.diff第四步调用评审脚本。这里假设你已经写好了调用 Agent 的脚本python review.py --diff /tmp/review.diff --output /tmp/review-result.md第五步查看结果cat /tmp/review-result.md如果评审不通过脚本返回非零退出码你可以据此卡住后续流程。4.2 把评审接进提交钩子光手动跑还不够得让它自动跑。用 Git 的pre-push钩子最合适——提交的时候不拦推送的时候拦避免本地频繁提交被打断。在.git/hooks/pre-push里写#!/bin/bash git diff origin/main...HEAD /tmp/pre-push.diff python review.py --diff /tmp/pre-push.diff if [ $? -ne 0 ]; then echo 评审未通过请先处理问题再推送 exit 1 fi记得给钩子加执行权限chmod x .git/hooks/pre-push这样每次git push之前都会自动评审有问题直接拦住。提示钩子文件在.git/hooks里默认不会随仓库同步。团队要统一用的话得把钩子放到项目目录里再让每个人手动链接过去或者用工具管理。4.3 参数选择与成本控制模型调用是要花钱的尤其是大 diff。几个控制成本的手段限制 diff 大小。超过一定行数的 diff 直接跳过或者只评审核心文件。我一般设 2000 行上限超过就提示变更过大建议拆分。分级评审。小改动用便宜的小模型大改动或者核心模块用强模型。这个可以在脚本里根据 diff 行数自动切换。缓存结果。同一个 diff 的哈希值算出来如果之前评审过就直接读缓存不重复调用。控制手段适用场景效果限制 diff 大小大重构避免单次调用成本失控分级评审日常提交平衡质量与成本结果缓存重复评审完全省掉重复调用4.4 输出格式与团队协作评审结果如果只是终端里一堆文字团队协作时很难用。我建议输出成 Markdown方便贴到 MR 评论里。格式上我习惯按文件分组每个文件下面按问题类别列## src/user.py ### 正确性 - L42: 未处理 user 为 None 的情况建议加判空 ### 安全性 - L58: 直接拼接 SQL存在注入风险建议用参数化查询这样提交人一眼就能看到自己文件里的问题处理起来效率高。5. 常见问题与排查技巧实录5.1 环境类问题问题unable to locate the codex cli binary这类报错。这个报错的意思是系统找不到对应的 CLI 可执行文件。排查顺序先确认装没装which 命令名看能不能找到路径再看 PATH 环境变量里有没有包含安装目录最后确认安装目录下的文件有没有执行权限。Windows 上还常见一种情况——命令行里能跑但换个终端就不行这通常是 PATH 没刷新重开终端或者手动刷新环境变量即可。问题Git 命令报login failed. check api token。这是认证失败。检查密钥有没有过期、权限够不够、地址对不对。如果是自建服务还要确认版本兼容性。5.2 评审质量问题问题Agent 输出一堆无关的风格建议。回到提示词加不要评论代码风格偏好这类约束。如果还不行就在输出后加一层过滤把风格类关键词的条目删掉。问题Agent 漏掉了明显的问题。大概率是上下文不够。让它主动去读被改动文件的完整内容而不是只看 diff。可以在提示词里明确要求先读取相关文件再评审。问题同一个问题反复报。说明规则没沉淀。把确认过的问题整理成规则库评审前先跑规则库命中的直接报不用每次都靠模型判断。5.3 常见问题速查表现象可能原因处理方式找不到 CLI 可执行文件未安装或 PATH 未配置确认安装、检查 PATH认证失败密钥过期或权限不足重新生成密钥、检查权限输出噪音多提示词边界不清加约束、加过滤漏报问题上下文不足要求读取完整文件重复报同一问题规则未沉淀建立规则库调用成本高diff 过大限制大小、分级评审5.4 几个我踩过的坑坑一直接在开发工作区跑评审。前面提过Agent 读文件时你切了分支结果全乱。用git worktree隔离这个坑就没了。坑二把密钥写进代码。这个不用多说血的教训。用环境变量提交前检查.gitignore。坑三提示词一次写死。不同项目、不同语言评审重点不一样。提示词要能按项目配置别一套用到底。坑四忽略退出码。脚本跑完不看退出码评审失败了还照样推送。一定要在钩子里判断退出码。坑五评审结果不落地。只在终端看一眼就没了问题没跟踪。建议把结果写文件或者直接同步到 MR 评论里。6. 进阶玩法与扩展方向6.1 多模型对比同一份 diff用不同模型跑一遍对比结果。强模型通常更准但更贵小模型快但可能漏。我一般用强模型做最终评审小模型做初筛。这个对比过程本身也能帮你判断哪个模型更适合你的代码风格。6.2 规则库与模型结合纯靠模型判断稳定性和一致性都不够。把高频问题整理成规则库用正则或者 AST 匹配命中的直接报剩下的交给模型。这样既省钱又稳定。6.3 接入团队协作工具评审结果可以直接推到团队的协作工具里比如把 Markdown 结果发到群里或者 MR 评论。热词里提到的codex cli 接入飞书就是这个思路——CLI 负责评审协作工具负责分发。具体接入方式看你们团队用什么工具一般都有 Webhook 或者 API。6.4 历史提交的批量评审不只是评审新提交还可以对历史提交做批量评审找出遗留问题。用git log列出提交逐个生成 diff 再评审。这个适合做技术债清理但要注意控制量别一次跑几千个提交。7. 我个人的一些体会这套东西我用了大半年最大的感受是它不能替代人但能让人把精力放在真正重要的地方。以前评审一个 MR 要花半小时现在十分钟看模型报的问题二十分钟看业务逻辑效率提升很明显。另一个体会是提示词和规则库的维护比搭环境重要得多。环境搭一次就完了提示词要持续调。我现在的做法是每次发现模型漏报或者误报就回去改提示词或者加规则慢慢就越来越准。最后分享一个小技巧评审结果别只看一次。同一个 MR隔一天再看一遍模型输出经常能发现第一次没注意到的问题。因为你自己对代码的理解也在变化回头看会有新视角。这套方案还在持续迭代后面我打算加上按文件类型切换提示词、评审结果自动生成修复建议这些功能。如果你也在搞类似的东西欢迎交流。
