Cursor – 程式碼審查

這份教學會帶你在 GitHub Actions 中用 Cursor CLI 設定程式碼審查。工作流程會分析 pull request、找出問題，並把回饋以留言方式貼上。

對大多數使用者，我們建議改用 Bugbot。Bugbot 提供免設定的託管式自動程式碼審查。這種 CLI 作法適合用來探索功能與進行進階自訂。

顯示完整的 workflow 檔案

cursor-code-review.yml

name: 程式碼審查

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  pull-requests: write
  contents: read
  issues: write

jobs:
  code-review:
    runs-on: ubuntu-latest
    # 對草稿 PR 略過自動程式碼審查
    if: github.event.pull_request.draft == false
    steps:
      - name: 取出儲存庫
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}

      - name: 安裝 Cursor CLI
        run: |
          curl https://cursor.com/install -fsS | bash
          echo "$HOME/.cursor/bin" >> $GITHUB_PATH

      - name: 設定 git 身分
        run: |
          git config user.name "Cursor Agent"
          git config user.email "cursoragent@cursor.com"

      - name: 執行自動化程式碼審查
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
          MODEL: gpt-5
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BLOCKING_REVIEW: ${{ vars.BLOCKING_REVIEW || 'false' }}
        run: |
          cursor-agent --force --model "$MODEL" --output-format=text --print '你正在 GitHub Actions runner 中執行自動化程式碼審查。gh CLI 已可用並透過 GH_TOKEN 驗證。你可以在 pull request 上留言。

          Context:
          - Repo: ${{ github.repository }}
          - PR Number: ${{ github.event.pull_request.number }}
          - PR Head SHA: ${{ github.event.pull_request.head.sha }}
          - PR Base SHA: ${{ github.event.pull_request.base.sha }}
          - Blocking Review: ${{ env.BLOCKING_REVIEW }}

          Objectives:
          1) 重新檢查既有審查留言，若已處理則回覆 resolved。
          2) 審查目前 PR 的 diff，只標記明確且高嚴重性的問題。
          3) 只在變更行留下非常精簡的行內留言（1-2 句），並在最後附上簡短總結。

          Procedure:
          - 取得既有留言：gh pr view --json comments
          - 取得 diff：gh pr diff
          - 取得含 patch 的變更檔以計算行內位置：gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files --paginate --jq '.[] | {filename,patch}'
          - 為每個問題計算精準的行內錨點（檔案路徑 + diff 位置）。留言必須放在 diff 中已變更的那一行，而不是頂層留言。
          - 偵測先前由此機器人發出的頂層「無問題」類型留言（比對內文如："✅ no issues", "No issues found", "LGTM"）。
          - 若本次執行發現問題且存在任何先前的「無問題」留言：
            - 優先移除以避免混淆：
              - 嘗試透過以下方式刪除頂層留言：gh api -X DELETE repos/${{ github.repository }}/issues/comments/<comment_id>
              - 若無法刪除，使用 GraphQL（minimizeComment）將其最小化，或編輯為在前綴加上「[Superseded by new findings]」。
            - 若無法刪除或最小化，回覆該留言：「⚠️ Superseded: issues were found in newer commits」。
          - 若先前回報的問題看起來已被附近的變更修正，回覆：✅ This issue appears to be resolved by the recent changes
          - 僅分析以下項目：
            - Null/undefined 反參照
            - 資源洩漏（未關閉的檔案或連線）
            - 注入（SQL/XSS）
            - 併發/競態條件
            - 關鍵操作缺少錯誤處理
            - 明顯導致不正確行為的邏輯錯誤
            - 具可衡量影響的明確效能反模式
            - 明確的安全性漏洞
          - 避免重複：若相近行已有類似意見則略過。

          Commenting rules:
          - 最多 10 則行內留言；優先處理最關鍵的問題
          - 每則留言僅描述一個問題；放在精準的變更行
          - 所有問題留言必須為行內（錨定到 PR diff 中的檔案與行/位置）
          - 語氣自然、具體且可執行；不要提及自動化或信心等級
          - 使用表情符號：🚨 Critical 🔒 Security ⚡ Performance ⚠️ Logic ✅ Resolved ✨ Improvement

          Submission:
          - 若沒有任何問題可回報，且已存在一則表示「無問題」的頂層留言（例如「✅ no issues」、「No issues found」、「LGTM」），不要再提交另一則留言。略過提交以避免重複。
          - 若沒有任何問題可回報，且先前沒有「無問題」留言，提交一則簡短摘要留言說明無問題。
          - 若有問題可回報，且先前存在「無問題」留言，請在提交新的審查前，先確保先前留言已刪除／最小化／標記為已被取代。
          - 若有問題可回報，提交一則審查，只包含行內留言，另可選擇附上一段精簡總結。使用 GitHub Reviews API 以確保留言為行內：
            - 建立一個留言的 JSON 陣列，例如：[{ "path": "<file>", "position": <diff_position>, "body": "..." }]
            - 透過以下方式提交：gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews -f event=COMMENT -f body="$SUMMARY" -f comments='[$COMMENTS_JSON]'
          - 不要使用：gh pr review --approve 或 --request-changes

          Blocking behavior:
          - 若 BLOCKING_REVIEW 為 true，且張貼了任何 🚨 或 🔒 問題：echo "CRITICAL_ISSUES_FOUND=true" >> $GITHUB_ENV
          - 否則：echo "CRITICAL_ISSUES_FOUND=false" >> $GITHUB_ENV
          - 最後一律設定 CRITICAL_ISSUES_FOUND
          '

      - name: 檢查阻擋式審查結果
        if: env.BLOCKING_REVIEW == 'true'
        run: |
          echo "正在檢查關鍵問題..."
          echo "CRITICAL_ISSUES_FOUND: ${CRITICAL_ISSUES_FOUND:-unset}"

          if [ "${CRITICAL_ISSUES_FOUND:-false}" = "true" ]; then
            echo "❌ 發現關鍵問題且已啟用阻擋式審查。工作流程失敗。"
            exit 1
          else
            echo "✅ 未發現會阻擋的問題。"
          fi

