开源代码审查工具open-code-review：用状态机与规则引擎重构评审流程

团队代码审查这件事，我从一开始的“认真逐行看”到后来的“看到第 10 个 PR 就开始划水”，只用了半年。不是我不想审，是流程太乱了：评审意见散落在 IM 聊天记录里，修改后的版本没人知道改没改干净，合并之后的关联记录全靠记忆。后来我下决心自己写了一套开源的代码审查工具，命名为 open-code-review，它不追求替代现有 Git 托管平台，而是把审查流程本身变成一套可追踪、可固化、可自动化的协议。这篇文章就聊聊它的设计思路、核心流程和我在真实使用中踩过的坑，希望能给同样被评审问题折磨的团队一点参考。

如果你是一个中小型技术团队的技术负责人、后端/前端工程师，或者喜欢自己折腾工具链的个人开发者，这个项目都值得看下去。它解决的核心问题是：评审意见不丢、状态可追踪、规则能被代码化。

1. 我为什么宁愿自己写，也不想再等现成平台出功能

1.1 被评审流程消耗掉的三个典型场景

先说我遇到过的三个真实场景，你们感受下是不是似曾相识。

第一个场景，需求方催着上线，代码分支已经提了 MR，评审人在群里说“LGTM，合了吧”，但没人真正在代码托管平台上写完评审记录。等后面出问题回溯时，根本找不到当时谁看过、评论了什么、有哪些遗留问题。

第二个场景，一个 PR 里有 30 个文件，其中大部分是自动生成的、格式化产生的、或者无意义的空行变更。评审人真正的精力被大量 diff 稀释，真正需要关注的业务逻辑反而没人仔细看。

第三个场景，评审意见提了之后，作者改了一半，另外几条“忘”了。没人知道是不是真的忘了，因为意见分散在好几种渠道里，你不可能逐条对账。最后只能靠会议重新过一遍。

这些问题本质上是同一个：审查过程没有被结构化。Git 管住了代码的版本，但管不住“人对代码的看法和后续动作”。现成的平台也在做 review 功能，但它们的条评论体系是围绕 PR 展开的，不是围绕“评审会话”展开的。我想要的是更轻、更明确、一个 PR 上可以有多轮评审状态、每个意见都可以单独跟踪的模型。

1.2 设计原则：把流程拉回到开发者的控制之下

open-code-review 的核心思路非常朴素：所有审查状态都落在一个可读取的文本文件或本地数据库中，它可以被 Git 版本化，也可以被脚本读取。

设计时有三个原则：

• 最小依赖：不引入复杂服务，运行时就一个轻量进程，使用 SQLite 作为存储，不依赖外部数据库。
• 显式流程：评审单（review ticket）是核心对象，每个评审单有明确的状态机，比如 pending、in_progress、approved、changes_requested、merged。
• 规则可编程：不需要在 Web 界面里配置一堆按钮，用 YAML 规则文件定义必须通过的检查项，例如“所有阻塞意见必须标记为 resolved 才能进入 approved 状态”。

这三个原则决定了它和 GitHub/GitLab 自带 review 的差异。你可以把它理解成“评审流程的看板”，代码托管平台依然是代码和 MR 的唯一事实来源，但评审是否通过、谁阻塞、哪些意见还没处理，由 open-code-review 统一管理。

1.3 为什么选开源自托管，而不是直接用 SaaS

因为我在不少团队里见过这种尴尬：平台功能一大堆，权限模板、自动化工作流、流水线集成，样样都有，但真正用得最勤的却只有“评论”和“合并”。很多流程治理功能藏在设置后台，普通工程师根本不去碰，久而久之平台成了摆设。

open-code-review 采用自托管还有一个重要考虑：安全合规。有些团队在内部网络内开发，代码根本无法推送到公网的代码托管平台，也不希望把评审数据放到第三方服务上。自托管一个工具，部署在公司内网，所有数据都在本地，安全边界非常清晰。它不需要访问宿主 Git 平台的 API，而是直接站在 Git 仓库目录旁边，用 Git 命令获取 commit、diff、分支信息。

2. open-code-review 的整体设计与技术选型

2.1 核心数据模型：一个评审单就是一次完整的视图

open-code-review 里的核心对象有四个：ReviewTicket、Comment、Rule、Resolution。

一个评审单代表一次针对某个分支或 MR 的完整评审会话，它包含基础信息：目标分支、源分支、当前 commit SHA、关联的 MR/PR URL、评审人列表、状态、创建时间和更新时间。可以想象成“这一轮评审的容器”。

Comment 是评审意见，挂在某个评审单下面，每条意见都必须有目标文件、目标行号范围、严重级别（blocker、major、minor、nit）、正文内容和作者。每条意见可以拥有一个 Resolution 对象，标记为 open、resolved 或 wontfix。只有所有 blocker 级别的意见都 resolved，评审单才允许进入 approved 状态。

