精美HTML标准制作生成器（report-visualization · 第④环节 · v2.5.1 多格式版）

一键生成美观可用的 HTML，将你的报告可视化呈现。

不管原始文件是 PPT、Word、HTML、Markdown、TXT，还是 ③ 的标准 JSON 契约 / 原始 csv-xlsx 表——本 skill 吸收其中的内容，用统一的 Design Tokens 设计系统重新排版，输出一份单文件、品牌化、可打印的 HTML。

> 为什么需要它：做汇报时大家都想要好的呈现效果，但自己排版或让 AI 排，往往耗时久、反复改、还不好看。本 skill 把「吸收内容 → 标准化重呈现」这一步自动化。

支持输入（格式无关，只看内容）

统一内容模型：{"meta":{title,date,source,bgm?}, "sections":[ block, ... ]}，block.type ∈
heading / paragraph / list / table / kpi / trend / comparison / bar / share / funnel / insight / image / video / link。
③ 的契约本质就是这份模型的一种（已结构化好的那一种）。

媒体与链接（图片 / 视频 / 网址 / 背景音乐）

• 图片 image：{type:"image", src, caption?, alt?, width?}。src 支持 ① http(s) 链接 ② 本地相对路径（如 ./img/1.png，与输出 HTML 同目录即可）③ base64 data:image/...;base64,... 三态；缺失 src → 显示占位提示，加载失败 → 显示「图片加载失败」降级，绝不崩。
• 视频 video：{type:"video", src, caption?, poster?, width?}，同上三态地址，渲染为带控件的 <video controls>（不自动播放，符合预期）。
• 链接 link：{type:"link", url, title?, description?}，渲染为「标题 + 描述 + 域名」卡片，点击新窗口打开；此外段落 / 列表 / 洞察里的裸网址与 [文本](网址) markdown 链接会自动变可点击超链接（单遍匹配、安全转义，仅放行 http(s)/data/mailto/相对路径，拒绝 javascript: 等）。
• 背景音乐（仅 deck 风格）：meta.bgm = {src, title?}，在 deck 左下角显示开关按钮；默认关，点击才播放/暂停（浏览器禁止无交互自动播放，故默认静音不播），循环播放。report（文档式）暂不支持 BGM。

30 秒上手（最短路径）

一句话：把任意报告文件喂进来，它就吐出一份好看的 HTML。

python scripts/render_report.py --input 你的报告.md          # 文档式，直接出 HTML
python scripts/render_report.py --input 你的报告.json --deck # 想翻页演示？加 --deck

• 想直接吃 ③ 标准分析契约？--input 契约.json 即可，无需任何改写。
• 想要不同版面 / 品牌色 / 离线自包含图表？看下方「用法」，以及结尾「进阶 / 扩展」。

触发条件

• 已有一份报告（任意格式），想把它变成「人能直接看的、好看的」HTML 成果时 → --input 文件。
• 已拿到 ③ 产出的 .json 分析契约 → --input 契约.json（等同 --contract）。
• 手头有 .csv/.xlsx 原始表，想直接出图 → --input 表.xlsx（等同 --data）。
• 不触发：纯数据分析（那是 ③）、取数（①）、做日报（②）。

边界（铁律）

本 skill 只做「内容吸收 + 最后一步可视化呈现重排」。
- 不分析数据、不计算结论、不生成洞察。
- 洞察/结论仅当输入契约或文档本身已含 insight 区块时原样呈现。
- 文档式（report）下，解析器标 auto_chart:true 的表格若可图表化（含日期+数值 / 分类+数值），会先出图再附明细表；这是「呈现」，不是「分析」。幻灯片（deck）模式 table 只渲染表格，不出图。

依赖

• 零依赖即可用：.json / .csv / .xlsx / .md / .html / .txt（html 用 BeautifulSoup，但已随 python-docx 等一并安装；若只想用前几种，纯标准库也够 csv/xlsx/md/txt/json）。
• 解析 .docx / .pptx 需 python-docx + python-pptx（两者会顺带装 beautifulsoup4/lxml）。未安装时用到对应格式会明确报错提示安装。
• 安装：pip install python-docx python-pptx beautifulsoup4

