企业官网建设流程全解析

open-code-review 这个项目，起初是我在 GitHub 上翻代码审查工具时偶然看到的。当时我们团队正被一个老问题折磨：每个 MR 都有人 review，但意见大多是 LGTM，偶尔冒出几条关于变量命名的建议，真正能拦住线上故障的反馈几乎没有。代码评审变成了一个仪式，而不是质量防线。看到 open-code-review 的 README 时，我第一反应是“又一个套壳调 API 的工具”，但仔细读完后发现它的设计思路和我想要的自动化评审工作流很接近——规则可配置、模型可插拔、结果可追踪。于是我在自己维护的服务端项目里试跑了一个多月，中间踩了不少坑，也沉淀了一些真实数据。这篇就当作一次完整的使用报告，把部署方式、核心原理、常见坑位一次说清楚。

1. 代码审查为什么总在“走流程”：真实痛点与 open-code-review 的切入点

1.1 从 LGTM 现象说起

先说个数据：我们团队一共 8 个后端开发，一个迭代平均产生 47 个 MR。我抽样看了近三个月的 review 记录，发现纯 LGTM（Looks Good To Me）或者只有“加个空格”“方法名改成动词开头”这类意见的比例高得吓人。这背后不是大家不负责，而是人性——大多数人看别人的代码时，只要逻辑能跑通、风格和自己差不多，就不愿意花精力去挑刺。尤其是面对一个几百行的大 MR，人的注意力天然会衰减，看到后面基本是在扫视，根本谈不上深度审阅。

但问题恰恰出在这里。代码评审最大的价值是拦截那些“测试没覆盖到的逻辑漏洞”“资源没有释放”“异常被悄悄吞掉”的问题，这些恰恰需要逐行读代码才能发现。人的精力有限，机器又没有判断力，于是两边都不讨好。

1.2 open-code-review 的设计前提：机器负责过滤，人负责判断

open-code-review 的定位不是“替代人做 review”，而是先把人最容易疲劳的那部分工作接过去。它做的事情可以拆成三层：

• 扫描层：读取 MR/PR 的 diff，分析改动文件和函数级上下文。
• 推理层：把 diff、文件内容、仓库约定规则拼成提示词，交给大模型或本地模型做语义分析。
• 反馈层：把模型返回的意见结构化，以评论形式写回 Git 平台，或者输出成 Markdown 报告。

这个分层很关键。它不像 SonarQube 那样只做静态规则匹配，也不像某些 AI 工具那样直接把整个 diff 丢给模型然后“听天由命”。它给规则留了接口，让团队能把自身规范注入进去，同时又用模型补足了静态检查看不懂语义的短板。

1.3 它和 Jenkins、SonarQube 这些老牌工具的区别

我们项目里原来就有 SonarQube，为什么还要再引入一个审查工具？因为两者的抽象层级完全不同。SonarQube 的核心是“已知坏味道的探测”，它能告诉你这段代码重复了、圈复杂度超标了，但它基本不知道这段代码的业务意图。open-code-review 走的是“用自然语言描述期望约束”的路子，比如你可以配一条规则：检查所有新增的外部输入是否在进入 SQL 查询前做了参数化处理。这种规则没法用静态扫描实现，但用模型却能得到一个可用的判断。

当然，这里说的“可用”不是 100% 准确。经过我们一个月的实测，它的意见里大约有 15% 属于误报，这个比例需要配合规则调整才能降下来。但它最让我满意的一点是，所有意见都带着 diff 位置和理由，开发者在 MR 页面就能直接回复讨论，不用跳转到另一个系统。

2. 拆开 open-code-review 的引擎盖：一个 PR 从推送到产出意见的完整链路

2.1 输入端：怎么拿到一次变更的 diff

open-code-review 目前支持 GitHub、GitLab 和 Gitea 三种平台。拿 GitHub 举例，它通过 Octokit 库监听 Pull Request 的opened、synchronize和reopened事件。拿到事件后不是直接把整个 PR 内容甩给模型，而是先拉取base..head的 diff，再过滤掉非代码文件（比如 lock 文件、图片、自动生成的 protobuf），这个过程叫做 diff 清洗。

这里有个容易忽略的细节：它默认只审查新增和修改的行，不审查上下文里未改动的部分。这样既控制了 token 消耗，也避免了模型把历史代码的问题算到本次改动头上。如果你想让 review 覆盖整个文件，比如检查一个“新增私有方法但整个类的风格都不对”的问题，可以在配置里把review_scope从diff改成diff_plus_surrounding，会让模型额外读取每个改动块附近 10 行上下文。

