create-yss-spec 1.0.0

package/template/.hermes/skills/web-video-presentation/references/AUDIO.md

@@ -0,0 +1,276 @@
+# 音频合成
+
+把每个章节 `narrations.ts` 里的口播文字按 **step 颗粒度**合成 mp3，
+落到 `presentation/public/audio/<chapter-id>/<step-N>.mp3`。运行时
+Auto 模式会自动按 step 播放并自动推进——录屏可以一镜到底。
+
+> **真相源**：每个章节的 `src/chapters/<NN>-<id>/narrations.ts` 是 step
+> 数 + 口播文本的**唯一来源**。`outline.md` 不再参与音频合成，章节代码
+> 也不再手写 `totalSteps`。这一改根除了"网页 step 和音频文件数对不上"
+> 这个老问题。
+
+合成器是 **provider-agnostic** 的：runner 本身不绑定任何 TTS 后端，每个
+后端是 `scripts/tts-providers/<name>.sh` 一个文件。**内置 2 个 provider**：
+
+| Provider | 默认 | 何时用 |
+|---|---|---|
+| `minimax` | ✓ | 中文口播首选（用 `mmx-cli`，要 MiniMax API key） |
+| `openai`  | —— | 多数 agent 已有 `OPENAI_API_KEY`；curl-based、响应快 |
+
+换 / 加 provider 见
+[`scripts/tts-providers/README.md`](../templates/scripts/tts-providers/README.md)
+（脚手架跑完后路径是 `presentation/scripts/tts-providers/README.md`）。
+README 里还附了 5 套**可粘贴**的现成片段（ElevenLabs / edge-tts / macOS say /
+Azure / Google Cloud）和写自定义 provider 的三函数契约。
+
+---
+
+## 文件命名约定
+
+```
+presentation/public/audio/
+├── coldopen/
+│   ├── 1.mp3
+│   ├── 2.mp3
+│   └── ...
+├── hook/
+│   └── ...
+└── ...
+```
+
+- 章节子目录名 = `chapters.ts` 里的 `id`
+- 文件名 = `<step-N>.mp3`（**1-indexed**，对齐 narrations 数组的 index + 1）
+- 格式默认 mp3。如果你写的 provider 只能出 wav，在函数里加一步 `ffmpeg`
+  转 mp3（参见 `tts-providers/README.md` 的 `say.sh` 示例）
+
+---
+
+## 标准流程
+
+### 1. 抽取 segments
+
+```bash
+cd presentation
+npm run extract-narrations
+```
+
+这会扫所有章节的 `narrations.ts`，按 `chapters.ts` 注册顺序生成
+`audio-segments.json`：
+
+```json
+[
+  { "chapter": "coldopen", "step": 1, "text": "...", "audio": "coldopen/1.mp3" },
+  { "chapter": "coldopen", "step": 2, "text": "...", "audio": "coldopen/2.mp3" },
+  ...
+]
+```
+
+让用户**先扫一眼这个 json**，确认文本和切分都对，再开始烧 token 合成。
+
+> 空字符串的 narration 会被自动跳过（不烧 TTS token）——运行时 Auto 模式
+> 按字数估时撑过这种"无声过场"step。
+
+### 2. 选 provider
+
+```bash
+ls scripts/tts-providers/    # 看本项目带了哪些
+```
+
+- 用默认 `minimax` → 走 [2.A](#2a-用内置-minimax-合成)
+- 用内置 `openai` → 走 [2.B](#2b-用内置-openai-合成)
+- 想用别的 TTS / 自带 TTS → 走 [2.C](#2c-换-provider--加自定义-provider)
+- 一个都没装好 → 走 [2.D](#2d-退化路径)
+
+#### 2.A 用内置 minimax 合成
+
+```bash
+npm run synthesize-audio              # 增量：跳过已存在的 mp3
+npm run synthesize-audio -- --force   # 全部重合成
+npm run synthesize-audio -- --voice=<voice-id>  # 指定音色
+```
+
+启动时 runner 会先调 provider 的 `tts_check`：
+
+- mmx 未安装 → 报 `mmx CLI not found in PATH`，并打印安装说明
+- mmx 未登录 → 报 `mmx is not authenticated`，并提示登录命令
+
+修完再跑。每条段打印进度：
+
+```
+[  3/24] coldopen/3.mp3   ✓ 4s
+[  4/24] coldopen/4.mp3   skip (exists)
+```
+
+合成串行（避免 rate limit），**自动跳过已存在文件**（断点续合，不烧
+重复 token）。
+
+#### 2.B 用内置 openai 合成
+
+```bash
+export OPENAI_API_KEY=sk-...                   # 在 platform.openai.com 拿
+PRESENTATION_TTS=openai npm run synthesize-audio
+# 换音色 + HD 模型
+OPENAI_TTS_MODEL=tts-1-hd PRESENTATION_TTS=openai \
+  npm run synthesize-audio -- --voice=nova
+```
+
+可选 env：
+
+| 变量 | 默认 | 作用 |
+|---|---|---|
+| `OPENAI_API_KEY` | —— **必须** | API key |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | 切代理 / Azure-OpenAI |
+| `OPENAI_TTS_MODEL` | `tts-1` | `tts-1` 快 / `tts-1-hd` 高质量约 2× 价 |
+| `--voice=` / `PRESENTATION_TTS_VOICE` | `alloy` | 可选 alloy / echo / fable / onyx / nova / shimmer |
+
+`tts_check` 会检查 curl / jq / `OPENAI_API_KEY` 三件套，缺哪个报哪个。
+
+#### 2.C 换 provider / 加自定义 provider
+
+内置之外的常见后端在 `scripts/tts-providers/README.md` 里有 5 段
+**可粘贴**代码片段（ElevenLabs / edge-tts / macOS `say` / Azure / Google
+Cloud）。
+
+挑一个 → 复制 README 里的代码块 → 保存为
+`scripts/tts-providers/<name>.sh` → 设好环境变量 → 切换 provider 跑：
+
+```bash
+PRESENTATION_TTS=elevenlabs npm run synthesize-audio
+# 或
+npm run synthesize-audio -- --provider=edge-tts
+```
+
+如果用户的 TTS 完全自研，**按三函数契约**写一个 `<name>.sh` 即可：
+
+| 函数 | 必需 | 作用 |
+|---|---|---|
+| `tts_synthesize <text> <out_path> [<voice>]` | ✓ | 把一段文字写成 mp3 到指定路径 |
+| `tts_check` | 可选 | 启动时校验环境（CLI / key / auth），未就绪 return 非零 |
+| `tts_install_help` | 可选 | `tts_check` 失败时打印怎么修 |
+
+抄 `openai.sh`（HTTP-based）或 `minimax.sh`（CLI-based）起手最快。
+详细规范在 `scripts/tts-providers/README.md`。
+
+#### 2.D 退化路径
+
+如果两个内置 provider 都没就绪（没装 mmx 也没有 OpenAI key）告诉用户：
+
+```
+我可以：
+
+  1. 用内置 openai provider（如果你已有 OpenAI key）
+     export OPENAI_API_KEY=sk-...
+     PRESENTATION_TTS=openai npm run synthesize-audio
+
+  2. 帮你装 MiniMax CLI（默认 provider，中文音色更稳）
+     npm install -g mmx-cli && mmx auth login --api-key sk-xxxxx
+     API key 在 https://platform.minimaxi.com 获取
+
+  3. 换其它 provider
+     scripts/tts-providers/README.md 里有 5 种现成代码片段：
+       • ElevenLabs  (要 ELEVENLABS_API_KEY，英文音色最佳)
+       • edge-tts    (免费 / 无 key / pip install edge-tts)
+       • macOS say   (零依赖离线，质量一般，适合预览)
+       • Azure       (要 AZURE_SPEECH_KEY)
+       • Google      (要 gcloud auth)
+     复制一段保存成 tts-providers/<name>.sh，
+     再 PRESENTATION_TTS=<name> npm run synthesize-audio
+
+  4. 暂时跳过
+     稿子和 narrations 都在，你自己用任意 TTS 录制即可——文件
+     按 audio-segments.json 的 audio 字段命名就行。
+```
+
+不要假装合成成功。
+
+---
+
+## 校验时长
+
+合成完后跑：
+
+```bash
+for f in public/audio/*/*.mp3; do
+  d=$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$f")
+  echo "$f  ${d}s"
+done
+```
+
+把每条的实际秒数汇总告诉用户。**重点关注 ≥ 15s 的条目**——口播太长意味
+着该 step 的 narration 写得过密，或者 step 没拆够。让用户决定**改稿子
+重合**还是**回章节代码拆 step**。
+
+---
+
+## 运行时如何使用合成的音频
+
+合成完成后，**不需要任何额外配置**——脚手架的 `App.tsx` 已经接好：
+
+| 模式 | 触发方式 | 行为 |
+|---|---|---|
+| **Manual**（默认） | 直接打开页面 | 不播音频，点击 / 方向键推进 |
+| **Audio**（半自动） | URL `?audio=1` 或按 `M` 键 | 进入 step 自动播音频，但你手动推进（点鼠标） |
+| **Auto**（全自动） | URL `?auto=1` 或按两次 `M` 键 | 进入 step 播音频 → 播完自动 next() → 进下个 step → ... |
+
+Auto 模式首次需要按一次 `Space` 启动（绕过浏览器自动播放限制），之后
+全自动跑。**录屏时打开屏幕录制 → 按 Space → 整片自动跑完 → stop**。
+
+> **Auto 模式的推进规则就一句话**：每段音频播完 + 200ms 缓冲 → 自动 next。
+> **没有"等动画跑完"的兜底**——如果你写的视觉动画比口播长，会被当场切。
+> 解决办法：写更长口播 / 拆 step / 调动画速度（详见
+> [`CHAPTER-CRAFT.md`](CHAPTER-CRAFT.md) 「代码层最小约束」）。
+>
+> 音频文件缺失（还没合成 / 404）或 narration 是空串 → 退化到字数估时
+> （`max(1500ms, 字数 × 250ms)`），保证预览也能整片跑通。
+
+---
+
+## 故障排查
+
+通用：
+
+| 现象 | 原因 / 修法 |
+|---|---|
+| `chapter id "X" registered but no matching folder found` | 章节文件夹应命名为 `NN-<id>`；id 必须等于 chapters.ts 里注册的 |
+| `narrations.ts in X must export an array named "narrations"` | 该章节的 narrations.ts 没 export 名为 narrations 的数组 |
+| `TTS provider 'X' not found` | `scripts/tts-providers/X.sh` 不存在；列出来看哪些可用，或抄 README 加一个 |
+| `provider 'X' does not define tts_synthesize` | 你的 `<X>.sh` 没定义必需的函数。看 README 的契约部分 |
+| 中间断了几条没合成 | `npm run synthesize-audio` 重跑 —— 已存在文件会跳过 |
+| 浏览器没播音频 | Auto / Audio 模式下首次需要用户手势——确认你按了 SPACE 启动 Auto，或者点过页面 |
+| 音频 404 但 Auto 模式还能跑 | 找不到 mp3 时 useAudioPlayer 退化到字数估时（4 字/秒），保证预览不中断 |
+
+minimax 专属：
+
+| 现象 | 原因 / 修法 |
+|---|---|
+| `mmx: command not found` | `npm install -g mmx-cli`；npm 全局 bin 不在 PATH 时 `npm config get prefix` 看一下 |
+| `mmx is not authenticated` | `mmx auth login --api-key sk-xxxxx` 重新登录 |
+| 中文音色不自然 | mmx 默认音色未必最佳；查 `mmx speech --help` 看 `--voice` 可选项，传 `--voice=<id>` |
+| 整段合成被截断 | 单段过长（mmx 默认上限约 5000 字符）。在 narrations.ts 里把这条拆成两条（也意味着该 step 应该拆成两个 step） |
+
+openai 专属：
+
+| 现象 | 原因 / 修法 |
+|---|---|
+| `OPENAI_API_KEY is not set` | `export OPENAI_API_KEY=sk-...`，或者把它加到 shell rc / `.env` |
+| 全部段 FAILED + key 是对的 | 多半 model / voice 名字错。`--voice=alloy` 试默认值；`OPENAI_TTS_MODEL=tts-1` 试默认模型；用 `bash -x scripts/synthesize-audio.sh` 看请求体 |
+| 走代理 / 走 Azure-OpenAI | `export OPENAI_BASE_URL=https://your-proxy/v1` |
+| HD 太慢 | 改成 `OPENAI_TTS_MODEL=tts-1`（默认）；HD 大约慢 2 倍 |
+| 中文音色不像真人 | OpenAI 6 种音色都是英语偏向；中文角色用 `minimax` 更合适 |
+
+换其它（自定义）provider 之后：
+
+| 现象 | 原因 / 修法 |
+|---|---|
+| `<X>_API_KEY not set` | 你的 provider 需要 API key，但 env 里没设。`export <X>_API_KEY=...` 或写到 `.env` 再 `set -a; source .env; set +a` |
+| 合成的 mp3 浏览器播不了 | 检查 provider 是否真的出了 mp3（不是 wav / opus / aac）。`file public/audio/*/*.mp3` 看 magic header |
+| 一切看起来都对，但全部 FAILED | `bash -x scripts/synthesize-audio.sh` 看每段实际调了什么 |
+
+---
+
+## 相关链接
+
+- Provider 契约 + 现成片段：[`scripts/tts-providers/README.md`](../templates/scripts/tts-providers/README.md)
+- mmx-cli 仓库：<https://github.com/MiniMax-AI/cli>
+- mmx 官方文档：<https://platform.minimaxi.com/docs/token-plan/minimax-cli>
+- mmx 参数 / 音色查询：`mmx speech --help`

package/template/.hermes/skills/web-video-presentation/references/CHAPTER-CRAFT.md

@@ -0,0 +1,224 @@
+# 章节开发指引（每章开发必读）
+
+---
+
+## 这是视频，不是 PPT
+
+正在做的是**视频网页** —— 讲者点击 + 口播 + 录屏发出去给观众看。
+判断每一步做对没有，标准非常朴素：
+
+- **不像 PPT** —— 观众感觉是在看视频，不是在看翻页幻灯（页面中不得包含页眉页脚，突出主视觉元素）
+- **看起来舒服** —— 配色、字体、节奏都让人放松，不得出现大量的纯文字、不得出现字体太小的文字
+- **有视觉冲击** —— 画面在演事情，不只是文字堆砌，不得一次性全部罗列所有元素，关键元素随进度逐步推进展现
+
+---
+
+## 必须用 CSS / SVG / Canvas / JS 大胆绘制视觉演示
+
+> **这是底线。**
+>
+> 每一章都至少要有 1~2 处"动起来的图 / 演示元素"。
+> **整章只有纯文字 = 验收不过 = 回去重做。**
+
+视频感最强的来源 —— 用户**看见**了被讲解的东西在屏幕上演给他看：
+
+- 数字在递增 / 横条在生长 / 排名在交换
+- 流程节点依次点亮 / 连线自绘
+- 对比被一刀切开 / 聚光灯扫过 / 形状在变形
+- 粒子聚拢成形 / 噪声背景流动 / 字符雨下落
+- 模拟终端交互
+- 模拟 AI 对话窗口
+- 模拟文件目录树
+
+**怎么组合发挥都行 —— 但每章必须用，不允许整章纯文字。**
+
+---
+
+## 逐步揭示，禁止一次全展示
+
+整页内容由**全局 `step` 计数器**驱动 —— 点击空白处或按 → 键推进
+一步。设计每一步时心里要默念：**这一步演什么，下一步演什么**。
+
+**最重要的一条**：
+
+> 当口播在说"第一是 X、第二是 Y、第三是 Z"这种**清单 / 列表**时，
+> **严禁**一个 step 把 X / Y / Z 全部 stagger 上来。
+
+正确做法：
+
+- 一项 = 一个 step
+- X 只在它自己的 step 里独自亮起
+- 讲到 Y 时，X 灰化保留作上下文 + Y 亮起
+- 讲到 Z 时，X / Y 都灰化 + Z 亮起
+
+**判断标准**：讲者会一个一个念出来吗？会 → 必须逐个揭示。
+
+---
+
+## 内容取舍：抓重点，不要原文搬运
+
+视频是**音 + 画**：
+
+- **口播**负责把信息线性讲清楚
+- **画面**负责把节拍重点放大、节奏感拉出来
+
+每个 step 屏幕上只挂这个节拍**最值得放大的 1~3 个东西** —— 一个
+hero 标语 / 一个数字 / 一组对比 + 必要的视觉演示。
+
+不要试图把原文每个字都搬上去。那是论文阅读，不是视频。
+
+---
+
+## 双源：节奏跟口播稿，细节回原文章
+
+> **节奏 / 顺序 / 节拍切分** 跟 **`script.md` 口播稿** —— **关键顺序不能乱**。
+> **画面细节 / 数据 / 引用 / 案例** 回 **`article.md` 原文章**抽。
+
+`outline.md` 已经在每章首段抽了「信息池」做参考。但**实现章节时
+也必须回去翻 `article.md` 本章对应段落** —— 那里有比口播稿多得多的
+细节（具体数字、引用原话、案例维度、出处时间）。把这些挂到画面上，
+让**画面信息密度 > 口播信息密度**。
+
+> **如果你只用了口播稿的内容做章节** —— 屏幕等于把口播打字打了一遍
+> —— 那就是 PPT，不是视频。
+>
+> 章节实现一定要回原始文章抽细节，不要嫌麻烦。
+
+---
+
+## 字体 / 配色 / 动画 / 留白 —— 视频演示基本审美
+
+视频观众离屏幕远、注意力浮动，所以：
+
+- **字号要大** —— hero 文字至少 80px 起，远观也能看清
+- **留白要多** —— 舞台四边都要让出大留白，画面不要塞满
+- **配色要舒服** —— **颜色和字体家族必须用主题 token**（保证换主题不破）；
+  字号 / 间距 / 时长这些章节按内容自由发挥（详见下方「代码层最小约束」）
+- **动画要舒服 + 炫酷** —— 出现得干净利落，停下来不抢戏；炫酷靠
+  **设计巧思**（内容驱动的演示动画），不靠**速度暴力**或**密集闪烁**
+
+---
+
+## 避免 AI 味
+
+AI 生成的网页有几种共有的"视觉指纹"，**全部不要**：
+
+- 紫粉 / 蓝紫对角渐变背景
+- 圆角卡片 + 彩色左边框装饰
+- 渐变按钮 + 大圆角药丸
+- emoji 当图标用
+- 假数据 / 假 logo / 假"X 万用户"
+- 整章 N 步用同一种入场动画（全场 fade / 全场 blur）
+- 每步都挂 ken burns / 光晕呼吸 / 持续闪烁
+- 每屏右下角都挂 mono 角标 / 序号
+
+缺的东西**承认缺** —— 用 placeholder 占位卡（一张写着"image · 16:9
+描述"的卡片，按真实比例留位）。**不要**用 emoji 凑、不要找无关图凑、
+不要编数字。**没有就承认没有**，比 fake 强一百倍。
+
+---
+
+## 框架已经搭好的部分（理解就好，不需重写）
+
+- **16:9 固定舞台**：内容设计在 1920×1080 上，外层 transform scale
+  缩到任何视口，外围 letterbox 留黑 —— **没有响应式断点**
+- **舞台居中 + 大留白**：上下左右四边都让出至少 80px 的安全区
+- **隐形进度条**：屏幕底部默认完全透明，鼠标悬到底部边缘才出现，
+  支持点击跳转章节（录屏时摄像头看不到任何 chrome 控件）
+- **全局 step 驱动**：点击舞台空白处 / 键盘 ←/→ 推进；章节是 `step`
+  的纯函数，没有定时器、没有命令式状态
+
+---
+
+## 代码层最小约束
+
+不能踩的红线，其它怎么写都行：
+
+### 必须用 token（换主题不破的底线）
+
+- **颜色**：`--shell` / `--surface` / `--surface-2` / `--surface-3` /
+  `--text` / `--text-2` / `--text-mute` / `--text-faint` / `--rule` /
+  `--accent` / `--accent-soft` / `--accent-glow` ——
+  **禁硬编码 hex / rgb / 颜色名**
+- **字体家族**：`--font-display-cn` / `--font-display-en` / `--font-body`
+  / `--font-mono` —— **禁硬编码字体名**
+- **主题性格签名**通过 primitive class 自动接入，**不要在章节 CSS 里
+  重定义它们**：
+  - `.hero-num`（hero 数字风格 —— 主题决定衬线 / 等宽 / 粗黑）
+  - `.rule`（分割线 —— 主题决定 1px 实线 / 4px 实线 / 2px 虚线）
+  - `.card`（卡片 —— 主题决定圆角 + 阴影性格）
+  - `.stage-frame`（舞台底色 / 圆角 / 阴影 / 装饰图案 / vignette
+    全自动，章节什么都不用做）
+
+### 可硬编码 / 可 token，按内容自由（解锁章节自由设计）
+
+- **字号**：想要 80px 就写 80px，想用 `var(--t-h1)` 也行
+- **间距 / padding / margin**：按画面节奏写具体值
+- **动画时长 / 缓动 / keyframe**：按动画意图写具体值
+  （**节奏气质**参考 `theme.json` 的 `mood` —— 慢主题别写 200ms 的快动画）
+- **边框宽度 / 非性格圆角 / 字距**：随手写
+- **gap / grid 布局尺寸**：按画面构图写
+
+### 其它工程红线
+
+- 不用 `setTimeout` / `setInterval` 驱动动画 —— 用 CSS keyframes
+- 章节内的可交互元素（按钮 / 自定义控件）加 `data-no-advance`，
+  否则点了会被舞台误推进 step
+- 章节代码物理隔离：每章独立文件夹、独立 CSS 类前缀，不跨章 import
+- **每章必须有 `narrations.ts`**（与 `<Chapter>.tsx` 同目录）：
+  - 数组长度 **=** 章节代码里 `if (step === N)` 出现的最大 N + 1
+  - 每个元素 = 一个 string，该 step 要播的口播文本（来自 `script.md`
+    对应段，**语义一致**——可微调标点 / 断句以适配 TTS，但不能漏关键短语）
+  - 完全无音频的过场 step 用空串 `""`，Auto 模式会按字数估时撑过
+  - 这是**音频合成 + Auto 模式自动推进的唯一真相源**，写错或漏写
+    会让录屏对不上嘴
+- **动画时长必须 ≤ 该 step 的口播时长**——Auto 模式严格按音频结束推进，
+  没有"等动画跑完"的兜底。动画太长 → 三选一：**写更长口播 / 拆 step
+  / 调动画速度**。详细机制见 [`AUDIO.md`](AUDIO.md)
+
+---
+
+## 完工自检（写完每章**强制**执行，不可跳过）
+
+> ⚠️ **硬性流程**：章节实现完成后**必须**走完下面的自检 → 修复 → 汇报
+> 三步。**禁止**"实现完成 → 直接汇报给用户"。
+>
+> **执行方式**（按能力降级）：
+>
+> 1. **优先 Agent Teams**：开一个独立的 reviewer agent，传入本章代码路径
+>    + 本文件 Part「完工自检」清单，让它**逐项核查 + 出结论**（哪几条
+>    pass / 哪几条 fail + 证据）。
+> 2. **其次 subAgent**：当前 agent 没有 Teams 能力但能开 subagent，用 subagent
+>    走同样的流程。
+> 3. **都没有**：当前 agent 自己**严格逐项**核查，不允许目测一遍就放行。
+>
+> **拿到自检结论后**：先按 fail 项**改完代码**，然后再向用户汇报"做完
+> 了 + 自检结论 + 改了什么"。**直接拿原始结论汇报但不修复 = 违规**。
+
+写完一章 + 在浏览器点完一遍后逐项过：
+
+- [ ] **每章至少 1~2 处 CSS / SVG / Canvas / JS 视觉演示** —— 没有 = 回去补
+- [ ] **不同 step 的主导动作不一样** —— 全章一种动画 = 回去重做
+- [ ] 字号大、留白舒服、配色舒服
+- [ ] 清单 / 列表逐个揭示，**1 项 = 1 step**
+- [ ] 画面信息比口播稿多（回了原文章抽细节挂上来）
+- [ ] 没有紫粉渐变 / 圆角彩色边框 / emoji / 假数据 / 假 logo
+- [ ] 缺的素材用 placeholder，不是 fake
+- [ ] **颜色和字体家族全部走 token**（无硬编码 hex / 字体名）；hero 数字
+      / 卡片 / 分割线 / 舞台用 primitive class 接入主题性格 —— 这两条不
+      达标 = 换主题就破
+- [ ] 章节交付时**主动告诉用户**："本章还缺这些素材"
+- [ ] 禁止出现小号字体，大量纯文字（出现后必须回去改）
+- [ ] 禁止出现任何形式的页眉页脚，仅展示关键内容（出现后必须回去改）
+- [ ] **`npx tsc --noEmit` 通过** —— 不通过禁止汇报"做完了"
+- [ ] 章节代码物理隔离：独立 CSS 类前缀（`.cd-` / `.mg-` / ...），
+      未跨章 import，未修改 `chapters.ts` 之外的共享文件
+- [ ] **`narrations.ts` 存在**且 `narrations.length` === 章节代码里
+      `if (step === N)` 用到的最大 N + 1（不一致 = Auto 模式录屏会错位）
+- [ ] **每条 narration 文本与 `script.md` 对应段落语义一致**（关键短语 /
+      数字 / 引用全部保留，可为 TTS 微调标点断句）—— 录屏画外音应当能被
+      观众听成同一段稿子
+- [ ] **每个 step 的视觉动画时长 ≤ 口播时长**（口播 `字数 ÷ 4` ≈ 秒数）—— 
+      超出会被 Auto 模式当场切断，动画演到一半就跳下一步
+
+任一未过 → 回去改。**不要**"先放着以后修"。

package/template/.hermes/skills/web-video-presentation/references/EXAMPLES/README.md

@@ -0,0 +1,107 @@
+# EXAMPLES —— 完整章节 / 题材 anchor
+
+> ## ⚠️ 这是**结构示意**，不是抄袭模板
+>
+> 这些 example **不是给你照抄的**。它们的角色是"看一个完整章节大概
+> 什么形状、动画怎么分层、CSS 用了哪些 token、outline 长什么样"。
+>
+> **正确使用流程**：
+>
+> 1. 走完 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md) Part 0 五问
+> 2. 实在卡壳"我这一章的整体结构应该是什么"才翻 EXAMPLES
+> 3. **保留它的"形"**（step 切分逻辑、字号关系、布局原则），**按本
+>    项目的主题 + 内容换动作选型**
+>
+> 倒过来——先翻 EXAMPLES 选一个照搬到底 = [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+> Part 5 第 8 条「整章只用一种入场动画」同质化反模式（每个用户的视频
+> 看起来像同一个模板的 N 个变奏）。
+
+两类参考资源，让 agent 在写章节时**有具体形状可参考**，不用从零设计。
+
+> **不是必须按这个写**。卡壳时翻一翻；用力发挥时大胆偏离。
+
+## 目录
+
+### A. 章节结构 anchor（与题材无关）
+
+| 例子 | 适用场景 | 文件 |
+|---|---|---|
+| [`hook-chapter/`](hook-chapter/) | **钩子型开场** —— 多张图片逐张揭示后 hero takeover | `chapter.tsx` + `chapter.css` |
+| [`list-reveal/`](list-reveal/) | **列举型** —— 口播说"三件事 / N 个特性"，每项 1 step | `chapter.tsx` + `chapter.css` |
+
+每个 example 都是**完整章节**：**内容驱动主导动作** + 必要的伴随动作
+（**不强求挂持续微动**，按 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+Part 0 原则 7 节制使用）、真素材（不是占位卡）、字号狠对比、绑了
+`newsroom` 主题作为示范。
+
+### B. 题材 case anchor（与题材相关）
+
+| 例子 | 题材 | 文件 |
+|---|---|---|
+| [`case-tech-review/`](case-tech-review/) | 科技测评 / 实测对比 / 跑分类视频 | README + outline 节选 |
+
+> 题材 case 展示**真实 outline 的样子**（含 article 补字段如何填、
+> 章节切分如何决策）。拿到与某个 case 题材相似的需求时，先翻它再
+> 写自己的 outline。
+
+## 怎么用
+
+### 写章节卡壳时
+
+1. 看哪个 anchor 跟你这一章**结构最像**（钩子型 vs 列举型 vs 其它）
+2. 翻 `README.md` 看这个例子的设计思路 + 节奏
+3. 翻 `chapter.tsx` 看实现：JSX 结构、`step` 切分、用了哪些组件 / 类名
+4. 翻 `chapter.css` 看动画用了哪些 keyframes、token、`infinite` 持续
+   微动写在哪
+5. 写自己这一章时**保留 anchor 的"形"，按本章内容 + 本主题气质换动画选型**
+
+### 切换主题时
+
+每个 example 的 README 末尾有"切到其它主题怎么换"的提示 —— 通常只需要
+**换主导动作的形式**（newsroom 印章砸下 → terminal 打字机 → chalk
+粉笔自绘），**结构、step 切分、字号关系不动**。
+
+---
+
+## ⚠️ 这两个 anchor 是"地板"，不是"天花板"
+
+这两个例子已经引入印章砸下、stagger、accent 红条 —— 但**仍然是相对克
+制的版本**。**鼓励你做得更狂、更"视频感"**：
+
+### 进阶玩法（任选搭配）
+
+| 维度 | 这俩 anchor 给的（地板） | 可以升级到（无上限） |
+|---|---|---|
+| 背景层 | 纯色 surface | + SVG turbulence filter 纸纹永不停斜向漂移 |
+| 主导动作 | mask reveal + 印章砸下 | + Canvas 粒子从屏幕外汇聚成 hero 字 |
+| 伴随动作 | accent 红条 scaleX | + SVG path stroke-dashoffset 自绘下划线 / 装饰花纹 |
+| 持续微动 | accent 光晕呼吸 | + 多层粒子漂移 / scanline / ken burns 缓推 |
+| 数字 hero | 直接显示 | + JS 数字滚动（`requestAnimationFrame` + easeOutQuart） |
+| 流程 / 架构 | 仅文字列 | + SVG path 自绘流程图（每条线 stroke-dashoffset 错峰） |
+| 对比图 | 两段文字 | + SVG 双柱图自绘 + 差值数字滚动 |
+| 转场 | 章节边界硬切 | + clip-path inset 横向擦除转场 |
+
+→ 详细工具箱见 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md) Part 2
+"视觉手段全栈工具箱"（CSS / SVG / Canvas / JS 四层）。
+
+### 实测原则
+
+写章节时，**先实现 anchor 同等的地板版本**（按 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+Part 0 五问选好主导动作），跑起来确认气质对，**再决定要不要加伴随
+动作 / 持续微动**。
+
+**判断标准**：
+- 如果不同 step 的主导动作够多样（PPT 警报通过 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+  Part 0 原则 7 自检）= 不需要再加持续微动
+- 如果整章主导动作太单一 = 不要靠"加持续微动"补救，**回 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+  Part 1 五问换主导动作**才是正解（参 Part 5 第 8 条「整章只用一种入场动画」）
+
+## 不在 EXAMPLES 里出现的章节类型
+
+- **数字型 hero**（"+47%"  → "几乎快了一倍"）
+- **对比型**（前后对照 / 双柱图）
+- **链接卡片收尾**
+
+这些场景的视觉原语已经在 [`../CHAPTER-CRAFT.md`](../CHAPTER-CRAFT.md)
+Part 3 视觉工具箱（CSS / SVG / Canvas / JS 全栈）里覆盖了；按 anchor
+的"形"组合即可。

package/template/.hermes/skills/web-video-presentation/references/EXAMPLES/case-tech-review/README.md

@@ -0,0 +1,56 @@
+# Case: 科技测评类（tech review）
+
+一篇 AI / 工具 / 产品**实测对比**类文章 → 7 章 36 步、6 分 30 秒视频
+的真实案例。
+
+> ## ⚠️ 这是结构示意 / 历史案例，不是抄袭模板
+>
+> 这个目录的角色是让 agent 看："**测评类视频章节怎么切、信息池怎么
+> 抽、章长怎么定**"。**它包含的具体动画描述（如"慢速 blur clear
+> 1.5s ease-out / 打字机每字 80~100ms"）属于历史版本** —— 新版
+> outline 已经**不写动画 / 不写时长**（见 [`../../OUTLINE-FORMAT.md`](../../OUTLINE-FORMAT.md)）。
+> 新写 outline 时只写"屏幕内容 + 关系名前缀 + 章节级信息池"，动画
+> 选型留给章节实现阶段按 [`../../CHAPTER-CRAFT.md`](../../CHAPTER-CRAFT.md)
+> Part 0 五问决定。
+>
+> **看这个 case 学的应该是**：
+> 1. 测评类怎么切 7 章（钩子 → 优点 → 场景 → 进阶 → 收束）
+> 2. 章长怎么定（每章 4~6 step 防疲劳）
+> 3. 双源原则怎么落地（hero 来自 script / 数据角标来自 article）
+>
+> **不应该学**：动画选型、CSS 实现、时长数值（这些已下放到 chapter
+> 阶段）。
+
+## 适用场景
+
+- AI 模型 / 产品 / 工具的实测体验文
+- 多家产品对比（A vs B vs C）
+- 跑分 / benchmark / 用户投票数据驱动的内容
+- "强在哪 / 怎么用 / 怎么用得好"型结构
+
+## 关键决策
+
+| 维度 | 这个案例的选择 | 通用启发 |
+|---|---|---|
+| 主题 | `midnight-press`（电影感慢镜、blur clear、暖橙 accent、scanline） | 科技测评类适合"克制、有重量"的暗色调；避开俏皮 / 糖果色 |
+| 章节切分 | 7 章：开场悬念 / 强在哪 / 哪能用 / 怎么用好 / Skill 介绍 / Skill 模式 / 收尾 | 测评类的标准结构：钩子 → 优点 → 场景 → 进阶 → 收束 |
+| 章长 | 每章 4~6 step | 测评类信息密度高，每章不超过 6 step 防止观众疲劳 |
+| 双源应用 | hero 标语来自 script、画面密度（具体分数 / 投票数 / 时间戳）来自 article | 测评类 article 数据极多 —— 用 mono cue / 角标 / 数据浮层挂出来 |
+| 动画风格 | 慢速 blur clear / 打字机 / ken burns 缓推 | midnight-press 暗色印刷气质，章节实现时按主题氛围自由发挥 |
+
+## 文件
+
+- [`outline-snippet.md`](outline-snippet.md) —— 前 2 章完整节选（5 + 5 step），
+  展示双源原则在 outline 里怎么落地
+
+> 完整 7 章 outline 在调用此 Skill 的具体项目里（`gpt-image2-video/outline.md`），
+> 不放进 Skill 仓库 —— 避免 Skill spec 被某一个项目内容污染。
+
+## 不在这个 case 出现的情形
+
+测评类**通常不需要**：
+- 慢节奏长镜头（电影感片头 / 旅行 vlog 才需要）
+- 手写温暖感（教育 / 亲子 / 食谱才需要）
+- 大量插画（设计稿 / 工艺品类才需要）
+
+→ 选别的 case anchor 或自由发挥。