web-video-presentation

Web Video Presentation

把一篇文章或口播稿，一步步做成可录屏的"伪装成网页的视频"，可选合成 口播音频。产出物 = Vite + React + TS 项目 + 按章节切分的音频。

对话式协作流程：分 4 阶段，阶段之间有必须停下来的 checkpoint。 agent 不能一头扎到底，关键节点必须等用户对齐再推进。

适用场景

• "我有口播稿 / 一篇文章，帮我做成视频" —— 口播驱动的内容
• 想做"动态 PPT，但不要像 PPT"
• 16:9 横屏录屏，大字、留白、每屏都要有动效
• 教学 / 产品演示 / keynote 想要电影感
• B 站 / YouTube / 视频号录屏类内容

本 Skill 以方法论 + 协作流程为核心。脚手架模板提供 token 和原语， 但每个美学决策（配色、字型、动效气质）都应该针对你的主题重新设计 —— 不要照搬。

---

工作流总览

Phase 1.1  识别用户输入
Phase 1.2  文章 → 口播稿（如果用户给的是文章）
   ▼
[Checkpoint A1]           ←  必须停。稿子 + 选主题 + 素材清单
   ▼
Phase 1.3  口播稿 + 文章 → outline.md（动画选型扣所选主题气质）
   ▼
[Checkpoint A2]           ←  必须停。outline 对齐 + 选开发模式
   ▼
Phase 2  网页开发         按所选模式推进（增量 / 一次性）
   ▼
[Checkpoint B]            ←  必须停。问是否合成音频
   ▼
Phase 3  音频合成（可选）  按 step 切分，默认 MiniMax CLI（mmx-cli）
   ▼
Phase 4  录屏 + 后期      参考 references/RECORDING.md

为什么把内容阶段切成两个 checkpoint：outline 里每步动画选型 强依赖主题的 motionHints。先选主题再写 outline，动画选型可以 直接锁死气质；倒过来 outline 在前主题在后，动画描述只能写得很"通 用"，开发阶段又得大量返工。

工作目录约定（agent 在用户当前目录下创建 / 编辑）：

my-video/
├── article.md          # 用户给原文时必有 —— 不删！开发阶段画面信息源
├── script.md           # 必有：B 站风格口播稿（决定节拍）
├── outline.md          # 必有：章节规划（决定 step / 动画 / 画面）
└── presentation/       # 脚手架产出的 Vite + React + TS 项目
    └── public/audio/   # 可选：合成的音频

article.md 不是临时文件。它是后续 outline 写动画 / 章节代码 实现画面时的画面信息密度来源（详见 PRINCIPLES.md 原则 10「双源 原则」）。

---

各阶段文件读取指南

不同阶段读不同的文件。长会话里 agent 容易遗忘原则，特别是 Phase 2.4 的"实现单章"会重复 N 次 —— 每次都要回看核心约束。

