用Hermes打造GitHub PR自动化代码评审智能体-北京尧图网络

你这个PR为什么没有写测试这个函数为什么不直接返回这里是不是应该有缓存——如果你也像我一样每天要被这类review意见轰炸同时又觉得自己看别人代码时根本没时间细读那这篇东西应该是你的菜。我用Hermes做了一套GitHub PR自动化代码评审不是那种挂个机器人卖萌的玩具而是一条真正能跑在仓库事件流里的智能体链路从PR打开的那一刻起自动拉取diff、做语义级分析、按规则过滤噪音、在关键行上回评论全部无人值守跑完。这套东西在我这边已经稳定运行了三个多月累计评审了几百个PR接下来我会把选择理由、链路设计、规则打磨、踩坑记录和团队落地方式完整拆开讲适合正在评估AI代码评审方案、或者准备自己搭一套的技术负责人和爬过不少坑的开发者。1. 为什么我最终选了Hermes做自动评审1.1 人工review在快节奏迭代里藏不住的问题先说个大实话大部分团队的Code Review是在表演不是在评审。代码写的越来越快PR越来越小reviewer却越来越忙。我之前统计过自己团队的数据一个PR平均要等11个小时才有第一条人工评论等到全部讨论结束合并基本要跨两个工作日。这期间开发者在干什么要么切到下一个任务让上下文在脑子里断掉要么就在那干等。人工评审还有两个致命伤。第一是reviewer注意力是随机的看到哪算哪最关键的架构问题往往没人说反而揪着缩进和命名不放第二是人会碍于情面不把问题说透尤其刚入职的新人或者协作方写的东西有经验的同事心里觉得不行嘴巴上却说整体没问题。这些都是制度问题靠团队文化短期根本解不了。既然人不可靠我就把目光转向自动化。我试过传统静态扫描工具ESLint、SonarQube、CodeQL这类的确能拦掉低级错误但它们的本质是已知模式的匹配器发现不了跨文件、跨函数的语义问题。举个例子一个接口的参数从单个ID变成了整个对象静态工具只会报类型不匹配不会去追调用方是否还有隐式的顺序依赖。而这类问题恰恰是review里最有价值的部分。1.2 Hermes的定位不是又一个Lint而是一个编外Reviewer选择Hermes的核心原因是它的定位不在一行代码的规范上而在看得懂上下文。它的工作方式是接收PR的完整上下文——标题、描述、文件变更、diff、关联issue然后像一个人一样做判断这段逻辑是否重复、这个接口变更有没有漏改调用方、异常处理是不是吞掉了关键错误。这些事情本质是语义理解不是正则匹配所以必须由大模型驱动的agent来完成。另一个让我下决心的点是Hermes的设计允许自托管部署。代码评审这件事绕不开仓库权限和代码资产安全很多团队不敢把内部代码送到商业SaaS的服务器上做分析。Hermes以智能体的形式跑在自己的基础设施里代码只经过自己的服务端和所接的模型服务访问边界完全可控。对于把代码安全当红线的团队来说这一点比其他功能都重要。再加上它的规则系统是可编程的你可以把团队的评审规范直接写进配置而不是依赖线上prompt不可见、调整还要排期的黑盒产品。1.3 和GitHub Copilot等现成方案的直观对比做方案对比的时候GitHub官方路线肯定是绕不开的。Copilot现在确实能在PR页面上给出自动review建议开箱即用非常方便但对我的场景有两个硬伤一是它跑在GitHub的云环境里仓库代码默认会被处理合规那边直接一票否决二是它的评审风格偏通用助手你很难告诉它我们团队的异常处理规范是什么、禁止评价哪些东西、什么级别的意见必须block合并。我把三者的差异整理成了下面这张表看完应该就很清楚了对比维度传统静态扫描GitHub Copilot原生PR建议Hermes自托管PR审查Agent检查能力模式匹配只能查已知规则语义级能理解上下文语义级且支持自定义规则部署位置自己CI或云端GitHub云环境完全自托管代码出域看配置但规则基本是共识标准代码会进入GitHub环境处理代码只留在自己服务边界内规则定制需要写死正则/AST规则有限靠系统prompt自由编程团队规范直接落地评审姿势输出清单PR页评论行级评论整体总结状态检查噪音控制很差误报多普通可配置置信度、分级、豁免规则这张表列完选型其实已经结束了。剩下的问题只有一个Hermes这套链路到底怎么搭起来跑顺。下面就是整个架构的拆解。2. 从PR创建到评审落地的完整链路2.1 触发方式GitHub App的Webhook是正路整套链路的第一环是怎么知道一个PR被创建了。Hermes支持两种接入方式一种是用GitHub App注册到仓库另一种是用个人访问令牌PAT去调用REST API。我强烈建议用GitHub App原因有二权限颗粒度完全不同App可以只申请Pull requests和Checks两个权限而PAT在大多数情况下被团队管理员限制得很死甚至拿不到读代码的权限App的身份是独立的机器人它发的review评论会带上Hermes的标识不会被误认成某个同事说的、也不会有为什么小张给了一个和自己代码风格相反的意见这种尴尬。事件监听我关注四个类型pull_request里的opened、synchronize和ready_for_review外加pull_request_review里的submitted。opened管新建PRsynchronize管代码更新ready_for_review管从草稿转正式submitted用于监听人类reviewer已提交意见Hermes可以基于别人的评论补充技术验证这算一个进阶玩法。事件进来之后Hermes先去查一遍这个PR的元数据判断它是否命中需要评审的条件比如来自fork的PR要不要评、draft状态的PR要不要评通常这两个默认都是不评的。2.2 上下文组装从diff到模型能理解的评审材料事件拿到手只是起点真正的难点是把PR长什么样完整告诉Hermes。我不建议直接把原生diff丢给模型就完事因为GitHub的diff默认不带完整上下文模型容易看着删除了一行就去评论实际上删掉的那个函数在文件后面还有大段定义它根本看不见。正确的做法是走GitHub的Contents API把涉及变更的每个文件的最新版本内容抓下来然后在本地做一次diff计算把每个hunk前后各扩展20到30行上下文作为补充材料。组装评审材料时我按下面这个顺序打包给Hermes仓库的编程语言、核心框架、工程目录结构说明PR标题、描述、关联issue的标题和关键内容变更文件的完整列表标注哪些是新增、哪些是修改、哪些是删除每个文件的高亮diff段带扩展上下文本次PR的变更统计比如新增多少行、删除多少行便于模型判断改动规模这个打包过程还有个必须处理的点忽略文件。依赖锁定文件、构建产物、自动生成的代码、vendor目录这些一旦进到diff里轻则浪费token重则让模型完全走偏。我维护了一份默认忽略规则同时在仓库根目录支持.hermesignore自定义效果类似.gitignore但专门服务评审上下文。2.3 评审动作行级评论和整体总结分开做材料组装完Hermes就会开始第一轮文件级评审。为什么不是一次性把所有文件都丢给模型让它一口气评完因为实际测试下来文件数量一多模型对前面文件内容的记忆会急速衰减后面的评论质量明显下降还会出现把A文件的变量名写到B文件评论里的诡异情况。分文件处理之后再把每个文件产生的评审意见汇总起来做一次整体总结准确率高得多。行级评论通过POST /repos/{owner}/{repo}/pulls/{pull_number}/comments这个接口创建每个评论必须带上path和line参数也就是定位到具体的文件和代码行。Hermes会把评审意见里的每个观点先转成结构化数据包含文件、起始行、结束行、严重级别、问题类型、原始评论文本然后逐条去调评论接口。除了行级评论Hermes还会在PR末尾发一段整体总结分成三块本次PR核心变更概述、发现的关键风险点、给人类reviewer的建议关注范围。最后通过Checks API创建一个check run如果有BLOCKING级别的问题状态设为failure否则设为success让分支保护规则可以基于这个状态决定是否允许合并。2.4 增量评审与重复评论的兜底策略评审不是PR创建时跑一次就完了。开发者看到AI评论后大概率会改代码push新commit又触发synchronize事件如果每次都对整个PR重新评一遍会出现两个问题一是历史评论位置已经不在最新代码上行号全部错位二是同一个问题被反复评论开发者会直接爆炸。我的做法是维护一张pr_review_state表记录每个PR的每个文件每次评审时模型的输出摘要包括问题指纹和对应的diff hash。新版diff进来后先计算和上次评审的差异只把新增或发生变化的diff段交给Hermes做增量评审。对于相同问题的判断我给每条评审意见生成一个基于代码片段和问题类型的语义指纹如果在历史评论里找到了相同指纹就不再发重复评论而是给已有的评论点一个或者追加该问题在当前版本仍然存在的轻量回复。这套机制跑起来之后重复评论率从最初的35%降到了不到5%。3. 让AI不乱喷的评审规则设计3.1 先给Hermes定一个人设而不是放养它很多人在让大模型做代码评审时prompt就写一句请审查这个PR找出问题结果模型进入谄媚模式每条评论都像面试里夸赞候选人一样全是空话。我这边第一课就是你必须给Hermes定义一个明确的评审人设和边界。我们在规则系统里定义的角色是一个在这个仓库工作了两年半的资深开发者熟悉团队的代码规范和历史架构决策只关注值得花人力去改的问题。这里的关键词是只关注值得改的——不是把模型训练成一个找茬机器而是过滤掉那些改了也没意义的东西。这段人设会作为系统级指令在所有评审任务前固定注入效果立竿见影模型输出的垃圾评论量直接少了一半。3.2 噪音评论的硬过滤规则写在prompt之外光靠prompt约束模型不可靠模型本质是概率输出今天就遵守规则明天一个措辞变化就可能放飞。我在Hermes的规则层里加了一套不依赖模型自觉的硬过滤规则任何评审意见在发送前都必须过这一层。这些规则用YAML声明类似下面这样noise_filter: deny_phrases: - 建议优化 - 建议重构 - 性能可能会受影响 - 代码风格建议 min_line_count: 8 max_comment_length: 500 require_actionable: true allow_praise: false ignore_files: - *.lock - package-lock.json - dist/** ignore_patterns: - \\b(TODO|FIXME|HACK)\\b逐条解释下这些规则的意图。deny_phrases把那些常见的AI空话直接掐死只要评论里出现这些短语就不发防止模型输出建议优化性能这种说了等于没说的话。require_actionable是强制要求评论必须包含可执行的修改建议且建议不能是请优化这种而最好是能指明改哪个函数、加什么判断、参数怎么调整。allow_praise设为false不允许模型发这段代码写得很清晰之类的废话AI的认可对开发者来说没有价值反而会让真正的问题被淹没。ignore_patterns里的TODO和FIXME是故意放过的团队成员已经用注释标记了这些问题AI再评论一遍纯属噪音。3.3 严重级别让AI的意见有明确的分量评审意见最怕的就是全部一个等级开发者不知道哪条必须改、哪条可以忽略。Hermes把意见分成三个级别并且每个级别在评论里都有显式标签BLOCKING阻塞合并、SHOULD-FIX应该修改、NIT吹毛求疵级别。这个分级不是让模型随便定的我在指令里给了明确标准BLOCKING只允许用在三类问题上会导致线上故障的缺陷、明显的安全漏洞、以及会让本次PR功能无法按预期工作的错误。搞笑的是我刚上线这套分级的时候Hermes会把所有意见都标成BLOCKING整个PR被它锁得没法合并。后来在指令里加了如果你无法用一句话说明这个问题为什么会导致线上故障那它就不是BLOCKING效果才正常。NIT级别则要求模型主动控制数量一个PR里NIT意见不超过三条因为NIT的本质是不改也行发多了只会让作者心烦。3.4 一个经过验证的评审指令模板把规则层和指令层分开之后我沉淀了一套可以直接抄走的prompt核心模板。这里不涉及任何团队私有信息你拿去改改就能用你现在是仓库{repo}的资深代码评审员。请基于我提供的PR信息、diff和文件上下文进行评审。评审时必须遵守以下规则 1. 只评论你确信的问题。如果没有把握保持沉默。 2. 每个评论必须包含三部分问题定位、根因分析、具体修改建议。 3. 修改建议必须指明修改位置函数名/代码块和修改方向禁止请自行优化。 4. 如果发现跨文件影响在评论中明确列出受影响文件。 5. 禁止评论代码风格、缩进、命名等静态工具已覆盖的内容。 6. 禁止输出赞扬性内容。 7. 按BLOCKING/SHOULD-FIX/NIT分级标准如下 - BLOCKING可能导致线上故障、安全问题、或者功能无法实现 - SHOULD-FIX虽然不是致命缺陷但违背最佳实践或可能导致潜在bug - NIT非必要修改每PR最多三条 8. 如果某个问题在历史上已经讨论过并有意保留不要重复提出。我在多个仓库里用这套模板跑了几个迭代它最大的作用是给模型定了一个少说但说准的基调。实际评审质量不能只看单个PR的感受还要看后面统计反馈闭环的部分。4. 实测运行三个月踩过的坑4.1 解释性注释被当成坏味道典型的上下文缺失上线第一周最离谱的一次事故是Hermes在一段处理支付回调的复杂逻辑里把开发者的解释性注释批成了无用注释建议删除。那段注释解释了为什么这里必须延迟50毫秒再处理下一个状态机、以及延迟是为了配合第三方网关的最终一致性。作者看到评论直接炸了在群里问这AI是不是不懂业务。我打开评审日志一看原因很清楚组装上下文时只带了diff和文件片段没有把相邻的历史代码、相关文档带进去模型完全没看懂那段注释背后的业务含义。排查链路是这样的先导出了那条评论对应的请求日志发现送入模型的上文里只有120行代码diff注释所在函数的前后几十行根本没有再进一步查prompt发现系统指令里没有对解释性注释这类常见合法模式做豁免。根因确认之后做了两个修复一是在指令里显式声明当代码涉及复杂业务逻辑、并发处理、外部系统对接时解释性注释是必要且合法的不得建议删除二是把模型温度从默认的0.7下调到了0.2让输出更保守、更聚焦文件内的事实。4.2 大PR直接吃满Token评审中途崩溃跑通之后的第二批问题来自超大PR。有次同事把一次数据库迁移、一个模块重构和二十多个文件的测试改动全塞进了一个PR总diff超过8万字符。Hermes在组装上下文时把这些全部打包送给了模型结果请求直接超出上下文窗口被拒绝整个评审链路静默失败——没有任何评论也没有check runPR就那么明晃晃地摆在那里没人评。排查的时候我先看的日志发现模型调用接口抛出了max_tokens相关的错误紧接着又做了个对照测试手工把那个PR的文件列表摘出来发现接上文时没有做变体筛选。修复方案分三层第一层在上下文组装阶段对大型PR强制启动分块评审模式按文件维度切块每块之间增加这是同一个PR的第N块的衔接信息第二层设置单次评审最大token预算超过预算的PR自动跳过非关键文件的详细分析只做整体结构和风险扫描第三层增加失败重试和告警模型调用一旦失败Hermes会在PR里发一条评审失败上下文超限已降级为标准规则扫描同时给管理员推一条告警避免静默故障。4.3 并发触发的API限流与评论风暴有段时间组里做一次大规模重构十几个PR几乎在同一时间点被创建。Hermes本来是按PR维度做并发评审的结果十几个请求一起打到模型服务和GitHub API上直接触发了官方的限流策略。最尴尬的是GitHub对评论接口的限流是按仓库和用户维度算的因为所有评论都是用Hermes这个App的身份发的一个PR的评论还没发完另一个PR就开始报secondary rate limit错误。排查下来问题出在我没有做任何流量整形。修复方案是在Hermes里加了一个简单的队列调度器全局一共允许三个PR并发评审每个PR内部行级评论的创建速率控制在每两秒最多五条超出的排队等待。同时给GitHub API调用加上了指数退避重试Retry-After响应头里的值作为基准等待时间。这套调度上线后再也没出现过批量限流。值得多说一句的是这种并发问题在测试环境几乎踩不到因为只有真实的一天十几个PR涌进来才能暴露调度器的脆弱所以如果你也要搭类似系统建议上线前用历史PR数据做一次回放压测。4.4 评论疲劳每个PR十条AI意见作者快麻了有一个阶段Hermes的评论量很大每个PR平均十条意见而且大部分是SHOULD-FIX级别的潜在优化。表面看AI很勤奋但当开发者连看十条都发现改了也行、不改也没事之后他会对整个AI评审失去信任连真正重要的BLOCKING意见也不看了。这就是典型的评论疲劳和我们手机上推送通知越来越多却越来越不想看是一个道理。我的修复策略很简单把评审的默认目标从找出所有问题改成找出不要让这个PR带着隐患上线的那些问题。在规则里新增了一条如果一个问题不能明确地描述出它会导致什么具体故障场景那就不允许SHOULD-FIX级别以上的评论出现。同时把意见总数做了硬性上限单个PR最多输出八条意见超过上限的意见进入一个隐藏的草稿箱只有当作者主动说给我更详细的建议时才会展示。这个改动之后PR上的评论数降到了平均四条但作者评论里明确说有帮助、并照着修改的比例反而提高了近一倍。4.5 权限边界App权限开大了一点点就被安全同事找上门用GitHub App接入时我一开始直接用官方示例里的默认权限模板包含Contents读写、Pull requests读写、Checks读写。上线第二周安全同事发来一条告警说这个App有权直接往默认分支推送代码虽然实际没用但权限面明显超出只做评审的最小需求。我这才认真翻了GitHub官方文档发现Pull requests的write权限不仅包括发表评审意见还包括修改、关闭甚至合入PR的能力。排查链路不复杂就是反复核对App需要的权限和接口文档里的权限要求。最终我把权限收敛到这个清单Contents只保留read需要拉取文件内容做上下文Pull requests保留read和write因为要创建行级评论和整体评论必须用写权限Checks保留read和write用于创建check runIssues用read用于读取关联issue的标题Metadata自动附带read这是GitHub App的强制项。收敛完之后权限面满足了只能看、只能评、不能合的目标。这步排查也给我提了个醒接任何外部工具到代码仓库权限最小化不是安全团队的额外要求而是基本盘。5. 落地团队的协作流程与配置清单5.1 哪些PR必须走Hermes哪些可以不评不是所有PR都值得AI评审。在实际落地中我把PR分成了三类分别走不同的策略。第一类是核心服务的主分支变更强制Hermes评审且BLOCKING意见会阻塞合并第二类是feature分支合并到develop的常规PRHermes照常评审但BLOCKING只作为建议最终决策权在人类reviewer手上第三类是文档更新、依赖版本升级、配置修改这类低风险PR默认跳过详细评审只跑一个基本的变更检查。这个分类直接在Hermes的配置里用路径规则和分支规则表达。比如依赖升级类PRdiff里全是package.json和package-lock.json的变更Hermes的语义分析几乎没有用武之地跑了也是浪费token。我用一个简单的路径匹配规则把这些PR全部排除效果立竿见影每天消耗的token直接降了四成。这里的思路是自动化评审不是越多越好而是要把算力花在风险最高的地方。5.2 人类reviewer和AI的分工边界AI评审不是替代人工review而是把人工从找茬模式里解放出来让它专注在AI做不了的事情上。我团队里现在执行的流程是PR创建后Hermes先跑几分钟内给出评论和整体总结开发者收到Hermes的提示后当期就改一轮等代码稳定了再找人类reviewer人类只review那几处被Hermes标记为高风险的地方以及Hermes不擅长的架构决策、业务语义、长期演进这类问题。这样分工给团队带来的最直观变化是人类reviewer平均看一个PR的时间从二十分钟缩短到不到十分钟。因为相当一部分低级问题、边界遗漏、异常处理的缺失已经在AI阶段被拦住了人类reviewer不需要重复这些低水平的辛苦。但我也给团队定了一条铁律Hermes说没问题不代表真的没问题它没有通过测试确认行为的能力在并发、性能、数据一致性这些领域仍然需要人类做判断。AI可以作为第一道过滤网但绝不能成为代码质量正确性的最终裁决者。5.3 一套可以直接照抄的配置文件模板走到这一步我把自己团队目前在生产环境跑的Hermes配置脱敏后整理了一份你可以直接对着改。整个配置分成三块接入设置、评审行为、消息通道。app: mode: github_app app_id: 123456 private_key_file: /etc/hermes/hermes.private-key.pem webhook_secret: ${HERMES_WEBHOOK_SECRET} install_filter: organizations: - your-org repositories: - core-service - web-frontend review: auto_review: enabled: true on_events: [opened, synchronize, ready_for_review] skip_drafts: true skip_fork: true skip_paths: - *.md - **/package-lock.json - dist/** - vendor/** model: provider: your_model_provider base_url: http://hermes-model-proxy:8080 model_name: your-review-model temperature: 0.2 max_tokens: 4000 timeout_seconds: 90 severity: blocking_on_check: true max_comments_per_pr: 8 queue: max_concurrent_prs: 3 comment_rate_per_second: 2.5 notifications: admin_webhook: ${ADMIN_WEBHOOK_URL} on_failure: true on_rate_limit: true metrics: storage: sqlite db_path: /var/lib/hermes/hermes.db几个要注意的关键项model.temperature必须压低0.2是我调过一轮之后的稳定值太高会让模型输出发散、过度发挥queue.comment_rate_per_second是前面提到的限流保护2.5这个值实测不会触发GitHub的次级限流max_comments_per_pr是防评论疲劳的硬闸。还有一个容易忽略的skip_fork强制设为true因为来自fork的PR通常没有完整上下文而且提交者不受团队规范约束AI评审意义不大反而可能产生误导。5.4 用数据做反馈闭环而不是凭感觉调整最后我要强调的是评审规则不可能一步到位必须靠数据迭代。我在Hermes里加了两个关键统计维度意见采纳率和评审精准度。用户在PR页面上对某条AI评论点回复或确认修改就视为采纳反之如果作者明确回复这不是问题或者关闭不予处理则记录为一次误报。每天自动汇总一个表格展示不同问题类别安全、空值、并发、性能、可读性等的采纳率和误报率。复盘的时候魔改方向就非常清晰了如果某个类别采纳率低于30%说明规则和指令与该类别不匹配要么是这个问题判定标准不对要么是Hermes误把FYI当成了问题我会针对这类问题做精准的prompt修正然后在样本集上做回归测试。相反如果某个类别采纳率很高但评论总数很少说明这个方向是团队真正感到疼的我会把相关规则权重提高让Hermes更积极的挖掘同类问题。三个月下来整体意见采纳率从最初的45%升到了67%左右这个数字对AI评审来说已经算是相当能打的了。如果在搭这套系统的过程中只能选一条经验带走我想说是AI review真正难的地方从来不在调用模型而在于让模型知道什么话值得说、什么话不该说。你能把这条想透Hermes就能从一个话痨助手变成团队里真正靠谱的那双眼睛。

用Hermes打造GitHub PR自动化代码评审智能体

相关推荐

通读《Life Level-up Guide》后记：进阶的真义是诚实、证据与可返回的下一步

obsidian-skills 完整指南：让 AI 操作 Obsidian，跑通笔记自动化的四个环节

WPS论文参考文献插入全攻略：脚注尾注与手动方案详解

更多资讯

Puppeteer Browser.screens() 深度解析：获取屏幕信息与屏幕模拟的 API 实现

Claude Sonnet 4.6 运行时安全注入指令（safety_instructions_from_anthropic）深度解析

RPCS3 自动更新完整指南：查版本、选通道、三步开启并验证

XLD无损音频转换指南：CD抓轨、FLAC转码，3步搞定

Aider 基准测试中的 LLM 速度对比：GPT-4 Turbo 与 gpt-3.5-turbo-1106 的推理延迟实测

SpringBoot+Vue+MySQL校园疫情防控毕设实战指南

今日更新

能源系统对接碳交易的路径：从碳核算到碳资产运营

智能硬件数据驱动运营：订单日记与预测性维护实践

逆变器下垂控制与虚拟同步机对比：Simulink仿真建模与参数整定

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？