前言¶
PR 提交之后，最折磨人的往往不是写代码本身，而是等 CI 跑完——红叉一亮，就得在 GitHub Actions 页面和本地终端之间来回切换：点开失败的 job、翻几百行日志、猜到底是哪一步挂了。团队里如果 workflow 多、矩阵构建复杂，排查一次 CI 失败常常要占去大半个下午。
如果你已经在用 Cursor、Codex CLI 或 Claude Code 这类 AI 编程工具，OpenAI 官方 curated 技能 gh-fix-ci 可以把这套流程标准化：让 Agent 用 gh 拉取失败检查与日志、提取关键报错片段、给出修复方案，并在你明确同意后再动手改代码。本文基于 openai/skills 仓库 中的官方 SKILL.md 与配套脚本整理，关键步骤均可复现。
这是什么¶
gh-fix-ci 是一个遵循 Agent Skills 开放标准（agentskills.io）的技能包，由 OpenAI 维护，收录在 openai/skills 仓库的 .curated 目录下。它的定位很清晰：当用户要求调试或修复 GitHub Actions 上失败的 PR 检查时，Agent 应启用此技能，通过 GitHub CLI（gh）完成「定位失败 → 拉日志 → 总结原因 → 制定方案 → 获批后修复 → 复查状态」的完整闭环。
需要说明的是：openai/skills 仓库 README 标注该仓库已 deprecated，并指向 OpenAI Plugins 仓库 作为后续示例来源；但 gh-fix-ci 的 SKILL.md、脚本与 Codex 文档仍可正常访问，社区安装工具（如 npx skills add）也持续收录该技能，日常安装使用不受影响。
核心功能与亮点¶
1. 聚焦 GitHub Actions，边界清晰¶
技能只处理 detailsUrl 指向 GitHub Actions 运行的检查项。若失败检查来自 Buildkite 等外部 CI 提供方，Agent 会将其标记为 external，仅汇报详情链接，不强行深入——避免在无法控制的系统上浪费 token 和时间。
2. 自带 inspect_pr_checks.py 脚本¶
技能目录下 bundled 了 Python 脚本 scripts/inspect_pr_checks.py，专门用来：
- 调用
gh pr checks列出 PR 上所有检查，筛选失败项； - 从
detailsUrl解析 run id / job id，拉取gh run view --log或 job 级日志； - 兼容
gh不同版本的 JSON 字段差异（如conclusion与bucket字段漂移）； - 在日志中搜索
error、fail、traceback、assert等关键词，提取失败片段而非整段 dump； - 支持
--json输出，便于 Agent 结构化总结； - 仍有失败时以非零退出码结束，可用于自动化流水线。
3. 「先计划、后动手」的安全工作流¶
官方 workflow 明确要求：总结失败上下文后，优先调用 create-plan 技能（若已安装）或 inline 起草修复计划，必须获得用户明确批准 才实施代码变更。改完后建议重跑相关测试并用 gh pr checks 确认状态——这对 CI 修复这类高风险操作尤为重要。
4. 前置依赖简单¶
唯一硬性依赖是已安装并认证的 GitHub CLI。官方建议执行 gh auth login，并通过 gh auth status 确认具备 repo 与 workflow 权限——后者是拉取 Actions 日志的必要 scope。
安装与启用¶
gh-fix-ci 基于通用 SKILL.md 格式，可在多个 AI 编程工具中使用。以下方式均来自官方或 Cursor 文档，按你所用的工具选择其一即可。
在 Codex CLI 中安装¶
OpenAI 官方 README 提供两种方式：
方式一：使用内置 skill-installer（在 Codex 会话中）
$skill-installer gh-fix-ci
方式二：使用社区 skills CLI
npx skills add https://github.com/openai/skills --skill gh-fix-ci
安装后需重启 Codex 以加载新技能。.system 目录下的系统技能会自动安装，curated 技能需手动安装。
在 Cursor 中启用¶
Cursor 会从以下目录自动发现技能（官方文档）：
| 路径 | 作用域 |
|---|---|
.cursor/skills/ |
项目级 |
~/.cursor/skills/ |
用户级（全局） |
将 gh-fix-ci 整个目录（含 SKILL.md 与 scripts/）放入上述路径之一即可，例如：
git clone --depth 1 https://github.com/openai/skills.git /tmp/openai-skills
cp -r /tmp/openai-skills/skills/.curated/gh-fix-ci ~/.cursor/skills/
目录结构应类似：
.cursor/skills/gh-fix-ci/
├── SKILL.md
├── scripts/
│ └── inspect_pr_checks.py
├── agents/
│ └── openai.yaml
└── assets/
重启 Cursor 或在 Agent 对话中输入 /gh-fix-ci 可手动触发。Agent 也会在你提到「CI 红了」「PR 检查失败」等语境时自动匹配该技能。
在 Claude Code 等其他工具中¶
遵循 Agent Skills 标准的工具通常支持 .claude/skills/ 或 .agents/skills/ 目录，安装方式与 Cursor 类似——复制技能文件夹到对应目录即可。Cursor 文档也注明会兼容 .claude/skills/、.codex/skills/ 等路径。
典型用法示例¶
前置：确认 gh 已认证¶
gh auth login
gh auth status
若 auth status 显示缺少 workflow scope，需重新登录并勾选相应权限。
快速排查当前分支 PR¶
在仓库根目录，可直接运行技能自带脚本（将路径替换为你的技能安装位置）：
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py --repo "."
未指定 --pr 时，脚本会通过 gh pr view --json number 自动解析当前分支关联的 PR。输出示例包含：失败检查名称、Run ID、Workflow 信息，以及提取出的 Failure snippet。
指定 PR 编号或 URL：
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--pr "123"
需要机器可读输出时加 --json：
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--pr "123" \
--json
调整日志窗口大小：
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--max-lines 200 \
--context 40
手动 fallback（脚本不可用时的等价操作）¶
官方 SKILL.md 也记录了纯 gh 命令链路，便于人工或 Agent 逐步执行：
# 1. 查看 PR 检查列表
gh pr checks 123 --json name,state,bucket,link,startedAt,completedAt,workflow
# 2. 从 detailsUrl 提取 run_id 后查看运行详情
gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha
# 3. 拉取完整日志
gh run view <run_id> --log
# 4. 若日志尚在生成中，改拉 job 级日志
gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs"
在 Agent 对话中的提示词¶
Codex 为该技能配置了默认提示（见 agents/openai.yaml）：
Inspect failing GitHub Actions checks in this repo, summarize root cause, and propose a focused fix plan.
你也可以用中文直接描述场景，例如：
这个 PR 的 CI 挂了，帮我用 gh 查一下哪个 check 失败、日志里具体报什么错，先给出修复计划，我确认后再改。
Agent 启用 gh-fix-ci 后会按 workflow 逐步执行：认证检查 → 解析 PR → 跑脚本或 fallback → 汇总 snippet → 起草计划 → 等你批准。
适用场景与注意事项¶
适合谁用：
- 日常在 GitHub 上提 PR、依赖 Actions 做 lint/test/build 的开发者；
- 维护多个 workflow、矩阵构建经常「只有某一个组合红」的仓库维护者；
- 希望把「CI 失败排查」交给 AI Agent，但保留人工审批权的团队。
典型场景：
- PR 合并前某个 job 突然失败，需要快速定位是测试断言、依赖安装还是环境配置问题；
- 本地无法复现、只能依赖 Actions 日志的 flaky test；
- 新同事不熟悉
gh命令，希望 Agent 代为拉日志并解释报错含义。
注意事项：
- 仅覆盖 GitHub Actions。Jenkins、CircleCI、Buildkite 等外部检查只会返回 URL，不会自动修复。
- 必须先
gh auth login，且需 workflow scope；否则脚本会在ensure_gh_available阶段直接报错退出。 - 修复需显式批准。技能设计刻意避免 Agent 未经确认就改 workflow 或测试代码——CI 配置改动影响面大，这一步不能省。
- 日志仍在生成时可能返回
log_pending状态，需等 job 完成后再查，或改用 job 级 API。 - 若已安装 create-plan 技能，gh-fix-ci 会优先调用它生成结构化修复计划，两者可搭配使用。
小结¶
CI 失败排查是开发者最高频的痛点之一。gh-fix-ci 把 OpenAI 官方 curated 经验封装成可复用的 Agent Skill：用 gh 自动化拉取 PR 检查与 Actions 日志，用 bundled 脚本提取失败片段，再按「计划 → 批准 → 修复 → 复查」的安全流程推进。无论你是 Codex、Cursor 还是 Claude Code 用户，把技能目录放进对应路径、确保 gh 已认证，下次 PR 红叉亮起时，直接让 Agent 帮你查就行。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci
Codex Skills 文档：https://developers.openai.com/codex/skills