用法

# 任意格式，统一入口
python scripts/render_report.py --input 季度复盘.pptx --brand-color #007F3A
python scripts/render_report.py --input 月报.docx   --out 月报.html
python scripts/render_report.py --input 报告.md
python scripts/render_report.py --input 数据.csv
python scripts/render_report.py --input 契约.json   # 等价 --contract

# 可选
#   --out 输出路径（默认 <输入同名>.html）
#   --brand-color #RRGGBB（品牌主色 token；默认靛蓝 #4F46E5；deck 模式各翻页风格另有默认色）
#   --title / --date 覆盖 meta
#   --style report|dashboard  版面风格（默认 report 文档式；dashboard=仪表盘卡片网格）
#   --no-animate              关闭入场动画（默认开启；尊重 prefers-reduced-motion）
#   --inline-echarts 路径.js  内联 ECharts，使成品离线可用（图表不依赖 CDN）

• 品牌色未传则 deck 各翻页风格自动取各自默认色（青碧/皇家蓝/紫罗兰/炽橙/湖青），文档式默认靛蓝；任何项目均可用 --brand-color 覆盖成自家品牌色（见 design-tokens.md「如何取品牌色」）。
• 页眉自动标注「来源：文件名」，便于追溯原始文档。

幻灯片（deck）模式 —— 全屏翻页 PPT 风（浅色主题）

给 --deck 即输出一页一页翻的 HTML 幻灯片（不是往下滑的网页）。范式参考业界标杆
reveal.js（NASA/微软用于技术演示）：每个内容区块 = 一屏全屏 <section>，
用 ← → / 空格 / 方向箭头按钮 / 底部圆点 / 触屏滑动 / 鼠标滚轮翻页，带转场动画、F 全屏、@media print 可导出 PDF。
全程浅色主题：页面暖调浅底（暖白渐变）+ 白色幻灯片；品牌色仅用于强调（标题条、分隔页浅色调、KPI 强调），绝不使用深色大色块背景。

5 种翻页样式（--deck-style，默认 slide-h）：
| 值 | 效果 |
|---|---|
| slide-h | 横向滑动（默认） |
| slide-v | 纵向下翻（像卷轴往下） |
| fade | 淡入淡出（无位移） |
| zoom | 聚焦缩放（下一页从 0.9 放大入场） |
| flip | 3D 翻页（绕 Y 轴翻转） |

进度指示也跟着翻页样式自动换皮（每个版本长不一样，避免千篇一律的底部条）：
| --deck-style | 导航/进度样式 |
|---|---|
| slide-h | 顶部进度条 + 底部圆点 + 右下计数 |
| slide-v | 右侧数字索引（右侧竖向页码，窗口化渲染，永不溢出屏幕） |
| fade | 右上角标（03 / 17） |
| zoom | 左侧圆点 |
| flip | 底部中央胶囊（‹ 03 / 17 ›） |
左右索引样式下，翻页箭头自动移到底部两角，不与竖向索引重叠。

封面 kicker 可配置：meta.kicker 覆盖封面顶部小字（默认 一键生成美观可用的 HTML）；做通用展示时一般留默认即可，让成品不绑定任何具体业务。

内容模型 → 幻灯片映射：
- meta.title + date (+subtitle) → 封面页（浅色渐变 + 品牌色 kicker/大标题/分隔线）
- heading(≤2 级) → 分隔页（浅品牌色调背景 + 大号章节序号 + 品牌色标题）
- meta 末尾可加 end / 任意 heading → 用 {"type":"end","text":"感谢观看"} 生成封底页
- kpi → KPI 卡片屏（自适应栅格）；trend/bar/share/funnel/comparison → 单图大屏（每屏一个图表）
- 图表块可带 notes:[...] → 渲染为双栏（左图右要点），让图表页更有分析味
- paragraph 带 callout:true + big/text → 大数字 callout 屏（居中超大数字 + 说明）
- table → 宽表屏（自动 scale-to-fit 缩放适配屏宽，不溢出）
- insight / list → 要点屏（逐条 fragment 渐进出现，按 → 一条条展开）
- 注意：deck 模式下一屏一图表/一结论，刻意「一屏一个信息」，这是 PPT 的表达纪律；长文档用文档式更合适。

