企业官网建设流程全解析

写自动化代码评审这件事，我琢磨了挺长时间。代码评审一直是研发流程里最费人力、又最容易流于形式的一环，而把 Hermes 这种智能体接到 GitHub PR 上做审查，正好能把“人盯人”变成“人机配合”。这篇文章我会把我搭这套系统的完整思路、具体配置、踩过的坑和实际效果一次性讲清楚，适合后端开发、研发效能工程师，以及所有想给团队引入 AI 审查的读者。内容里涉及的步骤和配置示例都可以直接照着复制，再根据自己的项目情况调整。

1. 整体设计思路：一套PR审查系统要解决什么问题

1.1 传统代码评审的痛点和自动化机会

先聊点实际的。做过几年研发管理的朋友应该都有感受：PR 评审看着是个“把关”动作，实际上大多数时候是负担。开发者在深夜提了 PR，第二天 reviewer 打开一看，500 行改动，其中 300 行是格式化调整，真正需要动脑的逻辑只有 100 行。这时候 reviewer 能怎么办？大概率是挑几个明显的问题评论一下，然后 Approve。不是不负责任，而是人的精力和注意力确实有限，让工程师把时间花在逐行扫改动上，本身就是一种浪费。

自动化代码评审的价值就在于把“读代码”和“评代码”这两个动作拆开。重复性、机械性的问题交给机器，比如风格不一致、明显的内存泄漏风险、安全敏感函数使用不当、缺少异常处理等等。人只需要看机器标记出来的高优先级问题，以及机器无法判断的架构层面的事情。这和我之前折腾过的一些静态分析工具不同，那些工具虽然也能发现问题，但通常只会报“规则触发了”，不会告诉你“这里的并发处理有问题，建议加锁并评估竞态条件”。而 LLM 擅长的地方恰好就在这——它能综合上下文理解代码意图，给出带解释的、像人话一样的建议。

选择 Hermes 来干这件事，核心原因是它作为智能体，不是简单地“读一段代码然后输出一段话”，而是可以编排成一个完整的工作流：拉取 PR 元数据、读取 diff、逐个文件分析、汇总问题、调用 GitHub API 提交评论。如果把传统 LLM 比作一个只会回答问题的顾问，那 Hermes 更像一个有手有脚的员工，能把“审查”这件事从头做到尾。

1.2 自动化审查的系统边界和目标设定

设计这套系统之前我给自己定了几个边界，避免做到一半失控。

第一，自动化审查的目标不是“替代人做决定”，而是“帮人快速定位高价值信息”。所以系统输出必须是结构化的：每个问题要标注文件位置、严重级别、修改建议，All 的评论要能在 PR 页面上直接看到。第二，不要追求“一次审查解决所有问题”，先聚焦在逻辑缺陷、安全隐患和明显违反团队规范的问题上，把误报率控制在可接受范围内，否则 reviewer 每次都要看一堆废话，最后肯定会把 bot 关掉。第三，响应速度要快，PR 提交后 2 到 3 分钟内必须给出初步意见，慢了就失去了意义。

基于这些目标，我确定的系统形态是这样的：GitHub 仓库配置 Webhook，当 PR 的 open、synchronize 事件触发时，把事件推送给本地运行的一个服务；服务收到事件后，调用 GitHub API 拿到 PR 的元数据和 diff 内容；将 diff 切分、分批送入 Hermes 智能体，由它按预设的审查规则进行分析；最后把分析结果整合，以评论的形式提交到 PR 对应的 Commit 或 Conversation 里。

这个链路看起来不复杂，但真正落地的时候会碰到一堆细节，比如 diff 过大怎么切分、并发请求怎么控制、审查结果怎么去重、Hermes 偶发超时怎么处理。这些我后面一步步讲。

2. 技术方案深度拆解：Hermes在审查链路中的角色

2.1 选型对比：为什么用Webhook而不是定期轮询

立项的时候我第一个纠结的问题是，用 Webhook 实时触发，还是写一个定时任务去扫所有 open 的 PR。后来我选的是 Webhook，原因很直接：轮询的延迟不可控。假设每 5 分钟扫一次，一个 PR 从提交到被审查，最坏情况要等 5 分钟，而且随着仓库变多、PR 数量增加，轮询会反复拉取没变化的 PR，白占 API 配额。GitHub 的标准 API 未认证时一小时 60 次，认证后一小时也才 5000 次，看起来不少，但如果你有几十个仓库，每次拉取都要请求多个接口，配额消耗非常快。

