1. 为什么我要把 Code Review 自动化：一个每天都在消耗我的真实场景
我把这个项目命名为open-code-review，听起来像要以开源方式做一个通用代码评审工具，但最初它只是一个很私人的脚本。原因是我实在受不了一种日常：每次打开合并请求，页面里铺满了大大小小的评论，有的在提醒import顺序，有的在问"这里是不是少了空值判断"，还有的只是把代码转述了一遍。真正值得讨论的架构问题，反而被淹没在琐碎意见里。
我给这个项目定的目标是：在人类 reviewer 打开 diff 之前，先让机器把能确定的问题筛掉一轮，同时把需要人来判断的风险点标出来。它不是一个"自动挑刺机器人"，更像一个审前过滤器。做出来的东西现在跑在本地命令行、服务端流水线、以及合并请求的评论入口里，每天能帮我把 review 时间压掉差不多三分之一。
这篇文章适合谁？如果你是团队里负责把关代码的人，或者你在一个小团队里根本没有专职评审，又或者你只是想给日常工作里那套"人工看 diff"的流程加点自动化手段，这篇文章里写的东西应该对你有直接参考价值。
先说结论：代码评审自动化的难点从来不是"调用大模型看代码"，而是把边界划清楚，什么该提示、什么该拦截、什么不该碰。open-code-review的完整工作流基本是：解析 diff -> 规则引擎过滤确定性问题 -> 可选的大模型语义检查 -> 生成带行号和证据的报告 -> 以不同模式接入 review 流程。下面拆开讲。
2. 动手之前先划边界：哪些问题能自动化，哪些不能
我在项目第一版犯过一个典型的错误：把"代码评审"当成"放大版的静态检查工具"，试图用一堆正则去覆盖所有维度。结果是误报率非常难看。后来我花了一个周末把日常 review 里见过的意见做了分类，才确定了这个项目的边界。
2.1 第一类：能用确定性规则判断的"硬问题"
这类问题不依赖业务上下文，规则定了就不会反悔。最典型的是 import 排序、重复的 key、死代码引用、明显的语法问题、命名风格不统一、TODO 没清理、测试里残留的调试输出。这些意见在人工 review 里属于"看得到但不想看"的噪音，但对机器来说是最容易的得分项。
open-code-review在这一层采用了规则引擎，每条规则返回三级信息：问题级别、文件位置、证据片段。证据片段是 diff 里原始代码的上下文，不是只给行号。因为只给行号的话，reviewer 还得跳回代码里自己找位置，这就失去了自动化过滤的意义。
2.2 第二类：需要上下文才能判断的"软问题"
这类意见是"看起来像建议，但没法用正则确定"。比如"这个函数的边界条件是不是漏了""这段错误处理放在这里合理吗""这个状态字段在并发场景下会不会有竞态"。它们的问题特征不是固定的，必须结合函数签名、调用方、乃至整个模块的约定才能判断。
我曾经尝试把这类问题全部丢给大模型做语义扫描，后来发现效果不稳定。同样的 diff 今天能扫出三个问题，明天同一个模型可能一个都不报，或者报出两个昨天没提的。这不是模型笨，是问题的定义本身就模糊。open-code-review对这类问题的策略是：支持，但明确标注为"供人类 reviewer 参考"，不做拦截依据。同时它会限制请求范围，不是把整个仓库喂进去，而是只带相关函数和五到十行的上下文，这样语义判断的稳定性能提高不少。
2.3 第三类：给人类 review 提供"路标"的提示性信息
这类问题不是缺陷，但很有价值。比如"这个文件本次改动超过 300 行，建议重点 review""这里新增了一个之前没出现过的依赖""这个函数从一个私有函数变成了模块级导出"。
以前这些信息要靠 reviewer 自己从 diff 里发现，而人的眼睛在几十个文件里扫来扫去，很容易漏掉。open-code-review会把这类提示单独归入info级别，不打断流程，但放在报告最前面，相当于给人类 reviewer 递了一张地图。
2.4 自动化不该碰的问题
架构方向、产品取舍、团队历史约定、业务顶层设计……这些我统一不纳入规则，也不建议大模型直接点评。原因很简单：这类问题的"正确答案"只存在于团队语境里，外部模型看到的只是代码片段，它给出的高谈阔论反而会污染 review 讨论区。open-code-review的默认配置里有一条不成文的原则——宁可漏掉一个潜在问题，也不要产生一条无法被人类快速判断的评论。因为一条误导性评论的杀伤力，比十句正确废话都大。
我把这四类问题整理成一张表，后来也给团队里其他自动化项目参考过：
| 问题类型 | 典型例子 | 判断依据 | 自动化策略 | 期望准确率 |
|---|---|---|---|---|
| 硬问题 | import 顺序、死代码、重复 key | 单文件即可确定 | 规则引擎直接拦截 | 95% 以上 |
| 软问题 | 空值处理、错误处理位置、边界条件 | 需要函数级上下文 | 大模型语义建议 | 60%~75% |
| 路标信息 | 大改动文件、新增依赖、新导出 | 仅需统计 diff | 直接提示 | 100% |
| 不该碰的问题 | 架构选择、产品决策 | 需要团队语境 | 不生成评论 | 不适用 |
3. 模块设计：一条 diff 从进入工具到生成报告，到底经历了什么
open-code-review内部的流水线看起来简单，但每个环节都有一些容易被人忽略的细节。这里我按数据流向拆开讲。
3.1 解析 diff：不只看变更行，还要保留"前后文快照"
很多人做 diff 检查时会犯一个错误：只提取+、-的行，然后对这两组字符串做分析。这样确实快，但会导致两个问题。第一，新增的代码缺少前文，规则判断时看不出来这个函数原本有没有空值保护；第二，人类 reviewer 看到的意见只有孤零零几行，理解成本很高。
open-code-review的做法是把 unified diff 解析成结构化的变化块，每个变化块不仅包含变更行，还保留了前后最多五行的快照。这个过程看起来像是在浪费资源，但实际上决定了规则引擎的准确率上限。举个例子，如果工具只看到一行return _load_config()，它无法判断这是不是空值返回；但有了前文三行的上下文，它能看到_load_config上面刚刚有个FileNotFoundError的 catch，那么规则就能给出更准确的提示。
解析核心是一个简化的 unified diff 解析器，类似下面这个伪代码：
def parse_unified_diff(content): changes = [] current_file = None hunk = None for line in content.splitlines(): if line.startswith("+++ b/"): current_file = line[len("+++ b/"):] elif line.startswith("@@ "): # 新 hunk，记录新文件的起始行号与范围 hunk = {"file": current_file, "lines": [], "start": 0} elif hunk is not None: marker = line[0] if line[0] in "+- " else None if marker is not None: hunk["lines"].append({ "type": marker, # plus / minus / context "content": line[1:], "line_number": next_number, }) elif line.startswith("+++") or line.startswith("---"): continue return changes这只是一个示意。真实实现里我会把每个+行和它前面的最近上下文行组成一个"诊断单元"传给规则引擎，并记录新的行号。这样最后生成的每一条意见都能直接对应到 diff 里的物理位置。
3.2 规则引擎：pattern 与 condition 分离
规则引擎是我在设计上花时间最多的部分。如果规则只有pattern一个字段，很快配置文件会变成一团乱麻。open-code-review将一条规则拆成两个层面：模式（pattern）和条件（condition）。模式描述"什么样的代码结构需要关注"，条件描述"真正要触发的应用场景"。
还是举例说明。假设我们想检查"新增的 TODO"，模式层是检测到TODO或FIXME字符串，条件层是"这个字符串出现在本次新增行中，而不是历史遗留行里"。这样拆开后，一条规则的表达能力明显变强，统计和误报修正也更容易。比如某次新代码里确实有一个TODO，但经过确认是外部依赖的符号名称，那我可以给规则加一个排除条件，不用删除整条规则。
再看 import 顺序规则的实现思路。我不建议直接写一个大正则去解析所有语言的 import 块，因为不同语言语法差异太大。open-code-review的做法是让规则引擎接收解析后的"代码结构流"，每种语言提供一个很小的 tokenizer，输出的是语言中立的 token 列表。规则里写的是 token 序列模板，而不是原始字符串。比如一条 Python import 排序规则，本质上是说"在 import 块内，出现了字典序逆序的两个模块名"。这样规则配置不会随着语言特性爆炸式增长。
3.3 可插拔的语义分析器：大模型的请求组装是核心技术难点
规则引擎处理不了"空值处理是否到位"这类问题，这时需要语义分析器。open-code-review在这里做了一个抽象的SemanticAnalyzer接口，默认实现可以接任意大模型接口。但我实际调这个接口时发现，请求组装才是决定输出质量的关键，而大模型本身反而不是瓶颈。
我的策略是：每次只取一个"诊断单元"，也就是 diff 中某个文件的某一段变化块，加上变化范围内的函数签名和最多十行上下文，拼成一个短小的 prompt。prompt 里不写"请全面审查"，而写"请仅基于以下规则给出结论"。后者几乎是两个量级的差异：前者会让模型自由发挥，输出大量"建议优化"；后者则把模型框在可控范围里，回复稳定很多。
为了让结果更可验证，我会在 prompt 里塞一个例子，用 few-shot 的方式告诉模型回答的格式。模型返回的结构会被解析成一个序号列表，每一条必须包含行号和理由。如果有任何一条缺行号，整批会被丢弃并重跑一次。宁可少报，不要报一条无法落地的意见。
3.4 报告格式：评审意见必须能"回到代码里"
报告直接决定这个东西有没有用。我的原则是：每条意见都必须能让人十秒钟内找到位置。纯文本的 console 输出是最低规格，更完整的是 JSON 结构，方便别的工具继续处理。所有意见都包含四件事：file、line、rule_id、evidence。
其中evidence是原始代码片段，不是把代码再复述一遍。这一步很关键，因为它直接决定规则的可靠性。如果规则引擎发现有问题，证据就是触发规则的那行原始代码；如果语义分析器发现问题，证据就是它判断所依赖的上下文片段。reviewer 看到一条意见时，先看证据，再决定是否点开文件。
4. 我在实现 open-code-review 时踩过的五个坑和对应解决方案
这一节可能比前面的设计更值钱。因为设计是在纸面上，坑是实打实的教训。
4.1 坑一：把评审当成静态检查，误报率直接爆炸
第一版规则里我借鉴了常见的静态分析规则，比如"函数不应该超过 30 行""变量名不能太短"。结果到了真实 diff 里，这些规则几乎每一条都在误报。原因很简单：静态分析工具的规则是给整个文件用的，而评审场景只关注变更增量。一个 300 行的函数可能是历史遗留的，本次只改了里面一行，如果规则把整个函数拎出来说"太长"，开发者一定会觉得工具疯了。
解决思路是：所有规则默认只评估新增行和新增行影响的范围，历史问题只在"路标信息"里提示，不作为缺陷报告。并且新增规则前必须回答一个问题："当一个开发者看到这条提示时，能不能在三秒内把它归类为确定性问题？"如果不能，这条规则就不该进规则引擎。
4.2 坑二：大模型拿到的是孤立 diff，连函数边界都看不到
我试过直接把git diff的完整文本丢给大模型，结果它经常把同一个函数的两个变化块当成两个无关片段，给出的意见互相矛盾。后来我意识到，diff 本质上是"碎片化"的，模型看到的是片段拼接，不是结构完整的一块代码。
解决方法是前面提到的"诊断单元"思想。在做语义分析之前，先扫描变化块所在文件的函数结构，找到包含这些变化块的函数，然后把函数签名、函数体前几行、以及变化块的上下文一起打包。这样语义分析器看到的不是一段碎片，而是一个有边界的函数。这个改动之后，语义分析意见的采纳率从 40% 出头提到了接近 60%。
4.3 坑三：大模型输出不稳定，同一个 diff 每隔十分钟报法不一样
这个问题出现得比我想象中早。一开始我以为是 prompt 写得不够细，后来发现即使把 prompt 固定、把 temperature 调到 0，模型还是会在措辞和结论倾向之间漂移。
我最终的妥协方案是：可复现性优先于覆盖面。语义分析器在输出后，会做一次简单的自校验，把意见里的每条结论再次放进模板里询问模型"以上结论是否成立"，只保留两次都成立的意见。与此同时，我永远不会拿语义分析的输出做合并请求的硬性拦截。规则的稳定性必须由规则引擎负责，语义分析只负责给建议。这样即便模型偶尔抽风，也不会破坏整个流程的可信度。
4.4 坑四：接入服务端流水线之后，请求超时把整条链路拖慢了
这是上线之后第一个运营事故。有一次一个合并请求改了一千多个文件，open-code-review逐文件扫描，在大模型语义分析阶段花了将近十分钟，CI 任务直接超时，流水线标红，开发者开始找我。
我做了三层限制。第一层是文件级增量过滤：只跑本次有变更的文件，没变的不进分析队列。第二层是大小阈值：超过 500 KB 的文件跳过全部语义分析，只保留规则引擎结果。第三层是超时熔断：单个问答接口超过 60 秒就直接放弃该文件的语义检查，并记录一条提示。这三层做完之后，绝大多数 diff 的扫描时间都能控制在三分钟以内。我还把语义分析改成可选配置，默认关闭，只有团队明确需要时才打开。
4.5 坑五：配置文件从十几行膨胀到几百行，最后没人愿意改
规则多了之后，维护成本开始超过收益。每加一条规则都要重新理解配置语法，测试新规则的效果，还要处理规则的相互作用。我一度想把它做成可视化管理界面，后来冷静下来，决定先把配置格式本身简化。
open-code-review现在的规则文件采用"三层结构"：第一层是id和description，让人一眼看出这条规则在干嘛；第二层是pattern，描述匹配结构；第三层是condition，描述触发限制。任何一条规则如果无法用这三层结构表达清楚，就会被拒绝进入默认配置。默认配置只带三条规则起步：新增 TODO 检查、import 顺序检查、空值风险提示。先把这三条跑顺，再根据自己的团队逐步添加。
5. 让 open-code-review 在团队里真正跑起来：一份可以直接抄的配置样例
很多人看完原理会觉得不难，但真正上手时还是会卡在第一步：怎么配置、怎么跑、怎么让团队接受。这里我给出一个可以直接参考的配置样例和实践路径。
5.1 基础配置文件长什么样
open-code-review使用 YAML 配置文件，命名是.ocr.yaml，放在仓库根目录。下面是一份实际的起步配置，我会逐段说明。
version: 1 repo: language: python include_paths: - "src" exclude_paths: - "tests/fixtures" - "generated" check: max_diff_size: 500 concurrency: 4 rules: - id: todo-left-in-changes description: 新增行里出现 TODO / FIXME level: warning pattern: type: token target: any values: ["TODO", "FIXME"] condition: only_new_lines: true - id: import-order-python description: Python import 块未按字典序排列 level: warning pattern: type: sequence language: python context: import_block condition: ordering: lexicographic semantic: enabled: false endpoint: "" timeout: 60 min_confidence: 0.6这里的semantic.enabled: false特意设置默认关闭。上线阶段先只跑规则引擎，让团队熟悉输出格式和意见风格，再逐步打开语义分析。max_diff_size: 500的意思是单次变更超过 500 个文件时直接放弃语义分析，避免把流水线拖垮。
5.2 本地执行的三种常见姿势
配置好之后，最常用的执行方式有以下三种。第一种是本地 diff 自检，开发者在提交前跑一下，相当于给自己的代码过一道过滤器：
open-code-review --base main --report console执行后会在终端输出这样的结果：
[open-code-review] 扫描完成：12 个文件，新增 340 行，删除 120 行。 warning src/parser.py:119 import 顺序不符合字典序（'os' 应排在 'sys' 之前） warning src/loader.py:204 未对 _load_config() 的返回值做空值判断 info src/parser.py:180-190 本次新增 TODO 1 个，建议合并前确认第二种是格式化报告输出到 JSON 文件，方便接入自定义脚本或消息通知：
open-code-review --report json --output review_result.json第三种是增量定时扫描，适合团队不想在合并请求阶段增加卡点的情况。可以每天晚上由流水线跑一次全仓库 diff，把意见汇总到一个频道里，第二天开发者自己来认领。
5.3 接进合并请求流程：先做"点评模式"，再考虑"拦截模式"
我强烈建议任何团队第一次接入时都只开"点评模式"，也就是工具在合并请求下方留评论，但不阻止合并。原因是工具刚上线时必然有误报，如果一开始就做硬拦截，团队对工具的第一印象就会变成"阻碍我上线的东西"。
点评模式跑两周之后，再根据实际采纳率决定哪些规则升级为 critical。比如import-order-python如果连续两周没有一条误报，采纳率超过 90%，就可以把它设为拦截规则，任何包含该问题的合并请求直接挂红。而"空值风险提示"这类软问题则长期保持点评模式。
接入的伪代码也非常直接：
REVIEW_RESULT=$(open-code-review --report json) if [ "$IS_BLOCKING_RULES_ON" = "true" ]; then if echo "$REVIEW_RESULT" | grep -q '"level": "critical"'; then echo "合并请求包含阻塞级问题，请在合并前修复。" exit 1 fi fi echo "$REVIEW_RESULT" >> review_comment_body.md exit 0这一步强调的只是流程骨架。真正上线时建议把规则列表、拦截级别、白名单都放到配置里管理，不要在脚本里硬编码。
5.4 规则集怎么逐步扩大才不失控
我见过太多团队第一天就把规则集堆到三四十条，结果第二天集体关掉。更稳妥的做法是：先定三条准确率最高、争议最少的规则，跑两周，统计采纳率，制定一张"规则晋级表"。
我会用下面这张表来管理每条规则的状态：
| 规则 | 级别 | 触发数 | 被采纳数 | 采纳率 | 状态 |
|---|---|---|---|---|---|
| todo-left-in-changes | warning | 18 | 15 | 83% | 维持 |
| import-order-python | warning | 9 | 9 | 100% | 准备晋级 critical |
| 空值风险提示 | suggestion | 12 | 7 | 58% | 继续观察 |
采纳率超过 70% 的规则可以考虑升级；低于 40% 的规则直接下线或降低级别；40% 到 70% 的规则保持观察。这样做的好处是规则集不会靠"感觉"膨胀，每一次调整都有数据支撑。规则数量的上限我建议控制在十五到二十条，超过这个数，维护成本就开始超过收益。
6. 我如何看待 open-code-review 的长期边界：工具省下的时间到底该花在哪
用到现在，我最深刻的体会是：这类工具的价值不在于"替代人类 reviewer"，而在于把人类 reviewer 从"看得到但不想看"的问题里解放出来，让讨论重新回到真正重要的事情上。它更像是一个前置过滤器，让每个合并请求在被人工看之前，已经去掉了一层噪音。
我现在的使用习惯是这样的：写代码的时候会在提交前手动跑一次open-code-review --diff --base main，确认规则引擎没有意见后再提交。合并请求创建之后，服务端流水线会自动生成一份"审前地图"，把较大的改动文件、新增依赖、遗留 TODO 放在最前面。真正的 reviewer 打开页面时，第一眼看到的不是散乱的评论，而是一份已经整理过的阅读路线。
这还只是第一阶段。我后续想把 diff 摘要功能做得更细，比如让工具在每个合并请求开头自动生成一段"本次改动简介"，能一句话说清楚改了什么、影响哪些模块、建议重点看哪些区域。如果这段简介足够准确，reviewer 打开页面的认知成本会再降一个台阶。另外也可以让open-code-review在开发者提交前生成一份"自查清单"，告诉作者"你这次改动里有三个 TODO、一个空值风险点、一处大的重构"，让作者在自己打开合并请求之前先自查一遍。
这里面的每一次扩展，都要回到最开始那个边界问题：这条意见是否能被人类在三秒内理解并验证？如果不能，它就不该出现。我在实际使用中最大的收获，其实不是工具帮我省下了多少时间，而是我被迫把"什么样的代码意见才算有效意见"这件事想清楚了。如果你也在做类似的自动化评审工具，建议你先从这个问题开始，而不是从某个具体技术开始。
