用Hermes Agent自动化GitHub PR审查：部署指南与实战避坑

我维护的几个开源项目，这几年最让我头疼的其实不是写代码，而是review别人的PR。一个中型项目，每个PR平均要改二三十个文件，等CI跑完、一行行过diff、再对着PR讨论半天，基本一个上午就没了。更要命的是，人看代码会有状态波动，累了就容易漏掉潜在问题。所以我一直在找能把"初筛"这件事自动化掉的东西——不是那种只查空行和分号的Lint工具，而是真正能读懂代码逻辑、看出设计问题的助手。

我从上个月开始系统性折腾Hermes Agent，配合DeepSeek的API做了一套自动化GitHub PR审查的流程。说人话就是：PR一提交，Hermes自动拉取diff、结合项目规范和模型能力做一轮代码评审，把踩坑点、潜在bug、安全隐患直接评论到PR下面。用下来的感受是：它不能替代人工终审，但至少能帮我把80%的机械性检查工作干了。这篇文章我不讲广告词，只讲我怎么从零部署、怎么接入GitHub、怎么把审查规则调到能用，以及这一路踩过的坑。

1. 为什么我决定把PR审查交给Hermes：代码评审的痛点与自动化思路

1.1 代码评审的真实痛点

先说一个大家心知肚明的问题：代码评审这事，做得认真还是敷衍，差别非常大，但它的成本又高得离谱。我统计过自己一个中等规模的前端仓库，单次PR从打开到合入，reviewer平均需要花40分钟到1小时，而且这是在没有历史包袱的情况下。如果碰上改动的模块涉及多个团队、跨服务调用，这个时间还会翻倍。

另一个经常被忽略的问题是"评审质量不稳定"。同一个人在上午九点和下午四点看同一段代码，给出的意见深度完全不一样。我见过不少PR在合并之后几天才被人发现少处理了一个边界情况，而那个边界在评审时其实就摆在眼前，只是当时没人注意到。

传统的静态检查工具（ESLint、SonarQube、CodeQL）能解决的是规则类问题，比如未使用的变量、明显的反模式、已知漏洞的CVE匹配。但它们对"这个函数的抽象边界是不是合理""这次改动会不会影响另一条链路"这类语义性问题无能为力。这些问题恰恰才需要人反复看，也恰恰是最耗时的。

1.2 Hermes到底是什么角色

我在调研自动化评审方案时，一开始关注的是那种专门做Code Review的SaaS服务。它们往往很贵，而且代码要经过第三方云，很多公司过不了合规那一关。后来我注意到Hermes Agent这个方向——它是一个Agent形态的智能体框架，而不是一个吃死规则的静态分析器。

它的工作方式在设计上就跟传统工具有本质区别：你可以把Hermes接入GitHub，当一个PR出现时，它会通过GitHub API获取PR的完整上下文——不光是diff，还有提交信息、关联Issue、被改动文件所在模块的历史变更——然后把它整理成一个大模型能理解的结构化输入，再调用模型（我接的是DeepSeek）逐文件做推理分析，最后把审查意见作为PR评论发回去。整个过程不需要开发团队把代码同步给任何第三方平台，数据链路是你自己的服务器到模型API，可控性更强。

我后来在团队内部做了一次对比测试，同一批PR分别用SonarQube和Hermes跑，结果显示Sonar对死代码和配置错误的捕获更稳定，但Hermes能在"改动是否会破坏现有调用方""新加的异常处理是不是吞掉了关键错误"这类逻辑性问题上给出有用的提示。这两者其实不是替代关系，Hermes更适合做"人工评审前的语义初筛"。

在动手部署之前，建议你先想清楚一个问题：你希望它做"全自动拍板"，还是"人机协作的初筛"？我强烈建议后者。后面所有配置思路，我都默认你和我一样，把Hermes定位在"先替我过一遍、再把有价值的发现标出来"的角色。

2. 自动化PR审查的核心设计：从diff理解到Skill机制

2.1 机器要理解一个PR，难点在哪

要让AI把代码评审这件事干好，首先要理解这件事的输入边界。一个PR的diff虽然有几十上百个文件，但很多文件往往只是格式化、挪位置、加注释，真正的逻辑变化可能集中在三四个关键文件里。模型如果平铺直叙地读diff，很容易被大段的纯格式变化带偏，把注意力放在无关紧要的行上。

所以第一步是"信息压缩"。我在配置里做了两件事：一是让Hermes只针对发生结构性变动的文件做深度分析（通过文件变更统计来判断，比如删除行数超过文件总行数30%的，或者有新增函数定义的）；二是把PR的描述、提交信息和关联Issue拼进上下文，让模型先知道"这次改动想干嘛"，再去对照diff看"有没有做对"。这个"意图对齐"环节非常重要，没有它，模型经常会在评论区问一些"你为什么要改这个"的废话。

