1. 从一个看似“费时间”的需求说起代码评审这件事做过几年开发的人基本都有复杂情绪。一方面PRPull Request评审确实是保证代码质量的重要关卡很多线上事故往前追溯都能看到评审环节的遗漏另一方面评审又极其耗时尤其当团队规模上来之后每天几十个 PR每个 PR 改动几百行人肉逐行看完根本不现实。我自己就见过不少团队评审流于形式reviewer 点个 approve 就算完事问题全留给测试和生产环境去暴露。这个项目的出发点很简单把 PR 评审环节里那些重复、机械、可标准化的部分交给一个自动化代理去做人的精力只留给真正需要判断力和业务上下文的地方。我们用的载体是 Hermes——一个可以承接多步骤任务、能灵活编排工具调用的智能体框架。Hermes 在这里不是单纯调一次大模型接口而是像一个 junior reviewer 一样拉取 PR 信息、分析改动文件、按规则检查、给出结构化意见最后把结果贴回 PR 评论区。这篇文章适合谁看如果你是团队里负责工程质量、想给研发流程提效的工程师或者你正在研究怎么把大模型能力真正落地到开发工具链里而不是停留在 demo 阶段这篇内容应该能给你一些能直接参考的方案。我会把整个项目的设计思路、实现细节、踩过的坑和排查过程都摊开来讲不绕弯子。2. 方案设计把 PR 审查这件事拆成可自动化的环节2.1 先想清楚审查到底在审什么很多人一上来就急着写代码但我建议先把“人工评审到底在做什么”拆开看。一个典型的 PR 评审动作其实可以分成四层。第一层是规范性检查代码风格是否统一、命名是否合理、有没有明显的死代码和调试残留、是不是把密钥和敏感信息提交上来了。这些规则非常明确机器比人更适合做。第二层是逻辑正确性检查改动是否可能引入空指针、边界条件是否处理、并发场景下有没有竞态风险、有没有明显的逻辑漏洞。这一层需要理解代码语义传统静态检查工具能做一部分但像“这段改动可能让某个状态在不同线程下不一致”这类问题传统工具很难给出上下文相关的判断大模型反而擅长。第三层是架构一致性检查这次改动是否符合项目既有的分层规范和设计模式有没有绕过 service 层直接改数据库、有没有在 controller 里堆业务逻辑。这一层需要理解项目上下文比第二层更抽象。第四层是业务正确性审查改动是否真正实现了 PR 描述里的需求。这一层最难自动化因为要懂业务预期但至少模型可以核对“PR 描述里声称的目标”和“代码实际行为”之间的匹配度。我们最终定的自动化边界是第一层和第二层交给 Hermes 全自动处理第三层做半自动辅助模型给出可疑点人来最终判断第四层只做提示性检查。这个边界很重要否则你会陷入“什么都要自动化结果什么都做不精准”的尴尬境地。2.2 为什么选 Hermes 而不是直接调 API可能有人会问我用 Python 写个脚本调 GitHub API再拼 prompt 发给大模型也能实现类似效果为什么非要引入 Hermes 这个智能体框架我用过最原始的脚本方案最大的问题是“链路脆”和“状态散”。一个正经的 PR 审查流程不是你发一次请求就能跑完的。PR 可能有很多个 commit、评论里可能有作者对修改点的解释、CI 结果需要等待、第一次审查意见给出后作者又推了新 commit、需要做增量复审。这些都要求系统有状态管理、有循环执行能力、能在不同步骤之间传递上下文。Hermes 这种 agent 框架恰好把这些能力集成了。它可以定义一个任务目标内部按计划去调用 GitHub API、读取 diff、写入评论中途遇到异常还能根据反馈调整。对我们来说相当于把整个审查流程当成一段可编排的“智能流程”而不是一根“函数调用链”。另外 Hermes 本身支持插拔工具库GitHub 相关操作被打包成独立的 skill/tool不影响主框架的稳定后续想加 GitLab 支持或者接内部代码托管平台扩展起来也顺手。2.3 整体流程设计我们把自动化评审拆成下面这条链路Hermes 在这个链路里承担的是“调度大脑 分析器”的角色监听事件通过 GitHub App 或 Webhook 接收 PR 相关事件。拉取上下文获取 PR 元信息、改动文件列表、diff 内容、commit 历史、评论历史。规则注入把团队的审查规范文件、项目目录结构说明、相关模块的 README 注入到分析上下文中。第一轮全量分析Hermes 根据注入的上下文执行代码分析输出结构化审查意见。结果结构化把意见按“阻塞/非阻塞”“文件/行号”“问题类型”等维度整理成 JSON。回写 PR以机器人账号身份发布 review comment行级评论直接挂在对应代码行。增量复审如果 PR 推送了新 commit只对增量部分做回归审查避免重复打扰。这套链路看起来不复杂但真正落地的过程中每个环节都有不少细节坑下面讲实现时我会逐一展开。3. 核心实现Hermes 如何接入 GitHub PR3.1 PR 事件接入方式对比要让 Hermes 感知 PR常见方案有三类GitHub App、Webhook 自建服务、定时轮询。GitHub App 是最正规的方式它自带权限体系安装到仓库后可以通过 API 订阅 pull_request 事件而且机器人账号以 app 身份发言不会占用个人账号额度也不容易被封。缺点是首次配置流程稍长需要生成私钥、设置回调地址还要管理 token 的刷新和安装列表。Webhook 自建服务则更直接你租一个小服务器配好 Webhook 地址把 JSON payload 送过来自己解析事件类型再决定是否触发 Hermes。优点是灵活缺点是服务器挂了事件就丢了需要配合重试机制。定时轮询是最偷懒的方案定时调 GitHub Search API 找出状态为 open 且有新活动的 PR逐个处理。优点是抗网络抖动缺点是会有延迟而且容易遇到搜索接口的限流。我实际选的是 GitHub App Webhook 双保险用 GitHub App 负责认证和管理评论权限同时把 Webhook 作为事件触发器。这么做的好处是触发链路极短事件一到就启动分析而所有写操作都有合法身份。如果你们的代码托管在内部 GitLab思路是一样的只是 API 换一换。3.2 审查上下文怎么组织这是整个项目里影响效果最明显的环节。同一个大模型上下文组织得好不好审查质量天差地别。先说 diff。GitHub 默认的 diff 格式是统一 diff包含 hunk 头和上下文行。直接把完整 diff 一次性丢给 Hermes容易超过模型上下文窗口而且大片大片的代码会让模型“迷失重点”。我们的做法是把 diff 按文件拆分成独立单元每个文件单独分析。对超过 200 行的 diff 做二次切分按 hunk 块分组。每个文件分析时注入文件路径、变更统计新增/删除行数、变更类型新增/修改/删除/重命名、当前仓库的目录结构。这样组织之后模型的分析粒度是“文件级”的输出意见时能准确关联到具体文件和行号。除了 diffPR 描述和标题也是必须注入的。你想想一个 PR 的目标是“修复用户登录后 session 不失效的问题”审查时自然要重点看 session 相关的逻辑改动。不注入 PR 描述模型就只能泛泛而谈。项目规范文件也值得注入。比如后端仓库有 CONTRIBUTING.md里面写了事务必须走注解、禁止在循环里查库、DTO 不能直接透传 Entity 等约定。把这些规范压缩成精简的 rule 列表随每次分析一起发给模型审查意见会和团队风格高度一致。3.3 审查提示词设计要点提示词在这个场景里不是写一段话让模型“帮我看看代码”就完了。我踩了不少次坑最后沉淀出一个质量相对稳定的提示词结构可以拆成四个块目标块说明你要扮演的角色和任务比如“你是一名负责后端仓库代码评审的高级工程师请审查以下 PR 的代码变更目标是找出可能引发生产事故或技术债务的问题”。规则块注入团队的审查规则每条规则尽量是“可判定的”比如“禁止在事务方法中执行远程调用”“所有外部输入必须经过参数校验”。输出格式块明确要求输出为 JSON 数组每个元素包含 file_path、line_number、severity、category、message 五个字段。这步非常关键结构化输出让后续自动挂评论和分类统计变得容易而不是让模型自由发挥一段散文。自查块要求模型在输出前重新检查每一条意见是否属实避免幻觉。做法很简单在提示词末尾加一句“逐条检查以上意见如果某条意见无法从提供的 diff 或规范原文中找到依据请删除该条”。这个自查指令实测能过滤掉大概两成左右的假阳性问题。4. 部署与使用从克隆到跑通第一条 PR 审查4.1 安装和环境准备Hermes 的部署方式我试过几种最省心的是用 Docker。项目本身依赖 Python 环境直接裸机装的话要处理 Python 版本、依赖冲突、系统库等一系列问题Docker 能把这些问题一次性隔离掉。基础步骤是先在仓库目录下写好.env配置文件里面至少要有GITHUB_APP_ID你的AppID GITHUB_APP_PRIVATE_KEY_PATH/path/to/private-key.pem GITHUB_WEBHOOK_SECRET你的Webhook密钥 MODEL_API_KEY你的模型服务API Key MODEL_BASE_URL你的模型服务地址GitHub App 的私钥文件路径指到容器内挂载的目录不要打进镜像里。然后用 docker-compose 启动服务。依赖的模型服务既可以是公网的大模型 API也可以是内网部署的开源模型服务。我们当时为了数据安全最开始试的是内网模型效果也不错Hermes 对模型服务地址没有强绑定只要兼容 OpenAI 格式的接口都行。这算是这个框架比较友好的地方不会把你锁死在某一家的模型上。4.2 最小可运行的审查任务配置Hermes 的任务配置本质上就是告诉它“你收到什么事件时要执行哪些步骤”。我们定义了一个简单的规则文件核心逻辑是监听事件类型创建 PR、PR 同步新 commit、PR 请求审查。监听到之后按顺序做这些动作调用 GitHub skill 获取 PR 的详细信息和 files diff。组装上下文PR 描述 团队规则 文件列表。执行代码审查 skill传入组装好的上下文。拿到结构化 JSON 结果后过滤掉 severity 为 info 级别的低价值评论。对每条非阻塞意见先检查是否在最近的评论中已存在避免重复刷屏。以 GitHub App 身份逐条创建行级评论。第一次跑通的时候我印象特别深我在测试仓库里提了一个故意留了空指针隐患的 PRHermes 在几十秒内就在对应行下面评论了“这里未判空当 order 为空对象时有 NPE 风险”还挂了一条我对公司敏感信息硬编码的警告。那一刻我意识到这东西不是玩具是真的能顶一个初级 review 人员。5. 常见问题与排查实录5.1 PR 事件收不到这是接入阶段最容易遇到的情况。Webhook 配好了PR 也提了但服务端就是没动静。排查路径建议从这几条入手先看 GitHub 仓库的 Settings - Webhooks 页面确认最近一次 delivery 是否成功响应。如果显示 500 或超时说明服务端入口可能没接住。再看日志Hermes 的 webhook 入口如果正常收到事件会打印一条包含 event type 的日志。我们当时遇到过一种情况GitHub 的 payload 默认是 JSON但某个代理层把 content-type 转成了 text/plain导致解析失败。这种情况在自建代理的场景里很常见建议在代码里对 content-type 做容错。另外GitHub App 默认只在“已安装到仓库”的情况下才会推送事件。如果你新建了仓库但忘了点安装事件会静默丢失这个问题排查起来最费时间因为没有明显报错。检查方法是在 GitHub 的 App 管理页看看仓库是否在安装列表内。5.2 审查结果太宽泛或者太严苛模型刚跑起来的时候最容易出现两个极端要么输出像教科书一样的大道理“注意并发安全”“请完善错误处理”要么就是没事找事“这个变量名可以改得更简洁”。前一种问题通常是上下文里缺少规范导致的。模型不知道你们项目的具体约定只能给大而泛的通用建议。解决方法是把团队规范显式注入并且尽量写成可判定的规则语句。后一种问题则通常是规则块写得太模糊。比如你写“代码要优雅”模型就会把“不优雅”理解得五花八门。把规则改成“禁止在循环体内进行数据库查询”“禁止硬编码敏感 token应使用环境变量”模型就能给出具体可执行的建议了。还有一个技巧是调节审查级别。我们在配置里加了一个 severity 阈值信息级意见默认不展示、不给评论只记录到日志里。警告和建议级别会展示为行级评论阻塞级别则额外在 PR 顶部留一条总评。这样大幅减少了无效噪音。5.3 API 限流与费用控制自动化审查一段时间后你会发现最痛的约束不是模型效果而是成本。每审查一个 PR都要消化一次 diff大文件的 token 消耗很猛。控制成本的办法有几个。第一是引入增量审查。PR 第一次推送用全量分析后续新 commit 只分析增量 diff。GitHub 的 compare API 可以方便拿到两个 commit 之间的差异。第二是 diff 压缩。把空行变化、缩进变化、格式调整的块先过滤掉只分析实际逻辑变更的 hunk。这个操作用 git diff 的-w参数可以先过滤掉空格类差异再用脚本剔除纯增删注释的行。第三是分级处理。小型 PR改动小于 50 行直接走完整分析中型 PR50-300 行先做快速扫描可疑文件重点分析大型 PR超过 300 行拆成多个子任务逐个文件分析避免一次性超大上下文。按我们的实际数据这三个手段加起来能让单次审查成本下降约六到七成。对于一个日审查量在二三十个 PR 的团队每月的模型支出大概在一百到两百元之间完全可以接受。注意GitHub API 本身的调用也有速率限制。App 身份默认情况下每小时有 5000 个请求额度平时够用但如果你用定时轮询扫大量仓库很容易撞限。遇到 403 时不要慌张等服务返回X-RateLimit-Remaining头为 0 后等待重置时间即可。更稳妥的做法是每次调用前检查剩余额度低于阈值时先排队。5.4 假阳性评论的治理自动化审查上线以后最大的信任危机来自“乱报”。如果机器经常给出明显的错误意见团队很快就不会再看它的评论了。我们治理假阳性用了一套配合动作第一步是收集反馈。每次模型给出阻塞级别意见时人工评审者可以留标记。Hermes 提供了反馈回传接口处理后的结果会进入样本库。第二步是定期微调。攒到一百条人工纠正过的样本后我们会对提示词做一轮更新把误报类型作为反例写进规则块。比如“以下情况不是问题在测试文件中使用了 mock 对象、在初始化阶段使用了 try-catch 而不是防御性判断”这类反例能显著改变输出倾向。第三步是动态白名单。有些规则对某些文件不管用比如生成的 ORM 模型文件、自动生成的 API 客户端代码直接加到白名单跳过分析既不浪费 token 也不制造噪音。这套机制跑了一个多月我们模型的综合准确率从最初的六成左右提升到了八成五以上。虽然离全自动让人完全放心的程度还有距离但已经能做到“机器人提供九成以上的有效信息人只需要快速过一眼”。6. 回到实操几条我自己的体验项目跑起来之后我最大的感受是自动化代码评审最值钱的地方不是把“1 小时的评审工作压缩到 1 分钟”而是改变了团队对评审的预期。过去有些简单 PR 大家懒得看现在机器人先铺一轮底reviewer 打开 PR 的时候就已经有了上下文注意力可以集中在真正需要人判断的设计问题上。要说印象最深的教训可能就是“不要在一开始追求完美”。第一版 Hermes 审查的规则、提示词、调度策略都很粗糙如果当时想着把所有细节打磨好再上线估计现在还在写方案。边跑边迭代用真实 PR 的数据来调比什么设计都靠谱。还有一点想提醒大家自动化评审会放大你团队的规范。如果团队本身没有清晰的代码规范机器人给出的意见也会是混乱的。建议在启动这类项目之前先把团队的“代码审查检查清单”整理出来不需要多薄三五十条覆盖常见问题的规则就够了。这份清单既是人的评审参考也是机器的规则库一举两得。后续我们还在试两件事一个是把审查范围从代码扩展到依赖安全扫描和许可证合规检查另一个是让 Hermes 在给出问题意见的同时附带修改建议代码块这样开发者可以通过 GitHub 的 suggestion 功能一键应用修复。这两个方向做完自动化评审的闭环就更完整了。如果你们团队也在做类似的事情欢迎一起交流思路。