設定驗證

在 GitHub Actions 中設定你的 API 金鑰與儲存庫機密，用來讓 Cursor CLI 通過驗證。

設定代理權限

建立一個設定檔，控制代理能執行哪些動作。這能避免非預期的操作，例如推送程式碼或建立 pull request。在你的儲存庫根目錄建立 .cursor/cli.json：

{
  "permissions": {
    "deny": [
      "Shell(git push)",
      "Shell(gh pr create)",
      "Write(**)"
    ]
  }
}

這個設定允許代理讀取檔案並使用 GitHub CLI 發佈評論，但會阻止它對你的儲存庫做出任何變更。請參考權限說明以取得更多設定選項。

建立 GitHub Actions 工作流程

現在我們一步步來建立這個工作流程。

設定工作流程觸發器

建立 .github/workflows/cursor-code-review.yml，並設定在 pull request 時執行：

name: Cursor 程式碼審閱

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  code-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:

取得存放庫

新增 checkout 步驟以存取 pull request 的程式碼：

- name: 檢出存放庫
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
    ref: ${{ github.event.pull_request.head.sha }}

安裝 Cursor CLI

加入 CLI 安裝步驟：

- name: 安裝 Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.cursor/bin" >> $GITHUB_PATH

設定 review 代理

在實作完整的 review 步驟之前，先來了解我們的 review 提示結構。本節說明我們希望代理的行為：目標：我們希望代理檢視目前的 PR diff，只標記明確且高嚴重性的問題，並且只在變更的行上留下非常短的行內留言（1–2 句），最後在結尾附上一段簡短總結。這能維持良好的訊噪比。格式：我們要精簡且到點的留言。會使用表情符號讓掃讀留言更容易，並在最後提供整體 review 的高階總結。提交：當 review 完成後，我們希望代理根據檢查結果附上一段短評。代理應提交一個包含行內留言與精煉總結的單一 review。 邊界情況：我們需要處理：

既有留言已被解決：問題處理後，代理應將其標記為完成
避免重複：如果相似回饋已存在於相同或相鄰行，代理應略過留言

最終提示：完整提示會結合以上所有行為要求，產出聚焦且可執行的回饋現在來實作 review 代理步驟：

