excel-chart - Excel 统计图生成 Skill

功能概述

从 Excel 文件（.xlsx / .xls）读取数据，自动识别数据结构，生成高质量的统计图表。支持多种图表类型和两种输出格式。

触发条件

当用户提出以下意图时使用此 skill：

「从这个 Excel 生成图表」「根据 Excel 画图」「Excel 数据可视化」
「帮我做一张柱状图/折线图/饼图/散点图/箱线图/热力图」
「把这份 Excel 数据变成图表」
「Excel 数据分析」「统计图」「数据图表」
泛化表述：涉及 Excel 文件 + 图表/可视化/统计图

前置环境检查

使用此 skill 前，确保以下 Python 库已安装：

python -m pip install pandas openpyxl plotly matplotlib kaleido --quiet

一键检查：

python -c "import pandas; import openpyxl; import plotly; import matplotlib; import kaleido; print('OK')"

如果报错 ModuleNotFoundError，先执行安装命令。

使用流程

第一步：读取并理解 Excel 数据结构

调用 scripts/generate_chart.py 的预览模式来查看 Excel 内容：

python <skill_path>/scripts/generate_chart.py <excel_path> --mode preview

脚本会输出：

所有 sheet 名称
每个 sheet 的前 5 行数据
列名和数据类型
数据统计摘要（数值列的最大/最小/均值等）

第二步：与用户确认图表参数

基于预览结果，与用户确认：

使用哪个 sheet（如果有多张表）
用作 X 轴的列（通常为分类/时间列）
用作 Y 轴的列（通常为数值列）
图表类型（柱状图/折线图/饼图/散点图/箱线图/热力图）
输出格式（HTML 交互图表 / PNG 静态图片）

如果用户没有明确指定，根据数据结构自动推荐最合适的图表类型：

1 个分类列 + 1 个数值列 → 柱状图或饼图
1 个时间列 + 1 个数值列 → 折线图
2 个数值列 → 散点图
多个数值列 → 箱线图或热力图

第三步：生成图表

根据确认的参数生成图表：

python <skill_path>/scripts/generate_chart.py <excel_path> \
    --sheet "Sheet1" \
    --chart-type bar \
    --x-column "列名1" \
    --y-column "列名2" \
    --title "图表标题" \
    --output <输出路径> \
    --output-format html

图表类型参数 --chart-type 的可选值：

bar — 柱状图（竖直）/ 条形图（水平）
line — 折线图/趋势图
pie — 饼图/环形图
scatter — 散点图
box — 箱线图
heatmap — 热力图（需要至少两个数值列）
auto — 自动推荐最合适的图表类型

输出格式参数 --output-format：

html — 生成 Plotly 交互式 HTML 图表（默认）
png — 生成 Matplotlib 静态 PNG 图片

第四步：展示结果

HTML 输出：使用 preview_url 工具预览生成的 HTML 文件
PNG 输出：使用 open_result_view 或直接发送文件给用户

脚本详细用法

python <skill_path>/scripts/generate_chart.py <excel_path> [options]

位置参数：
  excel_path             Excel 文件路径

选项：
  --mode preview         仅预览数据，不生成图表
  --sheet SHEET_NAME     指定使用的 sheet 名称（默认：第一个 sheet）
  --chart-type TYPE      图表类型：bar|line|pie|scatter|box|heatmap|auto
  --x-column COL         指定 X 轴列名
  --y-column COL         指定 Y 轴列名（多个列用逗号分隔，用于箱线图和热力图）
  --title TITLE          图表标题
  --subtitle SUBTITLE    图表副标题
  --output PATH          输出文件路径（不含扩展名）
  --output-format FORMAT 输出格式：html|png（默认：html）
  --width WIDTH          图表宽度（像素，默认：1000）
  --height HEIGHT        图表高度（像素，默认：600）
  --palette THEME        配色方案：default|vivid|pastel|dark（默认：default）
  --horizontal           生成水平条形图（仅对 bar 类型有效）
  --sort                 对类别数据进行排序（按数值降序）
  --top N                仅显示前 N 条数据

数据预处理

脚本会自动进行以下预处理：

尝试将日期字符串解析为 datetime 类型
自动识别数值列和分类列
忽略完全为空的列
缺失值标记但不填充（由图表类型决定处理方式）
如果数据量过大（超过 1000 行），自动提示分批或采样

文件结构

excel-chart/
├── SKILL.md              # 本文件 - skill 主说明
├── scripts/
│   └── generate_chart.py # 核心脚本 - 读取 Excel 并生成图表
└── references/
    └── chart_types.md    # 图表类型参考指南