H繁中版
文件教學與最佳實踐github pr review agent
<!-- Source: https://hermesbible.com/docs/guides/github-pr-review-agent -->

教學：打造 GitHub PR 審查代理

**問題：**你的團隊提交 PR 的速度比你審查的速度還快。PR 放了幾天等待被檢視。初級工程師合併了 Bug 因為沒有人有時間檢查。你每天早上都在補看 diff 而不是在開發。

**解決方案：**一個全天候監控你的儲存庫的 AI 代理，審查每個新 PR 的 Bug、安全問題和程式碼品質，然後發送摘要給你——讓你只花時間在真正需要人工判斷的 PR 上。

你將打造的東西：

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   Cron 定時器  ──▶  Hermes 代理  ──▶  GitHub API  ──▶  審查結果   │
│   （每 2 小時）      + gh CLI          （PR diff）     遞送       │
│                    + 技能                                （Telegram、│
│                    + 記憶                                Discord、  │
│                                                        本地）     │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

本指南使用 cron 排程作業定期輪詢 PR——不需要伺服器或公開端點。可在 NAT 和防火牆後運作。

TIP — 想要即時審查？

如果你有公開端點可用，請參閱 使用 Webhooks 自動化 GitHub PR 評論——GitHub 在 PR 開啟或更新時會即時推送事件到 Hermes。

前置需求

  • 已安裝 Hermes Agent — 請見 安裝指南
  • Gateway 正在執行以使用 cron 排程作業： 
    hermes gateway install   # 安裝為服務
# 或
hermes gateway           # 在前景執行
  • 已安裝並認證 GitHub CLI（gh）： 
    # 安裝
brew install gh        # macOS
sudo apt install gh    # Ubuntu/Debian

# 認證
gh auth login
  • 已設定訊息傳遞（選擇性）— Telegram 或 Discord

TIP — 沒有訊息傳遞？沒問題

使用 deliver: "local" 將審查結果儲存到 ~/.hermes/cron/output/。非常適合在設定通知之前進行測試。

步驟 1：驗證設定

確保 Hermes 可以存取 GitHub。啟動一個對話：

hermes

用一個簡單的指令測試：

執行：gh pr list --repo NousResearch/hermes-agent --state open --limit 3

你應該會看到一份開放的 PR 列表。如果這成功了，你就準備好了。

步驟 2：試試手動審查

仍然在對話中，要求 Hermes 審查一個真實的 PR：

審查這個 Pull Request。讀取 diff，檢查 Bug、安全問題
和程式碼品質。具體指出程式碼行號並引用有問題的程式碼。

執行：gh pr diff 3888 --repo NousResearch/hermes-agent

Hermes 會：

  1. 執行 gh pr diff 取得程式碼變更
  2. 閱讀整個 diff
  3. 產生一份帶有具體發現的結構化審查

如果你對品質感到滿意，就可以開始自動化了。

步驟 3：建立審查技能

技能可以讓 Hermes 擁有一致的審查指引，並在不同的對話和 cron 排程作業中持續存在。沒有技能的話，審查品質會不穩定。

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。

步驟 4：教它你的慣例

這是讓審查者真正有用的關鍵。啟動一個對話並教 Hermes 你團隊的標準：

記住：在我們的後端儲存庫中，我們使用 Python 搭配 FastAPI。
所有端點必須有型別註解和 Pydantic 模型。
我們不允許原生 SQL——只使用 SQLAlchemy ORM。
測試檔案放在 tests/ 並必須使用 pytest fixtures。

記住：在我們的前端儲存庫中，我們使用 TypeScript 搭配 React。
不允許 `any` 型別。所有元件必須有 props 介面。
我們使用 React Query 進行資料取得，從不使用 useEffect 呼叫 API。

這些記憶會永久儲存——審查者會自動執行你的慣例，不需要每次都提醒。

步驟 5：建立自動化 Cron 排程作業

現在把所有東西串接起來。建立一個每 2 小時執行的 cron 排程作業：

hermes cron create "0 */2 * * *" \
  "檢查新的開放 PR 並審查它們。

要監控的儲存庫：
- myorg/backend-api
- myorg/frontend-app

步驟：
1. 執行：gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. 對於過去 4 小時內建立或更新的每個 PR：
   - 執行：gh pr diff NUMBER --repo REPO
   - 使用 code-review 技能審查 diff
3. 格式化輸出為：

## PR 審查 — 今日

### [repo] #[number]: [title]
**作者：** [name] | **結論：** APPROVE/REQUEST_CHANGES/COMMENT
[findings]

如果沒有新的 PR，回覆：沒有新的 PR 需要審查。" \
  --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，而是讓代理在 PR 上直接發佈評論：

將此加入你的 cron 提示：

審查後，發佈你的審查：
- 對於問題：gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
- 對於嚴重問題：gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
- 對於乾淨的 PR：gh pr review NUMBER --repo REPO --approve --body "Looks good"

CAUTION

確保 gh 擁有帶有 repo 範圍的 token。審查會以 gh 認證的使用者身份發佈。

每週 PR 儀表板

建立一個每週一早上的所有儲存庫概覽：

hermes cron create "0 9 * * 1" \
  "產生每週 PR 儀表板：
- myorg/backend-api
- myorg/frontend-app
- myorg/infra

針對每個儲存庫顯示：
1. 開放 PR 數量和最舊 PR 的時間
2. 本週已合併的 PR
3. 過期 PR（超過 5 天）
4. 沒有指派審查者的 PR

格式化為簡潔的摘要。" \
  --name "weekly-dashboard" \
  --deliver telegram

多儲存庫監控

透過在提示中加入更多儲存庫來擴展。代理會依序處理它們——不需要額外設定。

疑難排解

"gh: command not found"

Gateway 在精簡環境中執行。確保 gh 在系統 PATH 中並重新啟動 Gateway。

審查太過泛用

  1. 加入 code-review 技能（步驟 3）
  2. 透過記憶教 Hermes 你的慣例（步驟 4）
  3. 它對你的技術棧了解越多，審查品質就越好

Cron 排程作業沒有執行

hermes gateway status    # Gateway 有在執行嗎？
hermes cron list         # 排程作業有啟用嗎？

速率限制

GitHub 允許已認證使用者每小時 5,000 次 API 請求。每次 PR 審查使用約 3-5 次請求（list + diff + 選擇性評論）。即使每天審查 100 個 PR 也遠在限制之內。

下一步

自動化藍圖

delegation patternsgoogle gemini