# aiops-assistant

**Repository Path**: wanzehua/aiops-assistant

## Basic Information

- **Project Name**: aiops-assistant
- **Description**: 基于MCP协议的多Agent协作数据分析平台（LangGraph+4个MCP Server+ReactFlow可视化）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自动化数据分析 Agent

基于 MCP 协议的多 Agent 协作平台，用自然语言做数据分析。

**一句话定位**：问一句话，出一份带图表的分析报告。

## 架构

```
用户自然语言提问
  │
  ▼
LangGraph 多 Agent 编排
  Planner → Executor (ReAct) → Reporter
                │
          MCP Client (stdio)
                │ MCP 协议
    ┌───────────┼───────────┐
    ▼           ▼           ▼
 Data MCP   Analysis MCP  Chart MCP
 (CSV/SQLite) (pandas)   (matplotlib)
    │           │           │
    └───────────┴──── Report MCP ──→ HTML 报告
```

## 功能亮点

- **4 个 MCP Server、22 个工具**：数据获取 / 统计分析 / 可视化 / 报告生成，通过 MCP 标准协议实现插件化工具调用
- **3 Agent 协作**：Planner（规划）→ Executor（ReAct 多轮执行）→ Reporter（报告生成）
- **多数据源**：CSV 文件、SQLite 数据库、股票（新浪 + AKShare 三级 fallback）、基金净值、宏观经济数据
- **data_ref 引用传递**：大数据集通过 pickle 落盘引用，避免在 LLM 上下文中传输原始数据
- **SSE 实时推送 + ReactFlow 流程可视化**：Web UI 实时展示 Agent 执行过程
- **多格式报告导出**：Markdown / PDF / Excel，满足不同汇报场景
- **多轮对话**：支持会话管理，可基于历史对话继续追问

## 快速开始

### 1. 后端 API

```powershell
# 安装依赖
pip install -r requirements.txt

# 复制环境变量（填入 LLM_API_KEY）
Copy-Item .env.example .env

# 准备数据（CSV → SQLite）
python scripts\prepare_data.py

# 启动后端服务
uvicorn src.api.app:app --reload --port 8001
```

后端启动后访问 http://127.0.0.1:8001/api/health 检查健康状态。

### 2. Web UI（可选）

```powershell
cd aiops-web

# 安装前端依赖
npm install

# 启动前端开发服务器
npm run dev
```

打开浏览器访问 http://localhost:3000 即可使用 Web UI。

### 3. 命令行模式（可选）

```powershell
# 跑 Agent（需 LLM Key）
python -m src.aiops "分析 2026 上半年各区域的销售总额对比"
```

运行后输出：
- 控制台打印 Planner 计划、Executor ReAct 轮次、工具调用、结论
- `data/output/charts/` 生成图表 PNG
- `data/output/reports/` 生成 HTML 报告（含内嵌图表，浏览器直接打开）

## 5 个预设场景

Web UI 内置 5 个预设问题，一键验证全流程：

| 编号 | 预设问题 | 涉及能力 |
|------|---------|---------|
| Q1 | 分析 2026 上半年各区域的销售总额对比 | SQL 查询 + 柱状图 + 基础报告 |
| Q2 | 分析 2025 下半年哪些品类销售下滑了，找出原因 | ReAct 多轮归因 + 数据下钻 |
| Q3 | 对比比亚迪和特斯拉 2024 年的股价走势 | 外部 API + 三级 fallback + 时序图 |
| Q4 | 分析易方达蓝筹精选基金 005827 近一年的净值走势 | 基金数据获取 + 净值曲线 |
| Q5 | 中国 GDP 和 CPI 走势相关性分析 | 宏观数据 + 双轴图 + 相关性分析 |

