1. 项目概述：为什么我决定做一个开源的 code review 工具

代码审查这件事，说实话，每个团队都在做，但真正做好的没几个。我过去几年呆过好几个团队，见过用 GitHub PR 评论来回刷的，见过在 IM 群里丢代码链接让大家“帮忙看看”的，也见过采用 Gerrit 那套复杂权限流程结果全员抗拒的。直到我自己动手写了一个叫 open-code-review 的开源工具，才觉得代码审查这件事终于有了一个既轻量又可控的解法。

open-code-review 本质上是一个基于 Git 工作流、完全运行在终端环境下的开源代码审查工具。它不依赖任何商业平台，也不需要额外的 Web 服务，你只需要一个 Git 仓库，就能在本地或 CI 环境里完成从“提交审查请求”到“记录审查意见”再到“确认是否通过”的完整闭环。适合那些不想被平台绑定、又希望把 code review 这件事真正落到流程里的个人开发者和中小团队。

我把整个项目开源的时候，主要思路就一句话：让代码审查像 git commit 一样自然。你提交代码时用 git，切换分支用 git，那么发起一次审查、提一条意见、打一个通过标记，也应该可以用一套命令行工具完成，而不是跳去网页、点一堆按钮、还要忍受漫长的评论加载。这个项目的意义就在于把代码审查的“仪式感”降到最低，把“效率感”提到最高，同时把审查过程中产生的所有数据留存在本地，方便追溯和统计。

2. 核心设计思路与技术选型

2.1 为什么不用现成的 Code Review 平台

先说一个很现实的问题：市面上不是没有代码审查工具，GitHub Pull Request、GitLab Merge Request、Gerrit、Phabricator，哪个不能用？都能用。但我在实际使用中逐渐感受到几个痛点，这些痛点恰恰是 open-code-review 想解决的。

第一个痛点是平台锁定。代码放在 GitHub 上，审查就得在 GitHub 上做；代码挪到自建的 GitLab，审查流程又要重新配置一遍。对于同时维护多个仓库、横跨多个平台的开发者来说，这种绑定非常难受。我希望能有一套和仓库托管平台解耦的审查机制，只要底层是 Git，走到哪里都能带过去。

第二个痛点是流程太重。GitHub PR 的全套流程——开 PR、等 CI、找人 review、处理 comment、再 push 新 commit——对于大型项目是合理的，但很多内部工具、脚本、配置类的仓库，改动往往很小，也要走完整套流程，时间成本明显不匹配。我需要的是一种“轻量审查”模式：改动不大，但该走的检查要有，该留的记录也要留。

第三个痛点是数据归属问题。审查意见、通过记录、驳回理由，这些都是团队的过程资产。放在商业平台上，导出和归档都相对麻烦；放在本地仓库里，随便 grep 一下就能出报告。从数据自主可控的角度看，本地化存储反而更有优势。

2.2 技术栈选择：Python 与 Git 命令的配合

open-code-review 选择用 Python 来实现，原因很简单：Python 在处理文本、解析 diff、调用外部命令方面都非常顺手，而且几乎不需要编译，拿到代码就能跑，对使用者的环境要求也低。

核心架构上，我并不直接操作 Git 的内部对象，而是通过 subprocess 调用系统 git 命令来完成任务。这样做的最大好处是，只要机器上装了 Git，工具就能正常工作，不用去处理不同 Git 版本之间内部存储格式的差异。Git 本身已经是一套极其成熟的版本管理协议，我不需要重复造轮子，只需要在它的上层构建代码审查的语义层。

整个工具的数据存储也非常朴素，就落在当前仓库的 .git/review/ 目录里，用 JSON 文件保存每次审查的记录。为什么不用数据库？因为代码审查的数据量级根本到不了需要数据库的程度，一个中型团队跑一年，审查记录也就几千条，JSON 文件完全撑得住，而且可以直接用文本编辑器查看、用脚本处理，天生就是开放格式，这完全符合 open-code-review 这个名字的“open”精神。

2.3 审查工作流的状态机设计

任何流程类工具，核心都是一套清晰的状态转换规则。open-code-review 的审查流程被我设计成四个状态：

pending（待审查）→ approved（已通过） pending（待审查）→ changes_requested（需修改） changes_requested（需修改）→ pending（重新提交） changes_requested（需修改）→ approved（审查者确认修改到位）

这个状态机非常朴素，但胜在清晰。审查者看到一条记录时，不需要思考“现在处于什么阶段”，因为状态只有三种可能：还没审、已通过、需修改。不存在“reviewing”（审查中）这种中间态，因为实际工作中，“审查中”本质上是“还没结论”，用 pending 表达就够了，多一个状态反而增加理解成本。

