代码评审这件事做得好了是质量防线做得不好就是项目进度的黑洞。我维护的几个仓库最近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 评审触发链路与状态流转我把一次完整的评审过程用文字描述一遍你感受一下整条链路。开发者推送一个分支并发起PRGitHub检测到这个事件后向Hermes配置的Webhook URL发送一个pull_request事件action是opened。Hermes收到请求后先验签确认请求合法。然后检查这个PR当前的状态如果是draft或者被标记为[skip review]直接忽略。接下来通过GitHub API拉取这个PR变更的文件列表和diff内容根据文件数量和行数决定是否需要截断。把diff连同评审规则一起组装成提示词发给大模型。大模型返回结构化的评审结果Hermes解析后调用评论API把摘要写到PR的Review区域把具体问题标注到对应的代码行上。最后更新check run状态整个流程结束。开发者后续再推新的commitGitHub会再次触发Webhookaction变成synchronizeHermes拿到新的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 requestsRead and write读取PR信息、创建Review评论ChecksRead and write登记check run让结果出现在PR合并检查区ContentsRead only需要拉取仓库文件内容时使用IssuesRead 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. 性能风险死循环、明显的高复杂度算法、不必要的大对象复制、N1查询 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 DeliveriesWebhook返回401/403Secret不一致或App未安装核对Secret、检查安装范围Webhook返回200但无评论PR为draft、被过滤、权限不足查看服务日志、检查App权限评论出现但行号错位模型输出的行号与diff不匹配检查降级逻辑、更新commit_id5.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限流并发评审任务过多令牌队列加并发控制分支已删除导致404PR合并后分支被清理拉取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状态的时候扫一眼就知道哪些要优先处理不用在每份报告里翻半天找重点。