# CI Analyze

> 分析 CI 失败原因并给出修复建议。在用户提到 CI 失败、pipeline 失败、构建失败、测试失败时使用。典型场景：PR 合前 CI 红、需要根因与修复建议时。

- Skill: `qiniu/ci-analyze` (Agent Skill)
- Install (CLI): `npx skillmds@latest add qiniu/ci-analyze`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qiniu/ci-analyze/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: qiniu (https://skillmd.com/u/qiniu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qiniu/ci-analyze

---


# 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。"

## 使用示例

```bash
# 按 PR 编号分析
ci-analyze 123

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

## 核心原则

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

## 执行流程

### 步骤 1：获取失败列表

```bash
# 获取 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 状态概览：

```bash
gh pr view <PR编号> --repo qiniu/go-sdk \
  --json statusCheckRollup \
  --jq '.statusCheckRollup[]? | {name: .context, state: .state, url: .targetUrl}'
```

### 步骤 2：获取失败日志

```bash
# 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 字；只保留值得写的项。

```plaintext
## 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. 代码路径没有最近改动

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