做技术负责人这几年我每天最耗时间的动作不是写代码而是Review PR。不是不想认真看而是大部分PR里真正需要人思考的逻辑问题只占两成剩下的都是格式不统一、空指针隐患、密钥泄漏这类一眼就能判断的问题。后来我把Hermes接到GitHub仓库上让它在每个PR开出后自动跑一遍代码评审把低质量变更挡在合并之前。现在团队每天的PR审查时间大概压缩了一半Human Reviewer只需要盯着Hermes标记出来的高危项和高层设计问题就行。这篇文章就是Hermes在GitHub PR审查场景里的完整落地总结包括架构思路、部署方式、规则配置和我在真实仓库里踩过的坑。1. 项目概述与设计思路1.1 为什么要做自动化代码评审先说一个我自己的观察代码评审这件事越往后越像在“扫雷”。刚开源项目或者小团队的时候PR数量少每条PR逐个文件看也花不了多少时间。但一旦仓库进入多人协作状态每天三五个PR甚至十几个PR人工审查就开始出现明显问题。第一是重复劳动。很多问题是同一类问题反复出现比如JavaScript项目里常见的console.log忘记删除、Python里裸except吞掉异常、配置项里把明文密钥提交上来。这类问题不是不会写纯粹是忙起来顾不上人工review去抓这种问题性价比极低。第二是标准不统一。同样一段代码A审查者觉得可以合B审查者会要求重构最后变成“谁审查谁说了算”代码风格越来越散。第三是周期拉长。PR挂一整天没人看合并时间不可控需求迭代速度被卡在“等人review”这一环上。Hermes解决的正是这些问题。它本质上是一个挂在GitHub PR事件上的自动化审查管道PR一开出来自动拉取diff跑一组可配置的分析器然后把结果以Comment和Check Run的形式回写到PR页面。人工reviewer只看结论挑重点深入讨论不需要再花时间做机械判断。它适合个人项目也适合小团队和平台工程化团队区别只在于你选择哪种部署方式。1.2 Hermes 的核心架构与完整工作流我第一次拿到Hermes的时候第一反应是“这不就是个机器人吗”后来我把它的数据流完整理了一遍才发现它的设计比我想象的克制。事件入口有两种一种是挂在GitHub Actions里靠workflow的pull_request事件触发另一种是部署一个自托管服务通过GitHub App接收Webhook推送。无论哪种入口触发之后的核心管道大致是四段式第一步收集变更集。从GitHub API拉取PR的元信息、提交列表、文件级别的diff注意这里不是把整个仓库clone下来而是按PR数据接口拿变更内容这样在超大仓库里也能控制数据量。第二步执行分析器链。这是Hermes的精髓。它不是一个单一检查器而是一个插件化的分析器集合常见的包括静态Lint检查、密钥泄漏扫描、复杂度分析、重复代码检测、依赖漏洞扫描以及可选的LLM语义分析。每个分析器独立并行跑互不阻塞最后把结果统一回传到聚合器。第三步结果聚合与去重。多个分析器可能报同一个问题比如一个高复杂度函数既触发复杂度警告又在LLM分析里被点名聚合器需要按“文件行号问题类型”做指纹去重再按严重级别排序控制最终输出的条数。第四步结果回写。在PR上创建一条聚合评论同时创建Check Run。Check Run的好处是可以直接接入分支保护Hermes如果判定存在error级别的规则命中Check Run状态置为failed这个PR在保护规则下就无法点Merge按钮。这套管道最让我满意的地方是插件化。我后来自己加了一个针对公司内部私有组件的扫描器只需要实现一个分析器接口把结果格式化成统一的ReviewFinding结构主流程完全不用动。用生活化类比来说Hermes就像一条自动流水线每个分析器是流水线上的质检工位各管一摊最后汇总到总控台。2. 部署接入两种方式怎么选2.1 方式一GitHub Actions 轻量接入如果你的仓库数量不多或者还在验证阶段我强烈建议先用GitHub Actions方式这是成本最低的一条路径。不需要维护服务器权限模型由GITHUB_TOKEN天然承载触发事件也是GitHub自动帮你想好了。在仓库根目录创建.github/workflows/hermes-review.yml一个最简可用的配置长这样name: hermes-review on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write checks: write jobs: hermes: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run Hermes PR Review uses: your-org/hermes-actionv1 with: github_token: ${{ secrets.GITHUB_TOKEN }} config: .hermes/config.yml几个关键点我展开说一下。types里为什么是opened, synchronize, reopened这三个opened是PR第一次开出synchronize是开发者又推了新提交reopened是关闭后重新打开。这三类事件基本覆盖了PR全生命周期内的主要变更时刻。注意视觉效果上第一次提交和后续提交都会被自动覆盖不需要额外设置。permissions这一块很多人会忽略但它是Action最常见报403的根源。GitHub默认的GITHUB_TOKEN权限其实很保守如果你不显式声明pull-requests: write和checks: writeHermes去写评论、创建Check Run都会被拒日志里就报一个让人摸不着头脑的403。我建议按最小权限原则来写不要图省事把整个token权限拉到write-all。这个Action方式还有两个隐藏优点日志直接在Actions页面可视化查看排查问题非常直观每次触发都是一次干净的容器环境不会出现本地依赖污染。缺点是大型仓库拉diff慢以及如果需要接私有化的大模型接口Action环境不好配置网络访问。2.2 方式二Docker 自托管服务当仓库超过十个、需要统一管理多仓库的审查配置或者想给Hermes接上内部专用的模型服务时Action方式就开始别扭了。这时候我建议自托管一个Hermes服务用Docker一挂让它通过GitHub App监听所有目标仓库的PR事件。先贴一份我生产环境在用的docker-compose.yml做了最小化脱敏services: hermes: image: hermes/reviewer:latest restart: unless-stopped ports: - 8080:8000 environment: GITHUB_APP_ID: 123456 GITHUB_APP_PRIVATE_KEY_PATH: /run/secrets/hermes.pem HERMES_CONFIG_PATH: /app/config/config.yml LLM_API_URL: http://llm-proxy:8080 volumes: - ./config:/app/config - ./secrets:/run/secrets这里有个选择接入GitHub用Personal Access Token还是GitHub App我强烈建议用GitHub App。原因有三点。权限隔离App的权限可以精确到某几个仓库的pull request读和写而PAT一旦在服务器上泄漏等于把你账号下所有可见仓库都暴露了。可审计性App每次操作都会以机器身份出现在仓库的动态里不会和个人的提交记录混在一起。集中管理一个App可以安装到多个仓库在GitHub组织设置里统一授权和吊销比在每台服务器上维护PAT要优雅得多。Webhook的配置需要在GitHub App的设置页面填一个Payload URL指向你Hermes服务的/webhook路径。这里有个我踩过的坑Webhook的Secret一定要设置而且要和Hermes环境配置里的WEBHOOK_SECRET保持一致否则GitHub推送的请求会因为签名校验失败被服务器直接拒掉。第一次调试时我就是忘了配这个字段GitHub后台一直显示webhook请求409排查了半小时才发现是签名问题。自托管还有一个隐藏收益你可以把模型判断结果、历史审查数据落库之后想做一个“哪些文件最容易出问题”的统计面板就有了数据基础。Action方式虽然轻但数据是零散的不方便做长期质量分析。2.3 配置文件编写要点不管用哪种部署方式Hermes的规则控制都在一个YAML配置文件里。我见过一个很常见的误区拿到Hermes就默认配置跑结果它在你几千行代码的老仓库里刷出一堆存量问题评论长达几百条直接把团队吓退了。所以配置文件里的路径过滤和基线模式是第一批要调的东西。我的建议配置结构是这样的repository: owner: your-org name: your-repo review: enabled_rules: - no-secrets - complexity - lint-eslint - dependency-vuln path_filters: exclude: - **/package-lock.json - **/dist/** - **/generated/** base_mode: incremental comment_policy: mode: aggregate max_findings: 20 max_repeats: 3 severity: error: - no-secrets - dependency-vuln warning: - complexity - lint-eslintbase_mode: incremental这个参数是关键。它意味着Hermes只审查当前PR相对于目标分支新增和修改的行存量问题一概不报。这非常重要因为老仓库往往积压了大量历史遗留问题一上来全量报会把噪声放大到无法使用。先保证增量代码干净再逐步治理存量这才是可持续的落地节奏。comment_policy.max_findings是控制评论上限的一般设置在20条左右比较合适。超过上限的发现会被折叠到一个summary里避免刷屏。我见过一些团队因为评论太多直接想卸载Hermes其实问题不是工具不好而是没设上限。3. 审查规则与核心配置3.1 静态检查与规范类规则怎么配静态检查是Hermes最基础的能力也是“回本最快”的一类规则。你不需要让Hermes替代Human做设计评审只需要让它在错误还停留在代码库之前拦住它。常见的静态规则包括Lint检查JavaScript用ESLint、Python用flake8/Ruff、Go用golangci-lint、圈复杂度、重复代码、废弃API调用、TODO/FIXME遗留扫描。Hermes的规则引擎本质上是把外部工具的JSON输出转成统一的审查结果所以你在原生工具里配好的规则在Hermes里依然生效。以复杂度规则为例我会给一个实际参数建议rules: complexity: enabled: true threshold: total: 50 per_function: 15 incremental_threshold: per_function: 10per_function是单函数圈复杂度阈值行业惯例一般是15。但如果你希望新代码质量更高可以把incremental_threshold单独压到10这样存量代码超过15才报新增代码超过10就报二者不冲突。我在这套配置下跑了两周团队新代码的平均函数复杂度确实降下来了因为Hermes会在PR阶段直接提示开发者发现“这条函数太长了合并不过去”自然就会主动拆函数。重复代码检测同样值得重视尤其在多人维护的仓库里。我建议基于AST级别的重复检测而不是简单的文本相似度不然会把两个结构类似但语义不同的函数误判成重复。配置上可以设置最小重复块长度比如连续重复超过20行才报告避免大量琐碎的误报。3.2 安全与依赖扫描值得设为硬阻断的规则如果说静态检查是Hermes的“日常工作”那安全扫描就是它最应该被赋予“生杀大权”的部分。两条规则我建议直接设置成severity: error一旦命中就让Check Run失败阻断合并no-secrets密钥泄漏检测和dependency-vuln依赖漏洞扫描。no-secrets的检测思路是正则匹配加熵检测。正则匹配负责识别常见格式比如AWS Access Key、GitHub Token、SLACK_TOKEN这类结构化密钥熵检测负责找出高随机性的字符串防止自定义密钥或内部凭证漏网。这个规则容易误报尤其是测试代码里经常会出现模拟的密钥记得配置白名单。rules: no-secrets: enabled: true severity: error allowlist: - AKIAIOSFODNN7EXAMPLE - test-token - **/test/**dependency-vuln需要接入漏洞数据库。Hermes通常通过读取项目锁文件package-lock.json、poetry.lock、go.sum等把依赖版本对到漏洞库上。这里有一个实用建议锁文件建议走path_filters.exclude排除掉不参与diff分析但dependency-vuln规则特殊它会单独读取锁文件做全量扫描所以不需要在path里排除。为什么这两条要设为error因为它们修复成本极低、风险极高。一条泄漏的密钥流到公开仓库几分钟内就可能被自动脚本扫走造成实际损失。这类问题没有任何讨论余地直接让PR卡住是最科学的流程。3.3 AI 辅助评审的调优实战Hermes最有新意的地方是它可以接入大模型做语义分析。规则引擎只能查已知问题对于“这个函数在并发场景下有竞态条件”“这里缺少权限校验”这类语义问题传统工具无能为力。而LLM正好擅长理解代码意图和上下文。我推荐的做法是把LLM分析作为一个增量分析器和传统规则并行但需要做三个调优动作。第一限制输入规模。整个PR的diff可能很大直接全部塞给模型既慢又贵。Hermes会把diff按文件拆块每个块控制在8K token以内并且只对incremental模式下的新增代码做分析。你可以设置max_analysis_files: 10超过10个文件的新增代码就只采样分析避免一次PR烧掉大量token。第二约束输出格式。让模型返回结构化的发现列表而不是自由文本这样结果才能进聚合器。rules: llm-semantic: enabled: true provider: openai-compatible model: your-model-name max_findings: 10 confidence_threshold: 0.7 system_prompt: | 你是资深代码评审专家。请审查以下diff中的新增代码 只返回确定性的问题格式为 file:行号|严重级(high/medium/low)|问题描述。 不要输出赞美或概括性评论。第三处理误报。LLM的审查建议偶尔会给出明明正确但实际不需要修改的“建议”比如“建议加注释”这类噪声。我通过confidence_threshold和severity_with_model组合压制只有在模型置信度高于0.7且严重级别为high时结果才会进入最终的评论列表medium以下的结果只记录在日志里供开发者主动查看。这样既保留了语义审查的能力又不会污染PR评论区。4. 实操案例与结果解读4.1 一个典型 PR 的完整审查过程我拿一个真实情况的简化版来做讲解。假设有这样一个PR后端登录模块增加“记住我”功能改动涉及三部分auth_service.py新增了token刷新逻辑、schema.sql加了用户会话表、前端login.js调用新接口。PR一开出来Hermes自动开始跑。我们看这次审查产生的结果结构auth_service.py第37行no-secrets规则命中检测到硬编码的JWT secretseverityerror。这个必须修不然合并后生产环境等于裸奔。auth_service.py第58行complexity规则命中函数_refresh_token的圈复杂度为18超过新增阈值10severitywarning。这里提示代码可能逻辑分支过多建议拆函数。schema.sql第12行dependency-vuln未命中但lint-sql提示缺少service字段的注释severitylow。login.js第20行LLM语义分析命中一条high提示“token刷新失败时没有清理已有cookie存在会话残留风险”这个点是纯规则引擎抓不出来的。整个审查过程大约用时50秒。如果全部由人工来review至少要15分钟而且login.js这个会话残留问题大概率会被当成“细节问题”漏过去。Hermes的价值就在这里它把人的注意力从“查找问题”转移到了“决策问题”。PR作者看到Review结果后修掉了error级密钥问题拆分了高复杂度函数并用?请求半天后再跑一次Hermes检查重新变为pass才进入人工review和合并流程。这个闭环非常顺畅。4.2 评论聚合与状态检查的配置技巧Hermes默认会在PR上发评论但如果每条finding单独发一条评论几十条评论刷屏会让PR页面完全不可读。所以聚合评论是必须开启的。我这边实际用的配置是comment_policy: mode: aggregate update_on_new_commit: true max_findings: 20update_on_new_commit这个参数也很实用。它会让Hermes在同一PR有新提交时复用上一条评论进行内容更新而不是再发一条新评论。这样PR页面只会有“一条”Hermes评论内容始终是最新状态。配合max_findings: 20就算扫描结果非常多也只会把Top 20放出来其余折叠到summary里。Check Run的部分同样重要。Hermes会创建一个名为Hermes Review的Check Run并对每条error级规则的结果返回conclusion: failure。这看起来只是一个小小的状态标记但实际效果很惊人因为Check Run的状态可以直接被GitHub的分支保护规则识别。4.3 结合分支保护让错误无法合并如果你只把Hermes当“评论机器人”它能帮你提问题但开发者可以选择无视问题照样合进去。所以要把它的价值放大必须接入分支保护。在GitHub仓库的Settings - Branches - Branch protection rules里我给main和dev分支都配置了以下内容勾选“Require status checks to pass before merging”在搜索框里输入Hermes Review选中这个Check Run勾选“Require branches to be up to date”如果需要的话这套配置生效后逻辑变得非常简单只要有error级别的规则命中Hermes的Check Run就是fail状态Merge按钮直接置灰没有管理员权限的人根本点不动。开发者要吗修复问题要吗提交时使用更安全的写法。长此以往团队代码基线整体都会被抬起来。这里有一个实测的经验一开始不要把所有规则都设为error只把no-secrets和dependency-vuln这种明确红线设为error其余warning先留给人工判断。否则第一天Hermes上岗就可能把好几个人的PR全部卡住给团队带来强烈的挫败感。先让工具打出第一场小胜仗再逐步收紧规则是推进自动化评审更平滑的方式。5. 常见问题与排查技巧5.1 事件不触发或重复触发这类问题是我被问得最多的我用排掉时间最多的三个案例说明。一个是new PR根本不触发95%的原因是workflow文件路径或事件类型写错。确认文件在.github/workflows/下、后缀是yml或yaml、事件类型与预期一致。可以到Actions页面看有没有workflow记录如果连workflow记录都没有说明仓库压根没识别到文件。另一个问题是PR更新后重复触发synchronize事件会在每次push到PR分支时触发这本身是预期的。但如果一次push包含4个commitworkflow不会触发4次只会合并触发一次。如果你发现Hermes被触发了多次检查有没有多个workflow文件都监听了pull_request事件或者是不是Webhook和Actions同时接了两条入口。还有一个我很早之前踩过的坑PR里只改了.md文件Hermes启动后扫描diff没有任何匹配的文件类型于是静默退出连评论都不发。这样的体验会让开发者以为系统坏了。我建议在配置里显式开启一个空结果提示开关让Hermes在“没有可审查的代码”时也发一条简短评论或者把Check Run置为success告诉人类“我看了没有发现问题”。这对团队信任建设很重要。下面这个排查表是我给团队整理过的直接抄走就能用症状可能原因解决方式workflow完全没有执行文件路径错误或事件类型不对检查.github/workflows/下文件核对on.pull_request配置Action执行失败日志403permissions权限不足在workflow中显式声明pull-requests: write和checks: write自托管Webhook一直409Webhook Secret不匹配或为空在GitHub App中设置Secret与Hermes环境变量保持一致Hermes跑完不发评论没有规则命中或rules未启用检查配置中的enabled_rules空结果建议开空提示评论发了几百条comment_policy未配置聚合配置mode: aggregate和max_findings5.2 GITHUB_TOKEN 权限不足用Actions方式接入的时候最常见的问题就是GITHUB_TOKEN权限不足。这类报错通常发生在Hermes尝试创建评论或创建Check Run时报错信息是403 Resource not accessible by integration或者GraphQL: Resource not accessible by integration。这里的坑在于GitHub Actions给的默认GITHUB_TOKEN只有contents: read权限并没有pull-requests权限。很多第一次接入的人会去仓库的Settings里手动生成一个高权限token来替代但我建议不要这么做。手动token权限过大一旦仓库或服务器泄漏波及面很广。正确的做法是精确声明最小权限就像前面2.1节里的workflow那样。如果你确实需要更高权限也应该在仓库的Settings - Actions - General - Workflow permissions里调整而不是创建一个永不失效的PAT。还有一个容易被忽视的点自托管GitHub App方式中App的权限需要在GitHub App设置页单独配置比如Pull requests: Read write、Checks: Read write改完权限后必须执行一次新安装的流程才能生效手动改App权限但没重新安装权限变更不会实时同步。5.3 误报抑制与规则微调误报是自动化审查工具最大的“民心杀手”。一次误报可能没什么但一个误报率高的机器人很快会被团队默契地忽略。Hermes的误报抑制我总结了三招。第一招是白名单适合no-secrets这种格式匹配型规则。把测试用的假密钥、示例代码里固定字符串加进allowlist。但要提醒一句白名单要尽量精确不要整目录放开否则等于把这个文件里的真实密钥也放过了。第二招是增量模式这是对付存量仓库的利器。老仓库里历史问题成百上千但base_mode: incremental只对新增代码做审查误报和存量噪声在源头被砍掉一大半。等团队习惯了增量代码必须干净再慢慢安排技术债务专项来治理存量问题。这种方式比一次性全校验温和得多也更容易被团队接受。第三招是规则分级调权重。我通常会把规则的输出按严重级别分三档error级必须修复才有讨论余地warning级允许PR作者说明情况后忽略low级只在聚合评论里以摘要形式出现不进Check Run状态。通过这种方式真正影响合并的永远是少量高置信度问题其他问题保留可查但不会打扰人。实际用下来我还发现一个辅助技巧把Hermes的审查结果导出来每周拉一个“哪些错误重复出现最多”的统计。如果某类warning连续两周高频出现就说明光靠PR阶段提示不够应该去更新团队的编码规范文档或者在CI里加一个更前置的检查。工具治标规范治本两者结合才能把代码质量真正往上拉。这个项目接入到现在我最大的体会是自动化代码评审的价值不在“替代人”而在“把人从重复劳动里解放出来”。Hermes把机械性的问题挡在合并前Human reviewer终于有精力去讨论那些真正需要业务判断和高层设计的部分。如果你团队的PR审查也开始变成流水线式扫雷建议你花一个下午把Hermes接进去先跑一周增量模式看看人工review时间的变化再决定要不要继续深入调规则。
Hermes实战：GitHub PR自动化代码评审与提效指南
做技术负责人这几年我每天最耗时间的动作不是写代码而是Review PR。不是不想认真看而是大部分PR里真正需要人思考的逻辑问题只占两成剩下的都是格式不统一、空指针隐患、密钥泄漏这类一眼就能判断的问题。后来我把Hermes接到GitHub仓库上让它在每个PR开出后自动跑一遍代码评审把低质量变更挡在合并之前。现在团队每天的PR审查时间大概压缩了一半Human Reviewer只需要盯着Hermes标记出来的高危项和高层设计问题就行。这篇文章就是Hermes在GitHub PR审查场景里的完整落地总结包括架构思路、部署方式、规则配置和我在真实仓库里踩过的坑。1. 项目概述与设计思路1.1 为什么要做自动化代码评审先说一个我自己的观察代码评审这件事越往后越像在“扫雷”。刚开源项目或者小团队的时候PR数量少每条PR逐个文件看也花不了多少时间。但一旦仓库进入多人协作状态每天三五个PR甚至十几个PR人工审查就开始出现明显问题。第一是重复劳动。很多问题是同一类问题反复出现比如JavaScript项目里常见的console.log忘记删除、Python里裸except吞掉异常、配置项里把明文密钥提交上来。这类问题不是不会写纯粹是忙起来顾不上人工review去抓这种问题性价比极低。第二是标准不统一。同样一段代码A审查者觉得可以合B审查者会要求重构最后变成“谁审查谁说了算”代码风格越来越散。第三是周期拉长。PR挂一整天没人看合并时间不可控需求迭代速度被卡在“等人review”这一环上。Hermes解决的正是这些问题。它本质上是一个挂在GitHub PR事件上的自动化审查管道PR一开出来自动拉取diff跑一组可配置的分析器然后把结果以Comment和Check Run的形式回写到PR页面。人工reviewer只看结论挑重点深入讨论不需要再花时间做机械判断。它适合个人项目也适合小团队和平台工程化团队区别只在于你选择哪种部署方式。1.2 Hermes 的核心架构与完整工作流我第一次拿到Hermes的时候第一反应是“这不就是个机器人吗”后来我把它的数据流完整理了一遍才发现它的设计比我想象的克制。事件入口有两种一种是挂在GitHub Actions里靠workflow的pull_request事件触发另一种是部署一个自托管服务通过GitHub App接收Webhook推送。无论哪种入口触发之后的核心管道大致是四段式第一步收集变更集。从GitHub API拉取PR的元信息、提交列表、文件级别的diff注意这里不是把整个仓库clone下来而是按PR数据接口拿变更内容这样在超大仓库里也能控制数据量。第二步执行分析器链。这是Hermes的精髓。它不是一个单一检查器而是一个插件化的分析器集合常见的包括静态Lint检查、密钥泄漏扫描、复杂度分析、重复代码检测、依赖漏洞扫描以及可选的LLM语义分析。每个分析器独立并行跑互不阻塞最后把结果统一回传到聚合器。第三步结果聚合与去重。多个分析器可能报同一个问题比如一个高复杂度函数既触发复杂度警告又在LLM分析里被点名聚合器需要按“文件行号问题类型”做指纹去重再按严重级别排序控制最终输出的条数。第四步结果回写。在PR上创建一条聚合评论同时创建Check Run。Check Run的好处是可以直接接入分支保护Hermes如果判定存在error级别的规则命中Check Run状态置为failed这个PR在保护规则下就无法点Merge按钮。这套管道最让我满意的地方是插件化。我后来自己加了一个针对公司内部私有组件的扫描器只需要实现一个分析器接口把结果格式化成统一的ReviewFinding结构主流程完全不用动。用生活化类比来说Hermes就像一条自动流水线每个分析器是流水线上的质检工位各管一摊最后汇总到总控台。2. 部署接入两种方式怎么选2.1 方式一GitHub Actions 轻量接入如果你的仓库数量不多或者还在验证阶段我强烈建议先用GitHub Actions方式这是成本最低的一条路径。不需要维护服务器权限模型由GITHUB_TOKEN天然承载触发事件也是GitHub自动帮你想好了。在仓库根目录创建.github/workflows/hermes-review.yml一个最简可用的配置长这样name: hermes-review on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write checks: write jobs: hermes: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run Hermes PR Review uses: your-org/hermes-actionv1 with: github_token: ${{ secrets.GITHUB_TOKEN }} config: .hermes/config.yml几个关键点我展开说一下。types里为什么是opened, synchronize, reopened这三个opened是PR第一次开出synchronize是开发者又推了新提交reopened是关闭后重新打开。这三类事件基本覆盖了PR全生命周期内的主要变更时刻。注意视觉效果上第一次提交和后续提交都会被自动覆盖不需要额外设置。permissions这一块很多人会忽略但它是Action最常见报403的根源。GitHub默认的GITHUB_TOKEN权限其实很保守如果你不显式声明pull-requests: write和checks: writeHermes去写评论、创建Check Run都会被拒日志里就报一个让人摸不着头脑的403。我建议按最小权限原则来写不要图省事把整个token权限拉到write-all。这个Action方式还有两个隐藏优点日志直接在Actions页面可视化查看排查问题非常直观每次触发都是一次干净的容器环境不会出现本地依赖污染。缺点是大型仓库拉diff慢以及如果需要接私有化的大模型接口Action环境不好配置网络访问。2.2 方式二Docker 自托管服务当仓库超过十个、需要统一管理多仓库的审查配置或者想给Hermes接上内部专用的模型服务时Action方式就开始别扭了。这时候我建议自托管一个Hermes服务用Docker一挂让它通过GitHub App监听所有目标仓库的PR事件。先贴一份我生产环境在用的docker-compose.yml做了最小化脱敏services: hermes: image: hermes/reviewer:latest restart: unless-stopped ports: - 8080:8000 environment: GITHUB_APP_ID: 123456 GITHUB_APP_PRIVATE_KEY_PATH: /run/secrets/hermes.pem HERMES_CONFIG_PATH: /app/config/config.yml LLM_API_URL: http://llm-proxy:8080 volumes: - ./config:/app/config - ./secrets:/run/secrets这里有个选择接入GitHub用Personal Access Token还是GitHub App我强烈建议用GitHub App。原因有三点。权限隔离App的权限可以精确到某几个仓库的pull request读和写而PAT一旦在服务器上泄漏等于把你账号下所有可见仓库都暴露了。可审计性App每次操作都会以机器身份出现在仓库的动态里不会和个人的提交记录混在一起。集中管理一个App可以安装到多个仓库在GitHub组织设置里统一授权和吊销比在每台服务器上维护PAT要优雅得多。Webhook的配置需要在GitHub App的设置页面填一个Payload URL指向你Hermes服务的/webhook路径。这里有个我踩过的坑Webhook的Secret一定要设置而且要和Hermes环境配置里的WEBHOOK_SECRET保持一致否则GitHub推送的请求会因为签名校验失败被服务器直接拒掉。第一次调试时我就是忘了配这个字段GitHub后台一直显示webhook请求409排查了半小时才发现是签名问题。自托管还有一个隐藏收益你可以把模型判断结果、历史审查数据落库之后想做一个“哪些文件最容易出问题”的统计面板就有了数据基础。Action方式虽然轻但数据是零散的不方便做长期质量分析。2.3 配置文件编写要点不管用哪种部署方式Hermes的规则控制都在一个YAML配置文件里。我见过一个很常见的误区拿到Hermes就默认配置跑结果它在你几千行代码的老仓库里刷出一堆存量问题评论长达几百条直接把团队吓退了。所以配置文件里的路径过滤和基线模式是第一批要调的东西。我的建议配置结构是这样的repository: owner: your-org name: your-repo review: enabled_rules: - no-secrets - complexity - lint-eslint - dependency-vuln path_filters: exclude: - **/package-lock.json - **/dist/** - **/generated/** base_mode: incremental comment_policy: mode: aggregate max_findings: 20 max_repeats: 3 severity: error: - no-secrets - dependency-vuln warning: - complexity - lint-eslintbase_mode: incremental这个参数是关键。它意味着Hermes只审查当前PR相对于目标分支新增和修改的行存量问题一概不报。这非常重要因为老仓库往往积压了大量历史遗留问题一上来全量报会把噪声放大到无法使用。先保证增量代码干净再逐步治理存量这才是可持续的落地节奏。comment_policy.max_findings是控制评论上限的一般设置在20条左右比较合适。超过上限的发现会被折叠到一个summary里避免刷屏。我见过一些团队因为评论太多直接想卸载Hermes其实问题不是工具不好而是没设上限。3. 审查规则与核心配置3.1 静态检查与规范类规则怎么配静态检查是Hermes最基础的能力也是“回本最快”的一类规则。你不需要让Hermes替代Human做设计评审只需要让它在错误还停留在代码库之前拦住它。常见的静态规则包括Lint检查JavaScript用ESLint、Python用flake8/Ruff、Go用golangci-lint、圈复杂度、重复代码、废弃API调用、TODO/FIXME遗留扫描。Hermes的规则引擎本质上是把外部工具的JSON输出转成统一的审查结果所以你在原生工具里配好的规则在Hermes里依然生效。以复杂度规则为例我会给一个实际参数建议rules: complexity: enabled: true threshold: total: 50 per_function: 15 incremental_threshold: per_function: 10per_function是单函数圈复杂度阈值行业惯例一般是15。但如果你希望新代码质量更高可以把incremental_threshold单独压到10这样存量代码超过15才报新增代码超过10就报二者不冲突。我在这套配置下跑了两周团队新代码的平均函数复杂度确实降下来了因为Hermes会在PR阶段直接提示开发者发现“这条函数太长了合并不过去”自然就会主动拆函数。重复代码检测同样值得重视尤其在多人维护的仓库里。我建议基于AST级别的重复检测而不是简单的文本相似度不然会把两个结构类似但语义不同的函数误判成重复。配置上可以设置最小重复块长度比如连续重复超过20行才报告避免大量琐碎的误报。3.2 安全与依赖扫描值得设为硬阻断的规则如果说静态检查是Hermes的“日常工作”那安全扫描就是它最应该被赋予“生杀大权”的部分。两条规则我建议直接设置成severity: error一旦命中就让Check Run失败阻断合并no-secrets密钥泄漏检测和dependency-vuln依赖漏洞扫描。no-secrets的检测思路是正则匹配加熵检测。正则匹配负责识别常见格式比如AWS Access Key、GitHub Token、SLACK_TOKEN这类结构化密钥熵检测负责找出高随机性的字符串防止自定义密钥或内部凭证漏网。这个规则容易误报尤其是测试代码里经常会出现模拟的密钥记得配置白名单。rules: no-secrets: enabled: true severity: error allowlist: - AKIAIOSFODNN7EXAMPLE - test-token - **/test/**dependency-vuln需要接入漏洞数据库。Hermes通常通过读取项目锁文件package-lock.json、poetry.lock、go.sum等把依赖版本对到漏洞库上。这里有一个实用建议锁文件建议走path_filters.exclude排除掉不参与diff分析但dependency-vuln规则特殊它会单独读取锁文件做全量扫描所以不需要在path里排除。为什么这两条要设为error因为它们修复成本极低、风险极高。一条泄漏的密钥流到公开仓库几分钟内就可能被自动脚本扫走造成实际损失。这类问题没有任何讨论余地直接让PR卡住是最科学的流程。3.3 AI 辅助评审的调优实战Hermes最有新意的地方是它可以接入大模型做语义分析。规则引擎只能查已知问题对于“这个函数在并发场景下有竞态条件”“这里缺少权限校验”这类语义问题传统工具无能为力。而LLM正好擅长理解代码意图和上下文。我推荐的做法是把LLM分析作为一个增量分析器和传统规则并行但需要做三个调优动作。第一限制输入规模。整个PR的diff可能很大直接全部塞给模型既慢又贵。Hermes会把diff按文件拆块每个块控制在8K token以内并且只对incremental模式下的新增代码做分析。你可以设置max_analysis_files: 10超过10个文件的新增代码就只采样分析避免一次PR烧掉大量token。第二约束输出格式。让模型返回结构化的发现列表而不是自由文本这样结果才能进聚合器。rules: llm-semantic: enabled: true provider: openai-compatible model: your-model-name max_findings: 10 confidence_threshold: 0.7 system_prompt: | 你是资深代码评审专家。请审查以下diff中的新增代码 只返回确定性的问题格式为 file:行号|严重级(high/medium/low)|问题描述。 不要输出赞美或概括性评论。第三处理误报。LLM的审查建议偶尔会给出明明正确但实际不需要修改的“建议”比如“建议加注释”这类噪声。我通过confidence_threshold和severity_with_model组合压制只有在模型置信度高于0.7且严重级别为high时结果才会进入最终的评论列表medium以下的结果只记录在日志里供开发者主动查看。这样既保留了语义审查的能力又不会污染PR评论区。4. 实操案例与结果解读4.1 一个典型 PR 的完整审查过程我拿一个真实情况的简化版来做讲解。假设有这样一个PR后端登录模块增加“记住我”功能改动涉及三部分auth_service.py新增了token刷新逻辑、schema.sql加了用户会话表、前端login.js调用新接口。PR一开出来Hermes自动开始跑。我们看这次审查产生的结果结构auth_service.py第37行no-secrets规则命中检测到硬编码的JWT secretseverityerror。这个必须修不然合并后生产环境等于裸奔。auth_service.py第58行complexity规则命中函数_refresh_token的圈复杂度为18超过新增阈值10severitywarning。这里提示代码可能逻辑分支过多建议拆函数。schema.sql第12行dependency-vuln未命中但lint-sql提示缺少service字段的注释severitylow。login.js第20行LLM语义分析命中一条high提示“token刷新失败时没有清理已有cookie存在会话残留风险”这个点是纯规则引擎抓不出来的。整个审查过程大约用时50秒。如果全部由人工来review至少要15分钟而且login.js这个会话残留问题大概率会被当成“细节问题”漏过去。Hermes的价值就在这里它把人的注意力从“查找问题”转移到了“决策问题”。PR作者看到Review结果后修掉了error级密钥问题拆分了高复杂度函数并用?请求半天后再跑一次Hermes检查重新变为pass才进入人工review和合并流程。这个闭环非常顺畅。4.2 评论聚合与状态检查的配置技巧Hermes默认会在PR上发评论但如果每条finding单独发一条评论几十条评论刷屏会让PR页面完全不可读。所以聚合评论是必须开启的。我这边实际用的配置是comment_policy: mode: aggregate update_on_new_commit: true max_findings: 20update_on_new_commit这个参数也很实用。它会让Hermes在同一PR有新提交时复用上一条评论进行内容更新而不是再发一条新评论。这样PR页面只会有“一条”Hermes评论内容始终是最新状态。配合max_findings: 20就算扫描结果非常多也只会把Top 20放出来其余折叠到summary里。Check Run的部分同样重要。Hermes会创建一个名为Hermes Review的Check Run并对每条error级规则的结果返回conclusion: failure。这看起来只是一个小小的状态标记但实际效果很惊人因为Check Run的状态可以直接被GitHub的分支保护规则识别。4.3 结合分支保护让错误无法合并如果你只把Hermes当“评论机器人”它能帮你提问题但开发者可以选择无视问题照样合进去。所以要把它的价值放大必须接入分支保护。在GitHub仓库的Settings - Branches - Branch protection rules里我给main和dev分支都配置了以下内容勾选“Require status checks to pass before merging”在搜索框里输入Hermes Review选中这个Check Run勾选“Require branches to be up to date”如果需要的话这套配置生效后逻辑变得非常简单只要有error级别的规则命中Hermes的Check Run就是fail状态Merge按钮直接置灰没有管理员权限的人根本点不动。开发者要吗修复问题要吗提交时使用更安全的写法。长此以往团队代码基线整体都会被抬起来。这里有一个实测的经验一开始不要把所有规则都设为error只把no-secrets和dependency-vuln这种明确红线设为error其余warning先留给人工判断。否则第一天Hermes上岗就可能把好几个人的PR全部卡住给团队带来强烈的挫败感。先让工具打出第一场小胜仗再逐步收紧规则是推进自动化评审更平滑的方式。5. 常见问题与排查技巧5.1 事件不触发或重复触发这类问题是我被问得最多的我用排掉时间最多的三个案例说明。一个是new PR根本不触发95%的原因是workflow文件路径或事件类型写错。确认文件在.github/workflows/下、后缀是yml或yaml、事件类型与预期一致。可以到Actions页面看有没有workflow记录如果连workflow记录都没有说明仓库压根没识别到文件。另一个问题是PR更新后重复触发synchronize事件会在每次push到PR分支时触发这本身是预期的。但如果一次push包含4个commitworkflow不会触发4次只会合并触发一次。如果你发现Hermes被触发了多次检查有没有多个workflow文件都监听了pull_request事件或者是不是Webhook和Actions同时接了两条入口。还有一个我很早之前踩过的坑PR里只改了.md文件Hermes启动后扫描diff没有任何匹配的文件类型于是静默退出连评论都不发。这样的体验会让开发者以为系统坏了。我建议在配置里显式开启一个空结果提示开关让Hermes在“没有可审查的代码”时也发一条简短评论或者把Check Run置为success告诉人类“我看了没有发现问题”。这对团队信任建设很重要。下面这个排查表是我给团队整理过的直接抄走就能用症状可能原因解决方式workflow完全没有执行文件路径错误或事件类型不对检查.github/workflows/下文件核对on.pull_request配置Action执行失败日志403permissions权限不足在workflow中显式声明pull-requests: write和checks: write自托管Webhook一直409Webhook Secret不匹配或为空在GitHub App中设置Secret与Hermes环境变量保持一致Hermes跑完不发评论没有规则命中或rules未启用检查配置中的enabled_rules空结果建议开空提示评论发了几百条comment_policy未配置聚合配置mode: aggregate和max_findings5.2 GITHUB_TOKEN 权限不足用Actions方式接入的时候最常见的问题就是GITHUB_TOKEN权限不足。这类报错通常发生在Hermes尝试创建评论或创建Check Run时报错信息是403 Resource not accessible by integration或者GraphQL: Resource not accessible by integration。这里的坑在于GitHub Actions给的默认GITHUB_TOKEN只有contents: read权限并没有pull-requests权限。很多第一次接入的人会去仓库的Settings里手动生成一个高权限token来替代但我建议不要这么做。手动token权限过大一旦仓库或服务器泄漏波及面很广。正确的做法是精确声明最小权限就像前面2.1节里的workflow那样。如果你确实需要更高权限也应该在仓库的Settings - Actions - General - Workflow permissions里调整而不是创建一个永不失效的PAT。还有一个容易被忽视的点自托管GitHub App方式中App的权限需要在GitHub App设置页单独配置比如Pull requests: Read write、Checks: Read write改完权限后必须执行一次新安装的流程才能生效手动改App权限但没重新安装权限变更不会实时同步。5.3 误报抑制与规则微调误报是自动化审查工具最大的“民心杀手”。一次误报可能没什么但一个误报率高的机器人很快会被团队默契地忽略。Hermes的误报抑制我总结了三招。第一招是白名单适合no-secrets这种格式匹配型规则。把测试用的假密钥、示例代码里固定字符串加进allowlist。但要提醒一句白名单要尽量精确不要整目录放开否则等于把这个文件里的真实密钥也放过了。第二招是增量模式这是对付存量仓库的利器。老仓库里历史问题成百上千但base_mode: incremental只对新增代码做审查误报和存量噪声在源头被砍掉一大半。等团队习惯了增量代码必须干净再慢慢安排技术债务专项来治理存量问题。这种方式比一次性全校验温和得多也更容易被团队接受。第三招是规则分级调权重。我通常会把规则的输出按严重级别分三档error级必须修复才有讨论余地warning级允许PR作者说明情况后忽略low级只在聚合评论里以摘要形式出现不进Check Run状态。通过这种方式真正影响合并的永远是少量高置信度问题其他问题保留可查但不会打扰人。实际用下来我还发现一个辅助技巧把Hermes的审查结果导出来每周拉一个“哪些错误重复出现最多”的统计。如果某类warning连续两周高频出现就说明光靠PR阶段提示不够应该去更新团队的编码规范文档或者在CI里加一个更前置的检查。工具治标规范治本两者结合才能把代码质量真正往上拉。这个项目接入到现在我最大的体会是自动化代码评审的价值不在“替代人”而在“把人从重复劳动里解放出来”。Hermes把机械性的问题挡在合并前Human reviewer终于有精力去讨论那些真正需要业务判断和高层设计的部分。如果你团队的PR审查也开始变成流水线式扫雷建议你花一个下午把Hermes接进去先跑一周增量模式看看人工review时间的变化再决定要不要继续深入调规则。
