HTML Interactive Presentation — HTML 交互式演示

HTML Interactive Presentation 将一篇 Markdown 文章（技术博客、产品文档、知识笔记）转化为可交互、可播放的 16:9 理解界面。产出一个 Vite + React + TS 项目，带有：

分章分步的点击导航 多模态配图（MiniMax CLI 生成） 逐段口播音频（MiniMax TTS 合成） 自动播放、手动翻页、带声翻页三种模式 可选 Architecture Blueprint / Paper Press / Monochrome 等多种主题

适用场景： 技术文章想做成可播放的交互文档 学习笔记想加点"视频感" 产品文档想让人愿意读完 * 跟原有的静态 HTML 版本做效果对比

工作流总览：

Phase 1 内容准备

1.1 识别用户输入（原文 markdown / 已有 script） 1.2 一次产出 script.md + outline.md ▼ [Checkpoint Plan] 5 件事一次对齐：稿子 / outline / 主题 / 素材 / 开发模式 ▼

Phase 2 网页开发（16:9 点击驱动）

2.1 从模板脚手架（可选主题） 2.2 第 1 章 = 主线程 + 完整版（强制验收） 2.3 第 2~N 章（逐章 / 顺序 / 并行） ▼

Phase 3 多模态生产

3.1 用 mmx image 生成配图 3.2 用 npm run extract-narrations + mmx speech synthesize 合成口播 ▼

Phase 4 build 产出

4.1 vite build 4.2 输出 dist/ 目录，可部署为静态页面

工作目录约定： my-project/ ├── article.md # 用户给的原始文章 ├── script.md # 口播稿（B 站风格） ├── outline.md # 开发计划 └── presentation/ # Vite + React + TS 项目（脚手架产出） ├── src/ │ ├── chapters/ # 每章独立目录 │ ├── components/ # 舞台 / 进度条 / 模式切换 │ ├── hooks/ # useStepper / useAutoMode / useAudioPlayer │ ├── registry/ # chapters.ts 注册 │ └── styles/ # 主题 tokens ├── public/ │ ├── img/ # MiniMax 生成的配图 │ └── audio/ # MiniMax 合成的口播 └── dist/ # 最终静态 HTML 产出

Phase 1 —— 内容准备 1.1 识别用户输入 用户给的东西 该做的 原始 markdown 文章 一次产出 script.md + outline.md（1.2） 已有口播稿 / 视频脚本 落盘为 script.md，一次产出 outline.md 已有《The Unreasonable Effectiveness of HTML》风格文章 参考 SCRIPT-STYLE.md 做转写 1.2 一次产出 script.md + outline.md script.md 规则（B 站风口播稿）： 信息保留度 ≥ 60%（字数对比） 口语化、短句（≤ 20 字）、第二人称 开头 3 秒钩子 数字翻译成感受 不用首先/其次/最后结构词 不用"说白了/本质上/底层逻辑"等 AI 味模板 不堆排比 末尾具体 CTA outline.md 结构： # Video Outline

主题：blueprint
总时长：约 X 分
章节数：N 章 / M 步

1. — 标题（S steps · ~Ts）

信息池（回 article.md 抽细节）：

• 数字/引用/案例...

开发计划：

• step 1 (~Ts) — 屏幕内容描述
• step 2 (~Ts) — ...

口播节选：

...

outline 原则： 每章 38 步，每章 3060s outline 不写动画（留给章节开发时自由设计） 每章首段必须有「信息池」block Checkpoint Plan —— 5 件事一次对齐 产出 script.md + outline.md 后必须停。 一次确认： 稿子要不要改？ 开发计划章节切分 / step 数合理吗？ 选哪个主题？ 内置主题： blueprint（蓝图 / 深藏青色 + 青色 / 工程气质） paper-press（亮色印刷 / 暖色奶油底 / 杂志风） monochrome-print（黑白印刷 / 高对比 / 学术） terminal-green（终端绿 / 黑客风 / 技术演示） midnight-press（午夜印刷 / 深色 / 奢华） chalk-garden（粉笔花园 / 柔和 / 自然） 其它见 theme 清单 素材用 MiniMax CLI 生成配图，还是用户提供？ 开发模式： A) 逐章确认（推荐） B) 顺序开发 C) 并行开发

Phase 2 —— 网页开发 2.1 脚手架 bash /scripts/scaffold.sh ./presentation --theme= 脚手架产出 Vite + React + TS 项目，含： 16:9 固定舞台（1920×1080） 全局 step 计数器 隐形进度条 + 三种播放模式 音频流水线（extract-narrations + synthesize-audio） 2.2 章节开发 每章一个独立目录 src/chapters/-/，包含： .tsx — React 组件，每个 step 返回一屏内容 .css — 章节样式（CSS 类前缀如 .co- / .wh-） narrations.ts — 口播文本数组，长度 = step 数 视觉原则： 每章至少 1~2 处 CSS / SVG / Canvas 视觉演示 列表项逐步揭示（1 项 = 1 step） 颜色字体走主题 token，禁硬编码 缺素材用 placeholder，不用 fake 动画时长 ≤ 口播时长 代码红线： 不用 setTimeout / setInterval 驱动动画 交互元素加 data-no-advance 每章独立 CSS 前缀，不跨章 import narrations.length === 最大 step + 1 2.3 更新注册 编辑 src/registry/chapters.ts，按顺序注册所有章节。 2.4 bump STORAGE_KEY 改完 chapters.ts 后 bump useStepper.ts 中的 STORAGE_KEY。

Phase 3 —— 多模态生产 3.1 MiniMax 配图 cd presentation mmx image "<描述>" && mv image_001.jpg public/img/.jpg 建议配图： 冷开场背景（技术蓝图风格） 信息密度对比图 三优势概念图 每章特色配图 3.2 MiniMax 口播合成 cd presentation npm run extract-narrations # 扫 narrations.ts → audio-segments.json bash scripts/synthesize-audio.sh # mmx speech 逐段合成 mp3 输出到 public/audio//.mp3，自动跳过已存在的文件。

Phase 4 —— 构建产出 cd presentation npx vite build 输出 presentation/dist/ 为纯静态页面，可部署到任何静态托管服务。

三种播放模式 模式 行为 手动翻页 点击 / 空格翻页，无音频 带声翻页 每步播放口播，手动翻页 自动播放 口播自动播 + 播完自动翻页 用户点击右下角按钮或按 M 键循环切换。

相关资源 脚手架 scripts/scaffold.sh 音频提取脚本 scripts/extract-narrations.ts 音频合成脚本 scripts/synthesize-audio.sh 基于 web-video-presentation 技能体系