open-code-review：构建可定制的自动化代码评审工作流

做code review这件事，每个团队都有自己的痛点：有人觉得流程太重，有人觉得平台自带的功能不够细，有人担心代码评审流于形式。open-code-review不是一个独立的商业软件，而是一套以开放工具链为核心、可自托管、可定制的代码评审工作流。它解决的核心问题是：当你在代码评审中不满足于平台默认的"人工点按钮批准"，想让机器自动做第一轮筛查、让规则库逐步沉淀、让评审数据不被单一平台绑架时，该怎么搭一套属于自己的评审体系。

这套方案特别适合三类人：一是想给团队搭建自动化代码评审流水线的技术负责人；二是受够了平台内置检查能力太弱、想自建一套可扩展规则库的开发者；三是想在自己电脑上本地跑通、零成本验证"机器帮你检查代码"这件事的个人开发者。下面我会从设计思路、工具选型、实际配置到踩坑记录，完整讲一遍。

1. 整体设计与思路拆解：为什么选择"开放"的评审方式

先说结论：大多数团队觉得代码评审难推，不是成员懒，而是工具和流程没打通。代码评审要解决的是"在代码合入主干之前，把问题暴露出来"，而问题往往分为四类：

open-code-review的思路，是把前两类问题交给自动化工具，把第三类问题交给专门的规则扫描，把第四类问题留给人工聚焦。要实现这个分工，就得让整个评审流程具备三个特点：规则开放、数据开放、流程开放。

1.1 为什么不能完全依赖平台自带的评审功能

GitHub、GitLab这类平台都自带code review能力，评审者可以在PR/MR页面逐行评论，体验很好。但用久了你就会发现几个尴尬：平台自带的"机器人检查"要么绑死自家生态，要么只能在很窄的范围内做静态检查；规则不透明，出了误报你想改都不知道去哪改；数据都沉淀在商业平台内部，诊断报告、历史趋势很难导出；一旦团队切换到另一个协作平台，整套评审资产基本作废。

开放方案的好处是规则全部写在仓库里、用文本文件维护，换平台不换规则；检查脚本全部自托管，数据导出和二次分析不受限制；可以自由接入任何语言、任何lint工具、任何模型API。

1.2 "开放"不等于"重造轮子"

很多人一听自建流程就头大，觉得是不是要从零写一个评审系统。其实完全不用。open-code-review的核心哲学是:组合现有成熟工具，用最小的胶水代码把它们串起来。我在实际项目中使用的核心组合是：

• CI平台：GitHub Actions/自建GitLab Runner，负责触发和调度
• 静态检查工具：按语言选择，比如前端用ESLint、Java用SpotBugs、Go用golangci-lint
• 评审评论机器人：reviewdog，负责把检查结果以评论形式回写到PR/MR页面
• 规则库：代码仓库里的配置文件，随项目版本管理
• 可选：自托管的大模型接口，做智能审阅

这个组合里没有一个是新写的。你需要做的只是：写好配置、制定规则、设计触发条件。整个搭建时间，我在内网环境一次性做完大概花了一个下午。

2. 核心细节解析与实操要点：搭建一套可落地的review工具体系

这一节讲的是实操层面最核心的东西——具体怎么选工具、怎么设计规则、怎么把检查结果反馈到评审流程里。我会拆分成三个子主题来讲。

2.1 工具选型：按团队技术栈选静态检查工具

静态检查工具的选择标准，不是"越强大越好"，而是"团队现有技术栈里大家已经在用、误报率可控"的工具。以一个典型的Web前后端项目为例：

这里有个选择建议：别一上来就追求工具全家桶。先只接团队最痛的一个检查维度。比如前端团队天天因为未使用变量和隐式类型转换吵架，就先接ESLint的这两条规则。等流程跑顺了，再逐步加规则、加工具。我见过不少团队刚开始就上了十几个检查工具，结果CI时间直接翻倍，每天被一堆误报淹没，最后大家干脆不看评论，整个流程又回到了原点。

2.2 为什么用reviewdog做胶水层

reviewdog这个工具，核心功能是"把任意命令的输出结果，翻译成代码评审评论"。它做的事情很简单：读取你指定命令的stdout输出，按你设置的格式解析出文件、行号、错误级别、错误信息，然后把这些信息通过GitHub/GitLab的API写回到对应的代码行下面。

