做了几年开源项目维护GitHub 上最磨人的事情其实不是写代码而是 PR 评审。每天一打开仓库十几条 Pull Request 挂在那边有的等了三四天还没人看有的是改了一个单词也要占一个评审位。人工评审的时间被切得稀碎标准还经常前后不一致——同一个问题周一我说要改周五我可能就放过了。这种状态下靠“人肉”去盯每一行代码根本就不现实。后来我搭了一套基于 Hermes 智能体的自动化代码评审体系专门用来处理 GitHub 上 PR 的第一轮审查把那些琐碎、重复、看一眼就能判定的问题全部拦在机器人这一层效果比预期好得多。这篇文章就把这套东西从设计思路、部署流程到参数调优完整记录下来给同样被 PR 折腾到头秃的朋友一个参考。Hermes 这个智能体现在是国内开发者圈子讨论热度比较高的方案之一它可以对接 DeepSeek 等大语言模型做推理也有比较灵活的技能扩展机制。我这里说的 Hermes GitHub PR 审查实际上就是让 Hermes 扮演一个“独立评审员”监听仓库的 PR 事件拉取 diff多维度逐行审查然后把意见以评论和 review 的形式回写到 GitHub 上。整个流程全自动不需要人盯着。这套体系适合个人维护者、三五个人的小团队也适合开源项目里想给维护者减负的贡献者——尤其是那些代码审查资源严重不足的场景。在动手搭之前我需要先把整体思路掰开说清楚因为它决定了后面每一步选型的方向。1. 项目整体设计和思路拆解1.1 为什么要让智能体去干 PR 审查我统计过自己维护的几个仓库PR 从提交到获得第一条有效评审意见的平均等待时间大概在 9 到 22 小时之间周五晚上提交的 PR 甚至要拖到下周。这还只是“获得意见”离真正合入还有好几轮来回。人工评审最核心的问题不是“水平不够”而是“时间碎片化”——维护者不可能随时在线每次评审都像重新捡起上下文一样费力。PR 审查这个场景天然适合自动化。原因有三点第一大量评论指向的问题是低层次的比如缺少错误处理、硬编码了密钥、空指针风险、格式不统一这类问题有一套相对固定的判断标准第二PR 的 diff 是可量化的输入模型可以直接基于变更内容做单点分析不需要理解整个项目的历历在目第三评审意见可以被结构化机器可以先用规则筛一遍再让模型聚焦处理那些真正需要理解的逻辑问题。我最初也试过直接用静态检查工具但静态工具能查的只有类型错误、明显 bug 这一类对于“这个函数处理异常分支不够健壮”“这个改动会破坏调用方的什么假设”这种需要语义理解的问题传统工具无能为力。而 Hermes 接上大模型之后可以结合上下文做推理判断颗粒度完全不是一个级别。1.2 为什么选 Hermes 而不是现成 CI 工具团队里不缺少代码评审工具SonarQube 可以长期跑质量门禁GitHub 自带 code review 功能还有人用 GitHub Actions 里的现成 action 接 OpenAI 做审查。但这些方案都有一些让我不愿意继续用的短板。SonarQube 的重心在“持续质量度量”配置复杂规则要一条条调新仓库接入成本高GitHub Copilot 的代码审查虽然方便但它是闭源黑盒提示词的调节余地很有限审查规则没法跟自己的工程标准绑定。而 Hermes 的灵活性在于它提供了一个智能体框架事件监听、工具调用、模型切换都是模块化的。我可以让 Hermes 自己动手抓 diff、跑测试命令、读取相关文件上下文然后把所有结果汇总成一个结构化评审再回写到 PR 里。整套逻辑我可以自己改、自己控制规则粒度也方便接入团队的内部规范。方案选型上我实际对比过三条路线最后选了 Hermes方案自定义规则难度多模型支持事件驱动二次开发成本GitHub Actions 官方大模型 action中受限部分支持低独立写脚本调 API 回写评论高支持需要自己实现中Hermes 智能体框架低支持完整支持低用 Hermes 还有一个很实际的原因它天然支持多个底层模型我可以把不同的审查任务分给不同的模型跑而不是把全部压力压在一个大模型上——这个点后面讲参数配置的时候会展开。2. 核心功能与审查逻辑解析2.1 PR 从触发到回写的完整闭环Hermes 接入 GitHub 之后一个 PR 从提交到获得审查意见走的是一条完整的自动化链路。这条链路的重要节点包括GitHub 把pull_request事件通过 Webhook 推送到 Hermes 服务Hermes 先校验请求签名确认消息确实来自 GitHub避免伪造请求根据 PR 状态做分流只有opened、synchronize和ready_for_review这几个动作才需要触发审查draft状态的 PR 直接跳过Hermes 调用 GitHub API 拉取 PR 的 diff 数据同时读取基础分支和目标分支的上下文按变更文件的类型和规模分发任务先跑规则引擎再跑模型推理所有结果汇总成结构化的评审意见按严重程度分好级调用 GitHub API 创建 review把意见写到对应代码行的评论里生成一份摘要更新到 PR 的描述下面方便移动端快速浏览。整个流程最核心的设计原则有两条第一Hermes 只有“读”权限绝不能直接改代码、推分支它只负责评论和建议第二每一步都要有日志和可重试机制调用第三方模型失败时不能影响到已有的 PR 状态。在部署上我强烈建议把 Hermes 放进隔离环境里跑不跟业务代码部署在一起。这个思路跟日常做服务隔离是一样的评审服务的稳定性不能受业务发布影响。2.2 审查维度与分级机制这套自动审查不是简单的“有错就喷”而是分了四个严重级别因为如果机器每条问题都嚷嚷最终的结果就是开发者直接屏蔽机器人所有意见全部沦为噪音。级别标签含义触发示例P0 阻塞必须修改可能导致线上故障或数据丢失空指针、SQL 注入、密钥泄露P1 严重建议修改明显 bug 或边界错误处理缺失数组越界、事务未提交、类型误用P2 建议可以改可读性、命名、异常处理完善变量命名混乱、缺少防御性判断P3 琐碎可不改风格层面缩进、注释格式P0 级别的问题会触发 Hermes 给 PR 打上request changes状态其他级别只评论不阻塞。实测下来这个策略非常关键。最早我让机器人什么都说结果一个 PR 下面堆 30 多条评论开发者的耐心一周就被磨光了。后来改成只对真正严重的问题阻塞合入琐碎问题合并到一条汇总评论里一下子整个流程就顺了。2.3 规则引擎与提示词设计审查的“判断力”来自两层一层是可编程的硬规则另一层是模型的软推理。硬规则用代码就能写比如正则匹配api_key、password这类可疑硬编码软推理靠提示词引导模型去发现逻辑层面的问题。我给 Hermes 设计的审查提示词大概长这样已脱敏你是本仓库的资深代码评审专家。请针对以下 diff 做渐进式审查不要输出客套话。 审查关注点 1. 是否正确处理了异常和边界条件 2. 是否引入安全风险注入、敏感信息泄露、越权 3. 是否可能破坏既有调用方函数签名、返回类型变化 4. 并发场景下是否有竞态风险 5. 错误信息是否有价值是否暴露了内部实现细节 输出要求 - 每条意见必须包含文件路径、起始行号、结束行号、严重级别P0/P1/P2/P3、问题描述、修改建议 - 按严重级别从高到低排序 - JSON 格式输出这里有一个很重要的设计细节必须让模型输出 JSON 而不是自然语言。因为只有结构化的输出才能被后续的逻辑稳定解析才能自动化地映射到 GitHub review 的对应行评论也才能做后续的统计和规则反馈。第一次跑的时候我没在意让模型自由发挥结果意见倒是写了不少解析程序根本没法稳定消化后来全部改成 JSON 才解决。3. 环境准备与部署实操3.1 部署方案选型与前期准备这部分是目前大家在社区里问得最多的尤其是“在 Windows 上怎么部署比较合适”。我先说结论如果你的环境是 Windows最省心的路径是装 Docker Desktop用 WSL 2 作为后端然后在容器里跑 Hermes。容器方案的好处是依赖全隔离Python 版本、包依赖、配置文件都不会污染你本机的开发环境。前期需要准备的东西有四样一台能跑 Docker 的机器Windows 10/11 专业版或家庭版都行关键是开启 CPU 虚拟化一个 GitHub 账号以及一个你想接入的测试仓库一个 DeepSeek 开放平台的 API Key用来做模型推理Hermes 也支持本地模型但对电脑配置要求很高个人玩家建议先用 API一个回调地址让 GitHub 能把 Webhook 消息推到 Hermes 所在的服务上。如果你本机不想开 Docker也可以直接用 Python 虚拟环境跑 Hermes 源码这种方式适合调试但后续维护成本高一些。两者对比如下对比项Docker 部署源码部署环境隔离好一般升级更新镜像替换即可需要处理依赖冲突调试验证稍麻烦方便适合场景长期稳定运行本地开发调试3.2 Windows 系统上完整部署流程第一步先把 WSL 2 跑起来。在 PowerShell管理员模式里执行wsl --install装完重启系统执行wsl --set-default-version 2确认版本。这里容易踩坑的点是很多人装完 WSL 忘了进一次 Ubuntu 初始化用户Docker Desktop 会一直提示找不到默认发行版。第二步装 Docker Desktop。安装时勾选“Use WSL 2 based engine”装好后在 Settings → Resources → WSL Integration 里打开你要用的发行版集成。第三步把 Hermes 的部署仓库拉下来。我个人推荐直接用官方提供的 docker-compose 配置文件来管理因为后续改配置、重启服务都很方便。git clone https://github.com/hermes-agent/hermes.git cd hermes cp .env.example .env第四步编辑.env文件填写关键配置项# 模型服务配置 DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx HERMES_MODELdeepseek-chat # GitHub App 配置 GITHUB_APP_ID123456 GITHUB_PRIVATE_KEY_PATH/app/private-key.pem GITHUB_WEBHOOK_SECRETyour_webhook_secret第五步启动服务docker-compose up -d跑起来之后可以用docker-compose logs -f hermes观察日志看到Webhook server started on port 8080之类的内容就说明服务起来了。如果用的是源码方式部署安装依赖后直接python main.py即可前提是.env里的环境变量都配好了。这一步我踩过的最大的坑是 Webhook 端口被 Windows 防火墙挡住。服务明明起来了GitHub 那边一直报 “We couldnt deliver this payload”后来发现是入站规则没有放行 8080 端口。这个排查起来很费时间建议部署完先确认端口能被公网访问到。3.3 GitHub App 接入与权限配置要让 Hermes 能读写 PR 评论需要创建一个自己的 GitHub App而不是直接用个人 Token。GitHub App 的权限粒度更细也支持以应用身份进行代码审查这样评论里展示的是 bot 身份不会跟个人账号混在一起。创建路径GitHub 右上角 Settings → Developer settings → GitHub Apps → New GitHub App。需要注意的配置项Webhook URL填 Hermes 服务的回调地址例如https://review.example.com/webhookWebhook Secret随便生成一串随机字符串同时填到.env的GITHUB_WEBHOOK_SECRET里Permissions至少需要Pull requests: Read Write、Checks: Read Write、Contents: ReadSubscribe to events勾选Pull request和Pull request review。创建完成后GitHub 会生成一个 App ID 和私钥。私钥要下载下来放到 Hermes 能访问到的路径同时把路径配置到.env的GITHUB_PRIVATE_KEY_PATH里。最后一步是把 App 安装到你要审查的仓库上。在 App 的 Settings 页面选 Install App然后选择目标仓库。装完之后建议先在测试仓库提交一个改动很小的 PR验证一下 Hermes 能不能正常评论。我自己的习惯是先在私有仓库灰度跑一周再放到公开仓库上去。4. 参数配置与效果调优4.1 模型选型与成本控制Hermes 支持对接多种模型我在实际使用中会区分任务来调配而不是一股脑全用最强的模型。原因很简单最强模型虽然理解力更高但成本和时延也成比例上涨。对于一个每天几十条 PR 的仓库来说全部走大模型token 消耗会很快失控。我的配置策略是这样的任务类型推荐模型原因琐碎问题过滤deepseek-chat 的轻量档速度快、成本低逻辑推理与安全审查deepseek-chat 较高档理解能力强判断准确规则引擎兜底无模型纯代码不消耗 tokenHermes 在配置文件里支持按 skill 维度设置模型这里我强烈建议你把“格式检查”和“逻辑检查”拆成两个 skill分别绑定不同档位的模型。我在实际运营中把硬规则检查全部转移到规则引擎去跑模型重点做安全风险和逻辑正确性的判断token 成本直接降了 50% 以上。另一个控制成本的办法是设置“审查阈值”。Hermes 支持只在 PR 变更行数或文件数超过设定值时才触发深度审查小改动只跑快速检查。比如改造500行以内的 PR 只做规则引擎检查超过500行才调用模型做全文深度分析。这个阈值可以按仓库的实际体量调整。4.2 审查粒度与触发策略审查不是越频繁越好。如果每个 commit 都触发一次完整审查大家的 PR 会被评论刷屏模型配额也会被浪费。我采用的触发策略是PR 从 draft 转为 ready 时触发第一次完整审查PR 有新的 commit 推送时只对增量代码做增量审查不重复评论已经存在的问题超过 7 天的旧 PR 不主动触发避免无意义消耗。增量审查的实现依赖 Hermes 的 diff 追踪能力。它会把上一次审查的 commit SHA 记录在内部存储里下次只拿新的 diff 作为输入。对于问题重复评论的问题我给 Hermes 加了一层去重逻辑如果相同文件相同行号已经存在未解决的评论就直接跳过不再重复评论。这里还有一个比较实用的配置按文件类型下发不同的审查规则。比如.go文件重点看错误处理和并发安全.sql文件重点看事务边界.ts文件重点看类型是否符合约束。规则引擎会先做一轮文件分类再调用对应的 skill。这样模型的分析目标更聚焦输出质量会比“所有文件一把抓”稳定很多。4.3 反馈闭环与规则沉淀自动化评审最大的问题是它会“共情疲劳”——同一个模型服务跑久了可能会对某些类型的问题视而不见或者对某些风格反复误报。解决办法是建立反馈闭环当开发者在 PR 评论里回复“误报”或者对某条建议点了 “Resolve”Hermes 会把这条反馈记录到本地日志里后续通过规则调整把误报率压下来。我自己会在每周抽一点时间看 Hermes 生成的统计报告重点关注两个指标每条 P0/P1 意见的准确率以及评论被开发者直接 mark as resolved 的占比。如果发现某个规则频繁误报就把它从硬规则里移除或者给模型补充更明确的反例。这套“数据反馈 人工校准”的闭环跑了大概三周之后审查结果的可用性有了非常明显的提升。5. 常见问题与排查技巧实录5.1 部署和接入常用问题速查表这里整理了我自己实际操作中遇到的典型问题以及对应的排查思路可以直接对照处理现象可能原因排查方法GitHub 报 webhook 投递失败端口未开放、回调地址无法访问检查防火墙、用 curl 测试回调地址PR 提交后没有收到任何评论Webhook 未订阅 pull_request 事件登录 GitHub App 后台检查 Subscribe to events评论出现但内容为空模型返回非预期格式查看 Hermes 日志检查模型返回的原始内容同一个问题被评论多次缺少去重逻辑确认 commit 增量追踪是否开启P0 阻塞级别意见过多提示词里的严重级别定义不够清晰调整提示词增加“仅真实可复现风险才算 P0”约束API 调用回报率受限触发了平台频控检查模型并发数设置调低审查并发5.2 日志排查思路与灰度策略日志是排查一切问题的基础。Hermes 的日志默认走 stdoutDocker 部署下用docker-compose logs -f hermes就能实时看。建议把日志级别调到INFO级别先跑一段这个级别能看到关键流程节点Webhook 收到、diff 拉取成功、模型返回、评论写入。生产环境再调到WARNING以上。有一个非常值得提醒的点不要在刚接入的时候就把规则全部打开更不要直接对主分支的每个 PR 都发起 request changes。我见过有人一开始就把机器人的权重拉得很高结果一个 PR 被打回五六次开发者直接举报机器人是垃圾。最好的方式是先用“article 评论模式”跑一周只提建议不打回观察准确率上来之后再逐步开放阻塞级别。另外一个我踩过的坑是私钥配置错误导致评论写不进去。原因是 GitHub App 的私钥需要 PEM 格式我在.env里填的是路径而不是私钥内容本身导致 Hermes 找不到文件。这个细节极其隐蔽因为前面的 Webhook 监听都是正常的唯独写评论的时候报 401。后来我查了 Hermes 的 issue 列表才发现是常见问题。6. 实际运营中的体会这套 Hermes GitHub PR 审查方案上线一个多月我最大的体会是它不是用来替代人类评审的而是用来“保底”的。有了它兜底至少最基础的错误不会漏进主干评审者的精力可以集中在真正需要人脑理解的架构和设计问题上。它确实能让我从那些低水平的 “加个空指针判断”“密钥别硬编码” 的重复劳动里解放出来。最后分享一个我从多次调参中得出的建议不要急着追求“全自动通过”。自动化评审的价值不在于它帮你做了多少决定而在于它帮你筛掉了多少低质量问题。先把规则写得严一点把模型判断放在评论模式观察一周看看误报率再决定哪些级别可以自动阻塞合入。这一套流程跑顺之后就会发现 PR 队列真的不再那么让人焦虑了。