Cursor – 代码评审

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

对于大多数用户，推荐直接使用 Bugbot。Bugbot 提供托管的自动化代码评审，无需任何配置。CLI 方案适合用来探索能力和进行高级自定义。

显示完整的工作流文件

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) 复查已有评审评论，对已处理的标记为 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）最小化，或编辑为添加前缀"[已被新发现取代]"。
            - 若既不能删除也不能最小化，则回复该评论："⚠️ 已被取代：在较新的提交中发现了问题"
          - 若此前报告的问题看起来已被附近的变更修复，回复：✅ 此问题似乎已被近期变更解决
          - 仅分析以下内容：
            - null/undefined 解引用
            - 资源泄漏（未关闭的文件或连接）
            - 注入（SQL/XSS）
            - 并发/竞态条件
            - 对关键操作缺少错误处理
            - 明显的逻辑错误导致不正确行为
            - 明确的性能反模式且具有可衡量影响
            - 明确的安全漏洞
          - 避免重复：如果相似反馈已在相同或相邻行存在则跳过。

          评论规则：
          - 最多 10 条行内评论；优先最关键问题
          - 一条评论只包含一个问题；放在精确的变更行上
          - 所有问题评论必须是行内的（锚定到 PR diff 中的文件与行/位置）
          - 语气自然、具体且可执行；不要提及“自动化”或“高置信度”
          - 使用表情：🚨 严重 🔒 安全 ⚡ 性能 ⚠️ 逻辑 ✅ 已解决 ✨ 改进

          提交：
          - 如果没有可报告的问题，且已存在指示“无问题”的顶层评论（例如："✅ 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_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

配置身份验证

设置你的 API 密钥和仓库密钥，以在 GitHub Actions 中对 Cursor CLI 进行身份验证。

配置代理权限

创建一个配置文件来限制代理可执行的操作，避免发生像推送代码或创建 Pull Request 这样的意外操作。在仓库根目录创建 .cursor/cli.json：

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

此配置允许 agent 读取文件并使用 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:

检出仓库

添加检出步骤以获取 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

配置审查代理

在实现完整的审查步骤之前，先弄清我们的审查提示词是怎么构成的。本节会说明我们希望代理的行为方式：目标：我们希望代理审查当前 PR 的 diff，只标注明确且高严重度的问题；仅在变更的行上留下非常简短的行内评论（1-2 句），并在末尾附上一段简要总结。这样可以保持良好的信噪比。格式：评论要简短且直击要点。我们会用表情符号便于快速扫描，并在末尾给出一次高层级的完整审查总结。提交：审查完成后，代理需要根据审查结果附上一段简短评论。代理应提交一次包含行内评论和精炼总结的单次审查。 边界情况：需要处理：

既有评论已被解决：当问题已修复时，代理应将其标记为已完成
避免重复：如果同类反馈已存在于相同或相邻行，代理应跳过评论

最终提示词：完整的提示词将上述行为要求组合起来，产出聚焦且可执行的反馈现在让我们实现审查代理步骤：

- 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 认证。你可以在拉取请求上发表评论。
    
    上下文：
    - 仓库：${{ 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 }}
    
    目标：
    1) 复核已有审查评论，若已处理则回复：已解决
    2) 审查当前 PR diff，仅标注明确且高严重度的问题
    3) 只在变更的行留下非常简短的行内评论（1-2 句），并在末尾给出简要总结
    
    流程：
    - 获取已有评论：gh pr view --json comments
    - 获取 diff：gh pr diff
    - 若先前报告的问题似乎已被附近的更改修复，回复：✅ 此问题似乎已被最近的更改解决
    - 避免重复：如果同类反馈已在相同行或附近存在，则跳过
    
    评论规则：
    - 最多 10 条行内评论；优先处理最关键的问题
    - 每条评论只包含一个问题；放在准确的变更行
    - 语气自然，具体且可执行；不要提及自动化或高置信度
    - 使用表情：🚨 严重 🔒 安全 ⚡ 性能 ⚠️ 逻辑 ✅ 已解决 ✨ 改进
    
    提交：
    - 提交一次审查，包含行内评论与简明总结
    - 仅使用：gh pr review --comment
    - 不要使用：gh pr review --approve 或 --request-changes"

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

测试你的审阅器

创建一个测试 Pull Request，确认工作流正常运行，并且代理会发布带有表情反馈的审阅评论。

Pull Request 显示自动审阅评论，包含表情符号以及针对特定代码行的内联反馈

后续步骤

现在你已经有了一个可用的自动化代码审查系统。可以考虑进一步优化：

为修复 CI 失败设置额外的工作流
为不同分支配置不同的审查等级
与团队现有的代码审查流程集成
针对不同的文件类型或目录自定义 agent 的行为

显示高级：阻塞式审查

你可以配置在发现关键问题时让工作流失败，在问题被处理之前阻止合并该 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

配置审查代理

测试你的审阅器

后续步骤