★ FEATURED ARTICLE 做代码评审这件事我一开始是有点抗拒AI介入的。原因很简单一个不懂业务上下文、没见过团队历史的模型凭什么对一个改了三行代码的PR指手画脚后来我被现实教育了——团队规模变大之后人工评审根本忙不过来低级问题空指针、资源未关闭、魔法数遍地经常漏到主分支上等出了问题大家再来复盘成本高得离谱。于是我开始认真研究AI辅助代码评审的方向最终做了一个开源的、可以完全自托管的评审工具取名叫open-code-review。它不依赖某个固定云平台不做黑盒的评审规则而是把采集Diff、构建上下文、调用LLM、输出报告这条链路完全开放出来让每个团队都能用自己手里的模型和规则搭建一套真正贴合自身业务的代码评审助手。这套东西适合谁如果你的团队还在用纯人工评审、每次MR要攒三天才有人看或者你试过商业的AI评审服务但担心代码数据出网、费用又不好控制再或者你只是想搞明白LLM到底能不能当代码评审员那这个项目都值得花半小时了解一下。下面我会把整个项目的设计思路、核心模块、部署步骤和踩坑经验全部摊开讲文章偏工程实践建议配合源码一起看。1. 项目定位与核心设计思路1.1 为什么非要做成“open”而不是直接买个服务市面上做AI代码评审的产品已经有不少很多确实能用但它们有个共同的问题评审逻辑是封闭的。你只知道模型给出了这里有风险的结论却不知道这个结论是怎么来的也不能修改它的评审标准。有的服务会把你的代码片段发送到云端做推理这对很多金融、医疗类项目来说直接就是红线。再加上按Seat或按请求数计费团队一大人均评审量一上去账单非常难看。open-code-review在定位上有意避开这些坑。项目的open体现在三个层面 一是源码开放整个采集、分析、报告生成链路都可以读、可以改 二是接入开放LLM部分只依赖标准的OpenAI兼容API协议也就意味着你可以接任意一家商业API也可以接本地的vLLM、Ollama、各种开源模型服务不会被锁死 三是规则开放评审关注点、严重级别、是否忽略某个目录全部通过配置文件控制团队可以把代码规范直接沉淀成评审规则让AI严格按照团队自己的尺子去量。换句话说这不是一个零成本的AI评委而是一个评委中控台模型只是执行机构规则和流程都攥在自己手里。1.2 项目整体架构与技术选型整个项目我按管线的方式拆成四层变更采集层、上下文构建层、规则解析与LLM调用层、报告输出与通知层。代码主体用Python写的原因有两点一是Python的异步生态比较成熟处理Git命令、HTTP并发请求都很顺手二是后续如果要集成AST分析、代码结构解析这类重型任务Python的库支撑是最全的。变更采集的核心逻辑很简单用Git命令拿到本次合并请求的Base SHA和Head SHA然后执行git diff生成变更内容。这里要处理的坑比想象中多比如仓库很庞大时git diff的输出可能有几万行直接全部扔给LLM既不经济也不现实再比如二进制文件、生成的锁文件、打包产物这类变更必须主动过滤否则会污染评审结果。所以采集层还会带一个文件白名单/黑名单机制只把真正需要评审的源码文件送进后续流程。上下文构建层是这个项目里最花心思的部分。大模型的API是纯文本进出的给它一个光秃秃的diff它连那个函数是哪个类的成员都看不出来评审意见一定会跑偏。我后面会详细介绍怎么用AST去提取相关的符号定义把这段代码周边是什么样的一并拼进Prompt。LLM调用层就更直接了我只维护一个统一的Chat Completions接口封装模型名、Base URL、温度、最大Token数、超时时间全部做成配置项。这样做的好处非常明显——今天用GPT-4o做评审明天想换成更便宜的本地Qwen模型只需要改配置文件代码一行都不用动。1.3 三类评审方式的定位差异先列个表格对比一下这样大家对AI评审到底该放在哪个位置心里有数。评审方式擅长点薄弱点适合场景传统静态扫描ESLint/SonarQube等规则明确、误报率低、执行快只能查模式理解不了业务意图提交前拦截格式、空值、安全API误用等机械问题人工代码评审理解业务背景、能讨论设计取舍时间成本高、评审质量依赖个人经验、容易拖延核心模块、重大架构变更、新人代码指导LLM辅助评审open-code-review能理解上下文、能发现逻辑漏洞和并发隐患、响应快、成本低偶尔会幻觉、对业务语义理解有限、需要规则约束日常MR/PR的“第二双眼睛”兜底人工遗漏对比下来就很清楚了AI评审不是来替代人工的而是把人工从低级但必须看的泥潭里捞出来。团队里最值钱的老师傅不该把时间花在找哪里忘了判空这种事儿上AI把这些活儿揽下来之后人工只需要把精力放在AI拿不准的设计和业务合理性讨论上。2. 核心模块拆解与关键参数设计2.1 变更采集只评审“这次改动带来的风险”变更采集做得不好后面全是垃圾进垃圾出。我在实现里首先定义了一个标准流程拿到PR/MR的合并目标分支比如main的最新提交作为Base拿到当前评审分支的HEAD作为比较点然后调用git diff base...head。三段式diff在这里比两段式更准因为它只追踪这个分支上新发生的变更不会把目标分支上其他人提交的内容搅进来。Diff拿到手之后要做三件事 第一剔除噪音文件。我在默认配置里放了一批全局忽略正则比如package-lock.json、yarn.lock、*.min.js、*.pb.go这类自动生成文件这些文件就算有变更也不应该出现在评审结果里。 第二统计变更规模。这里有个关键的兜底参数max_diff_lines默认是1500行。一旦整个PR的变更行数超过这个阈值我不会把全部内容塞给模型而是按文件维度分片每片单独走一轮评审最后再汇总。分片还有分层的考虑一个文件超过300行的独立diff干脆直接丢进仅做文件级总览的模式不再逐行细评因为细评长文件不仅费Token模型还会在长上下文里丢失前面的信息越往后越敷衍。 第三生成结构化的变更条目。每条变更记录包含文件路径、变更类型新增/修改/删除、改动行号区间、diff内容块。这一步的产物会直接给上下文构建层消费所以字段设计得像DTO一样规整这才好做后续扩展。一个很现实的注意点git diff对中文注释、仓库存放在Windows上的路径分隔符处理各有不同Git必须设置core.quotepathfalse否则中文路径会被转义成八进制串模型看到的路径直接就是乱码评审结果定位不了文件后面全白干。2.2 上下文增强让模型看懂“这段代码在干嘛”这一步是整个项目里最能拉开差距的地方。一开始我直接拿纯Diff让GPT做评审出来的意见十有八九都浮在表面比如这个函数有点长建议拆分完全没有参考价值。后来我想明白了一个刚被从别的文件拷过来的函数模型只能看到它的骨架看不到它周围的接口、类、依赖关系自然没法判断改动是否合理。解决思路是做一个结构化上下文打包器。它做这几件事先用语言相关的解析库Python用tree-sitterJava和Go也有对应的tree-sitter语法包解析涉及变更的文件生成语法树然后根据Diff里的变更行号回溯出这些改动命中了哪些函数、方法、类定义和关键语句块再把这些抽象语法树节点的签名、所属类名、函数名、参数列表、对外调用关系一起提取出来最后把局部字段所属类结构相关函数的Docstring/注释拼成一段上下文文本。打个比方这就像你给一个医生看病人的化验单不能只给他看指标异常的那一行得把病人基础信息、历史病历、最近用药情况一起递过去诊断才有依据。上下文文本生成之后会和Diff本身按特定模板拼进Prompt【文件变更内容】 {file_diff} 【所属模块的上下文】 {context_snippet} 【变更影响的行范围和函数范围】 {scope_info}上下文不是越多越好。我把单文件的上下文Token预算控制在1000~2000之间超过就按优先级截断优先保留函数签名、类定义、关键注释丢掉大段实现。如果某个文件的变更牵涉到其他文件里的公共函数我会再去目标文件里提取那个函数的签名和Docstring一并带上。这一步对硬件要求几乎为零纯CPU操作一次PR大概增加1到3秒处理时间但效果提升非常明显。2.3 评审规则引擎AI只是执行者规则才是灵魂很多团队用AI评审工具觉得鸡肋问题往往出在没有规则约束上——模型在漫无目的地自由发挥。open-code-review的设计是完全相反的模型只负责执行规则规则定义清楚了模型的自由空间就压缩了。规则配置是一个YAML文件你可以在里面定义这一次评审要关注什么、不关注什么、什么级别算严重。我默认内置了一套规则集覆盖常见的六类问题规则标签说明严重级别示例security注入、硬编码密钥、路径穿越、不安全反序列化critical / highperformance循环内查库、N1查询、大对象拷贝、锁粒度不合理high / mediumreliability空指针、资源未关闭、异常被吞掉、并发竞争high / mediummaintainability魔法数、重复代码、函数过长、命名混乱medium / lowcorrectness边界条件、逻辑判断反了、浮点比较等highstyle格式、缩进、import顺序等low每条规则有两个核心属性enable和severity。默认全开但团队可以按需关闭。之前有家公司用得比较痛苦因为他们历史代码里全是魔法数AI每次评审都刷屏报maintainability开发根本看不过来后来他们把maintainability类规则关掉只保留security和reliability反馈立刻舒服多了。这就是规则可配置的价值——不用推翻整个工具拧一下开关就行。规则引擎在技术实现上其实不复杂把配置解析成一个个评审指令和用户的自定义评审清单一起拼进Prompt同时控制返回格式必须按JSON结构输出每条问题带file、line_start、line_end、severity、rule_id、message、suggestion字段。输出必须是严格的JSON这能极大减少解析和定位成本。后面的报告生成器再按rule_id分组、按severity排序渲染成可读的报告。2.4 LLM接入层兼容任何模型不被任何厂商绑定LLM接入层在设计上遵循一个原则绝不和某个模型深度耦合。我用的是OpenAI的Chat Completions协议因为这套协议已经成了事实上的行业标准无论国内外厂商几乎都提供兼容接口。关键参数我全部外置成了环境变量或配置文件这里给出我的默认建议值参数建议值理由model视预算和场景而定线上小PR用便宜快速模型复杂PR切深度模型temperature0.1 ~ 0.3温度越高越有创造性评审这种活需要确定性低了更稳定max_tokens每片1500 ~ 3000控制单次费用防止模型长篇大论生成废话timeout60秒模型服务偶发变慢超时直接跳过不能卡死整个流水线max_concurrency3 ~ 5并发太高容易触发限流并发太低评审慢我们内部实测并发4最平衡enable_stream否评审要用完整JSON不搞流式减少半截输出带来的解析问题关于成本控制有个很重要的思路不是每个PR都要用同一档模型。我在触发器里加了一个智能分级——按变更行数、涉及文件数、是否触碰核心目录三档决策小型PR调一个便宜快模型比如轻量级模型或量化版本地模型大型PR调一个深度推理模型。实测这样组合一个月API账单能比无脑用大模型直接降60%以上。后面我会在成本控制那一节再展开讲。对于本地模型我推荐用vLLM或Ollama起一个OpenAI兼容服务模型优先挑代码能力好的中小心尺寸版本比如Qwen系列或DeepSeek系列。本地部署要特别留意单次请求的上下文长度限制比如某些模型是32K上下文你以为够用结果单文件Diff加上上下文文本一拼就爆了所以我在配置里做了一层保护达到上下文上限前强制截断最前面的文件内容保证不报错。3. 实操过程与核心环节实现3.1 从零搭一个可用的评审服务先交代一下环境我建议你准备一台Linux或者macOS机器装好Python 3.10以上版本、Git再加一个能访问的LLM服务商业API或本地模型都行。项目目录结构设计如下open-code-review/ ├── config/ │ ├── review_rules.yaml # 评审规则配置 │ ├── ignore_patterns.yaml # 文件忽略配置 │ └── prompts/ │ └── review_system.tmpl # 系统Prompt模板 ├── src/ │ ├── collector/ # 变更采集模块 │ ├── context/ # 上下文构建模块 │ ├── llm/ # LLM接入与调用模块 │ ├── reporter/ # 报告生成与通知模块 │ └── main.py # 入口文件 ├── tests/ ├── requirements.txt └── README.md安装依赖只需要一行命令pip install -r requirements.txtrequirements.txt里就几个关键依赖gitpython用来和Git仓库交互、pyyaml用来解析规则配置、httpx用来做异步HTTP调用、tree-sitter和对应的语言包用来做AST解析。3.2 写一份“靠谱”的评审规则配置这里我给出一份可以直接抄作业的review_rules.yaml里面的数值都经过实际调优新项目可以直接跑# 评审范围控制 scope: # 检查以下扩展名的文件 extensions: [.py, .go, .java, .js, .ts] # 忽略以下路径 ignore_paths: - vendor/ - node_modules/ - dist/ - build/ - *.pb.go - *.min.js # 变更规模控制 diff_limits: # 全局diff超过该行数则分片评审 max_diff_lines: 1500 # 单文件diff超过该行数则仅做文件级总览 max_file_diff_lines: 300 # 规则开关与级别 rules: security: enable: true max_severity: critical performance: enable: true max_severity: high reliability: enable: true max_severity: high maintainability: enable: true max_severity: low # 只报告低级别不作为重点 correctness: enable: true max_severity: high style: enable: false # 风格问题交给格式化工具不占用评审资源 # LLM配置 llm: base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model_options: # 小改动用轻量模型 small: model: ${SMALL_MODEL} max_tokens: 1500 temperature: 0.2 threshold_diff_lines: 200 # 大改动用深度模型 large: model: ${LARGE_MODEL} max_tokens: 3000 temperature: 0.1 threshold_diff_lines: 200 # 输出设置 report: # 报告输出目录 output_dir: ./reports # 是否生成JSON完整报告 save_json: true # 是否生成Markdown摘要 save_markdown: true # 报告里的问题数量上限防止报告过长 max_issues_per_file: 10这份配置的核心思想是分级分层scope控制看什么diff_limits控制怎么看多少rules控制看重点llm控制用什么模型看。有几个细节要特别提醒temperature务必保持在0.2以下代码评审不是创意写作温度高了模型就开始自由发挥给出这个函数命名可以改进这类正确的废话style规则我默认是关的因为风格问题交给Prettier、ESLint这类工具更便宜、更精确完全没必要花Token让LLM去数空格。3.3 跑通第一轮评审从命令行到结果报告配置写好后核心入口的使用方式非常简单。我用命令行形式触发一波评审export LLM_BASE_URLhttps://api.your-provider.com/v1 export LLM_API_KEYsk-xxx export SMALL_MODELqwen2.5-coder-7b-instruct export LARGE_MODELclaude-sonnet-4-20250514 python src/main.py \ --repo-dir /path/to/your/project \ --base main \ --head feature/ai-review-test \ --rules config/review_rules.yaml \ --output ./reports程序执行时会在终端打印处理流水[collector] 获取变更: main...feature/ai-review-test [collector] 共检测到 2 个变更文件新增 89 行删除 12 行 [context] 正在构建正变更上下文: 2 个文件 [router] 变更规模较小路由到 small 模型 [llm] 调用模型: qwen2.5-coder-7b-instruct耗时 3.2s [reporter] 生成评审报告: ./reports/review_20240521_153000.md生成的Markdown报告长这样# 代码评审报告 ## 评审范围 - 分支: feature/ai-review-test - main - 变更文件: 2 个新增 89 行删除 12 行 - 评审模型: qwen2.5-coder-7b-instruct ## 问题摘要 | 级别 | 数量 | 主要问题类型 | | --- | --- | --- | | High | 1 | 资源未关闭 | | Medium | 2 | 边界条件缺失 | | Low | 1 | 日志信息不足 | ## 问题明细 ### [High] user_service.py: 第47行 - 数据库连接可能泄漏 - 规则: reliability - 问题描述: 在get_user方法中当db.query()抛出异常时 连接未通过finally块释放可能造成连接池耗尽。 - 建议: 使用with语句管理连接生命周期或在finally中显式关闭。 ...这一步跑通之后你就拥有了一个最基础的AI评审能力。剩下的事情都是工程化优化接入CI、加通知、做数据回流。3.4 把评审集成进GitHub Actions / GitLab CI命令行能用只是第一步真正让团队离不开它必须集成到现有代码托管平台。我用GitHub Actions举个例子直接在.github/workflows/code-review.yml里写name: code-review on: pull_request: types: [opened, synchronize, reopened] jobs: ai-review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 必须拉全历史否则没法比较base分支 - name: Run open-code-review env: LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }} LLM_API_KEY: ${{ secrets.LLM_API_KEY }} SMALL_MODEL: ${{ secrets.SMALL_MODEL }} LARGE_MODEL: ${{ secrets.LARGE_MODEL }} run: | pip install -r requirements.txt python src/main.py \ --repo-dir . \ --base origin/${{ github.event.pull_request.base.ref }} \ --head origin/${{ github.event.pull_request.head.ref }} \ --rules config/review_rules.yaml \ --output ./reports - name: Post comment to PR uses: actions/github-scriptv7 with: script: | const fs require(fs); const report fs.readFileSync(./reports/review_latest.md, utf8); await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: report });这里有一个极其关键的注意点actions/checkout必须设置fetch-depth: 0。如果只拉浅克隆git diff base...head比较时没有base分支的完整历史直接报错或者说差异为空这个问题我见过太多人踩了。关于CI的集成策略我的建议是默认只评论不阻塞。让AI评审意见以评论形式出现在PR里给开发者作为参考而不是直接设为Required Check。原因很现实AI偶尔会出现低质量意见如果它阻塞了重新合入团队的抵触情绪会非常大。等团队适应了这套工具、规则也调顺之后再考虑在核心项目上把零高危问题设为硬性门禁。GitLab CI的接入方式类似只是把Post comment换成GitLab的MR Webhook API核心逻辑不变。4. 常见问题与排查技巧实录4.1 模型幻觉问题怎么让AI少“编”点幻觉是LLM评审最大的拦路虎。我遇到过最离谱的一次模型指着一段完全没有改动的地方说这里存在SQL注入风险而且建议的修复方案根本对不上实际代码。排查后发现原因有两个 一是Prompt里没有明确约束只评审Diff中变更的部分模型把上下文里的旧代码也拿来评了一通 二是上下文片段结构不够清晰模型把不同函数的边界搞混了。解决办法是双管齐下。Prompt里强制加入一段指令只评审本次变更的代码行不评审未变更内容如果对某段代码的用途不确定必须明说不确定禁止猜测。另外在规则引擎里加了置信度过滤模型输出问题时必须附带confidence字段低于0.7的问题默认被过滤掉。这个设计帮我砍掉了大约30%的无效意见质量明显提升。4.2 成本控制烧钱大户的省钱玩法AI评审的成本大头不在调用次数而在Token消耗。有一次我用大模型直接跑一个变更很大的老项目单PR的费用高得离谱。后来我把成本控制策略总结成三条铁律第一条只评审变更行。上下文可以带但评审对象必须是Diff里的新增/修改行绝不整文件扫描。 第二条先路由再评审。小PR用便宜模型大PR用好模型这个策略执行下来绝大多数日常变更都走便宜模型成本直接降一大半。 第三条给单次评审设Token上限。我上面的配置里max_tokens只有1500这个值足够覆盖绝大多数日常评审。如果模型的输出触顶了我会在报告里标注输出达到上限可能有遗漏提醒开发者不要把这当成全量审查结果。还有一招更狠把重复发起的评审缓存住。同一个Commit SHA的评审结果直接读缓存不再重复调用模型。CI里偶尔会有重复触发的情况比如开发者连续push了几次这招能把无效调用直接清零。4.3 意见质量不稳定温度、示例和反馈闭环很多团队试用一两天后就放弃了原因是AI的意见一会儿靠谱一会儿离谱。我排查下来问题往往出在温度设置和Prompt里缺少示范。温度太高是头号杀手。有团队直接在面板里把温度拉到了0.7结果模型在评审报告里跟你讨论起代码审美来了。我后来在配置里把温度下限写死为0.1不通过配置根本改不上去。除了温度Prompt里加少样本示例也是稳定质量的关键。我在review_system.tmpl里塞了三条典型的评审示例一条是真实的高危问题资源未关闭、一条是边界条件问题数组越界、一条是不该报的问题并且明确标注了为什么不该报。模型看到样例之后输出的风格和粒度都会向样例靠拢这个技巧比任何参数调优都管用。反馈闭环也很重要。我的做法是让开发者在PR评论区对AI意见回复/ai-agree或/ai-disagree后台收集这些标注数据定期把不该报的问题追加到系统的负面清单里下次同样的模式就不再触发。跑了两三个月后系统针对这个团队的误报率会明显下降。4.4 延迟高、CI卡顿怎么办最开始的版本是同步调用模型导致每个PR的AI评审要等45秒甚至更久CI流水线被卡得死死的开发者怨声载道。后面我改成了异步策略第一把评审过程丢到后台队列里跑用Celery或直接用Redis做任务队列也行。CI只负责投递任务不等结果。 第二评审完成后通过Webhook把报告推送到PR评论或企业微信、飞书、钉钉群。开发者想看就看不想看也不阻塞流程。 第三给LLM调用设置了重试机制首次超时60秒失败后退避重试两次仍失败就把PR列入评审失败清单在群里提醒管理员手动评估。一套组合拳下来CI的额外延迟从45秒降到2秒以内团队接受度立刻上来了。4.5 团队不想用、落地受阻怎么办技术问题都好解决落地难才是这个项目真正的大坎。我在几个团队推这套系统过程中踩了不少坑总结了几条实用经验先找试点团队别一上来全公司铺开。选一个技术氛围比较open、对AI工具接受度高的小队让他们先用一个月。试点期间每周和开发聊一次收集哪类意见没用的反馈调规则。评审意见的风格要中性、有依据。我专门在Prompt里写了一句所有意见必须以客观语气描述事实和建议不说教、不调侃。因为开发看到AI用说教口吻讲话第一反应就是关掉这个功能。绝不能让AI意见直接判定PR失败。即使后面要设质量门禁也要设置警告级别先手动确认AI的高危意见确实有效再把规则转成硬性拦截。信任是一步步建立的不是一蹴而就的。最后做个规模发言open-code-review这个项目做到现在我在自己团队跑了两个多月累计评审了600多个MRAI平均每个MR能发现3.2个有效问题其中大概有0.4个高危问题这些高危问题在人工评审里基本都会被漏掉。这组数据让我非常确定AI代码评审不是噱头是实打实能提升质量的工具。如果你也想试建议从小团队、低温度、强规则起步跑两周看数据再决定要不要推广。这套系统真正的价值不在于模型多聪明而在于它能把你们团队积累的评审经验蒸馏成一条条可执行的规则让每一次提交都被一双永不疲倦的眼睛盯住。
阅读完成 · 觉得有帮助？