Webhook 的方式是事件驱动的，PR 一变就通知你，没有多余的请求。这个模式在 GitHub 上非常成熟，仓库 Settings 里配置一个 Webhook URL，选择推送 events，GitHub 就会在对应事件发生时把 JSON payload POST 到你提供的地址。我实际配置的时候选择了pull_request事件，并且在服务端对 action 做了过滤，只处理opened和synchronize（也就是 PR 更新了代码）两种情况。reopened我觉得也可以处理，但实践下来容易和synchronize重复触发，所以干脆砍掉。

还要注意一件事：Webhook 默认对网络要求确定，你的服务必须能从 GitHub 外网地址访问到。如果服务部署在有防火墙的内网，需要在防火墙开一个公网可达的入口，或者用内网穿透类工具把本地服务暴露出去。这个问题后面会专门在常见问题里展开。

2.2 Hermes智能体在审查流程中的职责划分

整个系统里有几个角色：GitHub Webhook 是事件源，服务端是一个胶水层（我用 Python 写的，比较顺手），Hermes 是分析引擎，GitHub API 是回写通道。这些角色各管各的，尽量不要互相越界。

我踩过的第一个坑就是把太多逻辑塞进 Hermes。最开始我让 Hermes 自己决定“该审查哪些文件”“跳过哪些文件”“怎么调 GitHub API 回评论”，结果整个流程变得不可控，它经常做出奇怪的选择，比如漏掉关键文件，或者干脆在分析中间停下来。后来我把职责重新划分清楚了：胶水层负责所有确定性的操作——拉取数据、解析 diff、过滤文件、调用 API、格式化输出；Hermes 只负责它最擅长的一件事，就是“理解代码并输出评审意见”。这让整个系统的行为变得可预测，排查问题也容易很多。

用生活里的例子来说，Hermes 就好比是医院里的专家门诊医生，他只负责看片子、写诊断意见；而挂号、拍片、取报告这些流程性的事情，是护士和前台干的。你非要让专家去挂号，那门诊效率一定乱套。

2.3 审查服务的运行形态和部署位置

关于 Hermes 部署在什么位置，我试过两种方式。一种是直接跑在开发机上，简单省事，适合个人项目和刚开始试验的阶段；另一种是用 Docker 跑在服务器上，稳定可控，适合团队正式使用。我最终选择了 Docker 部署，原因有三：一是服务器 7x24 小时在线，PR 什么时候提交都能及时响应；二是环境隔离，不会因为开发机升级、换电脑导致服务中断；三是资源可控，Hermes 这类 LLM 应用吃内存和 CPU 比较猛，用容器可以限制资源上限。

如果你只是自己玩，开发机上跑完全没问题，只要保证服务不关机就行。我见过有人直接挂在个人电脑上，后来电脑合盖休眠，PR 审查静默失败了好几天才发现。所以正式使用，至少也要扔到一台长期在线的机器上。

3. 核心细节落地方案：审查规则、提示词与实践配置

3.1 审查规则的设计原则：先定红线，再谈风格

很多人做 AI 代码审查，上来就让模型“全面分析代码质量”，结果输出了一堆“建议增加注释”“建议提取公共方法”这种正确的废话，Reviewer 越看越烦。我的做法是先把审查规则分级，让模型知道轻重缓急。

我把规则分成三个级别。第一级是阻断级，发现这类问题应该直接 Request Changes，包括明显的空指针/未定义变量、SQL 注入/命令注入等安全风险、死循环或递归无出口、密钥硬编码等等。第二级是警告级，包括异常被吞掉、资源未关闭、并发访问未加锁、明显的逻辑分支错误。第三级是建议级，比如命名不规范、函数过长、缺少必要的注释。这个分级的意义在于给模型一个明确的输出框架，让它把评审意见按 Severity 分组，用户在 PR 页面上能一眼看出哪些必须处理，哪些可改可不改。

