做代码评审这么多年我一直有个很深的体会评审意见里至少有三分之一其实是规则就能自动筛出来的。比如SQL字符串拼接、硬编码密钥、调试日志残留、空catch块这些东西不需要讨论只要规则够明确机器完全可以在提交Merge Request的瞬间自动标出来。open-code-review 这个项目就是我把这个想法真正落地后的产物——一个以 Git Diff 为处理核心、以规则引擎为骨架、可选接入大模型辅助的代码评审工具。它不负责替代人的判断只负责把重复性劳动和低置信度噪音挡在人工评审之前。如果你正在维护一个中等规模的代码仓库又被“每天都有重复低级问题需要人点评”这件事困扰这篇文章应该能给你提供一套可以直接抄走的思路和实现。1. 评审流程里的三个真实痛点以及它们如何逼我写了 open-code-review1.1 第一个痛点重复性问题反复出现人工评审根本盯不住我在某个业务系统的迭代维护阶段做过一次观察一次常规的MR评审人工能真正聚焦的逻辑问题不到一半其余时间都在反复标注同一类问题——SQL用了字符串拼接、密钥直接写在配置里、try-catch 里吞了异常、临时代码console.log/print忘记删除。这些问题不是团队成员水平不行而是人脑在处理大量代码变更时天然会疲劳注意力和标准线都会快速下滑。尤其是临近下班提交的MR漏检率会明显上升但评审者事后回看时又会觉得“这么明显的问题我怎么没看到”。这个问题本质上是“规范记忆”的失效。规范不是不存在而是散落在文档、会议纪要、历史评论里每个人执行标准不一样。如果把这些规范编码成确定性规则在代码变更的第一瞬间就自动检查完全可以省掉一大部分人工重复劳动。这也是我决定动手做 open-code-review 最原始的动机让“人记规范”变成“规则查代码”。1.2 第二个痛点规范落地靠嘴反馈碎片化严重第二个让我受不了的场景是规范写出来了也评审通过了但两个月后依然有人在问“这个规则还在生效吗”。评审意见散落在各个MR里没有结构化汇总想统计某个问题出现频率、某个模块重复踩坑的次数全部靠拍脑袋。我记得有一次正好碰到某位核心开发请假另一个同事接手改一个老模块仅仅因为不知道“这个模块禁止使用某个已废弃的公共包”就花了一整天在定位问题上最后起因就是一条早就写进规范但没人记得的约定。这类问题被工具化之后理想状态应该是不用人记住“这条规范在不在”只要代码触碰了机器就会自动提出证据并输出结论。open-code-review 的规则引擎本质上就是把这些“散落的约定”变成仓库内可见、可评审、可统计的显式配置。1.3 第三个痛点评审意见无法沉淀改完就丢第三个痛点相对隐性评审意见没有可复用的生命周期。一个意见今天在A项目被提了明天在B项目又被提一次过程、结论、修复方式完全不沉淀。真正有效的评审体系应该能告诉你“这个MR的失败点是什么、同类问题本周出现几次、集中在哪些目录”。这些维度靠人工整理完全不可持续必须靠自动化工具在每次评审时自动采集和汇总。正是因为这三个问题叠加我才决定自己动手做一个工具也就是现在的 open-code-review。它的定位从一开始就很明确以 Diff 为输入只审查变更内容不做全量代码质量体检规则引擎负责确定性检查保证结果可复现、可解释大模型作为可选模块只在规则引擎无法覆盖的语义层面提供辅助最终统一输出结构化报告并支持直接以评论形式回写到 MR/PR 里。这个定位决定了后面所有技术选型接下来我把设计和实现细节完整拆开讲。2. 整体设计思路Diff 是核心规则是骨架LLM 只是补充2.1 为什么一切从 Git Diff 出发代码评审和代码体检最大的区别在于评审关心的是“这次变更引入了什么”而不是“这个仓库整体有多糟糕”。所以 open-code-review 的第一原则就是只处理 Git Diff不扫全量代码。这样有几个直接好处评审成本与变更规模成正比。仓库再大单次 MR 只有几百行变更时检查可以在秒级完成所有结论都能精确对应到具体文件和具体行号方便回写到 MR 评论区减少存量代码的噪音干扰不会因为历史遗留问题淹没新增问题。当然只处理 Diff 也有代价比如无法做跨文件的深层数据流分析无法发现“新增的函数与另一个模块已有函数功能重复”这类问题。这个代价我认了把这类问题留给人工评审和大模型辅助模块规则引擎专注在确定性检查上。2.2 规则引擎和大模型的边界该怎么划我见过不少团队一上来就想把所有评审交给大模型然后发现结果不稳定、成本高、不可解释最后又回归人工。open-code-review 的答案是把两者拆开各管一段规则引擎离线、快速、确定性输出负责语法风格、安全模式、代码异味等“有明确模式”的问题大模型在线、相对慢、语义理解强负责空指针风险、逻辑边界遗漏、接口设计合理性等“没有明确模式”的问题。这个分工带来的直接工程约束是大模型模块必须可降级。如果模型服务超时、配额不够、网络抖动整个工具必须能自动退回只输出规则引擎结果否则 CI 会被堵死。2.3 一条评审请求的完整数据流从调用方视角看一次评审大致经历以下步骤获取变更清单 - 拉取目标分支最新代码 - 执行 git diff 或调用平台 API 获取补丁 - 解析 diff 得到变更文件列表与 hunk 块 - 按文件语言类型归类 - 规则引擎逐条匹配 - 可选收集函数级上下文送给大模型 - 合并两类结果 - 过滤低置信度与无效行号 - 生成 Markdown / SARIF 报告 - 可选通过平台 API 回写 MR 评论前四步是所有模块的地基后面每一步都依赖它所以 Diff 解析器是第一个要认真写的模块。项目目录结构也围绕这条链路组织open-code-review/ cli.py # 命令行入口 diff/ parser.py # diff hunk 解析与行号映射 collector.py # 拉取变更文件列表 rules/ engine.py # 规则引擎执行器 builtin/ # 内置规则 custom/ # 用户自定义规则 ai/ client.py # 大模型接口抽象 prompt.py # 上下文裁剪与 prompt 组装 schema.py # 输出 schema 校验 report/ markdown.py sarif.py platform_api.py # MR 评论回写 config/ loader.py # 配置文件解析这套结构看起来简单但后面所有踩坑和优化都围绕其中的某一环展开下一章我挑核心模块逐个讲实现细节。3. 关键模块的落地细节从解析 Diff 到生成评审报告3.1 Diff 解析变更类型、行号映射与上下文窗口很多人觉得解析 diff 很简单实际写起来才会发现问题都出在行号映射上。git diff 的标准格式中每个 hunk 头长这样 -12,5 15,8 func_name在旧文件的上下文中-12,5表示旧文件从第 12 行开始共 5 行15,8表示新文件从第 15 行开始共 8 行。解析时至少需要维护两组映射旧文件行号到新文件行号的映射以及新文件每一行是否属于新增行。因为后续无论是规则引擎报告还是大模型回复最终都要落到“新文件第几行有问题”所以 open-code-review 内部统一使用新文件行号作为唯一坐标。实现时我维护一个行号映射表把 hunk 里每一行在旧行号和新行号之间的偏移关系记录下来。一个简化版本的核心逻辑大概长这样def parse_hunk_header(header: str): # header 形如 -12,5 15,8 parts [p for p in header.split() if p.startswith((-, ))] old_part, new_part parts[0], parts[1] old_start, old_count parse_line_spec(old_part) new_start, new_count parse_line_spec(new_part) return old_start, old_count, new_start, new_count解析出 hunk 之后还要做上下文窗口管理。规则引擎在判断一些模式时需要知道某一行是否位于新增行以及它所在的代码块上下文。默认我取新增行前后各三行作为上下文规则引擎可以配置这个窗口大小。更关键的一个点是diff 里会包含新增文件、删除文件、重命名文件、二进制文件。open-code-review 对它们的策略不同新增文件走完整检查删除文件只做确认性提示重命名文件默认跳过行级规则避免把“文件移动”误判成“代码新增”二进制文件直接跳过文本规则。这些看起来不起眼的细节决定了报告的行号定位是否可信。3.2 规则引擎内置规则分类与规则 DSL 设计规则引擎是整个工具确定性能力的核心。内置规则我按四个维度分类对应绝大多数团队会关心的检查项分类典型规则默认级别风格规范行长度、Tab/空格混用、文件结尾缺换行warning安全风险SQL 字符串拼接、硬编码密钥、危险函数调用error代码质量空 catch 块、调试日志残留、魔法数字、重复代码块warning并发性能循环内 sleep、锁粒度过大、潜在死循环模式warning规则模式的表达形式我最后选用了“正则模式 语言过滤 路径过滤 上下文条件”组合的方案而不是直接上 AST。原因有三个团队里的规则维护者不一定是编译器专家正则和 YAML 的接受度远高于 AST 代码多数需要拦截的安全模式在词法层面就有显著特征比如execute(SELECT ... var)正则完全够用内置规则只追求高置信检查真正做到宁可漏、不可错报。一条规则在配置文件里长这样rules: - id: SQL_INTERPOLATION severity: error languages: [python, java, javascript, go] pattern: (?i)(execute|query)\\s*\\([^)]*\\\\s*\\w message: 发现SQL字符串拼接请改用参数化查询 exclude_paths: - **/tests/** - **/fixtures/** context: in_comment: false in_string: false引擎执行时先按语言过滤再按 exclude_paths 过滤然后对新增行区域做模式匹配。这里有个容易忽略的细节pattern 匹配的是“带上下文的文本块”而不是单行。因为很多危险模式是跨行的比如String sql SELECT * FROM user WHERE id userId;只匹配单行会漏掉一半情况。所以我在规则引擎里默认把 hunk 的上下文拼接成块再让正则作用于块遇到\s时允许跨行。为了防止误报我还在文本层做了一次预处理把注释和字符串内容打码之后再匹配。代价是略微增加耗时但误报率能下降一个数量级这很值。具体做法是先用简单的词法扫描把// ...、# ...、/* ... */、字符串字面量替换成占位符再跑规则。这一步给规则引擎的稳定性贡献极大后面第四章会再讲它怎么帮我解决误报轰炸。3.3 LLM 辅助评审模块Prompt 组织、输出约束与幻觉抑制LLM 模块是我后期才加上的一开始只有规则引擎。加它的原因很简单规则引擎对“某个函数可能空指针”“数组越界”“边界条件遗漏”这类语义问题完全无能为力而这些恰恰是人工评审最想先看的问题。但直接用 LLM 做评审会踩一堆坑第一坑就是把整个文件丢过去。后来我改成了三个原则每次调用前必须遵守。第一只送 Diff 和局部上下文。大文件全量塞进 prompt 不仅浪费 token还会稀释模型对变更区域的注意力。我会先解析出本次新增的函数或方法只提取该函数签名和函数体摘要配上 hunk 文本一并发给模型。第二用 JSON Schema 强约束输出。模型自由发挥时很容易输出“这段代码看起来不错”这类废话所以 prompt 里我明确要求输出一个固定结构{ findings: [ { line: 42, severity: warning, category: logic, confidence: medium, message: 循环内可能存在重复计算, suggestion: 将不变表达式提到循环外 } ] }解析结果时我会逐条校验 line 是否存在于新增行集合中、severity 是否在合法枚举内任何一条不合法就直接丢弃。这步是关键过滤能拦掉大量幻觉输出。第三用温度 0 并设置超时。评审场景不希望模型发挥创造力温度 0 保证重复提交同一批代码时输出稳定。超时按单次请求 60 秒设置失败后工具立即降级为纯规则引擎模式不让模型拖死整个 CI 流程。token 消耗也要提前算。按经验一个 500 行变更的 MR经过函数级裁剪后 prompt 大约在 3000 到 6000 token 左右对大多数模型服务都是可接受的。如果 MR 超过一定规模默认直接跳过 LLM 模块只跑规则引擎毕竟大 MR 本来就该拆小。3.4 报告输出与 CI 集成机器评论、SARIF 和门禁策略工具做得再准如果不把结果放到开发者看得见的地方就等于白做。open-code-review 目前支持三种输出方式按使用频率排Markdown 报告是最常用的。每次评审生成一份摘要按文件和严重级别分组。MR 评论策略我刻意做了克制错误级问题逐条评论在对应行上警告级问题不逐条刷屏只在顶部汇总一条“本次发现 4 个问题其中 1 个 error”避免把 MR 评论区变成垃圾场。SARIF 是给本地工具链用的。我持续生成 SARIF 格式因为主流编辑器和代码扫描平台都支持直接展示 Inline 提示开发者本地跑一次ocr review --diff ...问题就能像断点一样直接浮在编辑器里。这个体验对开发效率帮助很大。门禁策略通过配置文件控制默认推荐做法是 error 拦门禁、warning 只看不拦gate: error: block warning: report_only在 CI 流水线里的接入方式我建议不要用复杂插件只做一步跑一个命令行把 exit code 作为是否阻断的标志。像这样ocr review \ --head $CI_COMMIT_SHA \ --base $CI_MERGE_REQUEST_TARGET_BRANCH_SHA \ --format markdown \ --output review.md # 如果 error 级问题数量 0进程返回非零码CI 自动失败这种接入方式的好处是平台无关凡是能执行命令的 CI 都能用不需要为某个特定平台写集成代码。3.5 一份完整的配置示例把前面所有模块串起来open-code-review 的主配置大概长这样。这份配置我放在仓库根目录.open-code-review.yml里既方便团队 review也便于自动化工具读取。配置里四个大块各自对应一条数据流阶段project 决定语言与文件过滤规则rules 决定规则引擎启停ai 控制大模型辅助模块report 和 gate 决定结果怎么展示、怎么拦门禁。如果你们团队刚接入可以直接复制这份模板只改 languages 和 rules.enabled 两项其余保持默认即可。project: languages: [python, java, javascript, go] rules: enabled: [SQL_INTERPOLATION, HARDCODED_SECRET, EMPTY_CATCH, DEBUG_LOG_LEFT] excluded: - id: DEBUG_LOG_LEFT paths: [**/*.test.*, **/scripts/**] - id: HARDCODED_SECRET paths: [**/test/**, **/example/**] ai: enabled: true endpoint: http://model-svc.internal:8080 # 本地或内网模型服务地址 model: code-review-llm-v2 # 替换为你实际使用的模型标识 timeout_seconds: 60 temperature: 0 batch_lines_limit: 5000 fallback_to_rules: true report: formats: [markdown, sarif] mr_comment: enabled: true comment_on_line_for: [error] summary_comment_for: [warning] gate: error: block warning: report_only4. 跑了大半年踩过的最深的五个坑附完整排查链路4.1 误报轰炸报告出来了团队却没人看第一次把工具接入团队仓库后我收到最多的反馈不是“这工具真好用”而是“这报告也太吵了”。打开报告一看500 多条 warning其中某一条规则贡献了 60% 以上。逐条看样本发现问题集中在几类情况字符串字面量里的示例 SQL 被匹配了测试代码里的构造占位被匹配了注释里粘贴的一个“错误示范”被当成真实代码了。排查链路是先按规则 ID 做命中统计挑出命中量最高的规则再随机抽 20 条命中样本发现几乎都是上述三类。修复方式分三层一是在规则引擎里加入注释和字符串打码预处理二是给高频误报规则配置 exclude_paths把测试和样例目录排除三是在报告层加累计阈值同类型问题超过 10 条时只显示汇总和第一条证据其余折叠。三层叠加之后警告总量降到了原来的 15% 左右团队才开始真正信任报告。4.2 大 Diff 内存失控单文件 8MB 改动把 CI 跑崩某次 CI 任务跑着跑着挂掉了日志最后的输出是 Python 进程被 OOM Kill 掉。查日志发现这次 MR 里有一个数据文件改了 8MBgit diff 输出本身就有十几万行。当时实现是把整个 diff 文本一次性读入内存解析时又对每个 hunk 做了大字符串切片内存瞬间爆炸。排查思路是加日志统计每个阶段的峰值内存很快定位到两个内存消耗点。修复措施有三个diff 文本改为流式读取逐 hunk 解析解析完一个释放一个增加阈值控制默认 max_diff_lines 20000超过后进入降级模式只读取 hunk 元数据和文件级变更统计不再做逐行规则扫描对外层 CI 进程也设了超时保护超过 10 分钟强制终止并输出“本次变更过大建议拆分 MR”。经过修改超大变更不会再拖垮 CI而是直接明确告知开发者你的变更太大了请拆开提。4.3 行号偏移评论定位到空行上有一次团队反馈MR 评论区里机器人说“第 42 行有 SQL 拼接问题”但开发者点开 42 行发现是空行。这个问题非常隐蔽排查过程让我彻底理顺了行号体系。根因在于规则引擎内部某些规则报告的是“模式匹配块”的行号而匹配块基于上下文拼接的文本段行号偏移量和新增行原始行号对不上再加上重命名文件时新旧行号映射出现错误导致评论落点整体偏移。修复方案是统一坐标系统所有报告类型先经过行号映射表将内部坐标换算成新文件的真实行号对重命名文件不做行级评论只做文件级提示解析器里增加一组单元测试专门固定各类边界情况的行号映射防止后续改动引入回归。行号这类基础问题一旦出错工具的信任度几乎归零。所以我也建议所有要做此类工具的人第一优先级就把“报告行号是否准确”作为验收标准。4.4 LLM 上下文塞爆与“正确废话”接入大模型模块后遇到的第一个技术问题就是某次请求直接返回 token 超限。排查代码后发现当时实现是把整个 MR 涉及的文件全量塞进 prompt一个 3000 行的改动文件加上头注释直接超长。这个问题相对好修按第三章的函数级上下文裁剪思路token 立刻降到可接受范围。更难处理的是“正确废话”问题模型给出的结论语义上完全没错比如“这里建议加一下异常处理”但这种建议没有任何具体指向开发者看完也不知道到底哪里有问题。这类问题本质上是输出约束不够后来我在 prompt 里增加了硬性格式要求不给出具体行号和修改建议的 findings 一律不入报告confidence 输出 low 的直接丢弃。过滤之后模型产出的有效问题数虽然有所下降但每条准确度明显提升开发者的阅读负担反而更小了。顺带一提建议在 prompt 中告诉模型“这是高风险变更区域”这类上下文信息而不是只丢代码片段效果差别很大。4.5 规则没法自助更新改规则比写代码还费劲项目跑顺之后团队里开始有人主动提“能不能加一条规则”。当他们第一次看到要改源码、发版本、重新部署的时候就再也没提过了。这提醒我一个关键事实规则引擎的规则如果不能用配置化方式管理工具的长期可持续性就是零。现在的方案是把规则库存放在仓库里的review-rules/目录所有规则用 YAML 编写工具支持本地热加载。新增规则只需要在review-rules/custom.yml里增加一条规则本地运行ocr validate-rules验证语法和匹配样例提交 MR走正常评审流程合入。这样规则本身也能经过评审规则仓库的变更历史就是团队规范库的演进历史一举多得。5. 从“个人玩具”到“团队默认流程”我拿 open-code-review 做了什么5.1 先用默认规则集跑两周只报告不拦人很多自动化评审工具死在第一步接入当天就拦门禁结果一堆历史问题直接阻塞所有 MR开发者怨声载道工具第二天就被卸载。我采用的是分阶段推进前两周只让工具跑报告不拦任何合并让团队观察报告质量有任何误报立即修规则和配置。这个阶段的重点是建立信任。每次有人反馈误报我都在当天处理并在报告上标注“该问题已忽略”。两周之后团队对报告质量的信任基本建立主动要求在新建的 MR 上拦 error 级问题。信任这个环节不能省一旦团队觉得报告不可信后面所有门禁逻辑都会变成摆设。5.2 门禁从何时开始生效门禁正式生效的时间点我的建议是错误级问题拦截只在新 MR 上启用历史存量 MR 一律不追。工具的职责是防止新问题引入而不是把存量债务一次性算到每个人头上。门禁生效后第一个月团队提交 MR 前会自觉先本地跑一遍工具因为都知道 error 级问题会阻塞合并与其在 CI 上等结果不如本地先跑一轮。这是我认为整个项目最有价值的转折点工具从“被动评审”变成了“主动自检”。这一步的收益不只是在 MR 阶段拦住了问题更重要的是开发者在一开始就养成了自查习惯后续消息里不少问题是开发者在本地就修复掉根本没走到机器人评论那一步。5.3 规则本身的治理规则也要走评审规则库上了 YAML 之后我把规则变更也纳入评审流程。任何团队成员都可以提交规则 MR但必须附一段说明这条规则要解决什么问题、误报风险如何控制、示例代码验证结果如何。这样规则库不会因为某个人临时加一条拍脑袋规则而失控。同时我建立了简单的命中数据汇总流程每周统计各规则命中率和误报率低于阈值或长期零命中的规则会被标记过期自动下线。这让规则库保持“实用主义”而不是越积越臃肿。规则库和代码库一样需要维护不加治理的规则库最后只会变成一个让人麻木的噪音源。5.4 落地后的一些可观察变化这个阶段我观察到的变化主要有几个安全类问题在 MR 阶段的漏出率明显下降评审者的注意力从“找低级错误”转移到“讨论架构和边界条件”新同事入职后不需要再记“哪些东西不能碰”只要按照工具提示修改即可。基于那次实践open-code-review 从一个个人兴趣项目变成了团队日常开发环节里默认存在的一环。当然这个变化不是工具本身带来的而是把规则沉淀成流程、把流程交给自动化之后自然产生的。6. 给也想做代码评审工具的人什么时候该造轮子什么时候不该6.1 什么时候别自己造如果你只是想解决“代码里有没有调试日志残留”这一类零散问题直接用现有 lint 工具配合少量自定义配置就够了完全没必要做完整评审工具。维护一个自定义工具的成本是持续性的diff 格式变化、新语言支持、规则维护、大模型接口变化每一项都是长期投入。如果你所在团队没有强烈的定制需求也没有人能长期维护这个工具我劝你先用现成方案把时间花在代码本身更值。6.2 什么时候值得自己做反过来如果你有下面这类需求自己做就是合理的团队规范非常特殊外部工具无法表达你有数据隐私约束代码不能送往外部服务需要本地可控方案你想深度集成到现有开发流程让评审报告与 MR 评论、编辑器提示、CI 门禁全部打通或者你想通过做这件事系统性理解代码评审与自动化检查的边界。开放源码的设计本身就是对这种需求的回应规则、配置、接入方式全部可以改不必迁就固定行为。如果在实际使用中遇到某个常规工具覆盖不到的评审场景扩展一条规则或接一个本地模型服务就行这也是 open-code-review 存在的意义。6.3 如果重写一遍我会怎么做基于目前积累的经验如果重写一遍我会做几个调整核心解析器改用更底层的编译型语言重新实现把性能余量做大规则引擎增加基于轻量 AST 的可编程扩展点而不只依赖正则模式匹配报告层引入问题去重与自动分级把“同一个根因引发的多个表现”合并成一条。这些都属于锦上添花工具当前在中等规模仓库上的表现已经足够好用剩余瓶颈更多来自规则设计和流程治理而不是代码执行效率。最后分享一点个人体会代码评审工具替代的是“粗筛”不是“判断力”。无论规则引擎还是大模型辅助它们能帮你扫掉重复性问题和低级错误但评审里最有价值的那部分——模块边界是否合理、接口语义是否一致、后续维护成本是否可控——依然需要人去看、去讨论、去拍板。open-code-review 真正改变的不是评审这件事本身而是把人的注意力和时间从“找茬”里解放出来投向真正需要判断力的地方。