阶段	必读（每次都看）	一次性看完 / 按需查
Phase 1.2 文章 → 口播稿	references/SCRIPT-STYLE.md + article.md（用户原文）	——
Checkpoint A1 选主题	——	themes/*/theme.json（动态读全部，列清单 + bestFor 推荐 + motionHints）；references/THEMES.md（用户想了解主题系统时）
Phase 1.3 写 outline	script.md + article.md 全文 + references/OUTLINE-FORMAT.md + 选定主题的 themes/<id>/theme.json	——
Checkpoint A2 / Phase 2.1-2.3	——	SKILL.md 本节看一次
Phase 2.4 实现单章（×N 次）	references/PRINCIPLES.md（十条原则）+ references/CHAPTER-CRAFT.md（代码硬规则 + 视觉法则 + checklist）+ 当前主题的 themes/<id>/theme.json + 当前章节的 outline.md 段落 + article.md 本章对应段落 + 素材清单	references/EXAMPLES/（卡壳时翻 anchor）；references/THEMES.md 完整 token 契约
Phase 3 音频合成	references/AUDIO.md	——
Phase 4 录屏 + 后期	references/RECORDING.md	——
选 / 造 / 切主题	——	references/THEMES.md
卡壳找视觉灵感	——	references/PATTERNS.md 完全可选，不需要从中选

写章节时主要看 CHAPTER-CRAFT.md，原则速查回 PRINCIPLES.md。 不要去翻 THEMES.md 找 token —— CHAPTER-CRAFT.md Part 1 抄了精简版。

---

Phase 1 —— 内容编写

Phase 1 切成 三步 + 两个 checkpoint：1.1 / 1.2 → A1（稿子 + 主题 + 素材） → 1.3 → A2（outline + 模式）。

1.1 识别用户输入

用户给的东西	该做的
原始文章（书面语 / 公众号 / 论文 / 博客）	先转口播稿（1.2），过 A1，再生成 outline（1.3），过 A2
直接的口播稿 / 视频脚本	落盘成 script.md，直接进 A1，过 1.3，过 A2
啥都没有，只说"帮我做个 X 主题的视频"	反问：先给一段素材或大纲。Skill 不替用户构思内容

1.2 文章 → 口播稿

按 references/SCRIPT-STYLE.md 的规则 转写。落盘到 script.md，原文保留为 article.md（千万别删 —— 开发阶段画面密度要靠它，详见原则 10）。

落盘后进入 Checkpoint A1。

---

Checkpoint A1 —— 稿子 + 主题 + 素材（硬节点）

script.md 写完后必须停下来。outline 还没生成，因为 outline 里 的动画选型要等主题定了才能锁死气质。

agent 此时要做的预备工作：

1. 读所有 themes/*/theme.json 拿 nameZh / descriptionZh / bestFor / motionHints —— 不要硬编码清单
2. 根据 script.md 的内容类型 / 关键词 / 语气，主动从主题里 挑 2~3 套最匹配的推荐（匹配 bestFor 字段）
3. 扫一遍 script.md 估算粗略素材清单（精确版到 A2 再给）

总结模板（骨架，agent 按情况填充）

口播稿写完，产出文件：article.md（如有）+ script.md（{X} 字 / ~{T} 分钟）。

按 `---` 切的节拍块速览：
  • <节拍 1 主题>
  • <节拍 2 主题>
  • ...

接下来对齐 3 件事（outline 等你选完主题再写，动画选型要扣主题气质）：

  1. 稿子要不要改？（直接改 script.md 或口头告诉我）
  2. 选哪个主题？我的推荐：
     ★ <推荐 1：nameZh (id)> — 因为 <bestFor 命中>；motionHints: <摘要>
     ★ <推荐 2 / 推荐 3 同上>
     其它可选：<剩余主题，nameZh + 一句话>
     也可以让我帮你做新主题。
  3. 真素材怎么准备？粗看本视频要的图：<列粗略清单>
     a) 我从 <现有素材路径> 帮你挑   b) 你自己提供   c) 全部 placeholder

收到反馈后：

• 稿子要改：直接编辑文件，编辑完 ping 一次
• 主题选定：记录下来，1.3 写 outline 时打开对应 theme.json
• 素材选定：开发阶段按这个策略走

主题必须明确才进入 1.3。用户说"主题你帮我选" → 取你推荐的第 1 个， 告诉用户你选了什么、为什么，给个反悔机会。

---

1.3 口播稿 + 文章 → outline.md

前置条件：A1 已选定主题。没有主题就不要写 outline。 同时打开 script.md 和 article.md（如有）—— 双源对照写 （原则 10）。

双源工作法（核心）：

源	用来决定
script.md	节拍切分（--- 切节拍）/ 估时 / hero 标语
article.md	每个 step 的画面信息密度：数字 / 引用 / 对比 / 案例细节 / 图表数据点

每个 step 的画面要比口播节选信息密。如果画面只是把口播搬到屏幕 上 → 信息密度 = 0 → PPT 警报，重新去 article 抽细节挂上去。

写每个 step 的动画描述时，打开 themes/<id>/theme.json 看 motionHints —— 所有动作选型必须扣这条线（见 OUTLINE-FORMAT.md 的 「写动画的核心心法」节）。

通读 script.md → 按 --- 切节拍 → 切分章节（每章 3~8 step，可被 慢节奏主题覆盖）→ 对每个 step 翻 article 抽信息点 → 按 references/OUTLINE-FORMAT.md spec 落盘到 outline.md。

outline 阶段就要规划动画，每个 step 必须写：

