| name | dashboard-builder |
| description | 根据用户提供的数据集（Excel、CSV、API 或数据库）快速生成一个完整可部署的 Flask + ECharts 数据可视化仪表盘项目。当用户提到"做一个仪表盘"、"数据可视化"、"看板"、"dashboard"、"BI 页面"、"数据监控页"，或者拿着表格数据问"怎么把这些数据用图表展示在网页上"时，请使用此技能——即使用户没有明确说"仪表盘"三个字。产出的项目结构固定为：Flask 后端提供 3-4 个 JSON API、单页 HTML 前端展示 KPI 卡片和 ECharts 图表、附带 requirements.txt。不适用：单张静态图表（用 matplotlib 即可）、纯前端组件（不涉及数据后端）、Tableau/PowerBI 等第三方 BI 工具配置。 |
Dashboard Builder
把"数据集 → 可在浏览器打开的仪表盘"这条路径标准化成 5 步流程。每次生成的项目结构相同：Flask 后端 + 单页 HTML 前端 + ECharts 图表 + requirements.txt。
我应该读哪些文件？
本文件是路由地图。代码模板和案例分别在不同子目录，用到时再读——不要一次性全部读完。
| 你正在做的事 | 应该读 |
|---|
| 走完整 5 步流程 | 本文件（你已经在这儿） |
| 选图表类型不确定 | §4 决策树 |
| 写 Flask 后端 | assets/backend/app_template.py |
| 写 HTML 前端 | assets/frontend/index_template.html |
| 找类似场景的参考案例 | references/examples/ 里挑最像的一个 |
| 用户问部署、nginx、gunicorn | references/deployment.md |
| 用户报错了 | references/troubleshooting.md |
Step 0：先判断要不要问用户
动手前先看信息够不够：
- 够了 = 用户上传了数据文件 + 说清楚关心什么指标 + 大致提到想要什么图。直接跳到 Step 1。
- 不够 = 数据源、核心指标、图表偏好这三项里有任何一项模糊。用
ask_user_input_v0 工具给按钮选项，最多问 3 个问题：
- 数据从哪来？（Excel / CSV / API / 数据库）
- 主要想看什么？（时间趋势 / 分类对比 / 地理分布 / 综合）
- 数据多久更新？（一次性静态 / 每天刷新 / 实时）
不要一次性追问所有细节。先用合理默认值开干，跑通后再迭代。
Step 1：实地查看数据
如果用户上传了文件，先 pd.read_excel/read_csv 读一下前几行，再设计任何东西。不要假设字段名或类型。
读完用一句话向用户确认你看到的字段：「我看到数据有这些列：日期、城市、温度。我会按这个理解来做，对吗？」
如果用户只是描述了数据没给文件，列出你假设的字段让他确认。
Step 2：设计数据模型（3+1 接口模式）
3+1 接口模式 = 一个总览接口 + 三个分主题接口。每次都按这个套路设计后端，省得每次重新发明轮子。
每个仪表盘都暴露这套接口形状，按需挑选：
| 接口路径 | 返回内容 | 是否必需 |
|---|
/api/summary | KPI 卡片数据：总数、最大值、最小值、平均值、最后更新时间 | 必需 |
/api/timeline | 时间序列：{dates: [...], values: [...], moving_avg?: [...]} | 数据有日期列就要 |
/api/distribution | 分类分布：{categories: [...], values: [...], percentages: [...]} | 数据有分类列就要 |
/api/geo | 地理数据：{regions: [...], values: [...]} 或 {cities: [{name, lat, lon, value}]} | 数据有地点列就要 |
不需要四个全做。人口数据可能只需要 summary + distribution + geo。项目跟踪可能用 summary + timeline + distribution。看数据形状决定。
Step 3：搭后端
复制 assets/backend/app_template.py 和 requirements.txt 到输出目录，然后：
- 改
load_data() 函数对接用户实际的数据源
- 实现你在 Step 2 选定的那几个
prepare_*_data() 函数——这是唯一真正定制的部分，路由骨架原样复用
- 确认
prepare_summary_data() 返回的字段名跟前端 KPI 卡片用的 id 一一对应
最容易踩的坑：数据有日期列时，必须先 pd.to_datetime() 转换才能按时间分组。返回 JSON 前要把 Timestamp 转成字符串（用 .dt.strftime('%Y-%m-%d')），否则 jsonify 会抛错。
Step 4：选图表（决策树）
Claude 容易"想象力过剩"乱推荐花哨图表。严格按下面这棵树走，按"用户想回答什么问题"选图，不是按"数据是什么类型"。
用户想回答的问题是？
├─ 「X 随时间怎么变？」 → 折线图（单线 / 多线）
│ └─ 两个指标量级差很大？ → 双 Y 轴折线图
│
├─ 「不同类别怎么比？」
│ ├─ 类别 ≤ 10 个 → 竖向柱状图
│ ├─ 类别 > 10 个 → 横向条形图（标签有空间）
│ └─ 多维度对比 → 分组柱状图
│
├─ 「占比 / 份额是？」
│ ├─ 2-5 块 → 饼图
│ ├─ 6+ 块 → 环形图 + 图例 / 树状图
│ └─ 有层级关系 → 旭日图
│
├─ 「在哪里发生？」 → 地图（区域用 choropleth，散点用气泡图）
│
└─ 「什么流向什么？」 → 桑基图 / 力导向图
术语补充：choropleth = 区域着色地图，颜色深浅代表数值大小（比如各省 GDP 颜色深浅图）；气泡图 = 散点图但点的大小代表第三个维度。
一个问题对应一张图。8 个图回答 8 个不同问题是好仪表盘；8 个图回答同一个问题的 8 种角度是冗余。
Step 5：搭前端
复制 assets/frontend/index_template.html。对每个 Step 4 选定的图：
- 加一段
<div class="chart-wrapper"><div class="chart" id="my-chart"></div></div> 到布局里
- 加一个对应的
initMyChart(data) 函数（克隆模板里 initTimelineChart 的写法）
- 把它加到顶部的
Promise.all([...]) 加载链里
模板用了：ECharts CDN（echarts.min.js）、深色主题（背景 #0f1c3a）、CSS Grid 自适应布局。不要重新发明。除非用户要求改主题色，否则保持原样。
输出位置
最终交付始终长这样。文件创建在 /mnt/user-data/outputs/<项目名>/，方便用 present_files 工具让用户下载：
<项目名>/
├── app.py
├── data.xlsx （或用户上传的任何数据文件，复制进来）
├── templates/
│ └── index.html
├── requirements.txt
└── README.md （一段话：怎么装、怎么跑）
README 必须包含两条命令：pip install -r requirements.txt 和 python app.py，告诉用户默认端口 5000，浏览器打开 http://localhost:5000。
交付完成后
最多提一个具体的后续建议（不要列两个都说）：
- 「要不要加一个[具体图]来回答[具体问题]？」——提具体的、跟数据相关的，不要泛泛问「还要加图吗」
- 「要不要部署上线？我可以加 gunicorn + nginx 配置。」——只在用户透露出生产部署意图时说
不要问「还有别的问题吗？」这种废话。要么提具体建议，要么就停。
必须避开的坑（一次读懂、不要再犯）
- 不要用 Streamlit / Dash / Plotly Dash，除非用户明确要求。本 skill 的核心价值就是 Flask + ECharts 这套清晰分离的架构，部署到 nginx 后面更简单。
- 不要把所有数据硬编码到 HTML 里。即使是静态数据也要走后端，这才是仪表盘可刷新的关键。
- 不要
df.to_dict() 直接当 JSON 返回。pandas 的默认字典格式跟 ECharts 想要的格式不匹配，必须经过 prepare_*_data() 转换。
- 不要忘了
host='0.0.0.0'。如果用户在容器或远程服务器跑，127.0.0.1 只能本机访问。
- 日期序列化坑：
jsonify 处理不了 pd.Timestamp 和 datetime 对象，必须先转字符串。
- 中文字体显示：CSS 字体栈里加上
"PingFang SC", "Microsoft YaHei"，否则 macOS 和 Windows 的中文显示会不一致。模板里已经写好了。
