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_chars6000): # 优先截取 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: fBearer {API_KEY}}, json{ model: os.environ.get(AI_MODEL, default-model), messages: [{role: user, content: prompt}], temperature: 0, max_tokens: 2000, }, timeout30, ) 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.ymlname: 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/checkoutv4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-pythonv5 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 }}有几个细节值得展开permissions段必须显式声明尤其是pull-requests: write权限这样后续脚本才能通过 GitHub API 在 PR 下留言fetch-depth: 0是为了拉取完整 git 历史方便正确计算 difftimeout-minutes: 10也不可少防止模型响应慢导致任务无限挂起准确说需要的 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 页面不会主动去翻日志。留言内容建议用紧凑的表格逐条列出问题级别、类别、所在文件、建议。下面是一个参考格式级别类别位置说明errorSecret Leaksrc/config.js:42疑似硬编码 API 密钥请改为环境变量warningOversized Diffsrc/api/order.js本次改动 842 行建议拆分为多个 PRinfoMissing Testsrc/lib/parser.js新增逻辑未包含单元测试通过 GitHub API 提交评论时构造一个 Markdown 消息即可。这一步需要用到GITHUB_TOKEN权限就是前述 permissions 里声明的pull-requests: write。8. 本地调试与模拟 CI 环境接入前的必经之路很多人一上来就直接写好 workflow推到远端然后反复看 Actions 日志效率低到令人崩溃。我的经验是先在本地把完整链路模拟一遍稳住之后再推到远端。具体做法是在本地建一个临时目录把 review 脚本和 post_result 脚本放进去用git diff导出一个代表你日常改动的 diff 样例设定好环境变量AI_API_KEY、AI_API_URL、GITHUB_TOKEN可以用gh auth token临时获取一个本地 token手动执行python review.py --pr-diff /tmp/pr.diff检查模型输出能否被正确解析再手动执行python post_result.py看能否成功识别参数并把结果格式化输出。这样在本地暴露的问题几乎都是纯逻辑问题比在 CI 的“黑盒”日志里排查要快得多。模型输出不稳定的时候尤其需要这一步的反复调优因为 prompt 需要一点点磨。另一个小建议先拿 10 个历史上的真实 PR 做过一遍离线验证。把每个 PR 的 diff 和描述输入模型看它给出的问题和当时真实评审的意见重合多少。如果命中率低先调 prompt、调整补充上下文而不是盲目换模型。我试过用更强的模型但 prompt 没调好效果反而不如小模型 高质量 prompt。记住一点模型能力是基础prompt 才是发挥空间。这步做扎实了CI 接入只是水到渠成。9. 常见问题与故障排查实践最后集中整理我在实际跑这套流程时踩过的坑按出现频率从高到低列出来问题现象排查思路Actions 日志显示 403脚本调用 API 被限流或权限不足检查密钥是否有调用权限检查是否配置了正确的permissions段尤其是否遗漏pull-requests: write模型返回内容不是合法 JSONjson.loads报错在脚本里做 JSON 提取容错先去掉 markdown 代码块再解析。如果还是不稳定考虑在 prompt 中强化 JSON 约束或者用接口返回的 JSON 模式分支保护规则找不到 job 名称Settings 里看不到刚创建的 job首先确认 workflow 至少跑成功过一次否则 GitHub 无法注册该检查项其次确认你勾选的名称和 job 的name字段一致本地跑通、CI 跑失败环境变量没找到检查 secrets 是否配置检查 workflow 中 env 引用是否拼写一致。特别注意 YAML 缩进env和run的层级不对会导致变量不可见API 超时导致 job 卡死任务长时间处于 pending 或 running设置timeout-minutes在脚本中给requests传timeout参数并做重试与降级大型 PR 审查结果质量差明显问题没抓到或误报检查 diff 截取逻辑是否截到了正确区域。建议优化为“优先取新增行数最多的文件”而不是按文件名字母序截取模型服务不可用时影响合并正常 PR 无法合并按前文方案做失败放行或continue-on-error并保留日志便于事后排查有一个我印象最深的坑值得单独提一句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 流水线里的关键。