做开源维护者或者团队技术负责人久了你会发现最消耗精力的往往不是写代码而是审 PR。尤其项目活跃以后每天涌进来的 Pull Request 动辄十几个逐行看 diff 不现实全凭感觉扫一眼又容易漏问题等合并下去出了事故回头定位的成本比当场拦住高出一个数量级。Hermes 这个自动化代码评审工具就是我在这个场景里试了一圈以后留下来的一套解法。它本质上是一个面向 GitHub PR 的智能审查服务能自动拉取变更内容、分析 diff、识别潜在缺陷再把结论以评论、标签或者完整 summary 的形式贴回 PR 页面。对小团队和个人开发者它相当于一个不用休息的 Code Reviewer对开源维护者它能把明显的问题挡在第一道关口让人把精力集中在真正需要判断的地方。这篇文章我会从 Hermes 的设计思路讲起然后给出完整的接入方式、配置要点以及我在真实项目里踩过的坑。如果你只想赶紧用起来可以直接跳到第 3 节照着抄配置文件我也放在那里了。1. 为什么我把 PR 审查交给 Hermes 这个自动化工具1.1 人工评审的四大痛点哪一个戳中了你先说我自己的真实状态。我手上有一个维护了三年的开源项目高峰期一天能有七八个 PR我自己的全职工作还要写业务代码。最早我试图每个 PR 都认真看但坚持两周就撑不住了打开 PR 列表光是扫一遍标题和变更量就需要半小时等真正看进去第一个 PR已经过去一小时后面几个只能象征性点个 approve。这个场景拆开来看人工评审至少有四个绕不开的痛点。第一是耗时。一个稍有规模的 PR涉及十几个文件、几百行改动时完整看一遍需要的时间远超写这段代码的时间。遇到那种改一处逻辑、连带调整了五六个模块的 PR人脑要在文件之间来回切换上下文光是把逻辑关系在脑子里重建一遍就很累。第二是标准不一致。上午你还有精力会认真查空指针、边界条件、并发安全下午开了三个会回来你可能只想快速点个绿。同一个团队里有人是细节控有人是差不多先生同一个代码问题在不同 PR 里得到完全不同的评审反馈挺消磨信任的。第三是上下文断裂。很多问题不是单看 PR 就能发现的。改了数据库索引得知道线上表数据量改了接口返回结构得知道前端有没有依赖旧字段。评审人如果对项目背景不熟看到的只是孤立代码很难发现“代码本身没错但和现状冲突”的问题。第四是安全隐患容易被肉眼放过。硬编码密钥、SQL 拼接、越权接口、依赖版本带已知漏洞……这些在 diff 里往往一行就带过了但靠人眼盯根本盯不住。我后来统计过项目里出过线上事故的地方有一半在 PR 阶段其实已经有明显信号只是没有人注意到。1.2 Hermes 的项目定位不是替代评审人而是做第一道防线我开始找自动化方案的时候市面上不是没有代码扫描工具但它们大多只做静态检查能抓空指针、未定义变量这类问题对“这段业务逻辑对不对”“有没有更好的写法”“测试覆盖够不够”完全无能为力。Hermes 不一样它在设计上就定位成一个智能体Agent不只是跑规则而是真正去“理解”代码变更。具体来说Hermes 会做这么几件事先读取 PR 的完整 diff 和关联文件再把变更放到整个仓库上下文里理解然后模拟一个资深评审者的思路从正确性、安全性、性能、风格、测试完整性等维度逐条过一遍最后生成带具体行号和修改建议的审查结论。所以我对 Hermes 的定位从一开始就非常明确它是第一道防线不是最后一道闸门。它能帮我把 80% 的机械性、确定性问题挡在门外让我只需要关注剩下 20% 真正需要人来判断的架构问题和业务权衡。这个定位很重要因为如果指望它完全替代人工用两天你就会觉得它“不够聪明”然后弃用把它当过滤器它的价值会非常实在。1.3 同类方案对比Hermes 凭什么值得试我实际对比过几个主流方案包括 GitHub 原生内置的 code scanning、老牌的 SonarQube还有后来出现的 CodeRabbit 这类 AI 审查工具。各有各的适用场景但 Hermes 在几个维度上的表现让我决定长期用它。对比维度GitHub Code ScanningSonarQubeCodeRabbitHermes部署方式云端内置自建服务较重云服务支持 Action / CLI / 自托管审查深度静态规则为主静态规则为主大模型理解大模型理解 可编程技能自定义能力有限强但配置复杂支持 prompt 定制规则 Skill 双重扩展误报控制中中高中可训练调校噪音较低接入成本低高低低是否闭源锁定平台锁定开源核心闭源开源可自托管我不是说其他工具不好SonarQube 在规矩严格的团队里依然有价值GitHub 内置扫描也能兜底。但 Hermes 吸引我的是它的“可调教”属性既能用仓库内配置文件定义规则又能针对特定框架写 Skill 技能包还能自由切换底层模型。对一个追求定制化的团队来说这种自由度非常关键。2. Hermes 的核心设计它到底怎么审代码2.1 变更提取与上下文构建Hermes 处理一个 PR 的第一件事是把变更内容完整、精确地提取出来。这一步看起来简单实际很考验工程能力。GitHub 的 PR 本质上是基于 merge-base 的 diff但大 PR、二进制文件变更、文件重命名、行号偏移这些情况处理不好就会让后续分析建立在错误数据上。我自己在用的版本对这类场景处理得比较稳它会优先通过 GitHub API 获取正式 diff再针对大文件做分块处理避免把整个超大文件一次性塞进模型导致上下文溢出。同时它会提取变更文件所属模块的目录结构、相关函数定义、导入关系构建一个结构化的上下文图。这个设计让我印象很深因为多数 AI 审查工具只看 diff 本身而 Hermes 会去看“这个文件在项目里处于什么位置”审查结论明显更贴实际。2.2 大模型驱动的审查建议生成上下文准备好以后Hermes 会把 diff 和上下文组装成一连串审查任务交给底层大模型逐个执行。它默认支持 OpenAI 兼容接口也支持接入 DeepSeek、Qwen 这类国内模型以及通过 Ollama 之类工具跑本地模型。实际操作里不同模型的审查风格差异很大这个我会在后面配置那一节详细说。审查并不是一次性的“总结式”输出而是分步骤的先做变更摘要再按文件逐个分析最后汇总成整体结论。每个文件的分析会包含具体行号、问题类型、严重等级、修复建议。收到这些信息后Hermes 还有一个后处理环节会过滤掉明显重复、与上下文无关的噪音评论并合并同一位置的多条建议。实测下来噪音控制是 AI 审查工具里比较重要的体验指标Hermes 在这块做得不差。2.3 规则引擎与 Skill 技能体系光靠大模型自由发挥结果会有随机性不同 PR 的审查风格不稳定。Hermes 解决这个问题的方式是加了一层规则引擎和技能体系。规则引擎沿用类似 ESLint 的思路你可以在配置里声明“禁止检测到 console.log 时通过”“SSH 私钥文件不得进入仓库”“TODO 注释不得超过 3 个”这类显式规则规则命中后不会被模型讨论直接输出为必须处理的问题。更进阶的是 Skill 技能体系这也是我觉得 Hermes 比较有想象力的部分。一个 Skill 就是针对特定框架或业务的审查知识包例如常见的sql-injection-guard、react-hooks-deps、api-breaking-change-detector。每个 Skill 包含触发条件、检查清单和参考示例Hermes 会识别当前 PR 涉及的技术栈自动加载对应 Skill 参与审查。团队内部也可以沉淀自己的 Skill把踩过的坑固化成自动检查项这是纯人工评审做不到的积累方式。2.4 可配置的审查范围与严重级别同一个仓库里不同路径的代码重要程度完全不同。核心模块的改动需要严格审查文档和示例代码随便看看就行。Hermes 配置里支持paths和ignore_paths做路径级策略也支持按严重级别设置 PR 状态。例如我会在配置里规定review_policy: paths: src/core: severity_threshold: error required_modules: [security, performance, compatibility] docs: severity_threshold: warning skip_review: true tests: severity_threshold: info check_only: true这样核心目录的 PR 一旦出现 error 级问题Hermes 会通过 GitHub 的 commit status 阻止合并需要配合分支保护规则文档改动则干脆跳过避免浪费模型调用额度。精确控制审查范围不仅是为了质量也是在控制成本——大模型 API 按 token 计费无意义的全量审查会烧掉不少预算。3. 实战把 Hermes 接入 GitHub 仓库的完整流程3.1 前置准备仓库、权限与模型 Key接入前需要准备四样东西一个 GitHub 仓库、一个具有写入权限的 Personal Access Token、一个模型 API Key以及仓库的 CI 执行环境。如果只是个人项目体验GitHub 免费额度足够跑 Action如果是公司私有仓库需要确认 Runner 能正常访问模型 API 的地址。Token 的权限范围按最小化原则配置只需要repo读写权限和pull_requests: write权限不要用最高权限的 token 跑到生产环境里。在仓库设置的Secrets and variables Actions里添加HERMES_GITHUB_TOKEN和OPENAI_API_KEY如果接 DeepSeek 就配置DEEPSEEK_API_KEY名称取决于你用的模型服务。有一点要提醒不要把 Token 直接写进 workflow 文件。哪怕仓库是私有的workflow 日志也有泄露风险统一走 Secrets 是比较稳的做法。3.2 用 GitHub Actions 一键接入 Hermes最快的方式是用别人已经封装好的 Hermes GitHub Action。在仓库根目录创建.github/workflows/hermes-review.ymlname: Hermes PR Review on: pull_request: types: [opened, synchronize, ready_for_review] pull_request_review_comment: types: [created] jobs: hermes-review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write issues: write steps: - name: Checkout uses: actions/checkoutv4 - name: Run Hermes Review uses: your-registry/hermes-actionv1 with: github_token: ${{ secrets.HERMES_GITHUB_TOKEN }} model_api_key: ${{ secrets.DEEPSEEK_API_KEY }} model: deepseek-chat config_path: .hermes.yml几个配置项的实际意义types指定在 PR 创建、内容更新、转为 ready 时触发审查permissions的pull-requests: write是必须的否则 Hermes 无法创建审查评论model用来切换底层模型示例里用的是 DeepSeek 的 chat 模型你也可以换成其他兼容接口。第一次推上去后随便开一个测试 PR正常情况下几十秒内 Hermes 就会在 PR 下面回复一条审查 summary。等得久多半是 model 接口响应慢可以调整超时配置。3.3 配置文件详解审查规则、路径过滤与输出格式Hermes 的核心配置放在.hermes.yml里我维护的那个仓库经过多轮调校最终长这样version: 1.0 model: provider: deepseek name: deepseek-chat temperature: 0.3 max_tokens: 4000 review: languages: [python, javascript, typescript, go] ignore_paths: - *.lock - node_modules/** - dist/** - *.min.js severity_labels: error: ❌ 必须修复 warning: ⚠️ 建议修改 info: 可优化 rules: - pattern: console\\.log level: warning message: 不要在生产代码中保留 console.log请使用统一日志方案。 - pattern: (api[_-]?key|secret|token)\\s*\\s*[\][^\][\] level: error message: 疑似硬编码敏感信息请改用环境变量。 - pattern: TODO|FIXME level: info message: 存在未处理标记请确认是否遗留。temperature我建议设置到 0.2~0.4 之间。设置太高模型输出飘审查结论时好时坏太低则缺乏灵活性面对非常规写法容易误报。ignore_paths一定要配否则每次 PR 都会把package-lock.json这种上千行的文件喂给模型既慢又费 token。输出格式这里有个容易被忽略的细节Hermes 可以同时输出 review comment 和 commit status。在 GitHub 上review comment 是给人看的但真正能“卡住合并”的是 commit status。你需要配合分支保护规则把 Hermes 生成的 status check 设为 required。这样只要 Hermes 给出 error 级问题PR 的 Merge 按钮会被 GitHub 自动置灰从流程上保证问题必须被处理。3.4 本地 CLI 调试不 push 也能跑改配置的时候如果每次都推到 GitHub 触发 Action效率太低了。Hermes 提供本地 CLI 模式可以先在本地验证配置效果再上 CI。安装方式很直接curl -sSL https://get.hermes.example.com/install.sh | bash本地跑审查需要配置环境变量export HERMES_GITHUB_TOKENghp_xxx export DEEPSEEK_API_KEYsk-xxx hermes review --pr 123 --config .hermes.yml它会把这次审查结果输出到终端同时生成一份hermes-report.json内容包含问题列表、对应文件行号、置信度、修复建议。我会先看这份 JSON 里的误报比例再决定要不要调整规则。比如我第一次启用正则规则时api这个词在英文注释里频繁命中后来加上了边界匹配才消停。个人体会本地调试模式是 Hermes 在工程化上做得比较贴心的设计。审查工具不像编译器它在改动配置后的行为变化不容易预测能在本地快速跑一轮调试成本会低很多。3.5 让审查结果真正被团队采纳工具接入不难难的是让团队真正用起来。一开始我直接把 Hermes 全量接入结果三天后被同事抱怨“机器人话太多了刷屏”。后来我调整了策略效果好了不少。第一个调整是分级放量。先用一周观察模式Hermes 只发评论、不设门禁让大家感受它的输出质量等大家对它的建议习以为常了再把 error 级问题设成卡点。第二个调整是建立反馈通道同事觉得某条评论是误报可以在评论下回复/skip或/dismissHermes 支持按指令忽略同位置的后续评论。第三个调整是把审查范围按目录收敛核心模块卡严格非核心模块只提示不拦截。事实证明优先照顾人的体验工具才能融进流程否则再强的能力也会被抵制。4. 高频问题排查与避坑实录4.1 Action 跑不起来权限、超时与 Auth 报错接入第一天大概率会碰到问题。最常见的 Action 报错是权限不足Resource not accessible by integration。这不是 Hermes 的问题是你忘了在 workflow 里加permissions: pull-requests: write或者 GitHub Token 作用域设置不对。真正排查思路是这样的先在本地用同样的 token 调一次 GitHub API确认 token 有效再看 workflow 的permissions节点是否声明了写权限最后看仓库 Settings 里有没有把 Action 的权限级别限制成 read-only。顺着这条链查几分钟就能定位。另一个常见现象是 Action 运行时间超过一小时被 GitHub 杀掉。大 PR 加上模型响应慢很容易超时。我的解决办法是把审查拆到不同 job 并行一个 job 跑静态规则、一个 job 跑模型分析最后汇总。实际效果是整体时间从四十多分钟降到十几分钟体验提升明显。4.2 审查噪音太大怎么调教 HermesAI 审查工具最劝退人的就是误报。印象比较深的一次Hermes 在某个 PR 里连续给了 14 条评论我逐条看下来真正有价值的只有 2 条剩下都是无伤大雅的“建议改成单例模式”“这个变量可以更短”之类同事当场表示要把机器人关掉。后来我总结了一套调校方法。先看hermes-report.json里的置信度字段把低于阈值的直接过滤掉。再针对反复误报的同类问题写豁免规则比如项目里约定使用any类型的地方就在配置里声明豁免。最后给每条评论设置分级把风格类建议降级为 info只有正确性和安全问题才升级为 error。三连操作之后有效评论率从不到 20% 提到了 60% 以上。还有一个思路在 prompt 层面约束模型的语气和关注点。你可以自定义 Hermes 的 system prompt明确写“不要啰嗦、不要给泛泛的建议、只关注会导致功能错误或维护困难的问题”模型输出会明显收敛很多。模型本身是可调的不要怕调 prompt 和温度参数。4.3 大型 PR 超时或上下文截断代码库大了以后一个 PR 改 30 个文件很正常但大模型的上下文窗口有限不可能把全部变更一次性塞进去。Hermes 的分块策略虽然能解决大部分情况但某些互相调用的核心模块同时改动时分析结果还是会显得“只见树木不见森林”。我的处理办法是在流程层做拆分要求团队尽量把大 PR 拆成多个独立合并单元每个 PR 的变更量控制在 400 行 diff 以内。这个约束一开始靠人肉沟通后来写进了 CONTRIBUTING 文档并且配置了一个检查 jobPR 变更量超过阈值就自动警告。效果是所有工具的审查质量都提升了不只是 Hermes人工评审压力也小了很多。工具倒逼流程改进这一点是我没预料到的收获。4.4 本地 merge 冲突后Hermes 的审查如何衔接热知识CI 里的审查基于 push 的代码而不是你在本地合并后的结果。所以当你的 PR 因为主分支更新产生冲突时Hermes 审查的是旧代码结论可能已经失真。Git 里 PR 被插队导致的冲突处理步骤其实很标准先同步最新主分支再 rebase 自己的分支解决冲突后 force push。此时 workflow 的synchronize事件会触发新一轮审查Hermes 会根据新代码重新生成 summary并保留上一轮评论的上下文。需要留意的是rebased 之后行号基本都对不上旧评论里引用的位置可能是错的。我习惯在做完 rebase 后在 PR 里手动回复一条hermes re-review指令强制触发一次全量重审而不是依赖增量更新。这个细节在协作频繁的项目里很实用。4.5 多语言项目适配与私有大模型接入团队项目往往多语言并存前端 TS、后端 Go、脚本 Python 混在一个仓库里。Hermes 的默认提示词对主流语言覆盖得不错但一些冷门语言或内部框架的审查质量明显偏低。解决办法是给不同语言配独立的 Skill 或提示词例如 Python 项目重点查 GIL 误用和类型注解Go 项目重点查错误处理和并发安全。私有大模型这块我试过用本地 Ollama 跑小型模型效果一般14B 以下的小模型做代码审查能看出明显的“智力不足”。如果要自托管建议至少用 70B 级别的量化模型或者直接走 DeepSeek 这类 API性价比和效果平衡得比较好。从我实测看模型选择对审查质量的权重非常大值得花时间调。最后再说一个容易被忽视的点Hermes 审查和公司代码合规的关系。如果公司对代码外发给第三方模型有合规要求记得选私有化部署或者与供应商签订数据协议的方案或者直接接公司内网模型网关。建议在接入前和合规、安全团队确认一遍别等功能上线了再被叫停。我在实际项目里用了大半年 Hermes最直观的感受是它没有让我变成一个不用看代码的“甩手掌柜”但确实把我从大量重复性的、低价值的检查工作里解放出来了。现在我审 PR 的效率大概比以前快出一倍而且因为有一道机器防线在前面挡着我反而更能静下心来看那些真正需要人来判断的设计问题。如果你也在被 PR 评审的琐碎消耗不妨按上面的流程试一次。我觉得工具这东西用不用是一回事值不值得用试两周就有答案了。