2.2 中间层：规则引擎和提示词模板如何配合

这一层是 open-code-review 的精华。它内置了一个规则引擎，每条规则由三部分组成：

实际运行时，工具会把 diff 按文件拆分，然后对每个文件分别检查规则作用域。命中的规则会生成各自的提示词，和这个文件独有的“变更块信息”拼在一起，再调用模型。这种“规则-提示词”分离的模式，让你可以用一份配置管理不同语言的审查策略，比如 Go 项目重点关注错误处理和并发安全，前端项目则重点关注 useEffect 依赖和 XSS 场景。

下面是一条简化后的规则示例：

rules: - name: unclosed-resource scope: - "**/*.java" prompt: | 检查这段 diff 中是否有打开文件、网络连接、数据库连接等资源但未在 finally 或 try-with-resources 中关闭的情况。 如果发现疑似问题，请输出： 1. 文件路径 2. 行号 3. 问题类型 4. 修复建议 5. 置信度（high/medium/low） severity: critical

你可以看到，提示词里没有要求模型“review 所有代码”，而是聚焦在当前规则要查的单一维度。这个设计很聪明——单一规则 + 小范围 diff，模型回答的准确率会比“请全面评审这段代码”高很多。我们后来自己做对比测试，发现聚焦式提示词的误报率能降低 30% 以上。

2.3 模型后端抽象：不是只能接 OpenAI

现在很多 AI 工具都绑定某一家大模型厂商，open-code-review 没有这么做。它定义了一个ModelProvider接口，只要实现chat()方法就能接新的模型。官方支持 OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini，以及通过 Ollama 启动的本地模型（比如 llama3.1、Qwen2.5）。

这个抽象层对我们的实际意义很大。公司内部有合规要求，代码仓库不能出网，所以我们最终走的是内网部署的 Ollama 方案，模型用的 Qwen2.5-Coder-32B。虽然效果比 GPT-4o 略弱，尤其在复杂语义推理上还有差距，但胜在数据不出内网，能满足安全审计要求。如果你没有这种限制，直接用 OpenAI 会省心很多，按我们的测试，GPT-4o-mini 的性价比最高，多数规则场景足够用了。

2.4 输出端：如何把意见写回 Pull Request

open-code-review 拿到模型输出后，不会原样贴上去。它会先经过一个解析器，把回答里的“文件路径、行号、问题类型、严重级别”抽取成结构化字段，然后在生成的评论里按严重级别排序。Critical 和 High 的评论会带上醒目标记，Low 级别（比如命名建议）默认折叠在<details>块里，避免刷屏。

评论粒度也分两种模式：pr_review模式是在 PR 页面生成一条整体 review，inline_comments模式会精确到 diff 的某一行发表行内评论。我们最后选了行内评论，因为开发者在网页上直接就能看到对应代码，上下文不需要来回跳。

这里要提一个细节：如果不专门配置 webhook secret，open-code-review 默认只发送评论，不修改 PR 状态。也就是说它不会自动 approve 或 request changes，避免出现“机器人卡流程”的尴尬。你想让它生效，可以在配置里开启auto_request_changes_on_critical，但我不太建议，理由后文会展开。

3. 30 分钟跑通第一个自动 Code Review：从安装到接入 GitHub Actions

3.1 环境准备

open-code-review 的运行时是 Node.js 18+，安装方式用的是 npm 全局包。前提是你有一台能访问 GitHub API 的机器，以及一个大模型的 API Key。如果只想试试，本地 Mac 或 Linux 都可以，Windows 下建议用 WSL，主要是路径解析在 Windows 上偶尔会有小毛病。

# 安装 CLI npm install -g open-code-review # 查看版本与帮助 ocr --version ocr --help

初始化配置可以用向导：

ocr init

它会问你几个问题：代码托管平台（GitHub/GitLab/Gitea）、平台访问 Token、模型供应商、模型名称。回答完之后生成一个open-code-review.yml文件。

3.2 配置一个最小可用的 YAML 文件

下面这份配置是我个人觉得最适合起步的模板，兼顾了审查覆盖面和误报控制：

