我一直有个执念：代码评审这件事，应该让机器先把该看的看了，人再集中精力看机器看不懂的。所以当 Hermes 这个智能体出现在我视野里的时候，我几乎没有犹豫就把它接到了 GitHub PR 流程里。跑了两个月，几百个 PR 下来，我的体感是：它真的能帮团队把 Code Review 的底线兜住，甚至偶尔能提出让我眼前一亮的建议。
这篇文章就把我这段时间搭建 Hermes 自动化评审的完整过程分享出来，包括架构选型、规则配置、成本控制、误报调优，以及一套可以直接抄走的实战配置。如果你也在搞 GitHub 仓库的自动化代码评审，或者对 AI 辅助 Code Review 有兴趣，这篇文章应该能帮你少走不少弯路。
1. 为什么把 PR 审查交给智能体：评审流程里的三个死穴
先聊聊动机。很多人觉得 Code Review 不就是看看代码吗，有什么难的？但如果你是团队里长期担任核心 Reviewer 的人，你一定懂那种“看代码看到想吐”的感觉。我把团队过去半年的 PR 评审数据拉出来看了一下，发现真正的问题根本不在“能力”，而在“节奏”和“注意力”。
1.1 人工评审的疲劳曲线
人的注意力是典型的 U 型曲线。上午刚开工的半小时和下午快下班的那一小段时间，是评审质量最高的窗口；但这个窗口往往被例会、IM 消息和线上问题吃得精光。剩下的时间，尤其是连续看三四个 PR 之后，你会发现自己的眼球在 diff 上行走了，但脑子已经不动了。
这种状态下，最容易漏掉什么问题？不是复杂的设计缺陷，恰恰是最低级的错误：
- 空指针/除零这类未加防护的边界值
- 日志里把
%s和%d写反 - 删掉了测试用例却没删对应逻辑
- 环境变量名大小写不一致
- 事务没提交或连接没释放
人工评审在这种节奏下，完全是在用意志力对抗注意力的自然衰减。你靠“自己注意”是没法根治的。
1.2 风格标准在团队里的漂移
很多团队的编码规范写得很好，但实际执行情况完全靠 Reviewer 的个人记忆。新来的同事不知道旧约定，老同事改代码时顺手带偏，时间一长，整个代码库的风格就开始了“布朗运动”。今天 review 的人心情好放过去了，明天心情不好又挑出来说，规则全凭个人当下的感知，没有统一性。
Hermes 这类工具的第一个价值，是它不存在疲劳和情绪，它会严格按照你配置的规范去逐行核对。这不只是“抓 bug”，更是把团队规范从“口头文化”变成了“可执行的代码”。
1.3 低级错误漏网的成本
你说一个低级 bug 能造成多大损失？我见过因为一个判空漏掉，导致整个定时任务在每月最后一天凌晨直接 panic 的；也见过因为一个 SQL 拼接顺序问题，把线上数据更新错了的。这类问题在 PR 阶段只需要一眼就能发现，但一旦漏到生产，排查成本成倍上升。
所以我把自动化评审定位成：
第一道关卡负责过滤低级问题，人类 Reviewer 负责更高层的设计评审和业务合理性判断。
Hermes 就是这道第一关卡里的常驻哨兵。
2. Hermes 接入 GitHub 的两种姿势：GitHub App 与 Actions 的取舍
Hermes 本身是一个可独立运行的智能体程序，它通过 GitHub 的 API 去拉取 PR 的变更内容，再调用大模型对 diff 做分析，最后把评审结果以评论的形式提交回 PR 页面。但它和 GitHub 之间怎么建立联系，有两条主流路线，我先后都试过，各有各的脾气。
2.1 形态一：GitHub App 常驻监听
第一种方式是注册一个 GitHub App，让 Hermes 以机器人身份常驻监听仓库事件。你在仓库里配好 Webhook，每当有pull_request、pull_request_review等事件发生，GitHub 就会把事件推送到 Hermes 服务。
这种方式的好处是实时性极强，PR 一开就能在几秒内收到评审意见，而且可以做很多“主动”的动作，比如：
- 给 PR 打标签（Bug / Enhancement / Docs）
- 请求针对特定文件的 review
- 在 CI 跑完之前提前预审
- 根据 PR 标题自动分配评审人
缺点也很明显：你需要自己维护一个常驻服务。不管是跑在服务器上还是容器里，都要考虑可用性、鉴权、日志保留这些事。对于一个轻量团队来说，这属于“额外背了一个服务”的负担。
2.2 形态二：Actions 按需触发
第二种方式是完全基于 GitHub Actions 的。你在仓库里放一个 workflow 文件，监听pull_request事件，在 CI 环境里临时拉起 Hermes，跑完审查、提交评论、随后销毁容器。
这个方案的实时性比 App 模式略差，因为每次都要冷启动环境。但好处也很直接：
- 不需要自己维护服务，跑在 GitHub 的托管 Runner 上
- 计费透明，按分钟算
- 便于在 workflow 里串其他检查（lint、单测、构建）
- 仓库维度可独立开关，方便灰度测试
我当时刚开始试水时，很自然地选了第二种。
2.3 我为什么最终选择 Actions + 定时兜底
在我的实际配置里，最终的形态是一套组合拳：
| 触发方式 | 场景 | 说明 |
|---|---|---|
| PR opened / synchronize | 常规审查 | 每次代码更新都触发一次评审 |
| PR ready_for_review | 草稿转正式 | 对草稿期间的大量更新做一次集中评审 |
| 定时兜底（每两小时） | 追查遗漏 | 防止 Webhook 漏投或 Actions 偶发失败 |
| 手动 workflow_dispatch | 人工重跑 | 规则更新后，可对历史 PR 重新审查 |
我加定时兜底，是因为有一次遇到 GitHub Actions 的偶发失败，PR 已经被合进去了评审都还没跑。从那以后，我每天定时从仓库里把所有待审 PR 拉一遍，若有没被评审过的，就补一次。这个兜底策略让我踏实了不少。
3. 配置 Hermes 审查规则：提示词、等级划分与仓库白名单
选型定下来之后，真正的重头戏是配置。Hermes 的审查质量，一半取决于模型能力，另一半取决于你给它定的规则模板。
3.1 环境变量与密钥准备
在 workflow 里，我通过环境变量把密钥注入 Hermes：
env: GITHUB_TOKEN: ${{ secrets.HERMES_REVIEW_TOKEN }} LLM_API_KEY: ${{ secrets.LLM_API_KEY }} LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }} LLM_MODEL: deepseek-v3两点提醒：
GITHUB_TOKEN建议单独创建一个机器人账号的 PAT（Personal Access Token），而不是直接用默认的secrets.GITHUB_TOKEN。默认 token 只有当前 workflow 运行所需的临时权限，但它的身份和发起评审的 Actor 容易混淆，审计起来看不清楚。用独立的机器人身份，日志和评论作者一目了然。LLM_API_KEY就是你接入的大模型服务的密钥。Hermes 对模型没有强绑定，我试用下来，DeepSeek-V3 在代码分析场景下的表现不错，且成本比某些海外模型低一个量级，这也是我目前的主力配置。
3.2 规则文件的结构
Hermes 会读取仓库根目录下一个名为.hermes.yml的配置文件。我一开始把它当成“主板上的跳线”，什么都往里塞，结果规则多了以后反而出现误报。后来我重新设计成这套结构：
project: name: my-project language: python review: enabled: true level: strict ignore_files: - "**/lock/*.lock" - "**/generated/**" - "**/migrations/*.py" focus_rules: - id: NULL_CHECK level: error message: "请在解引用前增加空值判断" - id: SECRET_LEAK level: error message: "检测到疑似密钥写入，请改用环境变量或密钥管理服务" - id: SQL_INJECTION level: error message: "请勿直接拼接 SQL，改用参数化查询" - id: LOG_PLACEHOLDER_MISMATCH level: warning message: "日志占位符数量与参数数量不一致" - id: TEST_MISSING level: info message: "建议补充相关测试用例"ignore_files很关键。一开始我不小心把生成的代码和迁移文件也交给 Hermes 审，结果每份都报一堆格式问题，全是噪音。
3.3 给 Hermes 的审查指令模板
规则文件只负责告诉 Hermes“关注什么”，而真正决定评审深度的，是你要给它一段系统提示词。以下是我目前在生产环境里使用的精简模板：
你是仓库的高级代码评审专家。请按照以下原则审查 PR diff： 1. 优先关注可导致崩溃、性能问题、数据损坏、权限越界的问题。 2. 关注并发安全、事务完整性、资源释放等常见生产隐患。 3. 对逻辑改动，检查是否存在遗漏分支和处理不到位的边界情况。 4. 发现问题时，先引用具体代码行，再说明问题，最后给出修改建议。 5. 如果 diff 中没有任何问题，直接返回"LGTM"。 6. 不要对纯粹格式问题进行评论，除非它会导致 bug。 7. 每个问题标注严重等级：error / warning / info。其中有几个重点是反复调优后沉淀下来的：
- “先引用具体代码行，再说明问题，最后给出修改建议”，这能避免模型给出空泛评论，也方便开发者在评论里直接跳转定位。
- “不要对纯粹格式问题进行评论”，这句非常重要。不加这一句，你会发现模型会把单引号双引号的替换、缩进不对齐都翻出来说，评论刷屏，团队直接把机器人拉黑。
- “直接返回 LGTM”是一个减少噪音的手段，防止模型在没问题时硬编两句客套话。
3.4 分级输出：error / warning / info
三级等级，我对应了三类处理方式：
| 等级 | 含义 | 处理方式 |
|---|---|---|
| error | 可能导致崩溃、安全漏洞、数据错误 | 阻塞 PR 合并，必须人工处理 |
| warning | 潜在隐患或设计上的不良倾向 | 建议处理，允许协商 |
| info | 扩充测试、改进注释、代码风格建议 | 不阻塞，开发者自行决定 |
在 CI 阶段，我会判断评论中是否包含 error 级别的标签，如果有就让 PR 检查失败。通过这种方式，Hermes 不再只是“一个提意见的机器人”，而是切切实实地参与了质量门禁。
4. 从提交 PR 到收到评审意见：一次完整审查的实战记录
配置跑通后，我拿一个真实的业务 PR 做了测试。这个 PR 的目标是给订单模块增加一个“取消订单”的接口。改动包括：
- 新增一个 controller 方法
- 修改订单状态枚举
- 增加一个定时任务扫描超时未支付订单并取消
- 补了两个单元测试
4.1 测试 PR 的构造
我故意在代码里留了几个“坑”，想看看 Hermes 能不能找出来：
def cancel_expired_orders(): orders = get_expired_orders() for order in orders: # 故意省略了状态校验 order.status = OrderStatus.CANCELLED order.cancelled_at = datetime.now() order.save()还有一个隐蔽的字符串格式化问题：
logger.info("Order %s cancelled, amount: %s", order.id)第二个%s没有对应的参数。人眼扫过去很容易忽略，但运行时一定会报格式化异常。
4.2 Hermes 的评审全过程拆解
整个流程走下来，几次关键的交互是这样的：
- 开发者 push 代码，触发 workflow。
- Hermes 通过 GitHub API 拿到 PR 元数据和完整 diff。
- 将 diff 按文件拆分，交给大模型按规则分析。
- 生成 JSON 结构的评审意见，通过 API 提交到 PR 页面。
- workflow 判断存在 error 级别问题，设置 check 为失败状态。
提交到 PR 页面的评论大致形如：
## Hermes Code Review 结果 ### error - `order_service.py:42` 在取消订单前未校验订单当前状态，可能把已退款的订单重复置为取消。 建议先查询当前状态，若已处于终态则不执行更新操作，可参考 `cancel_order` 中已有逻辑。 ### warning - `order_scheduler.py:27` 定时任务每次扫描全表，数据量增长后可能造成数据库压力， 建议增加 `created_at < now() - interval '1 day'` 之类的条件，缩小扫描范围。 ### info - 建议为 `cancel_expired_orders` 补充一条测试用例，覆盖“订单已处于退款中”的边界场景。4.3 评审效果：抓到了哪些人工漏掉的问题
整个 PR 在团队内部 review 时，人类 Reviewer 其实只发现了一个空值校验的问题。而 Hermes 发现了三处有价值的点：
- 状态机流转漏洞：订单已经是退款中的情况下，被定时任务再次取消，破坏了业务状态机。这一条是 error，是我故意埋的坑，但它识别出来的深度让我有点意外。
- 日志占位符不匹配：虽然是我故意埋下的，但在日常开发里真的很常见，而且确实很难人工一眼发现。
- 定时任务扫全表的性能隐患：这个我认为是模型根据“定时任务 + 全表处理订单”的上下文推出来的合理建议，不算是 bug 级问题，但确实值得开发者思考。
最让我满意的是，它没有对缩进、引号风格这类格式问题说一句话。规则约束起效了。
5. 跑通后的收尾：权限收敛、成本控制与误报调优
项目跑通只是第一步，真正让这套方案在团队里“活下来”，靠的是后面这三件事。
5.1 权限收敛：只读优先
给机器人账号配置 GitHub 权限时，我一开始图省事给了 write 权限。后来发现机器人虽然不会作恶，但万一 token 泄漏，攻击者拿到一个 write 权限的 PAT 就麻烦了。
我最终的权限方案是：
| 权限 | 配置 |
|---|---|
| Pull requests | Read（必须） |
| Checks | Read（必须） |
| Contents | Read（需要读取 diff） |
| Issues | Read（可选，方便关联 issue） |
原则上，它只需要读代码和提交评论的能力，不需要写分支、改代码、管理仓库的权限。权限做到最小化，心里才踏实。
5.2 Token 成本怎么估算
这是很多团队关心的问题。我把一轮完整 PR 审查的成本拆成两部分：
- 输入 token：主要消耗在 diff 内容上。diff 越大，输入 token 越高。
- 输出 token：评审意见的长度，相比输入可以忽略不计。
以一个改动 200 行代码的中等 PR 为例，diff 序列化后大概 3000~5000 token，加上规则模板和对话上下文，单次调用约 6000~8000 token。按 DeepSeek-V3 的价格折算，一次完整评审的成本在几分钱量级，即使每天跑 200 个 PR，月成本也只是两位数。
如果你觉得成本还是高，可以把review.level切到fast模式，让 Hermes 只看 error 级问题，跳过 warning 和 info 的生成。输出少一半，成本也低不少。但我不建议一上来就这么调——至少在团队信任这个工具之前，让它把潜力发挥出来，大家看到实际效果后再收敛。
5.3 误报调优的三板斧
误报是这类工具最容易被吐槽的点。我们的处理策略分三步：
第一步，收集。每次开发者在 PR 里回复“机器人误报”，我就去后台看一眼。
第二步，归类。误报通常分三类：
| 误报类型 | 典型表现 | 处理方式 |
|---|---|---|
| 上下文缺失 | 模型没读懂整个工程的全局状态 | 补充项目级语境提示词，或把相关上下文也注入 |
| 规则过宽 | 某个规则触发太频繁，绝大多数是无害的 | 收紧规则条件，或直接降级为 info |
| 文件误伤 | 对生成代码、迁移文件做了审查 | 扩充 ignore_files 列表 |
第三步，迭代。把误报率最高的两类问题整理成“不要做什么”的负面清单，加进规则文件中。比如我们的清单里有：
- 不审查 vendor/ 与 node_modules/ 目录
- 不对测试代码里的硬编码字符串提意见
- 不评论已经由 formatter 统一过的代码风格
调了三个版本之后，团队的接受度明显提升了。
5.4 开发者体验：让机器人闭嘴比让它开口更重要
最后这条心得值得每个想引入自动化评审的人记牢：一个高频刷屏的机器人，比不审查更让人反感。
我见过有团队把 AI 评审调得极其激进，每个 PR 评论五十条，开发者打开 PR 先要关评论，再过一会儿直接给机器人账号发 disable。这个工具就废掉了。
所以我建议“评论节奏”上做几个控制：
- 每个文件最多评论 5 条核心问题，宁缺毋滥
- 同一个问题只报一次，不重复刷屏
- 对于格式或风格问题，只在初次提交时提示，后续版本不再纠缠
- 评论里写明这是自动生成，方便开发者甄别
我们的机器人最后一个月的运行数据显示，它的 error 级判断被开发者接受的比例已经从最初的 60% 提升到接近 85%。这不是模型变聪明了，而是规则、文件和提示词这三样东西在持续迭代。
我个人在操作中的一个小习惯是把每周的误报case汇总后发给 Hermes 的审查日志，形成一份周报，轮流发给团队同学过目。有人觉得这多此一举，但正是这个动作，让大家从“排斥一个机器人”转变成了“帮机器人调优”。这种心理上的转变，有时候比技术本身还重要。
如果你也准备在团队里尝试自动化 PR 审查，别一上来就上全套。先挑一个核心仓库，配置好规则，默默跑两周，把误报率降下来，再把机器人正式推向团队。让它在没人注意到的时候把该做的活干好，这比什么都管用。
