1. 为什么我会写 open-code-review 这个工具

做代码审查（code review）这件事，开发团队里永远是“人人都知道重要，但推进起来各种难受”。我看过很多团队的状态：新人不敢说话，老人没空细看，代码合并全靠一个人点头，线上出了事故翻代码历史才发现问题早在 review 环节就漏过去了。市面上静态检查工具不少，但只能抓格式、未使用变量这类表层问题，真正的并发隐患、异常处理缺失、业务逻辑漏洞，还是得靠人眼。可人眼会疲劳、会偏袒、会漏，尤其在一个几百行的 PR 里。

我平时在多个团队项目里做技术评审，也维护几个开源仓库，每天要看的 PR 数量不小。起初想找一个现成的 code review 辅助工具，把差异代码丢进去，能帮忙挑出逻辑问题、安全隐患、边界条件，但试了一圈发现：要么只支持 GitHub 生态，要么报告写得像模板，要么太重，装完一堆依赖。后来我干脆自己动手写了一个命令行工具，名字就叫 open-code-review。它做几件简单的事：把 Git 仓库里的提交差异按文件、按函数块拆开，送到大模型做结构化审查，再把结果整理成可读的报告。整个流程可以在本地跑，也可以接到 CI 里自动执行。

这个项目开源后，我把它用于自己维护的几个仓库，也在两个小团队里跑了几周，实测下来确实能分担不少 review 的重复劳动。这篇文章把它的设计思路、核心实现和踩坑记录完整写一遍，适合想给团队引入 AI 辅助 code review、但对工具原理还不太清楚的开发者参考。看完之后你可以直接复现整套流程，也可以根据自己的技术栈改成内部工具。

2. 核心需求与整体设计思路

2.1 人工 review 的三个痛点

先说清楚为什么需要这样一个工具。人工 review 有三个典型的痛点，凡是做过技术管理的朋友应该都深有体会。

第一，注意力窗口有限。一个正常人连续看 30 到 40 分钟代码，后面就开始走神。而团队里的 PR 往往集中在下午提交，等于在一天最疲惫的时候逼大家集中注意力，效率自然不高。我统计过自己日常 review 的耗时，一个 500 行的 PR，认真看完至少需要 40 分钟，其中有相当一部分时间浪费在无意义的格式争论上。

第二，标准不统一。同样的一个函数里，每个人的风格偏好不同，有人喜欢早期 return，有人喜欢嵌套 if，review 意见经常变成风格争论而不是问题讨论。当团队缺少统一的检查清单时，review 质量完全取决于评审人当时的经验水平，换个人意见可能完全不同。

第三，经验依赖强。资深工程师能看出某些代码在特定并发场景下会死锁，但新人看不出来。这种经验很难通过文档传承，只能靠一份一份代码积累。而大模型在训练阶段读过海量开源代码，对常见缺陷模式的认识广度，往往超过单个人类工程师。

2.2 open-code-review 的定位与设计理念

open-code-review 的定位不是一个“自动 review 机器人”，而是一个“辅助人做 review 的放大镜”。它不试图替代工程师，而是把最容易疲劳、最容易遗漏的部分交给模型去扫第一遍，然后让人把精力集中在风险最高的反馈上。

名字里的 “open” 有两层意思。第一层面当然是开源，整个工具以 MIT 协议开放，代码随便改。第二层意思是“开放的审查流程”，它不是黑盒，不会只丢给你一个分数，而是把每个问题的文件路径、行号、严重程度、修改建议全部展开，每次审查的记录都保留在本地，可以复盘、可以追溯。

选型上我坚持三点。第一，本地优先。代码是团队最敏感的资产，很多企业不允许把代码片段发到外部服务，所以我设计了可插拔的模型后端，既支持 OpenAI 兼容接口，也支持本地部署的模型。第二，命令行优先。CLI 最容易与脚本、CI 集成，不需要额外的前端服务，维护成本低。第三，报告要结构化。我输出 Markdown 和 JSON 两种格式，Markdown 给人看，JSON 给下游流程用，比如自动创建评论、联动缺陷管理工具。

2.3 工作流程与数据流

工具本身用 Python 编写，原因很实际：团队里 Python 熟练度最高，而且处理文本、调用 API 都非常顺手。核心依赖只有 Git 命令行、Requests 和 pyyaml，安装起来很简单。整个工作流程可以分成四个阶段。