platform: provider: github token_env: GITHUB_TOKEN model: provider: openai name: gpt-4o-mini temperature: 0 max_tokens: 2048 review: scope: diff_plus_surrounding surrounding_lines: 10 min_severity: medium inline_comments: true rules: - name: error-handling scope: - "**/*.go" prompt: | 检查这段 diff 中是否忽略了错误返回值，特别是调用了返回 error 的函数后没有检查 err。 如果发现，请给出文件路径、行号、可能造成的后果和修复建议。 severity: high - name: security-hotspot scope: - "**/*.{js,ts,py,java,go}" prompt: | 检查这段 diff 中是否存在将用户输入直接拼接进 SQL、shell 命令或 HTML 输出的情况。 如果存在，请标记为 high 置信度，并说明注入路径。 severity: critical - name: concurrency-issues scope: - "**/*.go" prompt: | 检查这段 diff 中的并发控制。重点看共享变量是否有锁保护、channel 是否正确关闭、是否在循环中错误使用 goroutine 闭包变量。 severity: high

temperature我强烈建议设成 0。代码审查需要确定性，不需要模型发挥想象力。max_tokens设太大反而容易让模型输出一些与问题无关的解释，2048 足够覆盖单文件 diff 的回复。

3.3 本地命令行模式

在配置好 model API Key 之后，你可以先用本地命令试一试，不用等 Webhook 触发。命令很简单：

export GITHUB_TOKEN=ghp_xxx export OPENAI_API_KEY=sk-xxx ocr review --platform github --repo yourorg/yourrepo --pr 123

这个命令会拉取 PR 123 的 diff，跑完规则后，把审查结果同时输出到终端和ocr-report.md。第一次跑完建议打开这个 Markdown 文件看看，确认模型输出和规则预期是否一致，再考虑接 CI。

3.4 在 GitHub Actions 里跑自动审查

接入 GitHub Actions 其实是在仓库里添加一个 workflow 文件，里面调用 open-code-review 的 action。我们把原来的 workflow 命名为.github/workflows/code-review.yml，核心部分长这样：

