check-pr

检查 PR

分析拉取请求（GitHub）、合并请求（GitLab）或搁置的变更列表（Perforce），检查审查评论、状态检查和描述完整性，然后协助处理发现的问题。

输入

• PR/MR/CL 编号（可选）：如果未提供，则检测当前分支对应的 PR/MR，或 p4 的默认待处理变更列表。

说明

0. 检测平台

首先检查用户是否在 Perforce depot 中工作：查找 .p4config 文件或 P4CLIENT/P4PORT 环境变量：

# Check for Perforce environment
if p4 info >/dev/null 2>&1; then
  VCS="perforce"
else
  # Fall back to git remote detection
  REMOTE_URL=$(git remote get-url origin)
  if echo "$REMOTE_URL" | grep -qi "gitlab"; then
    VCS="gitlab"
  else
    VCS="github"
  fi
fi

对于主机名不含 “gitlab” 的自托管 GitLab 实例，用户可以通过传入 --vcs gitlab 来覆盖检测结果。对于 Perforce，用户可以通过传入 --vcs perforce 来覆盖检测结果。

1. 确定 PR/MR/CL

如果已提供编号，则使用该编号。否则，进行检测：

GitHub：

gh pr view --json number -q .number

GitLab：

glab mr view --output json | jq '.iid'

Perforce：

# List pending changelists for the current user/client
p4 changes -s pending -u $P4USER -c $P4CLIENT

各平台关键字段的差异：

• GitHub：number、headRefName、headRefOid
• GitLab：iid、source_branch、sha
• Perforce：变更列表编号（CL），正在审查的 CL 所包含的 shelved 文件

2. 获取 PR/MR/CL 详情

GitHub：

gh pr view <PR_NUMBER> --json title,body,state,reviews,comments,headRefName,statusCheckRollup
gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments
gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments?per_page=100"

GitHub PR 也属于 issue，因此，常规 PR 评论位于 issue 评论端点。Greptile 可能会在每轮审查中编辑一条常规 PR 评论，而不是新建审查或评论。得出 PR 没有问题的结论前，务必根据 updated_at 检查 Greptile 发布的最新常规评论，包括其中的 “Prompt to fix all with AI” 部分。

GitLab：

glab mr view <MR_IID> --output json
# Fetch discussions (inline diff comments are type "DiffNote"; general comments have null type)
glab api "projects/:fullpath/merge_requests/<MR_IID>/discussions"

对于 GitLab，如有需要，请对讨论进行分页（添加 ?per_page=100&page=N）。

Perforce：

# Get changelist description, files, and status
p4 describe -s <CL_NUMBER>

# Get shelved files (for in-review CLs)
p4 describe -S <CL_NUMBER>

# Get the diff of the shelved changelist
p4 diff2 //...@=<CL_NUMBER> //...@=<CL_NUMBER>

# List review comments (if using p4 review workflow)
p4 review -c <CL_NUMBER>

Perforce CL 的关键字段：

• Change：变更列表编号
• Status：pending、submitted、shelved
• Description：CL 描述／提交消息
• Files：CL 中的文件列表

3. 等待待完成的检查

开始分析前，确保所有状态检查都已完成。如果有任何检查处于 PENDING 或 IN_PROGRESS（GitHub）／running 或 pending（GitLab）状态，则每隔 30 秒轮询一次，直到所有检查均进入终止状态。

**GitHub：**通过 gh pr view 轮询 statusCheckRollup。

GitLab：

glab api "projects/:fullpath/merge_requests/<MR_IID>/pipelines"

流水线状态：running、pending、success、failed、canceled、skipped。持续轮询，直到没有流水线处于 running 或 pending 状态。

**Perforce：**Perforce 原生不内置 CI 检查。如果团队使用审查工具（如 Swarm）或由搁置事件触发的外部 CI，请检查相应系统。否则，立即开始分析。

4. 分析 PR/MR

所有检查完成后，评估以下方面：

A. 状态检查

• 所有 CI 检查都通过了吗？
• 如果有检查失败，请指出失败的检查及失败原因。

B. PR/MR 描述

• 描述是否完整，且符合团队规范？
• 所有必填部分都已填写吗？
• 是否有需要更新的 TODO 或占位内容？