工具内部用一个简洁的 Python 类来管理状态转换：

class ReviewState: PENDING = "pending" APPROVED = "approved" CHANGES_REQUESTED = "changes_requested" # 合法的状态迁移路径 VALID_TRANSITIONS = { PENDING: {APPROVED, CHANGES_REQUESTED}, CHANGES_REQUESTED: {PENDING}, APPROVED: set(), } @classmethod def can_transition(cls, current: str, target: str) -> bool: return target in cls.VALID_TRANSITIONS.get(current, set())

状态机的好处在于，它天然阻止了一些不合理的操作。比如一条已经 approved 的审查记录，就不应该再被打回 pending，因为在真实工作流里，既然已经通过了，后续改动应该开启一次新的审查，而不是在同一记录里反复横跳。

3. 功能实现与关键细节

3.1 审查请求的创建逻辑

一次代码审查的起点是执行 review request 命令。它的核心任务只有一个：采集当前分支相比目标分支的代码变更，并生成一条待审查记录。

在实现上，这个功能依赖 git diff 的输出。我封装了一个底层函数来获取变更内容：

import subprocess def get_branch_diff(base_branch: str, head_branch: str) -> str: """获取指定分支之间的完整变更内容""" result = subprocess.run( ["git", "diff", base_branch, head_branch], capture_output=True, text=True, check=True, ) return result.stdout

拿到 diff 文本后，工具会把整个 diff 拆分成逐文件的变更统计，包括新增行数、删除行数、变更文件列表，一并写入审查记录。这样审查者在打开记录时，第一眼就能对整个改动的规模有直观印象，而不是面对一大段 diff 无从下手。

创建审查记录时，还需要指定审查者。open-code-review 支持两种方式：命令行参数显式指定，或者读取仓库根目录下的 REVIEWERS 文件。如果 REVIEWERS 文件存在，会优先从里面读取审查者列表；如果文件不存在，则退化为读取 git config user.name 作为默认审查者。这个设计兼顾了团队标准化和个人轻量使用的不同场景。

3.2 自定义审查规则的引擎实现

很多人觉得代码审查就是人肉看代码，其实不然。大量重复性的低级问题，完全可以在人眼介入之前，用规则引擎先跑一遍。open-code-review 内嵌了一个轻量的规则引擎，支持在配置文件中自定义检查规则。

规则的配置格式是 YAML，因为 YAML 的阅读和手写成本都低于 JSON 和 TOML。每个规则由四部分组成：名称、优先级、匹配模式、针对的文件类型。

# .codereview.yaml 配置示例 rules: - name: no-debug-print level: warning pattern: "print\\(.*debug|console\\.log\\(.*debug" files: - "*.py" - "*.js" message: "禁止调试用的 print/log 语句进入主干代码"

工具启动审查时，会逐条规则去扫描 diff 中的新增代码行，而不是扫描整个文件。这个设计是基于一个经验判断：审查的注意力应该只放在新增和修改的代码上，原有代码如果有问题，那属于遗留债务，不应该拦在一次小改动的审查门口。

扫描逻辑通过正则表达式匹配实现，核心代码非常精简：

import re from pathlib import Path from typing import Dict, List def scan_new_lines(diff_text: str, rules: List[Dict]) -> List[str]: findings = [] current_file = None for line in diff_text.splitlines(): if line.startswith("+++ b/"): current_file = line[6:] continue if current_file and line.startswith("+"): content = line[1:] for rule in rules: if re.search(rule["pattern"], content): findings.append( f"{current_file}: {rule['level']}: {rule['message']}" ) return findings

这段代码的逻辑非常直观：遍历 diff 文本，识别文件头，只挑选以 + 开头的内容行，逐条规则做正则匹配，命中就记录为一条发现问题。配合配置文件的规则扩展，基本能覆盖大多数团队常见的静态检查诉求。

3.3 审查意见的提交与通知机制

审查意见的提交是整个工作流里最需要打磨的部分。我见过太多审查流程死在意见表达上——要么意见写得含混不清，要么没有定位到具体的代码位置，导致开发者和审查者来回拉扯。

open-code-review 的意见格式参考了一些成熟平台的做法，强制要求每条意见包含三个要素：文件路径、代码行号、意见正文。命令行交互时，工具会引导用户逐步输入，而不是要求一次性记住所有参数：

