open-code-review：基于Git Notes实现代码评审闭环的开源工具

如果你在一个开发团队里待过，就一定经历过那种“为了 code review 而 code review”的尴尬：改动说明写得像日记，评审意见散落在聊天记录里，最后合并时谁都不知道那些“待处理”到底处理没有。我在几个不同规模的团队里踩过这些坑，后来干脆自己写了一套轻量级的开源代码评审工具，名字就叫 open-code-review。它不是一个要取代 GitHub Review 的庞然大物，而是一套把评审数据沉淀下来、可以随时导出的工作流。这篇文章我会把项目的设计思路、核心实现、落地方案和踩坑记录完整讲一遍，适合正在搭评审流程的团队，也适合想用 Git 能力做工程化改进的开发者参考。

1. 现状与目标：代码评审为什么总卡在“最后一公里”

1.1 看起来在评审，实际上在走过场

我先说一个很普遍的现象。很多团队确实有 Merge Request 或者 Pull Request 流程，代码也有人在下面留言，但你如果去翻历史，会发现大多数评审意见根本不可追溯：这周说的改进点，下周打开分支发现还留在原地；有人提了一条“这里要不要抽个函数”，作者回了个“好的”，然后就没了后续；再往下翻，还有几个“+1”和表情包。整个过程看起来有交互，实际上没有任何闭环。

问题出在哪？出在流程只有“提意见”这个动作，没有“记录、跟踪、门禁、归档”这些后续环节。评审意见一旦发出去，就变成了一个被动的聊天动作，而不是一条可追踪的数据。只要平台不强制解决，意见就永远可以挂着。我们团队当时的强制手段是“必须把评论清零才能合并”，结果大家开始刷“done”，反而让评审变得更敷衍。所以 code review 的核心难点从来不是“有没有工具”，而是“有没有办法让每一条意见都有去处、有状态、有结论”。

open-code-review 的想法就是这么来的：我不要再去说服大家“认真评审”，而是把评审意见变成一种结构化数据，让它们的生命周期可以被工具自动管理。评审完没完，不是靠人肉数评论，而是靠状态机判断。

1.2 现成的评审工具，重和便宜是两个极端

做这个项目之前，我把市面上主流的评审方案都过了一遍。它们之间有个非常明显的两极分化。

这套对比下来，我发现一个缺口：大多数人其实只想要轻量的评审闭环，不想再来一套管理系统。我们的日常操作已经离不开 Git 了，如果能基于 Git 本身把评审意见存下来，不需要额外服务端，不需要强制使用某一家平台，那这个工具就天然有了“开放”的属性。open-code-review 的定位因此很明确：轻量、可移植、可脚本化，用一组 CLI 命令补齐原生 code review 缺的闭环，而不是再造一个平台。

1.3 open-code-review 的定位与设计目标

简单说，open-code-review 是一套开源代码评审工具集，核心由 CLI 命令和 CI 集成组成。它把评审意见以结构化数据的形式挂到每个 commit 上，然后通过命令完成意见的增删改查、状态流转和门禁检查。

我给它定了四条设计原则：

1. 评审数据可携带。意见跟着 Git 历史走，不依赖某个平台的数据库。
2. 指令可脚本化。所有操作都能在终端里执行，也能放进 CI 流水线。
3. 平台不锁定。GitHub、GitLab、Gitea 都能用，标准 Git 协议即可同步。
4. 门禁可配置。不同团队可以定义自己的“严重级别”和“阻塞规则”。

这样一套工具适合谁？我觉得三类人最合适：第一类是中小团队，不想为评审维护额外服务器；第二类是开源项目维护者，希望外部贡献者也能按统一标准提交评审意见；第三类是经常要出审计报告或交接项目的团队，因为评审记录可以打包导出，不再是死数据。

2. 整体架构与关键设计选型

2.1 为什么用 Git Notes 做评审存储

