# data-analysis

> 数据分析技能，提供结构化的数据查询、统计分析和报告生成工作流。当用户需要查询数据库、进行数据统计分析、生成分析报告时使用。按规范输出原始数据、计算结果、Markdown报告和HTML可视化报告。

- Author: shanggqm
- Repository: shanggqm/data-insight-agent
- Version: 20260106170949
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/shanggqm/data-insight-agent
- Web: https://mule.run/skillshub/@@shanggqm/data-insight-agent~data-analysis:20260106170949

---

---
name: data-analysis
description: 数据分析技能，提供结构化的数据查询、统计分析和报告生成工作流。当用户需要查询数据库、进行数据统计分析、生成分析报告时使用。按规范输出原始数据、计算结果、Markdown报告和HTML可视化报告。
---

# 数据分析技能

标准化数据分析工作流，确保分析高效、结果可靠、输出规范。

## 激活条件

- 用户需要查询数据库并分析数据
- 用户需要生成数据分析报告
- 涉及"数据分析"、"统计"、"报告"、"洞察"等关键词

## 核心约束

### 1. 时区处理

**首次分析时确认数据库时区设定**，常见情况：

| 存储时区 | 查询处理       | 展示处理       |
| -------- | -------------- | -------------- |
| UTC      | 查询条件转 UTC | 结果转本地时区 |
| 本地时区 | 直接使用       | 直接展示       |
| 时间戳   | 按需转换       | 转本地时区     |

确认后记录到对应的 schema 文件中，后续分析直接参考。

### 2. 输出规范

```
{workspace}/analysis-output/{topic}_{YYYYMMDD_HHmmss}/
├── raw_data/           # 原始查询结果（仅复杂场景）
├── processed_data/     # 计算后的分析数据（JSON格式，供HTML读取）
│   └── charts_data.json
├── report.md           # Markdown 报告
└── report.html         # 可视化报告（幻灯片样式）
```

### 3. 数据处理原则

- **禁止**将大量原始数据读入对话上下文
- **优先**通过 SQL 聚合直接得出统计结果
- **仅当**数据量大或查询复杂时，才落地本地用代码处理

## 工作流程

### Step 1: 需求理解与 Schema 获取

1. 识别分析主题、时间范围、关注维度
2. 查看 `schemas/` 是否有对应表结构，无则通过工具获取并保存
3. 确定查询范围：哪些表、哪些字段、什么条件

**Schema 文件**: `schemas/{source}_{name}.md`

### Step 2: 设计分析方案

根据数据特点选择分析维度（参考 `references/analysis_perspectives.md`）：

- **描述性分析**：规模、分布、集中趋势、离散程度
- **时序分析**：趋势、周期、同环比
- **对比分析**：分群、分类、交叉对比
- **关联分析**：相关性、因果推断
- **异常分析**：离群值、突变点

输出简要分析方案后再执行查询。

### Step 3: 数据查询与计算

**可用工具参考 `dbtool/README.md`**，根据用户指定或默认使用 MySQL。

#### 策略选择

**简单场景（优先）**：直接用 SQL 聚合

```sql
-- 通过 GROUP BY、COUNT、SUM、AVG 等直接得出统计结果
-- 多个统计需求可并行发起多条查询
SELECT DATE(created_at) as date, COUNT(*) as count FROM table GROUP BY date;
```

**复杂场景（降级）**：当遇到以下情况时，才落地本地处理

- 查询超时
- 需要跨表复杂计算
- 数据量过大无法一次返回
- SQL 难以表达的统计逻辑

```
1. 查询原始数据保存到 raw_data/
2. 在输出目录编写 Node.js 脚本处理
3. 结果保存到 processed_data/charts_data.json
```

### Step 4: 生成报告

**Markdown 报告**（参考 `templates/report_template.md`）：

- 执行摘要：核心发现 + 关键指标
- 详细分析：按维度展开
- 洞察建议：结论 + 行动项
- 附录：数据说明 + 计算口径

**HTML 幻灯片报告**（参考 `templates/visualization_template.html`）：

技术栈：

- **Reveal.js**：幻灯片框架，支持键盘翻页、过渡动画、演讲者模式（按 S 键）
- **Tailwind CSS**：原子化 CSS，直接用类名布局
- **ECharts**：图表引擎，暗金色主题
- **Animate.css**：元素入场动画（配合 fragment）
- **Remix Icon**：图标库

设计规范：

- 暗金色主题（#0f0f1a 背景 + #d4af37 金色）
- 每页一个观点 + 图表 + 洞察说明
- **数据必须从 `processed_data/charts_data.json` 读取，禁止硬编码**

### Step 5: 质量检查

- [ ] 时区处理正确
- [ ] 数据可追溯
- [ ] 结论有数据支撑
- [ ] 输出文件完整
- [ ] HTML 数据从文件加载

### Step 6: 更新报告索引

报告生成完成后，执行索引生成脚本，更新报告中心：

```bash
node .claude/skills/data-analysis/scripts/generate_index.mjs
```

提示用户查看报告：

```
报告已生成！使用以下命令启动服务查看：

npm run serve

然后访问 http://localhost:3000/ 查看报告中心
```

### Step 7: 持续改进（必做）

**⚠️ 每次任务完成后，必须执行此步骤：**

检查本次分析过程中发现的可改进项，更新到对应文件：

| 发现类型           | 更新目标                              |
| ------------------ | ------------------------------------- |
| 新的表结构         | `schemas/{source}_{name}.md`          |
| 有效的分析方法     | `references/analysis_perspectives.md` |
| 常见问题及解决方案 | 本文件"问题处理"章节                  |
| 模板优化建议       | `templates/` 下对应文件               |

当前 Skill 是动态迭代的，保持其新鲜度是工作流的一部分。

---

## 问题处理

| 问题        | 方案                                     |
| ----------- | ---------------------------------------- |
| 查询超时    | 缩小范围/拆分查询/落地本地处理           |
| 数据量大    | SQL 聚合优先，必要时采样或分批           |
| Schema 不明 | describe_table + 样本查询                |
| 工具不通    | 检查 MCP Server 配置，告知用户后结束任务 |