CI 失败分析

开始时声明："我正在使用 ci-analyze skill 分析 CI 失败原因。"

项目 CI 概览

本项目使用 GitHub Actions（.github/workflows/ci-test.yml），CI 流程：

1. gofmt 检查（仅 stable）：gofmt -s -l . 检查未格式化文件
2. staticcheck（仅 stable）：make staticcheck
3. 编译 examples（仅 stable）：go build ./examples/...
4. 单元测试（Go 1.22 + stable）：make unittest
5. Windows 单元测试：Linux 通过后运行
6. macOS 单元测试：Windows 通过后运行

何时不要使用（Do NOT use）

• 用户仅请求"实现功能/改代码"，且未提供任何 CI 失败上下文。
• CI 状态为全部通过，仅需常规代码审查或功能验证。

触发样例与非样例

• 应触发：
• "这个 PR 的 CI 红了，帮我定位根因并给修复建议。"
• "pipeline failed，给我一份失败分析报告。"
• 不应触发：
• "帮我实现这个接口并补测试。"
• "帮我 review 这个 PR。"

使用示例

# 按 PR 编号分析
ci-analyze 123

# 按 run URL 分析
ci-analyze https://github.com/qiniu/go-sdk/actions/runs/999999

核心原则

1. 每个失败都视为潜在真实 bug，不要轻易归因为 infra flakiness
2. 必须给出根因和修复建议，不能只收集日志不给结论
3. 分析所有失败，不只是第一个

执行流程

步骤 1：获取失败列表

# 获取 PR 的 CI checks
gh pr checks <PR编号> --repo qiniu/go-sdk

# 或获取最近一次 workflow run 的失败
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：获取失败日志

# GitHub Actions 失败日志
gh run view <run-id> --repo qiniu/go-sdk --log-failed

步骤 3：分析每个失败

对每个失败的 check/job：

1. 获取完整错误日志
2. 定位失败的测试或步骤
3. 在代码中找到对应位置
4. 检查 git blame 看最近改动
5. 判断根因类别：
   • 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：

1. 同一测试在同一分支的最近 3+ 次运行中至少有 1 次通过
2. 错误信息显示明确的基础设施问题（网络超时、资源不足等）
3. 代码路径没有最近改动

# 检查历史运行
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 为准。