如果只是想存评审意见，最直接的做法是写进一个 Markdown 文件。但文件会有合并冲突，而且和 commit 没有天然绑定关系。另一个做法是依赖平台 API 存储评论，这又回到了平台锁定。我的选择是用 Git 自带但很多人不熟的 Git Notes。

你可以把 Git Notes 理解为“给 commit 贴便利贴”：commit 本身的内容不会变，但我们可以在 commit 对象上额外挂一段文本。这段文本可以用git notes命令读写，跟踪历史，也能通过标准 Git 协议推送到远端。

用 Git Notes 存储评审意见有四个好处。第一，意见天然和 commit 绑定，不会像聊天记录一样散落。第二，可以用普通的git fetch、git push同步评审数据，不需要部署数据库。第三，开发者拉一个仓库，顺手就能拉下所有历史评审意见。第四，它可以离线操作，不需要每次评审都打开网页。

当然它也有缺点。最明显的是多人同时写 Notes 时容易出现 merge 冲突，另外它不像数据库那样支持复杂索引。所以我在设计时规定：每一条评审意见是一行 JSON，追加写入 Notes，查状态时用 jq 做过滤，这样既保留了 Git 的同步能力，又避免了频繁修改同一段数据。

2.2 评审意见的数据模型

没做数据模型之前，我曾经直接用纯文本写评论，比如“第 42 行：建议判空”。后来发现文本一旦进入状态流转，解析就成了噩梦。有人写“好”，有人写“fixed”，还有人直接写“忽略”。纯文本完全无法自动化判断。最终我把每一条评论统一成 JSON，字段如下：

一条完整的意见长这样：