- name: 執行程式碼審查
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
    GH_TOKEN: ${{ github.token }}
  run: |
    cursor-agent --force --model "$MODEL" --output-format=text --print "你正在 GitHub Actions runner 中執行自動化程式碼審查。gh CLI 可用，並已透過 GH_TOKEN 完成驗證。你可以對 pull request 發表評論。
    
    Context:
    - Repo: ${{ github.repository }}
    - PR Number: ${{ github.event.pull_request.number }}
    - PR Head SHA: ${{ github.event.pull_request.head.sha }}
    - PR Base SHA: ${{ github.event.pull_request.base.sha }}
    
    Objectives:
    1) 重新檢視既有的審查評論，若已處理則回覆已解決
    2) 審查當前 PR 的 diff，只標註明確且高嚴重性的問題
    3) 僅在變更的行上留下非常短的行內評論（1-2 句），並在最後附上一段精要摘要
    
    Procedure:
    - 取得現有評論：gh pr view --json comments
    - 取得 diff：gh pr diff
    - 如果先前回報的問題看起來已被鄰近變更修正，回覆：✅ 這個問題看起來已由最近的變更解決
    - 避免重複：若相似的回饋已存在於相同或相近的行，請略過
    
    Commenting rules:
    - 最多 10 則行內評論；優先處理最關鍵的問題
    - 每則評論只針對一個問題；放在確切變更的那一行
    - 語氣自然、具體且可行；不要提及自動化或高信心
    - 使用表情符號：🚨 關鍵 🔒 安全 ⚡ 效能 ⚠️ 邏輯 ✅ 已解決 ✨ 改進
    
    Submission:
    - 提交一份包含行內評論與精簡摘要的審查
    - 僅使用：gh pr review --comment
    - 不要使用：gh pr review --approve 或 --request-changes"

.
├── .cursor/
│   └── cli.json
├── .github/
│   └── workflows/
│       └── cursor-code-review.yml

測試你的審查員

建立一個測試 pull request，確認工作流程正常運作，並讓代理在審查評論中貼上表情符號回饋，並對特定行提供行內意見。

Pull request showing automated review comments with emojis and inline feedback on specific lines

下一步

你現在已經有一個可運作的自動化程式碼審查系統。可以考慮這些強化：

設定額外的工作流程來修復 CI 失敗
針對不同分支設定不同的審查等級
與你團隊現有的程式碼審查流程整合
依不同檔案類型或目錄自訂代理的行為

顯示進階：阻擋式審查

你可以將工作流程設定為在發現關鍵問題時判定失敗，防止 Pull Request 在處理前被合併。將阻擋行為加入提示詞先把審查代理的步驟更新為包含 BLOCKING_REVIEW 環境變數，並把以下阻擋行為加入提示詞：

Blocking behavior:
- If BLOCKING_REVIEW is true and any 🚨 or 🔒 issues were posted: echo "CRITICAL_ISSUES_FOUND=true" >> $GITHUB_ENV
- Otherwise: echo "CRITICAL_ISSUES_FOUND=false" >> $GITHUB_ENV
- Always set CRITICAL_ISSUES_FOUND at the end

加入阻擋檢查步驟接著在程式碼審查步驟之後加入這個新步驟：

      - name: Check blocking review results
        if: env.BLOCKING_REVIEW == 'true'
        run: |
          echo "Checking for critical issues..."
          echo "CRITICAL_ISSUES_FOUND: ${CRITICAL_ISSUES_FOUND:-unset}"

          if [ "${CRITICAL_ISSUES_FOUND:-false}" = "true" ]; then
            echo "❌ Critical issues found and blocking review is enabled. Failing the workflow."
            exit 1
          else
            echo "✅ No blocking issues found."
          fi

開始使用

無頭

參考資料

程式碼審查

設定驗證

設定代理權限

建立 GitHub Actions 工作流程

設定工作流程觸發器

取得存放庫

安裝 Cursor CLI

設定 review 代理

測試你的審查員

下一步

開始使用

無頭

參考資料

​設定驗證

​設定代理權限

​建立 GitHub Actions 工作流程

​設定工作流程觸發器

​取得存放庫

​安裝 Cursor CLI

​設定 review 代理

​測試你的審查員

​下一步

設定驗證

設定代理權限

建立 GitHub Actions 工作流程

設定工作流程觸發器

取得存放庫

安裝 Cursor CLI

設定 review 代理

測試你的審查員

下一步