create-yss-spec 1.0.0

package/template/.hermes/skills/web-video-presentation/references/EXAMPLES/list-reveal/chapter.css

@@ -0,0 +1,137 @@
+/* ─────────────────────────────────────────────────────────────────
+ * list-reveal · 完整章节示例样式
+ * 默认绑 newsroom 主题。零硬编码视觉属性。
+ * ───────────────────────────────────────────────────────────────── */
+
+.lr-scene {
+  color: var(--text);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-6);
+}
+
+/* ── masthead ── */
+.lr-masthead {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+.lr-rule {
+  flex: 1;
+  height: 1px;
+  background: var(--rule);
+}
+.lr-kicker {
+  font-family: var(--font-mono);
+  font-size: var(--t-cue);
+  letter-spacing: 0.18em;
+  color: var(--accent);
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+/* ── intro step ── */
+.lr-intro {
+  justify-content: center;
+  align-items: stretch;
+  gap: var(--space-5);
+}
+.lr-intro-h {
+  margin: 0;
+  font-family: var(--font-display-cn);
+  font-size: var(--t-display-2);
+  text-align: center;
+  letter-spacing: -0.01em;
+}
+.lr-em { color: var(--accent); }
+.lr-intro-sub {
+  font-family: var(--font-body);
+  font-size: var(--t-h3);
+  color: var(--text-2);
+  text-align: center;
+  margin-bottom: var(--space-5);
+}
+
+/* ── grid (3 slots, fixed layout) ── */
+.lr-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: var(--space-5);
+}
+
+/* ── slot base ── */
+.lr-slot {
+  border-radius: var(--r-card);
+  padding: var(--space-5);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  min-height: 360px;
+  transition: opacity var(--dur-base) var(--ease-quart),
+              filter   var(--dur-base) var(--ease-quart),
+              border-color var(--dur-base) var(--ease-quart);
+}
+
+/* ghost: 虚线边 + 大灰序号 */
+.lr-slot-ghost {
+  border: var(--rule-w) dashed var(--rule);
+  background: transparent;
+  opacity: 0.55;
+}
+.lr-slot-ghost .lr-slot-num {
+  color: var(--text-faint);
+}
+
+/* active: 红框 + 实心面板 + 巨号砸下 */
+.lr-slot-active {
+  border: var(--rule-w) solid var(--accent);
+  background: var(--surface);
+  box-shadow: var(--shadow-card);
+}
+.lr-slot-active .lr-slot-num {
+  color: var(--accent);
+  animation: lr-num-drop var(--dur-base) var(--ease-quart) backwards;
+}
+@keyframes lr-num-drop {
+  0%   { transform: translateY(-40%) scale(1.6); opacity: 0; }
+  60%  { transform: translateY(0) scale(0.94);   opacity: 1; }
+  100% { transform: translateY(0) scale(1); }
+}
+
+/* past: 灰化 */
+.lr-slot-past {
+  border: var(--rule-w) solid var(--rule);
+  background: transparent;
+  opacity: 0.7;
+  filter: grayscale(0.4);
+}
+.lr-slot-past .lr-slot-num {
+  color: var(--text-mute);
+}
+
+/* ── slot internals ── */
+.lr-slot-num {
+  font-family: var(--hero-num-font, var(--font-display-en));
+  font-style: var(--hero-num-style, normal);
+  font-weight: var(--hero-num-weight, 700);
+  font-size: calc(var(--t-display-2) * 0.85);
+  letter-spacing: var(--hero-num-track, -0.02em);
+  line-height: 1;
+}
+.lr-slot-content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+.lr-slot-title {
+  font-family: var(--font-display-cn);
+  font-size: var(--t-h2);
+  letter-spacing: -0.005em;
+}
+.lr-slot-body {
+  font-family: var(--font-body);
+  font-size: var(--t-body);
+  color: var(--text-2);
+  line-height: 1.6;
+  max-width: 22ch;
+}

package/template/.hermes/skills/web-video-presentation/references/EXAMPLES/list-reveal/chapter.tsx

@@ -0,0 +1,103 @@
+// ⚠️ 这是 anchor 参考代码，不会被任何项目编译。
+//    抄到真实项目时（presentation/src/chapters/NN-list/），
+//    把下面两个 import 改成：
+//      import { MaskReveal } from "../../components/MaskReveal";
+//      import type { ChapterStepProps } from "../../registry/types";
+import { MaskReveal } from "../../../templates/src/components/MaskReveal";
+import type { ChapterStepProps } from "../../../templates/src/registry/types";
+import "./chapter.css";
+
+/**
+ * list-reveal · 完整章节示例
+ * ─────────────────────────────────────────
+ * 默认绑 newsroom 主题。
+ *
+ * 关键手段：
+ * - 槽位用 hero-num（serif 巨号）替代普通文字编号
+ * - 引子用 masthead 双线规则 + serif 大字
+ * - 槽位状态切换有专属动画：
+ *     ghost  → active：mask reveal 标题 + 数字砸下（accent 红）
+ *     active → past   ：accent 灰化（filter）
+ * - 关键：所有槽位的 React 节点位置不重排，只切换 className
+ */
+const ITEMS = [
+  { num: "01", title: "文字渲染", body: "图里的文字也能正确写出来" },
+  { num: "02", title: "指令遵循", body: "可以给到非常具体的要求" },
+  { num: "03", title: "照片真实感", body: "光影 / 材质 / 人物接近真实" },
+];
+
+export default function ListRevealChapter({ step }: ChapterStepProps) {
+  // step 1 — 引子
+  if (step === 0) {
+    return (
+      <div className="lr-scene scene-pad lr-intro">
+        <header className="lr-masthead">
+          <span className="lr-rule" />
+          <span className="lr-kicker">第一部分</span>
+          <span className="lr-rule" />
+        </header>
+        <MaskReveal show duration={1100}>
+          <h1 className="lr-intro-h">
+            强在<span className="lr-em">哪</span>
+          </h1>
+        </MaskReveal>
+        <MaskReveal show delay={400} duration={900}>
+          <div className="lr-intro-sub">三件事 —— 一个个看</div>
+        </MaskReveal>
+
+        <div className="lr-grid">
+          {ITEMS.map((it) => (
+            <Slot key={it.num} state="ghost" item={it} />
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  const activeIdx = step - 1;
+  return (
+    <div className="lr-scene scene-pad">
+      <header className="lr-masthead">
+        <span className="lr-rule" />
+        <span className="lr-kicker">第一部分 · 强在哪</span>
+        <span className="lr-rule" />
+      </header>
+
+      <div className="lr-grid">
+        {ITEMS.map((it, i) => {
+          const state =
+            i < activeIdx ? "past" : i === activeIdx ? "active" : "ghost";
+          return <Slot key={it.num} state={state} item={it} />;
+        })}
+      </div>
+    </div>
+  );
+}
+
+function Slot({
+  state,
+  item,
+}: {
+  state: "ghost" | "active" | "past";
+  item: { num: string; title: string; body: string };
+}) {
+  return (
+    <div className={`lr-slot lr-slot-${state}`}>
+      <div className="lr-slot-num">{item.num}</div>
+      <div className="lr-slot-content">
+        {state !== "ghost" && (
+          <>
+            <MaskReveal show duration={900} key={`${item.num}-title`}>
+              <div className="lr-slot-title">{item.title}</div>
+            </MaskReveal>
+            {state === "active" && (
+              <MaskReveal show delay={350} duration={900}>
+                <div className="lr-slot-body">{item.body}</div>
+              </MaskReveal>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,203 @@
+# `outline.md` 格式 spec
+
+视频章节规划的产出文件。**用户可以直接编辑**，所以格式必须人类友好
+（用 markdown 不用 JSON / YAML）。
+
+!重要：阅读此文件后必须继续阅读 [`CHAPTER-CRAFT.md`](CHAPTER-CRAFT.md) 的全部内容，了解对网页效果的真实需求，然后再开始编写 outline
+
+> ## ⚠️ outline 是开发计划，不是视觉规划
+>
+> outline 只规划**节奏 + 内容 + 信息密度**：
+>
+> - 章节切分 / 每章 step 数 / 每步估时
+> - 每步屏幕内容（hero / 标语 / 数据 / 列表项）
+> - 章节级**信息池**（从 article 抽的数字 / 引用 / 案例 / 标签）
+>
+> **outline 里的 step 数是初始预估**。最终 step 数以章节实现时的
+> `narrations.ts` 为准——后者既是 step 数源，也是音频合成源
+> （详见 [`CHAPTER-CRAFT.md`](CHAPTER-CRAFT.md) 「代码层最小约束」+
+> [`AUDIO.md`](AUDIO.md)）。如果实现时章节 step 数和 outline 不一致，
+> 回过来同步 outline 即可，不需要纠结"对得严丝合缝"。
+
+> **写 outline 前必读**（双源原则，[CHAPTER-CRAFT.md Part 0 原则 10](CHAPTER-CRAFT.md#10-双源原则scriptmd-定节拍--articlemd-定画面密度)）：
+>
+> - **`script.md`** —— 决定**节拍**：按 `---` 切节拍，每节拍 1~2 step、估时
+> - **`article.md`**（如有）—— 决定**画面信息密度**：每章首段抽**信息池**
+
+---
+
+## 抽象示例（看格式）
+
+````markdown
+# Video Outline
+
+> **主题**：`<theme-id>`（Checkpoint Plan 已选定）—— <一句话风格描述>
+> **总时长**：约 <T> 分 <S> 秒（口播 ~<X> 字 ÷ 4 字/秒）
+> **章节数**：<N> 章 / <M> 步
+
+---
+
+## 1. <chapter-id> — <章节标题>（<S> steps · ~<T>s）
+
+**信息池**（chapter agent 按需挂角标 / 副标 / pull-quote / mono cue）：
+- <类型：数字 / 引用 / 出处 / 案例 / 词义 / 时间 / 对比 / ...>：<内容> —— <来源 article §X / Lxx>
+- ...
+
+**开发计划**：
+
+- step 1 (~Ts) — <屏幕内容>
+- ...
+
+口播节选：
+> <1~3 句节选，对应到 script.md 完整文本>
+
+---
+
+## 2. <chapter-id> — ...
+````
+
+> **关于时长**：outline 里**只**写 step 的 `(~Ts)` 口播估时（音画对齐
+> 用），**绝对不写**动画时长 / 错峰量 / keyframe 数值。这些都在章节开发
+> 阶段决定（[`CHAPTER-CRAFT.md`](CHAPTER-CRAFT.md) Part 3 时长参考）。
+
+> **想看具象示例**：
+> - 钩子型开场结构 → [`EXAMPLES/hook-chapter/`](EXAMPLES/hook-chapter/)
+> - 列举型章节结构 → [`EXAMPLES/list-reveal/`](EXAMPLES/list-reveal/)
+> - 科技测评类（实测 / 对比 / 跑分） → [`EXAMPLES/case-tech-review/`](EXAMPLES/case-tech-review/)
+
+---
+
+## 字段约定
+
+### 顶部 metadata block
+
+用引用块（`>`）形式，方便扫一眼整体规模：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| **主题** | ✓ | Checkpoint Plan 必须已选定。chapter agent 实现时按主题颜色 / 字体 token 走，动画 / 节奏 / 视觉演示由章节自由发挥 |
+| **总时长** | ✓ | 估算口播时长（中文 ~ 250 字 / 分钟） |
+| **章节数** | ✓ | `N 章 / M 步` |
+
+### 章节标题：`## N. <id> — <title>（<S> steps · ~<T>s）`
+
+| 部分 | 规则 |
+|---|---|
+| `N` | 1-indexed 顺序，对齐 `chapters.ts` 的注册顺序 |
+| `<id>` | **小写 + 连字符**。会成为 React `key` / 文件夹名 (`src/chapters/0N-<id>/`) / 音频子目录 (`public/audio/<id>/`) |
+| `<title>` | 给人看的中文标题。**不会**进 React 代码 |
+| `<S> steps` | 该章 step 总数 |
+| `~<T>s` | 该章口播总估时（中文 ~ 4 字/秒） |
+
+合法 id：`coldopen`、`hook`、`why-good`、`why-good-text-render`。
+不合法：`why_good`（用连字符）、`Hook`（小写）、`第一章`（拉丁字符）。
+
+### 章节首段「信息池」（**双源原则核心落地**）
+
+每章独立列出从 `article.md` 抽的细节集合，**让 chapter agent 实现每步
+画面时按需取用**——可能挂成右下角 mono 角标 / 副标小字 /
+pull-quote 引用 / 数据浮层。
+
+#### 信息池条目格式
+
+```
+- <类型>：<具体内容> —— <来源 article §X / Lxx 或简注>
+```
+
+> **没 article（用户直接给 script）**：信息池退化为"主动设计画面信息
+> 密度"——靠数字 / 对比 / 元数据等让画面比口播信息密。可以列"画面
+> 装饰元素池"而非"article 抽取池"。
+
+### Step 列表：每步 **1 行**
+
+```
+- step N (~Ts) — <屏幕内容>
+```
+
+| 规则 | 原因 |
+|---|---|
+| `step N` 1-indexed | agent 实现时 `if (step === N - 1) ...`（注意零基偏移） |
+| **`(~Ts)`** 必填 | 按 script.md 本步对应口播段字数 ÷ 4 估算（中文 ~ 4 字/秒）。范围 3~10s |
+| **屏幕内容** | 一句话讲清楚这一步舞台上有什么：hero / 标语 / 数据 / 装饰元素。**≤ 1 行**，再多就该拆 step |
+| **不写动画** | 写死 = 翻译机化（详见本文件顶部框） |
+| **不写时长数值 / 错峰量** | 这些在章节开发阶段决定 |
+| **不写实现手段** | filter / SVG / Canvas 选型留给 chapter agent |
+
+
+### 口播节选（每章末尾，可选但推荐）
+
+精炼 1~3 句，**不是完整稿子**，仅供章节规划阶段对照"这章在讲什么"。
+完整文本回 `script.md`。`outline.md` 章节 = `script.md` 中两个明显
+主题切换之间的段落。
+
+> 音频合成（[`AUDIO.md`](AUDIO.md)）会**回到 `script.md`** 切分完整
+> 文本，**不**用 outline 节选。
+
+---
+
+## 命名规则速查
+
+| 对象 | 规则 | 示例 |
+|---|---|---|
+| 章节 id | 小写 + 连字符 | `coldopen`, `why-good` |
+| 章节文件夹 | `0N-<id>` | `src/chapters/01-coldopen/` |
+| 章节组件 | PascalCase | `Coldopen.tsx`, `WhyGood.tsx` |
+| 章节 CSS 类前缀 | 章节缩写（避免跨章冲突） | `.cd-` / `.wg-` / `.mg-` |
+| 音频子目录 | `<id>/` | `public/audio/coldopen/` |
+| 音频文件 | `<step-N>.mp3` (1-indexed) | `public/audio/coldopen/1.mp3` |
+
+---
+
+## 章节切分的经验法则
+
+- **每章 3~8 步**。少于 3 步太薄；多于 8 步观众会忘记这章在讲啥
+- **总时长 ÷ 30 秒** ≈ 章节数（一章约 30~60 秒讲完）
+- **每章 = 一个聚焦主题**。"为什么强 + 怎么用" 是两章，不是一章
+- **章节边界 = 口播稿里讲者会换语气 / 换主题的位置**。读 `script.md`
+  时哪里你下意识想"咳一声接下一段"，那里就是章节边界
+- **慢节奏 / 长镜头风主题**（midnight-press / 电影感片头）每章可少到
+  2~3 step；**信息密集型**（科技测评 / 对比表）每章可放宽到 8~10 step
+
+---
+
+## 素材清单（outline.md 末尾）
+
+```markdown
+## 素材清单
+
+### 1. coldopen
+- ✓ <资源 1 描述> （<已就位路径>）
+- ⚠️ <资源 2 描述>（待提供）
+- ⚠️ <资源 3 描述>（待提供）
+
+---
+
+## 自检（写完 outline **强制**执行，不可跳过）
+
+> ⚠️ **硬性流程**：outline 写完后**必须**走自检 → 修改 → 提交 三步。
+> **禁止**写完直接进入 Checkpoint Plan 让用户对齐。
+>
+> **执行方式**（按能力降级）：
+>
+> 1. **优先 Agent Teams**：开一个独立 reviewer agent，传入 `outline.md`
+>    + 本节自检清单 + `script.md` / `article.md` 路径，让它**逐项核查 +
+>    出结论**（哪几条 fail + 证据）。
+> 2. **其次 subAgent**：当前 agent 没 Teams 但能开 subagent，用 subagent
+>    走同样流程。
+> 3. **都没有**：自己**严格逐项**核查。
+>
+> 拿到结论后**先按 fail 项改 outline，再进入 Checkpoint Plan**。
+
+- [ ] 每个 step 都是**单一句屏幕内容描述**，没有"动画"行 / "手段"行
+- [ ] 没有任何 step 写了具体毫秒 / 秒数（除 `(~Ts)` 口播估时）
+- [ ] 每章首段都有「信息池」block，至少 3 条 article 抽取项，**每条
+      必带来源标注**（`—— 来源 article §X / Lxx`）—— 没标注 chapter agent
+      回不到原文
+- [ ] **所有 step `(~Ts)` 累加 ≈ 顶部声明的总时长**（误差 < 10%）—— 不
+      一致说明节奏规划失真
+- [ ] 章节切分符合"每章 3~8 步 / 30~60s 一聚焦主题"经验
+- [ ] 末尾「素材清单」分章节列出，✓ / ⚠️ 标注清楚
+- [ ] 脚本不得包含标题、序号等非口播内容，仅包含人类正常可读的内容
+
+写完看一眼：**outline 是不是干净到 chapter agent 看了能立刻开工 + 还有
+设计空间**？是 = 合格。如果你看了都觉得"太空，agent 不知道动画选什么"

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

@@ -0,0 +1,77 @@
+# 录制与后期合成
+
+网页做完 + 音频合成完之后，**Auto 模式 + 屏幕录制可以一镜到底**——
+不需要手动点击推进 step、也不需要后期对音频。
+
+如果你不打音频，仍可走"手动点击 + 后期配"的传统路径（在文档末尾）。
+
+---
+
+## 推荐流程：Auto 模式一镜到底
+
+### 前置
+
+- 章节代码做完，每章都有 `narrations.ts`
+- 已经跑过 `npm run extract-narrations` + `npm run synthesize-audio`，
+  `public/audio/<id>/<step>.mp3` 全部就位
+- `npm run dev` 跑着，浏览器能打开页面
+
+### 录制步骤
+
+1. **浏览器全屏**（F11 / Ctrl+Cmd+F），URL 改成
+   `http://localhost:5173/?auto=1`
+2. 看到 "Press SPACE to start" 蒙层 = Auto 模式就绪
+3. **打开屏幕录制**（QuickTime / OBS / Cmd+Shift+5），开始录
+4. **按一次 Space** → 蒙层消失 → step 0 出现，1.mp3 自动播 →
+   播完自动推进到 step 1 → 2.mp3 → … → 最后一个 step 播完 → 停在终态
+5. **停止录制** → 后期裁掉头尾（Space 那一下、最后停在终态的尾巴）就是
+   成品
+
+整个过程**完全不用点鼠标**。音视频天然同步，不需要后期对轨。
+
+> **Auto 模式严格按音频结束推进**（+ 200ms 缓冲），没有"等动画跑完"
+> 的兜底。如果你看到某步动画被切了一半 → 说明该 step 动画长于口播，
+> 回章节代码改：写更长口播 / 拆 step / 调动画速度。
+
+### 录屏工具
+
+| 平台 | 工具 | 设置 |
+|---|---|---|
+| macOS | Cmd+Shift+5 → 录制选定窗口 | 选浏览器窗口；浏览器全屏后输出就是 1920×1080 |
+| macOS | QuickTime → 文件 → 新建屏幕录制 | 同上 |
+| 跨平台 | OBS Studio | 窗口捕获，Canvas 1920×1080，60fps |
+
+### 模式速查
+
+| URL / 快捷键 | 行为 |
+|---|---|
+| 直接打开（默认） | Manual：点击 / ←→ 推进，不播音频 |
+| `?audio=1` 或按 `M` | Audio：进入 step 自动播音频，但**手动点鼠标推进** |
+| `?audio=1` + 再按 `M` | Auto：进入 step 自动播 + 自动推进（录制用） |
+| Auto 模式下首次按 `Space` | 启动 Auto 播放（绕过浏览器自动播放限制） |
+
+也可以鼠标移到右上角，会出现一个隐藏的模式切换按钮。
+
+---
+
+## 备用流程：没合成音频时手动录屏
+
+如果你跳过了音频合成（`Checkpoint Audio` 选了"不合成"），按老方法：
+
+1. 浏览器全屏 → 打开 `localhost:5173`（默认 Manual 模式）
+2. **刷新一次**清空历史 step
+3. 开始录屏 → 按口播节奏点击空白推进 step
+4. 后期用任何剪辑软件配音 + 调时间线
+
+### 后期工具
+
+| 工具 | 适合 |
+|---|---|
+| **DaVinci Resolve** | 跨平台免费、能处理多段音频拼接 |
+| **iMovie** | macOS 简单场景 |
+| **CapCut / 剪映** | B 站 / 抖音风加字幕 |
+
+---
+
+> agent 在 Checkpoint Audio 后**主动告诉用户**上面 Auto 模式录屏的
+> 路径，让用户知道下一步怎么把网页变成 mp4。