Gh-fix-ci ：一个把 CI 调错变成标准流程的 GitHub Skill

PR 标红这件事，几乎所有开发者都逃不掉。你在 GitHub 上点了 merge 前的最后一下检查，结果看到五六个 check 挂着红色叉号，点进去是一屏又一屏的 Actions 日志。找失败原因的时间，往往比修复本身还长。

gh-fix-ci 就是冲着这个痛点来的。它是 OpenAI 发布到 Smithery 的一个 AI Skill，职责很聚焦：定位 PR 上失败的 GitHub Actions check，拉取日志，提炼出可读的失败摘要，草拟一份修复计划，在获得你明确批准之后才动手改代码。

我最初以为它是个“自动修 CI”的工具，把日志丢进去就等它改完。细看文档才发现设计重心根本不在“修”，而在两件事：把失败上下文的采集标准化，以及在实施前设一道人工审批门禁。

这篇文章带你走一遍 gh-fix-ci 的完整工作流，拆解它内置的检查脚本和几个关键设计决策，最后聊清楚它适合谁、在什么场景下会打折扣。

环境准备

用 gh-fix-ci 之前，得先确认两样东西：GitHub CLI 已经装好并完成认证。文档里的前置条件写得很直白，先跑一次 gh auth login，认证时记得勾上 repo 和 workflow 两个 scope，再用 gh auth status 确认一下状态。

少了 workflow scope 是个很隐蔽的坑。认证通过了，但拉 Actions 的 run 信息时会静默失败，排查半天才发现是权限问题。所以环境准备阶段的验证步骤别省。

Skill 本体从 Smithery 获取，按它的安装说明把 gh-fix-ci 放进 Agent 的 skills 目录就行。它自带一个 Python 脚本，所以本机要有可用的 Python 环境，脚本只依赖标准库，不需要额外装包。

装好之后，最快的验证方式是用脚本直接跑一次检查：

python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"

命令里的 --repo 默认就是当前目录，--pr 传 PR 编号或完整链接。加 --json 参数会输出结构化结果，方便机器解析。

操作流程

gh-fix-ci 的内部流程是一个八步闭环，从验证认证开始，到复查状态收尾。整体长这样：

跑起来之后，脚本优先解析当前分支的 PR，用 gh pr view --json number,url 拿到编号和链接。如果你明确传了 PR 号，就直接用你给的，这一步没有任何歧义。

真正的核心动作在第三步：检查失败的 checks。首选跑自带脚本，它处理了两个容易翻车的细节：gh CLI 输出字段的漂移，以及 job 日志的兜底获取。手动替代方案是 gh pr checks 配合 gh run view --log，但字段一旦被 gh 拒绝就得自己重试。

范围之外的处理很克制。如果某个 check 的 detailsUrl 指向的不是 GitHub Actions run，比如 Buildkite 或者别的 CI，脚本不会去碰它，只把 URL 报出来，保持流程精简。

汇总阶段会给出失败 check 的名称、run 的链接，以及一段精炼的日志片段。日志缺失的时候会明确标注“拿不到日志”，而不是假装分析。从这一步开始，人类拿到的是一份可以直接决策的摘要，不是原始日志。

日志抓取的规模控制也考虑了。脚本提供 --max-lines 和 --context 两个参数，前者限制拉取日志的总行数，后者控制失败上下文的行数。对那种动辄几千行的构建日志，这个限制能让摘要既完整，又不至于把上下文窗口撑爆。

计划与实施遵循“先批后动”。Agent 会用 create-plan 之类的技能起草一份修复计划，或者直接内联给出精简方案，然后停下来等你的批准。批准之后才改代码，改完总结 diff 和测试结果，再问你是否要开 PR。收尾时建议重跑相关测试和 gh pr checks，确认红叉真的变绿。

关键设计

gh-fix-ci 最值得琢磨的不是流程本身，而是脚本和流程的边界划分。inspect_pr_checks.py 被设计成可以独立运行的检查器，所有失败都会让进程以非零状态退出，这意味着它不光服务于 Agent，还能直接塞进自动化流水线当看门狗。

对 gh 字段漂移的兼容处理，是典型的实战痕迹。gh CLI 的 JSON 输出字段会随版本变化，文档里明确写了“如果字段被拒绝，就用 gh 实际返回的可用字段重跑”。这种防御逻辑，只有被真实 CLI 坑过的人才会写。

