前言¶
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
