HTML Interactive Presentation

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

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

适用场景

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

兼容 Agent

工作流总览

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 识别用户输入

1.2 一次产出 script.md + outline.md

script.md 规则（B 站风口播稿）：

• 信息保留度 ≥ 60%（字数对比）
• 口语化、短句（≤ 20 字）、第二人称
• 开头 3 秒钩子
• 数字翻译成感受
• 不用首先/其次/最后结构词
• 不用"说白了/本质上/底层逻辑"等 AI 味模板
• 不堆排比
• 末尾具体 CTA

outline.md 结构：

# Video Outline

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

## 1. <chapter-id> — 标题（S steps · ~Ts）

**信息池**（回 article.md 抽细节）：
- 数字/引用/案例...

**开发计划**：
- step 1 (~Ts) — 屏幕内容描述
- step 2 (~Ts) — ...

口播节选：
> ...

outline 原则：

• 每章 38 步，每章 3060s
• outline 不写动画（留给章节开发时自由设计）
• 每章首段必须有「信息池」block

Checkpoint Plan —— 5 件事一次对齐

产出 script.md + outline.md 后必须停。一次确认：

1. 稿子要不要改？
2. 开发计划章节切分 / step 数合理吗？
3. 选哪个主题？ 内置主题：
   • blueprint（蓝图 / 深藏青色 + 青色 / 工程气质）
   • paper-press（亮色印刷 / 暖色奶油底 / 杂志风）
   • monochrome-print（黑白印刷 / 高对比 / 学术）
   • terminal-green（终端绿 / 黑客风 / 技术演示）
   • midnight-press（午夜印刷 / 深色 / 奢华）
   • chalk-garden（粉笔花园 / 柔和 / 自然）
   • 其它见 theme 清单
4. 素材用 MiniMax CLI 生成配图，还是用户提供？
5. 开发模式：A) 逐章确认（推荐）B) 顺序开发 C) 并行开发

Phase 2 —— 网页开发

2.1 脚手架

bash <skill-path>/scripts/scaffold.sh ./presentation --theme=<selected-theme>

脚手架产出 Vite + React + TS 项目，含：

• 16:9 固定舞台（1920×1080）
• 全局 step 计数器
• 隐形进度条 + 三种播放模式
• 音频流水线（extract-narrations + synthesize-audio）

2.2 章节开发

每章一个独立目录 src/chapters/<NN>-<chapter-id>/，包含：

• <Chapter>.tsx — React 组件，每个 step 返回一屏内容
• <Chapter>.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 —— 多模态生产

没有 MiniMax API 怎么办？ 图片和音频各自有降级路径，见下方"降级方案"。

3.1 配图

cd presentation
mmx image "<描述>" && mv image_001.jpg public/img/<name>.jpg

建议配图：

• 冷开场背景（技术蓝图风格）
• 信息密度对比图
• 三优势概念图
• 每章特色配图

3.2 口播合成

cd presentation
npm run extract-narrations    # 扫 narrations.ts → audio-segments.json
bash scripts/synthesize-audio.sh  # mmx speech 逐段合成 mp3

输出到 public/audio/<chapter-id>/<N>.mp3，自动跳过已存在的文件。

降级方案（没有 MiniMax API 时）

配图降级

规则：

• 生成图片控制在 2~4 张关键配图，不要每章都生
• 核心视觉靠 CSS / SVG 动画（字号、网格、边框、虚线），配图只是氛围装饰
• 没有就承认没有，placeholder 比编造好

口播降级

无需改代码 —— 替换 synthesize-audio.sh 中调用 mmx speech synthesize 那一行即可，文件输出路径不变。

不影响的功能

• ✅ 网页浏览（手动翻页 / 带声翻页）
• ✅ CSS / SVG / Canvas 视觉演示
• ✅ 主题切换
• ✅ 自动构建部署

Phase 4 —— 构建产出

cd presentation
npx vite build

输出 presentation/dist/ 为纯静态页面，可部署到任何静态托管服务。

三种播放模式

用户点击右下角按钮或按 M 键循环切换。

相关资源

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