Cursor – 代码评审

本教程演示如何在 GitHub Actions 中使用 Cursor CLI 设置代码评审。该工作流程会分析 pull requests、定位问题，并以评论的形式发布反馈。

对于大多数用户，我们推荐使用 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 完成认证。你可以在拉取请求上发表评论。

          上下文：
          - 仓库：${{ github.repository }}
          - PR 编号：${{ 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) 复查已有的审查评论，若已处理则回复“已解决”。
          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）最小化，或编辑为加前缀“[被新发现取代]”。
            - 若无法删除或最小化，则回复该评论：“⚠️ 已被取代：在较新的提交中发现了问题”
          - 如果先前报告的问题看起来已被附近的更改修复，回复：✅ 近期更改似乎已解决此问题
          - 仅分析以下内容：
            - 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: Check blocking review results
        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 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 失败设置额外的工作流
为不同分支配置不同的审查等级
和团队现有的代码评审流程集成
针对不同文件类型或目录自定义 agent 的行为

Show 进阶：阻断式审查

你可以把工作流配置为在发现关键问题时直接失败，在问题解决前阻止合并该 pull request。为提示添加阻断行为先更新审查 agent 的步骤，加入 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

配置审查代理

测试你的评审器

下一步

快速上手

无头

参考

​配置身份验证

​设置代理权限

​构建 GitHub Actions 工作流

​设置工作流触发器

​检出仓库

​安装 Cursor CLI

​配置审查代理

​测试你的评审器

​下一步

配置身份验证

设置代理权限

构建 GitHub Actions 工作流

设置工作流触发器

检出仓库

安装 Cursor CLI

配置审查代理

测试你的评审器

下一步