{ "id": "9f4e2b8f-3a1d-4c7a-b2a4-8e5f1d0a9f22", "commit": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e", "file": "src/main.go", "line": 42, "severity": "error", "message": "strconv.Atoi 的错误没有处理，建议在调用前先校验输入", "status": "open", "author": "senior@example.com", "created_at": "2025-03-14T09:30:00Z" }

为什么要用 JSON 而不是纯文本？因为后续的list、check、report命令都可以直接交给 jq 处理，规则引擎按severity和status过滤，报表按author分组，都不需要再做自然语言理解。结构化之后，工具能做成什么程度，取决于我们怎么组合这些字段。

2.3 CLI 命令集的设定

工具的命令行入口我命名为rv，取 review 的缩写。命令不多，但每一条都对应一个实际场景。

这组命令的设计目标是：一个开发者从提交代码到合并代码，全程不需要离开终端。当然，这不意味着强迫大家都用终端，配合 IDE 的 Git 插件也完全没问题，因为底层操作都是标准 Git 命令。

2.4 与平台协同的边界

有人可能会问，既然 GitHub/GitLab 已经有评审界面，为什么还要再来一套命令行？我的观点是：不冲突，甚至可以互补。平台上的评论适合快速交互，但很难离线处理和自动归档。open-code-review 的定位是“评审数据层”，你可以继续在网页上看 diff、点评论，最后由一个脚本把平台上的评论同步成 Notes；也可以完全用命令行走一遍。

我保留了一个 webhook 桥接目录，用来监听 GitHub/GitLab 的评论事件，并把新评论以 JSON 格式追加到对应的 commit note。这样做的好处是：团队还是用熟悉的平台交互，但底层数据统一沉淀到了 Git Notes，后续统计、门禁、审计都从同一份数据源读取，而不是每个平台一套 API。

3. 核心实现解析：把评审变成工程化数据

3.1 提交规范与变更范围计算

任何评审流程都躲不开一件事：这次提交到底改了什么、为什么改。没有上下文，评审者只能逐行猜。我在 open-code-review 里引入的第一个硬性检查就是提交信息规范。推荐使用 Conventional Commits，这不算新鲜，但确实最有效。

pre-push hook 里我放了一段很短的解析脚本，检查提交信息是否符合规范：

#!/usr/bin/env bash msg=$(git log -1 --pretty=%s) pattern='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-zA-Z0-9_-]+\))?!?: .+' if [[ ! "$msg" =~ $pattern ]]; then echo "commit message 不符合 Conventional Commits 规范" echo "示例: feat(user): 增加登录注册接口" exit 1 fi

这段脚本是给团队立规矩的第一道门槛。提交信息是评审者在 diff 之前看到的第一份材料，如果材料本身不清不楚，后面评审质量一定会打折扣。

变更范围的计算则是另一个关键。不能用git diff origin/main HEAD简单完事，因为在合并origin/main之后，你的分支里可能混进了别人的提交。正确做法是先找合并基点：

base=$(git merge-base origin/main HEAD) changed_files=$(git diff-tree --no-commit-id --name-only -r "$base" HEAD)

拿到变更文件列表后，我会用.open-code-review.yml里的过滤规则排除掉lockfile、生成的dist目录等非源码内容。这样评审者看的是真正需要人脑判断的代码，而不是 3000 行打包产物。

3.2 意见写入与读取的实现逻辑

核心的读写在rv comment和rv list两个命令里。写入时每一条意见都是一行 JSON，追加到当前 commit 的 Git Note 上：

function rv_comment() { local file="$1" local line="$2" local severity="$3" local message="$4" local commit="$5" local author="$6" local json json=$(printf '{"id":"%s","commit":"%s","file":"%s","line":%s,"severity":"%s","message":"%s","status":"open","author":"%s","created_at":"%s"}' \ "$(uuidgen)" "$commit" "$file" "$line" "$severity" "$message" "$author" "$(date -u +%FT%TZ)") if git notes --ref=code-review show "$commit" >/dev/null 2>&1; then git notes --ref=code-review append -m "$json" else git notes --ref=code-review add -f -m "$json" fi }

这里有个细节：我先判断当前 commit 是否已经有 note，有就用 append，没有就用 add。append 会在原来的 note 末尾追加一段，不会覆盖前面的意见。为什么不用一个文件从头写到尾？因为评审是一个渐进过程，作者改一版，评审者再追加一版，追加模式可以保留完整历史。

读取的时候，我会把当前分支所有 commit 的 note 拼起来，再用 jq 按状态过滤：

git log --format=%H | while read c; do git notes --ref=code-review show "$c" 2>/dev/null done | jq -s 'map(select(.status == "open"))'

要注意的是，jq 的-s会先把所有对象读进数组，然后再过滤。如果仓库很大、意见很多，性能会有点吃紧。我目前的处理是加一个--since参数，只扫描最近指定天数的 commit，适合大多数日常迭代场景。

3.3 评审状态机与门禁策略

评审意见不是一句说了就完的留言，它应该有明确生命周期。我定义了三种状态：

1. open：刚提出的问题，等待处理。
2. resolved：作者确认修改或处理完毕。
3. acknowledged：评审者认为可以接受当前方案，相当于“知道了，但不必改”。

状态流转规则如下：

open -> resolved # 作者修复，评审者确认 open -> acknowledged # 价值不高，双方同意接受 resolved -> open # 评审者复查后不满意，重新打开

为什么要单独保留acknowledged？因为不是所有 code review 意见都必须改。有些属于风格偏好，有些是“可以更好但不是必须”。如果所有意见都必须是 resolved，团队会被逼着做无效修改。保留一个显式的“接受现状”状态，反而更贴近现实。

门禁策略在配置文件中定义。比如：

review: required_approvals: 1 block_on: - error - warning ignore: - nit

这里的含义是：至少需要一个人 approve，所有 error 和 warning 级别意见必须处理完，而 nit 级别的意见可以忽略。这套规则会被rv check --strict执行，放进 CI 作为合并的 hard gate。这样评审结论就不再靠口头共识，而是由状态机和配置组合出来的确定性结果。

3.4 在 CI 流水线里跑起来

我最初只用本地 hook 做拦截，后来发现流水线上的反馈才更权威。以 GitHub Actions 为例，我在工作流里加了这样一段：

- uses: actions/checkout@v4 with: fetch-depth: 0 - name: Fetch review notes run: | git fetch origin refs/notes/code-review:refs/notes/code-review || true - name: Run review gate run: | rv check --base origin/main --strict

有两个细节必须提醒：第一，fetch-depth: 0不是为了炫技，而是因为rv check需要拿到完整历史才能计算合并基点和 commit 链；第二，拉 notes 的命令后面加了|| true，因为新仓库可能还没有任何评审 notes，此时 fetch 失败是正常的，不应该打断流水线。

在 GitLab CI 里同理，只需要保证 runner 上安装好rv，然后在before_script里把 notes ref 拉下来，后面可以复用同样的命令。这套设计的好处是：只要目标环境能跑 Git，就能用 open-code-review，门槛很低。

4. 从提交到合并：完整的团队操作流

4.1 初始化仓库

第一步先安装工具。我提供了三种方式：go install、下载二进制、或者直接跑安装脚本。安装完成后进入项目根目录，执行：

rv init --remote origin

这条命令会做四件事：

1. 生成.open-code-review.yml配置文件。
2. 安装 pre-push hook，在推送前检查提交信息。
3. 配置 remote 的 notes 推送范围。
4. 创建refs/notes/code-review引用目录。

为了让评审 notes 能和其他代码一起推送，需要额外执行一次 push 配置：

git config --add remote.origin.push refs/notes/*:refs/notes/*

如果不加这一步，后面你在本地用git push推送代码时，notes 并不会自动跟着走。我第一次测试时就踩了这个坑，以为 notes 会在远端自动出现，结果拉下来空空如也。

4.2 开发者提交流程

一个正常功能分支的提交流程大概是这样的：

git checkout -b feature/add-login # 写代码、跑测试 git commit -m "feat(auth): 增加登录接口和会话校验" git push origin feature/add-login rv submit --base main

rv submit会计算出相对 main 的合并基点和变更文件，然后把这次变更的信息登记到 notes 里，并打印一个简短的评审摘要：

[open-code-review] 提交已登记 变更文件: 5 新增行数: 128 删除行数: 16 关联 commit: 9f8e7d6... 请运行 rv list 查看评审状态。

开发者看到这个摘要，就会对“这次变更有多大”有个概念。如果提交信息不符合规范，pre-push hook 会在推送之前就拦截，这比 CI 里再报错要快得多，也减少了一次无意义的 push。

4.3 评审者怎么看、怎么评

评审者接到通知后，先拉分支：

git fetch origin feature/add-login git checkout feature/add-login rv list

rv list的输出会列出所有 open 状态的意见，包含文件、行号和作者。要是还没有人评审，会提示“暂无未解决意见”。接下来看代码，发现问题就写评论，不离开终端：

rv comment --file src/auth.go --line 67 --severity error \ --message "token 过期后没有做错误处理，用户会看到 500，建议加一个鉴权失败的返回"

这条意见写入后，作者下次运行rv list就能看到。按我的经验，这种结构化对话比在 IM 里发一句“那个 token 你处理一下”要清楚得多。因为同一时间可能有多个评审者，每条意见都有自己的 id 和作者，不会混在一起。

如果看到的是主观风格问题，比如命名不符合团队偏好，可以用--severity nit打标，不阻塞合并。这样评审者不需要为了逼死强迫症，搞得整个流程充满火药味。

4.4 维护者合并与归档

作者处理完意见后，把状态更新为resolved：

rv resolve <意见id> --reason "已增加过期判断并补充测试"

评审者复查后如果满意，可以跑一次门禁：

rv check --strict

输出会明确告诉你：error 警告是否清零、approval 是否满足、当前分支是否可以合并。CI 里也配置了检查，双重保险。

合并时我建议使用 fast-forward merge 或者 squash merge，尽量保持 main 分支线性。合并完成后运行：

rv report --format markdown > review-2025-03-14.md

把这次评审报告归档到 docs 目录或者附在 project 文档里。很多团队从来不做评审复盘，导致同样的低级错误反复出现。有了这份报告，你至少能知道这个季度团队主要在哪些问题上“翻车”，下个季度的 code review 重点自然就出来了。

5. 常见问题与排查技巧

5.1 Git Notes 冲突

多人同时往同一个分支的某个 commit 追加评审意见时，Git Notes 推送可能会冲突。现象是git push报! [rejected] refs/notes/code-review -> refs/notes/code-review (fetch first)。

解决办法也不复杂：

git fetch origin refs/notes/code-review:refs/notes/code-review git notes --ref=code-review merge origin/code-review git push origin refs/notes/code-review

不过更稳妥的做法是在团队里约定：同一个 commit 的评审尽量由一个 reviewer 汇总更新，不要两个人同时往同一个 commit 上 append。我在设计时其实也在考虑把 notes 按评审者拆分，比如review/<username>，最后统一汇总。目前版本我保持了一个 notes ref，因为配置简单、审计方便，但如果你团队人很多，建议给每个评审者单独一个 ref 来减少冲突。

5.2 评论行号漂移

代码不是静止的。作者收到意见后改了文件，原来第 42 行的问题可能已经跑到第 10 行去了。基于“提交时快照”的 line 字段，不是绝对坐标。

我目前的处理办法是：每条意见除了记录line，还会记录文件中的上下文片段（message 里带上关键函数名），让评审者能根据语义找到对应位置。在生成 diff 报告时，我会用 blob hash 做一次近似映射，但这无法做到像 GitHub 那样智能，毕竟我们没有平台级的 diff 分析引擎。

所以这里我把丑话说在前面：open-code-review 的定位不是替代平台评审体验，而是让评审数据更开放、流程更硬。如果你特别依赖“自动追踪到最新行”，那还是建议在平台上做交互。

5.3 CI 里 Notes 拉不下来

常见问题有两种。第一种是 checkout 的深度不够，历史被截断，git fetch origin refs/notes/code-review连 notes ref 都找不到。解决方法是把 checkout step 的fetch-depth设成 0。

第二种是私有仓库的 permission 不够。GitHub Actions 默认的GITHUB_TOKEN只能访问当前仓库，只要你的 notes ref 也在同一个仓库，理论上没问题。但如果你的 notes 单独放在了另一个仓库，就需要额外配一个 Personal Access Token 或者 SSH Deploy Key。这个和普通代码拉取权限规则完全一致，并不特殊。

5.4 团队不愿意用怎么办

工具再轻量，也会有人觉得多一步麻烦。我的经验是不要一上来就全面推行，更不要拿 hook 卡死所有人的提交。先把试用范围控制在一个小项目或者一个新功能分支，让几个资深工程师带头用。

等到他们通过rv report产出了几份高质量的评审记录，再把这些记录在周会或者文档里展示，其他人会看到“原来评审意见可以留下这么清晰的痕迹”。看到收益之后，团队自己就会愿意用。我遇到过不少一开始嘴上说“麻烦”的人，后来反而最依赖rv list检查自己还有什么没改完。

6. 一点个人体会

做 open-code-review 这个项目，给我最大的感触是：好的代码评审，不是靠更强硬的工具逼出来的，而是靠降低记录的摩擦换来的。过去大家把意见随手写在聊天框里，是因为打开网页评论往往要切上下文；现在只要在终端里把命令补完整，意见就能自动归档、自动跟踪，这条路径变短了，评审质量自然会上来。

我也踩过不少坑，比如最开始用纯文本存意见导致解析崩溃，又被 Git Notes 并发写坑过一轮，后来才一步步把数据模型、状态机、门禁策略这些细节补全。如果你也在纠结团队的 code review，我的建议是先从“让每一条意见都有状态”开始，不要一上来就上重型系统。先记录，再跟踪，最后才谈门禁。没有记录，后面一切都是空的。