所有 5 个场景均已端到端验证通过 ✅

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/analyze` | 提交分析任务 |
| GET | `/api/analyze/stream/{task_id}` | SSE 流式推送执行过程 |
| GET | `/api/task/{task_id}` | 查询任务状态 |
| GET | `/api/tasks` | 历史任务列表 |
| GET | `/api/report/{task_id}` | 获取报告 HTML |
| GET | `/api/export/{task_id}` | 导出报告（PDF/Excel） |
| POST | `/api/upload` | 上传 CSV/Excel 文件 |
| GET | `/api/sessions` | 获取会话列表 |
| GET | `/api/conversation/{session_id}` | 获取对话历史 |
| GET | `/api/presets` | 获取预设问题列表 |
| GET | `/api/health` | 健康检查 |

## 目录结构

```
aiops-assistant/
├── aiops-web/               Web 前端（Next.js 14 + React 18）
│   ├── app/                  页面路由（App Router）
│   ├── components/           UI 组件（10 个）
│   ├── lib/                  API/SSE/类型封装
│   └── package.json
│
├── data/                    数据层
│   ├── raw/                   原始 CSV（Superstore 数据集 + 股票/基金/宏观）
│   ├── db/                    SQLite 数据库（analytics.db）
│   ├── temp/                  临时数据（data_ref pickle 文件）
│   └── output/                生成结果
│       ├── charts/            图表 PNG
│       └── reports/           HTML 报告
│
├── mcp_servers/             MCP 工具层（4 个独立 Server，22 个工具）
│   ├── data/                  数据获取（query_data / read_csv / fetch_stock_data ...）
│   ├── analysis/              统计分析（calc_growth / compare_groups / correlation ...）
│   ├── chart/                 可视化（bar / line / pie / scatter / heatmap）
│   ├── report/                报告生成（generate_report / export_pdf / export_excel）
│   └── shared/                data_ref 共享存储（pickle 落盘）
│
├── src/
│   ├── aiops/                 Agent 编排层
│   │   ├── agents/              Planner / Executor (ReAct) / Reporter
│   │   ├── graph.py             LangGraph 工作流（条件边编排）
│   │   ├── state.py             状态定义（AgentState）
│   │   ├── mcp_client.py        MCP 客户端（按工具名路由到对应 Server）
│   │   └── db.py                SQLite 任务状态持久化
│   └── api/                   FastAPI 后端
│       └── app.py              REST API + SSE 服务
│
├── scripts/                 脚本
│   ├── prepare_data.py        数据准备（CSV → SQLite）
│   ├── test_mcp.py            MCP 端到端测试
│   └── test_llm.py            LLM 连通性测试
│
├── docs/                    文档
│   └── 开发方案.md            完整开发方案（架构设计 / 面试要点）
│
├── .env.example             环境变量模板
├── requirements.txt         依赖
└── README.md
```

## 技术栈

### 后端

| 层 | 技术 | 说明 |
|---|---|---|
| Agent 编排 | LangGraph | 多 Agent 状态机 + 条件边 |
| MCP | mcp 1.x (FastMCP) | 4 个独立 Server，stdio 通信 |
| LLM | DeepSeek-V3 | 硅基流动 / DeepSeek 兼容接口 |
| 数据处理 | pandas + numpy | 统计分析核心 |
| 数据库 | SQLite | 业务数据 + 任务状态 |
| 可视化 | matplotlib | PNG 图表，支持中文 |
| 报告 | Jinja2 + HTML | 模板化报告，base64 内嵌图表 |
| Web 框架 | FastAPI + SSE | REST API + 流式推送 |
| 外部 API | AKShare + 新浪财经 | 股票/基金/宏观数据 |

### 前端

| 层 | 技术 | 说明 |
|---|---|---|
| 框架 | Next.js 14 | App Router + Server Components |
| UI | React 18 + TailwindCSS | 深色主题，渐变玻璃拟态 |
| 可视化 | ReactFlow (@xyflow/react) | Agent 执行流程图 |
| 图表 | ECharts | 报告内嵌图表渲染 |
| 通信 | SSE (EventSource) | 实时接收 Agent 执行事件 |
| 图标 | Lucide React | 统一图标库 |

## 环境变量

```env
# ===== LLM 配置 =====
LLM_PROVIDER=deepseek
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# ===== 数据库 =====
DATABASE_PATH=data/db/analytics.db

# ===== 数据目录 =====
DATA_RAW_DIR=data/raw
DATA_OUTPUT_DIR=data/output
DATA_TEMP_DIR=data/temp

# ===== Agent 配置 =====
MAX_REACT_STEPS=5

# ===== 日志 =====
LOG_LEVEL=INFO
```

## 测试

```powershell
# MCP 工具链端到端测试
python scripts\test_mcp.py

# LLM 连通性测试
python scripts\test_llm.py

# 5 个预设场景全量验证
python test_5_scenarios.py
```

## 报告导出

- **Markdown**：默认格式，所有场景均支持
- **PDF**：基于 weasyprint（优先）或 matplotlib PdfPages 生成，支持中文字体
- **Excel**：基于 openpyxl，每个 Planner 步骤一个 Sheet，含封面页

访问 `GET /api/export/{task_id}?format=pdf` 或 `?format=excel` 下载。