最近团队把代码评审的活儿交给了一个自动化工具叫 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、提交新 commitGitHub 就把事件推送到 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-reviewerWebhook URL 填你部署 Hermes 服务的公网地址后面加/webhook路径Webhook secret 填一段随机字符串这个值要记下来后面要填到 Hermes 的配置里Permissions 里设置 Pull requests 为 Read writeIssues 为 Read writeContents 为 Read-onlyChecks 为 Read writeSubscribe 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_ID123456 - GITHUB_PRIVATE_KEY/run/secrets/hermes.pem - WEBHOOK_SECRETyour_webhook_secret - LLM_PROVIDERdeepseek - LLM_API_KEYyour_api_key - LLM_MODELdeepseek-chat - TEMPERATURE0.2 - MAX_CONCURRENCY8 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 fence4.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 是增强型的工具它放大了你本身已经拥有的评审能力而不是凭空产生一个评审专家。如果你正准备在团队里引入自动化代码评审我的建议是选一个体量适中的真实项目先跑两周收集团队成员的真实反馈再逐步从“建议模式”切到“强制门禁模式”。两周下来你大概就能判断这套流程到底适不适合你的团队。反正我们的体验是——一旦用上就再也不想回到纯粹的“全人工评审”时代了。