---
url: /zh/build/showcase/ci-fail-ai-analyze.md
description: >
  介绍如何利用 failStages + npc:go + tencentcom/wecom-message， 在流水线失败时自动让 AI
  总结根因、给出解决方案，并把结果发到企业微信群。
---
流水线失败后，人工去翻日志定位问题成本较高。本示例展示一条「**失败 → AI 总结 → 群通知**」的自动化链路：

1. 正常 `stages` 失败后，触发 `failStages`
2. `failStages` 内依次执行：把失败上下文整理成 Markdown →
   调用 `npc:go` 让 AI 给出根因和方案 → 读取该 Markdown 发到企微群

## 为什么在 failStages 中用 AI 分析

相比另起一条修复流水线或手动排查，`failStages` + AI 有两个天然优势：

* **保留失败现场**：`failStages` 与 `stages` 共享同一工作区，
  AI 触手可及的是真实的失败现场——构建产物、中间文件、依赖安装残留、
  环境变量等原封不动地留在原地，无需在修复流水线里费力复现
* **零等待、零交互**：失败 → AI 分析 → 方案通知全程自动化。
  不必重新触发构建、等容器启动、SSH 登录进去 debug；
  收到企微通知时，报告已经写好了根因和可执行的操作步骤，直接照做即可

## 完整示例

`.cnb.yml`：

````yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: test
          # 故意把 echo 写成 echo1，触发 failStages 用于演示
          script: echo1 1
      failStages:
        # 1) 把失败上下文整理成结构化 Markdown，给 AI 当输入
        - name: 准备失败上下文
          script: |
            {
              echo "## 失败概览"
              echo ""
              echo "| 项目 | 内容 |"
              echo "| --- | --- |"
              echo "| 失败阶段 | $CNB_BUILD_FAILED_STAGE_NAME |"
              echo "| 失败原因 | \`$CNB_BUILD_FAILED_MSG\` |"
              echo "| 触发分支 | $CNB_BRANCH |"
              echo "| 提交 | $CNB_COMMIT_SHORT — $CNB_COMMIT_MESSAGE_TITLE |"
              echo "| 触发人 | $CNB_BUILD_USER |"
              echo "| 构建 ID | $CNB_BUILD_ID |"
              echo "| 构建日志 | $CNB_BUILD_WEB_URL |"
              echo ""
              echo "## 原始错误信息"
              echo '```'
              echo "$CNB_BUILD_FAILED_MSG"
              echo '```'
            } > _fail_ci_.md
        # 2) 让 AI 读上下文，给出根因 + 解决方案，追加到同一文件
        - name: AI 分析失败
          type: npc:go
          options:
            systemPrompt: |
              你是一个资深 DevOps 工程师，擅长分析 CI/CD 流水线失败。
              阅读 _fail_ci_.md 中已写入的失败上下文（失败阶段、错误信息、构建日志链接、提交信息），
              结合常见失败模式（命令拼写错误、依赖缺失、权限不足、路径错误、网络超时、磁盘满、配置错误等），
              给出根因 + 可执行的具体解决方案。
            userPrompt: |
              请阅读 _fail_ci_.md，将以下内容用 Markdown 追加到文件末尾：
              ## 根因分析
              ## 解决方案
              ## 具体操作（给出命令或 yaml diff）
              ## 影响范围
        # 3) 用 AI 写好的 Markdown 文件发到企微群
        - name: 通知到企微群
          image: tencentcom/wecom-message
          imports: https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/wework.yml
          settings:
            robot: ${WECOM_ROBOT}
            msgType: markdown_v2
            fromFile: _fail_ci_.md
````

`WECOM_ROBOT` 是企业微信群机器人的 Webhook 地址。示例通过 `imports`
引入密钥仓库中的 `wework.yml` 文件，在该文件中用 `env` 注入 `WECOM_ROBOT`，
避免 Webhook 地址直接写在 `.cnb.yml` 中。密钥仓库文件示例如下：

```yaml title="密钥仓库 wework.yml"
env:
  WECOM_ROBOT: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
```

## 实际效果

构建失败后，企业微信群会收到 AI 生成的完整报告：

* **失败概览** + **原始错误** —— 由「准备失败上下文」stage 写入，
  含失败阶段、错误信息、构建日志链接、commit 等背景信息
* **根因分析** —— AI 从直接原因、根本原因、触发条件、常见模式
  等多个维度分析，并附上判断依据
* **解决方案 + 具体操作** —— 可执行的命令或 yaml diff，
  收到通知后直接照做即可

报告由「人工脚本写概览」+「AI 追加分析」两段组成，最终 `通知到企微群`
阶段用 `fromFile` 一次性读取，发出一条完整的事故报告消息。

## 关键设计点

* **把「整理上下文」拆成独立 stage**：直接把变量拼到 `userPrompt`
  里，shell 转义容易踩坑（含引号、换行、反引号的变量可能截断或注入 prompt）。
  先落盘成文件再让 `npc:go` 读，**shell 和 prompt 的边界更清晰**
* **AI 输出追加到同一文件**：`failStages` 内三个 stage 串行执行、
  共享工作区，最终通知阶段用 `fromFile: _fail_ci_.md` 一次性读取完整报告
* **推荐 `msgType: markdown_v2`**：旧版 `markdown` 对嵌套表格、代码块
  渲染不稳定，容易降级为纯文本。`npc:go` 需要 Docker 环境，
  若流水线已配 `docker.image` 则会复用

## 注意事项

* 若通知阶段自身报错，构建仍标记为失败但可能收不到消息，建议先 dry-run 验证联通
* `npc:go` 消耗 LLM 配额，频繁失败的项目可考虑加频控（如同一 commit 只通知一次）
* `$CNB_BUILD_FAILED_MSG` 等构建变量仅 `failStages` 内可用，正常 stages 内为空