那个周四下午，我们主分支上的一个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查询在循环里执行，是否会造成N+1问题""这个异常吞掉之后，调用方会不会傻等超时"。这类问题需要读懂代码的意图、了解调用上下文，传统工具做不了，纯靠人看效率又低。
第三层是规则引擎。它负责编排上面两层的输出，决定哪些内容该以评论形式发到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 + Docker | Windows 日常开发 | 对 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_comments=20是一个防刷屏保护。默认情况下，Hermes能发现很多问题，但如果全部刷到PR上，效果适得其反。调整为"只显示最重要的20条"，会倒逼规则引擎做更好的排序。min_confidence=0.7的意思小于这个置信度的意见直接丢弃，这和误报率直接相关，调太低全是噪声，调太高又会漏报，需要根据团队实际效果慢慢校准。
ignore_paths用来忽略不想审查的文件，比如lockfile、dist目录。已经生成的代码、第三方代码没必要让模型去评判。label_on_review表示审查完成后自动打个标签，方便按标签筛选已审查的PR。
3.3 接入GitHub的权限清单与Webhook配置
Hermes要读写PR内容、写评论、读issue，它的身份需要通过GitHub App创建。到GitHub组织或个人账户的设置页面，创建一个新的GitHub App，然后把权限按最小必要原则配置：
| 权限点 | 级别 | 用途 |
|---|---|---|
| Pull requests | Read & write | 读取PR diff、提交审查意见、写PR评论 |
| Checks | Read & write | 在PR状态栏显示checks结果 |
| Issues | Read | 读取关联issue里的上下文 |
| Contents | Read | 读取仓库内容，用于跨文件影响分析 |
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还是FastAPI，ORM用的是什么，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 值得商榷的一条：索引问题的质疑
另一条评论的内容是："在超时查询中使用的state='PAID'条件，建议确认是否存在对应索引，否则大表全表扫描风险较高。"
这条本身说得没错，但开发者看到第一反应是："这个条件已经走了索引啊，被制裁了吧。"这就要看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基于这套规则启动。这样部署下去的第一天，它输出的意见就是贴合团队现状的，不需要经历漫长的"边用边调"阵痛期。这个准备工作听起来花时间，实际上比临时调提示词高效得多。