第一阶段是获取差异：读取指定分支与目标分支之间的 diff，或者指定提交范围的 diff。第二阶段是差异切分：将 diff 按文件、按函数或类块进一步切分，避免一次请求携带过长上下文。第三阶段是模型审查：为每个代码块构造统一的 prompt，调用大模型生成问题列表与修改建议。第四阶段是汇总输出：把各个代码块的审查结果合并，按文件路径、严重级别排序，生成最终报告。

这个过程看起来简单，真正的难点在第二阶段和第三阶段。第二阶段直接决定模型看到的上下文质量，切分得不好，模型容易把上下文搞混；第三阶段的 prompt 设计则决定审查结果的准确率，prompt 写得好不好，出来的结果天差地别。后面我会把这两部分展开讲，这是我迭代了多个版本之后沉淀下来的经验。

3. 核心功能拆解与实现细节

3.1 diff 获取与差异切分

先说 diff 获取。open-code-review 使用 Git 原生的 diff 命令，支持三种模式：对比分支、对比提交、对比暂存区。为了让模型理解改动的上下文，我加了--unified=3参数，也就是上下各保留三行上下文。这个参数其实很有讲究，太少模型看不懂改动前后发生了什么，太多又浪费 token，实测下来三行是比较平衡的选择。

拿到整个 diff 后，真正的难点来了：如何把 diff 切成适合模型阅读的单位。我先把整个 diff 按文件拆开，然后针对每个文件，再按新增或变更的函数块切分。这一步用正则解析 diff 头里的@@ ... @@块，再结合语言特定的函数边界识别来完成。比如 Python 用缩进级别判断函数结束位置，JavaScript 用花括号配对判断作用域范围。

切分完之后，还需要过滤掉不适合审查的内容。二进制文件、锁文件、打包产物、min 之后的 JS、自动生成的代码，这些都应该在早期过滤掉。所以我在配置里提供了ignore_files参数，默认已经包含了package-lock.json、yarn.lock、vendor/、dist/这些常见目录。早期版本我没做过滤，结果把几千行生成的 JS 文件喂给模型，不仅浪费 token，审查结果还全是胡话。

3.2 AI 审查引擎的 prompt 设计

prompt 是整个工具的灵魂，也是我迭代次数最多的模块。早期版本里，我直接让模型“检查这段代码有没有问题”，结果返回的全是泛泛而谈的风格建议，比如“建议增加注释”“代码格式不规范”，一点用都没有。后来我把 prompt 改成了结构化任务描述，才解决了这个问题。

简单说，我在 system prompt 中固定了审查者的角色和规则：第一，你是一名擅长指定语言的资深代码审查员；第二，重点关注逻辑错误、并发安全、资源泄漏、异常处理、安全漏洞、边界条件；第三，忽略纯代码风格问题，只报告可能导致 Bug、性能问题或安全风险的缺陷；第四，每个问题需要给出严重级别（critical / warning / info）、所在文件行号、问题描述、修改建议。

在 user prompt 中，我传入代码块本身和相关的上下文信息，例如文件路径、函数名、改动行号范围等。这样的设计让模型把注意力放在真正重要的问题上，而不是关心格式化。一个关键技巧是：永远告诉模型“这段代码会被用于生产环境”，它能显著提高对风险问题的敏感度。这个技巧是实践出来的，单纯说“帮忙检查”的时候模型会比较放松，加了这个前提之后，报告里 critical 级问题的占比会明显上升。

3.3 并行调用与结果聚合

模型推理是耗时操作，一个 PR 里有 10 个文件，如果串行调用可能要等十几分钟，这在 CI 里完全不可接受。所以我实现了并发调用，默认并发数是 4，可以通过参数调整。每个代码块都是独立请求，超时设置 60 秒，一旦某个请求失败不会影响其他块，失败信息会单独记录。

全部返回后进入聚合阶段。我会为每条问题生成一个唯一 ID，提取文件路径、行号、严重级别、建议文本，然后排序并输出。排序规则是：先按严重级别降序，再按文件路径和行号升序。这样的设计是为了保证工程师打开报告时，第一眼看到的就是最需要处理的 critical 级问题，而不是被一堆 info 级别的建议淹没。

这里有一个细节值得多说一句：模型返回的结果不一定总是完整的 JSON。为了让结果能结构化输出，我最初直接要求模型“返回 JSON”，但部分模型总会在 JSON 前后加一段解释文字。现在我在 prompt 里用硬性指令“只输出 JSON 内容，不要包含任何其他文字”，同时对输出做容错处理：先尝试直接解析，失败则用正则提取最外层的花括号或方括号再解析。如果仍然失败，就把原始输出原样保留在 Markdown 报告中，绝不因为解析失败就丢弃审查结果。

