我最后悔的一段时间就是让代码审查这件事完全靠人肉撑着。PR 少的时候还好团队过十个人、每天十几个 PR主程的时间基本就碎在“看代码、回评论、等人改、再看代码”这个循环里了。更要命的是很多问题光靠人眼扫很容易漏——比如某个接口的鉴权少了、敏感信息被打进日志、异常被静默吞掉。这些问题在 code review 的时候看过一遍往往还会在下一周以另一个姿势再出现。后来我把 Hermes 引进了团队的 PR 流程。它不是那种只能跑跑 lint 的花架子而是真正能做到“按规则分析、按上下文理解、按结果回帖”的自动化代码评审智能体。这篇文章就是把我在本地把 Hermes 部署起来、接入 GitHub PR 审查、跑通自动 comment 全过程的经验梳理出来从架构理解到实际配置、从提示词编排到误报调优尽量做到能让想复现的人直接照着做。适合看这篇内容的是我这类已经被重复审查折磨过的技术负责人、运维以及那些想在自己开源项目里引入免费自动化评审的个人开发者。如果你只是想给 PR 加个 status check那很多现成的 CI 工具就够了但如果你想让它像个真正的 reviewer 一样给出具体到行的修改意见Hermes 这条路值得走一遍。1. 为什么我最终放弃了“买现成”和“纯人肉”两条路1.1 现成评审工具的尴尬能发现问题但提不出建设性意见先说结论市面上不是没有 AI 代码审查工具我也都试过。问题在于大多数工具的“自动评审”停留在静态扫描和基础 lint 的水平顶多帮你找出“变量未使用”“import 排序不对”这类问题对于“这个查询在数据量大时会全表扫描”“这里的事务范围是不是太大了”这种和业务逻辑强相关的问题基本无能为力。还有一些商业工具确实带了 AI但第一价格不便宜第二它的审查逻辑是黑盒的你没法设置“本项目禁止用 GET 请求做删除操作”“Redis key 必须带项目前缀”这种特定审查规则。对团队来说规则库不能定制这个工具就永远只是锦上添花。1.2 纯人肉审查的成本比你想象中高得多我统计过团队一周的审查耗时结论让我自己都吓了一跳五个核心开发者平均每天花在 review 别人代码上的时间超过两个小时。这两个小时不是整块的而是零散的、碎片化的正好把写代码的心流切得稀碎。更关键的是人肉审查存在明显的“注意力递减”。一个 PR 里前面几处文件看得很仔细看到后面几处线程折叠、上下文不够就容易草草点个 Approve。而这些问题恰好是自动化评审最擅长的机器不会累不会因为看了三个小时就降低标准。1.3 Hermes 能替代的恰恰是那个“最费人工”的环节Hermes 这个项目最初吸引我的点是它的定位非常明确它是一个可以编排的 agent而不是一个固定行为的插件。它能读懂 diff 上下文能自己拉取完整的文件内容能调用外部工具的接口最后还能把结论以评论的形式写回 GitHub PR。也就是说它可以替代一个初级 reviewer 的工作检查风格、查漏补缺、跑静态检查、找潜在的逻辑漏洞然后把结论整理成人类 reviewer 可以直接复核的内容。人类 reviewer 不再需要从头看起而是只需要对 Hermes 给出的意见做判断这条说得对不对、该不该采纳。这个工作流的变化让整个团队的 review 效率至少提升了一倍而且规则定好之后所有 PR 的执行标准完全一致——这一点是人肉审查永远做不到的。2. Hermes 的核心模块拆解它到底是怎么“读懂”你的代码的2.1 从热词看 Hermes 的定位不只是模型而是 agent在搜资料和部署的过程中我注意到和 Hermes 相关的热词里出现频率很高的是“hermes agent”和“hermes智能体安装”而不是单纯某个模型名。这说明它的使用方式和我们平时理解的那种“聊天机器人”不一样它是一个能够调用工具、自我决策的 agent 框架。实际用下来的体会也确实如此。Hermes 的核心是一个任务编排引擎给它一个目标比如审查这个 PR 并输出意见它会自己拆解步骤先获取 PR 的 metadata再获取每个文件的 diff判断哪些文件需要读完整上下文必要时调用语言模型做推理最后汇总结果。整个链路都是可配置的。2.2 一层一层剥开Hermes 的四个核心组件我习惯把 Hermes 的架构理解成四层这样排查问题的时候思路会清晰很多组件职责我的比喻任务编排引擎把“审查 PR”这个大目标拆成可执行的子任务并调度它们的执行顺序项目经理工具调用层封装 GitHub API、文件读取、命令执行等具体能力让 agent 可以实际操作双手模型接入层对接底层语言模型支持多种 LLM 供应商负责把上下文送给模型并拿回结论大脑规则配置层通过配置文件定义审查规则、忽略路径、输出格式工作手册这四层中间任何一层出了问题表现都不一样。我在部署的时候踩过一个坑规则配置层写错了路径映射导致 Hermes 一直提示找不到文件但当时第一反应是去查网络层绕了一大圈才定位到问题。后面我会单独讲这个排错过程。2.3 它和 GitHub Actions 的关系不是一个东西但可以配合很多人在搜索“Hermes GitHub PR 审查”时会混淆一个概念Hermes 不是 GitHub Actions 市场里那种一装就能用的 action。它是一个独立的服务你需要部署它、配置它然后通过 webhook 或者 API 把它和 GitHub 连起来。当然Hermes 官方也提供了 GitHub App 的接入方式但那是把 Hermes 当成一个外部服务来订阅仓库事件。你完全可以跑在自己的服务器上这也是我推荐的方式——不把代码评审这种涉及核心代码的请求发到第三方封闭平台。下面这张表列出了我一开始纠结的三种接入方式的对比接入方式部署位置优点缺点GitHub Actions 调用 Hermes API仓库内配置简单日志直观只对该仓库生效不适合大规模推广独立服务 Webhook自建服务器一服务多仓库规则集中管理需要自己维护 webhook 接收端GitHub App 方式自建服务器权限粒度细安全性高首次配置繁琐需要注册 App我最后选的是第三种GitHub App 方式。原因很简单权限可控、不用在每个仓库塞配置而且后续想让 Hermes 自动回复评论、更新审查状态都需要 GitHub App 的更高权限。3. 部署 Hermes 的环境准备与可能踩到的坑3.1 硬件和系统建议不需要很强但内存别太小Hermes 本身是个轻量级服务但它要跑模型推理。如果你选择的是本地跑小模型建议至少 16GB 内存如果接的是云端 API比如 DeepSeek 这类那对本地资源的要求就低很多2 核 4GB 的云主机都够跑。我自己最开始踩了一个典型的坑在一台只有 2GB 内存的旧服务器上直接部署结果加载模型权重的时候 OOM 了日志里只看到进程被杀没有任何报错信息。后来加上 swap 才能勉强跑起来但延时明显变高。所以如果你也打算本地推理内存这事别省。3.2 安装步骤从拉取代码到服务跑起来Hermes 目前的安装方式比较统一核心就是拉代码、装依赖、配置环境变量、启动服务四步。以我部署的版本为例大致是这样git clone https://github.com/your-hermes-repo/hermes.git cd hermes python -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env环境变量文件是第一个需要认真对待的地方。至少需要配置三块内容模型 API 的 key、GitHub App 的私钥和 App ID、以及 Hermes 自己监听的端口。我之前图省事直接在 .env 里写了明文私钥虽然内网问题不大但还是建议用密钥管理工具或者至少设置好文件权限。接下来是启动方式。Hermes 提供了两种运行模式一种是常驻服务模式适合配合 webhook 使用另一种是一次性模式适合在 CI 里调用。前者用python main.py serve后者用python main.py review --pr 123。我平时本地调试先用后者确认规则没问题再切到常驻模式。3.3 Windows 上部署的特殊情况热词里有一条是“window系统如何部署hermes智能体比较合适”确实有人在 Windows 上卡住了。我的建议是如果只是做测试Windows 上直接跑 Python 环境是没问题的但遇到两个问题概率很高一是python命令需要从微软商店装二是路径分隔符导致的配置解析问题。我在 Windows 的 WSL 里跑过一次比原生 Windows 顺畅很多。如果你也是 Windows 环境推荐 WSL2 Ubuntu 的组合基本可以照搬 Linux 的部署流程。原生 Windows 也能跑但需要你把所有配置文件里的绝对路径都改成 Windows 风格很折腾不值得。3.4 服务启动后的自检清单启动成功不等于配置对了。我在本地验证时习惯按下面这个顺序做一轮自检输入curl http://localhost:8080/health能返回{status: ok}说明服务活着。用一个历史 PR 的编号跑一次review --pr看能不能正常输出审查结果。检查 Hermes 是否真的拿到了 GitHub API 的权限可以在测试仓库里创建一个草稿 PR看 Hermes 能不能读取 diff。如果第三步失败了大部分原因是 GitHub App 的权限配置不对。这个我们放到下一节细说。4. 接入 GitHub PR 审查一步步配置 GitHub App 和 Webhook4.1 创建 GitHub App权限是重中之重用 GitHub App 对接 Hermes是配置过程中最繁琐但也最关键的一环。登录 GitHub 后在 Settings - Developer settings - GitHub Apps 里创建新 App有四个地方需要特别注意首先是 Permissions 设置。Hermes 至少要拿到 Pull requests 的 Read Write 权限用来读取 PR 内容和写评论、Contents 的 Read 权限用来读取仓库文件以及 Checks 的 Write 权限用来把审查结果回写到 status check。缺少任何一项都会出现“能读不能写”或者“能读不能看 diff”的诡异问题。我遇到过的一个现象是Hermes 能正常输出审查结论但无法评论到 PR 上日志显示 403。排查了半天发现是 Permissions 里 Pull requests 只给了 Read没有给 Write。改了权限之后GitHub 要求重新安装一次 App 到仓库权限才会生效这一步很容易被忽略。4.2 Webhook 配置接收 GitHub 的“Push”信号GitHub App 创建时还要配置 Webhook URL。GitHub 会在特定事件发生时向这个 URL 发送 POST 请求Hermes 收到请求后开始执行审查。我这里用的是/webhook/github这个路径具体路径取决于你的配置但一定得是一个公网可以访问的地址。这里有个现实问题很多个人开发者的服务器并没有公网 IP。我用的办法是内网穿透把本地服务的端口映射到一个公网域名上。这块涉及网络安全比较多具体方案你自己权衡要确保传输是加密的并且只允许 GitHub 的 IP 段访问这个端点至少也要加一个 Secret 做握手验证。4.3 事件订阅只订阅你需要的别贪多在 GitHub App 的 Webhook 事件设置里我建议只勾选Pull request这一个事件的子选项。原因是 Hermes 只需要在 PR 被打开、更新、重新请求 review 的时候触发订阅太多无关事件会白白消耗配额也会让日志变得杂乱。勾选之后仔细对照一下事件列表。我见过有人勾了 Pull request review结果 Hermes 是在有人提交了 review 之后才跑而不是 PR 一提交就自动跑。这两者的触发时点完全不同。你要的是“Pull request”事件不是“Pull request review comment”事件。4.4 用 GitHub Actions 做轻量替代方案如果你的场景还不需要一整套常驻服务只想在小仓库里快速体验Hermes 也支持直接在 GitHub Actions 里调用。大致流程是 workflow 里写一个 step拉 Hermes 的 docker 镜像或者直接 pip 安装然后传入 PR 号执行审查。这种方式不需要自己搭服务但每次运行都要重新初始化环境速度慢一些。- name: Run Hermes Review env: HERMES_API_KEY: ${{ secrets.HERMES_API_KEY }} MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }} run: | hermes review --pr ${{ github.event.pull_request.number }} \ --github-repo ${{ github.repository }} \ --output markdown这段代码是一个简化的示意。实际跑起来你还需要处理hermes命令的安装步骤另外要记得把 GitHub Token 传给 Hermes否则它没法用 API 拉取代码。5. 审查规则和提示词编排让机器人真正懂你的团队5.1 评审维度从风格到安全四个层次的递进部署跑通只是第一步真正决定这个机器人好不好用的是规则怎么定。我根据团队踩过的坑把审查维度分成四个层次正确性层变量未定义、空指针风险、并发安全问题、资源没关闭。这些是机器最容易发现也最该发现的。性能层明显的 N1 查询、大数据量循环里的网络调用、内存占用过大的集合操作。安全层注入风险、硬编码密钥、未鉴权的接口、用户输入未做校验。规范层命名、格式、目录结构、日志规范。这一层最轻但最消耗人眼。Hermes 的规则配置支持为不同维度设置不同的权重和开关。我建议初期不要全部打开否则评论会刷屏人类 reviewer 反而不知道该看哪条。5.2 提示词设计同样的代码不同的表达方式结果天差地别Hermes 的审查能力很大程度上取决于你给模型的提示词。我第一版提示词写得特别简单大概是“请审查这个 PR 并指出问题”结果 Hermes 输出的意见大而空什么“建议完善代码质量”这种正确的废话完全没有实际价值。后来我把提示词改成了结构化的指令效果立刻不一样了你是一个资深代码审查者。请审查以下 PR diff。 规则 1. 只报告确定性高的问题宁可漏报不要误报。 2. 每条意见必须包含文件路径、行号、问题类型、严重级别、修改建议。 3. 如果某段代码只是风格偏好问题不要提。 4. 重点关注明显的逻辑错误、安全隐患、资源泄露、并发问题。 5. 输出格式为 Markdown 列表按严重程度排序。关键变化是两条“只报告确定性高的问题”和“必须包含文件路径和行号”。前者直接降低了误报率后者让评论从“泛泛而谈”变成“可以直接定位修改”。如果你也遇到 Hermes 输出太水的问题不妨先从这两条改起。5.3 让规则沉淀成配置文件规则写好后不要每次在代码里改应该沉淀到 Hermes 的配置文件里。我的配置里大致是这样review: enabled: true dimensions: correctness: high performance: medium security: high style: low ignore_paths: - *.lock - package-lock.json - dist/** max_comments_per_pr: 15 model: provider: deepseek temperature: 0.2这里面有个经验值得单独说max_comments_per_pr一定要设不然一个改动很多的 PR 会产生三四十条评论不光噪音大还容易超出 API 的 token 限制。我把它设成 15Hermes 会先内部对问题排序只输出严重级别最高的 15 条。5.4 本地模型 vs 云端 API我的选型逻辑热词里反复出现“deepseek hermes”确实有人在用 DeepSeek 跑 Hermes。我的建议是如果你的代码量大、PR 频繁云端 API 的性价比更好按 token 计费不用自己养 GPU。本地小模型虽然私密性强但推理质量目前还不太稳定容易出现“看着像那么回事仔细看是幻觉”的意见。如果一定要在本地跑我个人的经验是选择参数量在 7B 以上的模型并且 temperature 调到 0.2 以下输出会比默认参数稳定很多。另外把上下文窗口尽量拉大因为审查小 diff 时模型可能看不出问题上下文越完整判断越准。6. 实测一场 PR 审查从提交到收到 comment 的完整链路6.1 一条真实 PR 的评审全流程为了验证全流程我在一个测试仓库里故意提交了一个包含三类问题的 PR一个变量名拼写错误、一个没有关闭的数据库连接、一个使用eval处理用户输入的安全隐患。PR 提交后GitHub 向 Hermes 的 webhook 发送事件Hermes 开始工作。整个过程我通过日志观察大致是四个阶段拉取 PR metadata 和文件列表耗时不到 1 秒。逐个文件拉取 diff比较大的文件还会读取完整内容这一阶段耗时取决于文件大小和数量。调用语言模型做推理。本地小模型跑了约 20 秒云端 API 大概 5 秒。把结果整理成 Markdown 评论提交到 PR 页面。最终 Hermes 在 PR 下留了三条评论第一条是变量拼写问题提醒得很准第二条是数据库连接未关闭给出的修改建议是正确的第三条是eval的安全风险不仅指出了问题还主动给了一个替代方案。整个耗时 30 秒左右比人工 review 快太多了。6.2 从一个误报案例讲起排查链路的完整复盘但有意思的是这个流程第一次跑的时候并不顺利。Hermes 第一次运行时报错说“无法解析 diff”但我在 GitHub 网页上明明能看到 diff 是正常的。我的排查链路是这样的先去 Hermes 的日志里看它拉取 diff 的 HTTP 请求返回什么状态码发现返回了 403然后检查 GitHub App 的 token 是否过期没有过期再检查 Permissions发现 Contents 权限只有 Read按道理 Read 已经能读代码了为什么还 403最后定位到原因Hermes 用的是安装级 token权限范围既取决于 App 的 Permissions又取决于 Installation 时勾选的仓库权限。我创建 App 的时候 Contents 是 Read但安装到仓库时那个安装实例拿到的还是旧配置。重新安装一次 App 后问题解决。这类问题最坑的地方在于GitHub 的 403 错误信息并不会告诉你具体是哪个权限缺失只能一个一个排查。6.3 从“能跑”到“好用”三轮调优记录第一轮跑通后评论质量我是基本满意的但还是有几个明显问题。最大的问题是误报率偏高尤其是本地小模型跑出来的结果偶尔会把“没有问题的代码”说成“可能有隐患”。我的处理办法是把提示词里的“只报告确定性高的问题”提到了第一条并且增加了一条“如果不确定不要提出”。第二轮调优是处理重复评论。同一个文件被多次提交时Hermes 会对每个版本的 diff 都产生评论导致同一问题被说两遍。解决方式是在配置里开启“基于 PR 的全局去重”Hermes 会维护一个评论内容的 hash 集合内容相同就跳过。第三轮调优是接入团队的规范文档。我把团队的 SQL 规范、Redis key 命名规范等整理成一段补充提示词让 Hermes 在审查前先读一遍。效果非常好它真的能把“Redis key 没有加项目前缀”这种只有团队内部才知道的规范识别出来。这一轮调优之后Hermes 才算是真正从“通用审查工具”变成了“我们的审查工具”。7. 成本控制、误报率治理和后续扩展方向7.1 跑了一段时间后的成本账算一笔经济账一个中型团队一个月大约 200 个 PR每个 PR 平均消耗 3000 到 5000 个 token。如果全部用云端 API以目前主流模型的价格一个月大概几十到一百多元人民币——这个成本对比一个初级 reviewer 的人力开销几乎可以忽略不计。但有个隐藏成本必须提醒你调试提示词的时间成本。为了让 Hermes 输出符合团队要求的审查意见我前后花了整整两个晚上不是改提示词就是调参数还要拿历史 PR 反复验证。这段时间才是真正的投入建议别急着一次做到完美先跑起来再逐步迭代。7.2 误报治理宁可漏报不可误报我吃过一次亏Hermes 在一个 PR 里报了一个“疑似 SQL 注入”的严重问题人类 reviewer 看到警报后很紧张仔细核查后发现是误报——那段是参数化查询只是变量名里写了拼接函数名让模型“想多了”。这次误报消耗了团队不少精力从此之后我坚定执行“宁可漏报不可误报”的策略。具体落地方式把严重级别的阈值调低、只报告高置信度问题、在提示词里加了“如果你对一个问题的把握低于 80%不要提出来”的指令。这样虽然漏掉了一些边缘问题但保留下来每一条意见都是值得看的整体体验好很多。7.3 后续扩展从 PR 审查到变更管理、安全巡检Hermes 的能力边界不止 PR 审查。我目前正在规划的两个扩展方向一个是常规巡检定时扫描主分支上最近的提交发现未经过 PR 流程的异常变更加以提醒另一个是依赖安全告警当requirements.txt或package.json出现变更时Hermes 自动查询漏洞库在 PR 阶段就拦住带已知漏洞的依赖升级。这两个方向都是在现有架构上扩展新 agent 任务不需要改动核心引擎只需要在规则配置里添加新的执行计划。这说明当初选择 Hermes 这类 agent 框架是值得的——它不是解决一个点的工具而是一个可以承载更多自动化场景的平台。7.4 如果让我重新来一遍我会怎么做回顾整个接入过程如果重新来一遍我会先花十分钟把团队的审查规则文档整理好而不是等部署完再去补提示词。规则整理清楚了提示词就有依据提示词有依据了后面调优就是微调工作而不是推倒重来。另一个会调整的是先在一两个重点仓库试运行一周收集误报数据和团队反馈后再正式推广到全组。我当时是一步到位全仓库启用结果前三天评论量偏多部分同事有抵触情绪。试运行阶段不仅能让技术方案更加成熟也能让你的团队在心理上逐步接受“机器人参与审查”这件事。最后想分享一个经验代码审查自动化不是用来取代人类 reviewer 的它真正取代的是“低级重复劳动”。当 Hermes 把拼写、风格、明显的逻辑漏洞都处理掉之后团队里的人类 reviewer 反而更愿意认真审查了因为他们知道自己看的每一个问题都是值得动脑子的。这应该才是自动化评审最理想的状态。