open-code-review：让代码评审规则随仓库走，摆脱平台绑定

open-code-review：让代码评审规则随仓库走，摆脱平台绑定

发布时间：2026/10/19 4:33:23
open-code-review：让代码评审规则随仓库走，摆脱平台绑定 如果你在团队里负责代码评审流程大概早就有过这种念头为什么评审一定要被绑定在某个代码托管平台上GitHub 有 Pull Request ReviewGitLab 有 Merge RequestGerrit 有 Change代码仓库一换整个评审习惯、审批规则、机器人提醒全都得跟着重来。我折腾了大半年最后整理了一套叫 open-code-review 的开源小工具集核心思路很简单把评审过程和托管平台解耦让评审规则、执行脚本、报告格式都变成仓库里的一份普通文件任何人 clone 下来就能跑。这篇文章不是讲怎么装一个现成系统而是把我从零搭建这套开放评审方案时踩过的坑、做过的取舍、以及真实落地到团队里的完整过程都写出来适合正在为评审流程不顺手平台绑死规则没法复用发愁的人参考。1. open-code-review 是什么先搞清楚它到底解决什么问题1.1 为什么我最终决定自己维护一套开放的评审工具我最早也是直接用平台自带的评审功能GitHub 的 Review 界面用起来很顺但问题出在这套流程没法搬走。团队后来有几个项目迁到了内部搭建的 Git 服务上评审规则、机器人通知、通过阈值统统要重写一遍再后来接到一个纯离线的项目代码托管在完全隔离的内网 GitLab很多社区插件装不了整个评审只能靠人工在聊天工具里喊。那段时间我反复意识到一件事我们真正需要的不是某个平台的Review 按钮而是一套可以放在任何 Git 仓库里的评审动作。这套动作应该能读 diff、能跑规则、能输出报告、能告诉机器这次变更能不能合入。平台只是承载代码的地方评审本身应该独立存在。open-code-review 就是从这个想法长出来的它用 Bash 和 Python 3 写不依赖任何平台的私有 API只要仓库能用 Git 命令行操作就能跑完整评审。有人可能觉得评审工具而已至于自己造轮子吗。我的回答是如果你只需要在 GitHub 上单人维护项目确实没必要但如果你要维护多个团队、多套代码库并且希望评审口径在 A 项目和 B 项目之间保持一致那轮子至少应该是你能看懂、能改、能带走的。open-code-review 不是重写一个 GitHub它只是把评审这件事拆成了最基础的几块获取变更、执行规则、生成报告、返回状态。每一块都可以独立替换这才是它叫 open 的原因。1.2 这套方案的核心能力与适用人群我在设计 open-code-review 时给自己定了四条硬指标后面所有功能都没离开过这四条仓库内配置每条评审规则都写在仓库的.code-review/目录下跟着分支走规则变更本身也要经过评审杜绝口头约定式的标准。平台无关只依赖git命令和 Python 标准库不调用 GitHub/GitLab 的 REST API理论上任何支持 Git 的服务都能用。分级输出每条问题分 P0阻断合并、P1必须修改、P2应当修改、P3建议调整四个等级报告的最终退出码只由 P0/P1 决定避免小问题无限阻塞。可脚本化所有能力都能通过命令行调用方便接进 CI、Git hooks、定时任务或者聊天机器人。适用人群的话我接触下来主要有三类一是内部平台团队需要给多个项目统一评审标准二是开源维护者希望贡献者在提交 PR 之前先自查一遍减轻维护负担三是已经厌倦了在不同平台之间反复适应评审流程的开发者想要一套换仓库不换习惯的方案。我见过不少团队把评审标准写在一个共享文档里内容很全但没人执行。open-code-review 的做法是让标准变成代码某条规则不过CI 直接红提交者自己就会去看报告。标准从建议变成了约束这种转变带来的效果比任何动员都明显。1.3 open-code-review 不是什么先给期望降降温我也得说清楚它的边界否则大家照着做会踩空。open-code-review 不是人工智能评审员它不会因为这段代码写得不够优雅就给你打回。它擅长处理的是可判定的问题密钥是否被提交、是否缺少测试、是否违反命名规范、是否引入禁止的依赖、diff 是不是大得离谱。至于这个抽象是否合理这里会不会有并发隐患它们会被工具标记为需要人工关注但不会自动判定。它也不是一个 Web 服务。虽然我后面实现了一个可选的serve命令用于生成网页版报告但整个项目的默认输出是 Markdown 文件和纯文本日志。没有数据库没有后台任务没有用户系统。这是刻意做的减法评审工具越简单越容易被放进任何环境。你需要的是一个可以在 CI 里稳定运行的命令行工具而不是一个需要运维的又一个系统。2. 方案选型与整体设计为什么不做又一个 Web 评审系统2.1 先盘点现有方案的痛点在动手写第一行代码之前我把常见的评审方案列了一遍逐个分析了它们的痛点方案优点我没选它的原因GitHub PR Review交互体验好内联评论方便只能用于 GitHub迁移成本高规则很难跨仓库复用GitLab MR Approval与 CI 集成紧密一旦脱离 GitLab 生态就完全失效自建实例时维护成本高Gerrit细粒度 commit 评审历史严谨学习曲线陡界面老旧小型团队接受度低Phabricator支持多平台托管项目活跃度下降重部署复杂度高自研 Web 评审系统完全可控但成本高需要数据库、前端、权限系统这是一个团队的事不是一个人该做的事我从这个表里得到的结论很明确工具本身复杂不是问题问题是复杂度放错了位置。平台原生评审的复杂度放在平台上所以换平台就归零自研 Web 系统的复杂度放在运维上所以我一个人维护不起。那我就把复杂度压到最低放在一份配置 一个脚本里。这样无论代码托管平台怎么换这套复杂度都能跟着仓库走。2.2 核心设计原则宁可少一个功能不让用户多一个依赖写 open-code-review 整个过程中我反复使用的决策准则是不做任何没有这个功能就跑不起来的事。具体影响了很多细节语言选择 Python 3但只使用标准库唯一的外部依赖是git命令而这是一个 Git 仓库环境无论如何都具备的。配置文件用 YAML但我没有引入 PyYAML而是写了一个大约 100 行的极简解析器。虽然不支持 YAML 的全部特性但足够处理我们需要的patterns:、include:这样的结构。这样在任何 Python 3 环境里 clone 下来就能跑不需要pip install。所有规则用 JSON 输出结果再用内置的渲染器转换成 Markdown。JSON 这层中间格式很重要它意味着输出可以被自己写的任意前端消费而不是绑定在某个报告模板上。我知道有人会说Python 标准库写 YAML 解析器太折腾了但在离线内网环境里pip install真不一定好用少一个依赖就是少一个坑。这个项目里我最自豪的不是功能多而是无论把仓库拷到什么机器上只要它有 Git 和 Python 3.8 以上版本就能马上跑起来。2.3 工作流总览一次评审请求从出发到回传用一个实际流程来说明 open-code-review 的运作方式。假设你基于main分支创建了一个功能分支提交了几个 commit 之后打算提交评审开发者在本地运行open-code-review check --base origin/main。脚本调用git merge-base找到origin/main和当前分支的分叉点再git diff拿到变更集。解析.code-review/rules.yml把交叉集合规则 x 变更文件分发到对应的检查器。检查器执行后把结果汇总成 JSON 文件。渲染器把 JSON 转成 Markdown 报告并打印到终端同时给出退出码。CI 或 Git hook 根据退出码决定是否阻止合并。这整条链路里没有平台参与变化的是第 5、6 步的输出目标——你可以把报告追加到 Pull Request 评论里也可以直接发到聊天群还可以只是让终端输出。平台成了纯展示层而评审逻辑牢牢地待在你的仓库里。3. 核心实现从零搭起一套可复用的开源评审工作流3.1 工程目录结构与模块拆解我的仓库结构大概长这样尽量保持一眼能看懂open-code-review/ ├── open_code_review/ │ ├── __init__.py │ ├── cli.py # 命令入口 │ ├── diff.py # 获取并解析 git diff │ ├── config.py # 简化版 YAML 解析 │ ├── rules.py # 规则调度器 │ ├── checks/ │ │ ├── secret.py # 密钥检测 │ │ ├── test_check.py # 测试文件检测 │ │ ├── forbidden.py # 禁止内容检测 │ │ ├── style.py # 风格规则检测 │ │ └── size.py # diff 规模检测 │ ├── report.py # 渲染 Markdown 报告 │ └── model.py # 数据模型 ├── .code-review/ │ └── rules.yml # 默认评审规则示例 ├── bin/ │ └── open-code-review # 可执行入口 ├── tests/ │ └── test_checks.py └── README.md这个结构没有什么新颖之处但它是为容易被理解和修改服务的。每个 check 文件都接收统一的输入——一个变更文件对象、一份规则配置、一个上下文对象——并返回一组Finding对象。新增一条自定义规则本质就是往checks/里加一个文件夹和一份配置不需要改动其他任何代码。3.2 关键配置评审规则文件怎么写规则文件是整个工具的法律文本。我提供了一份默认的.code-review/rules.yml里面每条规则都尽量写成普通人能读懂的句子version: 1 checks: secret: enabled: true severity: P0 patterns: - AKIA[0-9A-Z]{16} # AWS Access Key - -----BEGIN RSA PRIVATE KEY----- - ghp_[0-9A-Za-z]{36} # GitHub Token - (?i)password\\s*[:]\\s*[^\\s\] test_check: enabled: true severity: P1 require_for: - src/** - lib/** exclude: - **/*_test.go - **/test_*.py forbidden: enabled: true severity: P2 terms: - TODO - FIXME - XXX style: enabled: true severity: P3 max_line_length: 120 indent: size: enabled: true severity: P1 max_additions: 400 max_files: 20这里我想重点解释一下severity的作用这是我最初设计时容易想歪的地方。一开始我把所有规则都设成不满足就失败结果团队怨声载道随手写个 TODO 也被 CI 卡住太影响了。后来才改成四级严重度P0 是任何合入都不允许的底线比如密钥泄露P1 是应当修复但在紧急情况下可以申请豁免比如大规模重构导致 diff 超过 400 行P2 是强烈建议但不阻塞P3 纯风格建议。最终退出码只考虑 P0 和 P1这样规则既保住了底线又给人留了余地。3.3 评审指令与钩子公司让 open-code-review 自动跑起来命令行入口是我最先实现的因为一切功能都要通过命令来调用。核心就四条open-code-review init # 生成默认规则文件到当前仓库 open-code-review check --base origin/main # 对比目标分支跑评审 open-code-review report --format markdown # 读取 JSON 输出报告 open-code-review serve --port 8000 # 启动静态报告服务可选init是我在落地时才发现非常必要的命令。一开始我让大家手写rules.yml结果每个人写的格式都不一样后来干脆做了一个init直接把默认规则灌进去用户再根据自己的项目修改。这个操作极大地降低了启动成本。真正让 open-code-review 跑起来的其实是 Git 钩子。我在bin/目录里附了一个pre-push钩子示例#!/usr/bin/env bash # 放在 .git/hooks/pre-push 下或者通过 open-code-review init --install-hook 自动安装 set -euo pipefail current_branch$(git symbolic-ref --short HEAD) if [[ $current_branch main ]]; then exit 0 fi echo 运行 open-code-review 预推送检查... if bin/open-code-review check --base origin/main; then echo 评审通过可以推送。 else echo 评审未通过请查看上方报告。 exit 1 fi把它放到钩子里后push 之前先自查变成了硬约束。第一次安装时团队里有人嫌烦但两周后大家就习惯了因为工具报告会精确告诉你哪里不行比 CI 跑到一半再报错快得多。3.4 输出评审报告不止是过了/挂了报告格式决定了一个工具好不好用。我在 v1 版本只输出一个 flat 的文本列表结果在终端里超长重要的 P0 被淹没在 P3 风格建议里。后来我改成按严重度分组、按文件聚类的 Markdown 报告# 代码评审报告 评审对象: feature/user-login-refactor 目标分支: main 变更文件: 12 个 | 新增 356 行 | 删除 89 行 ## P0 - 阻断合并 ### src/auth/token.py:42 - secret: 检测到可能的硬编码密钥请立即移除并使用环境变量注入 ## P1 - 必须修改 ### src/auth/service.py:87 - size: 单次新增超过 400 行实际 423 行建议拆分评审 ### src/lib/validator.py:15 - test_check: 新增源代码文件但未发现对应测试文件 ## P2 - 应当修改 ### src/utils/http.py:33 - forbidden: 包含 TODO 标记建议补充 issue 链接 ## 统计 P0: 1 | P1: 2 | P2: 1 | P3: 0 结论: BLOCKED这个报告格式是从实际使用反馈里迭代出来的第一版失败点在于没有聚类导致同一个文件的问题分散在各个角落。现在按严重度-文件-行号三层展示开发者能按文件一个一个修过去。4. 实操过程在真实仓库里跑通一次完整评审4.1 环境准备与快速安装我先说安装。整个项目没有发布到包管理器因为很多内网环境根本访问不到 PyPI更稳妥的方式是直接 clone 仓库把bin/目录放进 PATH。以下是我自己使用的安装方法git clone https://your-git-host/open-code-review.git ~/tools/open-code-review ln -s ~/tools/open-code-review/bin/open-code-review /usr/local/bin/open-code-review然后是初始化目标仓库的规则文件cd /path/to/your/project open-code-review init这会在项目根目录生成.code-review/rules.yml。我强烈建议你打开它逐项检查并修改而不是直接使用默认配置。比如默认检查里有一个forbidden规则会把TODO标记为 P2如果你团队习惯用TODO(username)来记录待办就需要调整正则以避免误报。在正式接入 CI 之前我还建议先跑一次open-code-review check --base origin/main看看当前的报告规模。如果你的既有仓库已经积累了大量历史债务第一次跑可能会出现几十条记录这时先不要直接开启阻塞模式否则团队会崩溃。可以先用两周仅报告、不阻塞的模式等大家把存量问题清完再逐步开启 P0、P1 的失败阈值。4.2 一次评审的完整命令行实录为了让过程更直观我模拟一次评审过程。假设我在一个 Python 项目里新增了一个用户登录接口提交信息是feat: add user login api然后我运行open-code-review check --base origin/main脚本输出会分成几个阶段。第一阶段是获取变更集[info] 使用基准分支: origin/main [info] 合并基点: 8f2a9c3 [info] 发现 12 个变更文件 (新增 356 行, 删除 89 行)第二阶段是逐条执行检查器[run] 检查器 secret 正在执行... [run] 检查器 test_check 正在执行... [run] 检查器 forbidden 正在执行... [run] 检查器 style 正在执行... [run] 检查器 size 正在执行...第三阶段是输出汇总[result] P0: 1 | P1: 2 | P2: 1 | P3: 0 [result] 结论: BLOCKED然后完整的 Markdown 报告会被打印到终端。我第一次拿到这份报告时发现那个 P0 是因为我在重构时不小心把一份本地配置文件的私钥样例写进了源文件。看到报告的那几秒钟是很震撼的因为之前我完全没意识到这个文件会被提交上去。工具的价值在这一刻体现得清清楚楚它不聪明但它不会累、不会看走眼。修复那处密钥后再跑一次open-code-review check --base origin/main # 输出: [result] 结论: PASSED退出码为 0这次就可以安全推送到远程了。4.3 接入 GitHub / Gitea 等平台时怎么改open-code-review 本身不依赖平台但把报告同步到平台这件事确实需要一些胶水代码。这块是我觉得最有意思的部分因为它证明了解耦的价值。以 GitHub Actions 为例我的工作流文件大概是这样的name: open-code-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: 运行评审 run: | bin/open-code-review check --base origin/${{ github.event.pull_request.base.ref }} echo exit_code$? $GITHUB_ENV - name: 发布报告到 PR 评论 if: always() run: | bin/open-code-review report --format markdown report.md gh pr comment ${{ github.event.pull_request.number }} --body-file report.md env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}fetch-depth: 0这行是关键很多人在 GitHub Actions 里跑这类工具失败的根源就是这个。默认 checkout 只拉取一个浅克隆git merge-base找不到历史整个评审脚本就会直接退出。我第一次接入时在这里卡了两个小时后来查了一下才知道是浅克隆导致的问题。内网 Gitea 也类似Gitea 自带 Actions 兼容层工作流语法和 GitHub 几乎一致或者你用 Gitea 的 Webhook 指向一个内部 Jenkins 任务在任务里调用评审脚本后把报告写回评论。无论哪种路径评审本身的逻辑没有任何变化变化的只是调用入口。5. 常见问题与排查技巧实录5.1 评审脚本不干活的三种典型原因落地这么久团队成员问得最多的问题就是我跑了 check但它好像什么也没检查。这类问题我整理出三种最常见的原因没有找到基准分支。如果你本地没有origin/main这个引用git merge-base会失败脚本会直接以跳过状态退出。解决方法是在项目里先git fetch origin或者把--base指到一个确定存在的分支。变更文件不匹配任何规则的include模式。比如你改了docs/readme.md但规则里只检查src/**那么结果就是没有命中。这不一定是 bug但会让使用者困惑。后来我在输出里加了一行未命中规则的文件列表情况好了很多。浅克隆或缺历史。CI 环境里最常见如前所述必须保证仓库有完整历史。排查这类问题我建议先用一个巧妙的调试命令open-code-review check --base origin/main --verbose --dry-run--dry-run只打印如果执行会跑哪些检查不真正执行。它能帮你明确当前输入是否被正确解析排除掉 80% 的空跑问题。5.2 规则误报太多怎么办误报是规则引擎逃不掉的宿命关键是规则要能被精确地关闭或降级。我的原则是保留少数高置信规则砍掉低置信规则。举几个实际例子。secret规则中的正则(?i)password\s*[:]\s*[^]会把password guest这种测试代码也标记为 P0。对于测试目录我会额外排除secret: enabled: true severity: P0 exclude: - tests/** - **/fixtures/**另一个误报重灾区是forbidden里的TODO。如果你遇到报告里全是无关紧要的 TODO我的建议不是直接关掉这个规则而是缩小触发条件比如只对没有关联 issue 编号的 TODO报警forbidden: enabled: true severity: P2 patterns: - TODO(?![A-Z]-[0-9])这个正则会放行TODO(USER-123)这样的写法只对裸TODO或TODO:...报警。如果你完全没有 issue 编号习惯这个规则可以直接关掉不要让风格问题成为噪音。5.3 diff 太大导致检查超时或内存紧张open-code-review 内置了size检查器会在规则引擎之前计算变更集的规模但有些项目在超大 PR 进来时光生成 diff 就可能消耗大量内存。我曾遇到一个合并了多天的长周期分支一次变更包含上千个文件脚本直接在生成 diff 阶段 OOM 了。针对这种情况我做了两个调整。一是在size规则之前增加了一个硬性上限如果变更文件数超过 100直接标记 P1 并跳过逐文件检查要求开发者拆分提交。二是为 diff 解析器增加了按文件流式处理的模式不再把整个 diff 一次性读入内存。这个改动让我能处理更大的仓库。这里也引出一个使用建议open-code-review 更适合配合小步提交的工作流。如果你的团队习惯一个星期才推一次大分支工具会频繁地因为变更规模过大而阻断这会让人很反感。反之如果你把评审拆成多次小步提交每次工具都能快速给出精准结果体验会好很多。5.4 速查表常见报错与处理办法现象可能原因处理办法输出显示 skipped 但没有任何检查基准分支不存在执行git fetch origin后重试报告的 P0 数量巨大首次在存量仓库上运行暂时调低 severity 阈值先观察式运行CI 中报告为空浅克隆导致无法合并基点增加fetch-depth: 0或完整 clone规则修改后不生效文件路径写错或缓存确认.code-review/在仓库根目录并检查open-code-review init是否覆盖了规则中文路径文件乱码终端编码问题设置环境变量PYTHONUTF816. 落地经验与后续扩展方向6.1 让团队真正接受开放评审的落地心得工具写出来和团队用起来是两回事我在推广 open-code-review 的过程中学到的最重要一课是不要一上来就全面开启阻塞模式。我当时分了四步走。第一步只在一个不太活跃的后端仓库上跑输出报告但不阻断任何操作。第二步挑选两三个最确定的问题类型密钥泄露、缺失测试设为 P0/P1并对全组公告从这周开始这两类问题提交代码会失败。第三步收集两周内所有误报逐条调整规则。第四步全面铺开到其他仓库并让每个团队维护自己的rules.yml。这个节奏里最关键的是第二步和第三步。如果你同时开启全部规则误报会淹没真实问题团队会迅速失去信任。我之前在另一个项目上就吃过这个亏一上来全绿变红结果大家第一反应是找跳过方式而不是修复问题。宁可一开始规则少、稳定、精准也不要用一堆半吊子规则把体验搞砸。还有一件事值得强调规则变更本身要经过评审。open-code-review 的配置在仓库里所以任何人改rules.yml都是改代码会触发审查。这保证了评审标准不会因为某个人的心血来潮而随意变动。6.2 下一步我准备扩展的方向open-code-review 目前的状态对我来说已经够用了但我也在思考一些扩展方向这里列出来给感兴趣的读者参考。第一个方向是代码语义层面的辅助检查。传统规则引擎只能做文本匹配但如果接入一个本地开源模型做变更摘要生成至少可以帮人工评审者快速理解一个 PR 改了什么东西。我之前实验过把 diff 中最相关的几个 hunks 提交给模型让它生成变更意图描述然后附在报告开头。试点效果不错但我暂时不打算把它做成默认功能因为模型推理时间是变量不适合作为 CI 强制环节。第二个方向是更精细的评审豁免机制。现在 P1 类问题允许人工申请豁免但这只是在流程上放行缺少审计。我想实现一个简单的链上记录每次豁免都必须写明理由、指定审批人、设置过期时间过期的豁免自动重新进入待处理状态。这样既保留灵活性又不会让紧急豁免变成逃避评审的借口。第三个方向是做一个 VSCode 插件让开发者在写代码时就实时看到 open-code-review 的检查结果而不必等到 push 前才被打回。这相当于把评审提前到代码输入阶段收益会很大但工作量也明显更高目前我还在做一个 MVP 原型。最后说点个人体会。我自己一直不太相信评审可以完全自动化代码评审中真正有价值的部分是两个工程师之间关于设计取舍的讨论这是任何规则引擎都替代不了的。open-code-review 对我最大的价值不是替我做决定而是把团队里最没有争议的那一部分标准比如别提交密钥、改了代码要补测试、大 PR 要拆开提前变成了机器强制执行的动作。这样我和同事们在评审时才有精力去聊那些真正需要人脑判断的问题而不是一遍遍地提醒你这里少了测试吧这个 token 怎么又进来了。对一个技术团队来说这种机器管重复的事人管思考的事的分工我觉得才是评审工具该有的样子。