name: open-code-review on: pull_request: types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "20" - run: npm install -g open-code-review - name: Run open-code-review run: | ocr review \ --platform github \ --repo ${{ github.repository }} \ --pr ${{ github.event.pull_request.number }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

要注意permissions里必须给pull-requests: write，否则评论发不出去。GITHUB_TOKEN是 GitHub 自动生成的，不需要自己创建 Secret；OPENAI_API_KEY则需要到仓库 Settings 的 Secrets 中手动添加。

3.5 GitLab CI 的差异化配置

如果你用的是 GitLab，流程也类似，只是触发方式换成 Merge Request 事件，环境变量名稍有不同。下面是一个可以套用的.gitlab-ci.yml片段：

code-review: stage: test image: node:20 only: - merge_requests script: - npm install -g open-code-review - ocr review --platform gitlab --project $CI_PROJECT_ID --mr $CI_MERGE_REQUEST_IID variables: GITLAB_TOKEN: $GITLAB_TOKEN OPENAI_API_KEY: $OPENAI_API_KEY

GitLab 下要注意GITLAB_TOKEN需要使用一个具有api权限的 Personal Access Token，不能直接用 CI Job Token，否则拉取 diff 和评论接口会 403。

4. 我在真实项目里跑了一个月：47 个 MR 的统计与三位同事的反馈

4.1 命中率与关键数据

我把 open-code-review 接入的是公司一个外部 API 网关服务，Go 语言写的，平均每个 MR 改动量在 250 行左右。一个自然月里，它审查了 47 个 MR，一共生成 312 条意见，最终被开发者采纳或部分采纳的有 198 条，整体采纳率 63.5%。

单纯看这个数字可能没什么感觉，但对比之前的人工 review 数据就明显了。以前这 47 个 MR 里人工提出的有效问题大概只有 30 多个，而且集中在几个主力开发负责的 MR 上——大家会更认真地看熟人的代码，对不熟悉的模块基本放弃。自动化工具没有这种偏好，它对每个文件一视同仁。

按严重级别看，Critical 和 High 级别的意见采纳率最高，达到 82%。这些意见集中在 SQL 注入、goroutine 闭包捕获变量、错误被吞掉这几类，基本都是真实 bug 或隐患。Medium 级别采纳率 51%，Low 级别只有 12%，这和预期相符，Low 多为风格建议，每个人偏好不同。

4.2 误报重灾区在哪里

312 条意见里有 47 条被明确标记为误报，误报率约 15%。这些误报高度集中在两类规则：

第一类是并发安全。Go 语言里很多代码看起来是“并发访问共享变量”，但实际通过sync/atomic操作或 channel 做了同步，模型经常会忽略上下文中的同步机制。例如有一段代码先声明var counter int64，但所有读写都经过atomic.AddInt64，模型仍然报了一个“并发读写数据竞争”的 medium 意见。

第二类是错误处理规则。模型对if err != nil { return err }这种标准模式识别得不错，但对“调用defer关闭资源时忽略错误”的场景会产生误判。它会在某些已经被安全 defer 的代码上提示“未检查关闭错误”。这类误报虽然不影响开发决策，但会消耗人的注意力。

后来我调整了对应规则的 prompt，加了一句话：“如果错误处理逻辑已经通过 defer 或 atomic 机制完成，请不要报告。”误报率立刻降到了 9% 左右，这也印证了规则模板的调整空间很大。

4.3 同事们的真实反馈

我采访了团队里三位意见最多的同事。一位资深后端觉得“大部分意见有参考价值，但偶尔会因为行内评论太多而产生焦虑感”；一位刚转 Go 的同事说“这工具帮他把很多不熟悉的最佳实践补上了，比如错误包装时带上下文信息”；还有一位负责运维平台的老哥比较直接，他说“这个东西最有用的一点是能让新人少来问我基础问题，但有些意见确实像在没话找话”。

综合来看，团队没有出现“抵制机器人”的情绪，前提是意见不能刷屏。我们把 Low 级别的评论默认折叠，Critical/High 才直接显示。这个设计很重要，如果所有级别都平铺在页面里，开发者很快就会选择忽略这个机器人。

5. 避坑记录：AI Code Review 落地中最容易翻车的五个细节

5.1 Token 消耗：账要算清楚

很多人以为 AI 代码审查能一直免费跑，实际上 Token 消耗是一个被严重低估的成本。我们的一个 MR 平均 diff 在 200-300 行，加上上下文和规则提示词，单次审查大约消耗 8000-12000 个 input token。按 GPT-4o-mini 的定价，一个 MR 大概 0.01 美元，一个月几百个 MR 也就几美元，这个成本可以忽略。

但如果你用 GPT-4o 甚至更贵的模型，单次审查成本会飙升到 0.3 美元以上。之前我做过一次对比，配置长短提示词和模型分层很重要。建议是：默认用 mini 类模型跑全量规则，只有 diff 里出现敏感路径（比如支付、权限相关文件）时才用强模型二次复查。open-code-review 支持在规则里额外指定model字段，可以覆盖全局模型配置。

5.2 权限和密钥管理

open-code-review 需要访问代码仓库的 Token，这本身就是个安全敏感点。使用 GitHub Actions 时，推荐使用 GitHub 自带的GITHUB_TOKEN并加上最小权限，就像前面的 workflow 里那样。但如果你在本地命令行里跑，GITHUB_TOKEN千万不要写进 shell history 或配置文件里。

我在服务器上跑定时任务时踩过坑，最开始把 Token 明文放在.bashrc里，后来查日志发现权限范围过大的 Token 被运维安全团队扫描到了，还好是内部测试环境。现在我的做法是：用环境变量文件.env，并且加入.gitignore，CI 里用 Secret 注入。另外建议给 open-code-review 用独立的 Token，只开pulls和contents:read权限，不要图省事用写权限更大的个人 Token。

5.3 长 diff 的上下文截断问题

当一个 MR 改动超过 1000 行时，如果直接全部塞给模型，大概率触发上下文超限，或者模型注意力被稀释。open-code-review 的处理方式是“按文件分片”，每个文件单独构建审查上下文，并在规则里设置最大 diff 行数。超过阈值的文件会先做摘要压缩，把“哪些函数被改了”的概要信息送给模型，再让模型决定是否要求看某个函数的完整实现。

但这个分片方案也有缺陷。跨文件的逻辑改动（例如一个接口定义变了，所有调用方都改了）会被拆成多个独立任务，模型看不到全局影响。我们后来用了一个小技巧：在仓库根目录放一个ARCHITECTURE.md，里面写清楚核心模块的职责和调用关系，open-code-review 会把这个文件作为全局背景附带进提示词。效果很明显，涉及跨模块修改的意见质量提升了一个档次。

5.4 提示词写不好，模型就会“脑补”

这是最容易犯、也最难调的问题。很多人写规则 prompt 时，喜欢用“请检查所有潜在问题”，这等于给模型开了一个没有边界的想象力阀门。结果模型会从 diff 里硬找一些问题，甚至把本来正确的代码当作错误来报告。

我的经验是：规则 prompt 必须包含“出现什么才算是问题”的正向条件和“什么情况下不算问题”的负向排除条件。例如：

请只报告以下情况： 1. 新增代码中有未检查的 error 返回； 2. 调用的函数明确返回 error，且该 error 被 `_` 忽略。 不要报告已有代码中遗留的错误处理问题，不要报告本次 diff 未覆盖的逻辑。

加上边界限制后，模型就不会基于“可能出错”去脑补了。这个问题本质上是上下文工程，很多人以为换更大的模型能解决，但实际不如把规则写清楚来得有效。

5.5 一个误报排查链路：从“未处理异常”误报说起

调试误报不只要看结果，还要看模型“为什么这么判断”。我举一个具体的例子：有同事问为什么 open-code-review 在一个方法上报了“未处理异常”，但他明明在方法内部检查了异常并做了日志。

打开日志里的 prompt 之后，我发现规则模板只包含了 diff 区域，没有包含方法整体结构。这个方法本身很长，而改动点落在前 5 行，异常检查却在最后 10 行，因为 diff 被截断了，模型看到的代码是不完整的，自然推理出“缺少异常处理”。

解决方法是把review_scope从diff改成diff_plus_surrounding，并把surrounding_lines从默认的 3 行提高到了 10 行。这样模型能看到足够的上下文，误报立刻消失。排查链路如下：

• 收到误报意见，确认发生在文件中的真实行号。
• 检查该行是否位于 diff 边缘，若在边缘优先怀疑上下文不足。
• 对比当前配置的surrounding_lines与实际方法结构长度。
• 调整 scope 配置后重新触发一次 review，验证误报消失。
• 若仍旧误报，再往 prompt 中加入负向排除条件。

这条链路现在被我写进了团队内部的 SOP，每次遇到“看起来不对”的意见，先按这个流程走一遍，比自己凭空改 prompt 高效得多。

6. 从 open-code-review 延伸出去：代码审查数据还能怎么用

6.1 把审查意见变成新人的学习材料

open-code-review 生成的所有意见都会落成一个结构化 JSON 报告，这是它被忽略的一个优点。我们可以把这个报告导入到内部 Wiki 里，定期把高频问题整理成“代码审查周报”。对新人来说，这些东西比 IDE 插件提示更贴近团队真实代码库。

我做过一个尝试：把连续两周的 High 级别意见按照“文件模块”分组，发现支付模块的意见集中在“金额精度处理”和“外部接口错误透传”两个点上。后来我们在新人上手任务里专门设计了两个练习单元，对应这两个问题，新人完成练习的速度明显比之前只看文档快。

6.2 从规则命中率反推团队知识盲区

审查工具不只是帮你抓 bug，它还可以成为一种“团队代码雷达”。当我们统计了一个季度的规则命中数据后发现，错误处理规则的命中率高于我们自己的预期，说明大家不是不处理错误，而是不知道哪些错误需要 “包装后向上抛”。这个信息反推到了培训计划里，我们专门安排了一次“Go 错误语义化”的分享，从根因上解决问题。

如果你所在团队想长期用 open-code-review，我建议一开始就把报告数据存储到数据库。最简单的方案是在 GitHub Actions 里，每次跑完都上传ocr-report.json到 S3 或 OSS，后面想分析随时可用。

6.3 我对后续版本的三个期待

作为一个使用者，我对 open-code-review 还有几点期待。第一是希望规则支持多模型的“协商机制”，比如一个规则让两个不同模型分别判断，不一致时再触发人工确认，这能进一步降低误报。第二是希望内置更多语言的高质量规则模板，目前官方模板里 Go 和 TypeScript 做得比较好，但 Java 和 Rust 相对薄弱。第三是希望增加一个 Web 控制台，方便团队里不懂命令行的同学查看历史审查报告，而不是依赖 GitHub 评论。

从个人经验来讲，代码评审自动化不能抱着“把机器人当成评委”的心态去部署，它是把你从低效审查中解放出来的助手。open-code-review 让我重新找回了对代码评审的信心——至少每个 MR 推上去之后，不会只收到一句空洞的 LGTM 了。