1688 Common Html Report Generator

SKILL.md

---
name: 1688-common-html-report-generator
description: 将文本数据报告快速转换为交互式可视化HTML网页。使用 Python 代码驱动预置模板，只需编写数据配置即可自动生成专业数据看板。适用于市场分析报告、运营数据复盘、行业调研报告、销售数据汇总等场景。触发词：生成HTML报告、生成网页报告、转成可视化网页、做成数据看板、数据可视化、生成HTML看板。
---

# 数据报告可视化生成器

通过 Python 代码驱动预置 HTML 模板，将数据报告转换为交互式可视化网页。AI 编写 Python 数据配置脚本（行数随数据量伸缩，简单报告 ~100 行，复杂报告可达 300-500+ 行），脚本自动处理 HTML/CSS/JS 生成。

## 文件结构

```
1688-common-html-report-generator/
├── SKILL.md                 # 本文件（工作流 + 可视化思路）
├── scripts/
│   ├── generate.py          # ReportBuilder 核心脚本
│   └── template.html        # HTML 模板（暗色主题 + ECharts）
└── references/
    └── chart-bindbook.md    # 图表使用手册：每个组件的适用/禁用场景 + API 签名（写代码前必读）
```

## 工作流程

### Step 1: 读取数据源

读取用户提供的文本/数据文件，**逐章逐节**提取：

- 标题、时间、来源等元信息
- **所有**数据表格（含完整行列，不可省略行或列）
- 章节结构和层级关系
- 关键数字
- 洞察/结论/趋势建议等文字段落

### Step 2: 规划报告结构

**在写代码前，先列出章节规划清单**，逐条对照下方可视化思路指南检查。

规划清单必须满足：

1. **完整性**：原文件有 N 章就必须生成 N 个 section，不可合并或省略
2. **数据零丢失**：每张表格都必须出现在报告中（图表或 `r.table()`）；原文的文字洞察/结论用 `r.insight()` 或表格备注呈现
3. **图表多样化**：至少使用 3 种不同图表类型，禁止全篇只用 bar+pie
4. **叙事节奏**：适度使用 `r.insight()` 做章节过渡和收束，避免纯数据堆砌，但也不要每个图表后都加 insight

#### 可视化思路指南（核心，必读）

##### A. 结构组织原则

1. **图表先行，表格兜底**：优先用图表呈现数据。只有维度太多（≥6列）或包含文本字段时才用表格。**禁止一个 section 只有表格没有图表**。
2. **先总后分**：章节开头用一张全景图（`size="lg"`）给整体印象，再用 `grid` 分列展示细节。
3. **grid 高度平衡**：`grid(2)` 左右体量必须相当。禁止一边大图表、另一边 3 行文字。
4. **图表与表格互补**：图表覆盖核心数值维度，表格保留图表无法展示的文本维度（品牌名、关键词等），不要重复展示相同数据。
5. **叙事过渡**：避免"图表→图表→表格→表格"的纯数据堆砌。

##### B. 图表选型规范

每个图表组件有明确的**适用场景**和**禁用场景**，详见 [references/chart-bindbook.md](references/chart-bindbook.md)。选型时必须同时满足适用条件且不触犯禁用条件。

**选型核心原则**：

1. **量级一致**：同一 series / 同一图表中的数值量级差距不超过 10 倍
2. **有对比才用对比型图表**：雷达图至少 2 个对象，热力图至少 2×3 矩阵且无大面积 0 值
3. **连续数值才用连续色阶**：热力图格子必须是可比较的数值，不能是分类/布尔/枚举
4. **信息密度**：有两个维度时用 `dual_y` 而非两张独立图
5. **容器匹配**：`r.chart()` 仅用于 ECharts 图表，`progress_group`/`metric_grid`/`table` 禁止加 `r.chart()`



##### C. 布局约束

- **grid 最多一层，禁止嵌套**。需要并排 3 个饼图就用顶层 `grid(3)`，不要在 `grid(2)` 里再嵌 `grid(3)`。
- 一个格子内需要多个内容时，用**纵向堆叠**，不要横向再分格。

##### D. 表格精简原则

图表化后的表格应裁剪，但不能丢数据：

1. **图表已覆盖的纯数值列**：从表格中去掉
2. **文本字段列**（品牌名、关键词、建议等）：**必须保留**，图表无法表达
3. **表格行数不可裁剪**：原文 11 行就保留 11 行
4. 裁剪后至少保留"名称+2个文本列"。若只剩 1 列，改用 insight 框