$ open-code-review comment review-20250115-1630 文件路径: src/processor.py 代码行号: 42 意见内容: 这个函数在输入为空时会抛异常，建议增加空值判断

提交意见后，工具会自动追加一条格式化的 Markdown 文本到评审记录的 comments 字段，同时在终端输出提示。如果配置了 webhook 地址，还会向指定 URL 发起一个 HTTP POST 请求，把意见推送到团队群或消息机器人，这样审查者发出意见后，开发者不需要主动刷新状态就能收到通知。

这里有一个实操细节值得强调：webhook 的 URL 建议通过环境变量注入，而不是写在配置脚本里。因为代码审查配置通常会进版本库共享给团队，如果 URL 写死在配置里，一旦后期更换消息机器人地址，就要改代码、提交、再等 CI 跑一遍，非常低效。

3.4 审查记录的存储结构与查询

每条审查记录对应 .git/review/ 目录下的一个 JSON 文件，文件名采用 审查者名字-时间戳 的格式，保证唯一性。一个典型的记录文件长这样：

{ "id": "review-20250115-1630", "author": "zhangsan", "reviewer": "lisi", "base_branch": "main", "head_branch": " feature-login-timeout", "created_at": "2025-01-15T16:30:22+08:00", "status": "pending", "summary": { "files_changed": 3, "insertions": 48, "deletions": 12 }, "diff_summary": "src/auth.py (+35, -8), src/config.py (+10, -2), test/test_auth.py (+3, -2)", "comments": [ { "file": "src/auth.py", "line": 42, "content": "这里建议用 datetime.now(timezone.utc) 替代 datetime.utcnow()，后者已标记过时" } ], "status_changes": [ { "from": "pending", "to": "changes_requested", "at": "2025-01-15T17:02:11+08:00" } ] }

用纯文本文件存储的好处是透明，谁都能看懂内容结构，也方便写脚本做二次分析。我见过有团队用 open-code-review 的 JSON 数据生成了月度代码审查统计报告，统计每位工程师被提出的问题数量、各模块的审查通过率，这在以往依赖 Web 平台时反而需要写爬虫才能做到。

查询方面，工具提供了 review list、review show 两个命令。list 命令支持按状态和审查者过滤，show 命令则完整展示某条记录的详情，包括所有历史意见和状态变更日志。状态变更日志的保留是我特别坚持的，因为审查过程中意见往返也是重要的过程数据，后续复盘时能看到一条意见从提出到解决花了多长时间，这个数据对团队改进协作效率非常有价值。

4. 完整实操：从零开始用 open-code-review 落地一次审查

4.1 安装与环境准备

open-code-review 的安装非常简单，我已经把它发布到了 PyPI，一行命令就能装好：

pip install open-code-review

安装完成后，可以执行 open-code-review --version 验证是否安装成功。项目对 Python 版本的要求是 3.8 及以上，因为用到了 f-string 的动态表达式和内置 typing 的部分特性，更低版本会报语法错误。

如果你不想通过 pip 安装，也可以直接从 GitHub 仓库 clone 源码，然后把它加到 PATH 里使用。源码包内只有一个核心模块和一个命令行入口文件，依赖只有 requests 和 PyYAML 两个第三方库，非常轻量。

4.2 项目初始化与团队配置

在项目根目录执行初始化命令：

open-code-review init

这个命令会做三件事：创建 .git/review/ 目录、生成一份默认的 .codereview.yaml 配置文件、在 .gitignore 中添加 review 临时文件规则。

默认的配置文件内容如下：

# open-code-review 配置文件 rules: - name: no-debug-print level: warning pattern: "print\\(.*debug|console\\.log\\(.*debug" files: - "*.py" - "*.js" message: "禁止调试打印语句" - name: no-todo-comments level: warning pattern: "TODO|FIXME" files: - "*.py" - "*.js" - "*.java" message: "TODO 注释不允许进入主干" - name: secret-key-detection level: error pattern: "(api[_-]?key|secret|password)\\s*[:=]\\s*['\"][^'\"]{8,}" files: - "*.py" - "*.js" - "*.yaml" - "*.yml" message: "检测到疑似密钥硬编码，必须处理后再提交"

这三条规则是我根据多年经验总结的高频问题清单。第一条和第二条属于常规工程规范，第三条特别重要：密钥硬编码是安全事故的重灾区，很多团队直到出事了才回头排查代码仓库里的明文密钥。规则引擎在扫描到 error 级别问题时，会直接阻止审查请求的创建，强制开发者先解决。