4. 工具安装与命令行实操

4.1 安装与配置

open-code-review 发布在 PyPI 上，安装只需要一行命令：

pip install open-code-review

安装前建议在虚拟环境里操作，避免和系统 Python 依赖冲突。配置分为两部分：模型连接配置与审查规则配置，统一放在当前目录的.ocr.toml文件里。以下是一份典型的配置示例：

[model] provider = "openai-compatible" base_url = "https://api.example.com/v1" api_key_env = "OCR_API_KEY" model = "gpt-4o-mini" max_tokens = 1024 temperature = 0.2 [review] language = "python" severity_filter = ["critical", "warning"] ignore_files = ["lock", "*.min.js", "vendor/"] max_diffs = 200 max_workers = 4

api_key_env表示从环境变量读取 API Key，这样 Key 不会写进配置文件，避免泄露风险。severity_filter可以过滤掉低价值信息。max_diffs限制提交给模型的代码块数量，防止单次审查内容过多。max_workers控制并发数，需要根据模型服务的限制调整。

4.2 常用命令示例

命令设计尽量贴近 Git 原生命令行风格，让开发者零学习成本：

# 对比当前分支与 main 分支 open-code-review -b main # 审查某两个提交之间的差异 open-code-review --from HEAD~3 --to HEAD # 只输出 JSON 格式，便于集成 open-code-review -b main --format json -o review.json # 指定并发数，在 CI 里跑（不输出详细过程） open-code-review -b main --ci

跑完一次后，终端里会看到一个包含各严重级别问题的统计表。输出文件默认生成review_report.md，内容是按文件分类的问题清单，每条问题带行号和建议，可以直接贴到 PR 评论里。整个使用过程不需要看图、不需要开网页、不需要额外服务，这也是 CLI 工具最大的优势：在任何环境里都能跑。

4.3 在 GitHub Actions 中自动执行

团队使用最频繁的场景是自动审查 PR。我提供一个 GitHub Actions 工作流示例，当开发者发起或更新 PR 时自动执行审查：

name: open-code-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: '3.11' - run: pip install open-code-review - run: open-code-review -b origin/${{ github.base_ref }} --format json --output review.json env: OCR_API_KEY: ${{ secrets.OCR_API_KEY }}

这里有两个非常关键的细节。第一个是fetch-depth: 0必须设，否则 Actions 只会克隆最新一次提交，git diff拿不到完整历史，对比分支时会直接失败。第二个是 API Key 一定用 GitHub Secrets 存储，不要直接写在 workflow 文件里。这两个坑我都踩过，一次是 CI 报错查了半天才发现是浅克隆引起的，另一次是在公开仓库的 workflow 里泄露了 Key，被迫重置。

4.4 对接不同模型平台的说明

模型对接采用 OpenAI 兼容接口，这是我的一个关键设计决策。目前市面上主流的大模型服务基本都提供了兼容接口，无论是 OpenAI、Anthropic，还是本地部署的 vLLM、Ollama，只需要改base_url和模型名即可。

如果团队条件允许部署本地模型，我推荐优先考虑本地方案。代码不外流，延迟可控，离线也能跑。我用 8B 左右的量化模型实验过，效果虽然不如大参数模型，但用来抓明显异常、空指针、资源没有释放这类问题已经够用。对于代码审查场景，模型大小不是唯一决定因素，合理切分代码块和精心设计的 prompt 往往能弥补模型能力的差距。

5. 实测效果与典型案例分析

5.1 一个真实捕获的并发问题

说一个让我印象深刻的案例。有一次工具对一段 Python 的缓存更新逻辑报了 critical 级问题，提示“检查并更新操作之间存在竞态条件”。我第一反应是不太信，因为那段代码是团队里一位资深开发写的，测试也都过了。但仔细一看，确实有问题：代码先if key not in cache:判断，再去执行cache[key] = calculate()，中间没有任何锁或原子操作。多线程下两个请求同时命中空缓存，就会重复计算，严重时还会写入不同值。

这种问题在人工 review 时非常难发现，因为单次执行看起来完全正确，只在并发高时才暴露。大模型每天读海量代码，对并发模式的训练样本很多，所以能一眼识别这种反模式。这个案例之后，团队里普遍对工具的价值有了实感。

5.2 误报与漏报的真实分布

