那个周四下午我们主分支上的一个bug直接引爆了线上告警。追查下来问题不在测试覆盖而在三天前一条被合入的PR——负责审查的同事当时正在开另一个会用手机扫了一遍diff留下一句LGTM刷新页面就去忙别的了。这个场景在多少团队里反复上演PR堆积到两位数reviewer在上下文切换里耗尽精力反倒是那些最不起眼的低级错误最容易从眼皮底下溜过去。后来我把评审流程的第一步交给了Hermes让自动化代码评审来当第一道哨兵。这篇文章记录了我以Hermes为核心搭建GitHub PR自动化审查体系的完整过程从部署方式、配置细节、规则编写到拿真实PR跑了几轮之后的复盘和反思。如果你也想在自己的团队里做一套类似的自动化评审那这篇内容应该能帮你少踩几个坑。1. 为什么我要把PR审查交给一个智能体1.1 人工评审的三大死穴漏看、拖延、标准漂移先说漏看。一个reviewer切到你的PR时脑子里还装着上一个任务的状态平均要花很长时间才能进入状态然后盯着diff看注意力最多集中十几分钟就开始下滑。人一旦疲劳最典型的动作就是只看新增代码、不看删除代码忽略import变更、忽略配置文件的微小改动。那些一眼扫过去完全正常的改动往往就是事故的第一步。再说拖延。PR一多reviewer会本能地往后排因为每个人手头都有更急切的任务。但评审这件事最伤人的地方在于它拖得越久上下文丢失得就越多。等reviewer终于点开PR时可能连当初为什么这么改都忘了。我们团队最夸张的一次一个PR从提交到合入等了整整36个小时而实际代码改动只有20行。最后是标准漂移。不同人对代码风格、错误处理、日志规范的容忍度完全不同。同一个团队里有人会为一行console.log重新打回有人对所有TODO都睁一只眼闭一只眼。甚至同一个人周一严得不行周五下午就只想快点收工。这种随机性直接导致代码库质量参差不齐。引入Hermes做自动化代码评审并不是要取代这些人工reviewer。我的想法很简单让机器先把那些有明确对错、但需要有语义理解能力才能判断的问题过滤一遍把人的精力留给真正需要判断力的问题。算是给评审流程加一道预处理工序。1.2 自动化评审的边界它替代不了谁这是我最想强调的一点。自动化代码评审听起来很诱人但它有自己的能力边界。它可以做的是检查diff里是否出现明显的隐患验证代码风格是否和团队规范一致核对提交信息格式检查是否忘了同步某个配置文件甚至跨文件判断某个接口改动是否影响了其他调用方。这些任务的特点是规则清晰、反馈明确、重复性高恰好是机器擅长的。它做不了的架构层面的取舍、产品语义的权衡、对历史代码的为什么这么写的深入挖掘。这种判断往往需要长时间的项目背景和业务上下文LLM很难凭空推理出来。所以我把这道自动化评审定位成第一道哨兵它的职责是把明显的问题提前暴露出来降低人工reviewer的基础认知负担。真正的评审决策权还是在人手里。它和CI/CD插件的逻辑也不一样CI查的是能不能跑而PR审查关注的是该不该这么写、有没有写错方向这两件事恰好能互补。2. Hermes的审查逻辑它不是普通的机器人评论2.1 定位LLM、静态扫描、规则引擎组成的三层架构一开始我也以为Hermes就是一个套了ChatGPT壳的PR机器人后来翻它的设计文档才发现它把审查能力拆成了三层每层管一件事。第一层是静态扫描。它不依赖任何大模型用正则、AST、文件路径规则去做精确匹配。比如禁止在main分支上直接push禁止提交包含console.log的代码禁止出现硬编码密码这类规则用静态扫描就能稳定命中。这层的特点是快、便宜、没有任何幻觉。第二层是LLM语义分析。它处理的是静态扫描够不到的问题比如这个SQL查询在循环里执行是否会造成N1问题这个异常吞掉之后调用方会不会傻等超时。这类问题需要读懂代码的意图、了解调用上下文传统工具做不了纯靠人看效率又低。第三层是规则引擎。它负责编排上面两层的输出决定哪些内容该以评论形式发到PR里、按什么级别排序、重复内容怎么折叠、置信度不足的意见要不要直接过滤掉。这套三层结构解决了一个纯LLM方案最让人头疼的问题——幻觉。模型再强也会一本正经地胡说八道。而静态扫描提供的是100%可复现的确定性结果它像是一个严格的把关人把LLM的输出框在一个可信范围内。规则引擎再根据置信度阀值决定是否外发整体准确率会稳定很多。2.2 一次PR审查请求的完整路径我梳理一下一个PR从提交到Hermes评论上墙的完整链路看完你就能明白它的工作方式。GitHub收到PR事件后通过Webhook推送到Hermes服务Hermes先去GitHub API拉取这个PR的元数据、diff文件、commit message、以及关联的issue信息接着静态扫描器在几秒内跑完规则集LLM则并行读取变更文件和相关引用文件做语义分析规则引擎汇总两层结果去重、排序、计算置信度过滤掉低质量意见最后通过GitHub App的身份把最终意见以评论形式写到PR下方。关键点在于第2步拉数据的范围判断。Hermes不是把整个仓库的代码都喂给LLM的它会优先分析变更文件本身再按需拉取变更文件引用的外部模块。这既控制了token消耗也避免了被无关代码干扰。我们在实际使用时如果仓库过大或依赖关系复杂这部分仍然需要人为调优后面在成本和性能那一节详细讲。2.3 为什么被称作智能体而不是CI插件我最初的理解是Hermes就是一个比较聪明的评论机器人但用了几周之后才慢慢体会出它和普通插件的本质区别。CI插件是事件驱动的一次性脚本。事件进来脚本跑完输出结果结束。它没有状态、没有目标、不能根据中间结果调整下一步动作。而Hermes这类智能体具备目标-计划-执行-修正的行为闭环。它可以自主拆分审查目标先分析diff结构如果发现某个改动涉及一个公共函数它不会直接给出武断结论而是会先去检索这个公共函数的定义、调用方把上下文补全后再回来生成最终意见。这种发现疑问、去查上下文、再回来验证的循环才是它与传统静态分析工具最核心的差别。换句话说普通插件只会回答你这里有什么问题而Hermes会自己想办法确认这里到底是不是问题哪怕需要在多个文件之间来回穿梭。这对审查场景来说价值巨大因为很多问题是跨文件的只看单文件diff永远发现不了。3. 部署到真实技术栈环境准备与配置拆解3.1 三种部署方式与我的选择我在部署Hermes时试了三种方式先说明结论正式环境用Linux Docker Compose最省心Windows本机调试用WSL2快速试验时直接用Python虚拟环境跑。Linux Docker Compose是官方最推荐的路径把Hermes服务、依赖中间件全部编排在一个compose文件里一条docker compose up -d就能拉起来。好处是隔离性好、重启快也方便配合CI跑冒烟测试。Windows下的开发者不用绕路装好WSL2之后在Ubuntu子系统里跑Docker即可网络映射和文件共享都正常。开发模式我推荐直接在Python venv里跑。安装依赖后用环境变量指定GitHub App的私钥路径和Webhook地址进程起来就能调试比每次改代码都要重建镜像快得多。我把这三种方式的适用场景整理成下面的表部署方式适用场景优点需要注意的点Docker Compose正式服务隔离性好、一键启动、便于扩缩容需要单独配置持久化目录WSL2 DockerWindows 日常开发对 Windows 开发者友好文件互通方便磁盘 IO 跨文件系统时偏慢Python venv本地快速验证、二次开发启动快断点调试方便依赖环境易被污染不适合生产注意不管选哪种方式都要保证运行环境可以正常访问GitHub API和Webhook回调地址。3.2 核心配置文件逐项拆解Hermes的配置集中在config.yaml里我拿一份自己调整过的配置片段来说明server: host: 0.0.0.0 port: 8787 github: app_id: 123456 private_key_path: /etc/hermes/hermes-app.pem webhook_secret: your-secret-here events: - pull_request - issue_comment engine: static_scan: true llm: provider: openai_compatible model: deepseek-chat temperature: 0.2 max_tokens: 2048 rules: - rulesets/*.yaml review: max_comments: 20 min_confidence: 0.7 ignore_paths: - *.lock - dist/** label_on_review: bot/reviewed逐项解释一下关键字段。server部分不用多讲唯一要注意host别只绑127.0.0.1不然GitHub的Webhook根本打不进来。github.app_id和private_key_path是GitHub App的凭证这些信息在创建App的时候会拿到私钥只会下载一次务必保存好。webhook_secret是用来验证Webhook请求合法性的绝对不要泄漏。engine.llm这里我评估后选用了deepseek-chat实测下来在中文技术理解、与Python代码分析的组合表现上比较稳定。temperature我固定调低到0.2希望输出更保守尽量避免天马行空的建议。max_tokens控制在2048因为每轮评论文本不需要太长限制长度能防止模型话痨。review.max_comments20是一个防刷屏保护。默认情况下Hermes能发现很多问题但如果全部刷到PR上效果适得其反。调整为只显示最重要的20条会倒逼规则引擎做更好的排序。min_confidence0.7的意思小于这个置信度的意见直接丢弃这和误报率直接相关调太低全是噪声调太高又会漏报需要根据团队实际效果慢慢校准。ignore_paths用来忽略不想审查的文件比如lockfile、dist目录。已经生成的代码、第三方代码没必要让模型去评判。label_on_review表示审查完成后自动打个标签方便按标签筛选已审查的PR。3.3 接入GitHub的权限清单与Webhook配置Hermes要读写PR内容、写评论、读issue它的身份需要通过GitHub App创建。到GitHub组织或个人账户的设置页面创建一个新的GitHub App然后把权限按最小必要原则配置权限点级别用途Pull requestsRead write读取PR diff、提交审查意见、写PR评论ChecksRead write在PR状态栏显示checks结果IssuesRead读取关联issue里的上下文ContentsRead读取仓库内容用于跨文件影响分析Webhook事件我只订阅了pull_request和issue_comment两个。前者覆盖PR的打开、更新、合入等生命周期后者可以在评论里用命令触发重新审查比如/system review。创建好App之后把私钥下载下来、填写对应的App ID和Webhook Secret。把Webhook地址配置到公网可访问的HTTPS地址上路径指向Hermes的/webhook端点。如果服务在内网需要通过你团队自己的网关或内网穿透设施把这个地址放出来确保GitHub能请求到。部署稳定之前我踩过一个坑Webhook配好了但没在GitHub App的Permissions里给Pull requests开启write权限导致Hermes能拉取diff却写不了评论。这个问题很难排查因为日志里只显示403。建议配好权限后先用一个测试仓库、一个test PR验证全链路再放开到正式项目。4. 让审查标准真正落地规则与提示词工程4.1 三个审查维度Hermes的规则集不是零散的禁止XX而是围绕三个维度组织的。第一个维度是diff的静态检查。它直接作用于变更内容比如新增的logger是否带了类名、是否遗留了调试输出、是否把敏感信息写进日志、错误分支是否有return兜底。这些规则简单明确适合写成确定性规则。第二个维度是提交信息语义。很多团队规范要求提交信息遵循Conventional Commits但人手动检查很容易漏。Hermes会结合diff上下文判断如果提交信息写的是fix但改动实际是feat它会指出这种不一致。这个维度是我用下来意外觉得有价值的地方因为提交信息不规范会直接影响生成changelog的自动化。第三个维度是跨文件影响。单纯的静态扫描看不到文件A修改的接口被文件B调用时是否受影响而Hermes的LLM层可以做到粗粒度的跨文件分析。它会先识别变更的公共接口再去检索可能的调用方判断是否存在破坏性变更。4.2 自定义规则的三种写法写自定义规则是让Hermes真正贴合团队规范的关键。我按使用频率排一下自己接触到的三种写法。第一种是纯正则在rulesets目录下定义一个yaml规则。比如- name: 禁止裸用logger type: pattern pattern: logger\\.(info|error)\\s*\\( message: 请使用LoggerFactory.getLogger(Class)创建带类名的logger便于链路追踪。 severity: warning这种最简单适合拦截代码模式但因为是字符串或正则匹配对上下文理解有限容易误伤只适合高度固定的模式。第二种是路径与文件规则。按文件路径、扩展名或目录白名单黑名单来决定是否应用某条规则。比如自动化测试目录里禁止出现sleep调用生产代码里禁止出现测试专用的mock标记。第三种是函数级规则用Python脚本自定义检查逻辑。这是我最推荐的因为它能结合AST做语法级分析理解代码结构。比如检查一个函数里是否出现超过两层的循环嵌套或者检查同一个session在一个请求里是否重复创建连接。这种规则需要一定的开发能力但做出来之后效果也最稳定。4.3 提示词里必须交代的五件事Hermes的默认提示词能解决通用问题但到了真实团队你需要把团队的个性信息注入进去。按我的经验提示词里至少要交代这五件事。第一是技术栈与框架背景。告诉它项目用Spring Boot还是FastAPIORM用的是什么MQ用什么这些会直接影响它能否准确识别技术风险。第二是输出格式和评论风格。我要求每条评论都以问题摘要 所在文件行号 改进建议 置信度的结构输出并附上简短的推理依据。格式统一了开发者扫评论的速度会快很多也便于后续统计分析。第三是置信度阈值的行为说明。让模型在不确定时不硬给建议而是明确标注需要人工确认避免造成误报轰炸。第四是忽略清单。比如自动生成的代码目录、vendor目录、协议缓冲文件在提示词里显式声明这些位置不需要审查可以明显减少无效意见。第五是安全边界。明确告诉它不需要对不存在的问题勇于提醒更不要自己去脑补一个最佳实践强行输出。模型的想象力一旦放开评论质量灾难性地下降。提示词写好之后不是一劳永逸的我建议跟随规则集一起放在Git仓库里管理每次调整都走版本控制否则你根本不知道哪一轮的评论质量变化是改提示词导致的。5. 真实案例复盘一次PR从提交到合入5.1 这个PR的背景与改动概况我拿一个内部的订单系统来举例。这个项目是Python后端使用FastAPI数据库走PostgreSQL。当时的PR是新增超时关闭订单的后台任务改动涉及一个新增的定时任务模块、订单状态枚举里新增了一个字段、一个数据库查询条件的调整、以及一处配置项的修改。PR提交之后Hermes在几分钟内自动跑完审查在PR下方留下了8条评论其中5条被开发者认为有价值2条属于规范建议还有1条是误报。下面几条比较有代表性我逐一拆解。第一条是静态扫描命中的在定时任务模块里代码直接用了threading.Timer来实现周期性任务而项目其他部分统一使用的是Celery。这条的表述是建议检查此处是否应使用Celery Beat替代手工线程定时器当前模块与全项目后台任务框架不一致后续维护成本较高。静态扫描实际上不认识Celery它是先识别出threading.Timer这个危险模式再由LLM结合仓库上下文补出了项目里其他地方用的是Celery这个信息。这条命中得很准。第二条来自跨文件分析新增的订单状态ORDER_TIMEOUT_CLOSED没有同步到前端状态映射文件。Hermes在分析PR时发现后端枚举增加了值又检索引用了该枚举的JS常量文件发现那边没有新增。如果不是跨文件检索这个遗漏完全看不出来。5.2 值得商榷的一条索引问题的质疑另一条评论的内容是在超时查询中使用的statePAID条件建议确认是否存在对应索引否则大表全表扫描风险较高。这条本身说得没错但开发者看到第一反应是这个条件已经走了索引啊被制裁了吧。这就要看Hermes是怎么得出这个结论的。我后来去查了日志发现的逻辑是这样的Hermes在分析时读取了当前变更的SQL查询语句然后试图去库里找索引定义但它默认只搜索当前PR涉及变更的文件而那个表的索引定义在另一个子模块里当时的检出环境中没有检索到该子模块的索引定义文件所以给了低置信度的提示。这个问题的本质不是模型能力不行而是数据获取边界不完整。5.3 完整排查链路从误报到必须人工兜底我完整复盘一下这条疑似误报的排查链路这比结果本身更有价值。第一步先复现猜测。看到评论后我先让开发者去数据库确认索引是否真的存在结果发现确实存在。第二步定位为什么Hermes没看到。打开Hermes日志查看针对该PR的分析上下文文件列表发现它压根没有读取索引定义所在的子模块。第三步追根因。问题出在子模块的检出方式仓库用的是monorepo里的子模块局部检出但Hermes没有跑到该子模块的索引定义文件。这不是规则配置的问题而是数据拉取策略的问题。第四步修复与验证。我在配置里给Hermes加了索引定义路径白名单让它遇到查询类分析时强制去指定路径下检索相关语句。调整后再提交一个同类PR这条评论就不再出现了。这个例子恰恰说明自动化评审永远需要人工兜底。你不该指望它每个结论都正确但你可以通过它的错误持续优化规则和检索策略让误报率一点点降下来。5.4 合入后的效果与开发者反馈这个PR最终在当天下午就完成了合入。开发者对自动化审查的实际感受是先被机器人挑了一遍刺再见到人工reviewer的时候整个人都轻松了。因为他们知道那些low-hanging fruit已经被扫过一轮真正的review时间可以用来讨论设计和潜在风险。从这个案例我获得的一个明确结论是自动化评审最大的价值不在抓出多少大问题而在于把团队从机械性的低水平评审中解放出来。人的注意力是稀缺资源让模型去跑重复的、确定性的检查把人的精力集中到那些需要多年经验才能看出的问题上这套协作模式的收益是实打实的。6. 用了三个月的实话质量、成本与团队流程6.1 用三个指标衡量自动化评审的好坏市面上很多团队接入自动化评审后只看机器人找到了多少个问题这个指标其实最容易被刷成漂亮的假数据。我建议用三个指标评估命中率、误报率、漏报率。命中率指已发出的评论中被开发者采纳或确认的比例误报率指发出的评论中被开发者明确否决的比例漏报率指人工reviewer发现的、但自动化评审没有发现的问题占比。我们三个月的统计命中率大约在55%到65%之间其中静态规则贡献的确定性意见命中率接近95%而LLM产生的开放性问题命中率只有40%左右。误报率在15%到20%。漏报率没有一个精确的数字但明显集中在跨服务调用链和深层业务语义上。单独看40%这个数字会觉得很低但如果把这40%拆开看其中一部分是当前不需要改动但值得关注的建议开发者愿意花时间了解这种我认为也算有效价值。总的结论是自动化评审适合做保底不适合做绝对权威。6.2 token成本与响应耗时的真实数据成本是每个想上自动化评审的团队都会关心的问题。拿我们的订单仓库来说平均每个PR涉及300到600行diff单次完整审查大约消耗10K到30K token按当前常用模型的定价单个PR的智能体推理成本不到1元人民币可以忽略不计。但要注意一个问题大仓库、高PR密度的团队成本会线性增长。如果一天有50个PR那一个月的token消耗就会非常可观。所以控制token的方式很重要。我的建议是只让Hermes分析变更文件和关键引用文件不要全仓无脑喂。同时设定单次审查的上限值超出部分走简化模式只跑静态扫描不做LLM深度分析避免被超大PR拖垮。响应耗时方面静态扫描基本秒级完成LLM分析则要40到90秒。整体来看一个PR从提交到看到机器人评论中位数在1分钟左右。这个速度已经可以让开发者在提交后先去处理其他事回来就能看到结果。6.3 团队落地时的流程设计建议最后整理几个我踩坑之后觉得值得注意的流程设计建议。先把自动化评审放在前置环节。我建议把它挂在PR提交后的第一步而不是等人工reviewer已经看过一遍之后再补刀。再把评论分级。我给Hermes的评论分了三个级别error、warning、suggestion。error会直接让PR的检查状态标记为失败warning只是提醒suggestion是可选优化。这样开发者可以按级别优先处理不会被一屏评论淹没。建立反馈闭环。我们每周会花15分钟处理一条原则凡是被开发者标记为误报的评论都要去写一条理由并反馈到Hermes的规则库里要么改提示词、要么调规则、要么加忽略路径。随着规则库迭代误报率确实是持续走低的这种每周微调的投入产出比很高。还有一个容易忽略的问题告诉团队机器人不是权威它的每条评论都有被挑战的权利。开发者完全可以回一条这个建议不适用因为...然后合入。团队需要建立这种质疑文化否则开发时效会被一堆低价值建议拖累。如果让我重来一次我不会一开始就跑默认策略。我会先花一个星期把团队过去三个月里的code review记录手工过一遍把最高频、最有共识的问题提炼成规则集再让Hermes基于这套规则启动。这样部署下去的第一天它输出的意见就是贴合团队现状的不需要经历漫长的边用边调阵痛期。这个准备工作听起来花时间实际上比临时调提示词高效得多。