我举一个真实的例子：有个PR的描述写的是"修复订单超时问题"，改动涉及订单服务和定时任务两个模块。Hermes拿到这个意图之后，会重点检查两个模块的改动是不是都围绕超时问题展开，而不是孤立地给每个文件挑语法毛病。这样产出的审查意见明显更接近一个懂业务的老同事会说的话。

2.2 Hermes的Agent-Skill机制

我理解的Hermes核心设计是"Agent + Skill"。Agent负责调度、规划、跟外部工具交互；Skill是具体的一项能力，比如"代码审查""生成单元测试""解析日志"，每个Skill会定义自己的输入输出格式和触发条件。PR审查就是这样一个Skill。

这个抽象的好处是，你不用每次写死一个脚本，而是在Skill内部组织好几轮"观察-分析-输出"的循环。比如审查一个PR时，Skill会先拉diff，然后调用一次模型判断"哪些文件值得深看"，再针对重点文件逐文件发第二次分析请求，最后汇总生成统一的review意见。整个过程对使用者是透明的，但你可以通过调Skill的prompt模板来控制它怎么思考、重点查什么。后面讲规则定制时我会给具体的配置。

2.3 三种接入方式怎么选：Actions、Webhook还是CLI

Hermes挂在GitHub上有几种接法，适用场景完全不同：

• GitHub Actions方式：在仓库里加一个workflow，当PR被标记为synchronize或opened时触发，临时环境里跑一次Hermes，再把结果通过GitHub API写回评论。优点是事件驱动、零常驻进程，适合大多数托管在GitHub上的公开或内部仓库。
• Webhook方式：自己起一个常驻服务，接收GitHub发来的Webhook事件再做处理。适合私有化部署、需要对多个仓库统一管理，或者你想在Hermes输出结果后接一个通知到IM的场景。
• 纯CLI方式：把Hermes当成手动命令，在本地跑一下作为给自己的辅助检查。适合我这种周末开源项目，不想配一堆远端权限的时候。

我用的是Actions方式，因为它不用维护一台常驻服务器，workflow的触发逻辑也清晰，出问题还好排查。后面第三章、第四章就是围绕这个方式展开的。

3. Windows部署Hermes Agent：安装步骤与避坑记录

3.1 环境准备

我平时主力机是Windows 11，所以这次全程在Windows上部署，也踩了不少Windows特有的坑。先列一下环境清单：

• Python 3.10以上版本，我实际用的是3.11（Hermes的依赖里有部分C扩展，太老的Python版本会编译报错）。
• conda作为虚拟环境管理（也可以直接用venv，但我习惯conda，用来隔离依赖很方便）。
• Git for Windows（需要用到git命令解析diff内容）。
• Docker（可选，如果你不想在当前环境里装一堆依赖，可以直接拉Hermes的镜像跑。不过我是在conda环境里直接装的，后面再单独说Docker方式）。

创建环境的时候有个小技巧，直接用国内conda镜像切到清华源，速度会快很多。我环境里那个channels配置是：

channels: - defaults - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/

然后执行：

conda create -n hermes python=3.11 -y conda activate hermes

3.2 安装Hermes及依赖

Hermes的安装我建议在干净的虚拟环境里做，避免和别的项目依赖打架。执行安装：

pip install hermes-agent

如果你网络环境下载慢，也可以把pip源切到国内镜像：

pip install hermes-agent -i https://mirrors.aliyun.com/pypi/simple/

装完之后执行一下自检命令确认能跑：

hermes doctor

这个命令会检查模型API配置、GitHub Token是否有效、核心依赖版本等，我建议第一次跑的时候一定认真看一下输出。如果提示缺某个模块，就用pip装。

如果你想用图形界面管理配置和Skill，可以顺手装一个Hermes Studio的桌面端；它在Windows上有安装包，界面能直接看到任务队列和审查日志。不过我个人在实际部署时更习惯先CLI，因为方便在Actions里复现同一条命令。

3.3 配置DeepSeek模型

Hermes本身不提供模型算力，需要你自己配置一个大模型API作为"大脑"。我用的DeepSeek，一是因为API价格相对实惠，二是它在代码理解和变更分析这类任务上的效果我看到不少正面反馈。配置方式是在Hermes的配置目录（一般在用户目录下，也可以在项目目录里建配置文件）设置模型相关参数，大致长这样：

model: provider: deepseek api_key: sk-xxxxxxx model_name: deepseek-chat temperature: 0.2 max_tokens: 4096

