CNB 文档

简体中文

English

简体中文

English

外观

失败流水线 AI 分析并通知

复制页面

1162 字约 4 分钟

流水线失败后，人工去翻日志定位问题成本较高。本示例展示一条「失败 → AI 总结 → 群通知」的自动化链路：

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

为什么在 failStages 中用 AI 分析

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

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

完整示例

.cnb.yml：

.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 中。密钥仓库文件示例如下：

密钥仓库 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 内为空
© 2026 cnb.cool