1. 屏幕内容
2. 动画描述（主导 + 伴随 + 持续微动，扣主题 motionHints）
3. 实现手段（SVG / Canvas / filter / 自绘 ...）
4. article 补（双源原则 —— 从原文抽来的具体细节）

末尾列精确素材清单。详见 OUTLINE-FORMAT.md。

落盘后进入 Checkpoint A2。

---

Checkpoint A2 —— outline + 开发模式（硬节点）

outline 写完后必须停下来，让用户精读 outline 是否扣住主题气质 + 节奏 + 章节切分，再选开发模式。

总结模板

outline 写完了，基于主题 <theme nameZh>：

  📄 outline.md     {N} 章 / {M} 步 + 精确素材清单

章节速览：
  1. <id>     <章节标题>    <S> 步 ~<T>s
  2. ...

接下来对齐 2 件事：

  1. outline 要不要改？重点看：
     - 每步 3 行（屏幕内容 + 动画 + 手段）+ article 补
       的动画选型是否扣 <theme> 的 motionHints
     - 章节切分 / step 数 / 估时是否合理
     - 末尾素材清单是否完整
     可以直接编辑 outline.md，或口头告诉我。

  2. 开发模式选哪个？
     每章 = 完整版本一次到位（节奏 + 视觉 + 真素材 + 3 层动作齐全）。
     第 1 章是后续章节的视觉锚点。

     A) 增量：每章做完都暂停验收。**推荐** —— 风险可控
     B) 一次性：第 1 章做完暂停（样板对齐）→ 剩余章节一起做完再统一对齐

收到反馈后：outline 要改 → 编辑文件再 ping；模式选定 → 进 Phase 2。

---

Phase 2 —— 网页开发

2.1 脚手架

bash .cursor/skills/web-video-presentation/scripts/scaffold.sh \
  ./presentation \
  --theme=<用户选的主题 id>

bash .cursor/skills/web-video-presentation/scripts/scaffold.sh --list-themes

自定义主题 → 先按 references/THEMES.md "创作新主题"流程做一个 themes/<my-theme>/，再 --theme=<my-theme>。

2.2 删除示例章节

脚手架带一个 01-example demo。在写第一章真实内容前删掉：

rm -rf presentation/src/chapters/01-example

并把 presentation/src/registry/chapters.ts 里 EXAMPLE_CHAPTER 的 import 和数组项移除。

2.3 按所选模式推进

核心：每章 = 完整版本一次到位（节奏 + 视觉 + 真素材 + 3 层动作 全部到位）。没有"骨架版"概念 —— 第一章就要做出用户能直接验收 并作为后续锚点的样板。

增量模式（默认推荐）

1. 实现第 1 章 = 完整版本 → 暂停 → 用户在 localhost 验收节奏 + 视觉气质（这一步对齐量最大，第 1 章是后续所有章的视觉锚点）
2. 用户 OK → 实现第 2 章 = 完整版本 → 暂停 → 验收
3. 重复直到所有章完成
4. Checkpoint B

一次性模式

1. 实现第 1 章（样板）→ 暂停 → 对齐节奏 + 视觉气质
2. 用户 OK → 一次性实现剩余所有章节 → 暂停 → 整体对齐
3. Checkpoint B（只对齐 2 次）

为什么不分骨架 / 精修两步：骨架版根本看不出节奏对不对（画面是 死的），用户也不知道视觉气质走哪个方向。第一章一次到位反而更清晰。 代价是第 1 章会写得稍久 —— 值得。

2.4 实现单章

详细流程见 references/CHAPTER-CRAFT.md （开工 checklist + 视觉法则 + 完工自检 + 反馈速查）。

简版要点：

1. 走 CHAPTER-CRAFT.md 开工 checklist（重读 PRINCIPLES.md）
2. 抄 outline.md 中本章 step 清单 + 翻 article 本章段抽信息点
3. 核对真素材是否到位；缺的用 [image: 16:9 描述] 占位卡
4. 按当前主题 theme.json 的 motionHints / motionDuration / typeScale 选动画与字号
5. 每步 3 层动作齐全（主导 + 伴随 + 持续微动 —— 缺哪个都是 PPT， 见 PRINCIPLES.md 原则 7）
6. CSS 100% 用语义 token；if (step === N) return <SceneN />， key={step} 重挂动画
7. 在 src/registry/chapters.ts 注册章节
8. 跑 npm run dev 浏览器点一遍，做完工自检
9. 暂停 → 让用户在 localhost 验收

