1. 为什么我决定用 Hermes 做 GitHub PR 审查做后端开发的这些年我花在代码评审上的时间越来越多。团队规模涨到二十多人以后PR 堆积速度肉眼可见地变快而能静下心逐行 review 的人却越来越少。最典型的状态是一个 PR 挂了两天没人碰或者 reviewer 只回一句“LGTM”评审该有的作用完全没发挥出来。这个问题不是靠强调流程纪律能解决的本质上是人工评审的吞吐量跟不上代码产出速度。后来我把 Hermes 这个开源智能体框架接到 GitHub PR 流程里跑通了一套“机器先审一遍、人再审重点”的自动化代码评审方案。这篇文章就把我实际搭建这套系统踩过的坑、总结出的配置方法、以及完整的实操过程记录下来。从部署 Hermes、配置模型到对接 GitHub PR、设计评审规则再到处理各种翻车现场都会尽量讲透。如果你也在为 PR 评审效率发愁或者想让团队引入 AI 评审助手这应该是能直接抄作业的一份参考。先说结论这套方案的核心不是“用 AI 取代人”而是让 AI 先完成 80% 的机械性检查——代码风格、明显逻辑错误、资源泄漏、并发隐患、安全漏洞这类有明确模式的问题交给我下面的智能体去扫人的精力腾出来处理架构合理性、业务语义、可维护性这些真正需要判断力的部分。实测下来一个中等规模 PR300 到 500 行变更Hermes 从触发到产出完整评审意见只需要 2 到 4 分钟而且评审覆盖度比人工更稳定。1.1 代码评审的痛点到底痛在哪里先说个扎心对比。人工评审一个 300 行的 PR快的话 20 分钟慢的话半小时起步而且这 20 分钟里你得反复切换上下文先看 diff、再去翻相关的业务代码、还得回忆项目里的历史约定。如果评审者刚接手这块代码光是理解上下文就耗掉大半时间。注意力波动也很要命——评审到第 10 个文件时前面的内容基本忘了一半遗漏率直线上升。AI 评审在这几个方面有天然优势。第一它没有上下文切换成本任何 PR 到手都是秒级重建项目背景第二它的注意力分布均匀不会因为“这个文件改得少”就跳过第三它能强制套用团队的评审规范比如“所有新增接口必须做参数校验”“数据库查询必须限制返回条数”这类硬约束模型每次评审都会被提示词逼着逐项核对。这也是我选择 Hermes 而不是手写一堆静态检查脚本的原因——静态规则只能查固定模式而智能体能理解代码语义能做跨文件的逻辑推理。1.2 Hermes 在整个方案里扮演什么角色Hermes 是一个开源的智能体框架核心思路是把大语言模型的能力封装成可编排的工作流让模型能调用外部工具、读取外部数据、执行具体任务。在这个项目里Hermes 扮演的是“评审主管”角色它负责接收 PR 事件、拉取代码变更、调用大模型逐文件分析、汇总评审结论、最后把评论和审查状态写回 GitHub。整个链路里 Hermes 不单打独斗它的关键搭档有三个GitHub承载代码仓库和 PR 流程、大模型负责语义理解与判断、以及触发机制负责告诉 Hermes“有新 PR 来了”。我选的是 GitHub Actions 作为触发载体原因后面细说。先强调一点Hermes 本身不绑定特定大模型它的模型层做成了可插拔接口兼容 OpenAI 风格的 API 格式。国内部署时可以直接接 DeepSeek 的 API也可以接本地模型比如 Ollama 拉起来的 Qwen 系列。考虑到成本和响应速度我目前用的是 DeepSeek 的 API评审质量和速度都比较均衡。注意Hermes 的部署和配置在不同版本里有差异本文以 0.2.x 版本为基础。如果你用的是更新版本记得以官方文档为准但整体流程和思路是通用的。2. 环境准备与 Hermes 部署2.1 部署方式选型容器优先本机兜底Hermes 的部署方式主要有三种Docker 容器、本机 Python 环境、以及通过构建工具打成独立可执行文件。我的建议是能上 Docker 就上 Docker尤其是要接到 GitHub Actions 里跑的时候。容器化之后整个评审环境是隔离的不会污染你的开发机也不会因为某次 pip 升级把依赖搞坏。另一个好处是 Actions 里可以直接用现成的容器镜像拉起一个 job 就是干净环境。但容器方式也有坑如果你的内网环境拉取镜像不方便或者需要在本地快速验证配置那在本机用 conda 建一个独立环境更省事。我最初就是先在本地搭了一套 Python 环境跑通流程确认配置没问题之后才把方案固化到 GitHub Actions 里的。这个顺序能帮你把“配置问题”和“环境问题”分开排查少很多纠结。2.2 具体安装步骤与依赖清单本机部署时我建议用 conda 单独建环境别直接装在 base 环境里。Hermes 的依赖比较多包括核心框架、Git 操作库、OpenAI 客户端还有一些工具调用相关的组件装到 base 环境容易跟其他项目打架。建环境时用 Python 3.10 或 3.11 比较稳太老的版本会有兼容性问题。conda create -n hermes-review python3.11 -y conda activate hermes-review pip install hermes-agent装完之后先验证一下版本确认核心命令能跑起来hermes --version正常情况下会输出版本号。如果提示找不到命令多半是 conda 环境的 bin 目录没进 PATH检查一下当前环境是否激活成功。另外Hermes 运行过程中需要调用 Git 命令来拉取和解析 diff所以宿主环境必须装好 Git这个容易被忽略。2.3 配置大模型后端用 DeepSeek 做评审大脑装好框架之后最关键的一步是配置模型后端。Hermes 的配置文件默认在~/.hermes/config.yaml首次运行时如果没有会自动创建。核心配置项是模型提供方、API Key、模型名称和请求参数。我用 DeepSeek 时的配置长这样model: provider: deepseek api_key: ${DEEPSEEK_API_KEY} model_name: deepseek-chat temperature: 0.2 max_tokens: 4096 request_timeout: 120几个参数解释一下。temperature我调到了 0.2这是评审场景的关键——代码评审需要的是稳定和精确不是发散创意温度越低输出越稳定。max_tokens设成 4096 是因为评审意见可能包含多条评论和总结太短容易被截断。request_timeout设成 120 秒因为大 PR 的 diff 很长一次请求可能需要较长时间生成。API Key 我建议通过环境变量注入别硬编码在配置文件里。这样即使配置文件被误提交到仓库也不会泄露密钥。本地调试时可以在~/.bashrc里 export部署到 GitHub Actions 时用仓库的 Secrets 管理。提示如果你用的是本地模型比如 Ollama 加载的 Qwen2.5-Coderprovider 要切换成 openai-compatible 模式地址指向本地服务同时确认本地服务能处理长上下文。本地模型的优势是数据不出内网但速度和质量通常比云端 API 差一截看团队对数据合规的要求来定。3. 让 Hermes 看懂 PR核心链路设计3.1 触发机制为什么我选了 GitHub Actions做自动化评审第一步是决定“PR 来了怎么通知 Hermes”。主流方案有两个Webhook 服务和 GitHub Actions。我最终选了 Actions原因有三条。第一配置成本低。Webhook 方案要求你有一个公网可达的服务端还需要处理 GitHub 的签名验证、重试机制、事件去重这些工作加起来不亚于写个小服务。Actions 只要在仓库里放一个 workflow 文件就行事件触发、权限、日志展示全是现成的。第二权限体系干净。工作流运行时能拿到github-token可以直接通过 API 提交 review 评论和状态不需要额外管理一个机器人的密钥。token 的权限范围在 workflow 里显式声明最小化授权。第三可观测性好。每次评审都是一次独立的 workflow run日志、耗时、失败原因都在 Actions 页面里能查排查问题非常直观。Webhook 方案也不是没有价值如果你希望评审服务常驻实时响应多个仓库的 PR或者想在 Hermes 里维护更多的跨仓库状态那独立服务更合适。但大多数团队的起步阶段Actions 完全够用。3.2 评审数据的获取与精简Hermes 要评审 PR必须先拿到变更内容。GitHub 的 PR 数据量很大一个几百行改动的 PR它的 API 响应可能包含大量元数据和评论信息直接全部丢给模型有两个问题token 消耗巨大而且无关信息会干扰模型判断。我的做法是分三步取数。第一步用 GitHub API 获取 PR 的基本信息——标题、描述、作者、目标分支第二步获取该 PR 的.diff文件这个格式比较精简包含每个文件的变更行第三步把 diff 按文件拆分控制每个文件的评审输入量。超过一定行数的文件要做分段处理因为单次请求塞太多内容模型容易丢失前面的上下文出现“看了后面忘了前面”的情况。这里有个实操细节.diff文件虽然是纯文本但里面包含路径、行号、上下文信息结构是规则的。我自己写了个解析脚本把 diff 转换成结构化格式标注每个 hunk 的新旧行号范围这样 Hermes 在生成评论时能精确引用到具体行号评论可以直接锚定到代码行上对开发者非常友好。3.3 评审规则的注入方式模型再强也不可能天然知道你的团队规范。所以评审规则必须显式注入。我把规则分成两层通用规则和仓库规则。通用规则写在 Hermes 的默认系统提示里覆盖所有仓库包括检查明显的逻辑错误空指针、数组越界、除零、死循环检查资源管理文件句柄、数据库连接、网络连接是否关闭检查并发安全共享变量是否有锁保护、是否存在竞态条件检查安全风险SQL 注入、XSS、硬编码密钥检查代码规范命名、格式、过长的函数、重复代码仓库规则则是每个项目单独维护一份放在仓库的.github/hermes-rules.md里里面写项目特有的约束。比如有个支付项目我就在里面加了一条“所有涉及金额的计算必须使用 Decimal禁止使用浮点数”。Hermes 每次评审时会把这份文件内容读出来拼到系统提示里。规则不在多而在能被执行。写规则的时候要用“可检查”的表述比如“禁止在事务内执行远程调用”模型就能顺着这个点去排查如果写“注意代码质量”模型只会泛泛而谈输出一堆没营养的套话。4. 完整实操从零接入一个仓库4.1 创建配置文件与私有 token开始之前先确认两件事仓库里要有.github/hermes-rules.md可以是空文件占位以及仓库的 Secrets 里配好DEEPSEEK_API_KEY。然后我们来写 workflow 文件。我的 workflow 文件放在.github/workflows/hermes-review.yml完整内容如下name: hermes-pr-review on: pull_request: types: [opened, synchronize] permissions: contents: read pull-requests: write issues: write jobs: review: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Hermes review uses: docker://hermes-agent/reviewer:latest env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }}这个文件的几个关键点types: [opened, synchronize]表示新 PR 创建时和 PR 更新时各触发一次保证开发者改了代码之后评审意见能刷新。权限里pull-requests: write是提交 review 评论必需的issues: write是给评论打标签时用的如果不需要可以去掉。fetch-depth: 0是让 Actions 把完整 Git 历史拉下来Hermes 需要对比目标分支来分析变更。4.2 设计评审结果的处理逻辑评审结果不能只丢到评论区就完事。我给 Hermes 定义了一套结果处理逻辑它生成的评审结论分成三个等级——阻塞Block、建议Suggest、提示Nit。阻塞级的问题比如明显会引发线上事故的 bug、安全漏洞会通过 GitHub review 接口提交为 Request Changes 状态建议级的问题作为普通评论提交提示级的问题只汇总进总结不逐条刷屏。这个分级机制能避免一个经典问题——AI 评审把整个 PR 页面刷成红色。如果每条“可能有问题”的话都变成阻塞评论开发者会觉得 AI 在制造噪音慢慢就不看了。分级之后只有真正该拦的问题才拦其他的作为参考人还是最终的审判者。我实际跑了一段时间之后团队成员对建议级评论的采纳率还是挺高的因为确实能发现一些眼睛扫过但没留意的细节。4.3 跑通第一次自动化评审配置都到位之后第一次触发是很忐忑的——不知道它会不会报错也不知道评审质量到底怎么样。我的建议是先在自己的开发分支上开一个“测试 PR”故意埋几个明显的 bug比如一个未关闭的文件句柄、一个可能会除零的计算、一个命名违例的函数。然后观察 workflow 是否正常运行。第一次跑通常会遇到几个坎。最常见的是依赖安装超时、镜像拉不下来、或者 API Key 配置错误。这些排错方法放在下一节细说。重点是你需要看 workflow 日志里 Hermes 的实际输出确认它真的读到了 diff、真的调用了模型、真的生成了评论。我当时第一次跑就看到它在测试 PR 下评论了三条意见其中正好命中我埋的除零问题那一刻就知道这套系统能干活了。跑通之后记得做一次“评审质量抽查”挑两三个历史 PR手动让 Hermes 重新评审一遍把它的意见和之前人工评审的意见做对比。重点看它有没有漏掉当时人工发现的关键问题漏报以及有没有提出明显不合理的意见误报。这个环节能帮你调整规则和提示词让系统快速进入可用状态。5. 常见问题与排错实录5.1 高频问题排查速查表这段时间用下来我把踩过的坑整理成了一张排查表分享出来供你参考。这些问题里有些很隐蔽不实际跑一遍很难发现。现象可能原因解决办法workflow 启动后秒失败镜像拉取失败或依赖不兼容检查 runner 是否稳定换用本机构建镜像再推送报错无法连接模型 API网络不通或 API Key 无效先本地 curl 测试 API 连通性确认 Key 正确且在有效期内评审结果为空配置里 prompt 模板为空或者解析 diff 失败检查 rules 文件是否存在检查 .diff 是否成功拉取评论只出来一条总结result 处理逻辑里提交类型识别失败查看日志中 review 提交阶段的错误确认权限配置了 pull-requests: write评审内容答非所问模型上下文被无关信息塞满精简 diff 输入过滤非代码变更增加分段处理workflow 运行正常但状态没更新Hermes 没有调用 commit review API检查是否有 set 状态权限确认调用了正确的 review 接口排查问题的通用思路是先把 workflow 里每个步骤拆开看。Hermes 的日志默认会输出到 stdoutActions 页面能看到每一步的执行细节。我记得有一次评审结果为空排查到最后发现是 diff 拉取时把多个文件拼成了一长串超出了模型单次上下文窗口输出被截断后 JSON 解析失败。把输入做了分段之后就正常了。5.2 误报与漏报怎么权衡AI 评审最大的争议永远是准确率报多了是噪音报少了没用。我的经验是初期宁可多报然后靠规则收敛。系统上线前两周Hermes 每条意见都会推到 PR 里有人觉得烦就关掉通知两周后我拿到一批真实数据统计哪些类别的评论是大家公认“没用的”再把这些规则从提示词里弱化。这种基于自己团队数据来调整的策略比一开始就猜“什么重要”要靠谱得多。漏报的情况相对难处理。Agent 评审偶尔会漏掉一些人眼一看就知道的问题通常原因是规则没覆盖到或者 diff 里相关上下文太远。我的办法是在规则文件里不断沉淀团队踩过的坑线上出过事故的代码模式、历次评审里反复出现的问题都写成明确规则。这样系统是越用越强的而不是一开始就追求完美。另外评审意见的措辞也很重要。我专门在提示词里要求“评论必须给出具体位置、问题描述、建议修改方向”禁止说空话比如“这段代码有潜在风险”这种没有信息量的话。措辞明确之后团队对 AI 评价的信任度提升很快。6. 几个必须单独拎出来说的经验6.1 控制评审节奏别让 AI 变成“抢话王”一个容易忽略的问题是AI 评审不能太快也没必要每次 PR 都立刻评论。如果 Hermes 在 PR 刚创建 10 秒内就评论开发者可能还在持续 push 新的提交评论很快就过期了产生信息噪音。我在 workflow 里加了一个延时策略PR 状态变更为 opened 之后等 5 分钟再触发评审给开发者一点缓冲时间。同步更新synchronize 事件的情况则等 CI 任务基本跑完再执行避免和静态检查的结果冲突。这个小调整虽然简单但对实际使用体验改善很大。6.2 评审历史要保留方便对照Hermes 每次评审都会把结果写一份 JSON 到 workflow 的 artifact 里包括评论内容、分级、涉及文件。这份历史非常有用一是做质量回溯看看评审建议被采纳了多少二是做系统优化统计哪些规则触发的评论最多、哪些评论被开发者关闭。没有这份数据后面调规则就只能靠感觉了。建议至少保留 30 天的 artifact 历史。6.3 token 成本要盯着自动化评审跑起来之后token 消耗是个不太起眼但没法忽视的问题。一个 500 行的 PR加上 diff 输入、提示词、模型输出一次评审可能要消耗几万 token。团队 PR 多的时候一个月下来费用是看得见的一笔支出。我的控制方法是只评审新增和修改的行过滤掉纯格式变更的文件规则文件本身单独维护不让模型每次去读整个仓库文档太小的 PR比如只有一行改动直接跳过评审。这样整体成本能降一半以上。另外提醒一句尽量给机器人账号单独申请 API Key别用个人账号的 Key。一方面是便于统计成本费用另一方面是避免个人额度用完影响自己的开发工作。6.4 后续还可以怎么扩展这套系统目前已经稳定跑在团队的主仓库上。它最大的价值其实不在“省了多少评审时间”而在于给团队提供了一条稳定的代码底线——每份代码合入主干之前都被认真看过了。后面我还打算做两件事一是让 Hermes 能跟着人的评审反馈学习比如开发者对某条评论点击“不采纳”时把这个信息回流到配置里让模型下次调整判断二是把评审范围从代码扩展到设计文档和接口契约让 PR 描述里的方案说明也能被自动检查。从我个人的实际体验来说最深的体会是自动化评审能不能用起来七成靠配置和规则设计三成靠模型能力。花在打磨规则文件上的时间比花在折腾框架上的时间回报高得多。如果你也想给团队上这套能力建议先从一个小仓库开始跑两周攒数据再逐步推广到核心仓库。磨刀不误砍柴工这套流程值得你花一个下午搭起来。
Hermes智能体自动化GitHub PR审查：从部署到实战
1. 为什么我决定用 Hermes 做 GitHub PR 审查做后端开发的这些年我花在代码评审上的时间越来越多。团队规模涨到二十多人以后PR 堆积速度肉眼可见地变快而能静下心逐行 review 的人却越来越少。最典型的状态是一个 PR 挂了两天没人碰或者 reviewer 只回一句“LGTM”评审该有的作用完全没发挥出来。这个问题不是靠强调流程纪律能解决的本质上是人工评审的吞吐量跟不上代码产出速度。后来我把 Hermes 这个开源智能体框架接到 GitHub PR 流程里跑通了一套“机器先审一遍、人再审重点”的自动化代码评审方案。这篇文章就把我实际搭建这套系统踩过的坑、总结出的配置方法、以及完整的实操过程记录下来。从部署 Hermes、配置模型到对接 GitHub PR、设计评审规则再到处理各种翻车现场都会尽量讲透。如果你也在为 PR 评审效率发愁或者想让团队引入 AI 评审助手这应该是能直接抄作业的一份参考。先说结论这套方案的核心不是“用 AI 取代人”而是让 AI 先完成 80% 的机械性检查——代码风格、明显逻辑错误、资源泄漏、并发隐患、安全漏洞这类有明确模式的问题交给我下面的智能体去扫人的精力腾出来处理架构合理性、业务语义、可维护性这些真正需要判断力的部分。实测下来一个中等规模 PR300 到 500 行变更Hermes 从触发到产出完整评审意见只需要 2 到 4 分钟而且评审覆盖度比人工更稳定。1.1 代码评审的痛点到底痛在哪里先说个扎心对比。人工评审一个 300 行的 PR快的话 20 分钟慢的话半小时起步而且这 20 分钟里你得反复切换上下文先看 diff、再去翻相关的业务代码、还得回忆项目里的历史约定。如果评审者刚接手这块代码光是理解上下文就耗掉大半时间。注意力波动也很要命——评审到第 10 个文件时前面的内容基本忘了一半遗漏率直线上升。AI 评审在这几个方面有天然优势。第一它没有上下文切换成本任何 PR 到手都是秒级重建项目背景第二它的注意力分布均匀不会因为“这个文件改得少”就跳过第三它能强制套用团队的评审规范比如“所有新增接口必须做参数校验”“数据库查询必须限制返回条数”这类硬约束模型每次评审都会被提示词逼着逐项核对。这也是我选择 Hermes 而不是手写一堆静态检查脚本的原因——静态规则只能查固定模式而智能体能理解代码语义能做跨文件的逻辑推理。1.2 Hermes 在整个方案里扮演什么角色Hermes 是一个开源的智能体框架核心思路是把大语言模型的能力封装成可编排的工作流让模型能调用外部工具、读取外部数据、执行具体任务。在这个项目里Hermes 扮演的是“评审主管”角色它负责接收 PR 事件、拉取代码变更、调用大模型逐文件分析、汇总评审结论、最后把评论和审查状态写回 GitHub。整个链路里 Hermes 不单打独斗它的关键搭档有三个GitHub承载代码仓库和 PR 流程、大模型负责语义理解与判断、以及触发机制负责告诉 Hermes“有新 PR 来了”。我选的是 GitHub Actions 作为触发载体原因后面细说。先强调一点Hermes 本身不绑定特定大模型它的模型层做成了可插拔接口兼容 OpenAI 风格的 API 格式。国内部署时可以直接接 DeepSeek 的 API也可以接本地模型比如 Ollama 拉起来的 Qwen 系列。考虑到成本和响应速度我目前用的是 DeepSeek 的 API评审质量和速度都比较均衡。注意Hermes 的部署和配置在不同版本里有差异本文以 0.2.x 版本为基础。如果你用的是更新版本记得以官方文档为准但整体流程和思路是通用的。2. 环境准备与 Hermes 部署2.1 部署方式选型容器优先本机兜底Hermes 的部署方式主要有三种Docker 容器、本机 Python 环境、以及通过构建工具打成独立可执行文件。我的建议是能上 Docker 就上 Docker尤其是要接到 GitHub Actions 里跑的时候。容器化之后整个评审环境是隔离的不会污染你的开发机也不会因为某次 pip 升级把依赖搞坏。另一个好处是 Actions 里可以直接用现成的容器镜像拉起一个 job 就是干净环境。但容器方式也有坑如果你的内网环境拉取镜像不方便或者需要在本地快速验证配置那在本机用 conda 建一个独立环境更省事。我最初就是先在本地搭了一套 Python 环境跑通流程确认配置没问题之后才把方案固化到 GitHub Actions 里的。这个顺序能帮你把“配置问题”和“环境问题”分开排查少很多纠结。2.2 具体安装步骤与依赖清单本机部署时我建议用 conda 单独建环境别直接装在 base 环境里。Hermes 的依赖比较多包括核心框架、Git 操作库、OpenAI 客户端还有一些工具调用相关的组件装到 base 环境容易跟其他项目打架。建环境时用 Python 3.10 或 3.11 比较稳太老的版本会有兼容性问题。conda create -n hermes-review python3.11 -y conda activate hermes-review pip install hermes-agent装完之后先验证一下版本确认核心命令能跑起来hermes --version正常情况下会输出版本号。如果提示找不到命令多半是 conda 环境的 bin 目录没进 PATH检查一下当前环境是否激活成功。另外Hermes 运行过程中需要调用 Git 命令来拉取和解析 diff所以宿主环境必须装好 Git这个容易被忽略。2.3 配置大模型后端用 DeepSeek 做评审大脑装好框架之后最关键的一步是配置模型后端。Hermes 的配置文件默认在~/.hermes/config.yaml首次运行时如果没有会自动创建。核心配置项是模型提供方、API Key、模型名称和请求参数。我用 DeepSeek 时的配置长这样model: provider: deepseek api_key: ${DEEPSEEK_API_KEY} model_name: deepseek-chat temperature: 0.2 max_tokens: 4096 request_timeout: 120几个参数解释一下。temperature我调到了 0.2这是评审场景的关键——代码评审需要的是稳定和精确不是发散创意温度越低输出越稳定。max_tokens设成 4096 是因为评审意见可能包含多条评论和总结太短容易被截断。request_timeout设成 120 秒因为大 PR 的 diff 很长一次请求可能需要较长时间生成。API Key 我建议通过环境变量注入别硬编码在配置文件里。这样即使配置文件被误提交到仓库也不会泄露密钥。本地调试时可以在~/.bashrc里 export部署到 GitHub Actions 时用仓库的 Secrets 管理。提示如果你用的是本地模型比如 Ollama 加载的 Qwen2.5-Coderprovider 要切换成 openai-compatible 模式地址指向本地服务同时确认本地服务能处理长上下文。本地模型的优势是数据不出内网但速度和质量通常比云端 API 差一截看团队对数据合规的要求来定。3. 让 Hermes 看懂 PR核心链路设计3.1 触发机制为什么我选了 GitHub Actions做自动化评审第一步是决定“PR 来了怎么通知 Hermes”。主流方案有两个Webhook 服务和 GitHub Actions。我最终选了 Actions原因有三条。第一配置成本低。Webhook 方案要求你有一个公网可达的服务端还需要处理 GitHub 的签名验证、重试机制、事件去重这些工作加起来不亚于写个小服务。Actions 只要在仓库里放一个 workflow 文件就行事件触发、权限、日志展示全是现成的。第二权限体系干净。工作流运行时能拿到github-token可以直接通过 API 提交 review 评论和状态不需要额外管理一个机器人的密钥。token 的权限范围在 workflow 里显式声明最小化授权。第三可观测性好。每次评审都是一次独立的 workflow run日志、耗时、失败原因都在 Actions 页面里能查排查问题非常直观。Webhook 方案也不是没有价值如果你希望评审服务常驻实时响应多个仓库的 PR或者想在 Hermes 里维护更多的跨仓库状态那独立服务更合适。但大多数团队的起步阶段Actions 完全够用。3.2 评审数据的获取与精简Hermes 要评审 PR必须先拿到变更内容。GitHub 的 PR 数据量很大一个几百行改动的 PR它的 API 响应可能包含大量元数据和评论信息直接全部丢给模型有两个问题token 消耗巨大而且无关信息会干扰模型判断。我的做法是分三步取数。第一步用 GitHub API 获取 PR 的基本信息——标题、描述、作者、目标分支第二步获取该 PR 的.diff文件这个格式比较精简包含每个文件的变更行第三步把 diff 按文件拆分控制每个文件的评审输入量。超过一定行数的文件要做分段处理因为单次请求塞太多内容模型容易丢失前面的上下文出现“看了后面忘了前面”的情况。这里有个实操细节.diff文件虽然是纯文本但里面包含路径、行号、上下文信息结构是规则的。我自己写了个解析脚本把 diff 转换成结构化格式标注每个 hunk 的新旧行号范围这样 Hermes 在生成评论时能精确引用到具体行号评论可以直接锚定到代码行上对开发者非常友好。3.3 评审规则的注入方式模型再强也不可能天然知道你的团队规范。所以评审规则必须显式注入。我把规则分成两层通用规则和仓库规则。通用规则写在 Hermes 的默认系统提示里覆盖所有仓库包括检查明显的逻辑错误空指针、数组越界、除零、死循环检查资源管理文件句柄、数据库连接、网络连接是否关闭检查并发安全共享变量是否有锁保护、是否存在竞态条件检查安全风险SQL 注入、XSS、硬编码密钥检查代码规范命名、格式、过长的函数、重复代码仓库规则则是每个项目单独维护一份放在仓库的.github/hermes-rules.md里里面写项目特有的约束。比如有个支付项目我就在里面加了一条“所有涉及金额的计算必须使用 Decimal禁止使用浮点数”。Hermes 每次评审时会把这份文件内容读出来拼到系统提示里。规则不在多而在能被执行。写规则的时候要用“可检查”的表述比如“禁止在事务内执行远程调用”模型就能顺着这个点去排查如果写“注意代码质量”模型只会泛泛而谈输出一堆没营养的套话。4. 完整实操从零接入一个仓库4.1 创建配置文件与私有 token开始之前先确认两件事仓库里要有.github/hermes-rules.md可以是空文件占位以及仓库的 Secrets 里配好DEEPSEEK_API_KEY。然后我们来写 workflow 文件。我的 workflow 文件放在.github/workflows/hermes-review.yml完整内容如下name: hermes-pr-review on: pull_request: types: [opened, synchronize] permissions: contents: read pull-requests: write issues: write jobs: review: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Hermes review uses: docker://hermes-agent/reviewer:latest env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }}这个文件的几个关键点types: [opened, synchronize]表示新 PR 创建时和 PR 更新时各触发一次保证开发者改了代码之后评审意见能刷新。权限里pull-requests: write是提交 review 评论必需的issues: write是给评论打标签时用的如果不需要可以去掉。fetch-depth: 0是让 Actions 把完整 Git 历史拉下来Hermes 需要对比目标分支来分析变更。4.2 设计评审结果的处理逻辑评审结果不能只丢到评论区就完事。我给 Hermes 定义了一套结果处理逻辑它生成的评审结论分成三个等级——阻塞Block、建议Suggest、提示Nit。阻塞级的问题比如明显会引发线上事故的 bug、安全漏洞会通过 GitHub review 接口提交为 Request Changes 状态建议级的问题作为普通评论提交提示级的问题只汇总进总结不逐条刷屏。这个分级机制能避免一个经典问题——AI 评审把整个 PR 页面刷成红色。如果每条“可能有问题”的话都变成阻塞评论开发者会觉得 AI 在制造噪音慢慢就不看了。分级之后只有真正该拦的问题才拦其他的作为参考人还是最终的审判者。我实际跑了一段时间之后团队成员对建议级评论的采纳率还是挺高的因为确实能发现一些眼睛扫过但没留意的细节。4.3 跑通第一次自动化评审配置都到位之后第一次触发是很忐忑的——不知道它会不会报错也不知道评审质量到底怎么样。我的建议是先在自己的开发分支上开一个“测试 PR”故意埋几个明显的 bug比如一个未关闭的文件句柄、一个可能会除零的计算、一个命名违例的函数。然后观察 workflow 是否正常运行。第一次跑通常会遇到几个坎。最常见的是依赖安装超时、镜像拉不下来、或者 API Key 配置错误。这些排错方法放在下一节细说。重点是你需要看 workflow 日志里 Hermes 的实际输出确认它真的读到了 diff、真的调用了模型、真的生成了评论。我当时第一次跑就看到它在测试 PR 下评论了三条意见其中正好命中我埋的除零问题那一刻就知道这套系统能干活了。跑通之后记得做一次“评审质量抽查”挑两三个历史 PR手动让 Hermes 重新评审一遍把它的意见和之前人工评审的意见做对比。重点看它有没有漏掉当时人工发现的关键问题漏报以及有没有提出明显不合理的意见误报。这个环节能帮你调整规则和提示词让系统快速进入可用状态。5. 常见问题与排错实录5.1 高频问题排查速查表这段时间用下来我把踩过的坑整理成了一张排查表分享出来供你参考。这些问题里有些很隐蔽不实际跑一遍很难发现。现象可能原因解决办法workflow 启动后秒失败镜像拉取失败或依赖不兼容检查 runner 是否稳定换用本机构建镜像再推送报错无法连接模型 API网络不通或 API Key 无效先本地 curl 测试 API 连通性确认 Key 正确且在有效期内评审结果为空配置里 prompt 模板为空或者解析 diff 失败检查 rules 文件是否存在检查 .diff 是否成功拉取评论只出来一条总结result 处理逻辑里提交类型识别失败查看日志中 review 提交阶段的错误确认权限配置了 pull-requests: write评审内容答非所问模型上下文被无关信息塞满精简 diff 输入过滤非代码变更增加分段处理workflow 运行正常但状态没更新Hermes 没有调用 commit review API检查是否有 set 状态权限确认调用了正确的 review 接口排查问题的通用思路是先把 workflow 里每个步骤拆开看。Hermes 的日志默认会输出到 stdoutActions 页面能看到每一步的执行细节。我记得有一次评审结果为空排查到最后发现是 diff 拉取时把多个文件拼成了一长串超出了模型单次上下文窗口输出被截断后 JSON 解析失败。把输入做了分段之后就正常了。5.2 误报与漏报怎么权衡AI 评审最大的争议永远是准确率报多了是噪音报少了没用。我的经验是初期宁可多报然后靠规则收敛。系统上线前两周Hermes 每条意见都会推到 PR 里有人觉得烦就关掉通知两周后我拿到一批真实数据统计哪些类别的评论是大家公认“没用的”再把这些规则从提示词里弱化。这种基于自己团队数据来调整的策略比一开始就猜“什么重要”要靠谱得多。漏报的情况相对难处理。Agent 评审偶尔会漏掉一些人眼一看就知道的问题通常原因是规则没覆盖到或者 diff 里相关上下文太远。我的办法是在规则文件里不断沉淀团队踩过的坑线上出过事故的代码模式、历次评审里反复出现的问题都写成明确规则。这样系统是越用越强的而不是一开始就追求完美。另外评审意见的措辞也很重要。我专门在提示词里要求“评论必须给出具体位置、问题描述、建议修改方向”禁止说空话比如“这段代码有潜在风险”这种没有信息量的话。措辞明确之后团队对 AI 评价的信任度提升很快。6. 几个必须单独拎出来说的经验6.1 控制评审节奏别让 AI 变成“抢话王”一个容易忽略的问题是AI 评审不能太快也没必要每次 PR 都立刻评论。如果 Hermes 在 PR 刚创建 10 秒内就评论开发者可能还在持续 push 新的提交评论很快就过期了产生信息噪音。我在 workflow 里加了一个延时策略PR 状态变更为 opened 之后等 5 分钟再触发评审给开发者一点缓冲时间。同步更新synchronize 事件的情况则等 CI 任务基本跑完再执行避免和静态检查的结果冲突。这个小调整虽然简单但对实际使用体验改善很大。6.2 评审历史要保留方便对照Hermes 每次评审都会把结果写一份 JSON 到 workflow 的 artifact 里包括评论内容、分级、涉及文件。这份历史非常有用一是做质量回溯看看评审建议被采纳了多少二是做系统优化统计哪些规则触发的评论最多、哪些评论被开发者关闭。没有这份数据后面调规则就只能靠感觉了。建议至少保留 30 天的 artifact 历史。6.3 token 成本要盯着自动化评审跑起来之后token 消耗是个不太起眼但没法忽视的问题。一个 500 行的 PR加上 diff 输入、提示词、模型输出一次评审可能要消耗几万 token。团队 PR 多的时候一个月下来费用是看得见的一笔支出。我的控制方法是只评审新增和修改的行过滤掉纯格式变更的文件规则文件本身单独维护不让模型每次去读整个仓库文档太小的 PR比如只有一行改动直接跳过评审。这样整体成本能降一半以上。另外提醒一句尽量给机器人账号单独申请 API Key别用个人账号的 Key。一方面是便于统计成本费用另一方面是避免个人额度用完影响自己的开发工作。6.4 后续还可以怎么扩展这套系统目前已经稳定跑在团队的主仓库上。它最大的价值其实不在“省了多少评审时间”而在于给团队提供了一条稳定的代码底线——每份代码合入主干之前都被认真看过了。后面我还打算做两件事一是让 Hermes 能跟着人的评审反馈学习比如开发者对某条评论点击“不采纳”时把这个信息回流到配置里让模型下次调整判断二是把评审范围从代码扩展到设计文档和接口契约让 PR 描述里的方案说明也能被自动检查。从我个人的实际体验来说最深的体会是自动化评审能不能用起来七成靠配置和规则设计三成靠模型能力。花在打磨规则文件上的时间比花在折腾框架上的时间回报高得多。如果你也想给团队上这套能力建议先从一个小仓库开始跑两周攒数据再逐步推广到核心仓库。磨刀不误砍柴工这套流程值得你花一个下午搭起来。