C. 审查评论

• 需要处理的行内代码审查评论
• 查找机器人审查评论（例如 GitHub 上来自 greptile-apps[bot] 的评论、GitLab 上 Greptile 机器人用户的评论、代码检查工具的评论等）
• 人类审查者的评论
• **Perforce：**来自 p4 review 或外部审查工具的审查评论

D. 常规评论

• PR/MR 上的讨论评论
• 对于 GitHub，请检查 issue 评论端点，并利用 updated_at 查找被编辑的机器人评论。即使没有新的行内评论，Greptile 最近编辑的摘要中也可能包含需要处理的事项。
• 机器人评论（部署预览等）——通常仅供参考
• **Perforce：**CL 描述应包含清晰的摘要、受影响文件的修改理由以及测试说明

5. 问题分类

对于发现的每个问题，请按以下类别进行分类：

类别	含义
需处理	需要进行代码更改、改进测试或修复
供参考	无需更改的验证说明、问题或提示信息
已处理	后续提交似乎已解决的问题

6. 报告发现

呈现汇总表：

区域	问题	状态	所需操作
状态检查	CI 构建失败	失败	修复 src/api.ts 中的类型错误
审查	“添加 null 检查” — @reviewer	可采取行动	添加保护子句
描述	测试计划中存在 TODO 占位符	可采取行动	补全测试计划
审查	“看起来不错” — @teammate	仅供参考	无

7. 修复问题（如有请求）

如果存在可采取行动的事项：

1. 切换到 PR/MR 的分支（git），或者确保文件已在正确的 CL（Perforce）中打开（如果尚未如此）。
2. 询问用户是否要修复这些问题。
3. 如果是，则进行修复，然后：

**GitHub/GitLab：**提交并推送：

git add <files>
git commit -m "address review feedback"
git push

**Perforce：**打开文件以供编辑，进行更改，然后重新搁置：

p4 edit <file>
# make changes
p4 shelve -f -c <CL_NUMBER>

8. 解决审查线程

处理完评论后，解决相应的审查线程。

Perforce — Perforce 没有原生的“解决线程”概念。可以通过更新 CL 描述，或在所用的审查工具（如 Swarm）中回复，来标记评论已处理。如果使用 p4 review：

# Mark files as reviewed after addressing feedback
p4 review -c <CL_NUMBER>

GitHub — 获取未解决的线程 ID（如有需要，请分页 — 参见 GraphQL 参考）：

gh api graphql -f query='
query($cursor: String) {
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: PR_NUMBER) {
      reviewThreads(first: 100, after: $cursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id
          isResolved
          comments(first: 1) {
            nodes { body path }
          }
        }
      }
    }
  }
}'

如果 hasNextPage 为 true，请使用 -f cursor=ENDCURSOR 重复查询，以获取剩余线程。

然后解决已处理或仅供参考的线程：

gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "THREAD_ID"}) {
    thread { isResolved }
  }
}'

使用别名（t1、t2 等）将多个解决操作批量合并到单个 mutation 中。

GitLab — 获取未解决的讨论（参见 GitLab API 参考）：

glab api "projects/:fullpath/merge_requests/<MR_IID>/discussions?per_page=100"

筛选 "resolved": false 的讨论。收集每个讨论的 id。

逐个解决每条讨论（GitLab 不支持批量解决）：

glab api --method PUT \
  "projects/:fullpath/merge_requests/<MR_IID>/discussions/<DISCUSSION_ID>" \
  --field resolved=true

对每个未解决的讨论 ID 重复此操作。

9. 多个 PR/MR/CL

如果要检查一系列 PR/MR/CL，请按顺序逐个处理。

Perforce — 若要一次检查多个变更列表：

p4 changes -s pending -u $P4USER -c $P4CLIENT -l

输出格式

汇总：

• PR/MR/CL 标题或描述及当前状态
• 检测到的平台（GitHub / GitLab / Perforce）
• 状态检查汇总（通过/失败/待处理）——Perforce 则填写 N/A
• 发现的问题总数
• 可采取行动的事项及其描述
• 可忽略的事项及原因
• 建议的后续步骤