Hermes实战：用规则引擎和大模型打造GitHub PR自动审查工具

1. 为什么我要折腾一个 Hermes 来做 PR 自动审查先说个背景。我参与维护的几个开源项目最近 PR 数量明显多起来了。社区贡献者来自不同水平段有些 PR 改得很到位但也有很多一眼就能看出问题代码风格不统一、缺少单元测试、存在明显的边界条件遗漏、文档没同步更新。每次我都要花大量时间点开 diff、逐行过一遍、再写评论一套流程下来一个中型 PR 少说半小时多则一下午。这种重复劳动做久了人真的会麻。所以当我的一个同事提到 Hermes 这个项目时我第一反应是看看它到底能把代码评审自动化到什么程度。他原话是“你把自己的评审标准写进去让它帮你先过一遍你只需要看它觉得有问题的部分。”这句话打动了我。于是我把 Hermes 拉下来折腾了一遍从安装、配置到跑真实 PR踩了不少坑也摸清了不少门道。这篇博客就是想把 Hermes 这套 GitHub PR 自动审查工具讲透从原理到实操从配置到排坑尽量让拿到这篇文章的人能直接照着做。先明确一点Hermes 不是一个“AI 魔法”它是一个会按你给的规则去读代码、找问题、生成评价的自动化框架。它的核心作用不是替代你做判断而是替代你做“初步筛选”和“信息整理”。它把你的评审经验和标准制度化、可执行化让机器先过滤掉 80% 的明显问题你只需要集中精力处理剩下 20% 需要真正动脑子的地方。Hermes 适合谁适合那些维护多个仓库、PR 量大、或者本身就想把团队代码规范落到自动检查层面的人。它不挑语言原理是通用的不过对 Python、JavaScript、Go 这类主流语言的适配效果明显更好。我自己前后用了大概两周目前已经把它接入了两个项目的 CI 流程效果比预期好尤其在对新贡献者的代码做“礼仪审查”和“基础质量审查”上省了很多沟通成本。2. Hermes 的设计思路与整体架构拆解2.1 它不是一个简单的大模型套壳很多类似工具的做法很简单把 PR 的 diff 塞给一个大语言模型然后让模型输出评论。这种做法有两个致命问题。第一大模型对“这个项目应该遵循什么规范”一无所知它只会根据泛化的代码知识去评论经常给出“建议把循环改成列表推导式”这种正确但没有针对性的废话。第二没有上下文。它看不到这个 PR 改动的文件在项目中处于什么位置不知道这个函数被谁调用也没法判断测试是否真的覆盖了核心逻辑。Hermes 的设计思路完全不同。它不是把 PR 交给模型就完事而是做了一个“读取代码、分析代码、再调用模型生成评价”的多阶段管道。我把它理解为三层结构信息采集层负责从 GitHub 拉取 PR 数据包括 diff、文件列表、提交历史、评论上下文、CI 状态等这是整个系统的事实基础。分析规则层根据你写好的审查规则对采集到的信息做结构化分析。这一层负责“发现问题”比如某个文件没有对应的测试、某个函数缺少异常处理、某处配置出现了硬编码。生成表达层把分析结果交给语言模型由模型负责生成自然语言评论表达方式更接近人类 Reviewer 的口吻并把建议按严重程度分好等级。这个拆法的好处非常明显。分析规则层是确定性的它不会像大模型那样“幻觉”出来一个问题生成表达层则负责把确定性的分析结果转化成人类容易读的评论。换句话说Hermes 把“发现问题”和“表达问题”分开处理前者靠规则保证精度后者靠模型保证体验。2.2 核心模块的功能拆解我实际跑下来觉得有四个模块是 Hermes 的核心缺一个整体效果都会差不少。第一个是 PR 扫描模块。它做的事情简单但繁琐——读取 PR 的元数据、文件变更列表、每个文件的 diff内容、 commit 信息、评论记录等。这些数据是后续所有分析的地基。这个模块还负责把 diff 按文件分组、统计增删行数、识别新增文件和删除文件方便后面的规则引擎做判断。第二个是 LLM 模块也就是大模型调用层。这一层主要负责两件事一个是对“模糊问题”的理解比如“这段代码是否存在潜在竞态条件”另一个是评论的润色把规则引擎的输出从干巴巴的“Missing test”变成“这个函数逻辑较复杂建议补充单元测试覆盖异常分支”。这个模块天然支持自定义模型地址也就是说你不一定用默认的模型可以换成企业内部私有化部署的模型这一点对于有数据安全要求的团队很友好。第三个是 Perplexity 搜索加权模块。这个名字听起来高大上实际作用就是对分析结果做“加权校准”。举个具体场景规则引擎扫描到一个文件有改动但不确定这个文件是否属于核心逻辑这时候就需要搜索加权模块介入根据文件路径、代码结构、项目配置等信息给不同文件和分析结果打权重。比如src/core目录下的文件权重就比docs目录下的高这种权重直接影响最终问题严重程度的排序。第四个是 GitHub 集成模块。它负责把生成好的评论通过 GitHub API 提交到对应 PR 上。可以是一行一行的 inline comment也可以是一条总结性评论还支持把完整审查报告以评论形式发送。这一层做得好的地方是支持 dry-run 模式也就是先不实际发评论把生成的审查结果输出到日志或者本地文件供你自己检查调整等效果满意了再打开真正提交评论的开关。2.3 为什么用这种架构而不是简单调 API我在实际配置过程中想过一个问题既然最终都要调用大模型为什么不直接让模型读整个 PR 然后一次性返回所有评论试过之后发现两个硬伤。第一个是上下文长度和价值密度的问题。一个大型 PR 动辄几千行 diff直接把全部内容塞给模型不光是 token 成本高而且模型会“迷失”在大量低价值信息里最终给出的评论变得泛泛而谈缺少针对性。Hermes 的做法是先让规则引擎定位到具体可疑行再把“可疑点周围代码项目上下文”作为输入这样传给模型的信息更加紧凑输出质量自然高不少。第二个是可解释性和可控性。纯靠大模型做评审你根本没法控制它关注什么、忽略什么。而 Hermes 的规则引擎是确定的、可审计的——你可以清楚地知道“是什么规则触发了这条评论”出了问题也能立刻定位是规则写得太宽还是模型理解偏了。这种可控程度对于把工具接入正式评审流程非常重要不然你根本不敢让它自动评论因为不知道它会在 PR 下面说出什么奇怪的话。3. Hermes 的安装、配置与落地实操3.1 环境准备与安装过程我以 Linux 服务器为例macOS 也基本通用。Hermes 的安装方式不算复杂核心依赖是 Python 3.10 和 Git如果你计划在本地跑还需要 Docker 来起服务依赖比如 Redis用它做简单的状态缓存。在我测试的时候安装主要分三步走。第一步克隆项目并安装 Python 依赖。官方推荐使用conda创建独立环境这样可以避免把系统 Python 环境搞乱。由于部分依赖包需要编译安装建议提前装好 build toolsgit clone https://github.com/your-org/hermes.git cd hermes conda create -n hermes python3.10 -y conda activate hermes pip install -r requirements.txt这里插一句如果是在国内网络环境用 pip 安装大型依赖包时建议换用国内镜像源否则有些包下载速度很慢甚至超时失败。我实际用清华源跑一遍基本两分钟就装完了。配置方式是在用户目录下建一个~/.pip/pip.conf文件并写入镜像地址。第二步配置环境变量。Hermes 将GITHUB_TOKEN、模型 API 地址和密钥都放进了环境变量里这样做的好处是可以直接在 CI 或者 Docker 里动态注入不用把密钥写死在配置文件中。我建议单独创建一个用于自动化评审的 GitHub Token权限只需要repo范围不要用个人主 Token权限范围太大有安全隐患。第三步验证安装是否成功。Hermes 自带了一个命令行入口可以先用--help看看命令是否正常打印出来然后跑一个自检命令它会自动检查环境变量、网络连通性以及模型 API 是否能正常响应python main.py --self-check如果这一步全部通过说明环境没问题可以进入下一步配置。3.2 审查规则的配置方法与语法解析Hermes 最核心的配置项是审查规则这直接决定了你的自动化评审到底在“审什么”。默认的规则文件是一个 JSON 或者 YAML 格式的配置文件里面定义了若干条规则每条规则包括 id、描述、触发条件、严重级别几项。我举个实际配置的片段。比如你想让 Hermes 强制要求每个新增的 Python 文件必须有对应的测试文件rules: - id: R001 name: New Python file should have a corresponding test file severity: warning language: python condition: type: file_pattern pattern: **/*.py exclude: [tests/**, setup.py, conf.py] require_matching: tests/test_*.py这段配置的意思很清晰对所有新增的.py文件排除掉tests目录和配置文件检查是否在tests目录下存在对应的test_文件名.py。如果没有就产生一条 warning 级别的评论。规则引擎会逐条执行这些配置收集所有触发点然后一并交给 LLM 模块生成评论。在配置时有一点值得注意规则不是越严格越好太严格会变成“狼来了”开发者会逐渐麻木真正重要的问题反而被淹没。我自己的经验是先从 warning 级开始跑几个真实 PR看看误报率再逐步把稳定高效的规则提升到 error 级。除了文件级的规则Hermes 还支持直接在 diff 行上做分析。比如检查是否引入了调试用的print语句、是否有明文密码硬编码等。这类规则可以在 diff 层面精确到行评论时也可以直接定位到具体代码行非常方便。3.3 与 GitHub 仓库的完整对接流程配置好规则后接下来就是把 Hermes 与你的 GitHub 仓库做对接。整体流程分四步。第一步设置 Webhook。Hermes 需要监听 GitHub 的pull_request事件所以在仓库的 Settings - Webhooks 中新增一个 WebhookPayload URL 填你部署 Hermes 服务的地址触发事件勾选Pull requests即可。第二步配置仓库级参数。如果不希望所有 PR 都触发审查你可以在 Hermes 的配置文件中配置白名单规则比如只有修改了特定目录的 PR 才触发或者只处理来自非特定成员非管理员的 PR。对于大型团队来说这个能力很实用避免内部成员提交的 WIP PR 也被 Roast 一顿。第三步验证对接结果。提交一个测试 PR观察 Hermes 是否在日志里正确识别到这个 PR并且按配置的规则跑完了分析流程。第一次跑的时候建议开启 dry-run 模式只查看分析结果不实际发表评论。第四步打开自动评论开关。确认分析结果符合预期后把配置中的dry_run改为falseHermes 就会自动把评论提交到 PR 上。3.4 用 dry-run 模式帮你调整评审风格我强烈建议所有人都先跑一遍 dry-run 再上生产。不只是初次配置时使用每次修改规则后也应该先 dry-run 几轮看看新规则会不会误伤正常代码。dry-run 模式下的输出是一个 JSON 文件里面记录了每条规则是否触发、触发在哪一行、生成的评论草案以及严重级别。你甚至可以看到 Hermes 对判断为“无问题”的文件的处理理由这对于调试规则非常有用。我经常是改完规则后用历史 PR 重新跑一遍看看规则效果有没有达到预期再决定是否正式启用。4. 文档输出与代码评审的量化评估4.1 自动生成的审查报告长什么样Hermes 跑完一轮审查之后除了在 PR 下发表评论之外还可以生成一份结构化的审查报告。报告通常包含以下几个部分变更概览本次 PR 修改了哪些文件增删行数统计哪些是核心文件、哪些是辅助文件。风险评估变更对整体项目风险的影响程度评估比如改动涉及核心模块、数据库逻辑或者对外 API 的会被标记为高风险。问题列表按严重级别分组的评论列表每条评论包含触发规则、文件位置、问题描述、修改建议。测试覆盖分析新增/修改的代码是否有测试覆盖覆盖率变化趋势如何。审查结论综合以上维度Hermes 给出的一个类似于“建议合并 / 请求修改 / 拒绝”的结论。这个报告可以直接作为 PR 描述的一部分也可以作为 CI 过程中的独立产物存到构建系统里。对于需要向团队管理层汇报代码质量的项目这个报告的价值就被放大了。4.2 评论的严重级别与合并判定逻辑Hermes 的评论严重级别分为三个等级error、warning、info。error 是必须修复的问题比如引入了语法错误、明显的安全漏洞、破坏了现有测试warning 是建议处理但非强制性比如代码风格不一致、缺少必要注释、性能隐患info 是参考性的比如可以优化的命名、更便捷的写法建议。在合并判定逻辑上我配置的规则是只要存在未解决的 error 级别评论CI 就会自动失败PR 不能被合并。warning 级别的评论会展示但不会阻塞合并留给开发者自行判断。这个策略执行下来代码库的质量底线有了明显提升同时又不至于因为过于严格的政策让贡献者感到挫折。4.3 怎么衡量一个自动化评审工具好不好用用一段时间后我想分享几个我用来评估 Hermes 效果好坏的量化指标这也是我们内部决定继续使用它的依据评论命中率被开发者接受并修改的评论比例。如果经常被开发者回复“这个建议不合理”说明规则设置有问题。问题发现前置率在人工介入之前已经发现的问题占比。这点最重要理想状态下60% 以上的明显问题应该在人工评审之前就被自动捕获。误报率被开发者忽略或者关闭的评论占比。这个比例高于 30% 说明规则太严格需要调宽。平均评审时长从 PR 开通到首条有效反馈的时间。用 Hermes 后我们项目的平均反馈时间从 4 小时降到了 20 分钟以内。5. 常见问题与排查技巧实录5.1 Webhook 不触发或评论不出现这是最常遇到的问题九成以上是 Webhook 配置问题。我踩过的坑主要有三个一是 Webhook 的 Payload URL 没填对服务器无法访问被 GitHub 判定为投递失败二是事件类型没勾选Pull requests所以 PR 打开了但根本没触发请求三是服务端没有开放公网访问GitHub 的 Webhook 推不进来。排查方法很简单在仓库的 Settings - Webhooks 页面点开对应 Webhook查看最近的 “Recent Deliveries” 记录。如果显示投递失败可以点击重发并在服务端日志里查看本次请求有没有进来。如果你是用内网测试可以用ngrok之类工具把本地端口映射到公网临时测试确认逻辑没问题后再部署到真正的服务器上。5.2 模型 API 响应不稳定或超时Hermes 依赖大模型做评论生成所以模型服务的稳定性直接影响整体体验。我碰到的问题主要是自建模型服务的并发能力不够多个 PR 同时触发审查时API 响应时间飙升甚至超时。解决方法有两个方向一个是给 Hermes 加上队列机制避免同时发起太多请求另一个是优化模型调用的参数降低输出 token 数上限因为评论本来就该是短小精悍的不需要长篇小说。另一方面模型输出偶尔会出现偏移现象——规则引擎认为这是 warning 级别的问题但模型生成的评论语气太软看起来像是 info。这种情况可以在 prompt 模板里做好约束明确告诉模型“根据给定的严重级别输出对应强度的评论语气”。5.3 GitHub 镜像访问与网络加速对自动化流程的影响如果你所在团队的网络环境对 GitHub 的访问不稳定这个问题会在自动化流程中被放大很多倍。因为 Hermes 的所有数据都来自 GitHub API如果 API 请求超时整个审查流程就卡住了。一个比较稳妥的解决方法是给 Hermes 部署节点选择一个能稳定访问 GitHub API 的区域或者在服务端配置 GitHub API 的镜像代理地址。另外建议把 GitHub Token 做成可轮换的并且确保 Token 没有过期。遇到过的最尴尬的情况就是 Token 过期了评审流程静默失败好几天没人发现。6. 我对 Hermes 效果的真实评价与改进方向Hermes 不是银弹但它在“自动化代码评审”这个赛道上确实做出了自己的特点。它跟那种直接调大模型评论一遍的“玩具”不一样它是真的把代码评审的经验沉淀成了规则再通过规则驱动模型生成高质量评论。这种“理性分析感性表达”的组合让评论既精准又自然。我实际用下来最明显的感觉是它帮我省掉了大部分“这代码没测试”这类基础性问题的时间让我能集中精力看那些需要深度思考的逻辑设计、架构合理性等问题。这带来的价值不仅是时间上的更是注意力和判断力上的——“该你判断的地方你有足够的脑力去判断”。如果后续要继续迭代我个人会关注三个方向一是对更多语言做深度适配目前对 JavaScript、Go 的支持有待增强二是支持更多自定义规则维度比如可以接入团队内部的规范文档做语义检查三是将多个 PR 的审查数据聚合起来做趋势分析帮助团队看清代码质量的演进过程。最后分享一个我的个人使用习惯我会把 Hermes 的审查结论当成“第一轮评审意见”但绝不直接照单全收。每条评论我都会亲自过一遍尤其对 warning 级别的建议需要结合整个 PR 的上下文来判断是否采纳。工具是帮我们提高效率的不是替我们做决定的把握好这个边界Hermes 才会成为你的得力助手。