自动化代码评审实战：用Hermes Agent打造PR智能审查助手

这周我们组又积压了一批待review的PR最长的一挂在队列里已经超过三天。倒不是大家不负责而是每次打开GitHub的Pull Request页面面对大几百行的diff加上上下文缺失和无休止的风格讨论评审这件事越来越像被迫加班。后来我尝试把Hermes接进仓库当自动代码评审助手把PR从等人看变成了机器先看、人再看重点效果远比预期好。这篇就把完整的接入过程和踩坑记录整理出来给同样被PR压得喘不过气的朋友一个参考。如果你也正在做代码评审或者团队里正为PR无人及时反馈头疼这篇内容应该能直接帮到你。Hermes在我这里跑的是智能体Agent模式核心职责就是监听GitHub的PR事件拉取diff和变更上下文结合团队规范与安全规则做自动审查再把结论以评论和Check Run的形式写回PR。1. 代码评审的隐性成本和PR积压的真相先讲点大实话。大多数团队的代码评审都没那么高大上它真正的成本不在于看代码本身而在于上下文切换、等待反馈和反复澄清。一个后端改动通常涉及接口定义、数据表变更、调用方适配单纯看diff根本看不出设计意图。评审人要自己翻issue、找关联PR、查历史提交这一套下来没有10分钟进不了状态。更麻烦的是大家各自有开发任务刚进入一个大型feature的上下文就被拉去review别人的代码等回到自己的任务又要重新花10分钟找状态。这种来回切换的损耗比实际review时间还高。我在上个月做了一次统计把团队近60个PR的评审数据拉出来看结论还挺明显指标平均值中位数首个评论延迟从PR创建到第一条评审意见7.6小时4.2小时PR从创建到合并总耗时28.4小时19.8小时包含阻塞性问题的PR占比22%—被LGTM直接合并的PR占比31%—31%的PR只有一个LGTM就合并了意味着接近三分之一的变更基本是碰运气。没有留下任何有实质意义的评审意见也没有人认真检查过边界条件和安全性。这不是说团队不负责而是人的注意力本身就不适合这种随时被叫停、看两眼、作出判断的场景。真正让我决定接入自动化评审的转折点是有一次合并后发现一个严重的鉴权绕过问题。那个PR在review时只拿到了LGTM但漏洞就藏在某个看似无害的权限判断重写里。仔细翻代码才发现改动是把require_role换成了has_permission两个函数名看着相似语义完全不同。人眼很容易漏掉这种细节但代码评审工具如果配置得当是可以按照规则稳稳抓住的。所以自动化代码评审的价值不在于替代人而在于先把机器能稳定处理的部分接住让人把注意力集中在真正需要判断力的设计问题上。2. 为什么是Hermes而不是再加一个Bot插件市面上PR审查工具不少有直接托管在GitHub Marketplace上的应用也有各种静态检查插件。我一开始也想过直接用现成的但真正试用下来发现一个共性问题它们大多是规则匹配器不是评审Agent。传统Bot能做的通常是这几类事情检查有没有TODO注释、格式化是不是符合Prettier、是不是缺少测试文件、是不是有合并冲突。这类检查有价值但它们停留在语法表面抓不住语义问题。比如前面提到的鉴权绕过传统Bot根本发现不了。而Hermes在我这边的定位是一个Agent框架它能根据一个目标动态规划步骤先看PR的title和description再读diff然后主动去查文件的历史提交和关联issue最后基于这些上下文给出评审意见。整个链路不是一条规则命中一条意见而是理解任务—收集信息—作出判断—输出结果。放一张对比表可能更直观一些能力维度传统Lint型BotHermes Agent模式检查格式/缩进/命名强可以但不是重点发现逻辑风险基本不行能结合上下文分析理解业务语义不能可以配置知识库和规则与团队规范对齐靠人工维护正则和脚本用自然语言描述即可审查报告可读性零散列表按严重级别汇总是否会产生误报低但确定需要调优但更接近人有一点必须说清楚Hermes不是一个开箱即用的PR审查产品。它更像乐高底座审查这个能力是需要你自己拼的。但恰恰是这个自己拼的过程让最终产出的审查逻辑能真正匹配自己团队的需求。通用的Bot给你一套固定规则你用起来觉得别扭但改不了Hermes则把规则定制权完整交给你代价是你要花一点时间搭建和调试。另外Hermes这种Agent模式还有个好处就是它可以自己调用工具。比如它发现一个改动涉及数据库字段变更会主动去翻schema定义文件确认兼容性看到一个函数被调用了多次会去全局搜索调用点评估改动的波及范围。这些动作在传统Bot里都需要人工逐条配置规则而Agent可以现场决策、动态执行。对我这种既要写业务又要管仓库的人来说省下的不只是时间还有来回切上下文的精力。3. 搭一套Hermes PR审查机器人从安装到跑通第一单先强调整个部署没有想象中那么复杂但也不是敲两行命令就完事。核心由三部分组成仓库侧的事件推送、Hermes侧的Agent执行、以及GitHub侧的评论回写。3.1 准备环境和GitHub访问凭证我的服务器环境是LinuxPython版本需要3.10及以上。Hermes相关的包通过pip安装一些依赖项即可这部分不会太折腾。真实踩过坑的是GitHub凭证你需要一个权限边界清晰的Token别图省事直接给一个拥有整个组织权限的Token。我给审查Agent单独建了一个GitHub App而不是用个人Token。原因很简单权限可以精确到单仓库级别只给contents: read和issues: write、pull_requests: write这些必要权限。App的Token有小时级过期机制即使出现问题影响面也很小。后续可以在组织级别统一管理不用绑定某一个人的账号。如果你只是在自己个人仓库实验用personal access token也完全可以但记得勾选最小权限。我建议最好还是直接上GitHub App省得后面扩展时又要返工。3.2 配置Webhook让PR事件主动找上门GitHub侧有两种常见接入方式Webhook和直接拉取。Webhook是事件驱动PR创建、更新、评论时GitHub会往你的服务器推送一个JSON请求拉取则是定时轮询每隔几分钟查一次有没有新PR。两种方式我都跑过最终选了Webhook为主。原因是PR审查对时效性有要求Webhook基本能做到秒级触发。但Webhook有个问题事件一多服务器处理不过来时容易超时。GitHub对Webhook的响应时间限制是10秒如果你的Agent执行一次要跑30秒甚至更久就必须把接收事件和执行审查拆开。我的做法是Webhook只负责收事件、确认事件格式正确然后立刻往Redis里塞一个任务返回200给GitHub。真正执行审查的是后台的Worker进程它从Redis取任务、跑Agent、再通过GitHub API把结果写回PR。这个改动看似多绕了一圈但稳定性和并发能力完全不是一个量级。后面踩坑部分我再展开讲。3.3 初始化Hermes并注册PR审查Skill这里以我实际运行的Hermes Agent模式为例。初始化时核心是配置两类东西模型接入和工具注册。模型我接的是DeepSeek的API因为我这边对成本比较敏感实测它在代码理解上的表现与更贵的模型差距已经完全可接受。如果你不介意成本接更强的模型效果会更好。关键是Hermes本身对模型做了抽象切换模型基本就是改一下配置。工具方面我给Agent注册了三个必要工具get_diff_data从PR里拉取文件的diff内容。get_related_file读取指定文件的完整内容很多问题只看diff看不出来要看整个函数或整个文件。post_review_comment往PR提交评论或审查意见。注册完工具还要写一个Skill。Skill有点像给Agent准备的一份岗位说明书告诉它遇到PR事件时该按什么步骤走、关注什么、输出什么格式。我那个最小可用的Skill逻辑大概长这样async def review_skill(context): pr_info await context.get_pr_info() if pr_info.state ! open: return # 1. 先看PR描述理解改动的业务目的 description await context.get_pr_description() scope await context.extract_scope(description) # 2. 拉取关键文件的diff changed_files await context.get_changed_files() diff_data await context.get_diff_data(changed_files) # 3. 按规则做静态风险识别 findings await context.analyze(diff_data, rulesREVIEW_RULES) # 4. 结合文件上下文排除误报 filtered [] for item in findings: full_context await context.get_related_file(item.file_path) if context.is_real_issue(item, full_context, scope): filtered.append(item) # 5. 写回评论 await context.post_review_summary(filtered)步骤其实不复杂但每一步背后都有讲究。比如先看PR描述再拉diff是为了让Agent在分析代码前先建立预期——这段代码本来想干什么。带着预期去看diff和直接看diff判断质量完全不一样。3.4 跑通第一个真实PR整个框架搭好之后我拿一个真实的feature PR做了测试。那个PR改动了一个支付回调的签名逻辑涉及两个文件删了80行、加了120行。Agent跑完大概花了40秒输出了一份审查报告内容包括一个高优先级问题回调签名里没有校验时间戳存在重放攻击风险。一个中等级别提示删除了旧版本兼容分支但调用方还留在线上可能导致灰度期报错。一条风格建议错误码用的是字符串字面量建议统一改为常量。第一次跑通时我的真实感受是虽然单个问题没有超出资深工程师的认知范围但它把细枝末节的检查全部兜住了。我看着报告只需要把精力放在时间戳校验和灰度兼容性这两个真正的核心问题上不用再逐行扫代码找低级问题。这基本就是我想要的工作方式机器做第一遍全量扫描人做第二遍重点判断。第一单跑通之后后面的事情就是不断调优规则和降噪了。4. 把人话变成规则审查维度设计与降噪很多人在给Agent配置审查规则时会走过一个弯路恨不得把团队所有编码规范都塞进去结果Agent每次PR都列 30 条意见大家反而什么都不看。我的经验是分三类设定高价值检查严格控制噪音。4.1 优先圈定三类高价值检查我按价值密度排了个优先级规则设计全部围绕这三类展开安全风险类鉴权绕过、注入、敏感信息泄露、重放攻击、路径遍历。这类问题一旦漏掉就是事故优先级别最高误报容忍度也最高——宁可错杀不可放过。变更一致性类改了A处调用是否同步改了B处声明删了兼容分支是否还有线上调用方改了接口签名是否更新了所有调用点。这类问题最消耗人工注意力Agent找起来又快又准。可维护性类重复代码、魔法数字、过于复杂的函数、明显违反项目约定的写法。这一类噪音最高我建议初始阶段只保留最明确的几条规则比如新增代码不得引入TODO。规则的具体表达方式我直接写成了Markdown格式的规则文档挂在Hermes的Skill目录下Agent分析时会参考它。规则不需要写成代码逻辑自然语言描述反而效果更好因为Agent能理解语义。4.2 安全检查的具体规则实例安全规则是我投入产出比最高的一部分。我列几条实际在用的- 如果PR涉及权限判断逻辑的变更必须核对调用链上是否还存在旧权限检查点 - 如果PR涉及URL路由或接口参数解析检查是否存在路径拼接和未授权访问风险 - 如果PR涉及用户输入处理检查是否有输入长度限制和内容过滤 - 如果PR新增了敏感数据字段定义检查日志输出中是否可能携带该字段 - 任何对时间戳、签名、密钥的改动都要检查校验逻辑是否完整这些规则如果写成传统正则或AST规则工作量巨大且维护成本高。但交给Agent它理解路径遍历攻击是什么也能从diff里判断是否出现了os.path.join拼接用户参数的写法。4.3 让Agent理解团队规范团队规范这种东西写进Wiki容易真正落实很难。以前靠reviewer肉眼把关现在我把关键规范也喂给了Agent。比如说我们团队约定数据库迁移文件一旦合并就不允许修改只能新增迁移。以前这条规范偶尔会有人违反现在Agent审查PR时会检查新增的迁移文件是否与已合并版本重复如果发现修改了历史迁移文件会自动评论并标记为blocking。再比如我们约定接口返回值统一使用ApiResponse结构。Agent会检查新增的接口方法是否返回了裸对象是否缺少统一包装。这些检查几乎不需要额外调参Agent在看到规则和代码样例后就能准确执行。我差不多用了半天时间把团队规范从Wiki里抽取了十几条最重要的、写成规则文档喂给Hermes。效果立竿见影新版规范违规率肉眼可见地下降了。4.4 阈值与降噪避免机器人刷屏自动审查最怕的是一句话能说清楚的问题被Agent拆成五条评论逐条刷。我调了三个降噪参数评论合并同一个文件里的同类问题合并成一条评论用列表列出所有位置。严重级别门槛默认只把High和Critical级别的意见写为review线程Medium及以下只在汇总评论里列一行。黑名单路径yarn.lock、package-lock.json、自动生成的API文档等文件直接跳过diff分析只提示锁文件已更新。降噪之后Agent每个PR的意见数从平均15条以上降到了3~5条其中90%以上的PR会带至少一条有效建议。这个密度对团队成员来说是舒适的不会烦到直接无视Robot又能真正起到兜底作用。5. 跑起来之后遇到的坑接入过程并不是一路顺利的。我把我踩过的几个有代表性的坑写下来希望你不用再走一遍。5.1 Webhook超时和丢事件第一版实现里我让Webhook直接同步执行Agent审查。结果第一个真实PR就把我打脸了——Agent分析到一半GitHub显示Webhook redelivery失败原因是服务器超时未响应。后续的事件更是因为同步处理阻塞连健康检查都被拖爆了。排查链路其实不复杂先看GitHub Webhook的recent deliveries发现大量Server Error超时。再看服务器日志Agent执行确实超过了10秒。定位结论Webhook不是用来跑长时间任务的地方它只负责接单。修复方案就是前面提到的引入Redis队列Webhook收到事件后立刻入队、立刻返回Worker进程异步处理。改造之后即使Agent执行耗时两分钟GitHub侧的delivery也是成功状态。这个改动让整个系统的可靠性格提升了不止一个量级现在我甚至敢把审查Agent挂到生产仓库的必查流程上。5.2 上下文窗口不够用大PR的diff动辄上千行加上关联文件完整内容一次性塞给模型直接触发上下文超限。最开始我遇到的长报错搞得任务直接中断审查结果只有一个任务失败的评论。这个问题的解法分三层增量diff策略只看每个文件的变更部分而不是整个文件全文。对单个文件的变更上下文长度做截断超过限度的只保留函数签名和关键行。分阶段分析先按文件逐个分析把每个文件的发现汇总成中间结果再做一轮汇总。不要求一次性看完所有文件。动态降级如果PR实在太大比如超过8000行diff放弃全量审查只审查高风险路径和核心业务文件并在评论里明确告知本次为部分审查。这里最核心的思路是让Agent像人一样处理大PR不要试图一口吞下。人也不会在一秒内看完整份diff而是分文件、分模块、分批处理。5.3 Agent被看起来正常的代码误导大模型的判断有一定概率被代码的表面形式带偏。比如开发者在PR描述里写本次改动仅重构无逻辑变更Agent就可能带着这个先入为主的预期审查时放松警惕。有一次PR实际上在重构过程中偷偷改了排序比较逻辑Agent顺着描述放行了是后来人工评审发现逻辑变了。应对方法是在Skill里加了这么一条在审查时请独立于PR描述判断代码变更。PR描述只是作者的意图声明不是标准答案。发现描述与实际diff不符时高亮提示。从那之后Agent开始能够识别描述与实现不一致的情况甚至有一次直接在评论里指出PR描述称无逻辑变更但第87行的请求参数默认值已修改请确认是否是有意为之。这种反馈力度已经接近一个较认真的中级工程师的水平了。5.4 Token权限最小化踩了次坑在GitHub App配置里我一开始图省事给了Repository permissions里的Contents: Read and write权限。结果某次测试中Agent除了读diff理论上都有能力直接改动仓库代码。虽然Agent不会主动去改但这种权限面在安全审计时是说不过去的。最终我把权限收敛成只读为主Contents只读Pull requests只读Issues只读Checks读写。因为写回评论这类操作只需要Pull requests的写权限就够了。权限越收敛即使Token泄漏攻击者能造成的影响也就越小。6. 从审查机器到评审伙伴后续演进的路线接入跑通只是第一步。真正有价值的是把Hermes从一个会评论的机器人升级成替团队记住规范的评审伙伴。我这里做了三件事进展都不错。6.1 接入GitHub Check Run把Robot挡在merge前评论是建议Check Run是门禁。我后来把Hermes的审查结论也同步到了GitHub的Check Run。如果Agent发现Critical级别问题Check Run状态设成failure配合仓库的branch protection规则直接阻止带问题的PR被合并。这一步的意义在于以前Agent的评论可以被无视但现在CI层面过不去开发者就必须处理或明确说明。我把规则定为Critical问题必须解决或由维护者在评论区声明已知晓风险后才能强制合并。效果是上线前的严重问题几乎清零。6.2 把历史审查沉淀成规则库跑了一个季度之后我回头把Agent在这段时间里的审查记录全部翻出来看哪些问题反复出现。比如团队多次犯改接口调用方时遗漏关联测试的毛病我就把这条规则固化进规则文档。再比如某个模块经常出现空指针风险我也针对性地增加了一条模块级检查规则。这种做法让规则库不是静止的文档而是跟着团队实际发生的错误共同演进。效率提升是滚雪球式的第一周还在频繁调规则一个月之后基本稳定新问题出现的频率越来越低。6.3 人的位置在哪里自动化PR审查上线后我一直跟团队反复强调一件事Robot只是前置过滤器它的任务是帮大家把低层次问题拦下来把时间省出来看真正值得讨论的设计问题。不要因为有了Robot就放弃人工评审也不要因为Robot偶尔误报就全盘否定它。现实中最健康的模式是各司其职Agent负责快速响应、全局扫描、规范检查、安全兜底人负责架构合理性、产品语义、未来演进、以及最终的合并决策。我甚至建议团队reviewer在收到Hermes的评论时先看Agent发现了什么再带着Agent给的上下文去读diff这样整体的review效率是最高的。老实说最初接入Hermes时我的预期只是帮我减少点review时间。但实际跑下来收获最大的是它在潜移默化中统一了团队的规范认知——以前每人心里一套标准现在至少机器这层先按一套规则来大家讨论的焦点也从格式对不对转移到了逻辑对不对。最后分享一个我认为整套方案里最值得注意的小细节无论是配置规则还是调整Prompt一定要让Agent在给出问题结论时附上依据。只说这里有问题没有说服力但如果说这里缺少时间戳校验攻击者可以重放旧请求开发者的接受度就完全不同。自动评审的目的不是让机器人显得聪明而是让评审意见真的被采纳、被落地。这一点做到了这套系统才真正有生命力。