Cursor – 程式碼審查

本教學示範如何在 GitHub Actions 中使用 Cursor CLI 設定程式碼審查。此工作流程會分析 Pull Request、找出問題，並以留言的方式發布回饋。

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

Show full workflow file

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 執行器中進行自動程式碼審查。gh CLI 可用，且已透過 GH_TOKEN 驗證。你可以在 pull request 上留言。

          上下文：
          - 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 }}
          - 阻擋式審查：${{ env.BLOCKING_REVIEW }}

          目標：
          1) 重新檢查現有的審查留言，若已處理就回覆 resolved。
          2) 審查目前的 PR diff，只標註明確且高嚴重性的問題。
          3) 僅在變更的行上留下非常精簡的行內留言（1–2 句），最後附上簡短摘要。

          流程：
          - 取得現有留言：gh pr view --json comments
          - 取得 diff：gh pr diff
          - 取得含補丁的變更檔（用來計算行內位置）：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]"。
            - 若無法刪除或最小化，則回覆該留言：「⚠️ 已被取代：在較新的提交中發現問題」
          - 若先前回報的問題似乎被附近的變更修復，回覆：✅ 此問題看起來已被近期變更解決
          - 僅分析以下項目：
            - Null/undefined 解參照
            - 資源洩漏（未關閉的檔案或連線）
            - 注入（SQL/XSS）
            - 併發/競態條件
            - 關鍵操作缺少錯誤處理
            - 明顯導致行為不正確的邏輯錯誤
            - 具可測量影響的明確效能反模式
            - 明確的安全性弱點
          - 避免重複：若同一行或鄰近行已有類似回饋則略過。

          留言規則：
          - 最多 10 則行內留言；優先處理最關鍵的問題
          - 一則留言只描述一個問題；放在精確的變更行上
          - 所有問題留言必須是行內留言（錨定到 PR diff 的檔案與行/位置）
          - 口吻自然、具體且可行；不要提及自動化或信心評估
          - 使用表情符號：🚨 關鍵 🔒 安全 ⚡ 效能 ⚠️ 邏輯 ✅ 已解決 ✨ 改進

          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:-未設定}"

          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 發表留言，但會阻止它對你的儲存庫進行任何變更。更多設定選項請參考 permissions reference。

建立 GitHub Actions 工作流程

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

設定工作流程觸發條件

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

name: Cursor Code Review

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

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

取出儲存庫

加入取出步驟以存取 pull request 的程式碼：

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
    ref: ${{ github.event.pull_request.head.sha }}

安裝 Cursor CLI

加入 CLI 安裝步驟：

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

設定審查代理

在實作完整的審查步驟之前，先理解我們的審查提示結構。以下說明代理應有的行為：目標：我們要代理審查目前的 PR diff，只標註明確且高嚴重性的問題，僅在變更的行留下非常精簡的行內評論（1–2 句），最後附上簡短摘要，以維持良好的訊噪比。格式：評論要短而精準。為了便於掃讀會使用表情符號，並在最後附上一則高層級的整體審查摘要。提交：審查完成後，代理要根據審查結果附上一則簡短評論。代理應提交一次審查，包含行內評論與精煉摘要。 邊界情況：我們需要處理：

既有評論已被解決：當問題已被處理時，代理應標示為已解決
避免重複：若相似回饋已存在於相同或相鄰行，代理應略過不再留言

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

- name: Perform code review
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
    GH_TOKEN: ${{ github.token }}
  run: |
    cursor-agent --force --model "$MODEL" --output-format=text --print "You are operating in a GitHub Actions runner performing automated code review. The gh CLI is available and authenticated via GH_TOKEN. You may comment on pull requests.
    
    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) Re-check existing review comments and reply resolved when addressed
    2) Review the current PR diff and flag only clear, high-severity issues
    3) Leave very short inline comments (1-2 sentences) on changed lines only and a brief summary at the end
    
    Procedure:
    - Get existing comments: gh pr view --json comments
    - Get diff: gh pr diff
    - If a previously reported issue appears fixed by nearby changes, reply: ✅ This issue appears to be resolved by the recent changes
    - Avoid duplicates: skip if similar feedback already exists on or near the same lines
    
    Commenting rules:
    - Max 10 inline comments total; prioritize the most critical issues
    - One issue per comment; place on the exact changed line
    - Natural tone, specific and actionable; do not mention automated or high-confidence
    - Use emojis: 🚨 Critical 🔒 Security ⚡ Performance ⚠️ Logic ✅ Resolved ✨ Improvement
    
    Submission:
    - Submit one review containing inline comments plus a concise summary
    - Use only: gh pr review --comment
    - Do not use: gh pr review --approve or --request-changes"

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

測試你的審查員

建立一個測試 pull request，確認工作流程正常運作，且代理會張貼帶有表情符號回饋的審查留言。

Pull request 顯示在特定程式行的自動化審查留言，包含表情符號與行內回饋

下一步

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

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

Show 進階：阻擋式審查

你可以把工作流程設定為在發現關鍵問題時標記失敗，避免 Pull Request 在處理完之前被合併。在提示中加入阻擋行為先把你的審查代理步驟更新為包含 BLOCKING_REVIEW 環境變數，並在提示中加入這個阻擋行為：

阻擋行為：
- 如果 BLOCKING_REVIEW 為 true，且張貼了任何 🚨 或 🔒 問題：echo "CRITICAL_ISSUES_FOUND=true" >> $GITHUB_ENV
- 否則：echo "CRITICAL_ISSUES_FOUND=false" >> $GITHUB_ENV
- 一定要在最後設定 CRITICAL_ISSUES_FOUND

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

      - 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

設定審查代理

測試你的審查員

下一步

開始使用

無頭

參考資料

​設定驗證

​設定代理權限

​建立 GitHub Actions 工作流程

​設定工作流程觸發條件

​取出儲存庫

​安裝 Cursor CLI

​設定審查代理

​測試你的審查員

​下一步

設定驗證

設定代理權限

建立 GitHub Actions 工作流程

設定工作流程觸發條件

取出儲存庫

安裝 Cursor CLI

設定審查代理

測試你的審查員

下一步