create-yss-spec 1.0.0

package/template/.agents/skills/web-video-presentation/references/THEMES.md

@@ -0,0 +1,351 @@
+# 主题系统
+
+每个演示从头到尾跑**一个主题**。我们**不**在章节间翻转明暗 —— 那会
+打断视频的视觉连贯性，录屏时看起来像很硬的剪辑。如果想要"暗一点的氛围"
+段落，请在**同一调色板内**降对比、收聚光，而不是翻转表面色。
+
+主题 = 一组 CSS 设计 token + 一个 `theme.json` 元数据。
+
+**章节对 token 的消费分两层**：
+
+1. **必须用 token 的**（换主题不破的底线）—— 颜色 + 字体家族
+2. **章节自由发挥的**（按内容设计）—— 字号 / 间距 / 动画时长 / 缓动 /
+   边框宽度 / 一般圆角 / 字距等都可硬编码
+
+主题**不只管**颜色和字体，但其他维度（hero 数字、分割线、卡片、舞台
+装饰）通过 **primitive class**（`.hero-num` / `.rule` / `.card` /
+`.stage-frame`）自动接入，章节用 class 即可，不需要手动 `var()`。
+
+主题管的维度：
+
+| 维度                       | 主题怎么管                                                        |
+| -------------------------- | ----------------------------------------------------------------- |
+| **调色板**                 | shell / surface 阶梯、text 阶梯、accent + 透明度衍生              |
+| **字型**                   | 中文 / 英文 / body / 等宽家族 + OpenType 特性集                     |
+| **舞台 padding 密度**      | `--stage-pad-x/y` —— 精炼主题 140×100，密集主题 80×60              |
+| **圆角性格**               | `--r-card` —— sharp (0) / refined (4) / soft (16) / keynote (32)  |
+| **分割线性格**             | `--rule-w` + `--rule-style` —— 细/粗 × 实/虚                       |
+| **hero 数字风格**          | `--hero-num-*` —— 编辑级斜体 / 终端等宽 / 粗黑 / 手写              |
+| **舞台 / 卡片阴影**        | `--shadow-stage` / `--card-shadow` —— 纸浮 / 偏移实色 / 内阴影     |
+| **装饰层**                 | `--surface-pattern*` / `--surface-vignette` / `--text-shadow`     |
+| **动效基线**               | `theme.json` 的 `mood` —— 电影感慢 / 弹簧 / 利落 / 安静            |
+
+> **`mood` 不写时长数值**。具体 ms / 缓动由 chapter agent 看 `mood`
+> 自己拍板（慢主题别写 200ms 快动画，仅此而已）。
+
+每个主题约 25~35 个 token。完整契约见下方。
+
+---
+
+## 内置主题
+
+23 套主题，每个都有**独立的设计 DNA** —— 不是简单的换色版。挑一个
+匹配你主题情绪的，或者作为你自己主题的起点。
+
+### 深色主题
+
+| id                | 性格                                                                                                                                                                                                            |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `midnight-press`  | 电影感编辑级深色。暖色 espresso（不是纯黑）+ 火热橙。Instrument Serif italic 英文 vs Noto Serif SC 中文。hero 数字：斜体衬线。慢速电影感节奏（1.6s 揭示）。140×100 padding。只有 vignette，没有颗粒。            |
+| `chalk-garden`    | 深石板黑板。Patrick Hand 全场手写，粉笔黄 accent。**2px 虚线 rule** 是签名。film grain（overlay）+ vignette。衬线带 chalk text-shadow。手绘节奏。                                                                |
+| `terminal-green`  | 80 年代磷光终端。纯黑 + JetBrains Mono only + 0px 直角。**CRT 扫描线**贴在舞台上。文字带磷光 text-shadow。利落线性动效（180/400/650ms）。hero 数字：等宽带发光。                                                  |
+| `blueprint`       | 工程蓝图。深海军蓝 + 绘图青 + IBM Plex Mono。**2px 虚线青色 rule + 60px 制图网格**是签名。hero 数字：等宽青色。等宽配对营造技术 / 蓝图感。                                                                       |
+| `dark-botanical`  | 高级感编辑暗底 —— 时尚刊物 / 博物馆图录。近黑 + 暖陶 / 玫粉 / 鎏金叠层。Cormorant italic + IBM Plex Sans。**柔光晕染（blurred light pool）作为签名**。慢速电影感节奏（1.7s）。140×100 padding。              |
+| `neon-cyber`      | 赛博朋克未来派。深海军底 + 电光青 + 玫红双霓虹。Clash Display + Satoshi。**青色发光网格 + 双色霓虹描边（cyan + magenta text-shadow）**是签名。snappy 节奏（380/650ms）。                                       |
+| `bold-signal`     | hero pitch-deck 暗底。Archivo Black + Space Grotesk。大橙色焦点色卡 + 制表数编号。**对角线深色渐变 + 大字标语**是签名。punchy 节奏（420/680ms）。                                                                |
+| `creative-voltage`| 复古朋克创意工作室。饱和电光蓝底 + 霓虹黄强调。Syne + Space Mono。**halftone 网点 + 偏移霓黄阴影**是签名。punchy + 能量节奏（450/720ms）。                                                                       |
+
+### 浅色主题
+
+| id                   | 性格                                                                                                                                                                                                            |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper-press`        | midnight-press 的白天孪生兄弟。暖奶油 + 纸纹（multiply blend）。火热橙。hero 数字：斜体编辑级衬线。慢速电影感节奏。140×100 padding。                                                                              |
+| `warm-keynote`       | 现代 SaaS keynote。奶油 + 棕褐墨 + 青绿 + Inter。**大圆角（32px）glass slab** 配 backdrop blur。**粗黑 font-black hero 数字**。舞台上 40px 暖色网格。弹簧动效。                                                  |
+| `newsroom`           | NYT 报刊。报纸奶油 + 墨黑衬线 + 旗红。Playfair Display + Noto Serif SC。**0 圆角**（报纸不会圆角）。hero 数字：超大斜体显示衬线。安静的印刷节奏。淡纸纹。                                                        |
+| `bauhaus-bold`       | 现代主义宣言。米白 + 墨黑 + 原色蓝。Archivo Black + Inter。**0 圆角 + 4px 实色厚边 + 4px 黑色画框包住舞台 + 偏移实色阴影**。hero 数字：font-weight 900 巨字。利落快速动效。无装饰。                              |
+| `sunset-zine`        | 独立 risograph zine。暖桃 + riso 洋红 + Fraunces。**虚线剪贴线 + 偏移桃色阴影**。hero 数字：斜体 Fraunces。粗 riso 纸纹。弹簧 overshoot 动效。                                                                  |
+| `monochrome-print`   | 安静精炼的印刷杂志 —— Monocle / Wallpaper / MIT Press。米白 + 墨黑衬线 + 墨蓝 accent。Source Serif。**只有 1px 实线发丝、4px 精炼圆角**。hero 数字：斜体 tabular figures。**无装饰** —— 极简纯粹。极静节奏（1.7s 揭示）。 |
+| `vintage-editorial`  | 俏皮编辑奶油底。Fraunces italic + Work Sans + 暖陶 accent。**细线几何叠层（圆 + 线 + 点）**是签名。有性格、会说话，像专栏作家。中速带轻微 overshoot。                                                            |
+| `pastel-dream`       | 友好柔光。柔粉蓝灰底 + 奶油卡 + 鼠尾草绿。Plus Jakarta Sans。**大圆角（20px）+ 右侧多色 pill 色条**是签名。soft springy（520/820ms）。                                                                          |
+| `split-canvas`       | 双拼画布 —— 蜜桃 + 薰衣草 50/50 硬切分。Outfit + 玫红 accent。**屏幕本身就是双色底**，章节自由在哪一侧落内容。playful 中速（480/780ms）。                                                                       |
+| `electric-studio`    | 企业电光蓝。净白底 + 单一电光蓝 + Manrope。**贴底 4px 电蓝条**作为签名，B2B / 路演 / 财报场景的清晰自信。punchy 节奏（420/700ms）。                                                                              |
+| `indigo-porcelain`   | 靛蓝瓷 —— **靛蓝当墨**（不是 accent，是字色本身）+ 瓷白纸。Playfair Display italic + Noto Serif SC + IBM Plex Sans 正文。学术 / 研究气质，像一本当代思想期刊。无装饰 —— 纯粹。慢速（1.55s）。                       |
+| `forest-ink`         | 森林墨 —— **森林绿当墨** + 象牙暖纸。Source Serif 正文 + Playfair Display。旧版《国家地理》感，沉稳、文献感。faint warm grain。慢速（1.65s）。                                                                  |
+| `kraft-paper`        | 牛皮纸 —— **深棕当墨** + 牛皮米。Fraunces + Source Serif + 紫铜 accent。老笔记本 / 老信封感。**粗暖纸纹**是签名。慢速 tactile（1.55s）。                                                                       |
+| `dune`               | 沙丘 —— **炭褐当墨** + 沙底 + 几乎无 accent（muted clay）。Inter display + Source Serif 正文。**无装饰 + 极宽 padding（140×100）**是签名。建筑手册 / 画廊感。最慢节奏（1.75s）。                                |
+| `swiss-ikb`          | 瑞士国际主义。**极细 200 weight Inter / Helvetica** + 净暖白底 + IKB 克莱因蓝 + **1px 发丝网格 (64px)**。`r-card: 0` 直角。Massimo Vignelli / Helvetica Forever 能量。punchy + linear（400/650ms）。           |
+
+
+随时列出可用主题：
+
+```bash
+bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes
+```
+
+---
+
+## 脚手架时挑一个主题
+
+```bash
+# 默认（midnight-press）
+bash scripts/scaffold.sh ./presentation
+
+# 显式指定
+bash scripts/scaffold.sh ./talk --theme=newsroom
+```
+
+脚手架会把所选主题的 `tokens.css` 拷到 `<project>/src/styles/tokens.css`，
+并把主题 id 写到 `<project>/.theme`，方便以后看是从哪个主题开始的。
+
+---
+
+## 之后切换主题
+
+切换 = 一次文件覆盖：
+
+```bash
+cp <path-to-web-video-presentation>/themes/newsroom/tokens.css \
+   presentation/src/styles/tokens.css
+```
+
+刷新 dev server。完成。章节代码一行没动。
+
+如果切换后某章节看起来有问题，那是该章节在某处硬编码了颜色 / 字体 /
+尺寸，而不是用语义 token。去找出来 —— bug 在章节里，不在主题里。
+
+---
+
+## 完整 token 契约
+
+`base.css` 给**性格 token 都准备了合理的默认值**。主题的 `tokens.css`
+只需要覆盖**调色板 + 字体 + 性格旋钮 + 装饰**这四类。
+
+> **base.css 里的字号 / 间距 / 时长尺度只供 primitive class 自己用**
+> （`.label-mono` / `.kicker` / `.scene-pad` 等）。**不是**章节必须消费
+> 的契约——章节这一层要不要 `var(--t-h1)` 还是直接写 `font-size: 96px`
+> 完全自由。
+
+### 必填（主题必须定义）
+
+#### 表面色（4 个）
+
+| token         | 作用                                                |
+| ------------- | --------------------------------------------------- |
+| `--shell`     | letterbox / 舞台外的页面背景                        |
+| `--surface`   | 舞台主背景                                          |
+| `--surface-2` | 凸起 —— 卡片、代码块、嵌入面板                      |
+| `--surface-3` | 最里层 —— surface-2 里再嵌一层时用                  |
+
+#### 文字（4 个）
+
+| token          | 作用                                  |
+| -------------- | ------------------------------------- |
+| `--text`       | 主                                    |
+| `--text-2`     | 次（副标题、正文）                    |
+| `--text-mute`  | 静音 —— 标签 / 元数据                 |
+| `--text-faint` | 三级 —— 提示 / 禁用                   |
+
+#### 线条（1 个）
+
+| token    | 作用              |
+| -------- | ----------------- |
+| `--rule` | 发丝分割线颜色    |
+
+#### Accent（3 个）
+
+| token           | 作用                                          |
+| --------------- | --------------------------------------------- |
+| `--accent`      | accent 本体（一个品牌强色）                   |
+| `--accent-soft` | 低透明度叠层 —— pill 背景、悬浮光晕            |
+| `--accent-glow` | 中透明度叠层 —— text shadow、圆点发光          |
+
+#### 字型家族（4 个）
+
+| token               | 作用                                       |
+| ------------------- | ------------------------------------------ |
+| `--font-display-cn` | 中文显示家族                               |
+| `--font-display-en` | 拉丁显示家族（斜体强调声音）               |
+| `--font-body`       | 正文 / 段落家族                            |
+| `--font-mono`       | 等宽家族（终端、mono caps、badge）          |
+
+### 可选的性格覆盖（主题应该定义来表达自己的性格）
+
+这些有 base 默认值；主题重新定义来表达性格。
+
+| token              | base 默认           | 作用                                                  |
+| ------------------ | ------------------- | ----------------------------------------------------- |
+| `--font-features`  | `"tnum","ss01"`     | body 上的 OpenType 特性栈                             |
+| `--r-card`         | `--r-md`            | 默认卡片圆角（sharp / refined / keynote）              |
+| `--r-stage`        | `0`                 | 直接加在舞台本身的圆角                                 |
+| `--rule-w`         | `1px`               | rule 粗细（1=发丝，2=中等，4=厚重）                    |
+| `--rule-style`     | `solid`             | rule 样式（`solid` / `dashed` / `dotted`）             |
+| `--hero-num-font`  | `--font-display-en` | `.hero-num` 用什么字体（主题决定性格）                 |
+| `--hero-num-style` | `italic`            | `italic` / `normal`                                   |
+| `--hero-num-weight`| `400`               | 400（编辑级）/ 500（等宽）/ 900（粗黑）                |
+| `--hero-num-track` | `--track-tight`     | hero 数字的字距                                       |
+| `--stage-pad-x`    | `96px`              | 舞台横向内边距（密度旋钮）                            |
+| `--stage-pad-y`    | `80px`              | 舞台纵向内边距                                        |
+| `--card-shadow`    | none                | `.card` 的 box-shadow                                 |
+| `--card-glass-bg`  | `rgba(255,255,255,0.06)` | `.card-glass` 的背景                            |
+| `--card-glass-border` | `rgba(255,255,255,0.12)` | `.card-glass` 的边框                            |
+| `--shadow-stage`   | dark drop           | 舞台的 box-shadow                                     |
+| `--stage-border`   | `none`              | 舞台的可选边框（Bauhaus 用 `4px solid black`）         |
+
+### 可选的装饰层（主题可选用，给质感加签名）
+
+这些默认是 no-op；主题选择性启用。装饰画**在舞台上**（pattern 用
+`stage-frame::after`，vignette 用 `stage-frame::before`），所以会被屏幕
+录制器捕捉到。
+
+| token                        | 作用                                                                                                       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `--surface-pattern`          | 叠在舞台上的 `background-image`。SVG 噪声 / 网格 / 扫描线。                                                |
+| `--surface-pattern-size`     | 配套的 `background-size`。可平铺渐变必填。                                                                  |
+| `--surface-pattern-blend`    | pattern 层的 `mix-blend-mode`（`normal` / `multiply` / `overlay`）。                                       |
+| `--surface-pattern-opacity`  | pattern 层的整体透明度乘子。                                                                                |
+| `--surface-vignette`         | vignette 叠层的 `background`（黑板 / 电影感边角的径向渐变）。                                              |
+| `--text-shadow`              | 应用在 `.serif-cn` / `.serif-it` / `.display-en` 上。如粉笔晕 / 磷光辉。                                    |
+
+如果你需要的装饰找不到对应槽位，那就跨过"主题契约"边界进入"章节自定义
+CSS"领域 —— 在那里解决，别扩主题契约。
+
+---
+
+## 创作新主题
+
+### 1. 复制一个最接近的作为起点
+
+挑一个**最接近**你目标气质的：
+
+| 目标情绪                                | 起点                  |
+| --------------------------------------- | --------------------- |
+| 阴郁、电影感、编辑级                    | `midnight-press`      |
+| 编辑级 - 浅色                           | `paper-press`         |
+| 现代 keynote / SaaS                     | `warm-keynote`        |
+| 教室 / 解说                             | `chalk-garden`        |
+| 终端 / 黑客 / 复古 CRT                  | `terminal-green`      |
+| 纪录片 / 严肃 / 新闻                    | `newsroom`            |
+| 工程 / 蓝图 / 技术                      | `blueprint`           |
+| 现代主义 / 布鲁塔利斯特 / 宣言          | `bauhaus-bold`        |
+| 独立 / 玩味 / zine                      | `sunset-zine`         |
+| 精炼 / 安静 / 印刷                      | `monochrome-print`    |
+| 高级感暗底 / 时尚 / 博物馆图录          | `dark-botanical`      |
+| 赛博朋克 / 未来感 / AI / web3           | `neon-cyber`          |
+| 俏皮编辑 / 有声音的博主 / 文化随笔      | `vintage-editorial`   |
+| 柔粉 / 友好 / onboarding / 女性向       | `pastel-dream`        |
+| 双色分屏 / 对照 / 辩论                  | `split-canvas`        |
+| pitch deck / 大字宣言 / 焦点色卡         | `bold-signal`         |
+| B2B / 企业 / 投资人路演                 | `electric-studio`     |
+| 复古朋克 / 创意工作室 / 设计周          | `creative-voltage`    |
+| 学术 / 研究 / 中国当代文化              | `indigo-porcelain`    |
+| 自然 / 可持续 / 户外 / 纪录             | `forest-ink`          |
+| 文学 / 怀旧 / 书评 / 手工艺             | `kraft-paper`         |
+| 建筑 / 艺术展览 / 高端画廊              | `dune`                |
+| 瑞士国际主义 / Helvetica / 信息驱动设计 | `swiss-ikb`           |
+
+```bash
+cd <path-to-web-video-presentation>/themes
+cp -r monochrome-print my-theme
+```
+
+### 2. 改 `my-theme/tokens.css`
+
+按契约自上而下走一遍：调色板 → 字体 → 性格旋钮（`--r-card` /
+`--rule-*` / `--hero-num-*` / `--stage-pad-*`）→ 阴影 → 装饰。
+**不要**碰字号 / 间距 / 时长尺度 —— 那些是 base.css 给 primitive class
+用的内部默认值，不是主题契约的一部分。
+
+**几条不那么显而易见的规则：**
+
+- 深色主题里 `--shell` **比 `--surface` 更深 / 更饱和**；浅色主题里
+  `--shell` **比 `--surface` 略灰一点** —— 这样舞台读起来是"主体"，
+  外围会退后。
+- 维持 `--text` 与 `--surface` **至少 4.5:1 对比度**。96px+ 的标题
+  可以放宽到 3:1，body / cue 必须 ≥ 4.5:1。
+- `--accent` 是**唯一的**饱和色。第二个饱和色会跟第一个打架。
+- `--accent-glow` 和 `--accent-soft` 是 `--accent` **同色相的透明度
+  叠层**，永远不要用别的色相。
+- `--text-faint` 在 `--surface` 上 13px 大写时**仍然要可读**。
+- 挑**一个设计签名**重重发力：虚线 rule、粗黑边、扫描线、纸纹、glass
+  slab。别同时叠三个。
+
+### 3. 改 `my-theme/theme.json`
+
+```json
+{
+  "id": "my-theme",
+  "name": "My Theme",
+  "nameZh": "我的主题",
+  "description": "一句英文描述它的气质。",
+  "descriptionZh": "一句中文描述它的气质。",
+  "mood": ["dark", "moody", "futuristic"],
+  "bestFor": ["<匹配场景 1>", "<匹配场景 2>"],
+  "preview": {
+    "shell": "#080808",
+    "surface": "#101010",
+    "text": "#f0f0f0",
+    "accent": "#ffd54a"
+  }
+}
+```
+
+`id` 必须等于目录名。
+
+### 主题元数据字段说明
+
+| 字段 | 必填 | 取值 | 决定什么 |
+|---|---|---|---|
+| `id` / `name` / `nameZh` | ✓ | 字符串 | 主题标识 |
+| `description` / `descriptionZh` | ✓ | 一句话 | Checkpoint Plan 列清单时的简介 |
+| `mood` | ✓ | 标签数组 | 模糊匹配用 |
+| `bestFor` | ✓ | 场景数组 | Checkpoint Plan 智能推荐时的命中点 |
+| `preview` | ✓ | 4 色对象 | Checkpoint Plan 列清单时的视觉预览 |
+
+> **主题不再约束动画选型 / 时长 / 字号 / emoji**。视觉风格由 `tokens.css`
+> 的颜色 / 字体 / 字号 token 决定，动画 / 节奏 / 视觉演示完全交给 chapter
+> agent 在每章实现时按内容自由发挥，避免主题字段过早限制创造力。
+>
+> 风格审美约束（不要紫粉渐变、不要 emoji 装饰、不要假数据等）由
+> [`CHAPTER-CRAFT.md`](CHAPTER-CRAFT.md) 统一规定，与具体主题无关。
+
+### 4. 用所有 demo 章节测试一遍
+
+```bash
+bash scripts/scaffold.sh /tmp/test-theme --theme=my-theme
+cd /tmp/test-theme
+npm run dev
+```
+
+把 demo 每一步点完。检查：
+
+- 标题衬线在舞台上很清晰。
+- accent 圆点在发光但不爆。
+- 斜体强调有可读的背景。
+- 进度条（悬浮底边）能看到，是 accent 色。
+- masthead 行（`.masthead`）读起来像编辑 chrome，不像 navbar。
+- hero 数字（`.hero-num`）感觉**和整体字型同源**，不像贴上去的。
+- 卡片（`.card`）感觉是合适的材质（纸 / 玻璃 / cell）。
+- 装饰**被注意到一次然后被忘掉** —— 永远不打扰。
+
+哪里不对就改 `tokens.css`，刷新即可。无需重新构建。
+
+### 5. 加到文档里
+
+在本文件顶部"内置主题"表里追加一行。
+
+---
+
+## 反模式
+
+- **章节 CSS 硬编码 hex 颜色 / 字体名** —— 缺哪个色彩 / 字体语义就在
+  契约里补一个，给所有主题加上（注意：**字号 / 间距 / 时长**硬编码不算
+  反模式，章节按内容自由设计）
+- **演示中途切换主题** —— 选一个，一以贯之
+- **第二个 accent 色** —— 只能有一个。用尺度 + 字重做层级
+- **在组件层 override 主题 token**（颜色 / 字体 / 性格签名）—— 只在
+  `:root` 里覆盖。一次性的颜色需求 = 提一个派生 token，让所有主题都
+  提供自己的值
+- **依赖主题的 TSX 条件分支** —— 章节必须主题无关。布局依赖明 vs 暗
+  = 布局脆弱，修布局
+- **一个主题叠三个设计签名** —— 选 ONE 个（虚线 rule / 扫描线 /
+  glass slab / 纸纹 / 粗边），三个会自己打架

package/template/.agents/skills/web-video-presentation/scripts/scaffold.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────
+# scaffold.sh —— 一键脚手架，创建一个 video-presentation 项目。
+#
+# 用法：
+#   bash scripts/scaffold.sh <target-dir> [--theme=<id>]
+#   bash scripts/scaffold.sh --list-themes
+#
+# 例子：
+#   bash <path-to-web-video-presentation>/scripts/scaffold.sh ./presentation
+#   bash <path-to-web-video-presentation>/scripts/scaffold.sh ./talk --theme=paper-press
+#   bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes
+#
+# 跑完后，看 SKILL.md "Phase 2.4 实现单章" + references/CHAPTER-CRAFT.md
+# 了解每章怎么写。卡壳时翻 references/EXAMPLES/ 找完整章节 anchor。
+#
+# 之后切换主题，覆盖一个文件即可：
+#   cp <path-to-web-video-presentation>/themes/<id>/tokens.css \
+#      <project>/src/styles/tokens.css
+# ─────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATES="$SKILL_DIR/templates"
+THEMES_DIR="$SKILL_DIR/themes"
+DEFAULT_THEME="midnight-press"
+
+list_themes() {
+  echo "可用主题（来自 ${THEMES_DIR}）:"
+  echo
+  for dir in "$THEMES_DIR"/*/; do
+    [[ -d "$dir" ]] || continue
+    local meta="$dir/theme.json"
+    [[ -f "$meta" ]] || continue
+    # 没有 jq，简单 grep + sed 提字段
+    local id name desc
+    id=$(grep -E '"id"' "$meta" | head -n1 | sed -E 's/.*"id":[[:space:]]*"([^"]+)".*/\1/')
+    name=$(grep -E '"nameZh"' "$meta" | head -n1 | sed -E 's/.*"nameZh":[[:space:]]*"([^"]+)".*/\1/')
+    desc=$(grep -E '"descriptionZh"' "$meta" | head -n1 | sed -E 's/.*"descriptionZh":[[:space:]]*"([^"]+)".*/\1/')
+    printf "  • %-18s %s\n      %s\n\n" "$id" "$name" "$desc"
+  done
+  echo "用 --theme=<id> 选定一个。默认：${DEFAULT_THEME}。"
+}
+
+# ── 解析参数 ──
+TARGET=""
+THEME="$DEFAULT_THEME"
+for arg in "$@"; do
+  case "$arg" in
+    --list-themes)
+      list_themes
+      exit 0
+      ;;
+    --theme=*)
+      THEME="${arg#--theme=}"
+      ;;
+    --*)
+      echo "✗ 未知参数: $arg" >&2
+      exit 1
+      ;;
+    *)
+      if [[ -z "$TARGET" ]]; then TARGET="$arg"; fi
+      ;;
+  esac
+done
+
+TARGET="${TARGET:-presentation}"
+THEME_DIR="$THEMES_DIR/$THEME"
+THEME_TOKENS="$THEME_DIR/tokens.css"
+
+if [[ ! -d "$THEME_DIR" || ! -f "$THEME_TOKENS" ]]; then
+  echo "✗ 找不到主题 '${THEME}'。可用主题：" >&2
+  echo >&2
+  for dir in "$THEMES_DIR"/*/; do
+    [[ -d "$dir" ]] || continue
+    echo "    • $(basename "$dir")" >&2
+  done
+  exit 1
+fi
+
+if [[ -d "$TARGET" && -n "$(ls -A "$TARGET" 2>/dev/null || true)" ]]; then
+  echo "✗ 目标目录 '${TARGET}' 已存在且非空，已中止。" >&2
+  exit 1
+fi
+
+if ! command -v npm >/dev/null; then
+  echo "✗ 需要 npm，但在 PATH 里没找到。" >&2
+  exit 1
+fi
+
+echo "▸ 在 $TARGET 创建 Vite + React + TS 项目"
+echo "▸ 使用主题：$THEME"
+npm create vite@latest "$TARGET" -- --template react-ts >/dev/null
+
+cd "$TARGET"
+echo "▸ 安装依赖（可能要等一会）..."
+npm install >/dev/null 2>&1
+
+echo "▸ 安装 tsx（用于 extract-narrations 脚本）..."
+npm install --save-dev tsx >/dev/null 2>&1
+
+echo "▸ 用演示骨架替换默认 boilerplate"
+
+# 干掉我们不要的 Vite 默认 boilerplate
+rm -f \
+  src/App.tsx src/App.css \
+  src/main.tsx src/index.css \
+  src/assets/react.svg \
+  public/vite.svg \
+  README.md
+rmdir src/assets 2>/dev/null || true
+
+# 把脚手架文件拷到项目根
+mkdir -p \
+  src/styles src/hooks src/components src/registry \
+  src/chapters/01-example \
+  public scripts
+
+cp "$TEMPLATES/vite.config.ts" .
+cp "$TEMPLATES/index.html" .
+
+cp "$TEMPLATES/src/main.tsx" src/main.tsx
+cp "$TEMPLATES/src/App.tsx"  src/App.tsx
+
+# tokens.css 来自所选主题
+cp "$THEME_TOKENS"                          src/styles/tokens.css
+cp "$TEMPLATES/src/styles/base.css"         src/styles/base.css
+cp "$TEMPLATES/src/styles/animations.css"   src/styles/animations.css
+cp "$TEMPLATES/src/styles/fonts.css"        src/styles/fonts.css
+
+cp "$TEMPLATES/src/hooks/useStageScale.ts"   src/hooks/useStageScale.ts
+cp "$TEMPLATES/src/hooks/useStepper.ts"      src/hooks/useStepper.ts
+cp "$TEMPLATES/src/hooks/useAudioPlayer.ts"  src/hooks/useAudioPlayer.ts
+cp "$TEMPLATES/src/hooks/useAutoMode.ts"     src/hooks/useAutoMode.ts
+
+cp "$TEMPLATES/src/components/Stage.tsx"          src/components/Stage.tsx
+cp "$TEMPLATES/src/components/MaskReveal.tsx"     src/components/MaskReveal.tsx
+cp "$TEMPLATES/src/components/ProgressBar.tsx"    src/components/ProgressBar.tsx
+cp "$TEMPLATES/src/components/ProgressBar.css"    src/components/ProgressBar.css
+cp "$TEMPLATES/src/components/AutoStartGate.tsx"  src/components/AutoStartGate.tsx
+cp "$TEMPLATES/src/components/AutoStartGate.css"  src/components/AutoStartGate.css
+cp "$TEMPLATES/src/components/AutoToggle.tsx"     src/components/AutoToggle.tsx
+cp "$TEMPLATES/src/components/AutoToggle.css"     src/components/AutoToggle.css
+
+cp "$TEMPLATES/src/registry/types.ts"    src/registry/types.ts
+cp "$TEMPLATES/src/registry/chapters.ts" src/registry/chapters.ts
+
+cp "$TEMPLATES/src/chapters/01-example/Example.tsx"     src/chapters/01-example/Example.tsx
+cp "$TEMPLATES/src/chapters/01-example/Example.css"     src/chapters/01-example/Example.css
+cp "$TEMPLATES/src/chapters/01-example/narrations.ts"   src/chapters/01-example/narrations.ts
+
+# Audio pipeline scripts (extract-narrations + synthesize-audio runner +
+# pluggable TTS providers under tts-providers/).
+cp "$TEMPLATES/scripts/extract-narrations.ts"  scripts/extract-narrations.ts
+cp "$TEMPLATES/scripts/synthesize-audio.sh"    scripts/synthesize-audio.sh
+chmod +x scripts/synthesize-audio.sh
+
+mkdir -p scripts/tts-providers
+cp "$TEMPLATES/scripts/tts-providers/README.md"   scripts/tts-providers/README.md
+cp "$TEMPLATES/scripts/tts-providers/minimax.sh"  scripts/tts-providers/minimax.sh
+cp "$TEMPLATES/scripts/tts-providers/openai.sh"   scripts/tts-providers/openai.sh
+
+# Wire the audio scripts into npm so contributors don't have to remember
+# the exact command. Uses node to merge into the existing package.json.
+node -e '
+const fs = require("fs");
+const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+p.scripts = Object.assign({}, p.scripts, {
+  "extract-narrations": "tsx scripts/extract-narrations.ts",
+  "synthesize-audio":   "bash scripts/synthesize-audio.sh",
+});
+fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+'
+
+# 留个标记，以后能查这个项目从哪个主题起步的
+{
+  echo "$THEME"
+} > .theme
+
+# 跑一次 typecheck 确认接线 OK
+echo "▸ 跑 typecheck ..."
+if npx tsc --noEmit; then
+  echo "✓ typecheck 通过"
+else
+  echo "✗ typecheck 失败 —— 请看上面的错误" >&2
+  exit 1
+fi
+
+cat <<EOF
+
+✓ 完成。下一步：
+
+  1. cd $TARGET
+  2. npm run dev      # 默认 http://localhost:5174（被占会自动换端口）
+
+当前主题：${THEME}（见 .theme）
+
+然后：
+
+  • 点舞台任意位置推进全局 step 计数器。
+  • 鼠标移到底部边缘可显出进度条；鼠标移到右上角可显出播放模式切换。
+  • 把 src/chapters/01-example/ 替换成你自己的章节
+    （流程见 SKILL.md "Phase 2.4 实现单章" —— 每章一次到位完整版本，
+     不分骨架 / 精修两步；动画选型由 chapter agent 按 CHAPTER-CRAFT.md
+     Part 0 原则 7 + Part 1 五问决定）。
+  • 在 src/registry/chapters.ts 注册每个新章节。
+  • **每章必须有 narrations.ts**（与 Example.tsx 同目录），
+    数组长度 = step 数，是音频合成 + Auto 模式的唯一真相源。
+  • 章节改了就 bump src/hooks/useStepper.ts 的 STORAGE_KEY 末尾版本号。
+
+录制：
+
+  • 手动模式：直接打开 http://localhost:5174（点击 / 方向键推进）
+  • 半自动：URL 加 ?audio=1 — 音频跟 step 切，但你手动推进
+  • 全自动录屏：URL 加 ?auto=1 — 按一次 SPACE 启动，整片自动播 + 推进
+                按 M 键随时切换三种模式。
+
+音频合成（可选，录制前做）：
+
+  npm run extract-narrations    # 扫所有章节 narrations.ts → audio-segments.json
+  npm run synthesize-audio      # 默认 minimax provider 合成 → public/audio/<id>/<step>.mp3
+                                # 换 provider：PRESENTATION_TTS=<name> npm run synthesize-audio
+                                # 自定义 / 没装 mmx 见 scripts/tts-providers/README.md
+
+写章节时必读（单一入口，路径在 SKILL 仓库内）：
+
+  • $SKILL_DIR/references/CHAPTER-CRAFT.md
+      Part 0 十条原则 / Part 1 开工 5 问 / Part 2 关系→动作决策树 /
+      Part 3 视觉工具箱 / Part 4 时长 / Part 5 反 AI 味反模式 /
+      Part 6 代码硬规则 / Part 7 完工自检 / Part 8 反馈速查
+  • $SKILL_DIR/themes/$THEME/theme.json
+      看 descriptionZh / mood / bestFor —— 参考主题气质
+      （动画 / 时长 / 字号 / emoji 由 chapter agent 在每章自由决定）
+
+卡壳时可翻：
+
+  • $SKILL_DIR/references/EXAMPLES/
+      完整章节 anchor（钩子型 / 列举型）—— 看"形"，不要照搬
+
+要换一个主题，覆盖 tokens.css 即可：
+  cp $SKILL_DIR/themes/<id>/tokens.css src/styles/tokens.css
+
+想自创主题，看 $SKILL_DIR/references/THEMES.md。
+
+EOF

package/template/.agents/skills/web-video-presentation/templates/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Presentation</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>