AI PR门禁：大模型驱动的代码审查与GitHub Actions自动化实践

1. 先拆清楚：AI PR 门禁到底在门禁什么

很多同学第一次听到“AI PR 门禁”这个词，第一反应是：是不是机器人来审核代码？其实不是那么玄乎。它做的事情，本质上是把原来靠人肉 review 才能完成的那一部分“低水平重复劳动”，提前用大模型在提交阶段拦一道。比如常见的检查项有：

• commit message 是否符合规范：是不是又是“fix bug”“update”“提交一下”这种毫无信息量的标题；
• PR 描述是否足够清晰：有没有写清楚“为什么改”“改了什么”“怎么验证”，还是只贴了一个 Jira 链接就完事；
• 代码变更是否引入常见低级问题：比如调试日志忘了删、密钥写进代码里、TODO 堆积成山、明显的大文件改动等；
• 破坏性变更有没有主动声明：改了接口、改了数据库字段，却连个“Breaking Change”提示都不给。

换句话说，AI 门禁不是要替代人工评审，而是把“一眼就能看出问题”的那部分脏活先机器自动做掉，让参与评审的同事把精力留给真正需要思考的地方：设计合理性、扩展性、业务逻辑正确性。

这里我补一句自己的定义：AI PR 门禁 = 在 CI 阶段，通过调用大模型接口，对 PR 的元信息、diff 内容、状态进行结构化打分与规则检查，并把判定结果作为 GitHub Action 运行结果中的“必须通过的检查项”暴露出来。理解了这一点，后面所有配置逻辑都顺了。它本质上还是一个 CI 任务，只不过“审查者”从人类换成了模型。

它适合谁？适合团队里已经有比较明确的代码规范文档、但人肉执行容易打折扣的组；适合开源项目维护者，没那么多时间逐个看陌生贡献者的 PR；也适合那种“开发节奏极快、review 资源严重不足”的业务团队。注意，它不是银弹，不能指望它抓住所有逻辑 bug，但把“规范类、描述类、明显风险类”的问题摊开摆在桌面上，已经能省掉可观的时间。

2. 关键前提：模型选型与上下文理解

做这个门禁，第一步不是写 YAML，而是想清楚你打算用它检查什么、愿意接受多高的成本。这直接决定了模型选型。

从实际情况看，社区里做得比较多的路线是走大模型的代码理解能力 + 规则判断能力，而不是让它做“自由发挥式的 code review”。所以模型选型我会优先考虑在代码任务上表现稳、响应快、价格可控的那几档。我自己用过的组合里，比较稳的是：

• 高成本高能力档：用于复杂 diff 审查，样本量大时准确率最高，但每次 PR 检查成本也最高，适合大库、核心模块；
• 成本适中档：主流业务 PR 用这个档位就能覆盖大部分场景，处理常规代码规范、描述质量检查完全够用；
• 低成本快速档：只做 commit message 和 PR 描述检查时，用这个档位非常香，快、便宜，效果也不差。

怎么选，我的建议很简单：先用小样本量把你团队的“典型 PR”分别跑一遍，用真实历史 PR 测，不用造数据。看看哪个模型能识别出你真正在意的那些问题类型，再定档位。不要一上来就追求最强模型，因为 AI 门禁是每笔 PR 都会跑一次的，成本是持续性的，省下的钱吃顿好的不香吗。

上下文这块，我习惯构造三段输入：

• 团队规范摘要：不要直接扔一份几十页的开发规范进去。模型对超长上下文的注意力是有限的，重点抽取和 PR 检查强相关的条目，比如提交格式、文件大小上限、禁止硬编码密钥、TODO 处理要求；
• 本次变更摘要：把 PR 标题、描述、commit 列表、变更文件列表汇总成一段结构化的“元信息”；
• diff 样本：这是成本和效果的关键平衡点。全量 diff 很长，尤其大型 PR 动辄几千行。我建议做分段截取策略：对改动文件先按“新增行数 + 删除行数”排序，优先取影响面最大的 top N 文件，再抽取每个文件的前若干行关键 diff 上下文。

这里有一个经验点：不要盲目全量喂入大模型的上下文。一是成本不可控，二是模型对过长输入的注意力会衰减，审查效果反而下降。用“规范摘要 + 变更摘要 + diff 样本”三段式输入，是一个工程上更可靠的结构。

3. 实施总览：三步完成接入

