1. PR 门禁到底拦什么先搞懂需求再动手如果你维护过 GitHub 仓库一定经历过这种场景每天打开 Pull Request 列表十几条待审查每条改动几百行。人工逐行看一遍精力基本耗在格式、命名、边界条件这些重复劳动上真正需要深度思考的设计问题反而没时间看。这时候AI PR 门禁的作用就体现出来了——它不是一个花哨的“自动机器人评论”而是一道在合并前必须通过的检查关卡。所谓“三步把 AI PR 门禁接进 GitHub Actions”说白了就是让 AI 在 PR 提交时自动审查 diff给出通过/拒绝的结论再把结论挂到仓库的分支保护规则里。代码没过关合并按钮就是灰的。这样做带来的最直接好处是基础问题被自动拦截人工 reviewer 只需要看 AI 挑剩下的、真正值得讨论的部分。我先把话放在前面这不是什么高不可攀的架构设计核心就三个环节——封装审查规则、调用模型、配置强制检查。你不需要自建模型服务不需要写复杂的推理框架只要有一个模型 API 的调用权限加上一个能跑脚本的 GitHub Actions 流程就能把门禁跑起来。下面从需求拆解开始把每一步的原理和代码都讲透。1.1 先想清楚门禁要拦什么问题很多人一上来就写提示词结果门禁上线第一天就把团队惹毛了AI 对每行代码都提意见PR 永远过不了最后被人手动跳过。问题出在需求没想清楚。门禁适合拦截的是那些“规则明确、可以被机械判断”的问题。典型的有三类风格与约定类命名不统一、缩进混乱、TODO/FIXME 残留、死代码。安全与隐患类硬编码密钥、SQL 拼接、危险函数调用、敏感信息打印。一致性类新代码没有配套测试、接口变更后调用方没同步改。不适合让 AI 门禁“一票否决”的是设计架构类问题。比如“这里该不该拆微服务”“表结构这样设计是否合理”这类判断依赖上下文模型容易误伤。所以我的建议是第一版门禁的规则宁可少而精只设 3 到 5 条硬规则跑通了再慢慢加。与其追求“AI 什么都能审”不如先做到“审一件是一件审得准”。1.2 模型选型和成本控制选模型这事没必要迷信“最大的就是最好的”。代码审查场景对模型的代码理解能力和输出格式稳定性要求高但对知识广度要求没那么高。我自己用了很长一段时间的通用 chat 模型配置好提示词后效果完全够用。成本上要有个预期每审查一次 PR消耗的 token 大致等于 diff 全文长度加上系统提示词和输出。一个几百行改动的 PR单次成本通常很低但如果团队每天有几十个 PR一个月下来也是一笔开销。省钱的办法很直接只把 diff 发送给模型不要附带整个文件历史。超出阈值的超大 PR 直接跳过 AI 审查标记为“请人工审查”。模型输出限制为结构化 JSON只保留关键字段避免长篇大论。关于 API 密钥只有一个原则永远不要写进代码库。放到 GitHub 仓库的 Secrets 里在 Actions 中用环境变量引用。后面踩坑清单部分我会专门讲权限配置的问题。2. 三步接入的实操拆解这一部分直接给可落地的方案。假设你已经有一个 GitHub 仓库并且对 YAML 语法和 git 操作有基础了解。我会从零开始把每一步的命令、代码和配置写出来。2.1 第一步把审查规则固化成提示词提示词是门禁的灵魂。很多人以为把代码扔给模型、问一句“有没有问题”就行实际效果会很差。模型的回答会很泛“建议优化代码风格”“注意潜在风险”——这种输出根本没法作为门禁依据。要做成“门禁”必须让模型的输出是结构化的、确定性的。我现在的做法是系统提示词里定义角色和规则用户提示词里放 diff 内容最后强制要求模型输出 JSON。一个经过多次迭代的提示词模板如下你是一个严格的代码审查助手。请审查以下 diff只报告与规则直接相关的问题。 审查规则 1. 禁止硬编码密钥、Token、密码包括测试代码中的假密钥。 2. 禁止将未清空的用户输入直接拼入 SQL、Shell 命令或 HTML。 3. 新增函数必须包含类型注解Python或明确类型声明TypeScript。 4. 禁止遗留 console.log、debugger、TODO、FIXME。 5. 每个新增公共函数必须有对应的单元测试。 输出要求只输出 JSON格式如下 { passed: true 或 false, issues: [ {rule_id: 1, file: src/xx.py, line: 12, message: 简短问题描述} ], summary: 最多30个字的整体评价 } 如果没有问题issues 返回空数组。这里有个关键点规则编号、输出字段一旦确定就不要频繁修改。因为你后面要写代码去解析 JSON字段变了解析逻辑就要跟着变。我在迭代过程中最大的体会就是提示词里的规则是“需求文档”输出 JSON 是“接口协议”协议稳定了整个系统才稳定。2.2 第二步用 GitHub Actions 建立检查流程工作流文件放在仓库的.github/workflows/目录下。先给一个最小可跑的版本后面我会逐段解释。name: AI PR Gate on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write jobs: ai-review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Compute diff id: diff run: | git fetch origin $BASE --depth1 || true git diff origin/$BASE /tmp/pr.diff echo diff_size$(wc -c /tmp/pr.diff) $GITHUB_OUTPUT - name: Analyze with AI id: ai env: AI_API_KEY: ${{ secrets.AI_API_KEY }} DIFF_PATH: /tmp/pr.diff run: | python3 .github/scripts/ai_gate.py - name: Post comment if: always() uses: actions/github-scriptv7 with: script: | const fs require(fs); const body fs.readFileSync(/tmp/ai_comment.md, utf8); const { repo, issue } context; await github.rest.issues.createComment({ owner: repo.owner, repo: repo.repo, issue_number: issue.number, body: body });这个工作流做了四件事检出代码、计算 diff、调用 Python 脚本分析、把结果评论到 PR 上。注意我用了fetch-depth: 0这一步很重要——如果你不把完整历史拉下来git diff可能因为缺少基线而失败。某些环境下actions/checkout默认只拉一个浅克隆所以要显式处理。permissions块很多人会忽略。默认情况下 Actions 的 token 权限有限如果不声明pull-requests: write后面调用 GitHub API 发评论时会报 403。反过来也不要随意给整个仓库写权限最小够用就好。2.3 第三步开启分支保护并设强制检查到了这一步门禁才算真正“硬”起来。没有分支保护的话PR 就算被 AI 标记为拒绝维护者还是能点“Merge”按钮门禁形同虚设。在 GitHub 仓库页面进入 Settings - Branches - Add rule。关键设置项有四个Branch name pattern填你的主干分支名比如main。Require a pull request before merging勾选这能防止直接推送主干。Require status checks to pass before merging勾选然后搜索你工作流中的 check 名称。注意这里要填的是 job 名称。如果你工作流里 job 叫ai-review状态检查名称会显示成类似ai-review或带工作流前缀的名称按页面上实际显示的来选。Require conversation resolution勾选防止有未解决的 review conversation 时合并。这里有个最容易踩的坑分支保护规则里的状态检查必须对应“一次已经跑完的工作流”。你不先跑一次 PR 让检查出现规则列表里就找不到它。所以正确的操作顺序是先创建一个测试 PR让 Actions 跑一遍确认状态出现在 Checks 中再去分支保护里把它勾选为 required。另外要注意分支保护规则是“作用于分支”的如果你仓库里多个分支都重要需要分别配规则或者用通配符。日常开发中保护main和develop通常就够了。3. 核心细节diff 获取、模型调用、结果解析现在进入真正有含金量的部分。三步框架搭起来容易但要让门禁稳定运行必须把 diff 获取、API 调用、结果解析这三个细节做好。3.1 拿到正确的 diff门禁就成功了一半门禁的输入是 diff。diff 错了后面全是错的。这里有两个重要细节。第一比较基线选什么。PR 的 diff 应该是“目标分支当前状态”和“PR 分支最新提交”之间的差异。很多人在 Actions 里直接写git diff main...HEAD这会有一个隐患如果 main 在 PR 创建后又有新提交而 Actions 检出时 main 没有更新diff 就会包含不该有的内容。稳妥的做法是在工作流里先 fetch 目标分支的最新状态再和 HEAD 做比较git fetch origin main --depth1 git diff origin/main...HEAD /tmp/pr.diff第二diff 文件大小要设上限。模型 API 对单次请求的 token 有限制一个几千行的大 PRdiff 轻松超过上限。我的处理方式是diff 超过 300KB 就跳过 AI 审查在评论里明确写“PR 过大请人工审查”。几十万 token 的请求既慢又贵强行送进去只会得到糟糕的结果。3.2 把 diff 安全地交给模型“安全”在这里有两层意思一层是密钥安全另一层是内容安全。密钥安全上面说过通过环境变量传入不在脚本里硬编码。内容安全指的是diff 里可能包含代码注释、文档片段、甚至测试数据其中可能夹带坑。比如有人把 API key 写在测试代码里AI 会把它当硬编码密钥揪出来——这其实是好事。但反过来如果 diff 里有一段英文注释和审查规则无关模型可能误判。要缓解误判脚本里可以过滤掉纯注释行、空行、以及只修改空格的噪音 diffimport re def clean_diff(raw): lines raw.splitlines() out [] for line in lines: stripped line.strip() # 去掉注释块和纯空格变更 if re.match(r^[-]\s*(//|#|/\*|\*|!--), stripped): continue if stripped in (, -, , ---) or stripped.startswith() or stripped.startswith(---): out.append(line) continue out.append(line) return \n.join(out)在把 diff 拼进请求之前还需要做一次 token 估算。一个粗略的规则中英文混合代码1 个 token 大约对应 3 到 4 个字符。保守起见按 2 字符/token 估算如果构造出的 prompt 超过模型上下文窗口的 60%就截断或者跳过。请求构造用最常见的 chat completions 格式Python 代码大概是这样的import os import json import urllib.request def call_model(system_prompt, user_content): api_key os.environ[AI_API_KEY] payload { model: gpt-4o-mini, messages: [ {role: system, content: system_prompt}, {role: user, content: user_content} ], temperature: 0, response_format: {type: json_object} } req urllib.request.Request( https://api.openai.com/v1/chat/completions, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, Authorization: fBearer {api_key} } ) with urllib.request.urlopen(req, timeout120) as resp: body json.loads(resp.read().decode(utf-8)) return body[choices][0][message][content]有两个参数要特别说明temperature设为 0确保输出确定性response_format强制 JSON 输出省去解析时的麻烦。如果你用的模型服务不支持强制 JSON就在提示词里加一句“只输出 JSON不要任何解释”然后做好容错。3.3 把模型的结论变成硬门禁模型返回的是 JSON 文本要成为门禁必须经过解析和判定。这里说的判定不是简单判断 JSON 里的passed字段——而是要考虑容错。模型偶尔会返回不合法的 JSON比如多了一个逗号、把布尔值写成了字符串。我写过几十个版本的解析函数目前最稳的思路是先试json.loads失败了就用正则提取括号里的内容再试还不行就给一个“整体结论超时/解析失败需人工确认”的默认值。这个默认值非常重要。宁可把门禁判为“不通过”也不能因为解析失败就放行。门禁的意义在于“默认拒绝通过需要有明确依据”。解析逻辑整理成一个独立的 Python 脚本会比较清晰。我通常把它放在.github/scripts/ai_gate.py工作流里直接调用。脚本的职责包括读取环境变量中的 API 密钥。读取 diff 文件做清洗和截断。拼接系统提示词和用户内容。调用模型 API。解析 JSON生成机器可读的 exit code 和人类可读的评论文件。关于 exit codeGitHub Actions 判断一个 step 成功还是失败靠的就是进程退出码。所以脚本最后要sys.exit(0)或sys.exit(1)。但这里有个细节如果你让脚本直接以失败退出整个 workflow 会显示为红色失败这对“门禁”是符合预期的但对“评论还是要发出来”造成了冲突。因为 Actions 的默认行为是前面的 step 失败后面的 step 不执行。解决办法有两种。一种是把调用脚本的 step 加上continue-on-error: true然后在后面的 step 里读脚本产出的结果文件来决定是否要让 workflow 最终失败。另一种是脚本自身不退出失败而是把passed结果写入文件工作流最后用一个单独的 step 去判断。我推荐后者因为逻辑更清晰- name: Check gate result if: always() run: | result$(cat /tmp/gate_result.json) passed$(echo $result | python3 -c import sys,json; print(json.load(sys.stdin)[passed])) if [ $passed ! true ]; then echo AI gate blocked this PR. exit 1 fi这样设计的好处是评论总能发出去而门禁的状态是“最终由最后一个 check 决定”。分支保护要求的是一个叫ai-review的 job 或某个自定义的状态检查实际上你可以在一个 job 里做完整件事确保只有真正通过才退出 0。4. 我在落地过程中总结的踩坑清单这部分的每一条都是我实际跑过之后才理解的。写出来希望你少走弯路。4.1 密钥和权限问题最常见的问题是 API 密钥泄露。不少人为了本地调试方便先把 key 写在脚本里推上去之后才想起来已经晚了。一定要从第一天就养成用 GitHub Secrets 的习惯。还有一点很多团队会忽略如果这个仓库 fork 了fork 仓库里的 workflow 不会继承原仓库的 secrets外部的 PR 会自动跳过需要密钥的 step。这其实是 GitHub 的安全机制防的是恶意 fork 窃取密钥。我在某个跨团队协作时遇到过外部贡献者的 PR 一直显示“一步未执行”排查半天发现就是 secrets 不继承。这种情况没法在技术上绕过合理的替代方案是外部 PR 打上ok-to-testlabel 才运行带密钥的 job。权限最小化也很重要。工作流里permissions只声明contents: read和pull-requests: write不要多给。有些教程会让你直接用GITHUB_TOKEN默认的全部权限这等于把仓库写权限交给一个只该审查代码的脚本。4.2 解析失败与超时模型接口有概率返回非 JSON 内容。即便我设置了response_format仍然遇到过一次返回空字符串的情况。排查下来发现是请求超时被网关拦截模型服务端没有返回完整响应。解决的思路是调用时设置 120 秒超时并在脚本里做三次重试每次重试之间退避 5 秒。重试要设上限否则 Actions 的耗时上限一轮下来就爆了。还有一类解析失败跟模型输出本身无关而是 diff 文件编码问题。Windows 环境下改动的文件带 CRLF 行尾模型返回的内容里可能出现\r。解析 JSON 之前先content.replace(\r, )这种问题就消失了。4.3 误报、漏报与团队信任问题门禁上线后团队里第一个反对声往往是“AI 误报了”。我见过最典型的一次一个测试文件里写了password 123456规则 1 直接判了不通过。但实际上这是一个单元测试的固定测试数据没有真实安全风险。所以后我在规则里加了一条豁免声明凡是测试文件里的 mock 数据不在规则 1 的拦截范围内。豁免机制的实现要谨慎。虽然可以在提示词里写“忽略测试文件中的假密钥”但模型会过度豁免把真正的硬编码测试密钥也放行。我最终采用的是规则描述里区分“生产代码硬编码”和“测试代码硬编码”测试代码里的硬编码只给 warning不给 failed。这个思路的代价是需要额外的判断逻辑但对团队接受度很关键。门禁的“失败”出口必须留人工干预通道。比如 PR 作者可以在评论里 维护者说明“这个是测试数据人工确认可通过”。GitHub 的 review 机制天然支持这个流程AI 门禁只是其中一个 required check维护者的“Approve review”也作为另一个 required check。两者都通过才能合并。这样既保证了 AI 的拦截能力又留了最终的人工裁决权。4.4 超大 PR 与工作流并发问题一个大 PR 能把 diff 撑爆这种情况不能让脚本去硬扛。在脚本开头做一个diff_size判断超过阈值直接写一份“此 PR 因过大致无法自动审查已转人工”的结果文件exit 1。如果你希望 AI 至少还是给点意见可以对 diff 做采样每个文件最多取前 200 行改动文件数量超过 20 个时只取影响最大的 10 个。这是一种妥协但至少保证门禁不中断。并发问题发生在多个 PR 同时触发工作流时。好在 GitHub Actions 每个 job 都是独立容器互相不干扰但要注意对GITHUB_OUTPUT的写入如果同一个 job 里多个 step 都往GITHUB_OUTPUT写同名变量后写的会覆盖先写的。我出现过一脚本把结果文件路径写成相对路径、后续 step 因为当前工作目录不同找不到文件的情况。经验是所有中间文件一律用绝对路径写入/tmp/避免目录上下文切换带来的麻烦。5. 门禁之外我建议你接着做的事一个能跑通的 AI 门禁只是起点。真正发挥价值的是在这个基础上把数据沉淀下来让门禁越用越准。5.1 自动汇总周报工作流跑完把结果往某个 JSON 文件里攒每周生成一份审查报告哪些规则命中最多、哪些文件最容易出问题、每个 PR 的平均耗时。团队聊代码质量时这些数据比感觉靠谱得多。实现上不复杂给脚本加一个写记录文件的逻辑再用一个定时工作流汇总即可。5.2 从门禁到自动修复AI 能发现问题就能尝试改。比如规则 5“新增公共函数必须有测试”模型可以基于函数签名自动生成测试模板作为评论添加到 PR 中由作者确认后使用。这个功能不要做成自动提交因为自动生成的代码质量波动大但作为“建议内容”发给作者体验提升非常明显。5.3 多仓库复用如果团队有几十个仓库不可能每个仓库都复制一份同样的工作流和脚本。把 Python 脚本做成内部共享的模板仓库用actions/checkout在步骤里引用模板仓库的路径再通过环境变量传入每个仓库的差异化配置。全局改一条规则所有接入仓库自动生效这是规模化落地时的必然选择。6. 最后分享一个我每次接入都会做的小验证如果你按上面的流程走完门禁已经能跑但我还是建议你专门花十分钟做一次“对抗测试”创建一个故意包含硬编码密钥和空函数的分支发一个 PR确认 AI 门禁把它拦下来、评论里指出问题位置然后再修正、推一个正常提交确认门禁放行。这个闭环验证的意义在于它同时验证了提示词、解析逻辑、退出码、分支保护四个环节是否串联正确。我刚做这个项目的时候最大的认知转变是门禁的重点不是 AI 审得多好多深而是它创造了一个确定性——代码在到达人工之前已经过了一遍自动化规则的过滤。一个 PR 进来团队所有人第一时间看到 AI 结论那些琐碎的、重复的、一眼就能看出的问题不再消耗人的精力。人该做的是去做机器做不了的设计判断。这套机制用起来之后我最大的感受是审查效率提升是副产品真正的收获是团队在代码质量上的讨论更聚焦了。
1. PR 门禁到底拦什么先搞懂需求再动手如果你维护过 GitHub 仓库一定经历过这种场景每天打开 Pull Request 列表十几条待审查每条改动几百行。人工逐行看一遍精力基本耗在格式、命名、边界条件这些重复劳动上真正需要深度思考的设计问题反而没时间看。这时候AI PR 门禁的作用就体现出来了——它不是一个花哨的“自动机器人评论”而是一道在合并前必须通过的检查关卡。所谓“三步把 AI PR 门禁接进 GitHub Actions”说白了就是让 AI 在 PR 提交时自动审查 diff给出通过/拒绝的结论再把结论挂到仓库的分支保护规则里。代码没过关合并按钮就是灰的。这样做带来的最直接好处是基础问题被自动拦截人工 reviewer 只需要看 AI 挑剩下的、真正值得讨论的部分。我先把话放在前面这不是什么高不可攀的架构设计核心就三个环节——封装审查规则、调用模型、配置强制检查。你不需要自建模型服务不需要写复杂的推理框架只要有一个模型 API 的调用权限加上一个能跑脚本的 GitHub Actions 流程就能把门禁跑起来。下面从需求拆解开始把每一步的原理和代码都讲透。1.1 先想清楚门禁要拦什么问题很多人一上来就写提示词结果门禁上线第一天就把团队惹毛了AI 对每行代码都提意见PR 永远过不了最后被人手动跳过。问题出在需求没想清楚。门禁适合拦截的是那些“规则明确、可以被机械判断”的问题。典型的有三类风格与约定类命名不统一、缩进混乱、TODO/FIXME 残留、死代码。安全与隐患类硬编码密钥、SQL 拼接、危险函数调用、敏感信息打印。一致性类新代码没有配套测试、接口变更后调用方没同步改。不适合让 AI 门禁“一票否决”的是设计架构类问题。比如“这里该不该拆微服务”“表结构这样设计是否合理”这类判断依赖上下文模型容易误伤。所以我的建议是第一版门禁的规则宁可少而精只设 3 到 5 条硬规则跑通了再慢慢加。与其追求“AI 什么都能审”不如先做到“审一件是一件审得准”。1.2 模型选型和成本控制选模型这事没必要迷信“最大的就是最好的”。代码审查场景对模型的代码理解能力和输出格式稳定性要求高但对知识广度要求没那么高。我自己用了很长一段时间的通用 chat 模型配置好提示词后效果完全够用。成本上要有个预期每审查一次 PR消耗的 token 大致等于 diff 全文长度加上系统提示词和输出。一个几百行改动的 PR单次成本通常很低但如果团队每天有几十个 PR一个月下来也是一笔开销。省钱的办法很直接只把 diff 发送给模型不要附带整个文件历史。超出阈值的超大 PR 直接跳过 AI 审查标记为“请人工审查”。模型输出限制为结构化 JSON只保留关键字段避免长篇大论。关于 API 密钥只有一个原则永远不要写进代码库。放到 GitHub 仓库的 Secrets 里在 Actions 中用环境变量引用。后面踩坑清单部分我会专门讲权限配置的问题。2. 三步接入的实操拆解这一部分直接给可落地的方案。假设你已经有一个 GitHub 仓库并且对 YAML 语法和 git 操作有基础了解。我会从零开始把每一步的命令、代码和配置写出来。2.1 第一步把审查规则固化成提示词提示词是门禁的灵魂。很多人以为把代码扔给模型、问一句“有没有问题”就行实际效果会很差。模型的回答会很泛“建议优化代码风格”“注意潜在风险”——这种输出根本没法作为门禁依据。要做成“门禁”必须让模型的输出是结构化的、确定性的。我现在的做法是系统提示词里定义角色和规则用户提示词里放 diff 内容最后强制要求模型输出 JSON。一个经过多次迭代的提示词模板如下你是一个严格的代码审查助手。请审查以下 diff只报告与规则直接相关的问题。 审查规则 1. 禁止硬编码密钥、Token、密码包括测试代码中的假密钥。 2. 禁止将未清空的用户输入直接拼入 SQL、Shell 命令或 HTML。 3. 新增函数必须包含类型注解Python或明确类型声明TypeScript。 4. 禁止遗留 console.log、debugger、TODO、FIXME。 5. 每个新增公共函数必须有对应的单元测试。 输出要求只输出 JSON格式如下 { passed: true 或 false, issues: [ {rule_id: 1, file: src/xx.py, line: 12, message: 简短问题描述} ], summary: 最多30个字的整体评价 } 如果没有问题issues 返回空数组。这里有个关键点规则编号、输出字段一旦确定就不要频繁修改。因为你后面要写代码去解析 JSON字段变了解析逻辑就要跟着变。我在迭代过程中最大的体会就是提示词里的规则是“需求文档”输出 JSON 是“接口协议”协议稳定了整个系统才稳定。2.2 第二步用 GitHub Actions 建立检查流程工作流文件放在仓库的.github/workflows/目录下。先给一个最小可跑的版本后面我会逐段解释。name: AI PR Gate on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write jobs: ai-review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Compute diff id: diff run: | git fetch origin $BASE --depth1 || true git diff origin/$BASE /tmp/pr.diff echo diff_size$(wc -c /tmp/pr.diff) $GITHUB_OUTPUT - name: Analyze with AI id: ai env: AI_API_KEY: ${{ secrets.AI_API_KEY }} DIFF_PATH: /tmp/pr.diff run: | python3 .github/scripts/ai_gate.py - name: Post comment if: always() uses: actions/github-scriptv7 with: script: | const fs require(fs); const body fs.readFileSync(/tmp/ai_comment.md, utf8); const { repo, issue } context; await github.rest.issues.createComment({ owner: repo.owner, repo: repo.repo, issue_number: issue.number, body: body });这个工作流做了四件事检出代码、计算 diff、调用 Python 脚本分析、把结果评论到 PR 上。注意我用了fetch-depth: 0这一步很重要——如果你不把完整历史拉下来git diff可能因为缺少基线而失败。某些环境下actions/checkout默认只拉一个浅克隆所以要显式处理。permissions块很多人会忽略。默认情况下 Actions 的 token 权限有限如果不声明pull-requests: write后面调用 GitHub API 发评论时会报 403。反过来也不要随意给整个仓库写权限最小够用就好。2.3 第三步开启分支保护并设强制检查到了这一步门禁才算真正“硬”起来。没有分支保护的话PR 就算被 AI 标记为拒绝维护者还是能点“Merge”按钮门禁形同虚设。在 GitHub 仓库页面进入 Settings - Branches - Add rule。关键设置项有四个Branch name pattern填你的主干分支名比如main。Require a pull request before merging勾选这能防止直接推送主干。Require status checks to pass before merging勾选然后搜索你工作流中的 check 名称。注意这里要填的是 job 名称。如果你工作流里 job 叫ai-review状态检查名称会显示成类似ai-review或带工作流前缀的名称按页面上实际显示的来选。Require conversation resolution勾选防止有未解决的 review conversation 时合并。这里有个最容易踩的坑分支保护规则里的状态检查必须对应“一次已经跑完的工作流”。你不先跑一次 PR 让检查出现规则列表里就找不到它。所以正确的操作顺序是先创建一个测试 PR让 Actions 跑一遍确认状态出现在 Checks 中再去分支保护里把它勾选为 required。另外要注意分支保护规则是“作用于分支”的如果你仓库里多个分支都重要需要分别配规则或者用通配符。日常开发中保护main和develop通常就够了。3. 核心细节diff 获取、模型调用、结果解析现在进入真正有含金量的部分。三步框架搭起来容易但要让门禁稳定运行必须把 diff 获取、API 调用、结果解析这三个细节做好。3.1 拿到正确的 diff门禁就成功了一半门禁的输入是 diff。diff 错了后面全是错的。这里有两个重要细节。第一比较基线选什么。PR 的 diff 应该是“目标分支当前状态”和“PR 分支最新提交”之间的差异。很多人在 Actions 里直接写git diff main...HEAD这会有一个隐患如果 main 在 PR 创建后又有新提交而 Actions 检出时 main 没有更新diff 就会包含不该有的内容。稳妥的做法是在工作流里先 fetch 目标分支的最新状态再和 HEAD 做比较git fetch origin main --depth1 git diff origin/main...HEAD /tmp/pr.diff第二diff 文件大小要设上限。模型 API 对单次请求的 token 有限制一个几千行的大 PRdiff 轻松超过上限。我的处理方式是diff 超过 300KB 就跳过 AI 审查在评论里明确写“PR 过大请人工审查”。几十万 token 的请求既慢又贵强行送进去只会得到糟糕的结果。3.2 把 diff 安全地交给模型“安全”在这里有两层意思一层是密钥安全另一层是内容安全。密钥安全上面说过通过环境变量传入不在脚本里硬编码。内容安全指的是diff 里可能包含代码注释、文档片段、甚至测试数据其中可能夹带坑。比如有人把 API key 写在测试代码里AI 会把它当硬编码密钥揪出来——这其实是好事。但反过来如果 diff 里有一段英文注释和审查规则无关模型可能误判。要缓解误判脚本里可以过滤掉纯注释行、空行、以及只修改空格的噪音 diffimport re def clean_diff(raw): lines raw.splitlines() out [] for line in lines: stripped line.strip() # 去掉注释块和纯空格变更 if re.match(r^[-]\s*(//|#|/\*|\*|!--), stripped): continue if stripped in (, -, , ---) or stripped.startswith() or stripped.startswith(---): out.append(line) continue out.append(line) return \n.join(out)在把 diff 拼进请求之前还需要做一次 token 估算。一个粗略的规则中英文混合代码1 个 token 大约对应 3 到 4 个字符。保守起见按 2 字符/token 估算如果构造出的 prompt 超过模型上下文窗口的 60%就截断或者跳过。请求构造用最常见的 chat completions 格式Python 代码大概是这样的import os import json import urllib.request def call_model(system_prompt, user_content): api_key os.environ[AI_API_KEY] payload { model: gpt-4o-mini, messages: [ {role: system, content: system_prompt}, {role: user, content: user_content} ], temperature: 0, response_format: {type: json_object} } req urllib.request.Request( https://api.openai.com/v1/chat/completions, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, Authorization: fBearer {api_key} } ) with urllib.request.urlopen(req, timeout120) as resp: body json.loads(resp.read().decode(utf-8)) return body[choices][0][message][content]有两个参数要特别说明temperature设为 0确保输出确定性response_format强制 JSON 输出省去解析时的麻烦。如果你用的模型服务不支持强制 JSON就在提示词里加一句“只输出 JSON不要任何解释”然后做好容错。3.3 把模型的结论变成硬门禁模型返回的是 JSON 文本要成为门禁必须经过解析和判定。这里说的判定不是简单判断 JSON 里的passed字段——而是要考虑容错。模型偶尔会返回不合法的 JSON比如多了一个逗号、把布尔值写成了字符串。我写过几十个版本的解析函数目前最稳的思路是先试json.loads失败了就用正则提取括号里的内容再试还不行就给一个“整体结论超时/解析失败需人工确认”的默认值。这个默认值非常重要。宁可把门禁判为“不通过”也不能因为解析失败就放行。门禁的意义在于“默认拒绝通过需要有明确依据”。解析逻辑整理成一个独立的 Python 脚本会比较清晰。我通常把它放在.github/scripts/ai_gate.py工作流里直接调用。脚本的职责包括读取环境变量中的 API 密钥。读取 diff 文件做清洗和截断。拼接系统提示词和用户内容。调用模型 API。解析 JSON生成机器可读的 exit code 和人类可读的评论文件。关于 exit codeGitHub Actions 判断一个 step 成功还是失败靠的就是进程退出码。所以脚本最后要sys.exit(0)或sys.exit(1)。但这里有个细节如果你让脚本直接以失败退出整个 workflow 会显示为红色失败这对“门禁”是符合预期的但对“评论还是要发出来”造成了冲突。因为 Actions 的默认行为是前面的 step 失败后面的 step 不执行。解决办法有两种。一种是把调用脚本的 step 加上continue-on-error: true然后在后面的 step 里读脚本产出的结果文件来决定是否要让 workflow 最终失败。另一种是脚本自身不退出失败而是把passed结果写入文件工作流最后用一个单独的 step 去判断。我推荐后者因为逻辑更清晰- name: Check gate result if: always() run: | result$(cat /tmp/gate_result.json) passed$(echo $result | python3 -c import sys,json; print(json.load(sys.stdin)[passed])) if [ $passed ! true ]; then echo AI gate blocked this PR. exit 1 fi这样设计的好处是评论总能发出去而门禁的状态是“最终由最后一个 check 决定”。分支保护要求的是一个叫ai-review的 job 或某个自定义的状态检查实际上你可以在一个 job 里做完整件事确保只有真正通过才退出 0。4. 我在落地过程中总结的踩坑清单这部分的每一条都是我实际跑过之后才理解的。写出来希望你少走弯路。4.1 密钥和权限问题最常见的问题是 API 密钥泄露。不少人为了本地调试方便先把 key 写在脚本里推上去之后才想起来已经晚了。一定要从第一天就养成用 GitHub Secrets 的习惯。还有一点很多团队会忽略如果这个仓库 fork 了fork 仓库里的 workflow 不会继承原仓库的 secrets外部的 PR 会自动跳过需要密钥的 step。这其实是 GitHub 的安全机制防的是恶意 fork 窃取密钥。我在某个跨团队协作时遇到过外部贡献者的 PR 一直显示“一步未执行”排查半天发现就是 secrets 不继承。这种情况没法在技术上绕过合理的替代方案是外部 PR 打上ok-to-testlabel 才运行带密钥的 job。权限最小化也很重要。工作流里permissions只声明contents: read和pull-requests: write不要多给。有些教程会让你直接用GITHUB_TOKEN默认的全部权限这等于把仓库写权限交给一个只该审查代码的脚本。4.2 解析失败与超时模型接口有概率返回非 JSON 内容。即便我设置了response_format仍然遇到过一次返回空字符串的情况。排查下来发现是请求超时被网关拦截模型服务端没有返回完整响应。解决的思路是调用时设置 120 秒超时并在脚本里做三次重试每次重试之间退避 5 秒。重试要设上限否则 Actions 的耗时上限一轮下来就爆了。还有一类解析失败跟模型输出本身无关而是 diff 文件编码问题。Windows 环境下改动的文件带 CRLF 行尾模型返回的内容里可能出现\r。解析 JSON 之前先content.replace(\r, )这种问题就消失了。4.3 误报、漏报与团队信任问题门禁上线后团队里第一个反对声往往是“AI 误报了”。我见过最典型的一次一个测试文件里写了password 123456规则 1 直接判了不通过。但实际上这是一个单元测试的固定测试数据没有真实安全风险。所以后我在规则里加了一条豁免声明凡是测试文件里的 mock 数据不在规则 1 的拦截范围内。豁免机制的实现要谨慎。虽然可以在提示词里写“忽略测试文件中的假密钥”但模型会过度豁免把真正的硬编码测试密钥也放行。我最终采用的是规则描述里区分“生产代码硬编码”和“测试代码硬编码”测试代码里的硬编码只给 warning不给 failed。这个思路的代价是需要额外的判断逻辑但对团队接受度很关键。门禁的“失败”出口必须留人工干预通道。比如 PR 作者可以在评论里 维护者说明“这个是测试数据人工确认可通过”。GitHub 的 review 机制天然支持这个流程AI 门禁只是其中一个 required check维护者的“Approve review”也作为另一个 required check。两者都通过才能合并。这样既保证了 AI 的拦截能力又留了最终的人工裁决权。4.4 超大 PR 与工作流并发问题一个大 PR 能把 diff 撑爆这种情况不能让脚本去硬扛。在脚本开头做一个diff_size判断超过阈值直接写一份“此 PR 因过大致无法自动审查已转人工”的结果文件exit 1。如果你希望 AI 至少还是给点意见可以对 diff 做采样每个文件最多取前 200 行改动文件数量超过 20 个时只取影响最大的 10 个。这是一种妥协但至少保证门禁不中断。并发问题发生在多个 PR 同时触发工作流时。好在 GitHub Actions 每个 job 都是独立容器互相不干扰但要注意对GITHUB_OUTPUT的写入如果同一个 job 里多个 step 都往GITHUB_OUTPUT写同名变量后写的会覆盖先写的。我出现过一脚本把结果文件路径写成相对路径、后续 step 因为当前工作目录不同找不到文件的情况。经验是所有中间文件一律用绝对路径写入/tmp/避免目录上下文切换带来的麻烦。5. 门禁之外我建议你接着做的事一个能跑通的 AI 门禁只是起点。真正发挥价值的是在这个基础上把数据沉淀下来让门禁越用越准。5.1 自动汇总周报工作流跑完把结果往某个 JSON 文件里攒每周生成一份审查报告哪些规则命中最多、哪些文件最容易出问题、每个 PR 的平均耗时。团队聊代码质量时这些数据比感觉靠谱得多。实现上不复杂给脚本加一个写记录文件的逻辑再用一个定时工作流汇总即可。5.2 从门禁到自动修复AI 能发现问题就能尝试改。比如规则 5“新增公共函数必须有测试”模型可以基于函数签名自动生成测试模板作为评论添加到 PR 中由作者确认后使用。这个功能不要做成自动提交因为自动生成的代码质量波动大但作为“建议内容”发给作者体验提升非常明显。5.3 多仓库复用如果团队有几十个仓库不可能每个仓库都复制一份同样的工作流和脚本。把 Python 脚本做成内部共享的模板仓库用actions/checkout在步骤里引用模板仓库的路径再通过环境变量传入每个仓库的差异化配置。全局改一条规则所有接入仓库自动生效这是规模化落地时的必然选择。6. 最后分享一个我每次接入都会做的小验证如果你按上面的流程走完门禁已经能跑但我还是建议你专门花十分钟做一次“对抗测试”创建一个故意包含硬编码密钥和空函数的分支发一个 PR确认 AI 门禁把它拦下来、评论里指出问题位置然后再修正、推一个正常提交确认门禁放行。这个闭环验证的意义在于它同时验证了提示词、解析逻辑、退出码、分支保护四个环节是否串联正确。我刚做这个项目的时候最大的认知转变是门禁的重点不是 AI 审得多好多深而是它创造了一个确定性——代码在到达人工之前已经过了一遍自动化规则的过滤。一个 PR 进来团队所有人第一时间看到 AI 结论那些琐碎的、重复的、一眼就能看出的问题不再消耗人的精力。人该做的是去做机器做不了的设计判断。这套机制用起来之后我最大的感受是审查效率提升是副产品真正的收获是团队在代码质量上的讨论更聚焦了。
