github.com/qiniu/go-sdk/v7@v7.27.0/.agents/skills/ci-analyze/SKILL.md (about)

     1  ---
     2  name: ci-analyze
     3  description: 分析 CI 失败原因并给出修复建议。在用户提到 CI 失败、pipeline 失败、构建失败、测试失败时使用。典型场景：PR 合前 CI 红、需要根因与修复建议时。
     4  argument-hint: "<PR 编号或 CI URL>"
     5  allowed-tools:
     6    - Read
     7    - Grep
     8    - Glob
     9    - Bash(gh run list:*)
    10    - Bash(gh run view:*)
    11    - Bash(gh pr view:*)
    12    - Bash(gh pr checks:*)
    13    - Bash(gh api *)
    14    - Bash(git *)
    15    - Bash(curl *)
    16    - Bash(jq *)
    17    - Bash(cat *)
    18    - Bash(wc *)
    19    - Bash(head *)
    20    - Bash(tail *)
    21    - Bash(grep *)
    22  ---
    23  
    24  # CI 失败分析
    25  
    26  开始时声明："我正在使用 ci-analyze skill 分析 CI 失败原因。"
    27  
    28  ## 项目 CI 概览
    29  
    30  本项目使用 GitHub Actions（`.github/workflows/ci-test.yml`），CI 流程：
    31  
    32  1. **gofmt 检查**（仅 stable）：`gofmt -s -l .` 检查未格式化文件
    33  2. **staticcheck**（仅 stable）：`make staticcheck`
    34  3. **编译 examples**（仅 stable）：`go build ./examples/...`
    35  4. **单元测试**（Go 1.22 + stable）：`make unittest`
    36  5. **Windows 单元测试**：Linux 通过后运行
    37  6. **macOS 单元测试**：Windows 通过后运行
    38  
    39  ## 何时不要使用（Do NOT use）
    40  
    41  - 用户仅请求"实现功能/改代码"，且未提供任何 CI 失败上下文。
    42  - CI 状态为全部通过，仅需常规代码审查或功能验证。
    43  
    44  ## 触发样例与非样例
    45  
    46  - 应触发：
    47  - "这个 PR 的 CI 红了，帮我定位根因并给修复建议。"
    48  - "pipeline failed，给我一份失败分析报告。"
    49  - 不应触发：
    50  - "帮我实现这个接口并补测试。"
    51  - "帮我 review 这个 PR。"
    52  
    53  ## 使用示例
    54  
    55  ```bash
    56  # 按 PR 编号分析
    57  ci-analyze 123
    58  
    59  # 按 run URL 分析
    60  ci-analyze https://github.com/qiniu/go-sdk/actions/runs/999999
    61  ```
    62  
    63  ## 核心原则
    64  
    65  1. 每个失败都视为潜在真实 bug，不要轻易归因为 infra flakiness
    66  2. 必须给出根因和修复建议，不能只收集日志不给结论
    67  3. 分析所有失败，不只是第一个
    68  
    69  ## 执行流程
    70  
    71  ### 步骤 1：获取失败列表
    72  
    73  ```bash
    74  # 获取 PR 的 CI checks
    75  gh pr checks <PR编号> --repo qiniu/go-sdk
    76  
    77  # 或获取最近一次 workflow run 的失败
    78  gh run list --repo qiniu/go-sdk --branch <branch> --limit 5
    79  gh run view <run-id> --repo qiniu/go-sdk --log-failed
    80  ```
    81  
    82  获取 CI 状态概览：
    83  
    84  ```bash
    85  gh pr view <PR编号> --repo qiniu/go-sdk \
    86    --json statusCheckRollup \
    87    --jq '.statusCheckRollup[]? | {name: .context, state: .state, url: .targetUrl}'
    88  ```
    89  
    90  ### 步骤 2：获取失败日志
    91  
    92  ```bash
    93  # GitHub Actions 失败日志
    94  gh run view <run-id> --repo qiniu/go-sdk --log-failed
    95  ```
    96  
    97  ### 步骤 3：分析每个失败
    98  
    99  对每个失败的 check/job：
   100  
   101  1. 获取完整错误日志
   102  2. 定位失败的测试或步骤
   103  3. 在代码中找到对应位置
   104  4. 检查 git blame 看最近改动
   105  5. 判断根因类别：
   106     - regression：我们的代码改动导致
   107     - flaky：间歇性基础设施问题（需要证据：同一测试在 3+ 次其他运行中通过）
   108     - environment：配置或依赖问题
   109     - format：gofmt 或 staticcheck 不通过
   110  
   111  ### 步骤 4：输出分析报告
   112  
   113  - 失败汇总表：最多列出 20 条，超出用「其余见日志」概括。
   114  - 详细分析：每项「根因分析 + 修复建议」合计不超过 300 字；只保留值得写的项。
   115  
   116  ```plaintext
   117  ## CI 失败分析报告
   118  
   119  ### 失败汇总
   120  
   121  | 序号 | 测试/Job | 错误类型 | 根因 | 置信度 |
   122  |------|----------|----------|------|--------|
   123  | 1    | ...      | ...      | ...  | 高/中/低 |
   124  
   125  ### 详细分析
   126  
   127  #### 失败 1: <测试名>
   128  
   129  错误信息：
   130  <具体错误日志>
   131  
   132  日志来源：
   133  <GitHub Actions URL 或 API 端点>
   134  
   135  根因分析：
   136  <分析过程>
   137  
   138  修复建议：
   139  <具体修复方案>
   140  
   141  相关代码：
   142  <文件路径:行号>
   143  ```
   144  
   145  ### 步骤 5：提出修复方案
   146  
   147  - 对于 regression 类型：给出具体代码修复
   148  - 对于 flaky 类型：说明判断依据，建议重跑或标记 flaky
   149  - 对于 environment 类型：说明配置修复方案
   150  - 对于 format 类型：运行 `gofmt -s -w .` 或修复 staticcheck 报告的问题
   151  
   152  ## 常见失败模式（本项目特有）
   153  
   154  | 失败类型 | 典型表现 | 修复方式 |
   155  |----------|----------|----------|
   156  | gofmt | "Files not formatted" | `gofmt -s -w .` |
   157  | staticcheck | SA/S/ST 开头的错误码 | 按 staticcheck 建议修复 |
   158  | examples 编译 | `go build ./examples/...` 失败 | 检查 examples 依赖的包是否有 breaking change |
   159  | 单元测试 | `FAIL` + 具体测试函数名 | 定位测试代码和被测代码 |
   160  | Windows/macOS | 平台相关路径、换行符问题 | 使用 `filepath.Join` 等跨平台写法 |
   161  
   162  ## 判断 flaky 的证据要求
   163  
   164  只有满足以下条件才能判定为 flaky：
   165  
   166  1. 同一测试在同一分支的最近 3+ 次运行中至少有 1 次通过
   167  2. 错误信息显示明确的基础设施问题（网络超时、资源不足等）
   168  3. 代码路径没有最近改动
   169  
   170  ```bash
   171  # 检查历史运行
   172  gh run list --repo qiniu/go-sdk --branch <branch> --workflow "Run Test Cases" --limit 10
   173  ```
   174  
   175  ## 禁止事项
   176  
   177  - 不要在没有证据的情况下说"可能是 flaky"
   178  - 不要只列出失败不给结论
   179  - 不要忽略任何一个失败
   180  
   181  ## 验收标准（统一）
   182  
   183  - 输入前提：参数与上下文可解析；缺省参数按 skill 默认值执行，并在输出中注明。
   184  - 产出要求：按 skill 约定的输出模板给出结果，并包含关键证据（命令、路径、链接或日志摘要）。
   185  - 通过判定：主流程步骤已完成且无阻塞；若有未完成项，必须明确标注影响范围与下一步。
   186  - 默认策略（非交互）：需要确认但用户未及时响应时，采用"推荐默认值/最小风险项"继续；需要交互选择时优先推荐项。
   187  - 阻塞升级：遇到权限、凭证、外部依赖缺失时立即停止该步骤，输出"阻塞点 + 已尝试 + 需要用户提供的信息"。
   188  
   189  ## 系统规范（AGENTS.md）
   190  
   191  执行本 skill 时同时遵守 `AGENTS.md` 中的系统规范；与本 skill 冲突时以本 skill 为准。