这里有个细节：temperature我故意调低到0.2。代码审查需要的是稳定、可复现的判断，而不是发散式的创意，temperature高了会经常给出"其实也可以考虑用xx模式重构"这类似是而非的建议。

API Key建议通过环境变量注入，不要硬编码在仓库里。我后面在GitHub Actions里也是通过Secrets传入的。

3.4 Windows上安装时的特有坑

这里分享几个我在Windows上实打实踩过的坑，你在部署时大概率也会遇到：

第一个是conda环境激活后在PowerShell里执行hermes命令报"无法加载（因为在此系统上禁止运行脚本）"。这是PowerShell的执行策略问题，临时放开当前会话的权限就行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

第二个是某些依赖库在Windows上需要Microsoft C++ Build Tools，如果你在安装阶段看到"Microsoft Visual C++ 14.0 or greater is required"的红色报错，去装一下Build Tools并勾选"使用C++的桌面开发"工作负载，然后重新装依赖就能过去。

第三个是路径问题。Hermes默认会把审核工作目录、缓存都放在用户目录下，如果你的Windows用户名是中文，某些依赖解析路径时可能会出问题。建议安装时额外配置一个纯英文路径的临时目录和缓存目录，能省很多麻烦。

4. 接入GitHub并跑通第一单PR自动审查

4.1 准备一个有权限的GitHub Token

要让Hermes读PR、写评论，需要在GitHub上创建一个Personal Access Token（PAT），或者更安全地创建一个GitHub App。个人项目我建议直接用Fine-grained PAT，权限只勾你需要的仓库范围，别图省事用老的full-token方案。

在GitHub设置里新建PAT时，仓库权限至少勾这两项：

• Pull requests: Read and write（Hermes要读取PR信息和提交评论）
• Contents: Read（读取diff和仓库文件）

生成后把Token复制出来，先在本地环境变量里用KEY的名字存好，比如：

$env:GITHUB_TOKEN="ghp_xxxx"

4.2 初始化项目级配置

为了让Hermes在不同的仓库里有不同的行为，我会在每个项目仓库里放一个配置文件。以一个Node.js项目为例，配置长这样：

provider: github token_env: GITHUB_TOKEN review: enabled: true review_depth: full comment_mode: single rules: - id: no-magic-number pattern: banned-number level: warning

这里面的review_depth有两个可选值：full表示分析整个PR，fast表示只挑关键文件看。我平时用full，因为PR数量不多，宁可慢一点也不想漏。comment_mode选single意思是把整个review汇总成一条评论，避免刷屏。

rules那一段是自定义规则的雏形，后面我会讲更完整的规则玩法。有一点要说明：在Actions模式下，触发逻辑主要由workflow的on字段控制，这个配置主要负责审查行为本身；如果你用的是Webhook或常驻服务模式，才会用到auto_trigger_events这类触发配置。

4.3 在GitHub Actions里跑Hermes

接下来就是把Hermes挂到GitHub Actions。在仓库的.github/workflows目录下新建一个文件，内容大概是这样：

name: Hermes PR Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install Hermes run: pip install hermes-agent - name: Run Hermes Review env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} run: hermes github-review --repo ${{ github.repository }} --pr ${{ github.event.pull_request.number }}

这里有两个容易出问题的点。第一，fetch-depth: 0必须加上，否则Actions默认拉的是浅克隆，Hermes拿不到完整的git历史，分析"这个PR是不是重复了之前已修过的bug"时会缺少依据。第二，GITHUB_TOKEN直接用secrets.GITHUB_TOKEN就行，GitHub在Actions环境里会自动生成，不用自己费劲创建PAT，但如果你的Hermes配置里要用的Skill需要以仓库身份做更多操作，那还是需要自己准备一个有额外权限的Token放到Secrets里。

4.4 第一单自动审查的完整流程复盘

配置完成后，我随便开了一个测试PR，故意在里面放了几个常见问题：一个不判空的数组访问、一个遗留下来的console.log、一段没有对应单元测试的逻辑分支。然后看着Actions跑起来。

实时的执行日志大致是这样：

[info] pull request #42 detected [info] fetching diff: 12 files changed, +340 -87 [info] preparing context: issue #41, commit messages [info] analyzing file: src/services/order.js [info] analyzing file: src/utils/validator.js [info] generating review summary [info] posting comment to PR #42

大概两分多钟后，PR下面出现了一条Hermes的评论，分成"高危问题""建议优化""提问"三个板块。三个故意埋的点，它逮到了前两个，没看到单元测试缺失那条是我没在配置里要求它检查测试覆盖，这个后面说。整体上输出格式比我想象的清楚，没有出现一堆废话建议。

