chartjs-reporter — Chart.js HTML 可视化报告生成技能

技能目的

将结构化数据（SQL 查询结果、CSV 摘要、Python dict/list、手动提供的表格）转换为
自包含的 HTML 可视化报告，内嵌 Chart.js 图表和 KPI 卡片，无需服务器，
浏览器直接打开即可查看。

触发条件

以下任意一种情况触发本技能：

• - 用户提供了数据并要求出图、可视化、生成报告
• 用户已有 DuckDB / SQL / pandas 查询结果，需要图表化展示
• 用户指定了图表类型（饼图、柱状图、折线图等）+ 数据
• 与 chat2duckdb 技能配合：查询完成后生成可视化报告

操作步骤

步骤 1：理解数据结构

收到数据后，确认以下信息：

• - 数据形态：数值列 / 分类列 / 时间列
• 分析目的：占比 / 趋势 / 对比 / 排名
• 期望图表类型（用户未指定时，按照「图表选型规则」自动选择）

步骤 2：选择图表类型

步骤 3：调用生成脚本

使用 scripts/generate_report.py 生成 HTML 报告：

bash
python scripts/generate_report.py \
--title 报告标题 \
--subtitle 副标题说明 \
--data {charts: [...], kpis: [...]} \
--output report.html

也可以直接在 Python 中调用（适合与 chat2duckdb 配合）：

python
from scripts.generatereport import buildreport
html = build_report(title, subtitle, kpis, charts)
with open(report.html, w, encoding=utf-8) as f:
f.write(html)

步骤 4：数据格式规范

kpis 列表（可选，顶部 KPI 卡片）：
json
[
{label: 总营收, value: ¥1,755,905, sub: 全年累计, color: green},
{label: 订单数, value: 200, sub: 5 品类, color: blue}
]

color 可选值：blue | green | yellow | purple | red

charts 列表（图表配置）：
json
[
{
type: doughnut,
title: 品类营收占比,
labels: [Food, Electronics, Sports],
datasets: [{data: [456833, 351665, 349967]}]
},
{
type: line,
title: 月度趋势,
labels: [1月,2月,3月],
datasets: [{label: 营收, data: [158495, 185560, 98369]}]
}
]

支持的 type 值：bar | line | doughnut | pie | horizontalBar（自动转 bar + indexAxis:y）

步骤 5：布局规则

• - KPI 卡片行：最多 4 列，超出自动换行
• 图表区：默认 2 列网格；1 个图表时全宽；3 个图表时 3 列
• 每张图表高度固定 240px，响应式宽度
• 表格（Top N 排名）：单独一行，全宽显示
• 页脚：说明数据来源和生成时间

步骤 6：输出与展示

• - 输出路径默认为用户提供的路径，或 ./report.html
• 生成后调用 previewurl 工具在浏览器中预览
• 所有依赖（Chart.js）通过 CDN 加载，无需本地安装

与 chat2duckdb 配合的标准流程

1. 1. chat2duckdb 执行 SQL 查询 → 得到 DataFrame / 字典结果
2. chartjs-reporter 将结果转换为图表配置 JSON
3. 调用 generatereport.py 生成 HTML
4. 调用 previewurl 展示报告

参考资源

• - 核心脚本：scripts/generatereport.py
• 图表配置参考：references/chart-config-guide.md
• 样式主题参考：references/theme-tokens.md