# oc-aicrash-skill

**Repository Path**: OpenCloudOS/oc-aicrash-skill

## Basic Information

- **Project Name**: oc-aicrash-skill
- **Description**: oc-aicrash-skill 是一个结合 AI 与 Linux crash 工具的自动化分析框架，用来定位 vmcore 产生的内核 crash 根因，并关联上游内核/厂商补丁与已知 bug 报告。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-04-17
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OC-AiCrash-Skill

[![License](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Linux-green.svg)](https://www.kernel.org/)

> ⚠️ **平台要求**：OC-AiCrash-Skill 仅支持 **Linux** 环境。依赖的 `crash` 工具和 vmcore 分析功能均为 Linux 专用，不支持 macOS、Windows 等其他操作系统。

OC-AiCrash-Skill 是一个结合 AI 与 Linux `crash` 工具的自动化分析框架，用来定位 vmcore 产生的内核 crash 根因，并关联上游内核/厂商补丁与已知 bug 报告。默认通过 Azure OpenAI Chat Completions 提供分析推理能力，可选回退到标准 OpenAI 接口。

同时，OC-AiCrash-Skill 也是一个 **CodeBuddy / Claude Code 的 Skill**（技能插件），通过 SKILL.md 定义完整的 vmcore 分析工作流，并通过 MCP Server 将 crash 分析能力暴露为标准化工具供 AI IDE 直接调用。

## 功能概览

- **Skill 自动加载**：将项目安装为 Skill 后，AI IDE 会根据用户意图自动加载 crash-expert 技能，无需手动触发。Skill 首次使用时会自动检测并完成 MCP 包安装和 Server 注册。
- **MCP Server**：基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的标准 MCP Server，可直接被 CodeBuddy / Claude Code / Claude Desktop 调用，将 crash 分析能力暴露为 9 个 MCP tools。
- **REST Server**：基于 FastAPI 的 HTTP 服务端，提供 REST API 管理 `crash` 会话与命令执行。
- **AI Orchestrator**：与 OpenAI 聊天模型交互，由模型规划下一步要执行的 `crash` 命令与分析思路。
- **Crash Session Manager**：通过 `pexpect` 驱动 `crash` CLI，对 vmcore + vmlinux 进行交互式分析。自动记录所有命令到 JSONL 日志，支持报告生成时通过 `@cmd[]` 引用填充。
- **Knowledge Base**：本地知识库 + Red Hat Customer Portal KB 双重检索模块，通过关键字匹配相关的 bug 报告或补丁说明。
- **HTML 报告生成器**：Markdown + 命令引用 → HTML 报告，通过 `@cmd[]` 引用自动填充 crash 命令输出，节省约 40-50% AI 输出 token。
- **CLI 工作流**：通过 `typer` 提供 `analyze`、`server`、`mcp` 子命令，一键发起 AI 指导的分析流程。

## 快速开始

### 方式一：一键安装（推荐）

```bash
# 第 1 步：配置环境变量（可选但推荐）
# 复制配置模板并根据需要填写
cp .env.example .env

# 第 2 步：安装 Skill —— 根据你使用的 AI IDE 拷贝到对应目录
# 如果使用 CodeBuddy
cp -a . ~/.codebuddy/skills/oc-aicrash-skill/
# 如果使用 Claude Code
cp -a . ~/.claude/skills/oc-aicrash-skill/

# 第 3 步（可选）：手动运行自动安装脚本预装 MCP 包 + 注册 MCP Server
bash scripts/setup.sh
# 也可跳过第 3 步，当 Skill 首次被使用激活时会自动完成 MCP 安装注册

# 直接在 IDE/CLI 里告诉 AI 需要分析的 vmcore 和 debuginfo 包路径及内核代码路径(可选)让 AI 开始分析，例如：
# 分析vmcore /path/to/vmcore /path/to/vmlinux  /path/to/kernel-src
```

### 方式二：手动安装（进阶）

**第 1 步：安装 Skill 文件**

根据你使用的 AI IDE，将项目拷贝到对应的 skills 目录：

```bash
# 如果使用 CodeBuddy
cp -a . ~/.codebuddy/skills/oc-aicrash-skill/

# 如果使用 Claude Code
cp -a . ~/.claude/skills/oc-aicrash-skill/
```

**第 2 步：安装 MCP Python 包**

```bash
pip install -e .[cli]
```

安装完成后，MCP Server 可通过以下命令启动：

```bash
python3 -m aicrasher.mcp_server
# 或通过 CLI 入口点
aicrasher-mcp
```


**第 3 步：注册 MCP Server**

```bash
# CodeBuddy
codebuddy mcp add -s user aicrasher -- python3 -m aicrasher.mcp_server

# Claude Code
claude mcp add aicrasher -- python3 -m aicrasher.mcp_server
```

或使用 IDE 配置：

```json
{
  "mcpServers": {
    "aicrasher": {
      "command": "python3",
      "args": ["-m", "aicrasher.mcp_server"],
      "env": {
        "CRASH_BINARY": "/usr/bin/crash",
        "KNOWLEDGE_BASE_PATHS": "/data/kb/vendor1:/data/kb/vendor2"
      }
    }
  }
}
```


### CLI 工具判定优先级

`setup.sh` 脚本和 `SKILL.md` 中的自动安装逻辑在检测IDE/CLI 工具时，遵循以下优先级顺序：

| 优先级 | 条件 | MCP Server 注册命令 | Skill 安装目录 |
|--------|------|---------------------|---------------|
| 1 | 系统存在 `codebuddy` 命令 | `codebuddy mcp add -s user aicrasher -- python3 -m aicrasher.mcp_server` | `~/.codebuddy/skills/oc-aicrash-skill/` |
| 2 | `codebuddy` 不存在但 `claude` 存在 | `claude mcp add aicrasher -- python3 -m aicrasher.mcp_server` | `~/.claude/skills/oc-aicrash-skill/` |
| 3 | 都不存在 | 提示手动注册 | 默认 `~/.codebuddy/skills/oc-aicrash-skill/` |

## MCP Tools

OC-AiCrash-Skill 实现了标准 [Model Context Protocol](https://modelcontextprotocol.io/)，注册方式详见上方「方式二 → 第 3 步」。

连接成功后，可使用以下 9 个 MCP tools：

| Tool | 说明 |
|------|------|
| `analyze_crash` | 一键创建 crash 会话 + 收集基线诊断信息（**分析入口点**） |
| `create_crash_session` | 创建 crash 调试会话，自动记录命令日志到 JSONL |
| `run_crash_command` | 在会话中执行单条 crash CLI 命令 |
| `run_crash_commands` | 在会话中批量执行多条 crash CLI 命令 |
| `collect_baseline` | 收集基线诊断信息（sys, bt, log \| tail -n 100） |
| `export_command_log` | 导出会话中所有已执行命令的完整历史到 JSONL 文件 |
| `close_crash_session` | 关闭并清理会话 |
| `search_knowledge_base` | 搜索本地知识库 + Red Hat Customer Portal KB |
| `list_sessions` | 列出所有活跃会话 |

## 项目结构

```
oc-aicrash-skill/                        # 项目根目录 & Skill 根目录
├── SKILL.md                             # Skill 主定义文件（含自动安装检查 + 完整分析工作流）
├── pyproject.toml                       # Python 项目配置（含 MCP 依赖和 CLI 入口）
├── .env.example                         # 环境变量配置模板
├── src/
│   └── aicrasher/                       # MCP Server 核心代码
│       ├── __init__.py                  # 包导出
│       ├── mcp_server.py               # 标准 MCP Server（FastMCP，9 个工具）
│       ├── rest_server.py              # FastAPI REST Server（HTTP API）
│       ├── crash_session.py            # crash CLI 会话管理（pexpect + JSONL 自动日志）
│       ├── ai_orchestrator.py          # OpenAI / Azure OpenAI 交互与指令规划
│       ├── knowledge_base.py           # 本地 + Red Hat KB 双重知识库检索
│       ├── config.py                   # Pydantic 配置加载
│       └── main.py                     # Typer CLI（analyze / server / mcp 子命令）
├── scripts/
│   ├── setup.sh                        # 一键安装脚本（MCP 包 + Server 注册 + Skill 安装）
│   └── crash_report_generator.py       # HTML 报告生成器（Markdown + @cmd[] 命令引用 → HTML）
└── references/                          # 参考文档根目录
    ├── phases/                          # 阶段详细步骤文件
    │   ├── mcp_tools_rules.md          # MCP 工具使用铁律
    │   ├── phase0_setup.md             # 阶段零：环境检查步骤
    │   ├── phase4_community_fix.md     # 阶段四：社区 fix commit 查找步骤
    │   ├── phase5_mitigation.md        # 阶段五：缓解措施分析步骤
    │   └── phase6_report.md            # 阶段六：报告生成步骤
    └── reference/                       # 场景分析与命令参考
        ├── crash_commands.md            # Crash 命令速查参考
        ├── scenario_analysis.md         # 场景分析指南总览
        ├── scenario_bug_null_ptr.md     # BUG_ON / NULL 指针 / 异常地址场景
        ├── scenario_hung_task.md        # Hung Task 场景
        ├── scenario_lockup.md           # Soft Lockup / Hard Lockup 场景
        ├── scenario_oom_deadlock.md     # OOM 内存耗尽场景
        └── scenario_sysrq_virsh.md      # SysRq 触发 / virsh dump 场景
```

### 关键设计

- **`SKILL.md`**：Skill 主定义文件，定义了 AI 在 IDE 中如何使用 OC-AiCrash-Skill 进行 vmcore 分析的完整六阶段工作流。包含前置环境自动检查、MCP 工具使用铁律、标准分析流程、报告生成规范等。
- **`src/aicrasher/`**：MCP Server 核心代码，通过 `pip install -e .[cli]` 安装为 Python 包。Skill 的运行依赖此包提供的 MCP 工具（`analyze_crash`、`run_crash_command` 等）。
- **`scripts/`**：脚本目录，包含一键安装脚本 `setup.sh` 和报告生成器 `crash_report_generator.py`。
- **`references/`**：参考文档目录，包含阶段详细步骤文件（`phases/`）和 Crash 命令速查及场景分析指南（`reference/`），供 Skill 运行时加载。
- **依赖关系**：`Skill (SKILL.md)` → 依赖 → `MCP Server (src/aicrasher/)` → 依赖 → `crash CLI 工具` + `vmcore/vmlinux 文件`
- **命令日志自动化**：MCP Server 自动记录所有 crash 命令到 JSONL，报告生成时通过 `@cmd[]` 引用填充，节省约 40-50% AI 输出 token。

## 扩展建议

- 将 `KnowledgeBase` 换成向量检索或整合现网 KB API。
- 在 AI 模型响应中加入结构化 checklist，确保覆盖 dump 分析的关键步骤。
- 结合 CI/CD，在新补丁或新内核版本上线前自动跑回归 dump 分析。



## 可选：

**单纯使用 SKILL + MCP 的话，跳过这部分内容即可。**

仅在使用 CLI 的 `analyze` 子命令（AI 自动驱动分析）时才需要配置：

在项目根目录创建 `.env`（参考 `.env.example`）并设置：

```ini
# Azure OpenAI credentials
AZURE_OPENAI_API_KEY=azure-key-here
AZURE_OPENAI_ENDPOINT=https://<resource-name>.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-15-preview
AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini

# Optional overrides
OPENAI_API_KEY=  # 仅在直接调用 OpenAI 公有云时使用
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=

# crash & knowledge base
CRASH_BINARY=/usr/bin/crash
CRASH_OUTPUT_MAX_CHARS=16384    # 限制单条 crash 命令返回给 AI 的输出，默认 16K
CRASH_BATCH_OUTPUT_MAX_CHARS=32768  # 限制批量命令总输出，默认 32K
KNOWLEDGE_BASE_PATHS=/data/kb/vendor1:/data/kb/vendor2

# Optional Red Hat Customer Portal KB search
REDHAT_KB_BASE_URL=https://access.redhat.com/hydra/rest/search/platform/kbase
REDHAT_KB_TIMEOUT_SECONDS=10
REDHAT_KB_MAX_RESULTS=5
```

## 启动服务

**REST Server（HTTP API）**

```bash
python -m aicrasher.main server --host 0.0.0.0 --port 8000
```

**CLI 自动分析**

```bash
python -m aicrasher.main analyze /path/to/vmcore /path/to/vmlinux --server-url http://127.0.0.1:8000
```

CLI 将自动：
- 建立 `crash` 会话并收集初始诊断信息
- 将最新的命令输出发送给 AI 模型，请求下一批命令
- 根据 AI 计划驱动 `crash` 执行，循环直至获得根因结论或达到轮次上限
- 在本地知识库和 Red Hat KB 中检索相关 bug 报告 / 修复补丁

## 注意事项
- 使用 CLI `analyze` 模式时 OpenAI API 调用会产生费用，请设置合理的 `MAX_AI_ROUNDS` 与模型选择。纯 MCP 模式下由 AI IDE 自身的模型驱动分析，不额外消耗 OpenAI API。

## 贡献

我们欢迎任何形式的贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与项目开发。

在参与本项目前，请阅读我们的 [行为准则](CODE_OF_CONDUCT.md)。

## 许可证

本项目采用 [GPL-2.0-only](LICENSE) 许可证。

## 致谢

- [crash](https://github.com/crash-utility/crash) - Linux 内核崩溃分析工具
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - AI 工具协议标准
- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP 服务器框架
- [Red Hat Customer Portal](https://access.redhat.com/) - 知识库检索 API