# 把数据日报渲染成可翻页幻灯片（横向滑动，默认；各风格自动取各自默认色）
python scripts/render_report.py --input 数据日报.json --deck --out 日报.deck.html
# 换成 3D 翻页 / 纵向下翻（自动用各自默认品牌色，五版长相各异）
python scripts/render_report.py --input 数据日报.json --deck --deck-style flip
python scripts/render_report.py --input 数据日报.json --deck --deck-style slide-v
# 想统一成自家品牌色时再覆盖：
python scripts/render_report.py --input 数据日报.json --deck --deck-style flip --brand-color #0B6E4F
# 内联 ECharts，离线也能翻看图表：
python scripts/render_report.py --input 季度复盘.pptx --deck --inline-echarts echarts.min.js

Design Tokens（让成果稳定的 6 层约束）

全部写进 scripts/report_template.html 的 :root，强制生效。详见 references/design-tokens.md：
1. 色彩：品牌色（token，仅装饰）+ 语义色（涨红 #E11D48/跌绿 #16A34A，A 股习惯锁死）+ 中性 5 级 + 分类 8 色。品牌色与涨跌语义严格分离。
2. 排版：system-ui 字体栈（零外部依赖）、字号阶梯 12/14/16/20/24/32、间距 scale、圆角、单级阴影。
3. 图表编码：share→环形、trend→折线、comparison→分组柱、bar→分类柱；配色顺序锁死；禁 3D/禁饼图/柱轴从 0。
4. 数据呈现：数字千分位/¥/万-亿缩写、百分比、日期 YYYY-MM-DD、空/单点/NaN 统一兜底。
5. 版式骨架：最大宽居中、页眉品牌条+标题+日期+来源+「由 AI 生成」、区块顺序随输入、响应式栅格；正文块（heading/paragraph/list）按层级排版，不入卡片。
6. 输出与无障碍：单文件自包含、CSS 内联、ECharts CDN（离线内联说明见下）、@media print A4、对比度≥4.5:1、非色依赖必带文字标签。

离线使用（内联 ECharts）

默认 ECharts 走 CDN。无网环境用 --inline-echarts 一键内联：

curl -fsSL https://cdn.jsdelivr.net/npm/echarts@5.5.0/dist/echarts.min.js -o echarts.min.js
python scripts/render_report.py --input 报告.md --inline-echarts echarts.min.js --out 报告.html

内联后成品为完全自包含单文件，断网也能看到图表。

版式健壮性（已加固，专为成品验收）

• 表格不乱：宽表自动套横向滚动容器 + 粘性表头；首列（分类名）可换行、数值列 nowrap 不挤压；min-width 保证不被压扁。
• 数值不重叠：KPI 大数字 clamp 自适应字号 + overflow-wrap 兜底；柱/折线轴标签超量时旋转/隐藏重叠；图表统一留白 grid。
• 颜色不乱：分类色板固定 8 色顺序循环，多序列不随机；占比环形图超过 8 切片归入「其他」（不再静默丢弃数据）；品牌色与涨红/跌绿语义色严格分离。
• 中文不乱码：<meta charset="utf-8"> + CJK 字体栈（PingFang SC/微软雅黑/思源等）+ JSON ensure_ascii=False 原样输出。
• deck 专有条理：全屏 100vw×100vh 不滚动（一屏一信息）；宽表 scale-to-fit 等比缩放适配屏宽不溢出；图表按所属屏懒resize，切屏尺寸准确；转场/动画尊重 prefers-reduced-motion；F 一键全屏、@media print 每屏一页导出 PDF。

文件

