| name | ci-analyze |
| description | 分析 CI 失败原因并给出修复建议。在用户提到 CI 失败、pipeline 失败、构建失败、测试失败时使用。典型场景：PR 合前 CI 红、需要根因与修复建议时。 |
| argument-hint | <PR 编号或 CI URL> |
| allowed-tools | ["Read","Grep","Glob","Bash(gh run list:*)","Bash(gh run view:*)","Bash(gh pr view:*)","Bash(gh pr checks:*)","Bash(gh api *)","Bash(git *)","Bash(curl *)","Bash(jq *)","Bash(cat *)","Bash(wc *)","Bash(head *)","Bash(tail *)","Bash(grep *)"] |
CI 失败分析
开始时声明："我正在使用 ci-analyze skill 分析 CI 失败原因。"
项目 CI 概览
本项目使用 GitHub Actions（.github/workflows/ci-test.yml），CI 流程：
- gofmt 检查（仅 stable）：
gofmt -s -l . 检查未格式化文件
- staticcheck（仅 stable）：
make staticcheck
- 编译 examples（仅 stable）：
go build ./examples/...
- 单元测试（Go 1.22 + stable）：
make unittest
- Windows 单元测试：Linux 通过后运行
- macOS 单元测试：Windows 通过后运行
何时不要使用（Do NOT use）
- 用户仅请求"实现功能/改代码"，且未提供任何 CI 失败上下文。
- CI 状态为全部通过，仅需常规代码审查或功能验证。
触发样例与非样例
- 应触发：
- "这个 PR 的 CI 红了，帮我定位根因并给修复建议。"
- "pipeline failed，给我一份失败分析报告。"
- 不应触发：
- "帮我实现这个接口并补测试。"
- "帮我 review 这个 PR。"
使用示例
ci-analyze 123
ci-analyze https://github.com/qiniu/go-sdk/actions/runs/999999
核心原则
- 每个失败都视为潜在真实 bug，不要轻易归因为 infra flakiness
- 必须给出根因和修复建议，不能只收集日志不给结论
- 分析所有失败，不只是第一个
执行流程
步骤 1：获取失败列表
gh pr checks <PR编号> --repo qiniu/go-sdk
gh run list --repo qiniu/go-sdk --branch <branch> --limit 5
gh run view <run-id> --repo qiniu/go-sdk --log-failed
获取 CI 状态概览：
gh pr view <PR编号> --repo qiniu/go-sdk \
--json statusCheckRollup \
--jq '.statusCheckRollup[]? | {name: .context, state: .state, url: .targetUrl}'
步骤 2：获取失败日志
gh run view <run-id> --repo qiniu/go-sdk --log-failed
步骤 3：分析每个失败
对每个失败的 check/job：
- 获取完整错误日志
- 定位失败的测试或步骤
- 在代码中找到对应位置
- 检查 git blame 看最近改动
- 判断根因类别：
- regression：我们的代码改动导致
- flaky：间歇性基础设施问题（需要证据：同一测试在 3+ 次其他运行中通过）
- environment：配置或依赖问题
- format：gofmt 或 staticcheck 不通过
步骤 4：输出分析报告
- 失败汇总表：最多列出 20 条，超出用「其余见日志」概括。
- 详细分析：每项「根因分析 + 修复建议」合计不超过 300 字；只保留值得写的项。
## CI 失败分析报告
### 失败汇总
| 序号 | 测试/Job | 错误类型 | 根因 | 置信度 |
|------|----------|----------|------|--------|
| 1 | ... | ... | ... | 高/中/低 |
### 详细分析
#### 失败 1: <测试名>
错误信息：
<具体错误日志>
日志来源：
<GitHub Actions URL 或 API 端点>
根因分析：
<分析过程>
修复建议：
<具体修复方案>
相关代码：
<文件路径:行号>
步骤 5：提出修复方案
- 对于 regression 类型：给出具体代码修复
- 对于 flaky 类型：说明判断依据，建议重跑或标记 flaky
- 对于 environment 类型：说明配置修复方案
- 对于 format 类型：运行
gofmt -s -w . 或修复 staticcheck 报告的问题
常见失败模式（本项目特有）
| 失败类型 | 典型表现 | 修复方式 |
|---|
| gofmt | "Files not formatted" | gofmt -s -w . |
| staticcheck | SA/S/ST 开头的错误码 | 按 staticcheck 建议修复 |
| examples 编译 | go build ./examples/... 失败 | 检查 examples 依赖的包是否有 breaking change |
| 单元测试 | FAIL + 具体测试函数名 | 定位测试代码和被测代码 |
| Windows/macOS | 平台相关路径、换行符问题 | 使用 filepath.Join 等跨平台写法 |
判断 flaky 的证据要求
只有满足以下条件才能判定为 flaky：
- 同一测试在同一分支的最近 3+ 次运行中至少有 1 次通过
- 错误信息显示明确的基础设施问题（网络超时、资源不足等）
- 代码路径没有最近改动
gh run list --repo qiniu/go-sdk --branch <branch> --workflow "Run Test Cases" --limit 10
禁止事项
- 不要在没有证据的情况下说"可能是 flaky"
- 不要只列出失败不给结论
- 不要忽略任何一个失败
验收标准（统一）
- 输入前提：参数与上下文可解析；缺省参数按 skill 默认值执行，并在输出中注明。
- 产出要求：按 skill 约定的输出模板给出结果，并包含关键证据（命令、路径、链接或日志摘要）。
- 通过判定：主流程步骤已完成且无阻塞；若有未完成项，必须明确标注影响范围与下一步。
- 默认策略（非交互）：需要确认但用户未及时响应时，采用"推荐默认值/最小风险项"继续；需要交互选择时优先推荐项。
- 阻塞升级：遇到权限、凭证、外部依赖缺失时立即停止该步骤，输出"阻塞点 + 已尝试 + 需要用户提供的信息"。
系统规范（AGENTS.md）
执行本 skill 时同时遵守 AGENTS.md 中的系统规范；与本 skill 冲突时以本 skill 为准。