整体路径就三步：准备一个具备有效访问凭据的模型 API → 编写 AI 审核服务工作流并封装成可调用接口 → 将这个接口接入 GitHub Actions 的检查环节。

下面分开细讲，每一步都会给出可直接用的方案和关键参数。

4. 第一步：准备模型 API 访问能力

在写任何代码之前，先解决“AI 能力从哪里来”的问题。

这步看上去简单，但很多团队真正卡住的点反而在这里。第一是密钥管理，第二是访问路径，第三是允许的调用并发和速率。

先说密钥管理。绝对不要把 API Key 明文写在代码仓库里，这是底线。即使你的仓库是私有库，一旦权限控制有疏漏，后果就是泄露。实际做法是把它配置成 GitHub Actions 的 repository secret：仓库设置 → Secrets and variables → Actions → New repository secret，变量名比如AI_API_KEY、AI_API_BASE。后续 workflow 里通过${{ secrets.AI_API_KEY }}引用即可。

再说访问路径。如果你是国内网络环境，直接调某些模型的官方 API 端点可能有延迟甚至超时问题。我的建议是统一走一个代理网关或者使用已在境内提供稳定服务的模型平台，具体怎么配，看你的实际环境。关键是：CI 是无人值守的，任何网络波动都会直接影响开发者提 PR 的体验，所以网络链路的稳定性优先级高于一切。

最后说调用参数。以最常见的对话补全接口为例，请求体里我会显式设置这些字段：

• model：指定模型名称；
• temperature：固定为 0，不允许发散，审查场景要的是稳定输出；
• max_tokens：限制输出最大长度，防止模型长篇大论；
• response_format：如果接口支持，直接指定 JSON 结构化输出。

注意，两个最容易忽视的参数：timeout和max_retries。CI 场景下模型服务也可能抖动，请求超时和重试策略必须提前定好。超时我一般设 30 秒以上，重试 2 次左右，同时要设置“失败默认放行”的后备策略。这个后备策略极度重要：AI 服务不可用，不应该阻塞开发者的正常提交流程。要么在代码里 catch 异常返回“通过（但注明未审查）”，要么在 workflow 层面用continue-on-error: true跳过本步。你总不希望模型供应商稍微抖动一下，整个团队的交付节奏就卡死。

注意：在密钥和访问路径就绪之前，不要进到下一环节。这一步的稳定性，直接决定后续整个门禁的可用性。

5. 第二步：编写并运行 AI 审查工作流

在拿到模型 API 访问能力之后，核心任务就是写一个“AI 审查服务”。它要完成：

• 拉取 PR 的元信息（标题、描述、commit 列表）；
• 拉取并组装 diff 样本；
• 拼接“规范摘要 + 变更摘要 + diff 样本”的 prompt；
• 调用模型接口，拿到 JSON 结构化结果；
• 将结果映射为明确的 pass / fail 结论。

这里强烈建议不要把所有逻辑都塞进 YAML 里的run步骤，那将是灾难。正确做法是单独写一个小服务，可以是 Node.js、Python，都无所谓，重要的是它可以在本地运行、可以在 CI 运行、接口统一。以 GitHub Actions 生态的贴近程度和依赖简洁度来说，我比较推荐 Node.js 或 Python，二选一。

下面给出一个 Python 版的核心示例，以最常见的模型 API 接口格式举例：

import os import json import requests API_KEY = os.environ["AI_API_KEY"] API_URL = os.environ["AI_API_URL"] def normalize_diff(diff_text, max_chars=6000): # 优先截取 diff 中新增行较多的片段，控制 token 成本 lines = diff_text.splitlines() result = [] count = 0 for line in lines: result.append(line) count += len(line) + 1 if count >= max_chars: result.append("... [diff truncated]") break return "\n".join(result) def review_pr(pr_meta, team_rules, diff_sample): normalized_diff = normalize_diff(diff_sample) prompt = f""" 你是一个严格的代码评审助手。请根据以下团队规范和变更信息，对 PR 进行审查。 团队规范： {team_rules} PR 信息： {pr_meta} 变更内容： {normalized_diff} 请严格输出 JSON 格式，结果如下： {{ "summary": "简短的总体评价", "issues": [ {{ "severity": "error|warning|info", "category": "category name", "location": "file or general", "detail": "问题描述" }} ], "should_block": true或false }} """ resp = requests.post( API_URL, headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": os.environ.get("AI_MODEL", "default-model"), "messages": [{"role": "user", "content": prompt}], "temperature": 0, "max_tokens": 2000, }, timeout=30, ) resp.raise_for_status() data = resp.json() # 解析模型输出中的 JSON 部分 content = data["choices"][0]["message"]["content"] content = content.strip() if content.startswith("```"): content = content.split("```")[1] if content.startswith("json"): content = content[4:] return json.loads(content)

