AI+静态规则，开源代码审查工具open-code-review实战

代码审查这件事只要带过团队、或者在一个规范一点的仓库里提交过 PR就一定不陌生。review 本身不难难的是“每轮都要看”难的是“看完之后发现问题已经晚了”更难的是“规则写了但没人执行”。我做了几年研发也带了十几人的小团队最烦的就是 PR 审查阶段里那些低级错误反复出现日志打点打错、空指针没判、异常被吞掉、格式和规范不统一。这些问题不致命但每一条都让 reviewer 烦躁也让提交者尴尬。后来我实在忍不了就用几个晚上写了一个开源小工具起名就叫 open-code-review。它不是要取代人来 review而是把“机器能看的部分”全部接走diff 静态扫描、规则校验、AI 上下文分析、结果评论回帖。人只需要把精力放在架构合理性、业务语义、未来扩展性这些真正需要人判断的事情上。这篇文章就把这个项目的完整思路、技术选型、核心实现、接入过程和踩过的坑全部摊开讲一遍。无论你是想自己搭一套类似的工具还是只想在团队里把 review 效率提上来都值得看完。1. 为什么我会自己写一个代码审查工具1.1 代码审查的痛点与项目起源先说说我自己的真实经历。我们团队维护的是一个微服务项目不算大大概六七个仓库每个仓库每周都有几十个 PR。GitHub 自带的 review 功能够用但问题是 review 质量完全依赖人的状态。忙的时候点击“approve”就过了闲的时候会盯着缩进问题说十分钟。更麻烦的是不同人心里那根“规范线”不在一起有人觉得函数超过 40 行就该拆有人觉得 100 行没问题有人要求每个 PR 必须带测试有人觉得“小改动不用写”。这种状态持续了半年我有一种很深的无力感规则写得越多执行得越差。后来我统计了一下过去三个月的 PR 评论里有超过四成是在说同一个维度的东西——命名、格式、空值判断、日志缺失、异常吞掉。这些东西如果让工具来跑两秒钟就能出一个清单根本不需要人肉去翻 diff。所以 open-code-review 这个项目的最初目标非常朴素把 review 里那些“99% 情况下有标准答案”的问题自动找出来并且给出精确到行号的提示。人的精力是有限的应该留给真正有分歧的问题而不是反复指出“这里应该判空”。1.2 项目目标与适用场景这个工具定位是“PR 审查辅助层”。它干三件事第一读取 PR 的 diff也就是变更内容不做全仓扫描也不关心没有改动的历史代码。这个设计很关键因为 review 的对象就是这次改动把审查范围缩小到 diff结果更聚焦速度也快很多。第二跑规则。规则分为两类一类是静态规则比如禁止 console.log、禁止 TODO 注释、禁止 catch 后空处理另一类是交给 AI 的分析项比如判断这次改动是否可能引入 NPE、是否存在并发隐患、是否缺少必要的日志上下文。第三把结果以评论的方式回写到 PR 页面。每一条都带文件路径、行号、严重级别和建议修改方式reviewer 打开 PR 直接看评论列表就能进入状态不用自己从头到尾翻一遍。适用场景包括中小团队没有专职 QA 也没有架构师逐行把关的场景、开源项目维护者需要快速过滤低质量 PR 的场景、企业内部想统一代码规范又不想靠人工强推的场景。它不适用于什么不适用于那种“业务逻辑极其复杂、需要深入理解产品意图”的深度 review那个仍然需要人来完成。1.3 项目定位不是替换人而是辅助人这一点我在 README 里写在了最前面也在实际使用中反复跟团队强调工具不能替你 review但能帮你把“不会错的部分”先干完。打一个比方。医生看病也要先做血常规、拍片子机器先把数据全部列出来医生再结合临床经验做判断。你不能说血常规仪能代替医生但它确实让医生省下大量重复劳动。open-code-review 就是这个“血常规仪”。它输出的是线索和疑点不是裁决书。每一句话后面都带根据reviewer 可以同意、忽略或者追加追问压力完全不在这边。我在设计上也是这么做的所有通过静态规则命中的问题默认级别是 warning只有极少数配置成 errorAI 给出的分析意见全部以“建议确认”的口吻输出而不是“这里必错”。这个微妙的设计差异决定了团队接受度——如果机器天天用斩钉截铁的语气说“你写错了”一周之后所有人都会烦它。2. open-code-review 的整体设计与技术选型2.1 架构思路AI 与静态规则双通道这个项目最核心的架构决策是把“静态规则”和“AI 分析”两条通道拆开做成两个独立的引擎再在最上层合成一份报告。为什么要拆因为它们的出错方式和成本结构完全不同。静态规则是确定性的命中就是命中没命中就是没命中跑一次只需要几十毫秒随时可以本地执行。而 AI 分析是非确定性的同样的 diff 模型可能给出不同意见单次要消耗数秒甚至更久还需要消耗 token 费用。如果把两者混在一起静态规则部分的即时性会被 AI 拖累AI 部分的不确定性又会污染规则的可解释性。所以实际流程是分两段的。第一段先用静态规则做本地快速检查能直接确定的问题直接出报告。第二段再把 diff 和规则结果一起打包给大模型让 AI 基于规则命中的位置做上下文分析。这样既保证了响应速度又让 AI 能理解“为什么这里报了一个空指针风险”。整个工具的调用链就是这样拿到 PR 或本地 diff先解析成结构化数据提取文件路径、变更行号、上下文片段然后送进规则引擎做模式匹配再把规则结果和 diff 片段拼接成 prompt调用大模型接口最后把两类结果合并成统一格式通过 CLI 输出到终端或者通过 API 回传到 GitHub/GitLab。2.2 技术选型与关键依赖我最终选了 Python 作为主语言。原因很实际团队里后端大多是 Python 背景后续让同事改规则、加检查项的门槛最低Python 处理文本和调用 HTTP 接口也足够顺手生态里有现成的 argparse、PyYAML、requests不需要引入重型框架。CLI 部分用了 argparse 做参数解析配置文件用 YAML 格式规则引擎用的是“正则 AST”混合方式。这里必须说明纯正则适合简单检查比如“是否包含 TODO”但一旦要理解代码结构比如“try 块里有没有 return”正则就无能为力了。所以我在设计规则时把检查项分成两种类型text 类型走正则ast 类型走语法树解析。这个分类在后面实现时非常省事。调用大模型的部分我封装了一个统一的 LLM client 接口。底层默认走 OpenAI 兼容协议但通过环境变量替换 base_url 和 model 可以切换到其他服务。这里不绑定任何特定商业服务只是提供了接口约定你完全可以塞一个自己部署的模型进去。另外必须提到的是 git 交互。open-code-review 需要拿到两份代码变更前和变更后。实现方式是基于 git diff 获取文件路径和行号映射再用 git show 取对应文件内容。这样即使 PR 已经推送到远端本地也能通过 fetch 拿到完整对比数据。2.3 从代码 diff 出发的审查流程设计整个流程的设计逻辑可以归纳成“三句话”范围来自 diff规则来自配置结论来自硬规则加 AI 的组合。第一步是解析 diff。Git 的 diff 格式看起来简单实际处理起来挺多细节。比如一个文件里有多段 hunk每段 hunk 的新旧行号对不上文件重命名时 diff 头信息不同二进制文件根本不适合做文本分析。我在这一层花的时间比预期多很多最后实现了一个尽量通用的 diff parser专门处理新增行和删除行的行号映射。第二步是过滤掉无关文件。锁文件、生成文件、vendor 目录、构建产物全部跳过这个过滤规则也开放配置。你在配置里写一句 ignore_patterns就能把 node_modules、dist、build、*.lock 之类的全部排除。第三步才是正式审查。静态规则引擎按规则优先级逐个跑把命中结果写到内存里AI 引擎收集 diff 片段和规则命中信息拼成 prompt 后调用模型。两步之间是串行关系因为 AI 需要知道规则命中了哪些位置才能把分析往关键处收拢。如果并行执行AI 就完全失去上下文会给出很多泛泛的建议。最后生成报告。报告有三种输出格式human 可读的终端文本、JSON 结构化结果、GitHub Actions 的 annotations 格式。采用多格式输出不是为了炫技是真的需要——本地调试时看 human 文本集成到 CI 时用 JSON 做接口转发在 GitHub 上展示时用 annotations 直接标红。一个数据处理流程从输入到输出保持全链路结构化后面无论接什么展示端都不需要改核心逻辑。3. 核心功能实现规则配置、AI 反馈与结果过滤3.1 分层检查硬规则在本机拦截AI 负责读上下文open-code-review 的分层逻辑和很多 lint 工具很像但比 lint 更进一步。lint 只管代码写得好不好看、命名规范不规范而 open-code-review 把“好不好看”的问题留在本地钩子里解决把“会不会出事”的问题交给 AI 做上下文判断。分层之后效果很明显。本地运行的 pre-commit 钩子用来拦截“必错项”比如不小心提交了 debug 日志、把密码密钥写死在代码里、留下未完成的 TODO。这些问题根本不配到 PR 阶段在本地提交时就不该通过。AI 则在 CI 阶段做更深一层的分析比如这段新增代码是不是线程不安全的、这个异常处理是不是会吞掉关键错误。两者一个负责拦截、一个负责推理职责不重叠。这里有一个很值得说的点硬规则必须是“确定性”的AI 必须是“建议性”的。如果你把 AI 的输出当成硬规则来卡门禁那团队迟早会疯掉——模型今天说这个写法没问题明天又说有问题你说开发听还是不听我最终实现的策略是硬规则命中直接标记 error如果配置了 fail_on_errorCI 会直接失败AI 意见只是以 review comment 的形式出现供人参考。3.2 自定义规则配置一份 YAML 管住所有检查项规则引擎设计了一个三层模型ruleset 对应一个规则集合rule 是一条具体规则action 是该规则命中后的处理方式。配置文件长这样rulesets: - name: python_security rules: - id: no_eval type: ast message: 禁止使用 eval 执行动态代码 level: error when: call_function: eval - id: no_assert_for_exception type: ast message: 测试中不要使用 assert 来处理预期异常 level: warning - id: no_todo type: text pattern: TODO\\s*: message: 发现遗留 TODO记得补充 issue 链接 level: warning这份配置文件最终会成为团队代码规范的可执行版本。之前规范写在 wiki 里没人看现在规范写在 YAML 里每次提交都会被执行。这是我认为这个项目最有价值的地方——它把“团队共识”变成了“机器约束”。实现原理上text 类型就是正则匹配。ast 类型则需要解析代码字段然后遍历语法树寻找特定节点。比如 checking 一个函数或者一个异常类型用 Python 的 ast 模块写起来并不复杂示例代码如下import ast class EvalCallFinder(ast.NodeVisitor): def __init__(self): self.found [] def visit_Call(self, node): if isinstance(node.func, ast.Name) and node.func.id eval: self.found.append(node.lineno) self.generic_visit(node) tree ast.parse(open(target.py, encodingutf-8).read()) finder EvalCallFinder() finder.visit(tree) print(finder.found)这个代码段是整个 AST 规则引擎的最小原型。你只要把不同检查项定义成不同的 NodeVisitor就能无限扩展新的规则。建议读者在自己项目里先用 text 类型解决 80% 的问题剩下 20% 再逐步用 ast 方式补。3.3 AI 反馈设计把问题钉在代码行上而不是丢给开发者一段总结我在早期版本里犯过一个错误让 AI 读完 diff 后输出一段“总体审查意见”。结果它确实输出得很流畅但开发者看了之后完全不知道怎么动。像“建议增强日志覆盖”这种话等于没说。后来我把输出格式改成了“基于代码行锚点的评论”效果立刻不一样了。具体做法是AI 返回的每一项结果必须包含 file_path、line、severity、summary 四个字段。然后系统根据这些字段把意见映射回 diff 对应的行号再通过 GitHub API 在该文件对应行上直接发评论。这样开发者收到通知后看到的第一眼就是“哪个文件哪一行有问题”直接跳过去修改不需要再猜。prompt 里我给了模型很明确的指令只分析 diff 中新增的行不要评价历史代码每条意见都必须引用具体的代码片段如果没有把握请不要输出意见。后面这半句非常关键能大幅降低 AI 的胡说八道率。模型在不确定的时候容易硬编理由用了这条约束之后大量水意见都被挡掉了。3.4 上下文压缩把“相关文件”而不是“整个仓库”喂给模型这是我在 token 控制上最纠结的部分。你不可能把整个仓库塞给大模型成本太高效果也不好。但只把 diff 一行行贴过去也不行因为模型不知道这个函数在项目里被谁调用了不知道这个模块的整体结构。最后采用的方案是“diff 加关联文件片段”。具体流程是先根据 diff 中变更的符号函数名、类名、变量名在仓库里做一次轻量索引搜索把相关的定义文件、调用点抓出来然后按相关性截取每个文件的一部分片段和 diff 一起拼进 prompt。比如你改了一个叫create_order的方法工具会自动去找这个方法定义在哪、被哪些地方调用把关键调试信息抓进上下文。模型拿到这些引用关系后才能正确判断“这个改动会不会影响其他模块”。这个方案在大多数场景下能把单次 AI 分析消耗控制在几千 token 内成本很低。你可以在配置里限制每个文件的最大片段长度和参与分析的文件数量设计上保留了充分的控制权。4. 接入与实操从本机到 CI 的完整落地4.1 最小可用版本地命令跑通把工具接入团队之前建议先在自己电脑上跑通最小可用版。安装很简单直接用 pip 装pip install open-code-review装好后你可以直接对当前分支跑一次open-code-review --diff origin/main...HEAD --config .review.yml --output human这里--diff参数指定 diff 范围--config指定规则配置--output指定输出格式。如果一切正常你会在终端看到类似下面的输出file: src/user_service.py line 42 [error] assert 不应用于处理预期异常 line 87 [warning] 建议确认该函数在并发场景下可能有竞态条件第一次跑的时候90% 的人会发现原来自己代码里藏着这么多低级问题。有这种感觉很正常——不是代码变差了而是之前没有机器帮你做地毯式检查。在本地跑通之后建议先拿几个历史 PR 试一试看看工具的误报率如何。我当时的经验是规则命中率很高但 AI 意见的准确率一般六到七成。这个准确率已经足够有参考价值了因为哪怕五条意见里只有两条是重要的也省了 reviewer 不少时间。4.2 接入 Git 工作流pre-push 钩子与 GitHub Action本地命令跑通只是第一步真正发挥作用必须融入到 Git 工作流里。我在项目里提供了两种集成方式你可以根据团队情况选择也可以两种同时用。第一种是 pre-push 钩子。它的作用是在git push之前自动执行一次规则检查只跑静态规则引擎不调用 AI。这样大部分低级问题在本地就被拦截下来了根本不会进入 PR。配置方式如下open-code-review install-hook这个命令会在.git/hooks/pre-push里写入脚本之后每次 push 之前都会先跑一遍检查。如果不通过push 会被中断。当然你也可以配置成只警告不拦截。第二种是 GitHub Action。当 PR 创建或更新时在 CI 上跑一次完整检查包括静态规则和 AI 分析然后把结果以评论方式回帖。我的 action 配置示例name: code-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install open-code-review - env: LLM_API_KEY: ${{ secrets.LLM_API_KEY }} LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }} LLM_MODEL: ${{ secrets.LLM_MODEL }} run: | open-code-review \ --diff origin/${{ github.event.pull_request.base.ref }}...${{ github.event.pull_request.head.sha }} \ --config .review.yml \ --output github \ --comment-on-pr这里有个非常容易踩的坑actions/checkout默认只拉取单次提交的代码如果不加fetch-depth: 0你拿不到完整的 git 历史origin/main...HEAD这种 diff 就根本算不出来。我第一次配置 action 时就挂在这个问题上日志报“fatal: bad revision”排查了半天才发现是 checkout 深度不够。4.3 Prompt 设计与参数调优如果要把 AI 审查效果调到最好prompt 值得花时间慢慢打磨。我当前使用的 prompt 结构大致分成四块定义角色、指定输入格式、限定输出格式、明确禁止行为。角色定义写得很短你是一名资深代码审查专家。但接下来会明确强调“不要赞美代码”“不要输出泛泛的建议”“只关注具体问题”。输入格式固定如下diff {diff} /diff context {related_snippets} /context rules_hit {static_rule_results} /rules_hit输出格式我强制要求 JSON方便程序解析。每一条意见都必须包含 file_path、line、severity、summary、suggestion 五个字段。所有意见都必须基于 diff 中新增的行历史代码问题一句话带过或者不提。禁止行为里写得最详细禁止输出类似“代码整体质量不错”的综合评价禁止在没有足够证据时给出结论禁止对未变更的行提出修改建议如果上下文不足宁可说“无法确定”也不要硬编。参数调优方面最核心的是 temperature我建议调到 0.1 到 0.2 之间。这个参数控制模型输出的随机性。作为代码审查场景你需要的是稳定、可复现的判断而不是每次审查结果都随机的天马行空。max_tokens 建议设为 2000 左右既能覆盖大多数 PR 的结果又不会因为太长而增加成本和延迟。4.4 团队落地时的权限与流程设计工具本身做出来了真正难的是让团队接受。我的建议是不要一开始就全量强制启用分三步走。第一步是“演示模式”。在项目里接好 action但所有结果只以评论形式出现不阻塞合并。团队跑两周让大家先感受一下这个工具都在说什么对准确率有一个直观认识。第二步是“建议模式”。根据前两周结果调整规则配置把误报率高的规则关掉把确实有价值的规则保留。然后告诉团队这几条规则是大家公认的从现在开始会标为 warning建议修改但暂时不强制。第三步才是“门禁模式”。只把极少数确定性最高的规则设为 error比如密钥泄漏、禁止函数调用、异常吞掉。其他内容继续以建议形式存在。我在实际团队里走到第二步就停住了。因为真正让代码质量提升的不是强制的门禁而是大家已经养成了“提交之前先看工具报告”的习惯。这个习惯比任何强制规则都有效。5. 常见问题与排查技巧实录这个模块整理一下我在开发和使用 open-code-review 过程中遇到的典型问题和解决办法按问题现象排列成一个速查表。问题现象根本原因解决办法GitHub Action 报 fatal: bad revisioncheckout 深度不够拉不到历史提交workflow 中设置 fetch-depth: 0AI 经常漏报问题prompt 缺少对具体问题的约束在 prompt 中强制要求引用代码行原文输出格式限定 JSON schema规则引擎匹配不到预期内容正则写错边界或 AST 类型判断错误先用 text 规则调试确认有效后再升级为 AST 规则报告里行号错位合并冲突之后 diff 行号偏移提醒开发者在跑检查之前先 rebase 并解决冲突成本偏高每个 PR 都跑多次 AI且输入内容过大缩小 diff 范围启用上下文压缩只在同步事件触发时跑团队不接受 AI 意见意见语气过于绝对缺少证据链把 prompt 中“必须”改成“建议确认”每条意见附上规则命中和上下文多语言项目无法统一规则不同语言需要不同的 AST 解析器规则引擎设计为按文件扩展名选择 parser先支持最常用的几种语言规则误伤测试代码没有区分生产代码和测试代码配置中增加 path_patterns 过滤段对 _test.py 或 tests/ 目录使用独立规则集5.1 多语言支持的现实问题如果你所在团队是一个多语言技术栈这里有一个更现实的建议不要指望一个工具覆盖所有语言的高级语义。我在做的过程中发现静态规则层面 text 正则是不区分语言的所以像禁止 TODO、禁止 console.log、禁止 debugger 这类规则可以全局生效。但 AST 类型规则严重依赖具体语言的语法结构每种语言都要写一套独立的 NodeVisitor工作量不小。最实际的做法是先用 text 规则覆盖所有语言通用问题再分别为主力语言比如 Python、Java、TypeScript写 AST 规则。次要语言仅仅保留通用规则不追求深度。这个取舍即使你做到第六七八个版本也应该坚持。5.2 关于延迟的优化经验还有一个性能问题值得专门说。GitHub Action 初始安装依赖和 clone 代码的时间大概要一分钟规则检查本身很快一般不到五秒。真正耗时的是 AI 调用尤其是 diff 比较大的 PR可能要二十秒到一分钟。如果团队对 PR 检查速度敏感有两个优化手段。第一是把 AI 分析和规则检查拆成两个 job规则检查秒级完成并立即回帖AI 分析异步跑完再追加评论。第二是给 AI 分析设置 diff 行数阈值超过阈值的 PR 自动跳过 AI 分析只做静态规则检查避免超大 PR 拖垮整个 CI。5.3 误报与漏报的平衡技巧误报和漏报是天然矛盾的。规则设置得严误报率上升团队开始骂工具规则设置得松漏报率上升工具变成摆设。这里我的实践心得是静态规则可以继续追求“零误报”因为它是确定性匹配如果你发现某条规则经常命中但开发者都说“这不是问题”果断把它关闭或降级AI 分析则不能追求零误报它的价值在于“提供线索”哪怕十条里有七条无关紧要剩下三条可能是人眼漏掉的隐患。可以在 quarterly review 时复盘规则效果哪条规则被忽略次数最多哪条规则真正拦截过线上事故然后动态调整。6. 把 open-code-review 推广到团队一些软性经验6.1 不要一开始就全量开启这里我非常想说一句因为踩过坑。工具刚开发完时我很兴奋觉得全团队、全仓库都接上代码质量马上就能提升。结果呢第一天就有同事在群里吐槽“这工具是不是疯了我改了俩变量它给我整出一堆意见”还有人不看内容直接给了个 dismiss review。问题的本质不是工具不好用而是我没有给团队适应期。正确的打开方式是先挑一两个活跃度适中、成员对代码质量本身有追求的仓库做试点。跑两周把结果拿给核心成员看让大家提意见集中调整一轮规则然后再推广到更多仓库。这个“由点及面”的路径虽然慢但稳不会让工具在一开始就被打上“不好用”的标签。6.2 让规则可解释、可关闭、可投票一件事情只有当你随时能关掉它的时候你才会真正愿意打开它。这个逻辑在工具推广上特别适用。我设计配置体系时有一个原则每条规则都能单独开关每个级别都能单独调整所有配置都写在一个可见的 YAML 文件里而不是藏在代码深处。当同事说“这条规则没道理”时我直接跟他一起打开 YAML当场改掉而不是说“这是工具的逻辑我回头再看看”。后面我又搞了一个“伪投票机制”任何成员都可以提一个规则变更建议比如“建议把 no_todo 从 warning 调到 error”然后在群里讨论并投票。这样大家会觉得工具是“我们共同维护的规则”而不是“某个人的意志体现”。这个心理变化非常微妙但对接受度影响很大。6.3 实际使用感受在项目开源并实际使用数月之后我观察到一些很有意思的数据。一个中等活跃度的仓库之前每个 PR 平均需要 reviewer 花二十分钟到半小时做逐行检查现在大概只需要十分钟看机器给出的评论再把剩余时间放在业务逻辑讨论上。低级问题基本不会再出现在 review 阶段因为本地钩子已经拦掉了一部分没有被拦截的也会被 CI 上的分析抓住。最让我惊喜的不是技术实现本身而是团队的行为发生了变化。以前有同事提交代码前根本不自己看 diff反正有 review 兜底现在他们知道提交时会有一个工具唰唰地扫描提交前会自己先看一遍、把明显问题清理掉。这个变化不是规则强制的是工具的“监督感”自然带来的。工具本身不复杂复杂的是把它嵌入到团队的日常协作节奏里。只要工具能稳定地提供高价值反馈并且让每个人都知道它不会乱发脾气它就会慢慢变成团队里一个很可靠的助手。最后补一句实在的AI 类审查工具更新迭代很快设计时一定不要把模型服务商的具体 SDK 写死在代码里。我就是用最简单的 HTTP 接口加环境变量配置完成了所有对接。这样未来无论换哪家模型都只是一行环境变量的改动而不是一次重构。做工具的人永远要给自己留好后路。