Rule 是代码化的检查项，用 YAML 配置。它可以是静态检查，比如“不允许合并包含 TODO 注释的代码”，也可以是流程检查，比如“至少需要两名评审人批准”。每次状态变更时，规则引擎会运行一遍，不符合规则的操作会被拒绝。

这个模型的好处是，评审状态不再是一堆聊天记录，而是一个可以查询、筛选、导出、统计的结构化数据集。我可以随时问：“当前迭代里有多少条 blocker 意见？”或者“哪个文件最容易被提意见？”

2.2 技术栈选择：为什么是 Python + FastAPI + SQLite + Git CLI

我评估过一堆技术组合，最后选择了尽量朴素的一套。

组件	选择	理由
核心语言	Python 3.11+	团队熟悉，处理 Git 输出、文本解析非常方便
Web 框架	FastAPI	开发效率高，自带 OpenAPI 文档，前端调用方便
存储	SQLite	单文件部署，备份简单，不引入 MySQL/Redis
Git 交互	直接调用 Git CLI	避免第三方 Git 库带来的兼容性问题，行为与命令行为一致
前端	极简 HTML + JS	因为核心使用者是开发者，界面能用就行，不需要炫酷

选择直接调用 Git CLI 是我深思熟虑后的决定。Python 有几个 Git 库，比如 GitPython，但它内部对子模块和特殊分支的处理偶尔会有怪异行为。直接用 subprocess 调用 git diff、git log、git merge-base，输出我可以精准解析，也方便调试。代价是要自己处理小概率的分支名带空格、特殊字符等边界情况，实际上这些在内部仓库中很少遇到。

用 SQLite 也是刻意的选择。评审数据的量级对于中小团队来说非常小，一年下来可能只有几万条评论，SQLite 完全扛得住，而且备份就是复制一个文件。我不想在自托管项目中引入 Redis 或 PostgreSQL，因为那会把部署复杂度抬高一个数量级。

2.3 这套设计解决了什么问题

这个组合带给我的实际好处：

• 部署变成一条命令：docker run -v /path/to/repo:/repo -v /data:/data open-code-review，数据都在挂载卷里。
• 规则文件进 Git 仓库：每个项目的 .open-code-review.yml 可以跟着代码分支走，不同分支可以测试不同规则，比如在希望强制执行某种风格的分支上打开更严的检查。
• Web 界面只是壳：即使没有 Web 界面，通过命令行 CLI 也能完成所有操作。因为整个系统本质上是对 SQLite 和 Git 仓库的读写。

这种“命令行优先”的设计在遇到自动化集成时特别舒服。CI 脚本里可以直接调用：

如果检查不通过，就返回非零退出码，流水线直接失败。

3. 核心流程实操：从提交到评审通过的完整链路

3.1 初始化项目：一条命令生成配置

拿到一个已有的 Git 仓库，进入项目根目录，运行：

它会生成两个文件：.open-code-review.yml 和 .open-code-review/state/ 目录。.open-code-review.yml 的内容大致如下：

• required_reviewers: 2 表示至少两个人批准才能进入 approved。
• disallow_todo 是示例规则，表示在 src 目录下提交的新代码中不允许出现 TODO/FIXME 标记。
• blocker_resolution_required 表示所有 blocker 意见必须显式标记为 resolved。

这些规则不是凭空设计的。我一直觉得规则应该分成两类：一类是客观可判定的静态检查，一类是需要人工确认的流程约束。把它们统一放进 YAML 后，规则引擎只负责输出“通过/不通过”，至于规则内容本身是否合理，由团队自己通过 Git 评审来控制。

3.2 发起评审：状态机自动分配

假设我在 feature/payment 分支上完成了一个需求，要往 main 合并。老规矩，我先创建 MR，然后调用命令：

命令执行后会发生几件事：

• 创建一条 ReviewTicket 记录，状态为 pending。
• 自动运行一轮 pre-check 规则，比如分支是否落后，MR 标题是否符合规范，是否包含 WIP 标记。
• 打印出评审单 ID（形如 TR-2025-0711-003），后续所有操作都会引用这个 ID。

评审单 ID 我认为比简单的数字自增 ID 好用，因为它在聊天记录里一眼能认出，而且可以天然包含日期信息，方便按时间检索。

这个过程里，自动分配不是随机分配，而是根据历史评论统计做的简单轮询。如果某个文件历史上只有某个人有权限，那么它会尝试优先分配给有权限的评审人。

3.3 评审人与作者如何交互：意见以独立实体存在

评审人拿到评审单后，可以直接打开 Web 界面查看 diff，或者用命令行操作。但无论哪种方式，意见都会落到 Comment 实体里。

评审人的典型操作流程：