规则不是一次性定死的。我第一版规则写得非常细，结果 Hermes 在“是否算违反规范”上频繁纠结，反而忽略了真正重要的逻辑问题。后来我把规则收敛到 10 条以内，每条都用“条件 + 示例 + 严重级别”的格式写清楚，效果反倒更好。

3.2 提示词模板的工程化写法

Prompt 是这套系统里最值得反复打磨的部分。我现在的提示词大致结构是这样的：角色设定、仓库背景信息、评审规则、输出格式要求、兜底指令。角色设定很关键，我让 Hermes 扮演“有 10 年经验的后端技术专家”，这个设定不是为了玄学，而是能明显提升它在输出时的专业度和条理性。

仓库背景信息我通过一个配置文件的变量注入，包括项目类型、技术栈、常用框架版本、团队约定等。这些信息能让 Hermes 在分析时更有针对性，比如知道这是个 Spring Boot 项目，它就会主动关注 Bean 注入、事务、循环依赖等问题；如果是个 Python 项目，它就会关注 GIL、异步、内存引用等问题。

输出格式我是这样设计的，要求 Hermes 按 Markdown 格式输出，每个问题包含：文件路径、行号（如果 diff 里有）、问题描述、严重级别、修改建议。下面是我实际在用的简化版提示词，你们可以参考：

你是一位拥有10年后端开发经验的高级工程师，正在为一个{project_type}项目做代码审查。 项目技术栈：{tech_stack} 团队规范要点：{team_rules} 请审查以下 Pull Request 的代码变更，重点关注： 1. 逻辑错误和边界条件 2. 安全漏洞（注入、越权、敏感信息泄露等） 3. 资源管理和异常处理 4. 并发与性能问题 5. 严重违反团队规范的问题 输出格式要求： - 使用Markdown格式 - 每个问题单独一段，格式为：**【严重级别】文件路径:定位位置** - 问题描述 + 修改建议 - 严重级别只允许三个值：BLOCKER（必须修复）、WARNING（应该修复）、SUGGESTION（可选改进） - 如果没有发现任何问题，输出：LGTM，未发现明显问题。 下面是需要审查的代码变更内容： {diff_content}

这个模板看起来不复杂，但实际调试的时候发现一个关键问题：如果 diff 内容太长，Hermes 容易漏看后面的文件。所以我在胶水层把 diff 按文件切块，每个文件单独送一个完整的审查请求，最后再合并结果。这样单个请求的内容量小了，模型注意力更集中，错误率明显下降。

3.3 审查速度和成本的控制策略

Herman 处理一份 diff 的速度和质量，跟你怎么控制上下文有直接关系。我最早图省事，把整个 PR 的完整 diff 一次性丢给 Hermes，结果改动稍微大一点，响应时间就飙到 5 分钟以上，而且经常出现“只分析了前几个文件”的情况。后来我做了一个很简单的优化：按文件维度拆分，每个文件都作为独立的审查任务执行。这样每个任务的数据量控制在合理范围内，执行速度稳定在 30 秒到 1 分钟，而且可以并发执行多个文件的审查，整体耗时反而比串行一次性处理还要短。

成本方面也要算账。如果用云端 LLM 接口，按 token 计费，一次上百行 diff 的 PR 审查大约消耗 1 到 2 万 token。如果团队 PR 比较多，一个月几百次审查，成本并不算低。我的解决办法是：只审查改动的行，不把整个文件全量送进上下文。GitHub 的 API 可以直接拿到 PR 的 diff，这个 diff 本身就只包含变更内容，所以上下文利用率很高，不会浪费在没改的代码上。另外，对于超过 300 行的超大 PR，我设置了自动跳过规则，只在 PR 上评论一句“本次改动过大，建议拆分为多个小 PR 以便人工审查”。这不是逃避，而是因为超大 PR 本身就不符合良好的 Code Review 实践，让 bot 硬上也看不过来。

3.4 与GitHub API交互的几个关键细节

和 GitHub API 打交道，认证方式我用的是一开始的 Token 模式，创建一个 Fine-grained personal access token，只授予目标仓库的 Pull requests 读写权限和 Contents 读取权限。权限最小化这个原则一定不要省，不要图省事开 repo 全权限，万一 token 泄露，影响面可以控制住。

