Excel 图表生成

技能文档

---
name: excel-chart
title: Excel 图表生成
category: 办公效率
description: 从 Excel 文件（.xlsx/.xls）读取数据并自动生成统计图表，支持柱状图、折线图、饼图、散点图、箱线图、热力图等类型，输出 HTML 交互图表或 PNG 静态图片。当用户需要把 Excel 数据变成图表、做数据可视化或绘制统计图时触发。触发词：Excel 图表、数据可视化、生成折线图、画柱状图、饼图。
---

# Excel 图表生成

## 功能概述

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

## 触发条件

当用户提出以下意图时使用本技能：
- 「从这个 Excel 生成图表」「根据 Excel 画图」「Excel 数据可视化」
- 「帮我做一张柱状图/折线图/饼图/散点图/箱线图/热力图」
- 「把这份 Excel 数据变成图表」
- 「Excel 数据分析」「统计图」「数据图表」
- 泛化表述：涉及 Excel 文件 + 图表/可视化/统计图

## 前置环境检查

使用本技能前，确保以下 Python 库已安装：

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

一键检查：

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

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

## 技能工作流

### 步骤1：读取并理解 Excel 数据结构

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

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

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

### 步骤2：与用户确认图表参数

基于预览结果，与用户确认：
1. 使用哪个 sheet（如果有多张表）
2. 用作 X 轴的列（通常为分类/时间列）
3. 用作 Y 轴的列（通常为数值列）
4. 图表类型（柱状图/折线图/饼图/散点图/箱线图/热力图）
5. 输出格式（HTML 交互图表 / PNG 静态图片）

如果用户没有明确指定，根据数据结构自动推荐最合适的图表类型：
- 1 个分类列 + 1 个数值列 → 柱状图 或 饼图
- 1 个时间列 + 1 个数值列 → 折线图
- 2 个数值列 → 散点图
- 多个数值列 → 箱线图 或 热力图

### 步骤3：生成图表

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

```bash
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 图片

### 步骤4：展示结果

- **HTML 输出**：在浏览器中打开生成的 HTML 文件预览交互效果
- **PNG 输出**：直接把 PNG 文件发给用户，或用系统默认图片查看器打开

图表类型选择、配色与数据结构判断的详细参考见 [references/chart_types.md](references/chart_types.md)。

## 脚本详细用法

```bash
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 条数据
```

## 数据预处理

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

## 文件结构

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

使用说明

# Excel 图表生成

从 Excel 表格数据一键生成专业统计图表，支持交互式 HTML 与静态 PNG 两种输出。

## 使用

```bash
# 安装依赖
pip install pandas openpyxl plotly matplotlib kaleido

# 预览数据结构
python scripts/generate_chart.py 数据.xlsx --mode preview

# 生成柱状图（HTML 交互版）
python scripts/generate_chart.py 数据.xlsx --chart-type bar \
    --x-column "城市" --y-column "销售额" --output 销售图表

# 生成折线图 PNG
python scripts/generate_chart.py 数据.xlsx --chart-type line \
    --x-column "日期" --y-column "温度" --output-format png --output 趋势
```

对话中直接说「把这个 Excel 画成柱状图」即可触发技能自动完成。

## 工作原理

脚本用 pandas 读取 Excel 全部 sheet，自动识别数值列、分类列与日期列；用户未指定图表类型时按数据结构自动推荐（如时间+数值→折线图，两数值列→散点图），内置六种图表与四种配色方案，输出前自动完成日期解析、空列过滤与大表采样提示。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。