用大模型自动评审代码：Hermes智能体实战指南

要聊自动化代码评审很多团队第一反应是先上一套 SonarQube再挂几个代码规范插件。说实话这类工具能抓出来的问题基本都是“规则可枚举”的漏网之鱼真正让 reviewer 在 PR 页面里来回拉滚动条、脑力全开的那些问题——比如这个改动会不会踩到并发边界、有没有漏掉异常路径、命名和既有模块的画风对不对——它们基本帮不上忙。最近我一直在折腾一个叫 Hermes 的开源智能体它的定位很直接把你的 GitHub Pull Request 交给大模型当“代码评审员”去读在读完之后给出带文件行号的行内评论和一份总结报告。这篇文章不是项目文档的翻译而是我从“看过一眼”到“跑在生产工作流里”的完整过程。我会把 Hermes 的工作原理、部署方式、和 GitHub 的集成链路以及我踩过的几个坑全部写出来。无论你是开源项目维护者还是想让团队 review 流程更省力的研发负责人只要会一点 Docker 或者 GitHub Actions都可以照着落地。1. Hermes 项目整体设计与思路拆解1.1 项目解决的核心痛点先说痛点。代码评审这件事一直是研发流程里最像“手工活”的环节。你开了一个 PR等了半天reviewer 才慢悠悠回一句“lgtm”或者说“这里不对但我也说不清哪里不对”。更常见的场景是核心模块的 PR 总是只有那两三个资深工程师能 review其他人不敢点评论怕说错。而 Hermes 要解决的第一步就是把“有没有人看”变成“AI 先看一遍”。它不是一个简单的代码检查插件而是一个完整的智能体服务。它会在 PR 创建或更新时读取本次变更的完整 diff甚至会把相关的文件内容一起塞给底层的大模型让模型理解这段改动的业务意图。这也是它和传统工具差异最大的地方。举一个很典型的例子有一次我们的改动里删掉了某个判空逻辑表面上编译和测试都能过但 Hermes 结合上下文直接指出“这里如果传入 null下面第 34 行会直接抛 NPE”然后在对应代码行留了一条评论。这种发现能力靠正则和 AST 是做不到的。它解决的痛点是“代码里被埋下的隐性雷”而不是“没有加分号”这种显性问题。1.2 为什么选择“智能体DeepSeek”的路线我最早看到 Hermes 的时候以为它只是把 GitHub Copilot 的 review 功能换了个壳。后来拆完代码才发现它更像一个能自己决策的智能体Agent收到 webhook 事件之后它会自己决定先调用哪个接口、读取哪些文件、需要让模型看几轮内容再决定把结果写成 review 评论还是调用 Checks API。这种设计让它的上限比普通 CI 工具高出一大截。底层模型方面Hermes 兼容 OpenAI 格式的 API所以可以很方便地把 DeepSeek 配置进去。我自己长期用的是 DeepSeek核心原因是三点第一代码理解和中文表达都足够稳review 意见能写到“人话”而不是机翻腔第二上下文窗口能覆盖大多数中等规模的 PR不会因为 diff 太长直接截断第三费用比很多商业模型低一截每天跑几十个 PR 也不会让团队被账单吓到。当然如果团队本身已经有其他模型渠道也可以替换。Hermes 的核心并不是绑定某一家模型而是把“拉取代码变更—组装上下文—调用模型—回写评论”这条链路做好。模型只负责其中“读代码、动脑”的部分其他脏活累活全部由 Agent 脚本接管。1.3 Hermes 与传统代码检查工具的差异很多第一次接触 Hermes 的人都会问它和 Lint、SonarQube 有什么区别我先用下面这张表说明白能力维度传统 LinterSonarQube 等平台Hermes 智能体规则来源基于内置规则做语法匹配规则库加自定义规则自然语言理解动态分析检测对象语法错误、风格问题重复代码、坏味道、覆盖率逻辑漏洞、边界条件、可维护性误报率低但漏报很多中高需要大量配置需要调 Prompt投入后可以很低部署成本低较高中低Docker 即可是否理解业务上下文完全不懂不太懂能结合上下文推理表格看下来就清楚了Hermes 不是来取代 SonarQube 的而是补上“人工代码评审”这一层。传统工具把“代码能不能跑”这件事守住了Hermes 把“这段代码好不好维护、会不会在极端情况下炸掉”这件事接过来。对我们团队来说现在的流程是CI 先跑单测和静态检查Hermes 再做一轮语义级 review最后人为 reviewer 只关注 AI 拿不准的设计问题。这样人机分工效率是最高的。2. 核心细节解析Hermes 如何做 PR 审查2.1 审查流程的完整链路Hermes 处理一次 PR 审查不是“收到请求直接问模型然后发评论”这么简单。它的完整链路拆开来看大致是这样接收 GitHub Webhook 事件包括pull_request.opened、pull_request.synchronize、pull_request.reopened。校验 Webhook 签名确保请求确实来自 GitHub并且仓库已安装 App。按预设的过滤规则判断是否要审查比如跳过标题以 “WIP:” 开头的 PR或者只审查指定路径下的改动。调用 GitHub API 拉取 PR 元数据、文件列表和每个文件的 diff。把 diff 和关联文件内容组装成上下文大 PR 会拆成多个文件块避免超过模型上下文窗口。并发调用底层模型要求返回结构化的 JSON 结果。解析输出通过 GitHub API 提交 Pull Request Review在具体代码行留下评论。如果开启了 Checks 联动再创建一个 Check Run 汇总审查状态和结果。其中第 5 步是我觉得 Hermes 做得最聪明的地方。一个几百个文件的巨型 PR如果一股脑全塞给模型大概率会超上下文或者模型捡了西瓜丢了芝麻。Hermes 会按文件或按变更块拆分同时对可能有关联的文件做合并处理。既省 token又不会让模型因为长时间阅读而“遗忘”前面的内容。2.2 Prompt 工程与代码评审规则设计Hermes 的审查质量很大程度上取决于 Prompt 怎么设计。不是说装了就能直接开箱即用而是需要在提示语里把“你是一个代码评审员”这件事交代清楚否则模型会产出大量“这段代码写得不错”的废话。我目前使用的核心 Prompt 大致是这个形态你是一位经验丰富的代码评审专家。请审查以下 diff并定位到具体行号。 审查重点 1. 逻辑正确性与边界条件 2. 错误处理是否完备 3. 是否有安全风险注入、越权、敏感信息泄露 4. 并发与性能隐患 5. 与项目现有风格是否一致 输出严格JSON数组每个元素包含: - path: 文件路径 - line: 行号必须存在于 diff 中 - severity: critical | warning | suggestion - message: 中文描述不超过 80 字 如果没有问题返回空数组。这里有个非常容易被忽略的点line必须是 diff 中真实存在的行号不能是原始文件中的行号否则 GitHub API 会直接拒绝评论。我刚开始就是没注意这一点结果好多条评论根本没提交上去日志里全是 422 错误。除了内嵌的 PromptHermes 还支持在仓库里放一份规则文件比如.hermes/rules.md里面可以写团队自己的约定。比如“禁止在业务代码中捕获 Exception 后静默吞掉”“所有对外接口的入参必须做长度校验”。这些规则会拼接到系统提示词里让模型在审查时优先遵守。调优方面我的建议是temperature设到 0.2 左右越低的随机性越能保证审查结果的稳定性。max_tokens根据 PR 大小设置为 1000 到 3000 之间太小了容易截断导致 JSON 解析失败。2.3 审查结果的输出与交互Hermes 的输出并不是一堆零散评论而是以一个正式的 Pull Request Review 形式提交。这样在 GitHub 页面上会有一个独立的 review 卡片作者可以清楚地看到哪些文件被标记了严重问题哪些只是建议。一个典型的输出结构是{ summary: 本次变更整体质量中等。最需要注意的是 auth/token.go 中 Token 过期未处理建议补充 Refresh 逻辑。, comments: [ { path: auth/token.go, line: 42, severity: critical, message: Token 失效后直接返回 500建议转为 401 并触发刷新流程。 } ] }summary 部分会显示在 PR Review 的最上方方便快速总览。对于 critical 级别的问题Hermes 会明显加重语气并且建议修改方案warning 级别则是“这里可能有坑你注意一下”suggestion 级别更多是风格和可读性层面的建议命中也无所谓。如果团队不想让机器人每次都在 PR 里刷屏可以配置成“只在存在 critical 问题时才提交正式 Review否则只在 Comment 区域汇总”。还有一个小技巧我们会在 PR 评论里输入/hermes review手动触发一次审查适合那种刚改完想再确认一轮的场景。3. 实操过程从安装到接入 GitHub3.1 环境准备与依赖清单在正式部署 Hermes 之前先列一下需要准备的东西免得装到一半发现少这个少那个一台能跑 Docker 的 Linux 服务器或者一台 Windows 电脑装好 Docker Desktop。DeepSeek API Key需要在 DeepSeek 开放平台申请。一个 GitHub 账号用于创建 GitHub App。一个能让 GitHub Webhook 访问到的地址。如果是本地调试可以用内网穿透工具暴露一个公网临时地址如果直接部署在云服务器上用公网 IP 就行。基础的命令行操作能力至少会看日志、会用curl测试接口。硬件方面Hermes 本身并不吃资源最占资源的是底层模型调用但这部分跑在云端。所以本地只需要 2 核 4GB 内存、20GB 磁盘就完全够用。如果你要在 Windows 上同时跑 Docker Desktop内存建议放宽到 8GB因为 Docker Desktop 本身会占一部分。3.2 使用 Docker 快速部署推荐我自己是直接用 Docker 部署的这样能和环境里的 Python 版本、依赖库彻底隔离。假定你已经写好了docker-compose.yml大致内容如下services: hermes: image: yourmirror/hermes-agent:latest container_name: hermes restart: unless-stopped ports: - 8080:8080 environment: - HERMES_GITHUB_APP_ID123456 - HERMES_GITHUB_PRIVATE_KEY_PATH/run/secrets/github-private-key.pem - HERMES_GITHUB_WEBHOOK_SECRETyour-webhook-secret - DEEPSEEK_API_KEYsk-xxxxxxxx - DEEPSEEK_BASE_URLhttps://api.deepseek.com - DEEPSEEK_MODELdeepseek-chat volumes: - ./secrets:/run/secrets:ro - ./data:/data需要注意环境变量名只是示例具体要以 Hermes 项目仓库的文档为准。启动命令很简单docker compose up -d启动之后先确认健康状态curl http://localhost:8080/health如果返回ok之类的结果说明服务已经跑起来了。接下来去 GitHub 创建 App 并配置 Webhook等配置完成后PR 事件就能自动触发了。3.3 Windows 本地部署指南关于 “Windows 系统如何部署 Hermes 智能体比较合适” 这个问题我在折腾了两天后可以负责任地说最合适的方案是 Docker Desktop其次是在 WSL2 里跑原生 Python最不推荐直接在 Windows 命令行下裸跑。原因有几点Hermes 项目里大量使用了 shell 脚本和符号链接Windows 的路径分隔符和 CRLF 换行会直接让你的start.sh跑起来报一堆诡异错误。如果一定要用原生 Python 部署我的建议是先装 WSL2然后在 Ubuntu 子系统里跑。这样你可以按照 Linux 环境的标准流程来几乎不会遇到兼容性问题。如果你只是想在 Windows 上做个快速实验又不想装 WSL2那 Docker Desktop 是最省心的。安装后打开 Settings把 “Use WSL 2 based engine” 勾上然后在 PowerShell 里执行docker compose up -dWindows 下还有一个容易踩的坑防火墙和端口映射。如果宿主机能访问localhost:8080但外部访问不到很可能是 Windows 防火墙拦住了入站流量。你需要手动放行 8080 端口或者在云服务器的安全组里确认规则放开了对应端口。3.4 创建 GitHub App 并配置 Webhook要让 Hermes 能收到 PR 事件必须在 GitHub 创建一个 App。进入 GitHub 的 Settings - Developer settings - GitHub Apps点击 New GitHub App然后按下表配置权限权限项需要的等级用途Pull requestsRead and write读取 PR 内容并提交 ReviewChecksRead and write创建 Check Run 汇总状态IssuesRead读取关联 issue 上下文MetadataRead读取仓库基本信息Webhook URL 填你的服务地址形如http://your-server:8080/webhook如果是在本地调试可以先用内网穿透工具把localhost:8080暴露成一个公网 URL后续收到 Webhook 的测试推送避免反复部署。创建完成后下载生成的私钥 PEM 文件并记录App ID。Webhook Secret 也保存下来后面要配置到 Hermes 环境变量里。最后一步是在 GitHub App 页面点击 Install App选择允许安装到目标仓库。从这一步开始该仓库的 PR 事件就会推送到你的 Hermes 服务。3.5 用 GitHub Actions 触发自动审查如果你采用的是独立服务 GitHub App 的方式其实不太需要 GitHub Actions因为 Webhook 本身已经完成了事件触发。但有些团队希望把 Hermes 的调用过程纳入 CI 流程或者不想维护一个常驻服务这时候可以在 PR 事件里通过 GitHub Actions 跑一个审查任务。下面是一个最简单的 workflow 示例name: hermes-review on: pull_request: types: [opened, synchronize] permissions: pull-requests: write checks: write jobs: hermes: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run Hermes review action uses: yourteam/hermes-review-actionv1 with: github_token: ${{ secrets.GITHUB_TOKEN }} deepseek_api_key: ${{ secrets.DEEPSEEK_API_KEY }} model: deepseek-chat rule_file: .hermes/rules.md这里有一个安全提醒DEEPSEEK_API_KEY一定要放到 GitHub 仓库的 Secrets 里不要直接明文写在 yaml 文件中。Actions 的表单里可以通过${{ secrets.XXX }}引用这样日志里不会出现真正的 Key。用 GitHub Actions 的好处是随取随用不需要常驻服务器但坏处是每次审查都要等一个独立的执行环境启动速度会比常驻服务慢几十秒。我的建议是如果仓库变动频繁就老实部署常驻服务如果只是偶尔用一下可以走 Actions。4. 常见问题与排查技巧实录4.1 模型调用失败与网络超时我在部署第一天就遇到了模型调用失败日志里报了AuthenticationError。先检查 DeepSeek API Key 有没有写错再确认余额是否充足。你可以先用一条纯手工请求测试模型接口curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]}如果返回正常的completion说明模型侧没问题问题出在 Hermes 的环境变量配置上。常见的坑是DEEPSEEK_MODEL写成了deepseek-coder但 DeepSeek 目前对外统一使用deepseek-chat和deepseek-reasoner按你自己的账号支持情况填。网络超时则比较复杂。服务器如果和 DeepSeek API 之间网络不稳定可以把请求超时时间调长到 60 秒同时打开 Hermes 的DEBUG级别日志看看是连接超时还是读取超时。再有就是检查防火墙或者出口网络策略看 API 域名是否被拦截。4.2 PR 事件漏触发与 Webhook 配置问题Hermes 装好之后最让人抓狂的问题就是PR 开了好几个它一条评论都没有。这种“静默失联”往往不是模型问题而是 Webhook 根本就没进来。排查顺序我建议是这样先打开 GitHub App 的 Advanced 页面看最近有没有投递记录。如果投递列表里出现了304或422说明事件已经到达但被拒绝了。此时去 Hermes 日志里搜webhook关键字大概率能看到签名校验失败或 secret 不匹配的错误。保存 Webhook Secret 时最好不要手动敲而是直接复制粘贴避免多一个空格导致哈希对不上。如果投递记录里完全空那说明仓库压根没安装这个 App或者事件没订阅。去 GitHub App 配置页把Pull request事件勾上再确认 installation 覆盖了目标仓库。最后用一句话总结我最近的排查经验Webhook 问题先看 GitHub 面板再看服务日志不要一上来就怀疑模型。模型出问题顶多返回报错Webhook 出问题才是真正的“无响应”。4.3 审查结果不稳定如何调优 Prompt审查结果不稳定的表现很多比如同样的代码上次说有问题这次又说没问题有时评论非常细致有时又全是一些“注意代码风格”的套话。这种问题基本可以归类为 Prompt 设计不够清晰。我做过一个对比实验。最早用的 Prompt 是“请审查以下代码”结果模型给出的反馈非常宽泛。后来我在 Prompt 里显式加上“必须找到至少一个严重问题如果找不到再考虑 warning”并且要求按严重级别排序审查质量立刻提升了一个档次。另外把团队规则写进.hermes/rules.md也是稳定输出的一大关键。比如“禁止在循环里查数据库”“禁止使用print调试”这些规则写清楚后模型每次都会照着执行。还可以加入少量示例比如给出一段错误代码和正确评论的对照模型会模仿这个输出风格比单纯文字描述更有效。最后记得把temperature调低随机性下降之后输出格式和内容都会稳定很多。4.4 Docker 与 Windows 环境下的资源占用问题Docker 部署虽然省心但在 Windows 上有个绕不开的问题Docker Desktop 基于虚拟机运行默认会占用不少内存。如果你发现电脑开始卡顿可以在用户目录下新建.wslconfig文件限制虚拟机的资源[wsl2] memory4GB processors2 swap2GB保存并执行wsl --shutdown让配置生效。这样 Docker Desktop 的内存占用就会被锁在 4GB 左右不会出现打开几个窗口就把电脑拖死的情况。还有一个性能坑在 Windows 里把 Hermes 的数据目录挂载到/mnt/c/...会非常慢因为跨文件系统访问会有很大开销。最好把数据目录放到 WSL2 自己的虚拟磁盘里也就是在 Ubuntu 子系统内的某个路径下操作。这也是我推荐 WSL2 Docker 的一个原因一切行为都更接近真实服务器环境。5. 部署后的运营心得与进阶建议5.1 让我头疼的三件事第一次把 Hermes 接到真实仓库后前两周其实一直是“边跑边修”的状态。最头疼的是误报率。为了让模型显得“严格”我把 Prompt 里加了“必须找到问题”的指令结果它对很多本来没问题的代码强行给出 warning搞得 PR 作者开始无视所有机器人评论。后来改成“有则指出没有则明确说没有”并且补充了团队规则误报率才降下来。第二件事是上下文窗口。单个大 PR 拆成多个文件块后每个块单独审查确实稳定但跨文件的问题比如一个服务接口的入参在 A 文件定义、在 B 文件使用、又在 C 文件缺失校验就很容易漏掉。我后来在规则里加入“先看整体摘要再针对重点文件深入审查”的流程情况好转了一些。第三件事是费用。DeepSeek 虽然便宜但每个 PR 跑一轮几百个 token 的输入团队人多之后账单还是会往上走。后来我加了并发限制和频率控制只对真正的 feature 分支跑完整审查hotfix 分支只跑 summary成本立刻可控。5.2 团队协作时如何设定审查规范如果你打算直接把 Hermes 丢给整个团队用不要只搭个服务就不管了。它只是一个人机协作的助手需要给团队立几条规矩。我会在仓库里建一个.hermes/rules.md把团队约定写进去比如错误处理必须显式、禁止在业务代码里使用缩写的变量名、所有对外接口需要做长度校验等。同时在 PR 模板里建议作者写清楚“改动背景”和“复现步骤”这样 Hermes 生成的上下文会更准。对于小改动比如一个文件 50 行以内的修改直接跑完整 review超过 500 行的大 PR建议拆成几个逻辑相关的小 PR 再交给 Hermes不然模型也会累。最后Hermes 的评论只是参考。团队里应该有一条明确的规范critical 级别的评论必须处理warning 可以讨论suggestion 有空再说。不能因为 AI 说了就一定要改代码评审的最终责任人仍然是开发者。5.3 从“能用”到“好用”的扩展思路等 Hermes 稳定跑起来之后我考虑过几个扩展方向。第一个是把结果接回 CI 流水线如果 Hermes 返回了 critical 级别的问题让 Check Run 失败阻止合并。第二个是让 Hermes 支持 GitLab 和 Bitbucket因为很多公司内部代码仓库并不是 GitHub。第三个方向是自动学习历史 review 经验。目前的规则文件需要手工维护如果能把之前所有人工 review 的讨论记录整理成补充 PromptHermes 会越来越贴近团队自己的代码风格。我也在试一些别的 Agent 工具和 Hermes 配合把“拉取最近合并的 PR 生成周报”这类重复性工作也自动化掉。至少到目前为止Hermes 已经是我这边 PR 流程里不可或缺的一环。它的价值不在于替你做一个决定而在于把一百个 PR 里的重复劳动先消化掉让你把时间和脑力花在真正值得争论的设计问题上。以后如果踩到新的坑我再回来继续更新这篇经验。