Explain Error 插件结合美团AI（Longcat） 解释 Jenkins 构建失败日志
项目简介
🤖 Explain Error 是一个 AI 驱动的 Jenkins 插件，能够自动解释构建失败原因，将复杂的日志转化为易读的分析报告。
核心特性
- ✅ 自动分析：构建失败时自动触发 AI 分析
- 🎯 精准定位：快速识别编译错误、测试失败、部署问题等
- 🔌 多模型支持：支持 OpenAI、Google Gemini、Ollama 及兼容 OpenAI API 的服务（如美团 Longcat、DeepSeek 等）
- 🚀 Pipeline 集成：可在 Pipeline 中使用
explainError()步骤 - 🌐 离线部署：支持本地 Ollama 模型，适合内网环境
使用场景
厌倦了翻阅冗长的 Jenkins 日志来查找问题？Explain Error 插件利用 AI 自动解释作业和流水线失败原因，节省时间并帮助你更快修复问题。
项目链接
- Jenkins 插件页：https://plugins.jenkins.io/explain-error/
- 项目源码（GitHub）：https://github.com/jenkinsci/explain-error-plugin
- 视频演示：YouTube Demo – 观看实际操作演示
前置要求
- Jenkins 版本：≥ 2.479.3（推荐使用 LTS 版本）
- AI 服务：需要以下任一服务的 API 密钥
提示：我这边使用美团的Longcat，毕竟能白嫖！
安装步骤
方式一：通过插件管理器安装（推荐）
- 进入
Jenkins 管理→插件管理→可选插件 - 搜索
Explain Error - 勾选并点击
安装 - 安装完成后重启 Jenkins
方式二：手动安装
- 从 Jenkins 插件中心 下载最新的
.hpi文件 - 进入
Jenkins 管理→插件管理→高级 - 在 “上传插件” 区域选择下载的
.hpi文件 - 点击
上传并重启 Jenkins
配置指南
全局配置
进入 Jenkins 管理 → 系统配置 → 找到 Explain Error Plugin Configuration 区域
配置项说明
| 配置项 | 说明 | 默认值 |
|---|---|---|
| Enable AI Error Explanation | 启用/禁用插件功能 | ✅ 已启用 |
| AI Provider | 选择 AI 提供商 | OpenAI |
| API Key | AI 服务的 API 密钥 | 从对应平台获取 |
| API URL | AI 服务端点地址 | 官方 API 留空；自定义服务需填写完整 URL |
| AI Model | 使用的模型名称 | 必填，根据提供商选择 |
在 Explain Error Plugin Configuration 中填写以下信息：
# 配置示例
AI Provider: OpenAI # Longcat 兼容 OpenAI API
API Key: <你的 Longcat API Key>
API URL: <Longcat API 地址> # 从接口文档获取
AI Model: <模型名称>
配置说明：
– Longcat 使用 OpenAI 兼容接口，因此 AI Provider 选择 OpenAI
– API URL 必须填写完整的 Longcat 接口地址（参考官方文档）
– 模型名称根据 Longcat 提供的模型列表选择
提示：插件现已支持中文反馈！在 Pipeline 中使用
language: 'Chinese'参数即可获得中文分析结果。
测试配置
配置完成后，点击 Test Configuration 按钮验证设置是否正确。
接入美团 Longcat AI 模型（免费额度）
环境说明
- AI 模型：美团 Longcat
- Token 额度：每日 500 万 Token（免费）
- 申请地址：https://longcat.chat/
- 最新模型介绍文章: https://tech.meituan.com/2026/01/20/longcat-flash-thinking-2601.html
申请步骤
- 访问 https://longcat.chat/
- 注册并登录账号
- 在控制台获取 API Key 和接口文档
使用方法
方法一：Pipeline 步骤（推荐）
在 Pipeline 的 post 块中使用 explainError() 步骤：
基础用法
pipeline {
agent any
stages {
stage('Build') {
steps {
// 构建步骤
sh 'mvn clean package'
}
}
}
post {
failure {
// 构建失败时自动触发 AI 分析
explainError()
}
}
}
高级用法（带参数）
post {
failure {
explainError(
maxLogLines: 1000, // 最多分析 1000 行日志（默认：全部）
logPattern: '.*ERROR.*', // 只分析包含 ERROR 的日志行（正则表达式）
language: '中文' // 设置分析结果语言为中文（默认：English）
)
}
}
可选参数说明
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
maxLogLines |
Integer | 限制分析的日志行数 | 全部 |
logPattern |
String | 正则表达式，只分析匹配的日志行 | 无 |
language |
String | 分析结果语言（支持：English、中文） |
English |
中文分析示例
post {
failure {
// 使用中文分析，并限制日志行数
explainError(
maxLogLines: 500,
language: '中文'
)
}
}
结合企业微信通知
post {
failure {
// 先执行 AI 分析（中文输出）
explainError(language: '中文')
// 再发送企业微信通知
script {
withCredentials([string(credentialsId: "${env.WEBHOOK_URL}", variable: 'url')]) {
def utils = new utils()
def msg = utils.buildMessage(this, 'failure', false)
sh """
curl -s '${url}' \
-H 'Content-Type: application/json' \
-d '{
"msgtype": "markdown",
"markdown": {
"content": "${msg.replaceAll("\n", "\\\\n")}"
}
}'
"""
}
}
}
}
方法二：手动控制台分析
适用于 Freestyle、Declarative 或任何类型的 Job。
- 打开失败构建的控制台输出页面
- 点击顶部的 Explain Error 按钮
- 等待 AI 分析完成
- 查看按钮下方显示的分析结果
提示：分析结果会直接显示在构建页面的侧边栏中，无需跳转到其他页面。
Token 使用优化建议
针对美团 Longcat 每日 500 万 Token 额度，建议采取以下策略：
1. 日志截取策略
// 只分析最后 500 行日志，使用中文输出
explainError(
maxLogLines: 500,
language: '中文'
)
优势：
– 减少 Token 消耗
– 加快分析速度
– 关键错误通常在日志末尾
– 中文输出更易理解
2. 日志过滤策略
// 只分析包含 ERROR 或 FAILED 的日志行，使用中文输出
explainError(
logPattern: '.*(ERROR|FAILED).*',
language: '中文'
)
优势：
– 精准定位错误信息
– 大幅降低 Token 使用量
– 提高分析准确性
– 中文反馈更友好
3. 综合优化策略（推荐）
post {
failure {
// 结合日志截取和过滤，使用中文输出
explainError(
maxLogLines: 500,
logPattern: '.*(ERROR|FAILED|Exception).*',
language: '中文'
)
}
}
优势：
– 最大化 Token 利用效率
– 快速定位关键错误
– 中文分析结果便于团队协作