拿 PR diff 有两个接口可以用。一个是GET /repos/{owner}/{repo}/pulls/{pull_number}，带Accept: application/vnd.github.diff头，直接拿完整 diff 文本；另一个是列出 PR 的文件GET /repos/{owner}/{repo}/pulls/{pull_number}/files，能拿到每个文件的具体 patch，以及文件名、状态（added/modified/removed）。两个我都会用到：files 接口用于过滤和切分，diff 接口用于最终组装成审查任务。注意 files 接口分页默认 30 条，PR 改动文件特别多时需要用per_page=100或者翻页，这个细节容易漏。

提交评论我用的是POST /repos/{owner}/{repo}/pulls/{pull_number}/comments，这是 PR 的常规评论接口。如果你想做行内评论（inline review comment），要用POST /repos/{owner}/{repo}/pulls/{pull_number}/comments的带 position/line 参数版本，或者在 GraphQL 里用 addPullRequestReviewThread mutation。行内评论效果好，但实现复杂度高一些，对行号的映射要求准确，diff 更新后行号可能失效。我第一版用的行内评论，后来发现这个问题太频繁，干脆改成了统一汇总评论，稳定性优先。

4. 实操全流程：从零搭建Hermes PR审查机器人

4.1 环境准备与配置清单

我假设你已经有一个 GitHub 仓库，并且本机或者服务器上有 Python 3.10 以上环境。需要的依赖不多，核心是requests和hermes-agent（如果 Hermes 是作为 Python 库调用的）。另外需要准备两样东西：一个 Hermes 运行环境（本地模型或云端接口，取决于你用的部署方式），一个 GitHub token。

我的环境清单如下，可以照抄：

4.2 创建审查服务主程序

我写的服务核心逻辑其实很薄，大致分这几步：接收 Webhook → 解析 event → 判断是否需要处理 → 拉取 PR 信息并准备 diff → 调用 Hermes 审查 → 提交评论。下面是一个简化版的代码骨架，用的 Flask 做 Webhook 接收端：

import os import json import requests from flask import Flask, request, jsonify app = Flask(__name__) GITHUB_TOKEN = os.environ["GITHUB_TOKEN"] GITHUB_API = "https://api.github.com" REPO_OWNER = "your_org" REPO_NAME = "your_repo" HEADERS = { "Authorization": f"Bearer {GITHUB_TOKEN}", "Accept": "application/vnd.github+json", } @app.route("/webhook", methods=["POST"]) def webhook(): payload = request.json if payload.get("action") not in ("opened", "synchronize"): return jsonify({"ok": True}) pr_number = payload["pull_request"]["number"] # 放到后台线程处理，避免Webhook响应超时 import threading threading.Thread(target=review_pr, args=(pr_number,)).start() return jsonify({"ok": True}) def review_pr(pr_number): # 1. 获取PR信息 pr_url = f"{GITHUB_API}/repos/{REPO_OWNER}/{REPO_NAME}/pulls/{pr_number}" pr_info = requests.get(pr_url, headers=HEADERS).json() title = pr_info["title"] description = pr_info.get("body") or "" # 2. 获取文件级diff files_url = f"{pr_url}/files?per_page=100" files = requests.get(files_url, headers=HEADERS).json() # 3. 按文件逐个送Hermes审查 review_results = [] for f in files: if f["status"] == "removed": continue # 删除的文件不用审查 patch = f.get("patch") if not patch: continue # 文件名带路径，审查意见里要能定位 result = hermes_review_file(f["filename"], patch, title, description) review_results.append(result) # 4. 汇总提交评论 if review_results: combined_md = "\n\n".join(review_results) comment_url = f"{pr_url}/comments" requests.post( comment_url, headers=HEADERS, json={"body": combined_md}, )

这段代码只是为了展示流程，实际生产环境至少还要加：Webhook 签名校验、异常重试、任务去重、日志记录。

4.3 封装Hermes审查函数

hermes_review_file这个函数是把 diff 文件和提示词模板拼接，然后调用 Hermes 拿到结果。以我用的方式为例，Hermes 支持 Python SDK 调用，也可以起一个 HTTP 服务然后用 requests 调用。我提供两种形态的示意。