这一条命令会产生一个带有唯一 ID 的评论，比如 CM-1289。评论一旦创建，不管后续怎么改代码，它都存在于意见列表中，不会被淹没在 diff 的刷新中。

作者收到通知后，可以选择：

• 修改代码，然后在评论下回复“已修改，签名校验放到 verify_callback_signature 中”，并标记 resolved。
• 觉得意见不合理，在评论下解释原因，标记为 wontfix。

这里我特意没有做“标记 resolved 时自动关闭，不允许 reopened”的逻辑，因为实际中经常有作者以为自己改好了，但评审人看了之后发现不对，需要把意见重新打开。所以每个 Resolution 都有 status、actor、timestamp 和 reason 四个字段，标记本身也是一种可审计操作。

3.4 合入策略：状态机防止“带病合并”

状态机是这套系统里最有价值的部分。下面是简化后的状态流转：

当前状态	允许操作	新状态
pending	规则 pre-check 通过	in_progress
in_progress	全部 blocker resolved，且 approve 数量 ≥ 2	approved
in_progress	存在 unresolved blocker	changes_requested
changes_requested	意见被 resolved/ reopen 处理后	in_progress
approved	执行 merge 操作	merged
approved	分支被 force push 或 commit 更新	in_progress

最后一行非常重要，这是一个我在真实项目中踩出来的规则。曾经发生过评审已通过，但有人又在本地 amended 了一次 commit 然后 force push，结果代码内容和评审过的完全不一样。所以 open-code-review 会在每次操作时记录当前分支的 HEAD SHA，一旦发现 HEAD 变了，自动把状态打回 in_progress。

给定一个 approved 状态的评审单，CI 脚本就可以安全地执行合并：

只有返回 0 时才合并。这样评审状态就成了合并流程的硬前置条件，不再依赖人的自觉。

4. 踩坑实录：规则引擎误报与 diff 解析的修复过程

这部分是实际使用中最让我抓狂，也最有收获的一段经历。设计文档里写得再好，真正跑起来才会发现边界情况有多狡猾。

4.1 第一个坑：disallow_todo 把删除行也算进去了

现象是这样的：我在 src/payment_callback.py 里删除了一段带 TODO 注释的旧代码，理论上这不应该是“新增了 TODO”，但规则引擎仍然报错。

我先去了规则日志，发现它读的是 git diff 的完整输出，然后对每一行做了正则匹配，只要在 diff 文本中出现 TODO 就触发警告。问题很明显：根本没有区分是 + 行还是 - 行，也没有区分 diff header。

排查过程是这样的：

1. 先手动执行 git diff main...feature/payment -- src/payment_callback.py，确认删除行以 - 开头。
2. 再看日志里的原始匹配文本，发现它把 - # TODO: 需要重构 里的 TODO 匹配到了。
3. 确认问题出在 parse_diff 函数：它只按 \n 切分 diff 输出，没有判断每个行的前缀。

修复方案是改进 diff 解析器，只提取以 + 开头的行（不包括 +++ 文件头行），再对提取后的代码行做规则检查。同时增加了一个“是否处于代码上下文”的标志，否则即使只看 + 行，也有可能误匹配 diff 上下文里的函数名。

这个坑给我们的教训是：基于 Git diff 的工具，解析 diff 输出永远是第一优先级。任何规则引擎如果没有精确的 diff 行定位，后续结果都不可信。

4.2 第二个坑：Git diff 中的行号在评审中失灵

这个坑更隐蔽。评审人在 Web 界面里针对 src/payment/service.py 的第 128 行提交了评论，作者去改代码时发现第 128 行根本就不是评论里提到的代码。因为评审人看到的 128 是当前 HEAD 版本的文件行号，但作者基于的本地工作区可能是旧版本，或者对方分支中该文件已经因为其他人合并而过期了。

这个问题本质上不是行号本身出了问题，而是行号是“依附版本”的。如果评论只保存一个数字，而不保存对应的 commit SHA，那么当文件变化后，这个数字就没有意义。

我修复这个问题的方法：

• 意见创建时同时记录当前 HEAD 的 commit SHA。
• Web 界面在展示评论时，如果发现当前 HEAD 与评论记录 SHA 不一致，会强制弹出一条提示：“当前代码版本已变化，此评论关联的版本为 commit abc123，点击查看该版本的片段。”
• 提供“查看原始 diff 上下文”的能力，而不是直接把行号映射到最新版本。

这样虽然不能彻底解决“行号漂移”，但至少不会误导作者。后来我干脆把 diff 评论的存储结构从“文件 + 行号”扩展成“文件 + 行号 + commit SHA + 代码片段”，这样即使没有原始仓库，也能从记录里看出当时这段代码长什么样。

4.3 修复后的回归验证与自动化测试