2.5 大改后 bump STORAGE_KEY

改动 chapters.ts（增加 / 删除 / 重排章节，或某章 totalSteps 变化） 后，bump presentation/src/hooks/useStepper.ts 的 STORAGE_KEY （如 v3 → v4），避免持久化游标落到不存在的 step 上。

---

Checkpoint B —— 是否合成音频（硬节点）

Phase 2 结束后必须停下来，问用户：

网页做完，{N} 章 {M} 步，dev server 在 localhost:5173 跑着。

要不要把口播稿合成音频？
  ✓ 合成 → 我会按 outline.md 切分，每步一个 mp3 到 public/audio/。
           默认 MiniMax CLI（mmx-cli）；本机没装会问你用什么 TTS。
  ✗ 不合成 → 流程结束，后期你自己配音 / 用别的工具。

要合成 → Phase 3。不合成 → 进入 Phase 4 录屏指引。

---

Phase 3 —— 音频合成（可选）

详见 references/AUDIO.md（MiniMax CLI 检测 / 调用、按 step 切分、用户自带 TTS 退化路径、故障排查）。

合成完后告诉用户：输出位置 / 总时长 / 哪些 step 稿子可能太长太短 —— 给最后一次校准节奏的机会。然后进入 Phase 4。

---

Phase 4 —— 录屏 + 后期

完整自动化合成 mp4 当前未实现，标作 roadmap。手动录屏 + 后期对音频 的标准路径详见 references/RECORDING.md。

agent 应主动告诉用户这条路径，让用户知道下一步怎么把网页变成 mp4。

---

十条原则（一句话清单）

完整展开见 references/PRINCIPLES.md —— 写章节时回那里查，下面只是索引。

#	原则	一句话
1	16:9 固定舞台	内容 1920×1080 + transform scale，没有响应式
2	全局 step 计数器	章节是 step 的纯函数，无定时器
3	每步独占整屏	if (step === N) return <FullScene />
4	口播节拍 = step	一节拍 = 一 step = 一聚焦想法
5	隐藏的边角控件	进度条 / 翻页器默认 opacity 0
6	舞台无 chrome	没有 header / footer / 页码 / 品牌条
7	每步 3 层动作	主导 + 伴随 + 持续微动，缺哪层都是 PPT
8	多点逐个揭示	1 项 = 1 step，禁同步 stagger 上 N 项
9	整片同一主题	章节间不翻表面色；CSS 全 token
10	双源原则	script 定节拍，article 定画面密度

---

常见用户反馈速查

简化表见 references/CHAPTER-CRAFT.md Part 6「常见反馈速查」。关键：先定位是哪一层（节奏 / 视觉 / 内容 / 代码），再改最小切片，不要重做整章。

---

相关资源

按"何时读"标注，避免一次性全读：

文件	何时读	内容
references/PRINCIPLES.md	十条原则唯一展开点，章节开发时查	完整十条原则 + 派生约束
references/SCRIPT-STYLE.md	Phase 1.2 必读	文章 → 口播稿规则、平台变体
references/OUTLINE-FORMAT.md	Phase 1.3 必读	outline.md 字段 spec、命名约定、章节切分
references/CHAPTER-CRAFT.md	Phase 2.4 每章必读	代码硬规则、视觉法则、token 速查、checklist、反馈速查
references/EXAMPLES/	Phase 2.4 卡壳时翻	章节 anchor（hook 钩子型 / list 列举型）+ 题材 case（科技测评）
references/THEMES.md	选 / 造 / 切主题时	完整 token 契约 + 内置主题清单 + 创作流程
references/AUDIO.md	Phase 3 才读	MiniMax CLI、TTS 退化路径、故障排查
references/RECORDING.md	Phase 4 才读	录屏工具 + 后期合成
references/PATTERNS.md	可选灵感库	11 个常用视觉原语，不是必选清单
themes/	A1 / 1.3 时翻	内置主题（每个含 theme.json + tokens.css）
scripts/scaffold.sh	Phase 2.1 跑一次	一键项目脚手架