代码逻辑不复杂，重点看三件事：

• normalize_diff函数体现了成本控制思路，这很重要；
• temperature: 0保证了输出稳定性，不让模型“自由发挥”；
• 输出结构强制为 JSON，方便后续 CI 解析和展示。

跑起来的方式有两种，二选一都可以：

• 作为 GitHub Actions 的某个 step 直接python review.py运行；
• 或者先部署为一个常驻 HTTP 服务，Actions 里用curl调它。

第一种简单、依赖少，但“审查逻辑”和 CI 配置会绑在一起；第二种把审查能力从 CI 中解耦出来，后续可以在 GitLab CI、Jenkins 等其他流水线复用。我个人更推荐第二种，但是第一阶段用第一种快速跑通也没有问题，先跑起来再说。

在本地调试时，可以先把 PR 的元信息和 diff 导出来，在本地构造 prompt，跑一次脚本，看看模型输出是否符合预期。这一步非常重要，因为 prompt 的措辞会直接影响检查效果，不要指望一次写对。

6. 第三步：接入 GitHub Actions 并让门禁真正生效

服务写完以后，下一步就是在 GitHub Actions 中定义新的 workflow，让它成为 PR 的“required check”。

先创建.github/workflows/ai-pr-review.yml：

name: AI PR Review on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write jobs: ai-review: runs-on: ubuntu-latest timeout-minutes: 10 steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install dependencies run: pip install requests pyyaml - name: Collect PR metadata id: pr_info run: | echo "title=$(gh pr view ${{ github.event.pull_request.number }} --json title -q .title)" >> "$GITHUB_OUTPUT" echo "body=$(gh pr view ${{ github.event.pull_request.number }} --json body -q .body)" >> "$GITHUB_OUTPUT" - name: Build diff id: diff run: | git diff origin/main...HEAD > /tmp/pr.diff wc -l /tmp/pr.diff - name: Run AI review id: ai_review env: AI_API_KEY: ${{ secrets.AI_API_KEY }} AI_API_URL: ${{ secrets.AI_API_URL }} run: | python review.py --pr-diff /tmp/pr.diff > /tmp/review_result.json cat /tmp/review_result.json - name: Comment and set status run: | python post_result.py --result /tmp/review_result.json env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

有几个细节值得展开：

1. permissions段必须显式声明，尤其是pull-requests: write权限，这样后续脚本才能通过 GitHub API 在 PR 下留言；
2. fetch-depth: 0是为了拉取完整 git 历史，方便正确计算 diff；
3. timeout-minutes: 10也不可少，防止模型响应慢导致任务无限挂起；
4. 准确说，需要的 token 是GITHUB_TOKEN，默认情况下 Actions 会自动注入，它的权限受permissions字段控制。

然后，要让门禁真正“生效”，至少要让这个 job 的总结状态作为 PR 合并的硬性条件。步骤是：打开仓库 Settings → Branches → Branch protection rules → 选择目标分支（通常是 main）→ 在 “Require status checks to pass before merging” 中勾选刚刚创建的 job 名称ai-review。

这里有一个非常常见的坑：GitHub 上显示的名称，和你在 YAML 里定义的 job id 不一定一致。在分支保护规则里识别的是 job 的name，不是id。如果你在 YAML 里写了name: AI PR Review，那么在 settings 里看到的就是AI PR Review；如果没写name，默认才是 job 的id。建议看情况配置，不要选错。

还有一个容易被忽略的点：continue-on-error或者“失败自动跳过”的策略。在分支保护规则设置好之后，一旦这个 job 挂了，PR 默认是没法合并的。这在 AI 服务不可用的时候就成了“事故放大器”。所以建议在 workload 的头部加一个容错处理：

- name: Health check run: | if ! curl -s --max-time 5 "${{ secrets.AI_API_URL }}" > /dev/null; then echo "AI service unavailable, skip review" exit 0 fi