很多人担心 AI review 误报多，我特意统计过几周的数据。我把模型审查结果与最终人工合并时的判断做了对比，对于 Python 和 JavaScript 代码块，误报率（模型报告但人工认为不是问题）大概在 15% 到 25% 之间。漏报率（人工发现问题但模型没报）大约在 10% 到 15% 之间。

这个数字说明两个事实：模型不能替代人工，但确实能帮助扩大覆盖面。最关键的是，模型报告的 critical 级问题里，80% 以上都对得上真实缺陷，这部分价值已经非常大。我把这个统计分析工具内置到了项目里，方便用户导出自己的误报数据，用来调整 prompt 和过滤规则。如果一个团队能连续记录两周的误报数据，再针对高频误报类型做规则过滤，准确率提升会非常明显。

5.3 报告内容长度控制

早期版本报告会输出大量建议，每段代码块平均 5 到 8 条，工程师看到一屏密密麻麻的内容反而懒得读，报告的作用大打折扣。后来我增加了“摘要优先”的策略：报告开头固定展示一段面向维护者的摘要，列出本次审查发现的 critical 与 warning 数量、涉及文件的列表，然后才是详细问题清单。

摘要段落采用固定模板，生成三条以内的核心观点。比如“本次审查发现 2 个 critical 问题，集中在用户认证模块和缓存更新逻辑；建议先处理认证模块的越权风险”。这样打开报告第一屏就能知道“这个 PR 值不值得合入前再看一眼”，大大提高了使用率。这个改动是我从运营思维里学来的：不是你输出什么，用户就看什么，而是用户容易看到什么，才真正有用。

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

6.1 diff 过大导致模型截断

现象：当 PR 改动的代码量很大，或者包含生成的 JS 文件时，单次调用很容易超出模型上下文限制，收到超时或截断错误。我在开发第一版时就遇到过，改动一个大型前端项目，一次审查直接把请求打爆。

解决方案：在配置中利用max_diffs限制提交给模型的代码块数量，同时开启文件过滤，排除dist、node_modules、vendor等目录。另外可以设置max_block_lines参数，把超过指定行数的代码块自动再次拆小。实用建议是：如果 PR 改动超过 20 个文件，建议分多次审查，或者先人工把高优先级文件挑出来，而不是一股脑全部丢给工具。

6.2 API 返回频繁失败

现象：并发数设得过高时，某些模型服务会触发限流，导致请求大规模失败，而且失败都是突然出现，让人以为是代码逻辑的问题。

解决方案：把max_workers调低，默认 4，必要时调到 2。同时我在代码里实现了指数退避重试：对 429 和 5xx 响应分别做最多 3 次重试，初始等待 2 秒，之后成倍增长。如果是本地模型，优先看显存占用和推理服务的并发配置，必要时降低模型最大请求数。

6.3 模型输出 JSON 解析失败

现象：为了让结果能结构化输出，我最初直接要求模型“返回 JSON”，但部分模型总会在 JSON 前后加一段解释文字，比如“好的，以下是问题的分析”，导致解析失败。

解决方案：现在我在 prompt 里使用“只输出 JSON 内容，不要包含任何其他文字”的指令，同时对输出做容错处理：先尝试直接解析，失败则用正则提取最外层的花括号或方括号再解析。如果仍然失败，就把原始输出原样保留在 Markdown 报告中，绝不因为解析失败就丢弃审查结果。这个方案看起来笨，实际效果非常好。

6.4 部分语言无法准确识别函数边界

现象：不同语言的函数定义语法差异很大。早期我用正则切分代码块，遇到 Kotlin 的fun和具有多层嵌套的 TypeScript 泛型时经常切分错误，导致代码块不完整，模型分析结果也不准。

解决方案：最终采用“行号范围 + 语言插件”的模式：对于常见语言，使用 tree-sitter 的 Python 绑定做语法级切分；对于其他语言，退回到基于缩进与大括号配对的启发式方案。如果你只是内部使用，还可以按约定在注释里写// ocr: block-start标记，工具会优先识别这些标记切分，这个方法最稳定。

6.5 CI 环境里 Key 泄露风险

现象：有用户在配置示例里直接把 API Key 写在了 workflow 文件里，等于公开泄露，这个必须避免。

解决方案：一定用 GitHub Secrets 或等价机制存储。工作流示例里我用${{ secrets.OCR_API_KEY }}而不是明文，同时在代码里要求 Key 只能来自环境变量，配置文件只记录环境变量名。本地开发时，则建议在.ocr.toml中使用api_key_env而不是直接填 Key。这个原则对任何内部工具都适用。

6.6 特殊代码导致误报集中