##### E. 多平台章节组织原则

**核心思路：先对比，再展开。** 读者看完平台A再看平台B时已经忘了A的数据，所以必须先用跨平台对比图建立全局印象。

推荐结构：

```
1. 跨平台对比（全局视角，必须有）
   → 全景对比图：分组柱状图/热力图/雷达图，把所有平台放一起（size="lg"）
   → metric_grid：各平台最突出的 1 个数字

2. 分平台细节（展开视角）
   → grid(3) 并列饼图（各平台渠道构成）
   → 各平台 dual_y 图（如：月销量柱 + 客单价线，信息密度翻倍）
   → 各平台详细表格（保留文本维度）
```

**禁止**的组织方式：平台A insight → 平台A图表 → 平台A表格 → 平台B insight → 平台B图表 → 平台B表格（串行罗列，无法横向对比）

### Step 3: 读取 API 文档（必须，不可跳过）

**在写任何代码之前**，必须先读取完整图表使用手册：[references/chart-bindbook.md](references/chart-bindbook.md)

读取后重点确认以下易错签名：
- `kpi` 的参数是 `(label, value, unit, change, down)`，**不支持 `color` 参数**
- `chart_heatmap` 的 `data` 格式是 `[x, y, value]` 三元组列表
- `chart_bar` 的 `dual_y=True` 时，series 里需要 `"type": "bar"/"line"` 和 `"yAxisIndex": 1`
- `chart_pie` 的 `inner_radius`/`outer_radius` 参数可选
- `progress_bar` 的参数顺序是 `(label, value, max_val, color, suffix)`
- `metric` 的参数是 `(value, desc, color)`，`unit` 可选

**禁止跳过此步骤直接写代码**——本文件的 API 速查是精简版，缺少参数细节，仅靠速查表写代码会导致调用出错。

### Step 4: 编写 Python 构建脚本

在当前工作区的 `outputs/` 目录下创建构建脚本，文件名格式为 `build_报告主题_时间戳.py`（如 `outputs/build_市场分析_20260515.py`）。脚本行数不设上限，以**完整还原数据**为第一优先级。

```python
import sys, os
sys.path.insert(0, "1688-common-html-report-generator/scripts")
from generate import ReportBuilder

r = ReportBuilder("报告标题")
r.header("大标题", "副标题", ["时间:2026-05-14", "来源:XX"])
r.nav([("核心指标", "#kpi"), ("平台对比", "#platform")])

with r.section("kpi", "01", "核心指标", "关键数据概览"):
    r.kpi_grid()
    r.kpi("销量", "4.23", "亿件", "同比+14.9%")
    r.kpi("均价", "89", "元", "同比-5.2%", down=True)
    r.kpi_end()

    # grid(2) 示例：左右体量对等
    r.grid(2)
    r.card("销量对比", dot_color=r.C_TAOBAO)
    r.chart("barChart")
    r.chart_bar("barChart",
        categories=["抖音", "淘宝", "小红书"],
        series=[{"name": "销量", "data": [120, 200, 80], "color": r.C_TAOBAO}],
        show_label=True)
    r.card_end()
    r.card("占比分布", dot_color=r.C_DOUYIN)
    r.chart("pieChart")
    r.chart_pie("pieChart", data=[
        {"value": 45, "name": "抖音", "color": r.C_DOUYIN},
        {"value": 35, "name": "淘宝", "color": r.C_TAOBAO},
        {"value": 20, "name": "小红书", "color": r.C_XIAOHONGSHU},
    ])
    r.card_end()
    r.grid_end()

    r.insight("核心发现", ["要点1", "要点2"])

r.footer("数据来源：XX平台")
os.makedirs("outputs", exist_ok=True)
r.render("outputs/报告.html")
```

### Step 5: 执行并交付

```bash
python3 build_报告主题_时间戳.py
open outputs/报告.html
```

## 关键约束

- **不要手写 HTML/CSS/JS**，全部通过 `ReportBuilder` 方法生成
- **不要手写 ECharts 通用配置**（tooltip/legend/grid 已内置），不满足时用 `chart_script`
- **颜色引用常量**（`r.C_DOUYIN` 等），保持跨图表一致
- **脚本行数不设上限**：数据量大时可 300-500+ 行，以完整还原为第一目标