用reviewdog而不是自己写脚本的好处有四点：

1. 格式标准化：它内置了几十种linter的输出格式解析器，ESLint的JSON输出、SpotBugs的XML输出都能直接识别。
2. 增量分析：它默认只评论本次diff中新增或修改的行，不会把整个项目的老问题全部刷到你面前。
3. 级别控制：支持info/warning/error三级，误报多的规则先降级成info，让团队逐步适应。
4. runner机制：支持以二进制或容器方式运行，和GitHub Action、GitLab CI都能无缝集成。

2.3 规则库设计：慢慢沉淀，不要一步到位

规则库是这套体系里最有积累价值的部分。我的建议是：在设计规则库之前，先整理一份团队的"代码红线清单"。比如：

• 禁止在代码里硬编码数据库连接串、API密钥
• 禁止使用eval（前端安全红线）
• 新增依赖必须声明版本号
• 删除代码时必须同步删除无用import
• 禁止吞掉异常（catch了不处理也不往外抛）

把红线清单转成具体的ESLint规则或自研检查脚本。以"禁止硬编码密钥"为例，可以在CI阶段用一个简单的正则扫描脚本，搜出password = "xxx"这类模式。刚开始规则越少越好，只保留"违规了必然要改"的规则。规则多了，维护成本高，误报率也高。

3. 实操过程与核心环节实现：从零搭出一套CI接入配置

这一节直接给可以复制使用的配置。我会用一个GitHub仓库来示范，整个项目里只需要新增一个workflow文件和一个reviewdog配置文件。

3.1 最小可运行的Action配置

在仓库的.github/workflows/code-review.yml中写：

name: open-code-review on: pull_request: types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 cache: 'npm' - run: npm ci - uses: reviewdog/action-eslint@v1 with: github_token: ${{ secrets.GITHUB_TOKEN }} reporter: github-pr-review level: warning filter_mode: diff_context fail_on_error: false

这个配置的含义是：当有PR被打开、更新或重开时，自动执行ESLint检查，并把结果以warning级别评论到PR上。有几个关键参数需要注意：

• reporter: github-pr-review：表示以评审评论的形式逐行汇报。
• filter_mode: diff_context：只评论本次diff变动的行及其上下文，避免把老代码的问题都抛出来。
• fail_on_error: false：检查到error不阻断CI。这是有意设置的——早期阶段机器评审应该是"辅助"而不是"门禁"，等团队信任度上来了再改成true。

如果用的是自建GitLab，思路完全一样，只是步骤变成：注册一个Runner，在.gitlab-ci.yml里写reviewdog相关的stage，runner仍然可以调用本地的eslint、spotbugs等工具。

3.2 本地先复现一遍，别直接上CI

我强烈建议所有规则在本地复现通过后再上CI。有一个非常实用的reviewdog本地模式：

reviewdog -f=eslint -reporter=local < eslint_output.json

这个命令的作用是：把你刚刚手动跑ESLint生成的JSON输出，用reviewdog的解析器读一遍，然后在终端里直接显示问题清单。通过这种方式，你可以一边调整规则配置一边看效果，等到输出内容稳定、误报可控之后，再推到分支上触发CI。

我在实际搭建时还会做一件事：在本地准备好一个"测试PR"，也就是一个特意包含几类常见问题（比如未使用变量、危险API调用、密钥硬编码）的改动分支。用它来验证整个reviewdog链路是否通畅。这样就不用每次调整配置都去开一个新的PR试错。这个小技巧能省下大量来回push和等待CI的时间。

3.3 自定义检查脚本的接入

不是所有问题都靠现成linter解决。比如"不允许新增接口不写注释"或"不允许直接修改数据库结构文件"这类团队特定规则，就需要自定义脚本。reviewdog支持一个通用的解析器，叫errorformat，可以把任何命令行输出格式化成评论。

我维护过一个check_custom_rules.sh脚本，里面写了几个团队红线检查。脚本输出格式统一成：

path/to/file.py:15: [error] 新增函数缺少docstring

然后在CI里这样接入：

./check_custom_rules.sh | reviewdog -f=efm -reporter=github-pr-review -name="custom-rules"