• scripts/render_report.py —— 解析层（按扩展名分发到各格式解析器）+ 渲染器 + 契约 schema 校验（渲染前字段级报错）
• scripts/report_template.html —— 文档式（report）模板：含 Design Tokens 与全部块渲染逻辑（ECharts）
• scripts/report_deck.html —— 幻灯片（deck）模板：全屏翻页版式与背景音乐开关逻辑
• references/design-tokens.md —— 6 层约束完整规范（含正文块排版）
• references/content-model.md —— 统一内容模型 block 类型字段规范
• references/contract-binding.md —— 契约与 ③ 标准分析契约的字段对齐 / 绑定说明

进阶 / 扩展（深入参考）

想进一步掌控产出，下面这些 references 是权威规范，按需查阅：

• references/content-model.md —— 所有 block 类型的字段清单（image / video / link / kpi / 各类图表…），写契约时照着填。
• references/contract-binding.md —— 本渲染器的统一内容模型 与 ③ 标准分析契约 的字段对应关系（直接吃 ③ 产物时可跳过）。
• references/design-tokens.md —— 6 层 Design Tokens 约束（色彩 / 排版 / 图表编码 / 数据呈现 / 版式 / 无障碍），要改视觉风格或自定义品牌色时看这里。
• 自定义品牌色：--brand-color #RRGGBB（deck 各翻页风格默认色各异，文档式默认靛蓝；详见 design-tokens.md「如何取品牌色」）。
• 离线自包含：--inline-echarts echarts.min.js 内联图表库，断网也能看图表。

更新记录

• v2.4.3（健壮性加固）：① JSON 注入 <script> 前转义 </ 防提前闭合/XSS；② 文本读取 GBK/GB18030 兜底；③ xlsx 公式无缓存值 + 多表静默丢弃 → 均改为明确告警；④ insight 支持纯字符串数组、顶层非对象 JSON 自动包裹；⑤ _to_num 支持 万/亿/万亿；⑥ 图表缺字段渲染「无数据」占位；⑦ KPI 数字 万/亿 缩写且整数不补 .00；⑧ 标题超长自动换行；⑨ Markdown 分隔符行跳过；⑩ 报告模板改用 {{ECHARTS_INLINE}} 占位（离线内联更健壮）。均配自动化测试（rv_test）。
• v2.5.0（媒体与链接）：① 修复 image 区块此前只画占位桩、不显示图片的 bug，现真正渲染 <img>（支持 http(s)/本地相对路径/base64 三态 + 加载失败降级）；② 新增 video 区块（<video controls>，三态地址）；③ 新增 link 区块（标题+描述+域名卡片，新窗口打开）；④ 段落/列表/洞察里的裸网址与 [文本](网址) markdown 链接自动变可点击超链接（安全转义、仅放行安全 scheme）；⑤ deck 风格支持 meta.bgm={src,title?} 全局背景音乐开关（默认关、可开关、循环播放）；⑥ 地址统一经 _safe_url/safeUrl 校验，拒绝 javascript: 等 XSS 向量。deck 与 report 两套渲染器同步支持。
• v2.5.1（评审驱动精进）：① 删除残留死文件 scripts/_deck.js（deck 逻辑早已内联进 report_deck.html）；② SKILL.md「文件」段补列 report_deck.html 与 contract-binding.md；③ 修正 auto_chart 表述（仅文档式 auto_chart:true 表格先出图，deck 模式 table 只渲染表格）；④ SKILL.md 新增「30 秒上手」最短路径 + 「进阶 / 扩展」专章（progressive 分层）；⑤ 渲染前新增契约 schema 字段级校验，type 拼错 / 字段缺失 / 危险地址会明确报错并定位到 sections[i].type=xxx；⑥ 修复 funnel 区块双端字段不一致（report 端 renderFunnel 此前只读 items，而 deck 端已兼容 stages/items，导致 report 模式下 stages 写法的漏斗为空），现 report 端也兼容两种命名，并修正 content-model.md 文档失真（funnel 字段实为 stages 或 items）。