---
name: data-analysis-reporter
description: 分析用户提供的数据文件（CSV、Excel、JSON）或包含数据的图片，动态生成分析方案和 Python 计算脚本，调用 data-chart-maker 生成可视化图表，最终输出一份图文并茂的 HTML 分析报告。当用户需要做数据分析、数据洞察、统计报告时使用。
---

# 数据分析与自动报告

> 本 Skill 来自《玩转 Skill：零门槛打造你的 AI 数字员工》第 9.5 节。
> 这是一个框架模板，核心是"动态脚本 + Skill 协作"的模式。
> `scripts/data_profiler.py` 和 `references/report_template.md` 是占位文件，首次使用时需要让 AI 生成完整版本。

## 工作模式说明

本 Skill 支持两种工作模式：

- **动态分析模式**（默认）：每次根据数据特征和用户需求临时生成分析脚本，灵活适应各种一次性分析需求
- **固定报告模式**：将某次分析使用的脚本沉淀下来，后续直接复用，适合日报/周报/月报等定期出具的固定报告

首次使用时通常从动态分析模式开始，多次分析后如发现某些维度反复被用到，可以将脚本固化为固定报告模式。

## 环境准备

- **Python**（3.8 及以上），以及 pandas、openpyxl 等数据处理库（AI 会自动安装）
- **data-chart-maker Skill**：本 Skill 生成图表时需调用 data-chart-maker，请确认已安装
- **多模态大模型 API**（可选）：如需处理图片/截图中的数据，需要在 `.config/multimodal_api_key.txt` 中填入 API Key

如果脚本运行时报错提示缺少库或模块，直接告知 AI 根据报错自动安装。

## 使用场景

用户提供数据文件（CSV、Excel、JSON）或包含数据的图片/截图，需要分析数据、得出结论、生成报告。

## 工作流程

### 第一步：获取并理解数据

确认用户的数据来源：

- **如果是 CSV、Excel、JSON 文件，或包含数据表格的图片/截图**，运行数据概览脚本：
  ```
  python scripts/data_profiler.py [数据文件路径]
  ```
  该脚本会自动识别文件类型。对于图片文件，脚本内部会调用多模态大模型识别其中的表格数据并转换为结构化格式，然后生成数据画像。

- **如果用户口述数据或粘贴了文本数据**，将其整理为临时 CSV 文件后同样运行 `data_profiler.py`。

**如果 data_profiler.py 尚未生成**（文件内容是占位说明），先自动生成完整脚本：
- 支持输入格式：CSV、Excel（.xlsx/.xls）、JSON、图片（PNG/JPG）
- 对于结构化文件：直接解析，输出数据画像
- 对于图片文件：调用多模态大模型 API（从 `.config/multimodal_api_key.txt` 读取 Key）识别表格数据，转换为 CSV 后解析
- 数据画像内容：字段名称/类型/非空数量、数值型字段的范围/均值/中位数、文本型字段的唯一值数量和高频值、总记录数和前 5 行样例

阅读数据画像，向用户确认：
- 数据共几条记录，包含哪些字段
- 是否有数据质量问题（大量缺失值、明显异常值）需要预处理

### 第二步：制定分析方案

根据数据画像和用户的分析需求，制定分析方案：
- 从哪些维度切入（时间趋势、分类对比、分布特征、相关性分析等）
- 每个维度使用什么统计方法
- 计划生成哪些图表类型

将分析方案以清单形式展示给用户，明确告知：
**"这是初步的分析方案，请确认或调整。确认后我将开始执行分析计算，完成后生成可视化报告。"**

**必须等用户确认后才能进入下一步。** 如用户要求修改，调整方案后重新确认。

### 第三步：执行数据计算

根据确认后的方案，现场编写 Python 分析脚本并执行。

脚本要求：
- 读取原始数据文件
- 按方案中的各维度逐项计算指标
- 将所有计算结果以 JSON 格式输出，结构为：
  ```json
  [
    {
      "dimension": "维度名称",
      "chart_type": "建议图表类型（bar/line/pie等）",
      "title": "图表标题",
      "data": { "labels": [...], "values": [...] },
      "key_findings": "本维度的核心发现（1~2句话）"
    }
  ]
  ```

如果脚本执行报错，自动检查原因并修正后重新执行。常见问题：数据类型不匹配、缺失值导致计算失败——可以在脚本中加入适当的数据清洗步骤。

### 第四步：生成图表

基于第三步的计算结果，调用 **data-chart-maker Skill** 逐项生成可视化图表：

调用规则：
- 指定使用 **SVG 方式**生成图表（数据图表精确度高，且可内联至 HTML）
- 传入具体数据和图表类型要求
- 将每个 SVG 图表文件保存到临时目录，记录文件路径

> 注意：调用 data-chart-maker 时直接指定 SVG 方式，无需再向用户确认图表方式。

### 第五步：生成 HTML 报告

阅读 `references/report_template.md`，了解报告的内容结构和视觉样式要求。

**如果 report_template.md 尚未生成**（文件内容是占位说明），先自动生成初版模板：
- 内容结构：顶部关键指标摘要卡片 → 分维度分析（每个维度含图表+文字结论）→ 总结与行动建议
- 视觉样式：简洁商务风、白底卡片式布局、深蓝+灰色主色调、合理的字号和间距

根据计算结果和图表，生成完整的 HTML 报告文件：

1. 按模板规定的结构组织内容
2. 读取每个 SVG 图表文件的内容，将 SVG 代码**直接内联嵌入** HTML 中（不使用 `<img>` 标签引用外部文件）
3. 报告必须是自包含的单文件，用浏览器打开即可查看，发给他人时图表不会丢失

将 HTML 报告保存为文件，告知用户保存路径，询问是否需要补充分析或调整内容。

## 注意事项

- 分析方案必须经用户确认后才能开始计算，未确认不得直接执行
- SVG 图表代码必须直接内联嵌入 HTML，确保报告是自包含单文件
- 如果数据量超过十万行，建议先用脚本做抽样或聚合降维，再进行分析，并告知用户
- 如果用户需要固定格式的定期报告（周报/月报），建议将本次分析脚本保存到 `scripts/` 下，后续直接复用（从动态脚本转为静态脚本）
- 本 Skill 可与其他 Skill 联动：分析结果可传给 PPT Skill 生成演示材料；如数据存储在数据库中，可配置对应 MCP 直接拉取数据