修复完这两个 bug 后，我意识到必须把这套解析逻辑变成可测试的，否则以后改规则时会再次踩雷。我给 diff 解析模块写了一套测试夹具，用真实的 git diff 输出来自测。

测试用例包括：

• 普通的文件新增和删除。
• 重命名文件，diff 头部是 rename from / rename to。
• merge 冲突标记，<<<<<<< HEAD 这样的行在 diff 中会以 + 或空格开头，但绝不能把它当成有效的代码新增。
• 二进制文件，diff 输出是 Binary files ... differ，解析器要跳过。

这些测试全部跑通后，规则引擎的误报率降低到几乎为零。我也从中得到一个经验：凡是处理代码文本的工具，不管表面多简单，都要把“空白行”“仅换行符不同”“文件末尾无换行”“非 UTF-8 编码”这些边界情况列出来做测试。

5. 在真实团队中落地 open-code-review 的经验与扩展方向

5.1 接入成本：一周内从 0 到全部核心仓库覆盖

工具做得再好，不落地就是白搭。我在自己的核心项目组里推广时，做了三件事。

第一件事是把部署做成内部文档，直接沿用现有的 Docker 基础设施。团队里有人连 Python 环境都不想配，但 Docker 人人会用。docker compose up -d 就能起一个服务，挂载两个卷，一个存仓库，一个存数据。

第二件事是先拿一个非核心仓库试水两周，期间不强制规则，只是让评审过程全部走 open-code-review，并每周拉一次数据统计。试运行的目的是让大家习惯新的工作流，减少抵触情绪。

第三件事是写了一个 CI 集成脚本，把 check 命令挂进 GitLab CI，代码评审未通过时流水线直接红。这一步是真正的强制手段，因为有这个卡点在，大家才没办法绕开流程。

以下是内部团队最初的接入检查表：

• [ ] 部署 open-code-review 服务，确认 Web 界面可访问
• [ ] 在仓库根目录初始化配置
• [ ] 在 CI 脚本中加入 open-code-review check 步骤
• [ ] 把评审流程说明贴到团队文档库
• [ ] 选择两周观察期，收集反馈和误报
• [ ] 观察期后按反馈调整默认规则

5.2 自动化指标：用数据反向驱动团队改进

工具上线后，我得到一个意外收获：可以统计很多以前完全拿不到的数据。比如：

• 平均每个评审单的意见数量。
• blocker 意见从提出到 resolved 的平均耗时。
• 哪些文件的评审耗时最长，反复修改次数最多。
• 哪些评审人的评审意见被标记为 wontfix 的比例偏高（间接反映评审质量）。

这些统计可以通过一个简单的 SQL 查询拿到：

有了这些指标，团队就能明确知道瓶颈在哪里。比如我们曾发现 config/ 目录下的 YAML 文件反复被视为阻塞问题，因为不同人风格不一致。我们把规则补上“config 文件格式必须通过 yamllint”，从此这类意见几乎消失。

这种“从数据中发现流程问题，再反过来写进规则”的方式，让我对工具的价值有了更高的预期。规则不是一开始就完美的，它应该是活的，随着团队演进不断调整。

5.3 接下来可以扩展的方向

open-code-review 目前已经能覆盖完整的评审流程，但我脑子里还有几个扩展方向。

第一个方向是“评审意见与 AI 辅助检查结合”。不是让 AI 直接替人评审，而是作为一个预检步骤：AI 可以根据 diff 先给出“疑似问题”，由评审人决定是否转成正式评论。这样既保留了人的判断力，又减少了低水平重复劳动。

第二个方向是支持单仓多项目的规则隔离。目前一个仓库一套配置，但实际上一个 monorepo 里有多个子项目，各自的规则应该不同。这个功能实现起来不复杂，只需要让 init 时支持多配置文件，并在运行时根据文件路径选择规则集合。

第三个方向是生成评审总结报告。每个迭代结束后，自动生成一份包含关键指标和待办事项的 Markdown 报告，直接推到团队文档库。这样管理层想了解情况时，不用临时拉数据做表，直接看报告就行。

不过不管扩展哪些方向，我都坚持一个底线：工具本身不能变成流程的负担。如果某一天团队成员觉得 open-code-review 的规则让大家束手束脚，那就应该减少规则，而不是增加。

回到最初的问题，代码审查不应该是靠记忆和自觉维持的仪式。把状态机、规则和数据结构化，是我能想到的最稳妥的解法。open-code-review 这个项目现在仍然保持着非常克制的功能边界，它不做代码托管，不做 CI，也不尝试替代人工判断，只负责把审查流程里最容易乱掉的部分固定下来。我个人在这过程中最大的收获，反而不是代码本身，而是对“流程工具”这个概念的理解更深了一层：真正好用的工具，不是每天给人弹无数个提醒，而是让人在需要的时候，恰好能找到正确的下一步。