-f=efm就是让reviewdog用自定义errorformat去解析输入。加上-name参数后，PR页面上会独立显示一个"custom-rules"来源的检查组。这样可以区分哪些问题是ESLint报的、哪些是团队自定义规则报的，评审者能快速分清优先级。

4. 给评审流程加上AI审阅层：更多的眼睛帮你把关

看完静态检查，回到那个绕不开的话题：除了linter和自定义规则，能不能让AI做一轮智能review？在open-code-review的框架里，这完全可行，而且可以做得比想象中轻量。不过要注意，这里说的不是把整个PR丢给AI，而是把diff的信息有策略地喂给模型，让模型只负责它能胜任的那部分判断。

4.1 AI在code review里到底能干哪些活

我实测下来，大模型审代码最可靠的场景集中在：找明显的逻辑错误或原子性问题（比如某个全局变量在异步回调里被意外修改）、检查重复代码和可以抽象的部分（比如两个文件里几乎一样的复制粘贴段落）、提醒遗漏的边界条件（比如数组为空、字符串有空格、数值为负的情况）以及解释一段复杂新代码的潜在风险（给评审者提供上下文线索）。

至于它不擅长的地方，也一定要说清楚：依赖外部服务的调用（比如某个框架的运行时行为）它经常瞎猜；风格争论（比如该用函数式还是面向对象）它往往给出两边都不得罪的回答，没实际帮助；数量多的小逻辑分支它容易漏，需要结合静态检查规则查。

所以正确姿态是：把AI当成"补充的审阅者"而不是"准确的审核者"。它更擅长快速标出可疑代码段，让上级评审者重点关注，而不是给出最终裁决意见。

4.2 接入大模型的思路与API密钥管理

接入方式很简单：在CI的某个步骤中，把本次PR的diff数据取出来，按文件分组，调用模型接口，让模型输出结构化意见。如果你有条件使用自托管方案（比如自建的内网推理服务），数据就不会出内网，经济性也更好。

实际操作时，我建议把diff按"文件维度"分组，原因是大模型的上下文窗口有限。一个PR通常涉及十几个文件，全塞进去既浪费token又容易让模型"看漏"。按文件分组，每次请求只给一个文件的有效变更内容，再按照文件类型（如ts、java、py）定制提示词模板。

AI接入时的密钥管理是一个必须强调的点：绝不把模型API密钥硬编码到代码里，要放在CI平台的secrets中，在workflow里通过环境变量引用。同时，给AI审阅这个步骤加上最大调用次数和超时时间限制，避免一次异常的耗时拖慢整个评审流程。

4.3 用"去噪规则"过滤AI的废话

AI审阅如果不加干预，很快会变成新的噪音来源。我的策略是：定义一个ai-review.py脚本，让模型输出严格遵循的JSON结构，脚本再去过滤低价值评论。比如：

{ "file": "src/order.ts", "line": 88, "risk": "high", "category": "null-safety", "summary": "这个取值路径可能空指针", "suggestion": "先判断是否存在再使用" }

脚本拿到输出后，可以做几件事：过滤risk为low的评论，这类评论大概率是"这行代码可以写得更优雅"之类的含糊意见；过滤没有具体suggestion的评论，没有修复建议的评论价值很低；过滤重复评论，同一个文件的相同问题只留一条；按file和category去重，避免同一个逻辑问题翻来覆去报多遍。

过滤之后，AI评论只留下真正值得人工聚焦的内容。加上第3.1节的静态检查评论，PR页面上会形成三层结构：由lint工具负责格式和低级错误、由自定义规则负责团队红线、由AI负责逻辑层面的可疑点，人工评审只需要聚焦最高层面的架构问题和业务判断。

5. 一次完整review的实操记录：从push到收到第一条机器评论

理论说完了，我用一次真实的开发流程来串一下，这样你能更清晰地看到整个体系跑起来的样子。假设我现在在一个Web前端仓库里，新增了一个订单列表页面。

5.1 从push到机器人自动评论

我基于main分支创建了feat/order-list分支，写了几百行代码，包括一个orderService.ts、一个orderList.vue，修改了apiClient.ts。提交并push后，我按照团队习惯立即创建了一个PR，并且故意保留了一个"未使用变量"和一个"某个路径忘记判空"的问题。

