最近团队把代码评审的活儿交给了一个自动化工具，叫 Hermes。一开始只是抱着试试看的心态，想着能帮我们少点重复劳动，结果跑了一段时间，这玩意儿确实把 GitHub 上的 PR 审查流程捋顺了不少。今天就把我们接入 Hermes 做自动化代码评审的整个过程、踩过的坑、调优的思路，一次性讲清楚。
先说结论：如果你是团队里负责代码质量、或者经常被 PR 淹没的人，Hermes 这类基于大语言模型的自动化评审工具，绝对值得花一个下午去试。它解决的核心问题很朴素——代码审查里那些“低级错误”“风格不一致”“明显逻辑漏洞”，不应该再消耗资深工程师的精力，应该让机器先过滤一遍，人只需要看机器筛出来的真问题。
1. 项目概述与整体设计思路
1.1 为什么要把 PR 审查交给自动化
代码评审是软件工程里绕不开的一环，但它也是出了名的耗时。我见过太多团队，PR 一多，评审就开始走过场：看一眼 diff 有没有冲突，点个 approve，完事。真正的问题——边界条件没处理、异常路径没覆盖、新代码破坏了既有接口——往往要等合并上线、线上报警了才被发现。
自动化代码评审想解决的，不是替代人类评审员，而是把人类从“逐行读代码”这种低效劳动里解放出来。机器擅长什么？擅长在大量代码里找模式、对比规范、识别常见的 bug 套路。人类擅长什么？擅长判断业务合理性、评估架构影响、权衡技术债。所以合理的分工是：机器先审一遍，把“疑似问题”标出来，人再带着上下文去审查，效率和质量都能上一个台阶。
我们用 Hermes 跑了一段时间后发现，它的价值不只是“找出 Bug”，更重要的是“强制统一了评审标准”。以前不同 reviewer 的偏好差异很大，有人只关心逻辑，有人非要抠命名，现在机器用同一套规则审每一份 PR，风格一致性明显变好了。
1.2 方案选型：为什么是 Hermes 而不是自己写脚本
做 PR 自动化审查，市面上其实有几条路可走。一条是自己写脚本调 GitHub API，拉 diff、跑静态检查工具、把结果怼回 PR 评论里。这条路的问题在于：静态检查工具（比如 ESLint、Pylint、Checkstyle）能查风格和低级错误，但查不了“逻辑层”的问题，更理解不了代码的意图。
另一条路是直接用 GitHub Copilot 这类商业产品。它确实能辅助评审，但基本逻辑是“基于整个文件上下文做建议”，不是专门为 PR Review 设计的，而且和自家团队的规范、CI 流程打通起来并不灵活。
我们最后选了 Hermes，核心原因有三个。第一，它是一个可自主配置的多智能体框架，不绑定任何特定模型，可以对接 DeepSeek、GPT、本地模型等，灵活度很高。第二，它能直接以 GitHub App 的身份接入仓库，监听 PR 事件并自动评论，不需要额外维护一堆对接脚本。第三，社区版本开源免费，部署在自己服务器上，代码数据不出内网，这对很多公司来说是刚需。
提示：如果你所在团队对数据安全要求极严，代码不允许出内网，Hermes 这类可以私有化部署的方案会是你为数不多可选的路。
1.3 整体架构：Hermes 是如何“看懂”一份 PR 的
要理解 Hermes 怎么审查 PR，得先看它的运作链路。整个流程可以拆成五步：
- GitHub 仓库配置了 Hermes 对应的 Webhook，一旦有人创建 PR、更新 PR、提交新 commit，GitHub 就把事件推送到 Hermes 服务。
- Hermes 收到事件后，通过 GitHub API 拉取 PR 的元数据、改动文件列表、每个文件的 diff，以及相关的 issue 和 commit 信息。
- 服务把 diff 和审查规则打包成 Prompt，发送给后端大语言模型。模型对每一段改动进行推理，输出“可能的问题点 + 改进建议”。
- Hermes 把模型输出的结构化结果，转化成 GitHub Review Comment，精准地贴在对应代码行上。
- 同时在 PR 的明细位置生成一份汇总报告，列出问题等级、文件分布、建议数量等。
这套架构并不复杂，但每一步都有细节要抠。比如第 2 步，拉取 diff 的时候如果 PR 特别大，GitHub API 有文件数量限制，就得走分页或者搞增量对比；第 3 步，Prompt 的构建决定了模型输出的质量，这不是简单把 diff 怼给模型就完事的。
2. 核心细节解析与实操要点
2.1 PR 审查的五个关键维度
Hermes 真正跑起来之后，我把它输出的审查结果做了归纳，它能力范围内做得比较靠谱的，大致是以下五个维度。
格式与风格一致性。这是最基础的一层。缩进是不是统一、命名是不是符合团队规范、import 有没有排序、有没有残留的 debug 代码。这类问题不需要很高智商，以前的 Lint 工具也能干，但 Hermes 做得更好的地方在于，它能理解上下文。比如“这个变量名叫 data，在这个函数里其实存的是用户列表，不如叫 users”，这种建议 Lint 工具给不出来。
潜在 Bug 与边界条件。这是最有价值的一层。空指针、数组越界、类型不一致、未处理的 null、并发问题。模型经过海量代码训练，对这类常见 bug 模式非常敏感。有一次我们的 Go 服务里有人写了if err != nil { return }但漏掉了真正要返回的 error 值，Hermes 一眼就标了出来，这种低级错误人工评审时非常容易漏掉。
安全漏洞筛查。SQL 注入、XSS、硬编码的密钥、使用不安全的加密算法、依赖版本带已知漏洞。这层特别适合自动化，因为安全知识更新快，靠人记根本不现实。Hermes 配合好的 Prompt，能直接引用 OWASP 的检查清单做判断。
测试覆盖与契约破坏。新增了一个函数，有没有配套的单测？改了一个核心接口的返回值，下游调用方会不会挂？这类问题 Hermes 也能给出初步判断。它会看 diff 里新增的代码和已有的测试文件，判断测试是否匹配。虽然达不到人工评估那么精确，但足够提醒开发者“你是不是忘了改调用方”。
可读性与维护性。函数太长、重复代码、复杂度太高、魔法数字遍布。Hermes 能基于 diff 范围内的情况给出重构建议，甚至在某些场景下能直接给出改进后的代码片段。
2.2 Hermes 审查服务的关键配置
部署 Hermes 不难，难在把参数调对。我整理几个我们实际使用后觉得最重要的配置项：
模型选择和 temperature。我们使用了 DeepSeek 的 API 作为默认推理后端，性价比很高。temperature 建议设低一点，我们用的是 0.2。代码评审需要的是稳定、保守的判断，不需要模型发挥创造力。要是跑偏了，一顿发散思维，会觉得每一行代码都有问题。
并发数与速率限制。Hermes 在批量处理 PR 时会同时发起多个推理请求，如果团队活跃、PR 多，务必注意模型 API 的速率限制。我们在 yaml 里设置了最大并发数和排队队列长度，宁可让评审消息迟到，也不能因为超频被模型服务商限流，导致所有 PR 都没人审。
增量审查与全量审查的切换。有些场景需要全量审，比如新项目第一次接入，希望把所有历史代码过一遍。但日常的 PR 审查，一定要改成仅审查本次变更的 diff。全量审查不仅浪费 token，而且会让模型陷入大量无关代码中，注意力被分散，反而忽略真正的改动问题。
路径过滤规则。不是所有文件都需要同等强度的审查。我们配置了 include_paths 和 exclude_paths，比如 vendor、lock 文件、生成代码目录统统排除。不然每次 PR 光 lock 文件变更就能刷一堆噪音评论。
2.3 关于 PR 中的版本标记：时间轴上的 v1 和 a1
在讲实操之前，顺便解答一个很多刚开始用 GitHub 的人会疑惑的点：为什么 PR 页面的时间轴上，有时候会看到 commit 前面标着 v1、a1 这类前缀？
这是仓库配置了自动化版本标记后的产物。一些流水线工具（比如 semantic-release、changesets）会在 PR 合并时自动生成版本号，并在提交记录上打 tag，比如 v1.0.0、v1.1.0 表示发布版本，a1、b1 这类可能是内测版本或特定环境的构建标记。它不是 PR 审查工具本身的功能，但和自动化评审有联动关系——当 Hermes 看到标注了 a1 这种预发布版本时，会知道这是给测试环境的，审查时会更关注兼容性和回滚风险；相反，标注了 v1 这种正式版本，审查时则会更严格地检查破坏性变更。
如果你在 PR 时间轴看到了这些标记，不用慌，说明仓库的发布流程已经自动化了，这是好事。
3. 实操过程与核心环节实现
3.1 从零接入：创建 GitHub App 并授权仓库
要让 Hermes 能自动看 PR、发评论，官方推荐的接入方式是通过 GitHub App，而不是个人访问令牌。原因很简单：GitHub App 的权限是细粒度的，可以只授权 Pull requests 的读写权限，而且身份独立、不会依赖某个人的账号，人员离职了服务也不会挂。
创建过程大致如下：进入 GitHub 的 Settings -> Developer settings -> GitHub Apps，点击 New GitHub App。关键配置有这么几项：
- GitHub App name 填一个独特的名字，比如
hermes-reviewer； - Webhook URL 填你部署 Hermes 服务的公网地址，后面加
/webhook路径； - Webhook secret 填一段随机字符串，这个值要记下来，后面要填到 Hermes 的配置里；
- Permissions 里设置 Pull requests 为 Read & write，Issues 为 Read & write，Contents 为 Read-only，Checks 为 Read & write；
- Subscribe to events 里勾选 Pull request 和 Pull request review。
创建完成之后，GitHub 会给你生成一个 App ID，并让你下载一份私钥文件（pem 格式）。这两个东西就是 Hermes 以应用身份访问 GitHub API 的凭证，建议放进密钥管理服务里，不要直接写在代码仓库的配置文件里。
然后到仓库的 Settings -> GitHub Apps 里，把刚创建的这个 App 安装到需要审查的仓库上，按需选择 All repositories 或 Only select repositories。
3.2 部署 Hermes 审查服务
部署方式官方推荐 Docker。我们团队的情况是服务器在内网，有一台配置还不错的 GPU 机器，所以顺便把本地模型也跑了。如果是小团队、只审公开仓库，直接用 Docker 装一个服务端，对接云端模型 API 是最省事的方式。
一个简化版的 docker-compose 服务配置大概是这样的：
version: "3.8" services: hermes: image: hermes-agent:latest container_name: hermes-reviewer environment: - GITHUB_APP_ID=123456 - GITHUB_PRIVATE_KEY=/run/secrets/hermes.pem - WEBHOOK_SECRET=your_webhook_secret - LLM_PROVIDER=deepseek - LLM_API_KEY=your_api_key - LLM_MODEL=deepseek-chat - TEMPERATURE=0.2 - MAX_CONCURRENCY=8 volumes: - ./config:/app/config - ./secrets:/run/secrets ports: - "8080:8080" restart: unless-stopped配置文件方面，核心是 config 目录下的review-rules.yaml，我们最初按下面的模板起步的：
rules: - name: security severity: critical checks: - hardcoded_secrets - sql_injection - unsafe_deserialization - name: bug_risks severity: warning checks: - nil_dereference - off_by_one - incorrect_error_handling - name: style severity: suggestion checks: - naming_convention - import_sorting启动服务后，记得确认 Webhook 能正常收到事件。最简单的办法是在 GitHub App 的 Advanced 页面手动 Deliver 一个测试事件，然后看 Hermes 的日志有没有对应的记录。
3.3 让 Hermes 真正“懂”你的团队规范
这一步是拉大差距的关键。默认配置下 Hermes 的审查确实是“能用”的，但如果想让审查结果贴合团队自身规范，必须花心思写指令和规则。
我们团队总结了几类非常管用的自定义手段：
代码规范描述。把团队的编码规范文档提炼成要点，写进配置文件。比如“Go 的错误处理必须以if err != nil开头，禁止忽略返回值”“Python 类型注解必须完整”这类。Hermes 会把这些规则内化到评审逻辑里，效果比让模型自己猜规范好得多。
禁止模式库。把历史上出现过的严重事故代码抽象成模式，写进黑名单。比如“不允许在支付模块使用float作为金额类型”“所有对外 API 必须有 rate limiting”。Hermes 看到类似的模式会直接标 critical。
自定义审查指令。这一块直接替换掉 Hermes 默认的 system prompt 模板。我们会注入一段固定格式的指令，大意是：你是一名经验丰富的资深工程师，请从正确性、安全性、可维护性三个维度审查 diff，每个问题必须标注所在行、严重级别、问题描述以及修改建议，没有把握的问题不要提，避免噪声。
Prompt 的质量直接决定审查效果。我见过有人直接把整个 diff 丢给模型，结果模型把每行代码都夸了一遍，什么有效建议都没出来。后来我们把指令改成了“只输出问题，不输出废话”，效果立竿见影。
3.4 审查结果长什么样
跑完一次 PR 审查后，Hermes 会在 PR 页面留下两种东西：一种是行级评论，直接贴在有问题的那行代码下方；另一种是 PR 顶部的汇总报告。
行级评论的格式大概是：
[warning] 潜在的并发访问问题 line 42: 这里对 sharedCache 的读写没有加锁，在并发场景下可能导致数据竞争。 建议：使用 sync.RWMutex 保护，或改用 atomic 操作。汇总报告里包括文件维度的问题分布、问题总数、严重级别的统计，以及一条总结性的结论，比如“本次变更整体质量良好，存在 2 个 warning 级问题，建议处理后再合并”。
这里给个忠告：不要指望它 100% 准确，它的价值在于“提醒”。实际使用中，真问题和误报的比例大概在 7:3 到 8:2 之间，已经远超我对自动工具的预期了。剩下那 20% 的误报，通过规则调优会逐渐降下来。
4. 常见问题与排查技巧实录
4.1 典型故障速查表
我们在用 Hermes 的过程中，碰到过好几类问题，整理成了一张速查表，方便你排查时对号入座。
| 现象 | 可能原因 | 排查思路 |
|---|---|---|
| PR 没有触发审查 | Webhook 没收到事件 | 在 GitHub App 的 Advanced 页面发送测试事件，查看 Hermes 日志 |
| 收到 401/403 错误 | 私钥无效或 App 权限不足 | 检查 pem 文件是否匹配 App ID，核对仓库授权范围 |
| API 报 429 限流 | 并发数设置过高 | 调低 MAX_CONCURRENCY，确认模型服务商的速率限制 |
| 审查结果全是重复建议 | Prompt 里缺少“避免重复”的约束 | 在指令里明确要求：与已有评论重复的问题不要再次提出 |
| 大 PR 超时无响应 | diff 过大超出模型上下文限制 | 开启增量审查，或将超大 PR 分割成多个小 PR |
| 评论乱码或格式丢失 | 特殊符号转义问题 | 检查 Hermes 的 Markdown 渲染配置，对代码块使用 code fence |
4.2 误报治理：怎么让 Hermes 越用越“懂行”
误报是自动评审工具天然带的毛病，不可能完全消除，但可以通过三个手段持续挤压压缩。
加白名单。对于确认没问题的文件、目录、代码模式，直接加白。我们曾经有一段时间，每次生成的 API client 代码文件都会被 Hermes 报一堆风格问题，后来把*/generated/*整个丢进了白名单，瞬间清净了。
细化规则等级。把拿不准的规则优先设置为 suggestion 而不是 warning。比如命名建议这类偏主观的判断，让它以“建议”的形式出现，而不是妨碍合并的 warning。团队成员长期使用下来，对 suggestion 类评论脱敏，反而更重视 critical 和 warning 的问题。
人工反馈闭环。这是最重要的一条：每当开发者在 PR 里手动驳回了一条机器评论（比如回复“误报，不影响功能”），我们都鼓励他反馈给 Hermes 的规则配置。我们对拒绝频率高的规则定期复盘，该改 Prompt 的改 Prompt，该降级的降级。两个月调下来，误报率降了至少一半。
4.3 网络环境的合规优化
做 GitHub 相关开发的人，多少都会遇到访问不稳定、API 响应慢的问题。但我们不会建议你用任何非正规渠道，这既不符合安全规范，也可能带来不必要的风险。合规的做法主要有几种：
配置靠谱的网络代理环境。如果你的办公网络能访问境外资源，直接在部署 Hermes 的机器上配置 HTTPS 代理环境变量，这是正常的 IT 操作，问题不大。
使用 GitHub 官方支持的加速节点或镜像。GitHub 自身在部分区域部署了 CDN 节点，通过调整 DNS 解析让请求走最近的节点，也能有效降低延迟。
私有化部署配套的镜像缓存。把依赖、base 镜像提前同步到内网仓库，构建和拉取过程就不需要频繁访问外网。
自建 Git 镜像仓库。把主仓库定时同步到内网的 Git 服务，Hermes 审查时直接跑本地数据，速度飞快，而且代码不会出内网。这是数据合规团队最喜欢的方式。
只要网络问题不拖后腿，Hermes 的整体运行稳定性和回复速度会有质的提升。
5. 扩展方向与后续优化建议
5.1 与 CI/CD、RPA 冒烟测试的联动
Hermes 做 PR 审查只是自动化质量门禁的一环，真正让它在团队里扎根下来的，是和我们 CI/CD 流水线的联动。
现在的流程是：开发者提交 PR -> Hermes 自动评审并输出结果 -> 如果 critical 级别的问题为 0，继续跑既有的自动化测试 -> 测试通过后，自动触发一个冒烟测试环境部署 -> RPA 脚本在测试环境上做一轮冒烟验证 -> 全部通过，才允许人工合并。这一套下来，人工真正要做的事只有两件：写代码，然后确认 Hermes 的评审结果没有误报，点合并。
这里我展开说说 RPA 冒烟测试的联动。很多团队有 UI 层面的自动化测试脚本，但触发时机通常在 nightly 或者手工，没法和 PR 合并流程打通。Hermes 可以把 PR 的 head 分支部署到临时环境，然后调用 RPA 脚本跑几个核心流程。我们其中一条支付链路的冒烟测试就是这样接进来的，每次有人改动支付相关代码，临时环境里会自动走一遍“发起付款 -> 回调 -> 查询结果”的核心流程，一旦失败，PR 直接打回。
这种方式最大的价值是：很多问题在代码层面看起来没问题，跑起来才发现接口字段对不上、环境配置缺失。而这些是纯静态的 PR 审查发现不了的。
5.2 后续可以扩展的方向
如果你们团队的评审体系已经跑顺了，以下几个方向值得继续深入。
多模型策略。不要让单一模型包办所有审查。我们现在的配置是：默认用 DeepSeek 做通用逻辑审查，安全相关规则单独交给一个安全垂直模型或规则引擎，风格类规则继续用轻量级模型。成本更低，效果反而更好。
评审历史数据库。把 Hermes 每次审查的问题都存下来，定期分析。比如“最近 30 天哪类问题出现得最多？集中在哪些文件？”这些数据对团队的技术债治理、培训选题很有价值。我们内部已经用这套数据做了一次全团队的错误模式分享，反响很好。
结合静态分析工具。Hermes 的 LLM 推理能力再强，也不如专用静态分析工具在特定领域精准。两条腿走路更稳：SonarQube 抓代码异味和坏味道，Hermes 负责逻辑漏洞和业务耦合问题，两边结果互相补充，再合并到同一个 PR 评论里。
5.3 我的真实使用感受
最后说几句个人体会。接入 Hermes 之前，我们团队每周平均要花大概 12 个小时做人工 PR 评审。接入三个月后，这个数字降到了 4 个小时左右，而且剩下的时间全部花在讨论真正有价值的问题上。
但我也要泼一盆冷水：不要把 Hermes 想象成一个“全自动化评审机器”，它是一个需要持续调教和信任培养的工具。刚开始跑的时候，团队成员普遍怀疑机器评论的可靠性，有人甚至会忽略它提出的 critical 问题，结果线上真的出过一次事故，事故现场和 Hermes 提醒的一模一样。从那以后，大家对待机器评论的态度才从“看看就好”变成“必须点开读一读”。
另外，配置 Hermes 的人一定要懂代码评审本身，而不是只懂部署。一个没有代码评审经验的人，很难写出高质量的规则和 Prompt。换句话说，Hermes 是增强型的工具，它放大了你本身已经拥有的评审能力，而不是凭空产生一个评审专家。
如果你正准备在团队里引入自动化代码评审，我的建议是：选一个体量适中的真实项目先跑两周，收集团队成员的真实反馈，再逐步从“建议模式”切到“强制门禁模式”。两周下来你大概就能判断这套流程到底适不适合你的团队。反正我们的体验是——一旦用上，就再也不想回到纯粹的“全人工评审”时代了。
