如果你维护的仓库一周有三四十个 PR作为核心 reviewer 的你很难每个都认真读一遍 diff。我们团队大约十个人维护几个内部仓库PR 一多就只能靠两个老员工轮流顶着看Review 积压、低级问题漏到主干、规范讨论反复拉扯这些痛我猜很多团队都有共鸣。上个月我们做了个调整把一个叫 Hermes 的智能体挂进了 GitHub PR 流程里让它先于人类完成一轮自动化代码评审。Hermes 在这个场景里的定位不是替代人也不是又一个 lint 工具。它收到 GitHub 的 PR 事件后会主动拉取代码、读取 diff、对照 PR 描述分析变更逻辑再把可疑点按优先级写成行内评论和汇总意见通过 GitHub API 回写到 PR 讨论里。也就是说当开发者打开一个 PR 时里面已经有了一份由机器生成的、带代码位置引用和修改建议的初筛报告。这篇文章不是产品介绍是一次完整的落地复盘。我会把这样的链路选型思路、部署细节、规则与提示词怎么调、真实 PR 里踩过的三个大坑、以及误报和成本控制方法都摊开讲。如果你是那种Reviewer 已经满负荷、PR 队列经常积压、想引入 AI 又怕误报的维护者这篇文章值得看完。1. 先说结论我为什么决定把 PR 初筛交给 Agent1.1 人工 Review 的舒适区与真实盲区先说一个可能不好听但对现状很真实的现象在大多数中小团队里代码评审并不是技术问题而是时间分配问题。Reviewer 被迫在自己开发任务和别人的 PR 之间来回切换真正能静下心逐行读代码的时间非常有限。最终的结果是架构级别的、大方向的讨论基本都能被覆盖但很多数据校验边界、错误处理分支、资源释放这类细节问题恰恰最容易在差不多看了的状态下漏掉。这种场景里人工 Review 的舒适区其实是设计评审和经验判断而不是机械性的检查。需要人反复确认的东西往往并不是新的业务逻辑本身而是那些通用规则新增的路径是否覆盖了空参数、数据库查询是否走了索引、异常情况下资源会不会泄漏、日志会不会把敏感字段打出来。这些规则每一轮都问一遍人很快就会疲劳而机器不会。1.2 自动化代码评审的三个层级在做方案调研的时候我习惯把代码质量相关的自动化能力分成三个层级来理解这样不容易被AI 会自动 review这种概念带偏。层级典型工具特点它能发现什么静态规则引擎Ruff、ESLint、SonarQube秒级反馈、结果稳定、可解释格式问题、未用变量、明显反模式测试与 CIPytest、Jest、GitHub Actions验证行为正确性但只能验证已覆盖路径功能回归、接口契约变化Agent 语义评审Hermes 这一类智能体能理解变更意图跨文件推断上下文逻辑漏洞、边界缺失、一致性偏差、安全隐患这里有个很容易踩的误区团队如果已经上了 lint 和单测就以为自动化代码评审已经做完了。但静态规则是没法知道这个 PR 的语义上下文到底是什么的它处理不了这个分支条件在 3 个调用方里行为不一致这类问题。单测可以在代码写好之后验证结果对不对但没法在代码还没跑起来之前告诉作者哪里可能会错。Hermes 这种 agent 补的恰好是语义理解这一层。1.3 我眼里的角色定位“助理评审员”不是“自动批准机器人”很多团队引入 AI 评审时最担心的不是它没用而是它乱说话、刷屏、挡流程。所以我们从第一天就定了一个原则Hermes 的所有评审意见都只是建议不参与 approve更不允许阻塞合并。它的实际产出是这几类东西一是 PR 级别的一段 summary讲清楚这个变更大概在做什么二是针对 diff 中具体行代码的评论每条评论都要求给出文件、行号、问题类型和修改建议三是一个需人工确认清单专门放那些模型自己也拿不准、但代码里看起来不合常理的疑点。人在打开 PR 时看到的不再是一块白板而是一张已经标注过的初稿。这才是 Agent 参与代码评审最舒服的状态。2. 链路选型GitHub App、Webhook 与 Actions我最终选了哪条路2.1 把 GitHub 和 Hermes 接起来主流方式其实只有三种所有 GitHub 之上的自动化本质都是在回答一个问题代码仓库里发生了什么事你怎么知道你又凭什么去回写结果。落到具体实现上常见的就是下表三条路。接入方式触发机制权限模型部署成本适合场景GitHub App Webhook 事件驱动GitHub 主动推送事件到自建服务App 安装级授权可精确限仓库需要一台公网可达服务器长时任务、需要跨 PR 缓存状态GitHub Actions workflowYAML 定义事件触发 CI 任务Actions token随 workflow 生命周期基本零运维短任务、依赖官方生态定时调用 GitHub API 轮询自己控制节奏PAT 或 App token简单但浪费无法开 Webhook 的网络环境从触发时效和可控制性综合来看Webhook 事件驱动是最符合自动化代码评审这个场景的。PR 创建、提交新 commit、被请求 review 这些动作GitHub 都会在秒级把事件推给服务端。Hermes 不需要反复拉取也不会因为轮询太频繁而被 API rate limit 卡住。2.2 我采用的模式GitHub App 只授予最低必要权限我注册的是一个 GitHub App而不用普通的 Personal Access Token。原因是 App 能按安装到哪个组织/仓库做授权权限范围也拆得非常细比一把梭的 token 安全很多。GitHub App 创建时Payload URL 填成 Hermes 服务的 Webhook 地址例如https://review.example.com/webhook/githubWebhook secret 用openssl rand -hex 32生成一串随机值这个值会用于之后校验每次请求的来源。Permissions 里只需要三项权限级别用途ContentsRead-only拉取仓库代码来分析 diff 上下文Pull requestsRead write读取 PR 信息并提交 review 评论MetadataRead-only获取仓库基础元数据GitHub 强制要求Subscribe to events 里勾上 Pull requests 一项就够了。这样 GitHub 只会在 PR 的 opened、synchronize、reopened 等时刻通知我们不会把 issue、push、star 之类无关事件也倒进来。2.3 为什么没有直接用 GitHub Actions 写完整个评审任务我们前期确实做过一个 Actions 版原型但很快就放弃了。最大的问题是代码评审这个任务本身不适合放在 CI 容器里短跑。一次认真一点的评审要读取 PR 描述、拉取 refs/pull/ /head、分析 diff、可能还要读几个相关文件的局部实现最后再调用大模型 API 生成意见。整个链路在模型推理比较慢或者网络波动时很容易超过 Actions 单任务的超时上限而且工作流的日志也不适合长时间审查跨多个 commit 的状态。Actions 的优势是完全不需要维护服务器这在很多轻量任务里很香。但是代码评审需要记忆这个 PR 上一次评审到了哪个 commit、哪些评论已经发过了、哪些规则已经被开发者标记为误报。这些状态放在长驻服务里很自然放在每次冷启动的容器里就非常别扭。另外Hermes 本身带调度逻辑长驻服务也方便本地调试开发时可以直接在本机跑起来对着测试事件调。所以在整个系统里GitHub Actions 仍然承担单元测试和静态检查而 Hermes 作为一个独立的 Webhook 服务在旁边跑。各干各的谁也不把谁拖垮。3. 部署与配置从空仓库到跑通第一次 PR 评审3.1 运行时环境与依赖安装Hermes 服务的部署形态是一台 4 核 8G 的 Linux 服务器前面挂 Nginx 做 TLS 终结和请求转发后面跑 Hermes runtime。模型推理走外部 API所以本地不需要 GPU硬件压力很小。不过这里有个容易被忽略的点Hermes 同时需要访问 GitHub API 和模型 API网络时延必须稳定否则拉代码和调模型都会频繁超时。建议选一台对 GitHub 网络链路相对畅通的节点部署前先用curl -I https://api.github.com确认一下。环境方面我比较推荐用 conda 隔离出一套干净的 Python 运行时避免污染服务器系统 Pythonconda create -n hermes python3.10 -y conda activate hermes pip install -U pip pip install hermes-agent不同版本的 Hermes 发行包入口名可能有差异有的叫hermes有的叫hermes-agent安装后先执行hermes --version确认一下。如果你服务器的 conda 配置文件里自定义过软件源通道最好确认相关依赖都来自同一个稳定通道别在生产机上进行通道混合实验否则很容易遇到上次能装上这次装不上的依赖解析问题。3.2 服务配置文件里的几个关键项Hermes 的配置我拆成了两部分一部分是运行时参数比如监听端口、日志级别、并发 worker 数另一部分是密钥和外部 API 地址
基于Hermes的GitHub PR自动化代码评审实践
如果你维护的仓库一周有三四十个 PR作为核心 reviewer 的你很难每个都认真读一遍 diff。我们团队大约十个人维护几个内部仓库PR 一多就只能靠两个老员工轮流顶着看Review 积压、低级问题漏到主干、规范讨论反复拉扯这些痛我猜很多团队都有共鸣。上个月我们做了个调整把一个叫 Hermes 的智能体挂进了 GitHub PR 流程里让它先于人类完成一轮自动化代码评审。Hermes 在这个场景里的定位不是替代人也不是又一个 lint 工具。它收到 GitHub 的 PR 事件后会主动拉取代码、读取 diff、对照 PR 描述分析变更逻辑再把可疑点按优先级写成行内评论和汇总意见通过 GitHub API 回写到 PR 讨论里。也就是说当开发者打开一个 PR 时里面已经有了一份由机器生成的、带代码位置引用和修改建议的初筛报告。这篇文章不是产品介绍是一次完整的落地复盘。我会把这样的链路选型思路、部署细节、规则与提示词怎么调、真实 PR 里踩过的三个大坑、以及误报和成本控制方法都摊开讲。如果你是那种Reviewer 已经满负荷、PR 队列经常积压、想引入 AI 又怕误报的维护者这篇文章值得看完。1. 先说结论我为什么决定把 PR 初筛交给 Agent1.1 人工 Review 的舒适区与真实盲区先说一个可能不好听但对现状很真实的现象在大多数中小团队里代码评审并不是技术问题而是时间分配问题。Reviewer 被迫在自己开发任务和别人的 PR 之间来回切换真正能静下心逐行读代码的时间非常有限。最终的结果是架构级别的、大方向的讨论基本都能被覆盖但很多数据校验边界、错误处理分支、资源释放这类细节问题恰恰最容易在差不多看了的状态下漏掉。这种场景里人工 Review 的舒适区其实是设计评审和经验判断而不是机械性的检查。需要人反复确认的东西往往并不是新的业务逻辑本身而是那些通用规则新增的路径是否覆盖了空参数、数据库查询是否走了索引、异常情况下资源会不会泄漏、日志会不会把敏感字段打出来。这些规则每一轮都问一遍人很快就会疲劳而机器不会。1.2 自动化代码评审的三个层级在做方案调研的时候我习惯把代码质量相关的自动化能力分成三个层级来理解这样不容易被AI 会自动 review这种概念带偏。层级典型工具特点它能发现什么静态规则引擎Ruff、ESLint、SonarQube秒级反馈、结果稳定、可解释格式问题、未用变量、明显反模式测试与 CIPytest、Jest、GitHub Actions验证行为正确性但只能验证已覆盖路径功能回归、接口契约变化Agent 语义评审Hermes 这一类智能体能理解变更意图跨文件推断上下文逻辑漏洞、边界缺失、一致性偏差、安全隐患这里有个很容易踩的误区团队如果已经上了 lint 和单测就以为自动化代码评审已经做完了。但静态规则是没法知道这个 PR 的语义上下文到底是什么的它处理不了这个分支条件在 3 个调用方里行为不一致这类问题。单测可以在代码写好之后验证结果对不对但没法在代码还没跑起来之前告诉作者哪里可能会错。Hermes 这种 agent 补的恰好是语义理解这一层。1.3 我眼里的角色定位“助理评审员”不是“自动批准机器人”很多团队引入 AI 评审时最担心的不是它没用而是它乱说话、刷屏、挡流程。所以我们从第一天就定了一个原则Hermes 的所有评审意见都只是建议不参与 approve更不允许阻塞合并。它的实际产出是这几类东西一是 PR 级别的一段 summary讲清楚这个变更大概在做什么二是针对 diff 中具体行代码的评论每条评论都要求给出文件、行号、问题类型和修改建议三是一个需人工确认清单专门放那些模型自己也拿不准、但代码里看起来不合常理的疑点。人在打开 PR 时看到的不再是一块白板而是一张已经标注过的初稿。这才是 Agent 参与代码评审最舒服的状态。2. 链路选型GitHub App、Webhook 与 Actions我最终选了哪条路2.1 把 GitHub 和 Hermes 接起来主流方式其实只有三种所有 GitHub 之上的自动化本质都是在回答一个问题代码仓库里发生了什么事你怎么知道你又凭什么去回写结果。落到具体实现上常见的就是下表三条路。接入方式触发机制权限模型部署成本适合场景GitHub App Webhook 事件驱动GitHub 主动推送事件到自建服务App 安装级授权可精确限仓库需要一台公网可达服务器长时任务、需要跨 PR 缓存状态GitHub Actions workflowYAML 定义事件触发 CI 任务Actions token随 workflow 生命周期基本零运维短任务、依赖官方生态定时调用 GitHub API 轮询自己控制节奏PAT 或 App token简单但浪费无法开 Webhook 的网络环境从触发时效和可控制性综合来看Webhook 事件驱动是最符合自动化代码评审这个场景的。PR 创建、提交新 commit、被请求 review 这些动作GitHub 都会在秒级把事件推给服务端。Hermes 不需要反复拉取也不会因为轮询太频繁而被 API rate limit 卡住。2.2 我采用的模式GitHub App 只授予最低必要权限我注册的是一个 GitHub App而不用普通的 Personal Access Token。原因是 App 能按安装到哪个组织/仓库做授权权限范围也拆得非常细比一把梭的 token 安全很多。GitHub App 创建时Payload URL 填成 Hermes 服务的 Webhook 地址例如https://review.example.com/webhook/githubWebhook secret 用openssl rand -hex 32生成一串随机值这个值会用于之后校验每次请求的来源。Permissions 里只需要三项权限级别用途ContentsRead-only拉取仓库代码来分析 diff 上下文Pull requestsRead write读取 PR 信息并提交 review 评论MetadataRead-only获取仓库基础元数据GitHub 强制要求Subscribe to events 里勾上 Pull requests 一项就够了。这样 GitHub 只会在 PR 的 opened、synchronize、reopened 等时刻通知我们不会把 issue、push、star 之类无关事件也倒进来。2.3 为什么没有直接用 GitHub Actions 写完整个评审任务我们前期确实做过一个 Actions 版原型但很快就放弃了。最大的问题是代码评审这个任务本身不适合放在 CI 容器里短跑。一次认真一点的评审要读取 PR 描述、拉取 refs/pull/ /head、分析 diff、可能还要读几个相关文件的局部实现最后再调用大模型 API 生成意见。整个链路在模型推理比较慢或者网络波动时很容易超过 Actions 单任务的超时上限而且工作流的日志也不适合长时间审查跨多个 commit 的状态。Actions 的优势是完全不需要维护服务器这在很多轻量任务里很香。但是代码评审需要记忆这个 PR 上一次评审到了哪个 commit、哪些评论已经发过了、哪些规则已经被开发者标记为误报。这些状态放在长驻服务里很自然放在每次冷启动的容器里就非常别扭。另外Hermes 本身带调度逻辑长驻服务也方便本地调试开发时可以直接在本机跑起来对着测试事件调。所以在整个系统里GitHub Actions 仍然承担单元测试和静态检查而 Hermes 作为一个独立的 Webhook 服务在旁边跑。各干各的谁也不把谁拖垮。3. 部署与配置从空仓库到跑通第一次 PR 评审3.1 运行时环境与依赖安装Hermes 服务的部署形态是一台 4 核 8G 的 Linux 服务器前面挂 Nginx 做 TLS 终结和请求转发后面跑 Hermes runtime。模型推理走外部 API所以本地不需要 GPU硬件压力很小。不过这里有个容易被忽略的点Hermes 同时需要访问 GitHub API 和模型 API网络时延必须稳定否则拉代码和调模型都会频繁超时。建议选一台对 GitHub 网络链路相对畅通的节点部署前先用curl -I https://api.github.com确认一下。环境方面我比较推荐用 conda 隔离出一套干净的 Python 运行时避免污染服务器系统 Pythonconda create -n hermes python3.10 -y conda activate hermes pip install -U pip pip install hermes-agent不同版本的 Hermes 发行包入口名可能有差异有的叫hermes有的叫hermes-agent安装后先执行hermes --version确认一下。如果你服务器的 conda 配置文件里自定义过软件源通道最好确认相关依赖都来自同一个稳定通道别在生产机上进行通道混合实验否则很容易遇到上次能装上这次装不上的依赖解析问题。3.2 服务配置文件里的几个关键项Hermes 的配置我拆成了两部分一部分是运行时参数比如监听端口、日志级别、并发 worker 数另一部分是密钥和外部 API 地址