Excel 智能可视化 Skill

把任意 Excel / CSV 自动转化为一份可交互的可视化分析报告（单文件 HTML）。技术栈：Python + pandas + pyecharts。对应需求规格说明书（V1.0）。

安装

pip install -r requirements.txt
# 可选：PNG/SVG/PDF 图片导出
pip install pyecharts-snapshot
# 中文拼音匹配（列名模糊匹配增强）
pip install pypinyin

快速开始

# 1) 生成样例数据（examples/sales.xlsx 等）
python tools/make_examples.py

# 2) 全自动：丢进去就出报告
python -m src.cli examples/sales.xlsx

# 3) 自然语言：一句话精确指定
python -m src.cli examples/sales.xlsx --ask "按大区看销售额占比，画成树图，只要前 8 个"

# 4) 显式参数：完全可预期，适合写进脚本
python -m src.cli examples/sales.xlsx \
  --chart=pie --dim=大区 --metric=销售额 --agg=sum --topn=8 --theme=business

驱动方式（三级仲裁）

自动推荐结果 < 配置文件默认值 < 自然语言指令 < 命令行显式参数

目录结构

skill1/
├── SKILL.md / requirements.txt / README.md
├── config/        # default / synonyms / chart_contracts 知识库
├── src/
│   ├── cli.py                 # 命令行入口
│   ├── config_loader.py       # 配置加载
│   ├── reader/    (M1) 输入解析：读取 / 表头定位 / 清洗
│   ├── profiler/  (M2) 数据理解：字段角色 / 基数 / 缺失率 / 层级
│   ├── recommender/ (M3) 推荐引擎：契约 / 评分 / 否决
│   ├── nlu/       (M4) 指令解析：槽位 / 模糊列名 / 仲裁
│   ├── charts/    (M5) 图表渲染：注册表 + 28 种图型 + 主题
│   ├── dashboard/ (M6) 仪表盘组装
│   ├── exporter/  (M7) 输出交付：单文件 HTML / 图片 / Excel / 血缘
│   └── utils/     # 日志 / 血缘 / 脱敏
└── tools/         # make_examples.py 示例数据生成

已实现范围（对照规格）

✅ M1 输入解析：多格式、多 sheet、--sheet=all、表头自动定位、脏数据清洗、干扰行剔除
✅ M2 数据理解：角色判定、基数/缺失率、时间粒度、层级识别、地理识别、同义归一
✅ M3 推荐引擎：数据契约筛选 → 加权评分 → 否决与冲突规避 → TopN 归并 → 视角均衡
✅ M4 指令解析：9 类意图槽位、六级容错列名匹配（精确/子串/拼音/同义/编辑距离）、优先级仲裁、指令回显
✅ M5 图表渲染：注册表覆盖饼/环/玫瑰/树图/旭日/瀑布/柱/条/堆叠/双向/折线/面积/双轴/直方/箱线/散点/气泡/热力/雷达/相关矩阵/漏斗/桑基/地图/词云/仪表/进度环；5 套主题；万/亿格式化；长标签截断
✅ M6/M7 仪表盘与输出：报告头 / KPI 概览 / 图表区 / 图表血缘附录；单文件离线 HTML（内联 ECharts）；PNG/SVG/PDF/XLSX 导出；失败降级；敏感字段脱敏
⚠️ 部分能力为「结构已就位、深度待补」：M6 的全局筛选联动、点击下钻、图型切换等深度交互；桑基/地图/进度的自动信号识别；P2 的批量/缓存/模板复用。这些留有清晰的扩展点（M8 配置、图表注册表、自定义图表注册接口）。

常见参数

| 参数 | 说明 | |------|------| | --ask | 自然语言指令 | | --chart/--dim/--metric/--agg | 显式图型/维度/指标/聚合 | | --filter | 筛选，如 地区==华东,年份>=2024 | | --topn/--sort/--theme | TopN 归并 / 排序 / 主题 | | --format | html,png,svg,pdf,xlsx 可多选 | | --max-charts | 自动模式图表数量上限 | | --config | YAML 配置文件 | | --verbose | 打印逐模块决策日志 |

说明

首次生成 HTML 会从 CDN 拉取并缓存 echarts.min.js 到 vendor/，之后产物均离线可打开。
地图（中国地图）需要 ECharts 地图数据注册，若环境缺失会按「失败降级」跳过该图并在报告中说明。