或者干脆在脚本入口处补充异常捕获，返回 pass 状态并注释“未审查”。两种方案都能避免把 AI 服务可用性当作 PR 合入门槛，我个人偏向后者，因为它保留了“可观测性”，而不是默默跳过所有检查。

7. 关键细节与判定策略：如何让门禁既有用又不恼人

接入动作完成之后，接下来最重要的问题是：怎么判定一个问题到底是“必须修”还是“仅提示”？

如果所有问题都设成 error，团队每天的 PR 会被一堆鸡毛蒜皮的 warning 挡住，开发体验直接崩。如果所有问题都是 info，又等于没做。

我用过比较好用的判定口径是：只把“可能导致线上故障、安全问题、严重背离团队规范”的问题定为should_block: true，其他的先以 warning 或 info 形式在评论中列出，让开发者自行判断。具体来说：

• error（拦截）：硬编码密钥、明显越权接口暴露、删除核心文件、破坏性 API 变更却无声明、提交信息完全空白无描述；
• warning（提醒）：diff 超过 1000 行未拆分、包含 TODO/FIXME、日志输出疑似调试残留、PR 描述缺少测试说明；
• info（提示）：未添加相关单测、命名风格与目录规范有出入、依赖库版本未锁定等。

对于模型给的判定，我一般还会加一道“后置规则”做兜底。比如：

• 如果 pull request 标题或分支名包含多个高频关键词，且有明显冲突，判定为 error；
• 如果描述里出现“fixes #1234”这样能够关联 issue 的格式，加分；
• 如果 diff 里包含-----BEGIN RSA PRIVATE KEY-----这类明显密钥串，直接 error。

这样做的本质是：AI 判断作为主体，但确定性规则作为最后一道保险。毕竟模型有概率性，而 CI 门禁要尽可能“可预期”。把两者结合，既利用了大模型的语义理解能力，又保证了关键风险不会被“漏判”。

另外还有一个细节：检查结果如何展示。我建议脚本在 PR 下留言，而不是仅仅在 Actions 日志里输出。因为开发者的日常工作流程是看 PR 页面，不会主动去翻日志。留言内容建议用紧凑的表格，逐条列出问题级别、类别、所在文件、建议。下面是一个参考格式：

通过 GitHub API 提交评论时，构造一个 Markdown 消息即可。这一步需要用到GITHUB_TOKEN，权限就是前述 permissions 里声明的pull-requests: write。

8. 本地调试与模拟 CI 环境：接入前的必经之路

很多人一上来就直接写好 workflow，推到远端，然后反复看 Actions 日志，效率低到令人崩溃。我的经验是：先在本地把完整链路模拟一遍，稳住之后再推到远端。

具体做法是：

1. 在本地建一个临时目录，把 review 脚本和 post_result 脚本放进去；
2. 用git diff导出一个代表你日常改动的 diff 样例；
3. 设定好环境变量AI_API_KEY、AI_API_URL、GITHUB_TOKEN（可以用gh auth token临时获取一个本地 token）；
4. 手动执行python review.py --pr-diff /tmp/pr.diff，检查模型输出能否被正确解析；
5. 再手动执行python post_result.py，看能否成功识别参数并把结果格式化输出。

这样在本地暴露的问题，几乎都是纯逻辑问题，比在 CI 的“黑盒”日志里排查要快得多。模型输出不稳定的时候，尤其需要这一步的反复调优，因为 prompt 需要一点点磨。

另一个小建议：先拿 10 个历史上的真实 PR 做过一遍离线验证。把每个 PR 的 diff 和描述输入模型，看它给出的问题和当时真实评审的意见重合多少。如果命中率低，先调 prompt、调整补充上下文，而不是盲目换模型。我试过用更强的模型但 prompt 没调好，效果反而不如小模型 + 高质量 prompt。记住一点：模型能力是基础，prompt 才是发挥空间。这步做扎实了，CI 接入只是水到渠成。

9. 常见问题与故障排查实践

最后集中整理我在实际跑这套流程时踩过的坑，按出现频率从高到低列出来：

有一个我印象最深的坑，值得单独提一句：actions/checkout 的fetch-depth默认是 1，即只拉取最新一次提交。这种情况下，如果你直接用git diff origin/main...HEAD计算 diff，会发现自己拿到的永远只有最后一次提交的内容，甚至直接报错告诉你不知道origin/main。这是让很多第一次接入的人怀疑人生的原因。正确做法是在 checkout 步骤加上fetch-depth: 0，拉取完整历史。如果你有充足的理由不想拉全量历史，也可以至少设置为一个较大的数值，比如fetch-depth: 50，再用git diff HEAD~1...HEAD这种局部范围。

