1. 为什么我要把 Code Review 做成自动化流水线先说说我做这个项目的初衷。在团队里待过几年的人应该都有这种感觉代码评审这件事看似简单实际执行起来问题一大堆。小团队靠口头约定大团队靠流程制度但无论哪种方式只要评审还是“人肉驱动”就一定绕不开三个死结评审速度取决于 reviewer 什么时间有空、评审质量取决于 reviewer 当天的心情和精力、评审标准取决于 reviewer 个人的口味和习惯。于是有的 PR 挂了两天没人理有的 PR 被揪着命名规范吵了半小时真正该看的逻辑漏洞反而没人提。我做 open-code-review 这件事就是想解决“评审质量不可复制”的问题。说白了我要的不是替代人工评审而是给团队加一个“先过一遍的机器人”。这个机器人不会累、不会烦躁、不会漏看空指针它能做的就是把代码里最容易被忽略的问题先筛一遍把结果贴到 PR 讨论区里然后让人来做真正的判断这个修改是否符合业务预期这个设计是否合理这段逻辑以后好不好维护。顺着这个思路我给 open-code-review 定了三个非常明确的目标跑得快整个审查过程控制在 3 分钟以内不能拖慢开发节奏看得准宁可漏报不可误报误报太多会让人产生“狼来了”效应最后根本没人看机器人的评论接得顺尽量复用团队已有的代码托管平台能力不要在评审流程里硬塞一套新工具让大家都得学。这篇文章我会把整个项目的设计思路、核心实现、选型考量、踩坑实录全部摊开讲。内容偏实操适合后端开发、DevOps 工程师以及想在团队里推行自动化代码审查的技术负责人。文中涉及的代码和配置都是我实际跑过的版本你可以直接拿去改。2. 核心思路拆解自动化 Code Review 到底在审什么2.1 代码评审的边界机器能审什么不能审什么要设计一套自动化 review 工具第一步不是写代码而是想清楚一个哲学问题机器到底能替人做哪一部分评审工作我把代码评审这件事拆成了四个层次第一层是规范类检查。缩进、命名、import 顺序、魔法数字、重复代码这些是纯粹机械的活儿传统上由 lint 工具和静态扫描工具承担。这一层机器做得比人好而且没有任何争议。第二层是缺陷类检查。空指针风险、资源未释放、并发安全、边界条件、明显的逻辑错误这层一部分可以靠静态分析做到一部分需要理解业务上下文才能判断。机器能做到“发现可疑点”但做不到“确认是 bug”。第三层是设计类评审。这个类的职责是否单一、这段逻辑是否应该抽到公共模块、接口设计是否合理、扩展性是否足够。这层需要大量的工程经验和业务理解机器目前只能给建议而且建议质量很依赖模型能力。第四层是业务匹配度评审。改动是否符合产品需求、是否覆盖了所有业务分支、是否有隐藏的兼容性风险。这层基本只能靠人机器连需求长什么样都看不懂。open-code-review 的定位非常明确死磕第二层顺带辅助第三层。第一层交给既有的 lint 工具链第四层永远留给人。这样设计的好处是——工具的输出是有明确价值的不会变成噪音。2.2 为什么选 LLM 而不是纯静态分析这个决定是我反复权衡过的。如果只靠静态分析工具比如 SonarQube、CodeQL、Semgrep它们确实能抓出很多确定性的问题但有两个很明显的短板一是只会找“有明确规则”的问题换个写法就漏了二是不会总结只能给片段描述不能给出全局性的修改建议。而大语言模型恰好能补上这两个短板。它能看懂逻辑、能理解命名背后的含义、能结合文件之间的调用关系推断意图、还能用自然语言把问题讲清楚。比如“这个函数的返回值在异常路径上没有处理会导致调用方拿到的 status 是默认值”这种表述静态工具写不出来但 LLM 能写。但引入 LLM 也有代价。最明显的是不确定性同一个 diff跑两次结果可能不一样。这个特性放在安全审查里是致命的但放在 code review 助手场景里其实可以接受——因为最终判断还是人做的LLM 的价值是“帮你发现之前没注意的点”而不是“给你一个终审结论”。在模型选型上我比较过几个方案。用 GPT-4 系列效果最好但每条 diff 的成本也高用开源模型成本低但审查逻辑复杂代码时的误报率明显偏高。最后我的方案是做成可插拔的默认走 OpenAI 兼容接口通过环境变量切模型小团队用开源模型跑跑足够预算足的团队直接上商用模型。具体的接口封装后面会贴代码。2.3 触发方式选型GitHub Actions 还是独立服务这是另一个关键决策。自动化审查工具有两种落地形态一种是作为 CI 流水线的一环在 push 和 PR 时触发像跑测试一样跑审查另一种是独立部署的常驻服务通过 webhook 监听仓库事件。我一开始倾向独立服务因为它的数据处理能力更强——可以对接多个仓库、维护历史状态、做增量分析。但后来放弃了原因很现实维护成本太高。独立服务意味着要管服务器、管数据库、管部署、管升级这套运维成本摊到一个小工具身上不划算。转回 GitHub Actions 之后事情变得异常简单。Action 本身是声明式的yaml 文件一配就能跑审查需要的所有上下文——diff、PR 元信息、仓库结构——都能通过官方 API 拿结果直接以评论形式发到 PR 页面开发者在原工作流里就能看到触发策略还能精确控制到“只有 PR 才跑”。这就是典型的“用平台能力省自研成本”。当然GitHub Actions 也有局限。它是一次性执行的没有常驻内存没法跨多次执行维护状态每次执行都要冷启动拉代码、装环境、跑模型怎么也得 1 到 2 分钟。但这些短板对我这个场景来说不影响大局后面会讲到怎么在 Action 里做消息缓存和幂等控制。3. 工具链选型与项目结构设计3.1 技术栈选择的理由整个项目的技术栈我刻意保持精简。语言选了 Python理由很朴素GitHub API 的 SDK 做得成熟Python 生态里处理 JSON 数据方便团队里后端同事都熟有什么问题大家都能上手改。模型调用层我封装了一个统一的接口不直接绑定某个厂商的 SDK。这么做是因为我预判到一件事LLM 领域的技术迭代太快了今天这个模型贵、明天那个模型效果差如果代码里到处是某个平台的 SDK 调用换模型就得改一堆代码。封装之后换模型只改配置文件前后不超过十分钟。主流程用的是 PyGithub 这个库。它把 GitHub 的 REST API 都封装成了 Python 对象操作 PR、Issue、评论都非常方便省去了自己拼请求的工作量。这里选择 REST API 而不是 GraphQL是因为审查场景需要的数据结构比较固定传参简单REST 完全是够用的。Prompt 模板我单独拆了一个目录来管理。这是个非常重要但容易被忽略的设计——LLM 应用的项目里Prompt 不是一行配置而是跟代码一样需要版本管理、需要多版本对比、需要回滚的核心资产。3.2 项目目录结构与每个模块的职责open-code-review/ ├── main.py # 入口文件解析环境变量编排整个流程 ├── requirements.txt # 依赖清单 ├── action.yml # GitHub Action 的元数据定义 ├── Dockerfile # 打包用的镜像定义 ├── src/ │ ├── __init__.py │ ├── review.py # 核心审查逻辑编排整个 review 流程 │ ├── llm.py # 模型调用层统一封装各家 LLM 接口 │ ├── prompt.py # Prompt 模板管理加载、渲染、版本对比 │ ├── github_client.py # GitHub API 封装PR 信息、diff、评论 │ └── utils.py # 工具函数文本处理、上下文组装、结果解析 └── prompts/ ├── code_review.md # 核心审查 prompt └── summary.md # 用于生成总结评论的 prompt你可能会问这个规模的项目为什么不一个文件搞定我的经验是LLM 应用有个特点——调试的重心会从“代码本身”转移到“代码和 Prompt 的交互边界”。如果所有逻辑堆在一个文件里想单独调 prompt 就得连带测试一堆无关代码很痛苦。拆开之后每个模块都可以独立调试尤其是 prompt.py 和 review.py 之间的接口是整套系统最核心的部分。3.3 Action 元数据设计如何让工具被更多人直接用既然做了 GitHub Action就得让它能被人方便地复用。action.yml 就是给 GitHub Action 用的“说明书”里面定义了输入参数、运行环境、入口命令。我把常用配置都做成可传入的输入项这样使用方不必改代码在 workflow 文件里传参就能定制行为。name: Open Code Review description: 基于 LLM 的自动化代码评审工具在 PR 上输出结构化审查建议 inputs: github-token: description: 用于调用 GitHub API 的 Token默认使用 GITHUB_TOKEN required: true default: ${{ github.token }} model: description: 使用的模型名称需兼容 OpenAI API 格式 required: false default: gpt-4o-mini api-base: description: LLM API 的地址支持 OpenAI 或兼容服务 required: false default: https://api.openai.com/v1 api-key: description: 调用 LLM 的密钥建议通过 Secrets 传入 required: true max-files: description: 单次审查最大文件数防止超时 required: false default: 20 review-mode: description: 审查模式full(全量) / changed(仅变更行) required: false default: changed runs: using: docker image: Dockerfile这个配置文件里有两个设计点值得展开。第一默认使用${{ github.token }}这个 token 是 GitHub Actions 内置的无需额外申请权限安全风险最小。第二镜像采用 Docker 方式运行而不是 JavaScript Action因为 Python 环境和模型调用的依赖打包成 Docker 镜像更省心避免在 GitHub 的 runner 里现场 pip install 超时。4. 实操过程与核心环节实现4.1 审查流程的五步编排整个工具的执行流程我把它浓缩成五个步骤。这是从目标倒推出来的设计——先想清楚每一步要产出什么再确定每一步怎么实现。第一步是接收触发。Action 被触发后会拿到一系列环境变量包括 GITHUB_EVENT_PATH事件数据的 JSON 文件路径、GITHUB_REPOSITORY仓库名、GITHUB_SHA提交哈希。我在 main.py 里做的第一件事就是解析这些变量拼出后续要调用的 API 参数。第二步是拉取上下文。这一阶段要做的事情包括获取 PR 的基本信息标题、描述、提交列表、拉取这次改动涉及的 diff、读取仓库文件结构。上下文的质量直接决定审查质量这个后面详细说。第三步是组装 Prompt。把 diff、文件路径、仓库信息、审查要求全部填充进模板生成发给 LLM 的请求体。第四步是调用模型。发给 LLM拿到返回的审查结果做格式解析和过滤把明显无效的内容剔除掉。第五步是回写结果。把审查结论以评论和行级注记的形式发布到 PR 上让开发者在熟悉的界面里看到结果。def run_review(): repo get_repository() pr get_pull_request(repo) diff get_pr_diff(repo, pr) changed_files parse_changed_files(diff) if len(changed_files) MAX_FILES: changed_files changed_files[:MAX_FILES] context build_review_context(pr, changed_files, diff) review_results call_llm(context) post_review_comment(pr, review_results)这就是主流程的骨架看着简单但每一步都有很多坑。下面逐个说。4.2 拉取 diff 的正确姿势和上下文组装细节拉 diff 这件事看似简单其实有一个大坑——大 PR 的 diff 很长直接塞给模型会爆 token 上限。我处理的方式是把 diff 按文件切块批量审查而不是一次性全塞进去。具体实现上GitHub REST API 获取 PR 的 files 接口会返回每个文件的 patch 字段就是标准 unified diff 格式。但注意对于超大文件或者二进制文件patch 字段可能是空的需要做好跳过处理。更关键的是上下文组装策略。单一文件的diff不够模型理解业务逻辑但它也不需要理解整个仓库才能给出有效的初级审查意见。我的策略是一个两级的上下文结构对大文件只截取变更部分前后各几行对整个 PR挑出修改最多的几个文件路径信息作为补充背景。def parse_changed_files(diff_data): changed_files [] for item in diff_data: filename item[filename] patch item.get(patch, ) if not patch: continue additions item[additions] deletions item[deletions] changes item[changes] raw_url item[contents_url] file_info { path: filename, patch: patch, additions: additions, deletions: deletions, changes: changes, language: filename.split(.)[-1], } changed_files.append(file_info) return changed_files审查的过滤规则也在这里定义跳过超过 1000 行的文件 diff、跳过二进制文件、跳过 lock 文件package-lock.json、poetry.lock 这类、跳过 minified 文件。规则前置过滤比让模型自己判断要省钱得多因为这些文件不管是人是机器都不会喜欢review。4.3 Prompt 模板设计这是整个项目灵魂所在把核心 prompt 拆出来单独讲因为它决定了工具的上限。我把 Prompt 设计成四个组成部分角色定义、审查维度、输出格式、禁止事项。每个部分都经过多次迭代下面是当前在用的核心模板。你是一名高级软件工程师正在参与一个开源项目的代码审查。 请审查以下代码变更重点检查 1. 逻辑正确性是否存在潜在的空指针、数组越界、资源未释放、并发安全问题 2. 错误处理异常路径是否被忽略错误信息是否清晰 3. 代码质量是否有明显可重构的点比如重复逻辑、过长的函数、模糊的命名 4. 安全性是否存在注入风险、敏感信息泄露、不安全的依赖使用 约束 - 只报告你确信有问题的地方不确定的不要提 - 每个问题必须包含文件路径、行号如适用、问题的严重程度high/medium/low、具体原因和修改建议 - 使用简洁的中文表述不要客套话 - 如果代码没有问题明确回复未发现明显问题 diff 内容如下 {diff_content}这个模板看起来简单但每个措辞都有讲究。比如“只报告你确信有问题的地方不确定的不要提”——这是在刻意压制误报率。LLM 有个倾向你让它找问题它就会凑出一堆问题来显得自己勤奋但这对用户是灾难。把审查标准从“尽可能多找”改成“尽可能准”输出质量会大幅提升。输出格式我用的是“每条一个 JSON 对象”的方式比让模型返回完整 JSON 数组更稳。因为 LLM 生成完整数组容易在中间截断生成单条记录即使断了也可以跳过那条不影响整体结果。4.4 调用模型与结果解析的稳定性处理调用模型这块代码实现我封装成了一个通用的 LLM 客户端兼容 OpenAI 的 chat completions 接口。def call_llm(messages, modelgpt-4o-mini): client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE, https://api.openai.com/v1), ) try: response client.chat.completions.create( modelmodel, messagesmessages, temperature0.2, max_tokens4096, ) return response.choices[0].message.content except Exception as e: logger.error(fLLM 调用失败: {e}) return None这里 temperature 设为 0.2是我反复调出来的经验值。设成 0 会让输出过于死板稍微复杂一点的表达就退化设成 1 又容易发散。0.2 是在“稳定输出”和“自然表达”之间比较合适的中点。解析结果的稳定性是另一个容易踩坑的地方。模型输出经常带无关文字比如以下是审查结果这种前言。我的处理方式是先尝试按 JSON 行解析解析不出来就用正则提取代码块再不行就整段丢弃。宁可少一条结果不能让一条坏格式把整个流程搞挂。4.5 审查结果的回写行级注记优于整段评论结果回写是我反复调整过的一个环节。第一版我把所有问题汇总成一段长评论发到 PR 页面后来发现效果并不好——开发者看到一大段文字本能地想逃避而且问题定位不清晰还得自己去 diff 里找位置。第二版改成行级注记对应 GitHub 的 review comments 功能。每个问题直接挂在具体代码行上开发者浏览 diff 的时候一眼就能看到。这个改动带来的体验提升非常明显互动率比整段评论高了不止一个量级。实现这个功能需要调用 GitHub 的创建审阅评论接口def post_line_comments(pr, comments): for comment in comments: path comment[path] line comment[line] body comment[body] commit_id pr.head.sha try: pr.create_review_comment( bodybody, commit_idcommit_id, pathpath, lineline, ) except Exception as e: logger.error(f行级评论创建失败 ({path}:{line}): {e})这个方案有一个需要注意的地方GitHub 的 review comment 只能挂在 diff 上下文中存在的行上。如果某个问题指向的位置不在 diff 范围内比如用户新增的代码只改了某一行但问题出在该文件的另一处API 会直接报错。我的处理是捕获异常后降级——如果行级评论创建失败就把这条评论合并进汇总评论里保证信息不丢只是展示位置不够精准。另外还要考虑重复评论的问题。Action 每次 push 都会触发如果上一次发现的问题没有修复这次又会重复报。解决方式是在写评论前先查一遍这个 PR 下已有的评论如果同文件同行同内容的问题已经存在就跳过不重复创建。5. 项目落地从零开始配置一个可用的审查机器人5.1 标准部署步骤以下是在一个 GitHub 仓库里启用 open-code-review 的完整步骤。整个过程大约需要十分钟。第一步准备密钥。在 GitHub 仓库的 Settings - Secrets and variables - Actions 里添加一个名为OPENAI_API_KEY的密钥填入你调用的 LLM 服务 API Key。如果你的模型服务是自建的或者其他兼容平台再加一个OPENAI_API_BASE变量填服务地址。第二步创建 workflow 文件。在仓库的.github/workflows/目录下新建一个 yaml 文件内容如下name: Open Code Review on: pull_request: types: [opened, synchronize, reopened] pull_request_review_comment: types: [created, edited] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: your-org/open-code-reviewv1 with: github-token: ${{ secrets.GITHUB_TOKEN }} api-key: ${{ secrets.OPENAI_API_KEY }} api-base: ${{ secrets.OPENAI_API_BASE }} model: gpt-4o-mini第三步也是很多人容易忽略的一步配置 Actions 的权限。上面的 yaml 里写了permissions字段这是必需的。如果没有显式声明pull-requests: write权限GitHub 默认只给只读权限机器人就只能读 PR 信息、不能写评论整个工具就只剩报错的功能了。第四步是测试。随便开一个 PR改点东西push 上去等 Actions 跑完。如果一切正常大约两分钟后 PR 页面会出现机器人的审查评论如果失败点进 Actions 页面看日志排查。5.2 Dockerfile 与依赖管理由于 Action 以 Docker 方式运行Dockerfile 的编写也有讲究。核心是镜像要轻、构建要快、运行时依赖要锁版本避免“今天能跑明天挂了”的随机性问题。FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . ENTRYPOINT [python, /app/main.py]这里用的是python:3.11-slim而不是完整版镜像体积从 1GB 级降到 200MB 左右拉取和启动都快很多。requirements.txt里的依赖我锁了精确版本号防止上游库更新引发行为不一致。之前吃过亏有个依赖库小版本升级之后分页接口返回的数据结构变了CI 从稳定运行直接变成全部报错排查了半天。5.3 与既有工作流的集成方式最后一个实用话题怎么让这个工具和团队已有的流程和谐共存。我的建议是把它当成第一道自动门而不是评审流程里的唯一角色。推荐的工作流顺序是push 代码 - 跑 lint 和单测 - 跑 open-code-review - 人工 review。lint 和单测负责第一层筛选把低级问题挡在门外open-code-review 负责第二层筛选从逻辑、安全、健壮性角度找问题人工评审专注在最关键的业务匹配度和设计合理性上。三层各有侧重互不挤占。这个顺序还有一个好处lint 和单测的结果是确定的跑挂了就不会走到后面的步骤可以帮团队省下模型调用的费用——毕竟 LLM API 是按 token 收费的代码质量越差审查成本越高。6. 常见问题与排查技巧实录6.1 问题速查表我踩过的坑和排查方法这套工具上线之后我从实际使用中收集了不少问题。按出现频率从高到低整理成一张速查表每一条都是实测踩过的。现象可能原因解决办法Action 执行后没有任何评论Token 权限不足检查 workflow 的 permissions 是否声明pull-requests: write行级评论报 422 错误行号不在 diff 上下文中捕获异常降级为汇总评论Model 返回超时diff 过长超出模型上下文限制减小 max-files按文件分块审查重复评论刷屏上一次的问题未被修复又触发审查写评论前先查已有评论并去重审查结果是一堆空话Prompt 约束不严强化“不确定的不要提”约束降低 temperature本地能跑 CI 不能跑依赖版本漂移requirements.txt 锁定精确版本号Dependabot 的 PR 也触发审查机器人 PR 也会触发 workflow在 on 条件里排除 actor 为 dependabot审查覆盖不到某些文件类型文件过滤规则太激进检查 parse_changed_files 中的扩展名黑名单6.2 误报率过高的处理经验误报是这类工具最致命的问题。我的第一版 prompt 误报率接近 40%就是说模型报出的问题里四成根本不算问题。这会造成两个危害开发人员要花时间一条条核实时间成本比人肉评审还高更严重的是信任崩塌试过几次发现全是噪音之后大家就会对整个工具的输出置之不理。针对误报我做了三轮调整。第一轮改 prompt加上“只报告你确信有问题的地方”第二轮加规则明确列出了不能审查的文件类型和跳过条件第三轮调整审查的代码上下文窗口让模型看到更完整的上下文再下结论。三轮下来误报率降到了大约 15%。15% 仍然不算低但相对于它发现真实问题的价值这个比例团队是可以接受的。在工具积累了一定的真实 review 数据之后还可以做一个反馈回路——人审时如果点“不是问题”把样本收回来用来迭代 prompt。6.3 大 PR 的审查策略调整还有一个实际工作中必然遇到的高频问题大 PR。一个 PR 改了 60 个文件、2000 行代码直接全量审必然超时、超 token、结果也大概率是泛泛而谈。我的策略是分级审查先跑一个快速摘要输出这次 PR 的主干改动逻辑然后按文件维度逐个审查只挑风险最高的文件深入审。风险高的判断规则是改动行数超过 100 行的文件、涉及核心逻辑的目录比如 auth、payment、db、新增文件而不是修改文件。每个文件单独构造一次模型调用这样即使单个文件 diff 很大也不至于把一个请求撑爆。代价是调用次数变多、总耗时变长但换来的是结果质量稳定。如果团队要求更快的响应速度可以把并行度调高多个文件同时去请求模型时间能压到一分钟以内。6.4 成本控制如何让每块钱都花在刀刃上最后聊聊成本。LLM 做 code review 是按 token 计费的一个 10 文件的中型 PR完整审查大约消耗 2 万到 4 万 token。如果天天大量提交月底账单确实肉疼。我的省钱经验有三个第一default 模型用便宜档。gpt-4o-mini在多数场景下表现够用只有遇到特别复杂的逻辑时才需要手动指定升级模型。实践中大约 90% 的 PR 用 mini 档就能发现问题。第二精确控制输入上下文。只发送和修改相关的代码片段不要整个文件灌给模型。很多误报其实也跟上下文过载有关——模型看了太多无关代码注意力被分散反而对关键问题不敏感。这个策略同时提升了质量、降低了成本一举两得。第三添加一个review-mode参数设置成changed时只审查变更行附近的内容不分析整个文件。这个模式对“改了一行但引发全局 bug”这种问题的发现率会低一些但对大部分规范类、健壮性类问题足够用。想要深度审查时再手动开full模式。7. 后续还能怎么扩展我已经跑通的核心流程是PR 触发 - 拉 diff - LLM 审查 - 行级评论回写。这套骨架稳定之后扩展方向其实非常清晰。第一个方向是把审查结果接入仓库的规则引擎比如通过 GitHub 的 branch protection 设置当 open-code-review 标记出 high 级别问题时PR 不允许合并。这能让工具的定位从“建议助手”升级为“质量关口”。但要注意这个功能需要谨慎设计得给人工 review 留一个“忽略并强制合并”的口子否则会把工具架到开发者的对立面。第二个方向是针对特定领域定制 Prompt。目前这套 Prompt 是通用的对 Python 和 JavaScript 代码效果最好。如果团队主要是写 Go 或者 Rust可以把并发安全相关的审查维度加强如果是前端团队可以把重点放在组件性能、依赖体积、样式副作用上。Prompt 是这套系统里性价比最高的调优点改动一个字都可能带来体验的明显提升。第三个方向是沉淀内部的 review 知识库。每次人工评审时的修改意见其实都是团队的隐性知识资产。把常见问题和标准回复整理成 few-shot 样本喂给模型工具的审查能力会越用越贴近团队的标准。这条路我还没完全打通但方向已经验证过可行。我在团队里推这套流程时最深的体会是工具替代不了人的判断力但它能把人从重复劳动中解放出来让人有精力去做更值得做的事。open-code-review 这个名字里的 open既是指这个工具本身开源也是在提醒我——评审的标准要开放要接受团队成员的不同观点工具的结论永远只是参考真正的决策权始终在人的手里。 基于LLM的自动化Code Review流水线设计与实践
1. 为什么我要把 Code Review 做成自动化流水线先说说我做这个项目的初衷。在团队里待过几年的人应该都有这种感觉代码评审这件事看似简单实际执行起来问题一大堆。小团队靠口头约定大团队靠流程制度但无论哪种方式只要评审还是“人肉驱动”就一定绕不开三个死结评审速度取决于 reviewer 什么时间有空、评审质量取决于 reviewer 当天的心情和精力、评审标准取决于 reviewer 个人的口味和习惯。于是有的 PR 挂了两天没人理有的 PR 被揪着命名规范吵了半小时真正该看的逻辑漏洞反而没人提。我做 open-code-review 这件事就是想解决“评审质量不可复制”的问题。说白了我要的不是替代人工评审而是给团队加一个“先过一遍的机器人”。这个机器人不会累、不会烦躁、不会漏看空指针它能做的就是把代码里最容易被忽略的问题先筛一遍把结果贴到 PR 讨论区里然后让人来做真正的判断这个修改是否符合业务预期这个设计是否合理这段逻辑以后好不好维护。顺着这个思路我给 open-code-review 定了三个非常明确的目标跑得快整个审查过程控制在 3 分钟以内不能拖慢开发节奏看得准宁可漏报不可误报误报太多会让人产生“狼来了”效应最后根本没人看机器人的评论接得顺尽量复用团队已有的代码托管平台能力不要在评审流程里硬塞一套新工具让大家都得学。这篇文章我会把整个项目的设计思路、核心实现、选型考量、踩坑实录全部摊开讲。内容偏实操适合后端开发、DevOps 工程师以及想在团队里推行自动化代码审查的技术负责人。文中涉及的代码和配置都是我实际跑过的版本你可以直接拿去改。2. 核心思路拆解自动化 Code Review 到底在审什么2.1 代码评审的边界机器能审什么不能审什么要设计一套自动化 review 工具第一步不是写代码而是想清楚一个哲学问题机器到底能替人做哪一部分评审工作我把代码评审这件事拆成了四个层次第一层是规范类检查。缩进、命名、import 顺序、魔法数字、重复代码这些是纯粹机械的活儿传统上由 lint 工具和静态扫描工具承担。这一层机器做得比人好而且没有任何争议。第二层是缺陷类检查。空指针风险、资源未释放、并发安全、边界条件、明显的逻辑错误这层一部分可以靠静态分析做到一部分需要理解业务上下文才能判断。机器能做到“发现可疑点”但做不到“确认是 bug”。第三层是设计类评审。这个类的职责是否单一、这段逻辑是否应该抽到公共模块、接口设计是否合理、扩展性是否足够。这层需要大量的工程经验和业务理解机器目前只能给建议而且建议质量很依赖模型能力。第四层是业务匹配度评审。改动是否符合产品需求、是否覆盖了所有业务分支、是否有隐藏的兼容性风险。这层基本只能靠人机器连需求长什么样都看不懂。open-code-review 的定位非常明确死磕第二层顺带辅助第三层。第一层交给既有的 lint 工具链第四层永远留给人。这样设计的好处是——工具的输出是有明确价值的不会变成噪音。2.2 为什么选 LLM 而不是纯静态分析这个决定是我反复权衡过的。如果只靠静态分析工具比如 SonarQube、CodeQL、Semgrep它们确实能抓出很多确定性的问题但有两个很明显的短板一是只会找“有明确规则”的问题换个写法就漏了二是不会总结只能给片段描述不能给出全局性的修改建议。而大语言模型恰好能补上这两个短板。它能看懂逻辑、能理解命名背后的含义、能结合文件之间的调用关系推断意图、还能用自然语言把问题讲清楚。比如“这个函数的返回值在异常路径上没有处理会导致调用方拿到的 status 是默认值”这种表述静态工具写不出来但 LLM 能写。但引入 LLM 也有代价。最明显的是不确定性同一个 diff跑两次结果可能不一样。这个特性放在安全审查里是致命的但放在 code review 助手场景里其实可以接受——因为最终判断还是人做的LLM 的价值是“帮你发现之前没注意的点”而不是“给你一个终审结论”。在模型选型上我比较过几个方案。用 GPT-4 系列效果最好但每条 diff 的成本也高用开源模型成本低但审查逻辑复杂代码时的误报率明显偏高。最后我的方案是做成可插拔的默认走 OpenAI 兼容接口通过环境变量切模型小团队用开源模型跑跑足够预算足的团队直接上商用模型。具体的接口封装后面会贴代码。2.3 触发方式选型GitHub Actions 还是独立服务这是另一个关键决策。自动化审查工具有两种落地形态一种是作为 CI 流水线的一环在 push 和 PR 时触发像跑测试一样跑审查另一种是独立部署的常驻服务通过 webhook 监听仓库事件。我一开始倾向独立服务因为它的数据处理能力更强——可以对接多个仓库、维护历史状态、做增量分析。但后来放弃了原因很现实维护成本太高。独立服务意味着要管服务器、管数据库、管部署、管升级这套运维成本摊到一个小工具身上不划算。转回 GitHub Actions 之后事情变得异常简单。Action 本身是声明式的yaml 文件一配就能跑审查需要的所有上下文——diff、PR 元信息、仓库结构——都能通过官方 API 拿结果直接以评论形式发到 PR 页面开发者在原工作流里就能看到触发策略还能精确控制到“只有 PR 才跑”。这就是典型的“用平台能力省自研成本”。当然GitHub Actions 也有局限。它是一次性执行的没有常驻内存没法跨多次执行维护状态每次执行都要冷启动拉代码、装环境、跑模型怎么也得 1 到 2 分钟。但这些短板对我这个场景来说不影响大局后面会讲到怎么在 Action 里做消息缓存和幂等控制。3. 工具链选型与项目结构设计3.1 技术栈选择的理由整个项目的技术栈我刻意保持精简。语言选了 Python理由很朴素GitHub API 的 SDK 做得成熟Python 生态里处理 JSON 数据方便团队里后端同事都熟有什么问题大家都能上手改。模型调用层我封装了一个统一的接口不直接绑定某个厂商的 SDK。这么做是因为我预判到一件事LLM 领域的技术迭代太快了今天这个模型贵、明天那个模型效果差如果代码里到处是某个平台的 SDK 调用换模型就得改一堆代码。封装之后换模型只改配置文件前后不超过十分钟。主流程用的是 PyGithub 这个库。它把 GitHub 的 REST API 都封装成了 Python 对象操作 PR、Issue、评论都非常方便省去了自己拼请求的工作量。这里选择 REST API 而不是 GraphQL是因为审查场景需要的数据结构比较固定传参简单REST 完全是够用的。Prompt 模板我单独拆了一个目录来管理。这是个非常重要但容易被忽略的设计——LLM 应用的项目里Prompt 不是一行配置而是跟代码一样需要版本管理、需要多版本对比、需要回滚的核心资产。3.2 项目目录结构与每个模块的职责open-code-review/ ├── main.py # 入口文件解析环境变量编排整个流程 ├── requirements.txt # 依赖清单 ├── action.yml # GitHub Action 的元数据定义 ├── Dockerfile # 打包用的镜像定义 ├── src/ │ ├── __init__.py │ ├── review.py # 核心审查逻辑编排整个 review 流程 │ ├── llm.py # 模型调用层统一封装各家 LLM 接口 │ ├── prompt.py # Prompt 模板管理加载、渲染、版本对比 │ ├── github_client.py # GitHub API 封装PR 信息、diff、评论 │ └── utils.py # 工具函数文本处理、上下文组装、结果解析 └── prompts/ ├── code_review.md # 核心审查 prompt └── summary.md # 用于生成总结评论的 prompt你可能会问这个规模的项目为什么不一个文件搞定我的经验是LLM 应用有个特点——调试的重心会从“代码本身”转移到“代码和 Prompt 的交互边界”。如果所有逻辑堆在一个文件里想单独调 prompt 就得连带测试一堆无关代码很痛苦。拆开之后每个模块都可以独立调试尤其是 prompt.py 和 review.py 之间的接口是整套系统最核心的部分。3.3 Action 元数据设计如何让工具被更多人直接用既然做了 GitHub Action就得让它能被人方便地复用。action.yml 就是给 GitHub Action 用的“说明书”里面定义了输入参数、运行环境、入口命令。我把常用配置都做成可传入的输入项这样使用方不必改代码在 workflow 文件里传参就能定制行为。name: Open Code Review description: 基于 LLM 的自动化代码评审工具在 PR 上输出结构化审查建议 inputs: github-token: description: 用于调用 GitHub API 的 Token默认使用 GITHUB_TOKEN required: true default: ${{ github.token }} model: description: 使用的模型名称需兼容 OpenAI API 格式 required: false default: gpt-4o-mini api-base: description: LLM API 的地址支持 OpenAI 或兼容服务 required: false default: https://api.openai.com/v1 api-key: description: 调用 LLM 的密钥建议通过 Secrets 传入 required: true max-files: description: 单次审查最大文件数防止超时 required: false default: 20 review-mode: description: 审查模式full(全量) / changed(仅变更行) required: false default: changed runs: using: docker image: Dockerfile这个配置文件里有两个设计点值得展开。第一默认使用${{ github.token }}这个 token 是 GitHub Actions 内置的无需额外申请权限安全风险最小。第二镜像采用 Docker 方式运行而不是 JavaScript Action因为 Python 环境和模型调用的依赖打包成 Docker 镜像更省心避免在 GitHub 的 runner 里现场 pip install 超时。4. 实操过程与核心环节实现4.1 审查流程的五步编排整个工具的执行流程我把它浓缩成五个步骤。这是从目标倒推出来的设计——先想清楚每一步要产出什么再确定每一步怎么实现。第一步是接收触发。Action 被触发后会拿到一系列环境变量包括 GITHUB_EVENT_PATH事件数据的 JSON 文件路径、GITHUB_REPOSITORY仓库名、GITHUB_SHA提交哈希。我在 main.py 里做的第一件事就是解析这些变量拼出后续要调用的 API 参数。第二步是拉取上下文。这一阶段要做的事情包括获取 PR 的基本信息标题、描述、提交列表、拉取这次改动涉及的 diff、读取仓库文件结构。上下文的质量直接决定审查质量这个后面详细说。第三步是组装 Prompt。把 diff、文件路径、仓库信息、审查要求全部填充进模板生成发给 LLM 的请求体。第四步是调用模型。发给 LLM拿到返回的审查结果做格式解析和过滤把明显无效的内容剔除掉。第五步是回写结果。把审查结论以评论和行级注记的形式发布到 PR 上让开发者在熟悉的界面里看到结果。def run_review(): repo get_repository() pr get_pull_request(repo) diff get_pr_diff(repo, pr) changed_files parse_changed_files(diff) if len(changed_files) MAX_FILES: changed_files changed_files[:MAX_FILES] context build_review_context(pr, changed_files, diff) review_results call_llm(context) post_review_comment(pr, review_results)这就是主流程的骨架看着简单但每一步都有很多坑。下面逐个说。4.2 拉取 diff 的正确姿势和上下文组装细节拉 diff 这件事看似简单其实有一个大坑——大 PR 的 diff 很长直接塞给模型会爆 token 上限。我处理的方式是把 diff 按文件切块批量审查而不是一次性全塞进去。具体实现上GitHub REST API 获取 PR 的 files 接口会返回每个文件的 patch 字段就是标准 unified diff 格式。但注意对于超大文件或者二进制文件patch 字段可能是空的需要做好跳过处理。更关键的是上下文组装策略。单一文件的diff不够模型理解业务逻辑但它也不需要理解整个仓库才能给出有效的初级审查意见。我的策略是一个两级的上下文结构对大文件只截取变更部分前后各几行对整个 PR挑出修改最多的几个文件路径信息作为补充背景。def parse_changed_files(diff_data): changed_files [] for item in diff_data: filename item[filename] patch item.get(patch, ) if not patch: continue additions item[additions] deletions item[deletions] changes item[changes] raw_url item[contents_url] file_info { path: filename, patch: patch, additions: additions, deletions: deletions, changes: changes, language: filename.split(.)[-1], } changed_files.append(file_info) return changed_files审查的过滤规则也在这里定义跳过超过 1000 行的文件 diff、跳过二进制文件、跳过 lock 文件package-lock.json、poetry.lock 这类、跳过 minified 文件。规则前置过滤比让模型自己判断要省钱得多因为这些文件不管是人是机器都不会喜欢review。4.3 Prompt 模板设计这是整个项目灵魂所在把核心 prompt 拆出来单独讲因为它决定了工具的上限。我把 Prompt 设计成四个组成部分角色定义、审查维度、输出格式、禁止事项。每个部分都经过多次迭代下面是当前在用的核心模板。你是一名高级软件工程师正在参与一个开源项目的代码审查。 请审查以下代码变更重点检查 1. 逻辑正确性是否存在潜在的空指针、数组越界、资源未释放、并发安全问题 2. 错误处理异常路径是否被忽略错误信息是否清晰 3. 代码质量是否有明显可重构的点比如重复逻辑、过长的函数、模糊的命名 4. 安全性是否存在注入风险、敏感信息泄露、不安全的依赖使用 约束 - 只报告你确信有问题的地方不确定的不要提 - 每个问题必须包含文件路径、行号如适用、问题的严重程度high/medium/low、具体原因和修改建议 - 使用简洁的中文表述不要客套话 - 如果代码没有问题明确回复未发现明显问题 diff 内容如下 {diff_content}这个模板看起来简单但每个措辞都有讲究。比如“只报告你确信有问题的地方不确定的不要提”——这是在刻意压制误报率。LLM 有个倾向你让它找问题它就会凑出一堆问题来显得自己勤奋但这对用户是灾难。把审查标准从“尽可能多找”改成“尽可能准”输出质量会大幅提升。输出格式我用的是“每条一个 JSON 对象”的方式比让模型返回完整 JSON 数组更稳。因为 LLM 生成完整数组容易在中间截断生成单条记录即使断了也可以跳过那条不影响整体结果。4.4 调用模型与结果解析的稳定性处理调用模型这块代码实现我封装成了一个通用的 LLM 客户端兼容 OpenAI 的 chat completions 接口。def call_llm(messages, modelgpt-4o-mini): client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE, https://api.openai.com/v1), ) try: response client.chat.completions.create( modelmodel, messagesmessages, temperature0.2, max_tokens4096, ) return response.choices[0].message.content except Exception as e: logger.error(fLLM 调用失败: {e}) return None这里 temperature 设为 0.2是我反复调出来的经验值。设成 0 会让输出过于死板稍微复杂一点的表达就退化设成 1 又容易发散。0.2 是在“稳定输出”和“自然表达”之间比较合适的中点。解析结果的稳定性是另一个容易踩坑的地方。模型输出经常带无关文字比如以下是审查结果这种前言。我的处理方式是先尝试按 JSON 行解析解析不出来就用正则提取代码块再不行就整段丢弃。宁可少一条结果不能让一条坏格式把整个流程搞挂。4.5 审查结果的回写行级注记优于整段评论结果回写是我反复调整过的一个环节。第一版我把所有问题汇总成一段长评论发到 PR 页面后来发现效果并不好——开发者看到一大段文字本能地想逃避而且问题定位不清晰还得自己去 diff 里找位置。第二版改成行级注记对应 GitHub 的 review comments 功能。每个问题直接挂在具体代码行上开发者浏览 diff 的时候一眼就能看到。这个改动带来的体验提升非常明显互动率比整段评论高了不止一个量级。实现这个功能需要调用 GitHub 的创建审阅评论接口def post_line_comments(pr, comments): for comment in comments: path comment[path] line comment[line] body comment[body] commit_id pr.head.sha try: pr.create_review_comment( bodybody, commit_idcommit_id, pathpath, lineline, ) except Exception as e: logger.error(f行级评论创建失败 ({path}:{line}): {e})这个方案有一个需要注意的地方GitHub 的 review comment 只能挂在 diff 上下文中存在的行上。如果某个问题指向的位置不在 diff 范围内比如用户新增的代码只改了某一行但问题出在该文件的另一处API 会直接报错。我的处理是捕获异常后降级——如果行级评论创建失败就把这条评论合并进汇总评论里保证信息不丢只是展示位置不够精准。另外还要考虑重复评论的问题。Action 每次 push 都会触发如果上一次发现的问题没有修复这次又会重复报。解决方式是在写评论前先查一遍这个 PR 下已有的评论如果同文件同行同内容的问题已经存在就跳过不重复创建。5. 项目落地从零开始配置一个可用的审查机器人5.1 标准部署步骤以下是在一个 GitHub 仓库里启用 open-code-review 的完整步骤。整个过程大约需要十分钟。第一步准备密钥。在 GitHub 仓库的 Settings - Secrets and variables - Actions 里添加一个名为OPENAI_API_KEY的密钥填入你调用的 LLM 服务 API Key。如果你的模型服务是自建的或者其他兼容平台再加一个OPENAI_API_BASE变量填服务地址。第二步创建 workflow 文件。在仓库的.github/workflows/目录下新建一个 yaml 文件内容如下name: Open Code Review on: pull_request: types: [opened, synchronize, reopened] pull_request_review_comment: types: [created, edited] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: your-org/open-code-reviewv1 with: github-token: ${{ secrets.GITHUB_TOKEN }} api-key: ${{ secrets.OPENAI_API_KEY }} api-base: ${{ secrets.OPENAI_API_BASE }} model: gpt-4o-mini第三步也是很多人容易忽略的一步配置 Actions 的权限。上面的 yaml 里写了permissions字段这是必需的。如果没有显式声明pull-requests: write权限GitHub 默认只给只读权限机器人就只能读 PR 信息、不能写评论整个工具就只剩报错的功能了。第四步是测试。随便开一个 PR改点东西push 上去等 Actions 跑完。如果一切正常大约两分钟后 PR 页面会出现机器人的审查评论如果失败点进 Actions 页面看日志排查。5.2 Dockerfile 与依赖管理由于 Action 以 Docker 方式运行Dockerfile 的编写也有讲究。核心是镜像要轻、构建要快、运行时依赖要锁版本避免“今天能跑明天挂了”的随机性问题。FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . ENTRYPOINT [python, /app/main.py]这里用的是python:3.11-slim而不是完整版镜像体积从 1GB 级降到 200MB 左右拉取和启动都快很多。requirements.txt里的依赖我锁了精确版本号防止上游库更新引发行为不一致。之前吃过亏有个依赖库小版本升级之后分页接口返回的数据结构变了CI 从稳定运行直接变成全部报错排查了半天。5.3 与既有工作流的集成方式最后一个实用话题怎么让这个工具和团队已有的流程和谐共存。我的建议是把它当成第一道自动门而不是评审流程里的唯一角色。推荐的工作流顺序是push 代码 - 跑 lint 和单测 - 跑 open-code-review - 人工 review。lint 和单测负责第一层筛选把低级问题挡在门外open-code-review 负责第二层筛选从逻辑、安全、健壮性角度找问题人工评审专注在最关键的业务匹配度和设计合理性上。三层各有侧重互不挤占。这个顺序还有一个好处lint 和单测的结果是确定的跑挂了就不会走到后面的步骤可以帮团队省下模型调用的费用——毕竟 LLM API 是按 token 收费的代码质量越差审查成本越高。6. 常见问题与排查技巧实录6.1 问题速查表我踩过的坑和排查方法这套工具上线之后我从实际使用中收集了不少问题。按出现频率从高到低整理成一张速查表每一条都是实测踩过的。现象可能原因解决办法Action 执行后没有任何评论Token 权限不足检查 workflow 的 permissions 是否声明pull-requests: write行级评论报 422 错误行号不在 diff 上下文中捕获异常降级为汇总评论Model 返回超时diff 过长超出模型上下文限制减小 max-files按文件分块审查重复评论刷屏上一次的问题未被修复又触发审查写评论前先查已有评论并去重审查结果是一堆空话Prompt 约束不严强化“不确定的不要提”约束降低 temperature本地能跑 CI 不能跑依赖版本漂移requirements.txt 锁定精确版本号Dependabot 的 PR 也触发审查机器人 PR 也会触发 workflow在 on 条件里排除 actor 为 dependabot审查覆盖不到某些文件类型文件过滤规则太激进检查 parse_changed_files 中的扩展名黑名单6.2 误报率过高的处理经验误报是这类工具最致命的问题。我的第一版 prompt 误报率接近 40%就是说模型报出的问题里四成根本不算问题。这会造成两个危害开发人员要花时间一条条核实时间成本比人肉评审还高更严重的是信任崩塌试过几次发现全是噪音之后大家就会对整个工具的输出置之不理。针对误报我做了三轮调整。第一轮改 prompt加上“只报告你确信有问题的地方”第二轮加规则明确列出了不能审查的文件类型和跳过条件第三轮调整审查的代码上下文窗口让模型看到更完整的上下文再下结论。三轮下来误报率降到了大约 15%。15% 仍然不算低但相对于它发现真实问题的价值这个比例团队是可以接受的。在工具积累了一定的真实 review 数据之后还可以做一个反馈回路——人审时如果点“不是问题”把样本收回来用来迭代 prompt。6.3 大 PR 的审查策略调整还有一个实际工作中必然遇到的高频问题大 PR。一个 PR 改了 60 个文件、2000 行代码直接全量审必然超时、超 token、结果也大概率是泛泛而谈。我的策略是分级审查先跑一个快速摘要输出这次 PR 的主干改动逻辑然后按文件维度逐个审查只挑风险最高的文件深入审。风险高的判断规则是改动行数超过 100 行的文件、涉及核心逻辑的目录比如 auth、payment、db、新增文件而不是修改文件。每个文件单独构造一次模型调用这样即使单个文件 diff 很大也不至于把一个请求撑爆。代价是调用次数变多、总耗时变长但换来的是结果质量稳定。如果团队要求更快的响应速度可以把并行度调高多个文件同时去请求模型时间能压到一分钟以内。6.4 成本控制如何让每块钱都花在刀刃上最后聊聊成本。LLM 做 code review 是按 token 计费的一个 10 文件的中型 PR完整审查大约消耗 2 万到 4 万 token。如果天天大量提交月底账单确实肉疼。我的省钱经验有三个第一default 模型用便宜档。gpt-4o-mini在多数场景下表现够用只有遇到特别复杂的逻辑时才需要手动指定升级模型。实践中大约 90% 的 PR 用 mini 档就能发现问题。第二精确控制输入上下文。只发送和修改相关的代码片段不要整个文件灌给模型。很多误报其实也跟上下文过载有关——模型看了太多无关代码注意力被分散反而对关键问题不敏感。这个策略同时提升了质量、降低了成本一举两得。第三添加一个review-mode参数设置成changed时只审查变更行附近的内容不分析整个文件。这个模式对“改了一行但引发全局 bug”这种问题的发现率会低一些但对大部分规范类、健壮性类问题足够用。想要深度审查时再手动开full模式。7. 后续还能怎么扩展我已经跑通的核心流程是PR 触发 - 拉 diff - LLM 审查 - 行级评论回写。这套骨架稳定之后扩展方向其实非常清晰。第一个方向是把审查结果接入仓库的规则引擎比如通过 GitHub 的 branch protection 设置当 open-code-review 标记出 high 级别问题时PR 不允许合并。这能让工具的定位从“建议助手”升级为“质量关口”。但要注意这个功能需要谨慎设计得给人工 review 留一个“忽略并强制合并”的口子否则会把工具架到开发者的对立面。第二个方向是针对特定领域定制 Prompt。目前这套 Prompt 是通用的对 Python 和 JavaScript 代码效果最好。如果团队主要是写 Go 或者 Rust可以把并发安全相关的审查维度加强如果是前端团队可以把重点放在组件性能、依赖体积、样式副作用上。Prompt 是这套系统里性价比最高的调优点改动一个字都可能带来体验的明显提升。第三个方向是沉淀内部的 review 知识库。每次人工评审时的修改意见其实都是团队的隐性知识资产。把常见问题和标准回复整理成 few-shot 样本喂给模型工具的审查能力会越用越贴近团队的标准。这条路我还没完全打通但方向已经验证过可行。我在团队里推这套流程时最深的体会是工具替代不了人的判断力但它能把人从重复劳动中解放出来让人有精力去做更值得做的事。open-code-review 这个名字里的 open既是指这个工具本身开源也是在提醒我——评审的标准要开放要接受团队成员的不同观点工具的结论永远只是参考真正的决策权始终在人的手里。