5. 让Hermes更懂你的项目：规则配置与Prompt调优

5.1 通用审查维度怎么落地

默认情况下Hermes的PR审查Skill会覆盖几个通用维度：

• 语法与运行时错误：例如可能抛出的空指针、数组越界、明显的类型不匹配。
• 逻辑正确性：例如条件判断倒置、返回值顺序错误、循环边界问题。
• 安全风险：例如把未验证的用户输入直接拼进SQL、敏感信息硬编码。
• 性能隐患：例如在循环里发HTTP请求、大数组无谓拷贝。
• 可维护性：例如重复代码、过深的嵌套、命名完全无意义的变量。

这些维度不需要你写代码实现，它们是靠prompt层面的知识表达出来的。也就是说，审查质量高度依赖你给模型的上下文是否充分。我发现一个有效做法：先在项目根目录维护一个CONTRIBUTING.md或docs/review-guideline.md，把团队自己的约定写清楚，然后在Hermes配置里把这份文档的路径挂到"项目规范引用"字段。这样每次审查时，Hermes会把这份文档作为背景知识喂给模型，效果比你在prompt里零零散散地写十条规则好得多。

5.2 项目规范定制实操

我举个我真正用过的例子。我的一个Python仓库要求所有对外接口必须做参数类型校验，并且禁止在业务代码里出现裸的except。我把这个要求写进项目规范文件，然后Hermes配置里这样引用：

review: guideline_file: docs/review-guideline.md extra_instructions: | 1. 重点检查是否有裸except，如果有必须标记为error。 2. 检查所有标记为public的接口是否有类型校验，没有则标记为warning。 severity_threshold: warning

这样配置之后，新PR再进来，它给出的意见会更贴合我们仓库的实际情况。我强烈建议你花一点时间把项目里最重要、最容易踩的3到5条规则先写上，不要一上来就列二三十条，否则模型注意力分散，关键规则反而不突出。

5.3 控制误报率的几个参数

AI review最让人头疼的就是误报和废话建议。我调过一轮之后，经验是这几个参数影响最大：

• temperature：前面说过，压到0.2左右，稳定优先。
• max_tokens：不要给太少，否则审查意见写到一半被截断；也不要给太多，我用4096基本够一个中大型PR的汇总。
• comment_mode：尽可能用single模式，一条汇总评论而不是逐文件刷评论。
• review_depth：如果仓库PR特别频繁，建议用fast模式先跑，发现可疑点再人工跟进。

另外一个很重要的心得是：PR审查的输出格式最好固定成结构化的markdown块（比如"高危/中危/建议"三栏），这样你自己写个小脚本或者人工浏览时都能快速定位。我在配置里通过prompt把输出模板固定下来，实测下来，模型的输出稳定性会比自由发挥高很多。比如我要求每条意见必须包含"文件路径: 行号，问题描述，建议改法"，这样就方便直接跳转定位。

6. Hermes实践中的常见问题与排查实录

6.1 高频问题速查表

我整理了一张表，覆盖我遇到以及帮朋友排查过的高频问题。

6.2 Windows部署专属问题

Windows上跑Hermes，除了前面安装阶段那几个坑，运行时也有几个容易翻车的地方。

一个是路径分隔符。如果你在一个路径里给Hermes传了带有反斜杠的路径，部分解析diff的模块会对不上。我一般统一用正斜杠或者在Git Bash里运行命令来规避。

另一个是防火墙。如果你选择Webhook方式自建服务，Windows防火墙第一次会弹窗询问是否允许Python监听端口，记得放行。如果是个人测试机，干脆直接用Actions方式，不用开端口。

还有一点：如果你装了多个Python版本，conda激活环境后hermes可能还是会找到别的Python安装路径，这时候在环境里显式执行一下：

python -m hermes doctor

会比直接敲hermes稳定得多。

6.3 判断AI review值不值得信

最后说一下主观感受。我用了两三个星期之后，逐渐形成了自己的判断标准：不要把AI review当成"真理"，把它当成"一个快速但有时会过度联想的初级同事"。它对常识性错误的识别率很高，但对业务语义的理解有上限，尤其当项目里充满历史包袱和非典型写法时，它会给出似是而非的"重构建议"。

我的做法是：高危级别的意见我一定要亲眼看一下对应代码，中危的交给提交者自查，建议级的基本跳过。这样既不会被它带偏，也不会放过真正的风险点。

顺便说一个扩展方向：Hermes的Skill机制可以让你把同样一套流程复制到别的地方，比如用它在合并前自动生成CHANGELOG片段，或者对特定类型的改动自动补一个单元测试初稿。我把PR审查跑顺之后，下一步就是在项目里试这个方向。