另外，如果要让 AI 审查结果不只是“说句话”，而是像一个真正的门禁那样影响合并状态，记得在脚本里设置 process exit code，比如 0 表示通过，1 表示未通过。GitHub Actions 正是根据这个 exit code 判定 step 是否失败的。不要只往 PR 里写评论，exit code 为 0 却 exposer smoking_gun，那门禁就名存实亡了。

10. 接入后的调优思路与成本观察

接入成功只是起点，后面很长一段时间的重点工作是“调优”。我自己的调优迭代通常从两个数据维度入手：

• 拦截准确率：被门禁拦截下来的 PR 中，有多少是开发者确实“应该修”的。如果比例很低，说明 prompt 或判定阈值过严，会严重磨损团队的耐性；
• 漏网率：合并后线上出问题、但门禁没有拦截的 PR 占最终问题 PR 的比例。这个数据需要结合线上故障复盘来评估，通常能发现门禁规则覆盖的盲区，然后补充 prompt 示例或加确定性规则。

成本观察方面，建议记录每次 PR 审查的 token 消耗。不同团队的代码量和 PR 频率差别很大，有的库一个 PR 平均就 200 行改动，有的核心模块改动轻松上千行。对后者，必须做好 diff 截断和分段审查的设计。

我见过一个比较成熟的团队把审查分成两段：先检查 PR 描述与提交信息，再检查代码 diff。前者用小模型低成本快速过，后者按文件影响面分段喂给更聪明的模型。这种分层设计可以有效控制成本，也能提高结果的可读性。这也是我想强调的：AI 门禁不是一个“配置完就完事”的工具，它需要你像维护测试用例一样，持续补充 prompt 示例、调整判定阈值、跟进误报和漏报。

形式上，AI 审查结果最好能和团队的 code review 流程自然融合。比如常见做法是：门禁只负责“拦截明显问题”，同时把补充意见以评论形式留在 PR 里，让评审人员参考，而不是替代人类。这样既保证机器检查的执行力，又保留人工评审的自主空间，团队接受度会高很多。

11. 经验沉淀：团队落地时容易踩的衔接坑

最后这部分，说说“技术之外”的坑。往往一个功能单看技术实现并不复杂，难的是让它真正在团队里被顺畅使用。

• 先定规则再写 prompt。如果团队自己都说不清“坏 PR”长什么样，AI 自然更说不清。我在实际推动这个项目的时候，第一件事是先和团队确认了一份精简版 PR 检查清单，统一口径，后续 all prompt 和规则都围绕这份清单来建。
• 给开发者留“解释出口”。AI 门禁拦截之后，开发者如果觉得是误报，最好能有一条申辩路径。例如在 PR 评论里标记/ai-review-ignore，再由人工维护者决定是否放行。否则频繁误杀会引发抵触情绪。
• 做好面向开发者的结果展示。尽量让 AI 给出的每一条问题，都带一个简短的“为什么这是问题”“怎么修”的建议，而不是冷冰冰一句“diff too large”。开发者愿意看，门禁才能真正改变行为。
• 灰度放量。不要第一周就对全仓库强制要求。可以先只在部分模块或部分类型的 PR 上开启检查，观察准确率和团队反馈，再逐渐放大范围。直接一刀切，容易在初期就把功能口碑做坏。

我自己是经历过“一上来就全线开启”的教训的。头两周团队里几乎每天都会有人来问“这个 AI 是不是疯啦”，因为误报率确实还在高位。调整成灰度推进之后，节奏舒服了很多：先把硬规则（密钥检测、题描述必填、commit 信息不规范）打好底，模型审查作为后续迭代逐步加强。

如果你是想在团队里推这件事，我的建议是先在某个小项目或自己维护的仓库里跑通整条链路，再推广到主力仓库。整个过程其实没有太多神秘感，就是一个“服务 + 规则 + CI 集成”的组合动作。技术实现层面，大概率半天到一天就能完成初版；真正耗时的是你不断调试 prompt、调整阈值、让检查结果在“有效”和“不打扰”之间找到平衡。这个平衡，是 AI 门禁能不能长期留在你 CI 流水线里的关键。