\r \r

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

\r

技能目的\r

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

触发条件\r

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

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

操作步骤\r

\r

步骤 1：理解数据结构\r

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

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

步骤 2：选择图表类型\r

\r | 分析目的 | 推荐图表 |\r |---------|---------|\r | 占比 / 构成 | doughnut（≤6类）/ pie |\r | 趋势 / 时间序列 | line（fill: true 显示面积） |\r | 分类对比（≤8项） | bar（垂直） |\r | 分类对比（>8项或标签长） | bar（水平，indexAxis: 'y'） |\r | 多指标对比 | 分组 bar |\r | 排名 Top N | 水平 bar + 进度条 |\r | 关键指标摘要 | KPI 卡片（非图表） |\r \r

步骤 3：调用生成脚本\r

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

python scripts/generate_report.py \\r
  --title "报告标题" \\r
  --subtitle "副标题说明" \\r
  --data '{"charts": [...], "kpis": [...]}' \\r
  --output report.html\r
```\r
\r
也可以直接在 Python 中调用（适合与 chat2duckdb 配合）：\r
\r
```python\r
from scripts.generate_report import build_report\r
html = build_report(title, subtitle, kpis, charts)\r
with open("report.html", "w", encoding="utf-8") as f:\r
    f.write(html)\r
```\r
\r
### 步骤 4：数据格式规范\r
\r
`kpis` 列表（可选，顶部 KPI 卡片）：\r
```json\r
[\r
  {"label": "总营收", "value": "¥1,755,905", "sub": "全年累计", "color": "green"},\r
  {"label": "订单数", "value": "200",         "sub": "5 品类",  "color": "blue"}\r
]\r
```\r
`color` 可选值：`blue` | `green` | `yellow` | `purple` | `red`\r
\r
`charts` 列表（图表配置）：\r
```json\r
[\r
  {\r
    "type": "doughnut",\r
    "title": "品类营收占比",\r
    "labels": ["Food", "Electronics", "Sports"],\r
    "datasets": [{"data": [456833, 351665, 349967]}]\r
  },\r
  {\r
    "type": "line",\r
    "title": "月度趋势",\r
    "labels": ["1月","2月","3月"],\r
    "datasets": [{"label": "营收", "data": [158495, 185560, 98369]}]\r
  }\r
]\r
```\r
\r
支持的 `type` 值：`bar` | `line` | `doughnut` | `pie` | `horizontalBar`（自动转 bar + indexAxis:y）\r
\r
### 步骤 5：布局规则\r
\r
- KPI 卡片行：最多 4 列，超出自动换行\r
- 图表区：默认 2 列网格；1 个图表时全宽；3 个图表时 3 列\r
- 每张图表高度固定 240px，响应式宽度\r
- 表格（Top N 排名）：单独一行，全宽显示\r
- 页脚：说明数据来源和生成时间\r
\r
### 步骤 6：输出与展示\r
\r
- 输出路径默认为用户提供的路径，或 `./report_\x3Ctimestamp>.html`\r
- 生成后调用 `preview_url` 工具在浏览器中预览\r
- 所有依赖（Chart.js）通过 CDN 加载，无需本地安装\r
\r
## 与 chat2duckdb 配合的标准流程\r
\r
```\r
1. chat2duckdb 执行 SQL 查询 → 得到 DataFrame / 字典结果\r
2. chartjs-reporter 将结果转换为图表配置 JSON\r
3. 调用 generate_report.py 生成 HTML\r
4. 调用 preview_url 展示报告\r
```\r
\r
## 参考资源\r
\r
- 核心脚本：[scripts/generate_report.py](scripts/generate_report.py)\r
- 图表配置参考：[references/chart-config-guide.md](references/chart-config-guide.md)\r
- 样式主题参考：[references/theme-tokens.md](references/theme-tokens.md)\r
\r
## 注意事项\r
\r
- 报告为**深色主题**（dark mode），背景色 `#0f172a`，适合截图展示\r
- 数值超过 1000 时，自动格式化为千分位（¥1,234,567）\r
- 颜色序列已内置，无需手动指定每个数据点颜色\r
- Chart.js 版本固定为 4.4.0（CDN），确保稳定性\r