教程：构建 GitHub PR 审查 Agent

问题： 你的团队创建 PR 的速度快于你审查的速度。PR 往往需要等待数天才能有人查看。初级开发人员因为没人有时间检查而合并了包含 bug 的代码。你不得不把早晨的时间花在追赶差异（diffs）上，而不是进行开发工作。

解决方案： 一个全天候监控你的仓库的 AI agent，审查每个新 PR 中的 bug、安全问题和代码质量，并发送摘要给你——这样你只需将时间花在真正需要人工判断的 PR 上。

你将构建的内容：

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   Cron Timer  ──▶  Hermes Agent  ──▶  GitHub API  ──▶  Review     │
│   (every 2h)       + gh CLI           (PR diffs)       delivery   │
│                    + skill                             (Telegram, │
│                    + memory                            Discord,   │
│                                                        local)     │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

本指南使用 cron jobs 按计划轮询 PR——无需服务器或公共端点。可在 NAT 和防火墙后方运行。

想要实时审查？

如果你有可用的公共端点，请查看 使用 Webhook 自动评论 GitHub PR——当 PR 被打开或更新时，GitHub 会立即将事件推送到 Hermes。

---

前提条件

• 已安装 Hermes Agent——参见 安装指南
• 为 cron jobs 运行 Gateway：

  hermes gateway install   # Install as a service
  # or
  hermes gateway           # Run in foreground

• 已安装并认证 GitHub CLI (gh)：

  # Install
  brew install gh        # macOS
  sudo apt install gh    # Ubuntu/Debian
  
  # Authenticate
  gh auth login

• 已配置消息传递（可选）— Telegram 或 Discord

没有消息传递？没问题

使用 deliver: "local" 将审查结果保存到 ~/.hermes/cron/output/。这在配置通知之前进行测试非常有用。

---

步骤 1：验证设置

确保 Hermes 可以访问 GitHub。启动聊天：

hermes

使用简单命令进行测试：

Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3

你应该能看到一个开放 PR 的列表。如果成功，说明已准备就绪。

---

步骤 2：尝试手动审查

仍在聊天中，要求 Hermes 审查一个真实的 PR：

Review this pull request. Read the diff, check for bugs, security issues,
and code quality. Be specific about line numbers and quote problematic code.

Run: gh pr diff 3888 --repo NousResearch/hermes-agent

Hermes 将：

1. 执行 gh pr diff 以获取代码变更
2. 阅读整个 diff
3. 生成包含具体发现的结构化审查报告

如果你对质量满意，就可以将其自动化了。

---

步骤 3：创建审查 Skill

Skill 为 Hermes 提供一致的审查指南，这些指南在会话和 cron 运行之间持久存在。如果没有 Skill，审查质量会有波动。

mkdir -p ~/.hermes/skills/code-review

创建 ~/.hermes/skills/code-review/SKILL.md：

---
name: code-review
description: Review pull requests for bugs, security issues, and code quality
---

# Code Review Guidelines

When reviewing a pull request:

## What to Check
1. **Bugs** — Logic errors, off-by-one, null/undefined handling
2. **Security** — Injection, auth bypass, secrets in code, SSRF
3. **Performance** — N+1 queries, unbounded loops, memory leaks
4. **Style** — Naming conventions, dead code, missing error handling
5. **Tests** — Are changes tested? Do tests cover edge cases?

## Output Format
For each finding:
- **File:Line** — exact location
- **Severity** — Critical / Warning / Suggestion
- **What's wrong** — one sentence
- **Fix** — how to fix it

## Rules
- Be specific. Quote the problematic code.
- Don't flag style nitpicks unless they affect readability.
- If the PR looks good, say so. Don't invent problems.
- End with: APPROVE / REQUEST_CHANGES / COMMENT

验证其已加载——启动 hermes，你应该能在启动时的 skills 列表中看到 code-review。

---

步骤 4：教它你的规范

这是让审查者真正有用的关键。启动一个会话并教导 Hermes 你团队的标准：

Remember: In our backend repo, we use Python with FastAPI.
All endpoints must have type annotations and Pydantic models.
We don't allow raw SQL — only SQLAlchemy ORM.
Test files go in tests/ and must use pytest fixtures.

Remember: In our frontend repo, we use TypeScript with React.
No `any` types allowed. All components must have props interfaces.
We use React Query for data fetching, never useEffect for API calls.

这些记忆将永久保存——审查者将在无需每次告知的情况下执行你的规范。

---

步骤 5：创建自动化 Cron Job

现在将所有内容连接起来。创建一个每 2 小时运行一次的 cron job：

hermes cron create "0 */2 * * *" \
  "Check for new open PRs and review them.

Repos to monitor:
- myorg/backend-api
- myorg/frontend-app

Steps:
1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. For each PR created or updated in the last 4 hours:
   - Run: gh pr diff NUMBER --repo REPO
   - Review the diff using the code-review guidelines
3. Format output as:

## PR Reviews — today

### [repo] #[number]: [title]
**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
[findings]

If no new PRs found, say: No new PRs to review." \
  --name "pr-review" \
  --deliver telegram \
  --skill code-review

验证其已调度：

hermes cron list

其他有用的调度计划

调度计划	何时运行
0 */2 * * *	每 2 小时
0 9,13,17 * * 1-5	每天三次，仅限工作日
0 9 * * 1	每周一早晨汇总
30m	每 30 分钟（高流量仓库）

---

步骤 6：按需运行

不想等待调度？手动触发它：

hermes cron run pr-review

或者在聊天会话中：

/cron run pr-review

---

进阶使用

直接将审查发布到 GitHub

与其发送到 Telegram，不如让 agent 直接在 PR 上评论：

将此添加到你的 cron prompt 中：

After reviewing, post your review:
- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"

警告

确保 gh拥有具有 repo 范围的 token。审查将以 gh 认证的身份发布。

每周 PR 仪表板

创建所有仓库的周一早晨概览：

hermes cron create "0 9 * * 1" \
  "Generate a weekly PR dashboard:
- myorg/backend-api
- myorg/frontend-app
- myorg/infra

For each repo show:
1. Open PR count and oldest PR age
2. PRs merged this week
3. Stale PRs (older than 5 days)
4. PRs with no reviewer assigned

Format as a clean summary." \
  --name "weekly-dashboard" \
  --deliver telegram

多仓库监控

通过在 prompt 中添加更多仓库来扩展规模。Agent 会按顺序处理它们——无需额外设置。

---

故障排除

"gh: command not found"

Gateway 在最小化环境中运行。确保 gh 在系统 PATH 中，并重启 gateway。

审查过于通用

1. 添加 code-review skill（步骤 3）
2. 通过记忆教导 Hermes 你的规范（步骤 4）
3. 它对你的技术栈了解越多，审查效果越好

Cron job 未运行

hermes gateway status    # Is the gateway running?
hermes cron list         # Is the job enabled?

速率限制

GitHub 允许认证用户每小时发起 5,000 次 API 请求。每次 PR 审查使用约 3-5 次请求（列表 + diff + 可选评论）。即使每天审查 100 个 PR，也远低于限制。

---

下一步？

• 基于 Webhook 的 PR 审查 — 在 PR 打开时获得即时审查（需要公共端点）
• 每日简报 Bot — 将 PR 审查与你的晨间新闻摘要结合
• 构建插件 — 将审查逻辑封装为可共享的插件
• 配置文件 (Profiles) — 运行具有独立记忆和配置的专用审查者配置文件
• 备用提供商 (Fallback Providers) — 确保即使某个提供商宕机，审查仍能运行