Skip to main content

教程：构建一个 GitHub PR 审查代理

问题： 你的团队创建 PR 的速度远超你能审查的速度。PR 被搁置数天等待人工审阅。初级开发者因无人检查而合并了错误代码。你每天早上都在花时间阅读变更内容，而不是专注于开发。

解决方案： 一个 AI 代理全天候监控你的仓库，自动审查每个新提交的 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 和防火墙后正常运行。

想要实时审查？

如果你有公网可访问的端点，可参考 通过 Webhooks 实现自动化 GitHub PR 评论 —— 当 PR 被打开或更新时，GitHub 会立即推送事件给 Hermes。

先决条件​

  • 已安装 Hermes 代理 —— 参见 安装指南
  • 运行中的网关，用于支持定时任务： 
    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/。非常适合测试阶段，再接入通知功能。

第一步：验证环境设置​

确保 Hermes 能够访问 GitHub。启动一次聊天：

hermes

用一个简单命令进行测试：

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

你应该能看到一份开放 PR 的列表。如果成功，说明一切就绪。

第二步：手动尝试一次审查​

仍在聊天中，让 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. 生成结构化的审查报告，包含具体发现

如果你对审查质量满意，现在就可以开始自动化了。

第三步：创建审查技能​

技能（Skill）为 Hermes 提供一致的审查标准，这些标准在不同会话和定时任务中持久存在。如果没有技能，审查质量将不稳定。

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，你应该能在启动时看到 code-review 出现在技能列表中。

第四步：传授你的团队规范​

这才是让审查代理真正有用的环节。开启一个会话，向 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.

这些记忆将永久保留 —— 代理会持续遵循你的规范，无需每次重复提醒。

第五步：创建自动化定时任务​

现在把所有组件整合起来。创建一个每 2 小时运行一次的定时任务：

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 分钟一次（高活跃度仓库）

第六步：手动触发任务​

不想等定时任务？可以手动运行：

hermes cron run pr-review

或在聊天会话内执行：

/cron run pr-review

进阶功能​

直接将审查结果发布到 GitHub​

不再只发送到 Telegram，而是让代理直接在 PR 上发表评论：

在定时任务提示中添加以下内容：

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"
caution

请确保 gh 拥有 repo 权限范围的令牌。评论将以 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

多仓库监控​

通过在提示中添加更多仓库来扩展监控范围。代理会按顺序处理所有仓库 —— 无需额外配置。

故障排查​

“gh: command not found”​

网关运行在精简环境中。请确认 gh 已加入系统 PATH，并重启网关。

审查结果过于泛泛​

  1. 添加 code-review 技能（第三步）
  2. 通过记忆传授 Hermes 你的团队规范（第四步）
  3. 给代理提供更多关于技术栈的上下文，审查质量将显著提升

定时任务未运行​

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

速率限制​

GitHub 对已认证用户开放 5,000 次 API 请求/小时。每次 PR 审查约消耗 3–5 次请求（获取列表 + diff + 可选评论）。即使每天审查 100 个 PR，也远低于限制。

下一步​