cidiff

cidiff

这些 CI 失败中，哪些确实是你的问题？

一个 PR 上有 12 项检查失败，通常只有一个是真正的问题。其他失败可能在基础分支上就已存在，属于部署预览服务，或者正在等待维护者批准工作流运行。如今，你得先后点击 PR 和基础分支上的每项检查，再逐一对照，才能弄清楚原因。

cidiff 会为你完成这项对比。它会读取 PR 头部提交和基础提交上的检查运行及提交状态，并对每项检查进行分类：

类别	含义
introduced	基础分支上通过，头部提交上失败。这项需要由 PR 修复
pre-existing	头部提交和基础分支上都失败，且检查名称相同
external	托管或部署预览服务（Vercel、Netlify、Cloudflare 等，根据检查名称匹配），或正在等待维护者批准的检查（action_required）
fixed	基础分支上失败，头部提交上通过；或者头部提交运行了其他检查，但该项检查已消失
passing	头部提交上通过
indeterminate	检查失败，但没有可用的基础分支证据来确认具体情况
pending	头部提交的运行尚未完成

存在新引入的失败时，退出代码为 1；否则为 0，因此可以直接用于 CI 门禁或维护者的分类脚本。

诚实原则

cidiff 从 Greenlight 中的 CI 分类功能提取而来。在一次扫描中，它对 46 个未关闭 PR 中的 89 项失败检查进行了分类，发现没有新引入的失败。要确保这个结果准确，就必须拒绝猜测：

• 没有基础分支证据，就标记为无法判定，绝不妄下结论。 如果头部提交上的检查失败，但没有基础分支运行记录，就会报告为无法证实，不论结果对你是否有利。
• 只有头部提交实际运行过检查，基础分支上的失败才会被标记为“已修复”。 第一天针对真实的派生仓库 PR（usebruno/bruno #9569）进行试用时，我们发现了这个陷阱：PR 的检查套件卡在 action_required，等待维护者批准工作流，因此头部提交没有任何检查运行记录。简单的差异比较工具会把基础分支上的所有失败都报告为已修复，并把基础分支上的所有通过都报告为通过。cidiff 会检测头部提交上没有检查运行记录的情况，读取检查套件，并通过清晰的警告说明：CI 尚未在此头部提交上运行，因此目前还无法对这些失败进行分类。
• 旧版提交状态也算作证据。 Snyk、CodeRabbit 和较早的 CI 系统通过 Statuses API 而不是检查运行上报状态。cidiff 会合并两者；名称冲突时，以实际检查运行记录为准。
• 先分类外部阻碍。 Vercel 预览失败并不代表测试失败，等待维护者批准的检查也不代表代码有问题。这两种情况都会在进行任何基础分支比较之前标记为外部问题。
• 不稳定的证据不能用于归因。 如果同一提交上同一项检查的已完成运行结果不一致（相同代码有时通过、有时失败），则该检查不稳定。如果比较结论依赖不稳定一侧的单次结果（新引入、既有、已修复），cidiff 会将其标记为无法判定并暂不下结论，同时在报告中标记 flaky 并记录尝试次数；如果最新结果是通过，则保留通过结论并标记该项。文本报告会在 [FLAKY] 行列出不稳定的检查。

用法

CLI

# Classify a PR's checks against its base
npx @reneturcios/cidiff pr usebruno/bruno 9569

# Machine readable output
npx @reneturcios/cidiff pr owner/repo 123 --json

# Compare two commits directly
npx @reneturcios/cidiff runs owner/repo --head <sha> --base <sha>

输出示例（上述派生仓库 PR 案例的真实输出）：

cidiff usebruno/bruno PR #9569: 0 introduced, 0 pre-existing, 0 external, 0 fixed, 6 indeterminate, 0 pending, 2 passing
  [WARNING] No check runs on head commit 885c6fafed1e (only 2 commit status(es)). The workflow system has produced no evidence to diff against; base check failures below are indeterminate, not fixed.
  [WARNING] 3 check suite(s) on the head commit are action_required: CI is waiting on maintainer approval to run (typical for fork PRs). The failures cannot be classified until CI actually runs.
  [INDETERMINATE] Unit Tests (Linux): Failing on base, and the head commit has no check runs, so there is nothing to compare. CI may not have run on the head yet
  [PASSING] CodeRabbit, security/snyk (Bruno)
Verdict: no introduced failures. Any failing checks are pre-existing, external, or unproven either way (indeterminate).

明确说明已知限制：基础分支比较使用 PR 基础提交（PR 对象中存储的基础分支尖端）所记录的检查证据，并按完全相同的名称匹配检查。重命名的检查会被视为一项移除和一项新增。输出中会清楚显示这两项限制，不会隐藏它们。

设置 GITHUB_TOKEN，以获得更高的 GitHub API 认证速率限制。访问公开仓库不需要其他凭据。

MCP 服务

添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "cidiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cidiff", "mcp"]
    }
  }
}

工具：

• diff_pr_ci：提供仓库和 PR 编号，返回完整的分类报告（JSON）。
• diff_ci_runs：提供仓库以及头部和基础 SHA，执行相同的分类，但不需要 PR。

Docker

docker run -i ghcr.io/cloudcorprecords/cidiff mcp
docker run --rm ghcr.io/cloudcorprecords/cidiff pr owner/repo 123

工具包

cidiff 是同一作者计划打造的一系列小型单一用途开发者工具中的 Wave 1、package 2。它们都采用相同的构建方式：一个 bin 同时提供 CLI 和 MCP 服务，执行确定性检查并给出证据，不编造答案。它的同系列工具 shipcheck 用于验证已完成的发布，而它也会反过来验证 cidiff 自身的发布。

• greenlight：开源贡献的预检：这个 issue 真的能合并吗？
• shipcheck：发布验证：git tag、release、npm、MCP Registry 和 GHCR 必须保持一致，否则就是 NO-GO。
• prwatch：开放 PR 的关注报告：当前有哪些事项需要你处理。
• claimcheck：跟踪过期声明的状态，以及分叉仓库中搁置的修复。
• gatefile：将隐藏的贡献门槛提取为机器可读的 contribution-gates.json。
• pkgverdict：npm 软件包的安装前判定：GO、RISKY、FAKE 或 MISSING。

开发

npm install
npm run build
npm test   # 31 tests, classification logic runs on fixtures, no network

许可证

MIT