push后大概14秒，GitHub Actions被触发。工作流程分三个阶段运行：先跑npm ci安装依赖，这是最耗时的一步，之后是npm run lint导出ESLint结果，最后是reviewdog解析并写入PR评论。整个流水线跑完大约2分钟。这时候打开PR页面，能看到reviewdog已经在那两行问题代码下面生成了评论，标注来源是eslint，级别warning，还附带了规则的说明链接。

在同一轮PR里，我也触发了AI审阅步骤。我给自己设定的阈值是"只保留high风险评论"，所以AI模型只上报了一条关于"这个接口响应可能为空数组，但你直接取了第0个元素"的评论。这条评论确实指到了点子上，因为这是我故意埋进去的隐患。

5.2 处理误报与规则迭代

收到评论之后，我以为可以提交修复了，结果发现ESLint还标了一条"误报"：某个import看起来是未使用的，但实际上它是为了副作用而引入的（比如引入一个样式文件入口）。这类情况在生产中经常发生，处理方式不是删除代码，而是修改规则配置，在.eslintrc.js里把这个文件路径加入ignorePatterns，并加一行注释说明原因。

在这里分享一个非常实用的调整思路：机器评论不要一上来就fail CI。刚开始的一个月，把机器检查全部设置成warning、fail_on_error: false，让团队成员先熟悉和适应这套评论机制。期间认真记录哪些规则价值最高、哪些规则全是误报。一个月后，把高价值规则提升为error，把误报率高的规则降级为info或直接关掉，再把真正的红线规则设为fail_on_error: true。经过两个月的沉淀，团队规则库会稳定得很舒服。

6. 常见问题与排查速查表：实际运行中遇到的难题

工具的坑，网上文档很少写全。我把自己踩过的一些问题整理成一张速查表，并解释排查思路，方便你直接对照。

6.1 路径类报错的第一排查方向

路径报错是最常见的，也是最容易让人迷惑的。实际上这类问题的排查顺序只有一个：先看日志里实际执行命令时的工作目录在哪里，再确认目标文件相对于该目录的路径。我在自建Runner上遇到过requirements.txt找不到的情况，排查后发现是Runner执行器配置的builds_dir和clone目录不一致，导致脚本在错误的目录下执行。GitHub Action里通常是working-directory没配好，CI日志里会明确打印出当前路径。

6.2 依赖库缺失与实际运行环境的对应

在CI环境里遇到库缺失的报错，根因往往是运行镜像太精简。libmysqlclient.so.18这类报错在跑数据库相关的静态检查或测试时很常见。别慌，装依赖就行。不过要提醒一点：这类问题最好一次性写进CI的镜像构建文件里，而不是在workflow里临时apt-get install。临时安装会导致每次流水线都重复下载依赖，CI时间白白增加几分钟。我自己在写Dockerfile时就一次性把所有运行库的依赖都写进去了，这是省时间的技巧。

6.3 误报与规则调优的长期维护

机器评论跑了一段时间后，最大的问题不是报错，而是误报率。误报率一高，团队成员就会开始无视所有评论，整个流程形同虚设。要控制误报，可以让机器评论按规则来源分组显示（reviewdog的-name参数就能实现），这样成员可以在页面上区分"ESLint规则"和"自定义规则"；把不成熟的规则默认降为info先跑一个月，观察实际效果；每条规则都要写清楚"为什么需要这条规则"，写在配置文件的注释里，方便评审者理解；定期（比如每两周一检）统计各类规则的命中率和误报率，规则库里只保留高价值、低误报的规则。

我个人的经验是：规则库的维护，本质上是一个持续做减法的过程。不要怕删规则，删掉一条造成困扰的规则，比新增十条看起来很美的规则更能提升团队对这套流程的信任。

结尾：一个小建议

最后分享一个我自己的体会。open-code-review这套方案最可贵的地方，不是某个工具多好用，而是它让代码评审这件事变得"可积累"了。规则文件放在仓库里，随代码一起演进；CI配置写在工程里，新人加入时自然就会使用；review评论历史沉淀在平台上，随时可以回溯。我从一开始追求"一次搞定所有检查"，到后来慢慢收敛成"少而精的规则+AI辅助审阅"，踩了不少弯路。建议你从一个小项目、一条规则开始，先把链路跑通，再逐步扩展。等这套体系真的跑顺了，你会明显感受到：机器帮你挡住了低级问题，人工评审终于有精力去讨论真正重要的架构和业务逻辑了。