mcpField
P
prcheckloop

prcheckloop

github.com/paperclipai测试与质量108.3k184 次安装今天更新
代码仓库

关于 prcheckloop

用于处理 GitHub 拉取请求 CI 检查的技能，可修复可处理的失败，或报告明确阻碍。它持续跟踪最新 head SHA 的检查，并在每次推送后重新检查。

主要功能

  1. 01按编号或分支查找 PR
  2. 02跟踪最新 head SHA 的检查
  3. 03检查待处理和失败项
  4. 04修复可处理的问题并推送
  5. 05报告阻碍及后续步骤

适用场景

  1. 01使 GitHub PR 检查全部通过
  2. 02诊断代码推送后的失败
  3. 03查找缺失检查或 CI 阻碍

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paperclipai/paperclip --skill prcheckloop

安装后在 Claude Code 中输入/prcheckloop确认已加载。

详细介绍

PRCheckloop

让 GitHub PR 的所有检查都变为绿色；如果无法做到，则明确指出具体阻碍。

范围

  • 仅处理 GitHub PR。如果仓库使用 GitLab，请停止并使用 check-pr。
  • 关注最新 PR head SHA 的检查，而非旧提交。
  • 关注 CI／状态检查，而非审查评论或 PR 模板清理。
  • 如果用户还希望清理审查评论，请配合使用 check-pr。

输入

  • PR 编号（可选）：如果未提供，则检测当前分支对应的 PR。
  • 最大迭代次数：默认为 5。

工作流

1. 确定 PR

如果未提供 PR 编号，则从当前分支检测：

gh pr view --json number,headRefName,headRefOid,url,isDraft

如有需要，请在进行更改前切换到 PR 分支。

出现以下情况时，请尽早停止：

  • gh 未通过身份验证
  • 该分支没有对应的 PR
  • 仓库托管在 GitHub 以外的平台
2. 跟踪最新 head SHA

始终针对当前 PR head SHA 操作：

PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)

忽略旧 SHA 的失败检查。每次推送后，刷新 HEAD_SHA 并重新开始检查循环。

3. 清点该 SHA 的检查

同时获取 GitHub 检查运行记录和旧版提交状态上下文：

gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"

要简洁地查看 PR 级别的信息，可以使用此 GraphQL 负载：

gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }
            ... on StatusContext { context state targetUrl description }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"
4. 等待检查实际运行

推送后，检查可能需要一段时间才会出现。每隔 15-30 秒轮询一次，直到满足以下任一条件：

  • 检查已出现，且每项都处于终止状态
  • 检查已出现，且至少有一项失败
  • 等待合理时间（通常为 2 分钟）后仍未出现任何检查

将以下状态视为成功终止状态：

  • 检查运行记录：SUCCESS、NEUTRAL、SKIPPED
  • 状态上下文：SUCCESS

将以下状态视为待处理：

  • 检查运行记录：QUEUED、PENDING、WAITING、REQUESTED、IN_PROGRESS
  • 状态上下文：PENDING

将以下状态视为失败：

  • 检查运行记录：FAILURE、TIMED_OUT、CANCELLED、ACTION_REQUIRED、STARTUP_FAILURE、STALE
  • 状态上下文：FAILURE、ERROR

如果最新 SHA 没有出现任何检查，请检查 .github/workflows/、工作流路径筛选条件以及分支保护要求。如果缺失的检查无法通过仓库内的操作触发或修复，请升级处理。

5. 调查失败的检查

对于 GitHub Actions 失败，请检查当前 SHA 对应的运行记录和失败日志：

gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
gh run view <RUN_ID> --log-failed

对每项失败的检查进行分类：

失败类型处理方式
代码／测试回归在本地复现、修复并验证
Lint／类型／构建不匹配运行工作流中对应的本地命令并修复
不稳定测试或临时基础设施问题有证据表明问题由不稳定因素导致时，重跑一次
外部服务／状态应用失败提供详情 URL 和可能的负责人信息，并升级处理
缺少密钥／权限／分支保护问题立即升级处理

不更改代码时，失败任务最多只能重跑一次。不要反复重跑。

6. 修复可处理的失败

如果可以通过已检出的代码修复失败：

  1. 阅读工作流或失败命令，确定实际的检查关卡。
  2. 在合理情况下于本地复现。
  3. 进行最小且正确的修复。
  4. 先运行针对性验证，再按需进行更全面的验证。
  5. 提交一个逻辑清晰的提交。
  6. 在重新检查 PR 前推送更改。

不要只完成本地修复。只有远程 PR 针对新 head SHA 的检查全部变为绿色，循环才算完成。

7. 推送并重复检查

每次修复后：

git push
sleep 5

然后刷新 PR 元数据，获取新的 HEAD_SHA，并从第 3 步重新开始。

仅在以下情况下退出循环：

  • 最新 head SHA 的所有检查都已通过，或
  • 经过合理的修复尝试后仍存在阻碍，或
  • 已达到最大迭代次数
8. 精确说明阻塞问题

如果无法让 PR 的所有检查通过，请报告：

  • PR URL
  • 最新的 head SHA
  • 失败或缺失检查的准确名称
  • 详情 URL
  • 已尝试的操作
  • 受阻原因
  • 最可能解决阻塞问题的人
  • 下一步具体操作

良好的阻塞问题示例：

  • 外部状态应用服务中断
  • 缺少 GitHub 密钥或权限
  • 分支保护中的必需检查名称不匹配
  • 重新运行一次后仍持续出现偶发故障
  • 故障需要你不具备的凭据或基础设施访问权限

输出

技能执行完毕后，请报告：

  • PR URL 和分支
  • 最终 head SHA
  • 通过／待处理／失败的检查摘要
  • 已进行的修复和验证
  • 是否已推送更改
  • 若检查未全部通过，提供阻塞问题摘要

备注

  • 此技能的范围有意小于 check-pr：它专门用于修复 PR 检查问题。
  • 此技能与 greploop 互为补充：即使 Greptile 全部通过，CI 仍可能失败。

评论

支持 Markdown