代码评审这件事，做得好了是质量防线，做得不好就是项目进度的黑洞。我维护的几个仓库最近PR积压严重，小改动还好，遇到一次动十几个文件的PR，人工review一轮下来半小时打底，反复打回再来几轮，一个功能能拖两三天。后来我把Hermes这套智能体接进了GitHub PR流程，做成了自动化代码评审，效果比我预期好不少。这篇文章就把整个方案的架构设计、部署细节和踩过的坑完整写出来，给同样被PR评审折磨的人做个参考。适合正在做研发效能建设、想引入AI辅助Code Review的团队，也适合一个人维护多个仓库、没太多精力盯每次提交的独立开发者。
1. 为什么需要一套自动化PR评审服务
1.1 人工评审的三大痛点
先别急着谈方案，我把问题先摆清楚。我在团队里观察到的第一个痛点就是等待成本。PR发出去之后，reviewer什么时候看完全看运气。手头有别的任务、正在开会、或者单纯忘了，这个PR就一直卡在那里。对开发者来说，等待review的这段时间实际上是被阻塞的，你不敢继续往下写，怕方向偏了白做，整个人的节奏全被打乱。
第二个痛点是评审标准不一致。团队里每个成员的代码风格、技术背景、在意的东西都不同。有的人死抠命名，有的人只看逻辑正确性，还有的人只关心有没有测过。同一个PR换不同的人review，反馈质量天差地别。时间长了大家就会有一种感觉：review就是碰运气，遇到严格的就多改几轮，遇到宽松的就蒙混过关。
第三个痛点是低级错误浪费了大量评审精力。我统计过那些被反复打回的PR，相当一部分问题根本不是高深的架构问题，而是明显的空指针隐患、密钥硬编码、错误处理缺失、API调用参数写反这类基础问题。这些问题交给大模型来看，几乎不会漏，但人眼扫过去很容易被大段代码淹没。真正需要人工判断的设计取舍、业务逻辑、长期演进方向，反而因为评审者把精力都耗在低级问题上而被忽视了。
1.2 传统静态检查工具的局限
有人可能会说，你说的这些问题，ESLint、SonarQube这些东西不是已经能查了吗？确实能查，但查的东西非常有限。传统静态检查工具的核心能力是规则匹配，它只能发现你预先定义好的模式，比如不允许使用var、不允许出现console.log、禁止硬编码密钥。超过这个范围的语义问题它完全无能为力。
我给你举个例子。有一次某个PR里把两个方法的调用顺序换了一下，单看每一行代码都是合法的，参数类型也对，但换完之后原来的幂等性就没了，在高并发下会出重复数据。这种问题传统工具根本不会报，因为它不理解"这两个方法调用之间存在隐含的顺序依赖"。但大模型能看出来，因为它读的是上下文语义，不是逐行匹配规则。这就是我决定引入AI做评审的最直接原因。
1.3 Hermes在这套体系里到底扮演什么角色
可能需要先解释一下Hermes是什么。它是一个可以自托管的智能体框架，核心能力是接收外部事件、调用大模型进行推理分析、再通过工具执行具体动作。在这套PR评审方案里，Hermes承担的是"连接器"和"调度中枢"的角色。GitHub把PR相关事件推给它，它负责拉取变更内容、组织上下文、调用大模型分析、然后把结果以评论的形式写回PR。
你可能会问，直接用脚本调大模型的API不就行了？思路差不多，但用脚本有个很麻烦的问题：所有流程都要你自己写，包括事件接收、签名校验、任务去重、API限流处理、评论格式组装、错误重试。这些逻辑看似简单，真写起来全是非常琐碎的活。Hermes这种Agent框架把这些基础设施都封装好了，我只用关心核心的评审逻辑和提示词配置，上手成本低很多。
2. 整体设计：把Hermes嵌进GitHub PR流程
2.1 系统模块划分
整个系统我拆成了四层，每一层职责都很单一，出了问题也好定位。
第一层是事件接收层，负责接收GitHub发来的Webhook请求。GitHub上任何与PR相关的事件，比如新建PR、提交新commit、PR从草稿转为可评审状态，都会以HTTP请求的形式推送到Hermes服务上。这一层要做的事情是签名校验，确认请求确实来自GitHub，然后根据事件类型决定要不要继续往下走。
第二层是任务调度层，负责去重、排优先级和任务分发。同一个PR可能同时触发多个事件，比如开发者提交完commit之后马上又改了标题，这时候如果不做去重，机器人就会重复评论。调度层的核心逻辑很简单：缓存每个PR当前最新的commit SHA，只有SHA变化了才触发新的评审任务。
第三层是分析执行层，这是Hermes真正干活的地方。它调用大模型对PR的diff进行代码评审，同时还可以执行一些工具操作，比如拉取某个文件的最新内容、查看仓库目录结构、搜索特定符号的定义。这一步实际上是把大模型的"分析能力"和外部工具的"行动能力"结合在一起，这也是Agent方案比纯脚本方案强的地方。
第四层是结果回写层，负责把评审结果写回GitHub。包括在PR上创建review评论、在具体代码行上打标注、更新check run的状态。这一层直接决定开发者能不能在GUI上看到清晰的反馈，所以我把错误处理做得比较重，宁可失败重试，也不允许评论发到一半就静默丢弃。
2.2 为什么选择GitHub App而不是个人Token
这是我在设计阶段踩过的一个大坑。最开始我想省事，直接在Hermes配置里放一个个人访问Token，用这个Token去调GitHub API。结果发现两个很严重的问题。
第一个问题是权限边界失控。个人Token的权限是跟着账号走的，我为了让机器人能评论PR，给Token开了repo的写权限，这意味着这个Token实际上能改我账号下所有仓库的代码，万一泄露了后果不堪设想。第二个问题是身份识别混乱。用个人Token创建的评论显示的是我自己的名字，团队成员看到评论后经常会跑来问我"这句话是你写的还是机器人写的"，沟通成本非常高。
换成GitHub App之后这两个问题都解决了。App是一个独立于个人账号的机器人身份，它的权限被限制在"安装了这个App的仓库"范围内，而且是细粒度的，比如我只给了它Pull requests: Read and write和Checks: Read and write，它就无法动代码内容。App的凭证是自动轮换的Installation Token，有效期很短，即使被截获，能造成的破坏也极其有限。
2.3 评审触发链路与状态流转
我把一次完整的评审过程用文字描述一遍，你感受一下整条链路。
开发者推送一个分支并发起PR，GitHub检测到这个事件后，向Hermes配置的Webhook URL发送一个pull_request事件，action是opened。Hermes收到请求后先验签，确认请求合法。然后检查这个PR当前的状态，如果是draft或者被标记为[skip review]，直接忽略。接下来通过GitHub API拉取这个PR变更的文件列表和diff内容，根据文件数量和行数决定是否需要截断。把diff连同评审规则一起组装成提示词，发给大模型。大模型返回结构化的评审结果，Hermes解析后调用评论API，把摘要写到PR的Review区域，把具体问题标注到对应的代码行上。最后更新check run状态，整个流程结束。
开发者后续再推新的commit，GitHub会再次触发Webhook，action变成synchronize，Hermes拿到新的commit SHA后发现和缓存的不同，于是再跑一轮新的评审，覆盖之前的评论。这套状态流转设计好之后，整个系统就是一个完整的闭环，人只需要在最后看一眼机器人的评审结果，决定同意还是驳回。
3. 从零搭建：GitHub App、Webhook与服务部署
3.1 创建GitHub App与权限清单
部署的第一步是在GitHub上注册一个App。入口在GitHub右上角头像菜单里的Settings，然后进Developer settings，再选GitHub Apps，点New GitHub App。名字随便起，比如hermes-reviewer，首页URL可以填你的服务地址，Webhook URL填Hermes对外暴露的HTTPS接口地址。
权限配置是整个过程中最需要仔细核对的部分。我给Hermes开的是这么一组权限：
| 权限项 | 访问级别 | 用途说明 |
|---|---|---|
| Pull requests | Read and write | 读取PR信息、创建Review评论 |
| Checks | Read and write | 登记check run，让结果出现在PR合并检查区 |
| Contents | Read only | 需要拉取仓库文件内容时使用 |
| Issues | Read and write | 用于给PR打标签，方便按状态筛选 |
Webhook事件我只勾选了Pull requests这一项，避免不必要的请求轰炸。
创建完成之后，GitHub会生成一个App ID和一个私钥文件。私钥是PEM格式的，下载后要放在一个安全的位置，这个文件就是机器人身份的凭证，泄露了等于把整个仓库的评论权限交出去了。App生成之后还需要安装到自己账号下的目标仓库，安装时可以选择"This account only"或者"Only select repositories"，我建议选后者，只把需要自动评审的仓库加进去。
3.2 部署Hermes服务与基础配置
Hermes的安装部署我建议直接用Docker，省得被宿主机的Python环境折腾。我的Docker Compose配置大概长这样：
version: "3.8" services: hermes: image: hermes-agent:latest container_name: hermes-reviewer restart: unless-stopped ports: - "8080:8080" environment: HERMES_GITHUB_APP_ID: "123456" HERMES_GITHUB_PRIVATE_KEY_PATH: "/run/secrets/hermes_private_key.pem" HERMES_GITHUB_WEBHOOK_SECRET: "${WEBHOOK_SECRET}" HERMES_MODEL_ENDPOINT: "${MODEL_ENDPOINT}" HERMES_MODEL_API_KEY: "${MODEL_API_KEY}" HERMES_MODEL_NAME: "hermes-review-model" volumes: - type: bind source: /etc/hermes/secrets/hermes_private_key.pem target: /run/secrets/hermes_private_key.pem read_only: true几个关键配置项我多说两句。WEBHOOK_SECRET是GitHub在创建App时让你填的一个随机字符串，用来做Webhook请求签名校验，上下两边的值必须完全一致，否则Hermes验签失败会直接丢弃事件。MODEL_ENDPOINT和MODEL_API_KEY是给Hermes调用大模型用的，Hermes本身不内置模型，它更像一个调度器，把代码评审的任务交给模型去做。这里你可以接任意支持OpenAI兼容协议的模型服务，按自己团队的预算和合规要求来选，没有强制绑定。
部署完成后，Hermes会在8080端口提供Webhook接收接口。生产环境我建议在前面挂一层反向代理，强制HTTPS，因为GitHub在Webhook配置里只接受HTTPS地址，纯HTTP是过不去的。
3.3 验证链路：如何确认整条管线已经打通
服务部署完、App也装好了，怎么确认整条链路是通的？我最常用的验证方式是利用GitHub App设置页面里的Recent Deliveries功能。
在GitHub App的高级设置页面，GitHub会记录最近一段时间内发给你的所有Webhook请求，每条请求都能看到完整的Payload、响应状态码和响应体。我先在本地往目标仓库提一个测试PR，然后去Recent Deliveries里看最新一条记录。如果状态码是200，说明Hermes接收成功；如果返回4xx，大概率是签名校验失败或者请求体解析出错；如果是5xx，那就是Hermes内部处理逻辑有问题。
这个功能也是日常排障的第一入口，我后面在问题排查章节会再提到。整个验证过程不需要写一行代码，GitHub把这些调试信息都给你准备好了，关键是你得知道去哪看。
3.4 上线前必做的安全检查
我把一套系统接入到代码仓库的日常流程里，安全上不敢马虎。有几个点是我上线前反复确认过的。
第一，Webhook签名校验必须开启。GitHub在发Webhook请求时，会用你配置的Secret对请求体做HMAC-SHA256签名，放在X-Hub-Signature-256头里。Hermes如果收到请求但验签不通过，必须直接拒绝，不能有任何例外。防止有人伪造请求触发无意义的评审。
第二，私钥文件权限要收紧。我放在宿主机上的PEM私钥文件权限设成了600，只允许root用户读取。Docker挂载时用的是read_only模式。一个很小的细节，但真的出事时这就是最后一道防线。
第三，对评审对象做白名单限制。Hermes配置里有一个ALLOWED_REPOS列表，只处理我在列表里明确指定的仓库，其他仓库发来的事件一律忽略。防止有人把App不小心安装到其他位置后自动开始工作，产生意料之外的行为。
4. 核心环节：审查规则配置与提示词设计
4.1 评审维度的取舍
部署起来只是第一步，真正决定这套系统有没有用的是评审质量，而评审质量几乎完全取决于提示词设计。我第一版上线时直接把需求写成"请帮我review这个PR"，结果模型输出的评论全是废话，什么"代码写得很清晰""建议补充测试"这种空洞的套话，没有实际价值。后来我花了很多功夫把评审维度细化，效果才慢慢上来。
我最终使用的评审维度有六个：逻辑正确性、安全性、性能风险、接口兼容性、可维护性、测试质量。每个维度在提示词里都有明确的检查重点，模型不会跑偏。比如逻辑正确性，我要求它重点看空指针、数组越界、边界条件遗漏、并发状态更新冲突；安全性重点看硬编码密钥、注入风险、缺失的权限校验；接口兼容性重点看API参数变更是否会影响调用方。维度不是越多越好，太细了模型反而抓不住重点，六个维度覆盖大部分场景是够用的。
4.2 可以直接抄走的提示词框架
下面是我经过多轮迭代后稳定下来的提示词框架，你可以直接参考。最外层是System Prompt，定义角色和评审规则；然后把PR的diff和必要的上下文作为用户消息传入。
你是一名资深代码评审专家，负责对GitHub Pull Request进行严格评审。 请按以下优先级检查代码： 1. 逻辑正确性：空指针、数组越界、边界条件、并发状态更新、异常路径 2. 安全性：硬编码密钥、注入风险、缺失的权限校验、敏感数据泄露 3. 性能风险：死循环、明显的高复杂度算法、不必要的大对象复制、N+1查询 4. 接口兼容性：公开API参数变更是否影响调用方、是否存在破坏性变更 5. 可维护性：命名是否准确、函数是否过长、是否存在明显重复代码 6. 测试质量：关键分支是否缺少测试、测试断言是否有效 输出格式要求： - 所有问题按严重级别分为 critical / warning / suggestion 三档 - critical：会导致bug、安全漏洞或数据错误的问题，必须修改 - warning：可能导致问题或明显不符合工程规范，建议修改 - suggestion：风格或优化类建议，仅供参考 - 每条问题必须包含：文件路径、行号、问题描述、具体修改建议 - 修改建议必须是可直接执行的操作，不得使用"建议优化""注意一下"这类模糊表述 - 如果某个维度没有问题，不要输出内容 - 禁止输出"代码整体质量不错"这类无价值的夸赞这套提示词看起来简单，但每个字都是我调出来的。比如"修改建议必须是可直接执行的操作"这一条，直接过滤掉了大量套话评论。模型原来会写"建议优化该函数的时间复杂度"，现在它会明确指出"第37行循环嵌套导致O(n2)复杂度，建议先对列表按id建索引，将内层循环改为O(1)查找"。
4.3 大PR的上下文截断策略
大PR是自动化评审最头疼的场景。我遇到过一次PR改了四十多个文件、diff总量超过三千行，直接全部塞给大模型，结果响应时间特别长，而且模型因为上下文太长，对早期文件的注意力已经衰退了，评审质量明显下降。
最后采用的策略是分层截断。首先设一个文件数上限，默认只评审前30个文件，超出时按文件类型和变更行数排序，优先评审核心代码文件，跳过锁文件、生成的代码、配置文件。其次对单个文件的diff做行数限制，超过500行的diff按变更的代码块截取，只保留新增行和附近20行以内的上下文。截断策略牺牲了一部分覆盖率，但换来了更稳定的质量和响应速度，对绝大多数PR来说是划算的。
另一个我试过效果不错的策略是先让模型看文件列表，让它自己挑选最值得深入审查的文件，然后只对选中的文件做详细评审。这个方案在PR动了几十个文件时尤其好用，相当于让模型做了两轮判断：先粗筛，再精评。
4.4 输出格式与评论落点控制
模型输出的评审结果要落到PR上，需要处理一个关键问题：如何把"问题描述"精确地关联到"代码行"。GitHub的Review API支持行级评论，但要求你传入具体的行号、文件路径和对应的side参数。我在提示词里要求模型输出必须带文件路径和行号，然后在代码层面做一层校验：如果模型输出的行号在diff中不存在，就退化成PR级别的普通评论，不强行做行级定位。
这样设计是为了避免评论落到错误的位置。有一次模型指出了一个问题，给出的行号对着的是完全无关的一行代码，如果直接提交，开发者根本找不到位置。加上校验逻辑之后，定位失败的问题会自动降级为汇总评论，至少不会误导人。调用GitHub API创建行级评论的接口大概是这样的：
POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews Content-Type: application/json { "commit_id": "最新commit的SHA", "event": "COMMENT", "body": "评审摘要，包含问题总数和关键结论", "comments": [ { "path": "src/users/service.py", "line": 42, "side": "RIGHT", "body": "[critical] 这里未对空值做判断，当user对象为NULL时会直接触发空指针异常。建议增加防御性判断，或改用安全取值方式。" } ] }注意commit_id一定要传最新commit的SHA，否则GitHub会把评论挂在历史commit上，开发者看到评论后点了"已解决"，但代码里根本找不到对应位置。
5. 常见问题与排查技巧实录
5.1 评论迟迟不出现，问题出在哪一环
搭好系统之后遇到的第一类问题就是：PR提了，Hermes服务也显示收到了请求，但PR页面上就是看不到评论。排查链路我用的是排除法。
先去GitHub App的Recent Deliveries里看Webhook请求是否到达、响应码是什么。如果请求压根没到，检查Webhook URL是否公网可达、有没有被防火墙挡掉。如果请求到了但返回4xx，检查是不是签名校验失败或者JSON解析出错。如果返回200但PR上没评论，那就是Hermes内部逻辑有问题，需要看服务日志。我遇到过的具体原因有两个，一个是PR处于draft状态被我自己的过滤逻辑拦掉了，另一个是权限配置里忘了开Pull requests: Read and write，导致Hermes虽然有感知但没有权限写评论。
给个排查速查表，按顺序看一遍基本都能解决：
| 现象 | 可能原因 | 排查方式 |
|---|---|---|
| Webhook记录不存在 | URL不可达或GitHub侧配置错误 | 检查Recent Deliveries |
| Webhook返回401/403 | Secret不一致或App未安装 | 核对Secret、检查安装范围 |
| Webhook返回200但无评论 | PR为draft、被过滤、权限不足 | 查看服务日志、检查App权限 |
| 评论出现但行号错位 | 模型输出的行号与diff不匹配 | 检查降级逻辑、更新commit_id |
5.2 同一份PR被反复评论，幂等怎么做
这个问题刚上线的头几天就撞上了。开发者在PR里提交了新的commit，本来应该只触发一次pull_request.synchronize事件，结果我收到两三条重复的评审评论。查了一圈发现原因是多重的：GitHub的Webhook本身有重试机制，第一次请求超时后会重新推送；我自己的服务在处理过程中有一小段耗时操作，处理完之前GitHub又推送了同一条事件；再加上我自己手动点击了Redeliver测试。三重因素叠加，就造成了重复评论。
解决办法是在任务调度层做幂等控制。我在内存里维护一个map[prId -> lastReviewedSha]，每次收到评审需求时，先查当前PR的最新commit SHA和缓存里的值是不是相同，相同就直接跳过。评论发出去之后立刻更新缓存，防止同一个事件被再次处理。另外每条评论的body里我都带上了commit SHA的标识，万一真有重复，开发者一眼就能识别。
5.3 大模型"幻觉"评论的处理办法
这是所有AI评审系统都绕不开的痛点。有一次Hermes给一个Java项目提了个critical级别的评论，一本正经地说"第103行存在SQL注入风险，用户输入未经过滤直接拼接到查询语句"，但我打开源码一看，那行用的是PreparedStatement参数化查询，根本不存在注入问题。这种"幻觉"如果直接推给开发者，会严重消耗信任，几次之后大家就不看机器人的评论了。
我的应对策略是引入证据校验机制。在提示词里增加一条硬性规则：critical级别的问题必须在代码中引用具体的证据，包括变量如何从输入源头流转到危险调用点的完整链路。然后在后处理阶段再加一道复核：对于模型标记为critical的问题，把相关的代码片段和问题描述再发给模型，让它重新确认是不是误报，只有二次确认通过的问题才会真正发布为critical评论。这个机制上线之后，明显误报率降下来很多，虽然增加了模型调用次数，但换来的是开发者对评审结果的信任，这笔交易很划算。
5.4 GitHub API限流与并发冲突
GitHub API有速率限制，虽然GitHub App的Installation Token限额比个人Token宽松，但评审多个PR时仍然可能撞上。我遇到过一次批量打开多个PR的场景，几个评审任务并发执行，瞬间把API配额打爆了，紧接着所有评论都发不出去，服务日志里全是rate limit exceeded。
处理办法有两层。第一层是令牌管理：用一个队列统一管理API调用，每个请求发出之前先检查当前配额剩余量，不够就排队等待，避免一窝蜂地请求。第二层是任务并发控制：默认只允许两个评审任务同时执行，其他任务排队等候。这两个限制加上之后，API限流的问题基本没有再出现过。
5.5 现场排查速查表
最后整理一份完整的排查速查表，给后面维护这套系统的同学一个参考：
| 问题 | 直接原因 | 处理手段 |
|---|---|---|
| 评论缺失 | Webhook到达但PR状态为draft | 确认PR状态，改为ready后自动触发 |
| 评论重复 | 事件重试或调度层未做幂等 | 按commit SHA做去重 |
| 行号错位 | 模型输出行号不存在 | 做行号校验，失败时降级为普通评论 |
| 大PR超时 | 上下文过长导致模型响应慢 | 开启文件数限制和diff截断 |
| 误报critical | 模型产生幻觉 | 引入证据要求与二次复核 |
| API限流 | 并发评审任务过多 | 令牌队列加并发控制 |
| 分支已删除导致404 | PR合并后分支被清理 | 拉取diff前先检查PR状态，失败时跳过评审 |
6. 自动化评审的边界与下一步优化方向
6.1 自动化评审不能替代什么
这套系统上线之后，我必须诚实地讲，它替代的只是"第一道防线"的角色。凡是涉及业务语义判断、方案权衡、长期架构演进这类问题，模型现在仍然做不好。比如一个PR里把缓存策略从"每次读取都查DB"改成"先查本地缓存，miss了再查DB"，模型能指出缓存一致性和失效策略的风险，但没法判断在这个业务场景下允许最多多久的数据延迟，这种取舍需要人来做。
我目前在流程里是这样定位的：Hermes先跑一遍，把明显的bug、安全隐患、规范问题全部筛掉，把标注为critical的问题优先暴露在PR页面上。然后我作为维护者只需要把注意力集中在真正需要判断的问题上，比如设计取舍、接口方案、优先级排序。团队反馈下来，PR首轮评审的时间缩短了不少，但我省下来的精力并没有被"吞掉"，而是被重新分配到了更值得关注的事情上。
6.2 后续值得扩展的方向
这套体系跑起来之后，我觉得有几个方向是明显值得继续投入的。
第一个方向是接入CI流水线，把Hermes的评审结果做进required checks。现在的流程是Hermes评完发评论，但PR仍然可以绕过评论直接合并。如果能把评审结果做成一个check，让包含critical级别问题的PR强制不能合并，Authority就完全不一样了，等于把自动化评审从"建议环节"升级成"准入门槛"。
第二个方向是把评审规范配置化。不同团队对代码风格和规范的要求完全不同，现在这些规则硬编码在提示词里，改起来要重新部署。我计划把规范抽成独立的配置文件，让每个团队可以按需维护自己的规则集，Hermes启动时加载这些配置，再拼接到提示词里。这样规则的维护和调整就不需要动系统代码了。
第三个方向是把评审范围从PR扩展到issue和设计文档。理论上Hermes这类Agent的能力边界不在代码评审工具，而在于"理解上下文并采取行动"。给它一段设计文档，它能检查文档里的技术方案有没有明显漏洞；给它一个issue描述，它能判断这个需求有没有歧义、状态定义是否清晰。这些都是已经验证过的应用场景，扩展开来并不难。
这套自动化评审方案在我实际维护的项目里已经稳定运行一段时间了，最大的感受是它不改变我的评审结论，但极大地压缩了我在机械性问题上的投入时间。最后分享一个小技巧：把Hermes评论的文案风格调得更直接一点，让它第一句话就是结论，比如"发现1个critical问题和3个warning问题"，然后再展开细节。这样每天批量查看PR状态的时候，扫一眼就知道哪些要优先处理，不用在每份报告里翻半天找重点。
