1. 为什么我要自己搭一套 open-code-review代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见把问题拦在合并之前。现实往往是另一回事提交堆成山审查者扫两眼就点了通过等到线上出问题再回头翻记录发现那个空指针早就写在 diff 里了只是没人注意到。我所在的团队规模不大七八个人后端前端加起来每天十几到二十次提交。之前试过几种方案纯人工审查靠自觉结果就是谁忙谁跳过用平台自带的审查功能规则是死的只能查格式和明显的静态问题业务逻辑层面的隐患基本查不出来也试过让每个人提交前自己过一遍清单但人总有惰性清单写着写着就变成摆设。后来我把目光转向了 LLM Agent 这条路。核心想法很直接既然大模型能读懂代码、能理解上下文那让它扮演一个永不疲倦的初级审查者角色先把明显的问题筛一遍人只需要看它筛出来的重点效率应该能提上来。这个思路落地下来就是我现在用的这套 open-code-review 流程——一个跑在本地、挂在 Git 钩子上、用 CLI 调 LLM Agent 做代码审查的小工具链。它解决的问题很具体在git commit或git push之前自动把本次改动的 diff 喂给 LLM让它按预设的审查维度输出意见有严重问题就拦住提交没大问题就放行并附上建议。适合谁来参考我觉得是三类人一是小团队里负责工程效率的那个人二是自己写项目想有个第二双眼睛的独立开发者三是对 CLI、Git 钩子、LLM Agent 这套组合感兴趣、想动手试试的技术爱好者。不需要你是 AI 专家但得会用命令行、懂基本的 Git 操作。下面我把整套东西拆开讲从设计思路到具体实现再到踩过的坑尽量说透。2. 整体设计与技术选型思路2.1 为什么是 CLI Git 钩子 LLM Agent 这个组合先说选型逻辑。做代码审查工具摆在面前的路其实有几条做成 IDE 插件、做成 CI 流水线的一环、做成独立的 CLI 工具。我最后选了 CLI 加 Git 钩子理由有三条。第一侵入性最低。IDE 插件要适配不同编辑器团队里有人用 VS Code有人用 JetBrains 系列还有人习惯 Vim统一不了。CI 流水线的问题在于反馈太晚代码都推上去了才告诉你哪里有问题改起来要走一遍完整流程。Git 钩子挂在本地提交那一刻就触发反馈最快而且不依赖任何平台配置。第二CLI 天然适合做管道。Git 本身提供了git diff、git diff --cached这类命令输出是结构化的文本直接就能喂给下一个程序。LLM Agent 的调用方式无论是走 API 还是走本地命令行工具本质上也是输入文本、输出文本。CLI 把这两端串起来中间不需要任何图形界面脚本化程度高改起来也方便。第三LLM Agent 负责理解规则引擎负责拦截。纯规则的工具查不出业务逻辑问题纯 LLM 又容易幻觉把没问题的代码说成有问题。我的做法是让 LLM 输出结构化的审查结果再用一层简单的规则判断严重程度决定是拦截还是放行。这样既利用了模型的语义理解能力又保留了确定性的控制权。提示这里说的 LLM Agent指的是能接收文本输入、按指令返回文本输出的模型调用方式。它和传统意义上的AI 模型区别在于Agent 通常带有一层任务编排逻辑比如先读 diff、再按维度分析、最后格式化输出而不是单纯的一次问答。2.2 审查维度怎么定从什么都查到只查值得查的一开始我想让模型什么都查命名规范、注释完整性、性能、安全、可读性、测试覆盖……结果输出一大堆噪音比信号还多。后来我砍到四个核心维度每个维度给明确的判断标准。审查维度关注点拦截级别逻辑正确性空指针、边界条件、死循环、资源未释放严重拦截安全隐患硬编码密钥、SQL 拼接、未校验输入严重拦截可维护性函数过长、重复代码、魔法数字建议不拦截命名与注释变量名含义不清、关键逻辑缺注释建议不拦截这个分级很关键。如果所有问题都拦截开发者会被烦死最后直接--no-verify跳过钩子工具就废了。只有真正会导致 bug 或安全问题的才拦截其余作为建议输出让人自己判断。2.3 模型调用的两种路径API 直连与本地 CLI调用 LLM 有两条路。一条是直接调 API用 HTTP 请求把 diff 发过去拿回结果。另一条是走本地已经装好的 CLI 工具比如一些命令行形式的模型客户端通过子进程调用。我两条都试过。API 直连的优点是可控超时、重试、并发都能自己管缺点是得管密钥团队里每个人都要配还得考虑费用。本地 CLI 的优点是复用已有的登录态不用额外配密钥缺点是不同人装的版本不一样输出格式可能有差异而且有些 CLI 工具在 Windows 终端下的行为不太一致。最后我选的是以 API 直连为主、本地 CLI 为备选的方案。主流程走 API配置集中管理如果检测到本地有可用的 CLI 工具也允许切换过去方便在没有网络或想省费用的场景下用。# 检查本地是否有可用的模型 CLI 工具 which codex 2/dev/null echo codex cli available which claude 2/dev/null echo claude cli available这段检测逻辑放在脚本开头根据检测结果决定走哪条路径。实测下来这种双通道设计让工具在不同环境下都能跑起来适应性好很多。3. 核心细节解析与实操要点3.1 Git 钩子的选择pre-commit 还是 pre-pushGit 钩子有好几种和代码审查相关的主要是pre-commit和pre-push。这两个的区别直接决定了工具的使用体验。pre-commit在每次提交时触发粒度细反馈快。但问题是提交往往很频繁有时候只是改个错别字也要跑一遍审查浪费时间。而且提交阶段拿到的 diff 是暂存区的内容如果开发者习惯git add .一把梭diff 会很大审查质量反而下降。pre-push在推送前触发粒度粗但更接近一次完整的改动。推送前通常已经完成了若干次提交diff 是这一批提交的合集模型能看到的上下文更完整审查意见也更有价值。我最后选的是pre-push 为主、pre-commit 可选。默认挂在 pre-push 上如果某个项目想更严格可以额外挂 pre-commit。这样既保证了审查质量又不会让日常提交变得卡顿。# 安装 pre-push 钩子 cat .git/hooks/pre-push EOF #!/bin/bash # open-code-review pre-push hook exec $(dirname $0)/../../scripts/review.sh --mode pre-push EOF chmod x .git/hooks/pre-push注意钩子脚本的路径要用相对路径或者环境变量不要写死绝对路径。团队里每个人的项目目录不一样写死了别人就用不了。3.2 diff 的提取与预处理别把整个仓库喂给模型这是最容易踩坑的地方。一开始我图省事直接git diff HEAD~1把最近一次提交的全部改动丢给模型结果 token 消耗巨大而且模型经常跑偏去评论一些和本次改动无关的旧代码。正确的做法是只提取本次推送涉及的改动。pre-push 钩子会通过标准输入传入将要推送的引用信息可以从中解析出本地分支和远程分支再用git diff拿到精确的差异。# 从 pre-push 的标准输入解析推送范围 while read local_ref local_sha remote_ref remote_sha; do if [ $remote_sha 0000000000000000000000000000000000000000 ]; then # 新分支对比默认分支 rangeorigin/main..$local_sha else range$remote_sha..$local_sha fi git diff $range -- . :(exclude)*.lock :(exclude)*.min.js done这里有两个细节值得说。一是排除锁文件和压缩文件这些文件 diff 又长又没意义喂给模型纯属浪费。二是限制单次 diff 的大小如果改动超过一定行数我设的是 800 行就只取核心文件或者提示开发者拆分提交。模型对超长输入的处理能力有限塞太多反而效果差。3.3 提示词的设计让模型输出结构化结果提示词写得好不好直接决定审查质量。我试过很多版本最后稳定下来的结构是这样的先给角色设定再给审查维度再给输出格式最后给 diff。你是一名资深代码审查者。请审查以下代码改动按四个维度分析 1. 逻辑正确性是否有空指针、边界条件错误、资源泄漏 2. 安全隐患是否有硬编码密钥、注入风险、未校验输入 3. 可维护性是否有过长函数、重复代码、魔法数字 4. 命名与注释命名是否清晰、关键逻辑是否有注释 输出格式要求 - 每个问题一行格式为[级别] 文件:行号 - 问题描述 - 级别只能是 SEVERE 或 SUGGEST - 如果没有问题输出 NO_ISSUE - 不要输出任何额外解释 代码改动如下这个提示词的关键在于输出格式的强约束。模型如果自由发挥输出会五花八门脚本没法解析。限定成[级别] 文件:行号 - 描述这种格式后用简单的文本处理就能提取出严重问题决定是否拦截。提示提示词里的不要输出任何额外解释这句很重要。模型有很强的解释欲不加这句约束它会在结果前后加一堆总的来说这段代码……之类的废话解析起来很麻烦。3.4 结果解析与拦截逻辑模型返回结果后脚本要做两件事解析出严重问题、决定是否拦截。# 解析模型输出提取 SEVERE 级别的问题 severe_count$(echo $review_result | grep -c ^\[SEVERE\]) if [ $severe_count -gt 0 ]; then echo 发现 $severe_count 个严重问题推送已拦截 echo $review_result | grep ^\[SEVERE\] exit 1 else echo 审查通过建议如下 echo $review_result | grep ^\[SUGGEST\] exit 0 fiexit 1会让 Git 中止推送exit 0则放行。这个逻辑简单但有效。实测下来拦截率控制在 5% 到 10% 之间比较合适太高说明提示词太严太低说明没起到作用。4. 完整实操流程与关键环节实现4.1 环境准备Git、CLI 工具与模型接入先把基础环境搭好。Git 的安装不用多说Windows 上装 Git for WindowsMac 上用 HomebrewLinux 用包管理器。装完之后确认git --version能正常输出。然后是模型接入。如果走 API 路径需要准备一个 API 密钥放在环境变量里不要写进代码。# 把密钥放进 shell 配置文件不要提交到仓库 echo export REVIEW_API_KEYyour-key-here ~/.bashrc echo export REVIEW_API_ENDPOINThttps://your-endpoint/v1/chat/completions ~/.bashrc source ~/.bashrc如果走本地 CLI 路径确认对应的命令行工具已经装好并且能正常调用。有些 CLI 工具在 Windows 终端下会有编码问题建议在 Git Bash 或 WSL 里跑兼容性更好。# 验证本地 CLI 工具是否可用 codex --version 2/dev/null || echo codex cli not found4.2 脚本主体从 diff 提取到结果输出整个脚本我拆成了几个函数主流程清晰一些。核心逻辑是解析推送范围、提取 diff、调用模型、解析结果、决定拦截。#!/bin/bash set -euo pipefail REVIEW_MODE${1:-pre-push} MAX_DIFF_LINES800 extract_diff() { local range$1 git diff $range -- . \ :(exclude)*.lock \ :(exclude)*.min.js \ :(exclude)package-lock.json \ | head -n $MAX_DIFF_LINES } call_model() { local diff_content$1 local prompt prompt$(cat PROMPT 你是一名资深代码审查者。请审查以下代码改动按四个维度分析 1. 逻辑正确性 2. 安全隐患 3. 可维护性 4. 命名与注释 输出格式[级别] 文件:行号 - 问题描述 级别只能是 SEVERE 或 SUGGEST无问题输出 NO_ISSUE PROMPT ) curl -s -X POST $REVIEW_API_ENDPOINT \ -H Authorization: Bearer $REVIEW_API_KEY \ -H Content-Type: application/json \ -d $(jq -n --arg p $prompt --arg d $diff_content \ {model:review-model, messages:[{role:user,content:($p \n\n $d)}]}) \ | jq -r .choices[0].message.content } main() { local diff_content diff_content$(extract_diff $REVIEW_RANGE) if [ -z $diff_content ]; then echo 无改动跳过审查 exit 0 fi local result result$(call_model $diff_content) # 解析与拦截逻辑见 3.4 节 parse_and_gate $result } main这里用到了jq来构造和解析 JSON它是处理 JSON 的利器建议提前装好。set -euo pipefail这行让脚本在出错时立即退出避免错误被吞掉。4.3 参数计算diff 行数上限怎么定MAX_DIFF_LINES这个参数不是拍脑袋定的。模型的上下文窗口有限diff 太长会被截断导致审查不完整。我按经验算了一下主流模型的上下文窗口在 8K 到 128K token 之间1 行代码平均 10 到 15 个 token加上提示词本身占用的部分留出安全余量后diff 控制在 800 行左右比较稳妥。如果改动确实很大有两个处理方式一是按文件拆分逐个文件审查二是只审查核心文件跳过测试文件和文档。我在脚本里加了个判断如果 diff 超过上限就按文件分组每组单独调用一次模型。# 按文件拆分大 diff if [ $(echo $diff_content | wc -l) -gt $MAX_DIFF_LINES ]; then git diff $range --name-only | while read -r file; do file_diff$(git diff $range -- $file) [ -n $file_diff ] call_model $file_diff done fi4.4 与 Git 工作流的整合工具做好之后要让它自然地融入日常流程。我的做法是在项目根目录放一个scripts/文件夹把审查脚本放进去然后在.git/hooks/里放一个薄薄的钩子脚本调用它。这样脚本可以跟着仓库走团队成员拉下来就能用。# 在项目里初始化钩子 mkdir -p scripts cp review.sh scripts/ cat .git/hooks/pre-push EOF #!/bin/bash exec $(git rev-parse --show-toplevel)/scripts/review.sh --mode pre-push EOF chmod x .git/hooks/pre-pushgit rev-parse --show-toplevel能拿到仓库根目录这样不管在哪个子目录下操作路径都是对的。这个细节很多人会忽略导致钩子在子目录里跑不起来。注意.git/hooks/目录不会被提交到仓库所以每个成员都要手动装一次钩子。可以在 README 里写清楚安装步骤或者写个install-hooks.sh脚本一键安装。5. 常见问题与排查技巧实录5.1 模型调用失败从超时到密钥错误模型调用是最容易出问题的环节。我把遇到过的错误整理成了一张表方便对照排查。现象可能原因排查方法请求超时网络慢或 diff 太长缩短 diff增加超时时间401 未授权密钥错误或过期检查环境变量重新生成密钥429 限流调用频率过高加退避重试降低并发返回空结果提示词或 diff 格式问题打印原始响应检查 JSON 结构输出格式不对模型没遵守格式约束强化提示词加格式示例超时这个问题我遇到最多。默认的 curl 超时是无限的模型如果卡住整个推送就挂在那里。后来我加了--max-time 60超过 60 秒就放弃提示开发者手动审查。curl -s --max-time 60 -X POST $REVIEW_API_ENDPOINT ...5.2 误报与漏报怎么调提示词误报是指模型把没问题的代码说成有问题漏报是指真正的问题没被发现。这两个是此消彼长的关系调提示词就是在找平衡点。误报多的时候我会在提示词里加一句只报告确定的问题不确定的不要报告。漏报多的时候我会在提示词里加具体的检查清单比如特别注意数组越界、空指针解引用、未关闭的文件句柄。实测下来给具体的检查项比给抽象的要求效果好得多。模型对检查是否有空指针这种具体指令的执行率明显高于检查代码质量这种模糊指令。5.3 Windows 环境下的兼容性问题Windows 下跑这套东西坑比 Linux 和 Mac 多。最常见的是路径分隔符和换行符的问题。Git Bash 里路径用/但有些工具期望\混用会出错。换行符方面Windows 用 CRLFLinux 用 LF脚本从 Windows 传到 Linux 上跑经常因为\r导致命令找不到。解决办法是在仓库根目录加一个.gitattributes文件强制脚本文件用 LF 换行。*.sh text eollf另外Windows 终端下调用某些 CLI 工具时输出编码可能是 GBK 而不是 UTF-8导致中文乱码。可以在脚本开头设置export LANGen_US.UTF-8或者chcp 65001来统一编码。5.4 钩子被绕过怎么让团队真正用起来技术上做好了不代表团队会用。我见过太多人遇到钩子拦截第一反应是git push --no-verify跳过。要让工具真正发挥作用得从两方面入手。一是降低误报率。误报是绕过钩子的头号原因。如果十次拦截里有五次是误报没人会认真对待。我花了大概两周时间调提示词把误报率压到 20% 以下团队的接受度明显提高。二是让审查结果有价值。如果模型输出的都是变量名不够清晰这种无关痛痒的建议大家看两次就不看了。我在提示词里强调只报告会导致 bug 或安全问题的情况让每条意见都值得一看。提示可以在团队里约定绕过钩子需要在提交信息里说明原因。这不是强制但是一种软约束能减少随意绕过的行为。5.5 费用控制别让审查变成烧钱机器走 API 路径的话费用是个现实问题。每次推送都调用模型一天下来调用次数不少。我的控制策略有三条。第一只在有实际改动时调用。如果 diff 为空直接跳过不浪费调用。第二限制 diff 长度。前面说的 800 行上限既是为了审查质量也是为了控制 token 消耗。第三缓存相同 diff 的结果。如果同一个 diff 被审查过直接读缓存不再调用。用 diff 的哈希值做 key存在本地文件里。cache_key$(echo $diff_content | md5sum | cut -d -f1) cache_file/tmp/review-cache/$cache_key if [ -f $cache_file ]; then result$(cat $cache_file) else result$(call_model $diff_content) echo $result $cache_file fi这三条加起来费用能降下来一大半。实测下来一个七八人的团队每月的审查费用控制在很低的水平。6. 我在这套流程里踩过的坑和攒下的经验6.1 关于提示词迭代的一点心得提示词不是一次写好的是迭代出来的。我最初的版本只有一句话审查这段代码输出质量惨不忍睹。后来每次遇到误报或漏报就针对性地加一条约束或检查项慢慢打磨出现在这个版本。我的建议是建一个提示词的版本记录每次改动都记下来改了什么、为什么改、效果如何。这样过一段时间回头看能清楚知道哪些约束是有效的哪些是多余的。我现在的提示词里有几条约束是早期加的后来发现根本没用删掉之后输出反而更干净。6.2 关于模型选择的实际体验不同模型在代码审查上的表现差异挺大。有的模型对语法细节敏感能揪出很隐蔽的空指针有的模型擅长理解业务逻辑能发现这个判断条件写反了这类问题还有的模型输出特别啰嗦每条意见都要解释半天。我的做法是按维度选模型。逻辑正确性和安全隐患这两个维度用对代码理解深的模型可维护性和命名注释这两个维度用输出简洁的模型。如果只用一个模型就选综合表现最均衡的那个。提示模型的能力在快速变化今天表现好的模型过几个月可能就被超越了。建议每隔一段时间重新评估一次不要一套配置用到底。6.3 关于团队协作的观察工具上线之后我观察到一个有意思的现象审查意见的质量比数量重要得多。一开始模型输出一大堆建议大家看都不看。后来我把建议精简到每次不超过五条而且每条都标注了具体文件和行号大家的阅读率明显提高。另一个观察是开发者对被拦截的容忍度取决于拦截的准确性。如果拦截的都是真问题大家会认可这个工具如果拦截里有误报信任度会迅速下降。所以宁可漏报不要误报这是我在调提示词时一直坚持的原则。6.4 后续可以扩展的方向这套流程目前跑得挺稳但还有几个方向可以继续做。一是把审查结果沉淀下来存到数据库里定期分析哪些类型的问题出现最多反过来指导编码规范。二是支持自定义审查规则让每个项目可以配置自己的检查项比如某个项目特别在意性能就加一条性能检查。三是和 CI 流水线打通本地审查通过之后CI 上再跑一遍双重保险。这些扩展我还在陆续做有进展了再单独写一篇分享。代码审查这件事工具能帮上忙但最终还是要靠人。工具的价值在于把人的注意力从找明显问题转移到判断复杂逻辑上这才是它真正省时间的地方。