def hermes_review_file(filename, patch, pr_title, pr_desc): prompt = build_review_prompt( project_type="Spring Boot 后端服务", tech_stack="Java 17, Spring Boot 3.x, MySQL, Redis", team_rules="所有对外接口必须有参数校验; 禁止硬编码密钥", diff_content=f"文件: {filename}\n```diff\n{patch}\n```", ) # 方式一：如果用Python SDK from hermes_agent import HermesAgent agent = HermesAgent(...) response = agent.chat(prompt) # 方式二：如果用HTTP服务 # response = requests.post("http://127.0.0.1:8080/chat", json={"prompt": prompt}).text return response

这里有一个很重要的点：Hermes 的输出不能完全信任。有时候它会输出一段带错误 Markdown 格式的内容，甚至中途断掉。我会在拿到输出后做一个简单的后处理：检查是否包含“LGTM”或“未发现明显问题”，如果没有反而更好，直接往上拼；如果格式太乱，就加一层规则修正。更稳妥的做法是让 Hermes 输出 JSON，然后用json.loads解析，失败就重试一次。重试仍然失败的话就把这条任务标记为 skipped，并在汇总评论里告知“有 N 个文件审查超时/失败”，不阻塞 PR 流程。

4.4 配置GitHub Webhook并联通测试

Webhook 的配置路径是：GitHub 仓库 → Settings → Webhooks → Add webhook。Payload URL 填你的服务地址 +/webhook路径；Content type 选application/json；Events 选择 “Let me select individual events”，只勾选 Pull requests。

配置完之后，我习惯做一个联通测试：随便改一点代码，提一个临时 PR，看 Webhook 是否被触发。如果服务没收到请求，优先检查三件事：Payload URL 拼写、服务端口是否开放、GitHub Secrets 里填的 token 是否有权限。GitHub 的 Webhook 管理页面会记录最近几次投递结果，投递失败能看到响应错误码，这个排查看板非常有用，比对着日志猜高效得多。

4.5 部署运行：用Docker把服务固定下来

最后部署阶段，我写了一个非常简单的 Dockerfile 和 docker-compose 配置，方便团队其他人复用。Dockerfile 核心就三行基础指令，不展开；docker-compose 里需要注意的是把 GitHub token 用环境变量传进去，不要写死在镜像或代码里。另外给服务加个健康检查接口（比如/healthz返回 ok），方便监控。

还有一个容易被忽略的点：Webhook 对响应时间有要求，GitHub 会在投递后等你的服务响应，如果超过 10 秒没有返回，GitHub 会标记投递失败。所以 Webhook 接收接口里一定不要同步做完整审查，先把事件接收下来、立即返回 200，再把审查任务扔到后台线程或者消息队列里去处理。我第一版就是直接在 Webhook 里同步调 Hermes，结果 GitHub 那边显示投递超时，服务端还在跑，两边都很难受。改成异步处理之后，这个坑彻底消失了。

5. 实战效果复盘：真实PR审查案例解析

5.1 一个典型PR的完整审查过程

我用自己的一个实验仓库跑了一段时间，积累了一些真实的审查案例。拿其中一个比较典型的 PR 来说，改动是一个订单模块的重构，大概 200 行 diff，涉及 6 个文件。Hermes 对这个 PR 的处理结果分成了三部分：安全与正确性问题 2 个、代码风格问题 3 个、整体评价 1 段。

其中有一个问题我觉得特别有价值。改动里的一个函数从数据库查了一批订单数据，然后循环对每个订单做状态判断，如果状态异常就抛异常。Hermes 指出：如果这条 SQL 查询结果是按时间排序的，而业务上希望最先进入处理的订单优先被检查，那么查询条件缺少一个显式的ORDER BY，依赖数据库默认排序会导致行为不确定。这个问题人工 review 很容易忽略，因为看起来“程序逻辑是对的”，但 Hermes 结合 diff 上下文嗅到了排序依赖的味道。这类问题就是 AI 审查真正值钱的地方。

还有一个安全类问题：代码里把用户传入的条件直接拼进了 SQL 的LIKE语句，Hermes 立刻标记为 SQL 注入风险，并给出了改用参数化查询的具体建议。这种问题其实很基础，但人确实会漏，尤其是赶进度的需求里。