初始化完成后，你可以编辑 REVIEWERS 文件，写上团队里负责审查成员的 git 用户名，每行一个。这样创建审查请求时，工具会自动随机选择一个审查者，让团队间的审查任务分配更均匀。

4.3 发起一次审查请求

假设你在 feature-login-timeout 分支上完成了一个功能开发，现在要发起审查合并进入 main 分支：

open-code-review request --base main --head feature-login-timeout --reviewer lisi

执行后，终端会输出审查创建的摘要信息：

创建审查成功 审查 ID: review-20250115-1630 变更文件: 3 新增行数: 48 删除行数: 12 审查者: lisi 状态: pending 自动扫描结果: - src/auth.py line 42: warning: 这里建议用 datetime.now(timezone.utc) 替代 datetime.utcnow()，后者已标记过时 - src/config.py line 15: error: 检测到疑似密钥硬编码，必须处理后再提交 警告: 存在 error 级别未解决问题，建议先修复再提交人工审查

注意，这里规则引擎扫描出来的问题只是给开发者一个提醒，真正决定审查是否通过，还是由人工审查者确认。但 error 级别的规则命中会显著提醒开发者优先处理，避免把明显有问题的代码送到审查者面前。

4.4 审查者视角：处理一条待审查记录

审查者收到消息通知后，可以查看待办列表：

open-code-review list --status pending

找到对应的审查 ID 后，先查看整体变更摘要和规则扫描结果，再查看具体的代码 diff：

审查 ID: review-20250115-1630 审查者: lisi 状态: pending 创建时间: 2025-01-15 16:30 变更统计: src/auth.py +35 -8 src/config.py +10 -2 test/test_auth.py +3 -2 自动扫描发现: [warning] src/auth.py:42 建议使用 timezone-aware 的 datetime [error] src/config.py:15 疑似密钥硬编码

审查者可以先查看自动扫描发现的 error 级别问题，确认是否真的存在密钥硬编码。如果确认，就直接提交意见并打回；如果不影响合并，则继续查看 diff 的整体逻辑。

提交意见用的还是 comment 子命令，但审查者可以一次性针对多个文件提出多条意见，工具会按文件路径自动归类到对应的 JSON 记录中。

如果审查者认为代码整体合格，只需要微调几个点，就使用以下命令提交意见并标记状态：

open-code-review comment review-20250115-1630 --file src/auth.py --line 42 --message "建议改用 timezone-aware 的时间处理" open-code-review status review-20250115-1630 --to changes_requested

开发者看到状态变更后，修复对应问题，重新提交新 commit 到同一分支，再执行 review request 时，工具会识别到同一分支已经存在 pending 或 changes_requested 状态的记录，自动将其状态置回 pending，并把新生成的 diff 追加进原有记录，而不是创建一条新记录。这个设计保证了一条 feature 分支的审查历史是连续的、可追溯的。

4.5 CI 环境的自动化集成

open-code-review 除了支持手动执行，还设计了一个非常重要的场景：集成进 CI 流水线。在 GitHub Actions 或类似工具中，可以添加一步来调用规则引擎的扫描功能，让自动化检查跑在人工审查之前：

name: code-review-check on: [pull_request] jobs: review-scanner: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: "3.10" - run: pip install open-code-review - run: | open-code-review ci-scan \ --base origin/main \ --head HEAD

ci-scan 子命令是专门为 CI 场景设计的，它不会创建审查记录，只运行规则引擎并输出结果。如果发现 error 级别的问题，命令会以非零状态码退出，从而阻断流水线；如果只有 warning，则输出提示但不阻断。这个行为在代码里体现为：

def ci_scan(base_branch: str, head_branch: str) -> int: diff_text = get_branch_diff(base_branch, head_branch) rules = load_rules() findings = scan_new_lines(diff_text, rules) error_count = sum(1 for f in findings if f["level"] == "error") warning_count = sum(1 for f in findings if f["level"] == "warning") for finding in findings: print(f"[{finding['level'].upper()}] {finding['location']}: {finding['message']}") print(f"扫描完成: {error_count} errors, {warning_count} warnings") return 1 if error_count > 0 else 0

接入 CI 的价值在于形成分层防护：规则引擎拦截低级错误，人工审查专注代码逻辑和架构设计。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

我在使用和开发过程中遇到不少问题，也收到了不少使用者的反馈，整理成一张速查表，供遇到类似问题的朋友快速定位：

5.2 我踩过的坑：规则引擎误伤怎么处理

