1. 每天 20 个待审 PR人工 review 的效率和盲区我负责的仓库进入快速迭代期之后每天新增的 PR 稳定在 20 个左右。作为一个多端项目的主仓库这意味着每天早上打开 GitHub都要面对一整屏的 Changes requested、Approved 和大量等待 review 的卡片。团队里有经验的同事各有各的模块要维护真正能抽出大块时间逐行读 diff 的人越来越少。而 PR 越积越多代码合并的周期越拉越长下游的联调和发布也跟着堵。那段时间我连续踩了几次比较疼的坑。一次是有人改了配置中心的一个默认值这个改动藏在 400 多行的无关重构里review 时没人注意到结果上线后所有新实例都用了新参数回滚不说还得手动改对比配置。另一次是某个 SDK 升级把旧版本里一个已经废弃的 API 重新启用了新的 behavior代码编译能过但运行时的日志含义完全变了。这些单靠人眼扫描 记忆根本防不住。所以我把视线转向了自动化代码评审。市面上能用的方案其实分几类一类是 SonarQube 这种以静态分析为核心的平台规则库非常全但对业务语义的理解几乎为零属于语法和模式层面的体检另一类是 GitHub CodeQL 或者内置的 Dependabot它们能盯住安全问题、依赖漏洞和常见坏味道非常值得开但它们不会告诉你这个改动会不会破坏其他模块的调用约定。我真正需要的是一个能理解这个项目在做什么、改动意味着什么的审查助手。它能自动把 PR 里的 diff 拉下来结合项目上下文做初步评估给出可疑点、风险点和需要人工关注的清单——这就是我最终选择 Hermes 来做 GitHub PR 自动审查的原因。这篇文章不是官方文档的复读。我会从实际部署、接入、调优和踩坑这几个角度把我最近两个月用 Hermes 做 PR 自动审查的完整过程分享出来。如果你也在为 PR 积压、review 漏检、跨模块改动难以评估这些问题头疼这篇文章至少能帮你少走不少弯路。2. 为什么选 Hermes自动审查工具的真实取舍逻辑2.1 静态检查与智能审查的本质差异我最早试过自己写 GitHub Action 来跑 eslint、tsc 和一些自定义规则脚本。这套方案对付统一风格、禁止语法错误、检查安全依赖非常有效率CI 上跑一次差不多一两分钟就出结果完全够用。但问题在于lint 和编译检查只能回答这行代码合不合法回答不了这段代码会不会破坏现有功能。举例来说后端接口的字段从一个对象里的data.items改成了data.result.items只要调用方也同步改了编译器就会通过lint 也不会报警——但如果另一个服务里还有一段没被测试覆盖的代码在按旧结构取值这个改动就会在生产环境炸掉。人工 review 能发现这种问题靠的是对业务的整体理解和长期积累的上下文。而 Hermes 这类 agent 形态的工具和传统静态检查的核心差异就在这里它不是一个规则执行器而是一个带上下文的理解器。你可以把仓库说明、模块结构、常用模式告诉它它会在审查时综合这些上下文对每个 PR 形成类似人类的判断。它给出的不是第 X 行有语法错误而是第 X 行改了公共导出但调用方 Y 里还在用旧的导入路径需要确认是否同步调整。2.2 选 Hermes 而不是自研或接 Codex 的原因我认真比较过三条路线。第一条是自研审查服务。把 GitHub App 的 webhook 接入自己的后端解析 PR 事件调用一个大模型接口让模型读完 diff 之后输出 JSON 格式的评论。这个方案看起来可控性最强但实际做起来工作量巨大要处理 webhook 的重试、PR 的增量更新、评论的幂等性、模型输出的稳定性还要维护一套配置文件来告诉模型每个仓库的技术栈和规范。哪怕只做基本能用的水平也需要投入一周左右的开发而且后续每个细节都要自己磨。第二条是直接用 ChatGPT / Claude 的网页端。把 diff 复制进去让 AI 看看这对偶尔审查一两个 PR是有效的但一旦 PR 文件数量多起来对话就变得不可维护。每次都要手动画出 diff、切换上下文、追问细节占用的时间并不比人工用 Git 看 diff 少太多。第三条也就是我最终采用的是用 Hermes 这样以 agent 形态运行的开源审查工具。它把拉取 PR 数据、理解上下文、生成审查建议、提交评论这条链路封装好了我只需要做两件事一是把 GitHub Token 配好让它有权限读仓库和写 review 评论二是针对项目写一份简单的审查偏好说明告诉它项目里哪些文件是核心、常用的验收标准是什么。剩下的它自己在每次 PR 更新后跑一遍输出结构化的审查意见到对应 discussion 里。2.3 Hermes 的部署形态和社区生态Hermes 目前的部署形态主要是本地/服务器运行 GitHub 对接官方也提供了通过 Docker 拉起的方式来方便快速部署。它本身是基于大模型驱动的 agent 应用对运行环境的要求不高普通服务器就能跑起来关键依赖是调用大模型的 API Key。在社区生态上Hermes 的配置和使用方式正在被越来越多人验证尤其适合两类人一类是像我这样需要在高频 PR 仓库中保持代码质量的维护者另一类是团队里有统一代码规范、但缺乏专职架构师做评审的中小型开发组。它不需要你懂复杂的 RBAC 权限模型也不需要你搭一套完整的 CI/CD 平台属于轻量、可逐步调整的方案。3. 部署与接入从零到跑通首个自动审查任务3.1 环境准备与安装我是在一台 Ubuntu 20.04 的服务器上跑 Hermes 的配置不高2 核 4G 内存没有 GPU。先说结论这个配置完全够用因为真正吃算力的部分在远端的大模型 API 上Hermes 本地进程只做数据拉取、上下文组织和结果输出CPU 占用和内存消耗都很小。安装方式参考官方文档核心步骤如下# 1. 克隆 Hermes 代码仓库 git clone https://github.com/your-fork/hermes.git cd hermes # 2. 创建 Python 虚拟环境并安装依赖推荐 3.10 python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. 复制配置模板 cp .env.example .env如果你不太想在服务器上保留 Python 环境用 Docker 会更干净。官方提供了容器镜像通过环境变量传入配置执行docker pull和docker run就能拉起服务日志也会直接打到 stdout方便观察。我个人很推荐先用 Docker 跑通流程、确认没有配置问题再决定要不要换成裸进程常驻。注意安装时建议把 Hermes 单独放到一个系统用户下运行不要用 root。因为 Hermes 默认会从 GitHub 拉取 PR 里的补丁和元数据也存在被异常输入触发的可能。独立用户 文件目录权限收敛能把这个风险隔离掉。3.2 GitHub Token 权限配置这一步非常关键也是最容易被忽略的。Hermes 要正常干活需要两个层级的 GitHub 权限一个是读取仓库内容、PR diff、提交历史、issue 信息另一个是向 PR 写入 review 评论。在 GitHub 上创建 Personal Access Token 时我给的权限是下面的最小集权限项访问级别用途Repository permissions: ContentsRead读取仓库文件结构和代码用于理解项目上下文Repository permissions: Pull requestsRead/Write读取 PR 信息和变更写入审查评论Repository permissions: MetadataRead获取仓库基础元数据如名称、默认分支Account permissions: EmailRead可选某些场景下需要关联提交者信息我见过有人图省事直接勾选了整个reposcope相当于全仓库读写这虽然能跑但风险比较大。如果这台服务器上还运行着其他脚本一旦被第三方攻击者拿到 token不仅 PR 会被乱提仓库代码也可能被篡改。建议严格执行最小权限原则Token 只给到目标仓库过期时间尽量设短比如 30 天轮换一次。3.3 最小配置启动安装完成后核心的配置项在.env或容器环境变量里。以.env为例# GitHub 配置 GITHUB_TOKENghp_你的token GITHUB_REPOSusername/repo-name # 模型 API 配置根据你选择的模型服务商填写 LLM_API_KEYsk-你的key LLM_MODELdeepseek-chat # 可选自定义审查配置路径 HERMES_CONFIG./config/project_rules.yaml启动命令也很简单python main.py --daemon或是 Dockerdocker run -d \ --name hermes \ --env-file .env \ -v $PWD/config:/app/config \ hermes-image:latest跑起来之后Hermes 会以轮询或 webhook 的方式监听指定仓库的 PR 事件。首次启动时它会先拉取一次仓库元数据建立本地缓存然后开始处理已存在的待审 PR。3.4 第一个自动审查任务实测输出启动几分钟后我给测试仓库提了一个小 PR——修改一个工具函数把原来的list返回类型换成了generator同时更新了两处调用。Hermes 自动在 PR 的评论区生成了审查意见我简化一下当时的输出针对此 PR 的自动审查初步结果 1. [注意] 函数 get_user_profiles 的返回类型由 List[UserProfile] 改为 Iterator[UserProfile] 可能导致调用方索引访问失败。请检查 - src/services/user_service.py 第 87 行profiles[0] 的索引访问 - tests/test_user_service.py 第 34 行对返回结果调用了 len()。 2. [建议] 类型标注变化后建议补充一个针对空生成器的边界测试 防止下游代码误认为返回值总是可重复遍历。 3. [提示] 改动文件数量较少变更范围清晰没有检测到明显安全问题。看完那一刻我是比较惊喜的。它没有只停留在类型变了这种表面结论而是把List换成Iterator后可能引发的三个连锁风险点全都点出来了。这种跨文件联动的分析能力靠 lint 是做不到的。第一个任务跑通之后我心里对这套方案的预期就从能跑升级到了值得深度打磨。4. Hermes 的审查逻辑与配置体系让它越用越聪明4.1 一次审查背后发生了什么很多人以为 Hermes 只是把整个 PR 的 diff 扔给大模型让它看着办。实际不是这样。如果真这么干输出会非常不稳定模型的注意力会被大量无关改动稀释评论里会充满这段代码看起来没问题之类的废话。Hermes 的实际工作流程大致分四步我结合源码和日志梳理过变更面提取解析 PR 的 commit 列表和文件变更按文件类型和改动范围做一次分类判断这个 PR 是功能开发、缺陷修复、重构还是配置调整。上下文组装从仓库里读取与本次改动相关的模块定义、依赖关系、接口签名等元信息把这段代码在项目里所处的位置补充给模型。审查策略选择根据配置决定重点看什么。是优先关注安全敏感点如 SQL 拼接、命令执行还是优先关注兼容性如接口签名、数据格式变更或是重点关注测试覆盖情况。不同场景下审查指令会不同。结果生成与落盘模型输出 JSON 格式的结构化意见Hermes 将其转成 GitHub review 评论并保留一份本地记录方便后续复盘。4.2 用仓库规则文件约束审查边界默认的审查策略偏通用适合所有项目但它的平均水平不会特别贴合你的具体场景。我强烈建议你加一份project_rules.yaml用大白话告诉 Hermes 这个仓库里什么重要、什么不重要、什么叫合格。我的配置文件大致长这样project: name: user-platform description: 用户平台主仓库包含用户认证、资料管理、通知服务和后台管理模块。 前端使用 Vue3后端使用 Go数据库使用 MySQL依赖 Redis 做缓存。 review: focus: - security - api_compatibility - performance ignore: - *.md # 文档变化默认不深入审查 - yarn.lock - go.sum rules: - pattern: SQL message: 如果检测到字符串拼接方式生成 SQL必须改为参数化查询 并检查是否存在注入风险。 level: error - pattern: TODO|FIXME message: 新代码中出现 TODO 或 FIXME 时建议补充 ticket 链接或说明原因 避免技术债失联。 level: warning - pattern: panic(|log.Fatal( message: Go 代码里新增 panic 级调用必须显式说明理由 并评估是否会导致服务直接退出。 level: warning这份配置的核心价值是让 Hermes 知道哪些东西在这个项目里是高优先级关注对象。比如我们团队在 SQL 安全问题上有过教训我就在规则里加了这条哪怕某个人写的 SQL 写法跟库里的老代码风格一致Hermes 也会因为规则命中而给出 error 级别提醒。4.3 审查输出的标准化格式与接入流程Hermes 输出到 GitHub 的评论并不是随便一段散文。建议你在配置里让它按一套统一模板输出比如每条意见包含三部分风险级别error/warning/notice、问题描述精确到文件和行号、建议处理方式。格式化输出的目的有两个。第一对开发者来说一眼就能判断这条评论是要必须处理的、还是可选的第二对后续的自动化流程来说固定结构方便解析——比如你可以接一个 GitHub Action把 error 级别的意见筛选出来作为 CI 是否通过的条件之一实现 自动审查卡点。我在团队里落地的时候没有一开始就把 Hermes 的意见当成强制门禁。而是先用静态机器人评论的方式跑了约两周收集它给出的意见逐个跟资深工程师核对准确性等确认误报率低到可以接受的程度后才把 error 级别的审查结果接到合并检查里。这个渐进式的上线节奏很关键既能让工具快速体现价值又不会因为一两次误判消耗团队的信任。4.4 高频场景的自定义策略再来分享两个我实际用下来比较有效的高频场景配置。第一个是依赖升级类 PR。这类 PR 通常由 Dependabot 自动创建diff 大部分在go.mod或package.json里逐行看意义不大。我在规则里给这类 PR 单独加了一段提示让 Hermes 在审查时额外关注升级的主版本号是否带来了 breaking change、是否有已知的 CVE、是否影响了与当前运行环境的兼容性。这样一个本来需要人工去 Release Notes 里扒的信息现在会自动汇总在评论里。第二个是数据库迁移类 PR。我们项目里 SQL 迁移脚本是独立的migrations/目录这类文件一旦提交并执行不允许随意修改。我给 Hermes 加了规则对migrations/目录下已存在且非本次新增的文件只允许追加内容不允许修改或删除。这条规则用到的是对历史变更的理解能力它会在审查时对比当前 PR 和之前的提交记录一旦发现历史迁移脚本被改就会立刻报警。5. 实际接入中踩过的坑和解决思路5.1 模型把重构误判为 BugHermes 刚接入的第三天它在一个 PR 上给出了一条 error 级别的评论说函数 removeUserById 被删除但仍在多处被引用可能导致编译失败。团队里的开发看到这条评论很紧张马上顺着去看结果发现那个 PR 确实删除了这个函数但同时把所有的调用点都替换成了新的deleteUser方法。Hermes 的评论是完全错误的误报。我排查日志后发现问题出在上下文组装环节。Hermes 在分析时把 PR 的 diff 按文件单独喂给了模型但模型的注意力窗口或上下文策略没有一次性拿到删除函数 修改调用方这个完整链路导致它只看到了删除动作没看到同步的替换动作。解决方案是在配置文件里加了两条参数一是把context_strategy设为full_diff强制它在审查时一次性读取所有文件的完整变更而不是逐个文件分析二是对重构类 PR 加大 review 的历史对比权重让模型先看这个 PR 的 commit 列表先理解这次改动的目标再逐文件看细节。这样调整之后类似的误报基本消失了。5.2 审查评论刷屏按 diff 的每条 comment 都回复另一个很实际的问题是噪音。默认配置下Hermes 会在 PR 中每个自己关注的代码块都生成一个评论如果这个 PR 改动很多它可能会一次发出十几条意见。这导致真实的人工评审人员打开 PR 后先要花十分钟划掉这些机器人评论反而降低了效率。我最终的解决办法是在配置里开启summary_mode让 Hermes 把所有意见合并成一篇总评并在每条意见里带精确的文件路径和行号。人工评审时先看总评再点进对应代码块去确认体验比一条条刷屏好得多。而且在 GitHub 的 UI 里总评式输出天然适合放进 review thread 里所有讨论可以在一个线程内完成后续的追问和答复也不容易散掉。5.3 Token 权限过宽引发的一次安全事件这也是个比较典型的失误。我最开始图省事按照网上某篇教程把 Token 权限设成了全仓库读写其中还包括了对 main 分支的直接推送权限。结果有一次服务器被扫描器攻击攻击者通过一个暴露端口的服务拿到了环境变量。虽然那次没有造成实际损失但让我意识到自动化工具暴露的攻击面比你想象的大得多。后来我把 Token 换成了 fine-grained token只授予目标仓库的 Pull requests 和 Contents 读取权限Token 的有效期缩短为 30 天并加了 GitHub Secret 管理让 Hermes 运行时从环境里的 Secret 注入而不是把 Token 写到.env文件后随容器长期驻留。现在每周都会检查一次 access log看看有没有异常的 API 调用。5.4 并发 PR 较多时容易排队影响审查时效如果是开源项目或者大团队的核心仓库PR 往往会在某个时段密集出现。Hermes 默认串行处理 PR一个审查下来可能要几分钟如果同时来 10 个 PR最后一个可能要等半小时以上。这种延迟对于一些合并前置检查的场景是完全不能接受的。我的做法是把 Hermes 部署实例从一个扩展成两个一个负责监听新创建的 PR 并做初步审查另一个负责在 PR 更新时做增量审查。两个实例的数据相互独立通过配置里的instance_role区分任务类型。如果你的仓库 PR 量没那么大其实一个实例就够了等排队超过 10 分钟再考虑扩容也不迟。6. 让它融入团队工作流从机器人审到协作伙伴6.1 给开发者提供必要的工作流指引把 Hermes 接入仓库后我发现团队里有个适应过程。刚开始有人看到自动审查评论会紧张把它当成必须全部修改的命令也有人完全无视它觉得这只是个机器人。当你把自动审查结论接入合并门禁时这个问题会变得更突出。所以我在团队内部写了一页非常简短的工作流说明核心就三条Hermes 的 error 级意见必须处理要么修掉要么在评论区给出合理解释warning 级意见建议处理如果选择不处理请在 PR 描述里注明原因notice 级意见仅供参考不要求强制响应。有了这三条底线开发者对机器人评论的处理方式就统一了不是所有机器人都要照单全收但 error 级这种带明确否决性质的结论要有要么说服它、要么改代码的闭环。6.2 与 CI 流水线的联动我目前的 CI 流水线里有三个环节跟代码质量相关静态检查、单元测试、Hermes 审查。前两个是原有的Hermes 审查作为新加入的一环放在合并到 main 分支之前。运行方式是push 到 PR 分支后GitHub Actions 触发 CICI 跑完静态检查和单测后调用 Hermes 的 CLI 命令让它在当前 PR 上生成审查评论并检查结果里有没有 error 级意见。如果有CI 流程失败PR 不能合并。# .github/workflows/ci.yml 片段 - name: Run Hermes review run: hermes review --repo ${{ github.repository }} --pr ${{ github.event.pull_request.number }} env: GITHUB_TOKEN: ${{ secrets.HERMES_TOKEN }} LLM_API_KEY: ${{ secrets.LLM_API_KEY }}这个方案跑了两周实际效果是可以接受的。它把一部分原本必须由资深工程师执行的初筛工作转移给了自动审查人工评审员的精力被释放出来他们看 PR 的时候更多的注意力能放在架构合理性、业务逻辑正确性这些更为高层的维度上。6.3 团队文化层面的一个观察最后说一个容易被忽视的观察自动化审查工具能不能发挥价值很大程度取决于团队是否愿意把它当成伙伴而不是对抗者。如果工具一上线主管要求所有机器人意见全部处理那团队就会对工具产生防御心理开始想办法绕过它。而如果把它定位成帮大家减少重复劳动、兜住低级错误的助手并明确给出人可以否决机器结论的机制团队的接受度和配合度都会明显高很多。我见过很多团队在接入这类工具时上来就把门禁卡得很死反而导致工具形同虚设——因为总有人能找到绕过检查的方式。更好的做法是先从建议模式跑通建立信任后再切换成门禁模式。这个转变过程其实是团队对工具、工具对项目双向调优的过程。7. 一些后续优化思路和我的整体感受7.1 把审查结果沉淀到项目知识库到目前为止Hermes 的审查还是每次独立进行。但它积累的所有 review 评论和最终处理结果其实是非常宝贵的项目资产。我正在做的一件事是把历史 review 结论导出按模块归类和标注形成一个轻量级的项目常见问题库。后续当新的 PR 涉及类似模块时Hermes 可以像检索记忆一样把这些历史上下文补充进分析过程里减少完全靠模型临场发挥的随机性。这个方向做扎实之后自动审查的可信度和稳定性都会上一个台阶因为它的判断依据里多了一层这个项目曾经出现过什么问题的经验基础而不只是模型训练时的通用知识。7.2 对模型选择的一些测试心得Hermes 本身不绑定某一个具体模型但不同模型在代码审查场景里的表现差异非常明显。我试下来比较直观的感觉是模型能力越强审查结果的识别率和上下文理解能力越好但成本也越高。如果你只是接一个低流量的小仓库用通用且性价比高的模型就够用了但如果你需要它处理大量跨文件、跨模块的关联分析投入更高的模型能力通常能显著降低误报率。一个比较务实的做法是在 CI 阶段用速审模型跑全量 PR遇到可疑点再用强推理模型做二次核验。两种模型配合成本和效果能做到一个相对平衡的点。7.3 写在最后的体验经过这几个月的使用我对 Hermes 做 GitHub PR 自动审查的感受可以浓缩成一句话它不能替代资深工程师的判断但它能帮你把那些重复的、机械的、需要跨文件检索的审查工作在几分钟内做完把人的时间留到真正需要思考的地方去。如果你正被 PR 积压、review 漏检这些问题困扰我的建议很简单先用最小配置跑通一个测试仓库把project_rules.yaml写起来观察一两周的实际输出再来决定要不要把它接入核心流程。反过来如果你仓库的 PR 量本身不大、代码评审流程本身很健康那其实不一定需要引入这类工具——工具是服务于流程的而不是反过来给流程增加复杂度。按需接入、渐进调整才是比较合适的心态。