5.2 审查质量评估：误报率和有效率的平衡

当然，Hermes 也不是每次都准。我统计了自己仓库里大约 40 次审查记录，人工复核后发现：明确有价值、能帮助发现真实问题的评论占大概 60%，属于常识性建议但不够关键、可忽略的占 25%，明显误报的占 15% 左右。这个数据在可接受范围内，但必须设置一道“严重级别校准”机制。

校准的办法是：在提示词里强调“只有确定是问题才算 BLOCKER / WARNING，不确定的一律算 SUGGESTION”。这条约束能显著把误报率往下拉，因为模型倾向于宁多勿漏，你需要在提示词里强制它“克制”。我改了一版提示词之后，BLOCKER 级别的误报率从大概 30% 降到了 10% 以内，效果非常明显。

5.3 与人工审查的配合节奏

自动化审查上线之后，团队里最需要磨合的是“人怎么看待 bot 的评论”。我定了两条规矩：第一，bot 评论里的 BLOCKER 级别问题，作者必须在合并前给出回应，要么修复、要么在评论里说明理由；第二，WARNING 和 SUGGESTION 级别的评论，人工 reviewer 可以自行决定是否采纳，bot 也只是一票，不代表最终结论。实际运行下来，团队接受度比预期高，因为大家发现 bot 确实能挡住一些低级错误，而且 bot 不会催人、不会情绪化，这对提升体验帮助很大。

6. 常见问题与排查技巧实录

6.1 问题速查表

6.2 关于响应超时和异常重试

稳定运行的核心是“宁可跳过，也不要卡死”。我给不同环节都设了超时：GitHub API 请求设 15 秒超时，Hermes 单次审查设 90 秒超时，超过直接标记失败。失败之后重试一次，还是失败的就把这次审查任务单独放进一个 failure 列表，日志里打印出来。

这里分享一个我踩过的真实坑：最开始我做的是“审查失败就重新投递 Webhook”，结果和 GitHub 的重试机制叠加，一个失败的请求会触发好几次重复处理，直接把服务打挂了。后来我把触发链路和服务处理逻辑彻底分开——Webhook 只负责写入一个任务队列，真正干活的是消费者。这样就算 GitHub 重发事件，队列里重复的任务也能通过 commit_sha 去重，不会造成重复审查。

6.3 成本控制与资源占用心得

如果你用的是本地跑模型的方式，务必给 Hermes 进程设内存上限。我第一次是在一台 8G 内存的云主机上部署，模型加载后直接把内存吃满，服务 OOM 了好几次。后来给 Docker 容器设了mem_limit: 4g，又调整了模型参数量，才稳定下来。如果用的是云端接口，主要控制 prompt 长度，diff 太大就截断，只保留关键上下文比硬喂全部内容更省钱也更稳定。

另外强烈建议加一个“单 PR 审查文件数上限”的开关，比如超过 15 个文件的 PR 直接跳过，不给bot 也不给 API 造成压力。这个策略看起来有点粗暴，但它能强迫开发者保持小步提交的好习惯，是真有实效的。

6.4 团队落地时的一些建议

最后给准备在团队里引入这套系统的朋友几个基于实际经验的建议。上线初期不要直接让 bot 在正式仓库里评论，先在个人仓库跑一周，人工评估输出质量。上线之后，每两周复盘一次误报率，并且把团队确认过的误报案例整理成负样本，改进提示词或规则。审查规则一定要让一线开发参与制定，他们最清楚团队的死穴在哪里，也让后面执行时阻力小很多。

我个人实际使用下来的体会是，Hermes 做 PR 审查最大的价值不在于替代人，而是把人的注意力从“读完每一行”中解放出来，让人更专注在“架构、边界、演进”这些真正需要经验的判断上。这套系统我从搭好到现在迭代了三个版本，每次踩坑都让流程再顺一点。如果你也打算搞一个类似的自动化评审工具，照着上面的链路一步步搭，跑通第一版并不难，真正花时间的反而是后面的规则校准和排错机制打磨，但这一步做好了，后面的收益会越来越明显。