规则引擎用正则表达式做扫描，最大的风险就是误报。我记得有一次给某个项目配置规则时，设置了 pattern 是password\s*[:=]，结果项目里正好有一个测试用例的变量名叫 password_validator，每次扫描都会命中，搞得开发同事直接在群里喊“被误报了”。

后来我给出的方案是两条线并行：一是放宽正则表达式，把匹配范围缩小到更接近真实密钥定义的上下文，比如要求等号右侧必须是引号包裹的字符串，且内容长度超过八位；二是在配置文件中支持 per-rule 的 exclude_paths 字段，明确指定哪些目录或文件可以跳过某些规则。比如测试目录下生成的临时配置文件中包含类似密钥的测试数据，这是正常的，就应该跳过。

rules: - name: secret-key-detection level: error pattern: "(api[_-]?key|secret|password)\\s*[:=]\\s*['\"][^'\"]{8,}" files: - "*.py" - "*.js" - "*.yaml" - "*.yml" exclude_paths: - "test/" - "tests/" - "fixtures/"

做了这两个改进后，误报率明显下降。这也说明一个道理：静态检查工具的价值在于辅助人，而不是替代人。规则调得太紧会整天误报，让人产生“狼来了”的麻木感；调得太松又形同虚设。找到团队能接受的检查强度，需要在实际使用中持续调整。

5.3 数据迁移与跨仓库复用

如果团队之前已经在别的平台上有代码审查记录，想要迁移到 open-code-review，其实也不用太纠结历史数据。我的建议是最多迁移最近三个月的记录作为参考，更早的记录价值不大，反而会给新流程的落地增加噪声。

open-code-review 本身不提供自动导入功能，但 JSON 格式的好处就是方便做数据转换。只要写一个脚本，从原平台导出审查数据并映射成如下结构即可，这个字段设计对其他平台的审查数据比较友好：

{ "id": "review-20241101-1200", "author": "zhangsan", "reviewer": "lisi", "base_branch": "main", "head_branch": " feature-xxx", "created_at": "2024-11-01T12:00:00+08:00", "status": "approved", "comments": [] }

跨仓库复用方面，由于所有审查记录都存于 .git/review/ 目录，且不依赖远程服务器，团队完全可以把 review 记录目录纳入仓库的版本管理。这样每当有人克隆这个仓库，就能看到之前的全部审查历史。不过要注意，这会让仓库体积变大一些，对于长期活跃的大仓库，我建议还是把 .git/review/ 加入 .gitignore 中进行本地持久化，同时定期通过脚本归档到团队内部的文件存储服务。

5.4 多人协作时的意见冲突处理

最后分享一个协作经验。当审查者是多人轮换时，很容易出现前后意见不一致的情况——比如第一个审查者要求用 A 方案，第二个审查者却觉得 B 方案更好，开发者夹在中间很难做。我的解决方案是在意见提交时给每条意见增加一个 optional 标记，表示这是建议性意见，不强制修改；但如果一条意见被连续两个以上审查者同时提出，它就自动升级为 mandatory（必改）级别。

open-code-review 的实现是在 JSON 记录里增加一个 agreement_count 字段，每条意见被再次提及时自动加一。当 agreement_count 大于等于 2 时，show 命令展示这条意见时会带上高亮标记，提醒开发者这是多人共识，应该优先处理。这个设计避免了“官大一级压死人”或者“谁来审谁说了算”的尴尬局面。

6. 一些实操心得和个人体会

从开始写 open-code-review 到现在，我在自己参与的项目里已经用它完成了上百次代码审查。有个体会比较深：轻量级的工具真的能提高流程的执行率。以前用 PR 流程的时候，很多小改动大家嫌麻烦，干脆直接 push 上去口头说一句“改好了”，根本不留记录。现在用 open-code-review，发起一次审查就是一条命令的事，成本极低，大家自然愿意走流程，审查记录也就完整了。

另外想说一下，代码审查工具的价值不在于它能替代人去思考，而在于它能让人更专注于真正的思辨。规则引擎先把低级问题拦住，人工审查者看到的代码就已经相对干净，他们可以把精力放在架构设计、边界条件、潜在 bug 这些真正需要人脑判断的地方。

如果你正在为团队寻找一套轻量、开源、不依赖平台的代码审查方案，open-code-review 值得一试。它的学习成本很低，两条核心命令就能跑通整个流程；配置也集中在 YAML 文件里，团队统一调整规则非常方便。后续如果你想在这个项目上做二次开发，从 Python 源码入手也不会觉得困难。拿它作为团队代码质量建设的第一块基石，至少对我来说，是过去一年做过最正确的一个技术决定。