做代码评审的人应该都有过这种经历辛苦写完了功能提交 PR结果 reviewer 两天后才来一句“这里是不是少了个空指针判断”又或者一个仓库里同时挂着 20 个待审 PR谁都不敢合并怕把主干搞坏。我一直想找一种方式把“读 diff、找问题、写评论”这种机械劳动交给程序让人的精力只留在决策层面。后来我把 Hermes 这个智能体框架接到 GitHub 仓库里用 DeepSeek 这一档的大模型做推理引擎搭了一套自动化 PR 审查流水线。这篇文章把这套方案完整拆开从为什么需要自动化评审到 Hermes 的安装部署、GitHub 接入、提示词设计再到线上跑起来之后会踩的坑全部来自我实际操作的记录。1. 先把自动化PR评审这件事想清楚1.1 人工评审为什么这么“贵”评审成本高不只是时间问题。一个中型仓库一次 PR 平均改动 300 到 600 行reviewer 要把上下文从几个文件里拼出来才能判断“这个改动有没有引入回归”。如果这位 reviewer 同时还在改自己的分支每次上下文切换至少要十几分钟。赶上一天七八个 PR注意力基本废掉后面几个 PR 纯粹是“扫一眼就过”。这还不算沟通成本。意见写得不明确作者再追着问来来回回几轮一个合并能拖三四天。我见过最夸张的例子一个 200 行的 PR 从提交到合并用了两周10 个 review 评论里有 7 个是“这里为什么要改”“这个变量名是什么意思”——这些问题本来可以在提交说明或代码注释里解决。自动化评审解决的正是这段“高频、重复、消耗注意力”的部分。它不会疲倦不会因为下午三点的会议而丢三落四也不会因为和作者关系好就放水。它可以作为第一道防线先把明显的问题拦下来让人类 reviewer 的注意力放到架构和产品层面。1.2 自动化评审的边界在哪里我见过不少团队对自动化评审抱有极高期待觉得上了 AI 就能完全替代人工这是一个危险的误解。先说它能做什么格式规范、代码风格一致性。只要你把仓库的规范喂给模型它就能检查命名、缩进、结构这类问题。密钥泄露扫描。.env 文件入库、代码里硬编码 token、日志里打出了密码这些是可以用规则准确识别的。明显的空指针、未处理错误、资源未关闭。对于主流语言大模型能从 diff 里看出这类问题的概率很高。重复代码提示、测试缺失提醒。模型知道“这段逻辑在另一个文件里已经出现过”这是语义层面的能力。按仓库历史总结“这类改动曾经出过什么事故”。如果模型能读 issue 和 commit message效果会进一步放大。不能做什么架构合理性判断、产品需求取舍、跨模块深逻辑推理。举个简单例子某个查询从 A 库迁到 B 库代码层面完全成立但可能因为网络分区导致超时这种依赖真实运行环境和业务背景的判断模型给不了可靠结论。所以它的定位是“评审助手”。上线时只该以 comment 或 request changes 形式给建议绝不该做成“自动合并”。这句话我在后面实操部分还会反复强调因为真的有人踩过这个坑。2. Hermes智能体适合做评审工作流的框架2.1 Hermes 不是某个“开箱即用的插件”如果你去 GitHub 上搜 hermes agent或者直接搜 hermes 官网、deepseek hermes 这类关键词会看到很多变体项目。有些叫 hermes-agent有些直接叫 deepseek hermes本质上就是用 Hermes 框架去包装 DeepSeek 的 API。这个领域迭代非常快我建议以你找到的那个官方仓库文档为准我这里讲的是通用设计思路。Hermes 可以理解为一个“智能体编排框架”。它只给骨架真正干活的模型和工具都由你指定。核心概念包括 agent、skill、任务流。一个 agent 等于触发条件加上模型调用再加上工具调用和输出动作。拿 PR 审查这个场景来说一个审查 agent 可以是“收到 pull_request 事件拉取 diff调用 DeepSeek 分析把结果写成评论”这就是一个典型的 Hermes 任务流。它不是靠什么魔法实现的每一步都需要你自己配置。框架给你的是连接器和调度机制比如怎样监听 GitHub 事件、怎样调用模型 API、怎样把工具输出带回来。换句话说如果你理解的“开箱即用”是装完就跑那 Hermes 会让你失望但如果你要的是“按自己的业务流程自由编排”那 Hermes 就是合适的底座。2.2 为什么是 Hermes 而不是纯脚本或 Copilot可以直接回答一个很多人会问的问题我为什么不写个 Python 脚本去拉 diff再调一下模型 API非要引入一个 agent 框架纯脚本做规则匹配还可以一旦要生成“这块逻辑命名不够清晰”“这处改动可能影响旧接口的兼容性”这种需要语义理解的意见脚本就死了。你得自己处理 webhook 签名验证、重试机制、并发排队、模型输出解析、评论幂等这些跟审查本身无关的活会占掉一大半工作量。Hermes 的价值在于把这些通用能力预置好了你只需要专注在业务逻辑。至于 GitHub Copilot它更偏 IDE 内的补全和聊天是给单个开发者用的适合个人编码阶段。Hermes 这种 agent 可以放在服务端面向整个仓库团队所有人都能看到同一份自动审查意见。两者完全不冲突我自己甚至会在 Hermes 里把 Copilot 的能力也串进去当作一个代码搜索补充工具。如果你要做一个对比可以这样理解对比项纯脚本GitHub CopilotHermes 大模型语义理解弱强强自动化流程编排自己写不支持内置面向对象特定的脚本任务单个开发者团队/仓库/CI维护成本高所有东西自己管低但边界固定中需要配置 agent扩展性低低高skill 可复用3. 一条PR事件怎么变成一条审查评论3.1 流水线的六个环节一条 PR 从创建到收到自动审查意见中间要经过六个环节。每个环节都可能出问题我在第五章节里会详细讲排查这里先把流程说清楚。第一个环节是触发。GitHub Webhook 收到 pull_request 事件或者 GitHub Actions 在 opened 和 synchronize 事件上启动。一般只处理这两个事件一个代表新 PR一个代表提交更新避免重复跑。第二个环节是获取变更。调用 GitHub REST API 拿到 PR 的 commits 和 files把每个文件的 diff 取下来。这里有个细节对于超大 PR一定要先算文件数量和总行数超过阈值就走截断策略否则后续步骤会非常慢。第三个环节是组装上下文。把 PR 描述、改动文件路径、diff、仓库约定拼成模型输入。这一步很关键因为模型没有任何背景知识如果你不告诉它“这是一个支付系统的订单服务”它的审查意见就会飘在表面。第四个环节是模型推理。Hermes 调用配置好的大模型接口这里我用的是 DeepSeek。模型会按照你在提示词里定义的格式输出意见。第五个环节是解析结果。把模型输出解析成评论条目每条包含 severity、file_path、line、message。大部分模型只要提示词写得好都能输出结构化 JSON解析就简单了。第六个环节是回写。通过 GitHub API 创建 review或者写 check run把状态标记为 neutral 或 failure。如果你希望 PR 列表里能看到红色叉号就需要用 check run而不是普通评论。3.2 先做两段式审查别想着一步到位刚开始搭的时候我犯过一个错误想把所有问题一次性交给一个 agent 解决结果模型又审安全漏洞又审代码风格又审业务逻辑最后每个维度都浅尝辄止。后来我拆成两段式。第一段做快速门槛密钥泄露、.env 文件入库、构建文件乱改、依赖版本异常这些可以用规则引擎或轻量模型处理秒级完成。第二段做深度评审逻辑正确性、安全风险、性能隐患、可维护性。两段结果可以合并成一份 review也可以拆成两条评论。实际效果是快速门槛能拦截大量低级错误。比如有人把 AWS AK 直接写在配置里这种问题不需要大模型一个正则就能扫出来但人在 review 时反而容易忽略因为注意力全在业务逻辑上。深度评审则负责给人类 reviewer 提供候选问题点。两段式的好处是各司其职快速阶段稳定快速深度阶段灵活聪明。3.3 关键选型Webhook 常驻服务还是 GitHub Actions这个问题几乎每次接入评审 bot 都要面对。我做过两种方案给你一个选择建议。Webhook 常驻服务需要自己部署一个后端服务GitHub 在事件发生时把数据 POST 给你。优点是完全可控状态可以缓存任务可以进队列多仓库场景很好用。缺点是你需要自己承担运维工作部署、监控、失败重试全都要处理。GitHub Actions 则简单得多直接在仓库里放一个 workflow 文件事件触发时直接跑一个任务。优点是不用单独维护服务失败重试机制由平台托管。缺点是大 PR 场景下容易踩超时限制而且平台间的 Cache 和日志不便于跨仓库复用。我个人的建议是先在 Actions 里把流程跑通确认审查质量能接受后再迁到常驻服务。很多团队最终会选择常驻服务因为它要承载多个仓库的 PR还要控制并发和成本Actions 更适合做轻量集成和验证阶段。4. 从零搭一套Hermes PR审查服务4.1 环境准备与基础安装以 Python 环境为例我用的 Hermes 发行版需要 Python 3.11 以上。安装分两层一是 Hermes 框架本体二是它依赖的 GitHub 客户端和模型 SDK。大致命令是这样git clone 你的Hermes项目仓库地址 cd hermes python -m venv .venv source .venv/bin/activate pip install -r requirements.txt如果你要的是纯 pip 方式也可能直接执行pip install hermes-github但具体包名在不同发行版里会有差异一定要认准你那个仓库的官方文档。别嫌我啰嗦这个领域项目迭代太快直接抄别人的命令不一定能跑通。安装完成后配置环境变量。模型 API key、Base URL、GitHub token 这些都要配但绝对不能写进仓库代码里要用 CI 变量或部署平台的密钥管理。我习惯在项目根目录放一个.env.example文件做模板真实密钥放在本地.env并在.gitignore里把.env忽略掉这样队友拿到代码也知道要配什么。如果你用 Anaconda 管理 Python 环境需要确认 channel 配置是否正常避免装包时解析不到。这块和 Hermes 没有直接关系但环境不通会浪费很多时间。4.2 接入 GitHub 并配置最小权限接入 GitHub 有两种方式个人访问令牌Personal Access Token和 GitHub App。个人访问令牌配置简单适合本地测试但不要拿它跑生产任务更不要把带 write 权限的 token 放在开发者笔记本上。推荐用一个独立的 bot 账号或者上 GitHub App。无论哪种方式都要遵守最小权限原则。一个 PR 审查 bot 需要的最小权限是pull requests: read/write用来读 PR 和写评论。checks: write用来创建 check run。contents: read用来读文件内容。不需要 admin 权限不需要管理仓库设置。如果你看到某个教程让你把repo全选那基本是不负责任的。如果做 Webhook 常驻服务需要在 GitHub App 里设置 Webhook secret回调地址填你的服务地址。这个 secret 要保存好服务端每次验签才能确定请求真的来自 GitHub。4.3 编写审查规则与提示词模板提示词质量直接决定审查质量。我给的模板经过几轮迭代你要用可以直接抄你是一名高级代码评审工程师。请审阅以下 PR diff。 要求 1. 只针对本次改动行给出意见不要对未改动代码发散。 2. 每条意见必须包含文件、行号、严重级别critical/warning/suggestion、问题描述、修改建议。 3. 如果发现密钥、敏感信息、明显安全漏洞标记为 critical。 4. 已经由 CI 检查过的格式问题不要重复提出。 5. 输出必须是可以解析的 JSON 数组不要输出其他文字。 PR描述... 组件背景... diff ...这里有三个关键点值得展开说。第一“已经由 CI 检查过的格式问题不要重复提出”这句话非常重要。仓库里往往已经跑了 ESLint、gofmt、black 这类工具如果你不告诉模型它会和静态检查工具打架重复报各种格式问题评论噪声极大。第二强制输出 JSON 数组。模型输出自由文本时解析就是一场灾难。你会在第五章节看到我踩过的坑。输出格式约束住了后续处理才能稳定。第三提示词里放一段“组件背景”非常有用。比如“这是订单模块改动涉及库存扣减”模型对陌生仓库的准确性会大幅提高。每次 PR 可以把对应的模块描述拼进来几行字就能带来明显效果。4.4 把服务跑起来Webhook 与 Actions 两种落地方式先看 Webhook 方式。一个极简的 FastAPI 服务长这样from fastapi import FastAPI, Request from hermes_github import create_review_from_diff app FastAPI() app.post(/webhook) async def webhook(req: Request): payload await req.json() event payload.get(action) if event not in (opened, synchronize): return {ok: False, reason: ignored} pr_number payload[pull_request][number] repo payload[repository][full_name] # 这里建议用消息队列异步处理避免 GitHub webhook 超时 await create_review_from_diff(repo, pr_number) return {ok: True}真正耗时的评审逻辑一定要放到队列后端不要在 webhook 回调里做同步推理。GitHub 对 webhook 响应时间是有要求的如果你同步跑一次大模型推理很可能被断连之后 GitHub 会重试结果评论被重复创建。再看 Actions 方式。workflow 文件大致是这个样子name: hermes-pr-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Hermes Review env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} LLM_API_KEY: ${{ secrets.LLM_API_KEY }} run: | hermes review --diff-modegit注意一个细节actions/checkout 之后如果要拿到完整 diff建议加fetch-depth: 0否则 shallow clone 会裁掉部分提交历史diff 可能不完整。这个问题我至少遇到三次。4.5 上线前一定要做的三件事第一所有自动评论加固定签名“该评论由 Hermes 自动生成请在合并前人工复核。”这能避免 bot 意见被误当成人类意见也能让作者和 reviewer 知道评论来源。第二设置 review 状态为 COMMENTED或者明确使用 check run 的 neutral 状态。不要让 bot 直接 APPROVED尤其是关键分支。一旦 bot 批准变成了常规团队会逐渐丧失人工把关的意愿。第三灰度发布。先在 draft PR 或者带指定 label 的 PR 上运行比如仓库里存在hermes-review这个 label 才触发。跑稳了再全量放开。这个策略在自动化系统里永远是安全的默认选项。5. 常见问题与排查实录5.1 评论延迟、重复评论与评论丢失延迟大多来自模型响应时间长。如果模型接口超时GitHub 会重试 webhook于是可能产生重复评论。解决重复问题有两个层面。第一层幂等。在创建评论前先查一下这个 PR 里有没有已经存在的同一条评论。GitHub API 支持GET /repos/{owner}/{repo}/pulls/{pr}/comments你可以按 bot 标识符和 diff 内容的 hash 来判断是否已经评过。第二层失败重试。消费失败后进消息队列重试而不是直接丢弃事件。不要小看这层丢了审核事件等于这个提交没有任何 bot 意见对配置了“必须 check 通过才可合并”的仓库来说会卡住整个流程。还有一个实际坑GitHub API 创建 review 时line参数在部分场景下对应的是 diff position不是文件全局行号。如果你传错了评论会跑到别的代码行上去。处理方法很简单先从pulls/comments接口拿回 diff position 和实际行号的映射再决定把意见写到哪。5.2 模型审得太浅或太啰嗦模型输出质量跟提示词强相关。太浅通常是因为没有给模型足够的背景。人看代码知道这是支付模块模型如果不知道就会给出“这段代码是否考虑空值”这种泛泛而谈。你把组件背景描述塞进提示词后意见质量会有明显提升。太啰嗦则是约束不够。可以加三句话最多输出 10 条意见、每条意见不超过 100 字、不要夸奖代码。很多模型在无人约束时会输出一堆“代码整体写得很好”“建议补充注释”这样的废话。温度参数也很关键建议调到 0.2 以下减少发散。如果还是弱考虑换更强的模型。模型能力是瓶颈时换 API 比调提示词更高效。5.3 长 diff、大 PR 与资源开销大 PR 是个绕不开的问题。几千行的 diff 全部塞给模型既不经济又容易触发上下文截断。我的策略是分层处理。第一对文件排序优先审核心代码文件。像package-lock.json、go.sum、自动生成的文件直接跳过。第二按文件拆分进行多次推理再做归并。每个文件单独审能让模型注意力更集中也方便解析。第三设上限。比如超过 800 行时只审新增行或者只审前 N 个高风险文件。成本控制上用“只审新增行加上下文少量行”的方式比全文件便宜很多。我做过一个对比同一个 PR 用全文件审查和用新增行审查模型给出关键问题几乎没差别但 token 消耗差了将近一半。对于资源敏感型团队这个优化非常值得。5.4 权限、安全与误操作风险这一节看起来是讲排查其实是强调红线。bot 账号或 token 权限过大的隐患在团队里常常被忽略直到出事故才重视。不要把有仓库写权限的 token 放在开发者笔记本上也不要真把 bot 的自动批准权限打开。如果有人把 Hermes 审查结论当成自动合并依据那迟早会出事。理由很简单模型会误判规则会过期仓库的背景会变化最终责任人一定是人不是 bot。在做安全配置时我还有一个习惯对 GitHub App 设置只允许安装到指定仓库。多一步限制少一分风险。团队大了以后仓库越来越多如果每个新增仓库都能自动安装 bot一旦某个仓库的权限配置不当影响面会迅速扩大。6. 从PR审查开始还能往哪里延伸6.1 把规则沉淀成 SkillHermes 里可以定义 skill把“密钥扫描”“规范检查”“安全提醒”这类能力封装成可复用的模块。这看起来很抽象但实际价值很大。比如你给“密钥扫描”做了一个 skill下次不只是 PR 审查能用issue 里有人贴配置信息、文档里有人提交敏感信息甚至新成员入职时的仓库初始化检查都可以复用同一个 skill。团队新成员上手也会快很多。他不需要理解整套审查流程只需要知道“这个 skill 是查密钥的那个 skill 是查测试覆盖的”就像搭积木一样。官方文档里通常会有 skill 的编写示例照着写第一个 skill 大概半小时就够。6.2 从审查助手变成仓库管家一旦这套流程稳定下一步可以接更多事件。我在生产环境里陆续接了几件事新 issue 自动打 label、release 说明自动生成、过期 PR 自动提醒。有人用 Hermes 写了一个“仓库周报 agent”每周把合并统计、风险清单、待处理 PR 汇总到团队群里非常实用。这些扩展和 PR 审查共用同一套基础设施新增一个 agent 只是多配置一个触发条件和输出动作的问题。框架前期投入的成本会被逐渐摊薄。我个人在实际操作中最大的体会是自动化评审跑起来之后最明显的不是“PR 合并变快了”而是 review 的质量稳定了。之前总靠某几个核心开发者扛着现在至少有个 bot 在每一行改动后面先垫一遍底。大家省下来的时间反而用在了最需要人的讨论上。如果你也想搭这套东西我的建议是不要一上来就追求全自动先把“能读 diff、能评论”这个最小闭环跑起来再慢慢调规则。跑起来之后你会发现真正值得机器干的事比想象中多得多。