教程：構建 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) — 確保即使某個提供商宕機，審查仍能運行