1688 Common Html Report Generator

数据报告可视化生成器

通过 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。选型时必须同时满足适用条件且不触犯禁用条件。

选型核心原则：

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

读取后重点确认以下易错签名：

• 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）。脚本行数不设上限，以完整还原数据为第一优先级。

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: 执行并交付

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

关键约束

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