现象：如果项目里有大量“断言式代码”，比如assert isinstance(result, ExpectedType)，或者大量模板生成的重复结构，模型会反复报告同类问题。

解决方案：配置ignore_files之外，我还提供suggestion_rules，允许用户定义正则去过滤特定形式的问题描述。比如过滤掉包含“建议增加类型检查”这类泛泛意见的内容。这样经过一两周的使用，误报率会明显下降。建议每次发生误报时，顺手把问题特征的 regex 加到过滤规则里，积累一段时间后工具会越来越贴合你的项目风格。

以下是我整理的问题排查速查表，直接对照使用即可：

7. 影响范围与适用场景分析

7.1 适合哪些团队

open-code-review 最适合的是两类团队。一类是 5 到 50 人的小微技术团队，没有专职架构师，代码评审依赖少数几个技术骨干，工具可以帮骨干分担第一轮筛选。另一类是开源项目维护者，PR 来自世界各地，贡献者水平参差不齐，自动化 review 可以先把明显问题挡在 CI 阶段，维护者只需要关注核心逻辑。

不太适合的场景是：代码质量已经极高、PR 修改面很小、团队已经有完善的结对编程机制的团队。这种情况下工具带来的边际价值不大，反而可能增加噪音。判断标准很简单：如果团队大部分 PR 都要改超过 10 个文件，且人工 review 经常流于形式，那就值得引入；如果 PR 都很小、反馈又及时，可能并不需要额外工具。

7.2 语言支持状态

新版本里所有主流语言的覆盖率都在持续完善。目前 Python、JavaScript、TypeScript、Go、Java、Rust、C/C++、Swift、Kotlin、PHP 都支持函数块切分与审查。以下是语言支持的实测情况：

其中效果最好的是 Python 和 TypeScript，因为这类语言的常见缺陷模式在训练语料里极其丰富。C++ 和 Rust 因为涉及指针、宏、生命周期等复杂语义，效果稍弱，但依然能发现空指针解引用、隐藏的拷贝开销这类问题。如果你的主力语言不在列表里，工具会退化为按行号区间切分，功能依然可用，只是切分粒度没有那么精准。

7.3 与现有工具链的协作关系

open-code-review 并不替代现有的 lint 工具。ESLint、Ruff、Clippy 这些工具负责代码风格和确定性问题检查，比如缩进、未使用的变量、明显的空指针；open-code-review 负责需要语义理解的逻辑审查，比如并发安全、异常处理、权限控制。两者定位完全不同，反而互补。

实际使用中，我的建议是先在 CI 里跑 lint，通过后再跑 open-code-review。这样可以把确定性问题拦在第一层，让 AI 审查专注于更深层次的逻辑。如果项目已经配置了 SonarQube 或者 CodeClimate，可以在它们之后接入，工具生成的 JSON 报告可以直接用于二次分析。

8. 使用一段时间后的经验总结

工具从第一版到现在经历了很多调整，几个最有价值的经验值得单独说。

第一，prompt 里的角色设定必须明确。与其把模型当作一个通用问答助手，不如把它当作一个“有特定检查清单的资深评审人”。角色越具体，结果越稳定。我现在已经考虑把检查清单做成可配置项，让团队根据自己的技术栈定义检查重点，比如支付系统团队可能更关注金额精度和幂等性，实时通信团队可能更关注线程安全和超时处理。

第二，结果呈现方式决定工具能不能被团队接受。第一版工具输出一个纯文本长列表，结果团队里几乎没有人打开看。改成结构化 Markdown 报告，并且把 critical 问题置顶之后，反馈明显变好。界面和交互细节在内部工具中的重要性，远高于一般人想象。好工具和不好用的工具，功能差距可能只有 20%，但接受度差距可能是十倍。

第三，不要追求一次解决所有问题。AI code review 解决的是“覆盖率”问题，不是“正确率”问题。它帮你把注意力引导到最可能有问题的几处代码上，剩下的深度判断还是要靠人。能在 15 分钟里帮工程师少读 500 行无关紧要的 diff，就已经是成功，不用指望它替代人工评审的思考过程。

如果后续我再扩展这个项目，会优先考虑三个方向：支持自定义检查清单、接入更多代码托管平台的评论 API、以及把历史误报数据用于 prompt 的自动微调。代码仓库里已经放了不少示例配置和插件骨架，有兴趣的朋友可以直接拿去改。如果在用的过程中遇到 diff 切分或者结果解析的问题，欢迎在项目仓库提 issue，我会尽量回复。