job-log 兜底是另一个细节。run 的日志显示还在进行中时，直接改用 gh api 拉具体 job 的日志文件。日志拉取是 CI 调试里最容易失败的一环，这里做了两层降级路径。

从结构上看，这个 skill 把输入、采集、输出分成了清晰的三层：

输入层只有三样东西：

• 仓库路径
• PR 编号
• gh 认证

采集层是那个脚本，职责分四块：

• 解析 checks
• 拉取日志
• 兼容字段漂移
• 兜底 job 日志

输出层是失败摘要、修复计划和实施结果。每层职责单一，这让整个 skill 很容易被理解和维护。

使用场景

最典型的场景是单个 PR 挂了多个 check。以前你要挨个点开、滚动日志、手动比对失败原因，现在一条命令就把所有失败 check 的摘要集合到一块。文档给的示例是 --pr "123"，传完整 PR 链接也行，比如 --pr "https://github.com/org/repo/pull/123"。

自动化场景里脚本的价值更明显。因为它非零退出，你可以把它挂进自己的 CI 或者定时任务里，一旦有 PR 检查失败就触发告警，甚至作为 Agent 工作流的入口条件。机器读 --json 输出，人只需要看摘要。

人机协作场景是设计者最在意的一条链路。Agent 负责三件事：

• 把日志读完
• 把失败原因讲清楚
• 把修复方案摆出来

人类只做两件事：批准方案、审核 diff。这在多 PR 并行维护的时候省下的时间非常可观。

边界同样要讲清楚。它只认 GitHub Actions，外部 CI 一律只报 URL；没有 gh 认证的环境里它一步都走不动；而且修复方案本身仍然需要人的判断，它不是无脑全自动的修 bug 机器。

洞察与反思

用下来最深的感受是：CI 调试最大的成本从来不是修，而是读。日志几百行，真正失败的那几行淹没在噪音里，gh-fix-ci 把“读”这一步压缩成了一段摘要加一个链接。这个取舍很聪明，它不抢你判断的活，只帮你把信息整理到能判断的程度。

手动调试和脚本化采集的差距，比预想的大得多：

左侧是纯手动路径，你得自己拼命令、自己处理字段报错、自己在日志还在跑的时候另找 API 拉 job 日志。右侧是脚本路径，这些脏活全部内置了。人省下来的不是敲键盘的时间，而是反复试错的心智成本。

脚本独立于 skill 存在，这个拆分值得一提。它把“检查器”和“Agent 工作流”解耦了，同一份能力既能给 Agent 用，也能给脚本用。文档里甚至提示脚本可以用于自动化，这种“能力可复用”的设计比把一切焊死在 Agent 流程里高明。

审批门禁这个设计，放到 Agent 生态里看尤其难得。多数自动化工具追求的是全自动，恨不得你只点一个按钮。gh-fix-ci 反而在动手改代码之前强制停下，把方案摆到你面前等批准。它默认 Agent 的判断需要人来兜底，这个前提假设比功能本身更值得学习。

局限也真实存在。它对非 Actions 的 CI 完全无能为力，认证问题会直接卡死流程，而且修复计划的质量取决于 Agent 怎么消化摘要。如果你期待的是“丢个 PR 链接就全自动修好”，它会让你失望；如果你要的是“把 CI 调错的体力活标准化”，它非常对路。

资源地址

总结

回到开头那个场景：PR 标红依然会频繁发生，但“读懂失败”这件事可以不再靠人肉。gh-fix-ci 把日志采集、摘要提炼、计划审批串成了一条标准化流水线，让每次 CI 调试都走同一条成熟路径，而不是每次从头翻日志。

它适合两类人。一类是频繁维护 PR、被 check 红叉磨到没脾气的开发者；另一类是想给 Agent 装上 CI 调试能力的自动化爱好者。前者得到的是摘要和计划，后者得到的是可编程的检查器。

下一步很具体：装好 gh-fix-ci，先不带 Agent，直接跑一次 inspect_pr_checks.py --json，看看它对真实失败 check 的摘要质量。满意之后，再放它进你的 Agent 工作流，让它替你读完下一次 PR 的日志。