wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/huashu-design/references/brand-asset-protocol.md

@@ -0,0 +1,250 @@
+# 核心资产协议（完整版）
+
+> 从 SKILL.md「核心哲学 #1.a」下沉的完整协议（2026-06 瘦身）。SKILL.md 留了触发条件 + 5 步标题 + 自检；这里是 5 步详细操作、下载命令、brand-spec 模板、全流程失败兜底、反例与代价对比。
+> 触发：任务涉及具体品牌/产品时强制执行。回 SKILL.md 看精简版与上下文。
+
+#### 1.a 核心资产协议（涉及具体品牌时强制执行）
+
+> **这是 v1 最核心的约束，也是稳定性的生命线。** Agent 是否走通这个协议，直接决定输出质量是 40 分还是 90 分。不要跳过任何一步。
+>
+> **v1.1 重构（2026-04-20）**：从「品牌资产协议」升级为「核心资产协议」。之前的版本过度聚焦色值和字体，漏掉了设计中最基础的 logo / 产品图 / UI 截图。花叔的原话：「除了所谓的品牌色，显然我们应该找到并且用上大疆的 logo，用上 pocket4 的产品图。如果是网站或者 app 等非实体产品的话，logo 至少该是必须的。这可能是比所谓的品牌设计的 spec 更重要的基本逻辑。否则，我们在表达什么呢？」
+
+**触发条件**：任务涉及具体品牌——用户提了产品名/公司名/明确客户（Stripe、Linear、Anthropic、Notion、Lovart、DJI、自家公司等），不论用户是否主动提供了品牌资料。
+
+**前置硬条件**：走协议前必须已通过「#0 事实验证先于假设」确认品牌/产品存在且状态已知。如果你还不确定产品是否已发布/规格/版本，先回去搜。
+
+##### 核心理念：资产 > 规范
+
+**品牌的本质是「它被认出来」**。认出来靠什么？按识别度排序：
+
+| 资产类型 | 识别度贡献 | 必需性 |
+|---|---|---|
+| **Logo** | 最高 · 任何品牌出现 logo 就一眼识别 | **任何品牌都必须有** |
+| **产品图/产品渲染图** | 极高 · 实体产品的"主角"就是产品本身 | **实体产品（硬件/包装/消费品）必须有** |
+| **UI 截图/界面素材** | 极高 · 数字产品的"主角"是它的界面 | **数字产品（App/网站/SaaS）必须有** |
+| **色值** | 中 · 辅助识别，脱离前三项时经常撞衫 | 辅助 |
+| **字体** | 低 · 需配合前述才能建立识别 | 辅助 |
+| **气质关键词** | 低 · agent 自检用 | 辅助 |
+
+**翻译成执行规则**：
+- 只抽色值 + 字体、不找 logo / 产品图 / UI → **违反本协议**
+- 用 CSS 剪影/SVG 手画替代真实产品图 → **违反本协议**（生成的就是「通用科技动画」，任何品牌都长一样）
+- 找不到资产不告诉用户、也不 AI 生成，硬做 → **违反本协议**
+- 宁可停下问用户要素材，也不要用 generic 填充
+
+##### 5 步硬流程（每步有 fallback，绝不静默跳过）
+
+##### Step 1 · 问（资产清单一次问全）
+
+不要只问「有 brand guidelines 吗？」——太宽泛，用户不知道该给什么。按清单逐项问：
+
+```
+关于 <brand/product>，你手上有以下哪些资料？我按优先级列：
+1. Logo（SVG / 高清 PNG）—— 任何品牌必备
+2. 产品图 / 官方渲染图 —— 实体产品必备（如 DJI Pocket 4 的产品照）
+3. UI 截图 / 界面素材 —— 数字产品必备（如 App 主要页面截图）
+4. 色值清单（HEX / RGB / 品牌色盘）
+5. 字体清单（Display / Body）
+6. Brand guidelines PDF / Figma design system / 品牌官网链接
+
+有的直接发我，没有的我去搜/抓/生成。
+```
+
+##### Step 2 · 搜官方渠道（按资产类型）
+
+| 资产 | 搜索路径 |
+|---|---|
+| **Logo** | `<brand>.com/brand` · `<brand>.com/press` · `<brand>.com/press-kit` · `brand.<brand>.com` · 官网 header 的 inline SVG |
+| **产品图/渲染图** | `<brand>.com/<product>` 产品详情页 hero image + gallery · 官方 YouTube launch film 截帧 · 官方新闻稿附图 |
+| **UI 截图** | App Store / Google Play 产品页截图 · 官网 screenshots section · 产品官方演示视频截帧 |
+| **色值** | 官网 inline CSS / Tailwind config / brand guidelines PDF |
+| **字体** | 官网 `<link rel="stylesheet">` 引用 · Google Fonts 追踪 · brand guidelines |
+
+`WebSearch` 兜底关键词：
+- Logo 找不到 → `<brand> logo download SVG`、`<brand> press kit`
+- 产品图找不到 → `<brand> <product> official renders`、`<brand> <product> product photography`
+- UI 找不到 → `<brand> app screenshots`、`<brand> dashboard UI`
+
+##### Step 3 · 下载资产 · 按类型三条兜底路径
+
+**3.1 Logo（任何品牌必需）**
+
+> ⚠️ **别只试 `curl <brand>.com/logo.svg` 就放弃**——现在的官网大多是 SPA，直连静态路径基本返回空壳 HTML（2026-06-06 实测 Trae 官网 5 条直连路径全是空壳）。**数字产品 / SaaS / AI 工具优先用图标聚合源**，命中率最高、直出干净 SVG。
+
+按成功率递减：
+0. **图标聚合源（知名数字产品/SaaS/AI 工具首选，命中率最高）**：
+   ```bash
+   unset ALL_PROXY HTTP_PROXY HTTPS_PROXY all_proxy http_proxy https_proxy   # 清代理，否则 TLS 易炸
+   # svgl —— AI/开发者品牌覆盖最全（Claude/Cursor/OpenAI/Copilot/Anthropic/Vercel…），含 light/dark + wordmark
+   curl -s "https://api.svgl.app?search=<brand>"   # 返回 JSON，取 route(.light/.dark) 的 svg URL 再下载
+   # simpleicons —— 单色 glyph，可直接按品牌色上色
+   curl -o logo.svg "https://cdn.simpleicons.org/<slug>/<hexcolor>"
+   ```
+1. 独立 SVG/PNG 文件 / 官方 brand 页（如 `<brand>.com/brand`、`/press`）：
+   ```bash
+   curl -A "Mozilla/5.0" -L -o assets/<brand>-brand/logo.svg "<official-logo-url>"
+   ```
+2. 官网 HTML 全文提取 inline SVG：
+   ```bash
+   curl -A "Mozilla/5.0" -L https://<brand>.com -o assets/<brand>-brand/homepage.html
+   # 然后 grep <svg>...</svg> 提取 logo 节点
+   ```
+3. **Google favicon 服务（站点真实 mark 兜底，几乎不失败）**：
+   ```bash
+   curl -o logo.png "https://www.google.com/s2/favicons?domain=<brand-domain>&sz=256"   # 256px 官方站点图标
+   ```
+4. 官方社交媒体 avatar（最后手段）：GitHub/Twitter/LinkedIn 的公司头像通常是 400×400 或 800×800 透明底 PNG
+
+下载后**逐个核对**：`file <logo>` 确认是真 SVG/PNG（不是 106 字节占位或 HTML 空壳），`head -c 90 <logo.svg>` 看是否 `<svg`。
+
+**3.2 产品图/渲染图（实体产品必需）**
+
+按优先级：
+1. **官方产品页 hero image**（最高优先级）：右键查看图片地址 / curl 获取。分辨率通常 2000px+
+2. **官方 press kit**：`<brand>.com/press` 常有高清产品图下载
+3. **官方 launch video 截帧**：用 `yt-dlp` 下载 YouTube 视频，ffmpeg 抽几帧高清图
+4. **Wikimedia Commons**：公共领域常有
+5. **AI 生成兜底**（nano-banana-pro）：把真实产品图作为参考发给 AI，让它生成符合动画场景的变体。**不要用 CSS/SVG 手画代替**
+
+```bash
+# 示例：下载 DJI 官网产品 hero image
+curl -A "Mozilla/5.0" -L "<hero-image-url>" -o assets/<brand>-brand/product-hero.png
+```
+
+**3.3 UI 截图（数字产品必需）**
+
+- App Store / Google Play 的产品截图（注意：可能是 mockup 而非真实 UI，要对比）
+- 官网 screenshots section
+- 产品演示视频截帧
+- 产品官方 Twitter/X 的发布截图（常是最新版本）
+- 用户有账号时，直接截屏真实产品界面
+
+**3.4 · 素材质量门槛「5-10-2-8」原则（铁律）**
+
+> **Logo 的规则不同于其他素材**。Logo 有就必须用（没有就停下问用户）；其他素材（产品图/UI/参考图/配图）遵循「5-10-2-8」质量门槛。
+>
+> 2026-04-20 花叔原话：「我们的原则是搜索 5 轮，找到 10 个素材，选择 2 个好的。每个需要评分 8/10 以上，宁可少一些，也不为了完成任务滥竽充数。」
+
+| 维度 | 标准 | 反模式 |
+|---|---|---|
+| **5 轮搜索** | 多渠道交叉搜（官网 / press kit / 官方社媒 / YouTube 截帧 / Wikimedia / 用户账号截屏），不是一轮抓前 2 个就停 | 第一页结果直接用 |
+| **10 个候选** | 至少凑 10 个备选才开始筛 | 只抓 2 个，没得选 |
+| **选 2 个好的** | 从 10 个里精选 2 个作为最终素材 | 全都用 = 视觉过载 + 品位稀释 |
+| **每个 8/10 分以上** | 不够 8 分**宁可不用**，用诚实 placeholder（灰块+文字标签）或 AI 生成（nano-banana-pro 以官方参考为基底）| 凑数 7 分素材进 brand-spec.md |
+
+**8/10 评分维度**（打分时记录在 `brand-spec.md`）：
+
+1. **分辨率** · ≥2000px（印刷/大屏场景 ≥3000px）
+2. **版权清晰度** · 官方来源 > 公共领域 > 免费素材 > 疑似盗图（疑似盗图直接 0 分）
+3. **与品牌气质契合度** · 和 brand-spec.md 里的「气质关键词」一致
+4. **光线/构图/风格一致性** · 2 个素材放一起不打架
+5. **独立叙事能力** · 能单独表达一个叙事角色（不是装饰）
+
+**为什么这个门槛是铁律**：
+- 花叔的哲学：**宁缺毋滥**。滥竽充数的素材比没有更糟——污染视觉品味、传递「不专业」信号
+- **「一个细节做到 120%，其他做到 80%」的量化版**：8 分是"其他 80%" 的底线，真正 hero 素材要 9-10 分
+- 消费者看作品时，每一个视觉元素都在**积分或扣分**。7 分素材 = 扣分项，不如留空
+
+**Logo 例外**（重申）：有就必须用，不适用「5-10-2-8」。因为 logo 不是「多选一」问题，而是「识别度根基」问题——就算 logo 本身只有 6 分，也比没有 logo 强 10 倍。
+
+##### Step 4 · 验证 + 提取（不只是 grep 色值）
+
+| 资产 | 验证动作 |
+|---|---|
+| **Logo** | 文件存在 + SVG/PNG 可打开 + 至少两个版本（深底/浅底用）+ 透明背景 |
+| **产品图** | 至少一张 2000px+ 分辨率 + 去背或干净背景 + 多个角度（主视角、细节、场景） |
+| **UI 截图** | 分辨率真实（1x / 2x）+ 是最新版本（不是旧版）+ 无用户数据污染 |
+| **色值** | `grep -hoE '#[0-9A-Fa-f]{6}' assets/<brand>-brand/*.{svg,html,css} \| sort \| uniq -c \| sort -rn \| head -20`，过滤黑白灰 |
+
+**警惕示范品牌污染**：产品截图里常有用户 demo 的品牌色（如某工具截图演示喜茶红），那不是该工具的色。**同时出现两种强色时必须区分**。
+
+**品牌多切面**：同一品牌的官网营销色和产品 UI 色经常不同（Lovart 官网暖米+橙，产品 UI 是 Charcoal + Lime）。**两套都是真的**——根据交付场景选合适的切面。
+
+##### Step 5 · 固化为 `brand-spec.md` 文件（模板必须覆盖所有资产）
+
+```markdown
+# <Brand> · Brand Spec
+> 采集日期：YYYY-MM-DD
+> 资产来源：<列出下载来源>
+> 资产完整度：<完整 / 部分 / 推断>
+
+## 🎯 核心资产（一等公民）
+
+### Logo
+- 主版本：`assets/<brand>-brand/logo.svg`
+- 浅底反色版：`assets/<brand>-brand/logo-white.svg`
+- 使用场景：<片头/片尾/角落水印/全局>
+- 禁用变形：<不能拉伸/改色/加描边>
+
+### 产品图（实体产品必填）
+- 主视角：`assets/<brand>-brand/product-hero.png`（2000×1500）
+- 细节图：`assets/<brand>-brand/product-detail-1.png` / `product-detail-2.png`
+- 场景图：`assets/<brand>-brand/product-scene.png`
+- 使用场景：<特写/旋转/对比>
+
+### UI 截图（数字产品必填）
+- 主页：`assets/<brand>-brand/ui-home.png`
+- 核心功能：`assets/<brand>-brand/ui-feature-<name>.png`
+- 使用场景：<产品展示/Dashboard 渐现/对比演示>
+
+## 🎨 辅助资产
+
+### 色板
+- Primary: #XXXXXX  <来源标注>
+- Background: #XXXXXX
+- Ink: #XXXXXX
+- Accent: #XXXXXX
+- 禁用色: <品牌明确不用的色系>
+
+### 字型
+- Display: <font stack>
+- Body: <font stack>
+- Mono（数据 HUD 用）: <font stack>
+
+### 签名细节
+- <哪些细节是「120% 做到」的>
+
+### 禁区
+- <明确不能做的：比如 Lovart 不用蓝色、Stripe 不用低饱和暖色>
+
+### 气质关键词
+- <3-5 个形容词>
+```
+
+**写完 spec 后的执行纪律（硬要求）**：
+- 所有 HTML 必须**引用** `brand-spec.md` 里的资产文件路径，不允许用 CSS 剪影/SVG 手画代替
+- Logo 作为 `<img>` 引用真实文件，不重画
+- 产品图作为 `<img>` 引用真实文件，不用 CSS 剪影代替
+- CSS 变量从 spec 注入：`:root { --brand-primary: ...; }`，HTML 只用 `var(--brand-*)`
+- 这让品牌一致性从「靠自觉」变成「靠结构」——想临时加色要先改 spec
+
+##### 全流程失败的兜底
+
+按资产类型分别处理：
+
+| 缺失 | 处理 |
+|---|---|
+| **Logo 完全找不到** | **停下问用户**，不要硬做（logo 是品牌识别度的根基） |
+| **产品图（实体产品）找不到** | 优先 nano-banana-pro AI 生成（以官方参考图为基底）→ 次选向用户索取 → 最后才是诚实 placeholder（灰块+文字标签，明确标注"产品图待补"） |
+| **UI 截图（数字产品）找不到** | 向用户索取自己账号的截屏 → 官方演示视频截帧。不用 mockup 生成器凑 |
+| **色值完全找不到** | 按「设计方向顾问模式」走，向用户推荐 3 个方向并标注 assumption |
+
+**禁止**：找不到资产就静默用 CSS 剪影/通用渐变硬做——这是协议最大的反 pattern。**宁可停下问，也不要凑**。
+
+##### 反例（真实踩过的坑）
+
+- **Kimi 动画**：凭记忆猜「应该是橙色」，实际 Kimi 是 `#1783FF` 蓝色——返工一遍
+- **Lovart 设计**：把产品截图里演示品牌的喜茶红当成 Lovart 自己的色——差点毁整个设计
+- **DJI Pocket 4 发布动画（2026-04-20，触发本协议升级的真实案例）**：走了旧版只抽色值的协议，没下载 DJI logo、没找 Pocket 4 产品图，用 CSS 剪影代替产品——做出来是「通用黑底+橙 accent 的科技动画」，没有大疆识别度。花叔原话：「否则，我们在表达什么呢？」→ 协议升级。
+- 抽完色没写进 brand-spec.md，第三页就忘了主色数值，临场加了个「接近但不是」的 hex——品牌一致性崩溃
+- **五大 Coding Agent 对比 PPT（2026-06-06，触发触发条件扩展的真实案例）**：agent 把任务判成「PPT + 没风格参考」走 Fallback 设计方向顾问，只抽了五家品牌色就 spawn 三套设计逻辑，**五个产品 logo（Claude Code / Cursor / Codex / Copilot / Trae）一个没取**——被花叔抓现行「我们为什么没去取这些产品的 logo」。根因：把「对比 / 榜单 deck」误判为不触发 §1.a（以为 §1.a 只管「为单一客户做物料」），且 Fallback 路径里没有任何 logo 检查点。→ 修复：①触发条件扩成两类（含「设计里点名/并列真实产品」）②Fallback 不豁免取 logo ③Phase 3.5 加「具名产品 logo 子门」spawn 前必过 ④Step 3.1 补 svgl/simpleicons/Google favicon 可靠取图链。
+
+##### 协议代价 vs 不做代价
+
+| 场景 | 时间 |
+|---|---|
+| 正确走完协议 | 下载 logo 5 min + 下载 3-5 张产品图/UI 10 min + grep 色值 5 min + 写 spec 10 min = **30 分钟** |
+| 不做协议的代价 | 做出没识别度的通用动画 → 用户返工 1-2 小时，甚至重做 |
+
+**这是稳定性最便宜的投资**。尤其对商单/发布会/重要客户项目，30 分钟的资产协议是保命钱。
+

package/src/skills-lib/huashu-design/references/cinematic-patterns.md

@@ -0,0 +1,264 @@
+# Cinematic Patterns · Workflow Demo 的 Best Practice
+
+> 从「PPT 动画」升级到「发布会级 cinematic」的 5 个关键 pattern。
+> 蒸馏自 2026-04 「聊聊 skill」 deck 的两个 cinematic demo（Nuwa workflow + Darwin workflow），实测可复现。
+
+---
+
+## 0 · 这份文档解决什么问题
+
+当你需要做「演示一个工作流的 demo 动画」时（典型场景：skill 工作流、产品 onboarding、API 调用流程、agent 任务执行），有两种常见做法：
+
+| 范式 | 长什么样 | 后果 |
+|---|---|---|
+| **PPT 动画**（差） | step 1 fade in → step 2 fade in → step 3 fade in，4 个 box 同屏排列 | 观众感觉「就是一个 PPT 加了 fade 效果」，没有 wow moment |
+| **Cinematic**（好） | scene-based，一次只 focus 一件事，scene 之间是 dissolve / focus pull / morph | 观众感觉「这是一个产品发布会片段」，会想截图分享 |
+
+差异的根源**不是动画技术**，是**叙事范式**。本文档讲怎么从前者升级到后者。
+
+---
+
+## 1 · 五个核心 pattern
+
+### Pattern A · Dashboard + Cinematic Overlay 双层结构
+
+**问题**：单纯的 cinematic 默认是黑屏 + 一个 ▶ 按钮，用户翻到这页如果没点，什么都看不到。
+
+**解决**：
+```
+DEFAULT 状态 (永远显示)：完整静态 workflow dashboard
+  └── 观众一眼看清这个 skill / 工作流怎么跑
+
+POINT ▶ 触发 (overlay 浮上来)：22 秒 cinematic
+  └── 跑完自动 fade 回 DEFAULT
+
+```
+
+**实现要点**：
+- `.dash` 默认 visible，`.cinema` 默认 `opacity: 0; pointer-events: none`
+- `.play-cta` 是右下角金色小按钮（不是中央大覆盖）
+- 点击 → `cinema.classList.add('show')` + `dash.classList.add('hide')`
+- 用 `requestAnimationFrame` 跑一次（不是循环），结束后 `endCinematic()` reverse 状态
+
+**反 pattern**：默认 = 中央大 ▶ overlay 覆盖一切，没点之前页面是空白的。
+
+---
+
+### Pattern B · Scene-based, NOT Step-based
+
+**问题**：把动画拆成「step 1 显示 → step 2 显示 → ...」就是 PPT 思维。
+
+**解决**：拆成 5 个 scene，每个 scene 是**独立的镜头**，全屏只 focus 一件事：
+
+| Scene 类型 | 职责 | 时长 |
+|---|---|---|
+| 1 · Invoke | 用户输入触发（终端 typewriter）| 3-4s |
+| 2 · Process | 核心工作流的可视化（独特视觉语言）| 5-6s |
+| 3 · Result/Insight | 提炼出的关键产物（可视化）| 4-5s |
+| 4 · Output | 实际产物展示（文件 / diff / 数字）| 3-4s |
+| 5 · Hero Reveal | 收尾 hero moment（大字 + 价值主张）| 4-5s |
+
+**总时长 ≈ 22 秒**——这是经过测试的黄金长度：
+- 短于 18 秒：PM 还没进入状态就结束了
+- 长于 25 秒：失去耐心
+- 22 秒刚好够「钩住 → 展开 → 收束 → 留下印象」
+
+**实现要点**：
+- `T = { DURATION: 22.0, s1_in: [0, 0.7], s2_in: [3.8, 4.6], ... }` 全局时间轴
+- 单个 `requestAnimationFrame(render)` 跑所有 scene 的 opacity / transform 计算
+- 不要用 setTimeout 链（容易断掉、难调试）
+- Easing 必用 `expoOut` / `easeOut` / cubic-bezier，**禁止 linear**
+
+---
+
+### Pattern C · 每个 demo 的视觉语言必须独立
+
+**问题**：做完第一个 cinematic 后，做第二个时偷懒复用同一个模板（同样的 orbit + pentagon + typewriter + hero 大字），只换了文案。
+
+**后果**：观众发现两个 skill「长得一模一样」，等于在说「这两个 skill 没区别」。
+
+**解决**：每个工作流的核心隐喻不同，视觉语言就必须不同。
+
+**对照案例**：
+
+| 维度 | Nuwa（蒸馏人）| Darwin（优化 skill）|
+|---|---|---|
+| 核心隐喻 | 收集 → 提炼 → 写 | 循环 → 评估 → 棘轮 |
+| 视觉运动 | 漂浮 / 辐射 / pentagon | 循环 / 上升 / 对比 |
+| Scene 2 | 3D Orbit · 8 张档案在透视椭圆漂浮 | Spin Loop · token 沿 6 节点圆环跑 5 圈 |
+| Scene 3 | Pentagon · 5 token 从中央辐射 | v1 vs v5 · 并列 diff（红版 vs 金版） |
+| Scene 4 | SKILL.md typewriter | Hill-Climb · 全屏曲线绘制 |
+| Scene 5 hero | 「21 分钟」serif italic 大字 | 旋转齿轮 ⚙ + 「KEPT +1.1」金色 tag |
+
+**判断标准**：盖住文案，只看视觉，能不能区分这是哪个 demo？区分不了就是偷懒。
+
+---
+
+### Pattern D · 用 AI 生成的真实素材，不要 emoji 或 SVG 手画
+
+**问题**：3D orbit / gallery 里需要素材碎片漂浮，emoji（📚🎤）丑且无品牌、SVG 手画书脊永远不像真书。
+
+**解决**：用 `huashu-gpt-image` 跑一张 4×2 grid 大图（8 件主题相关物品 · 白底 · 60px breathing space · unified style），用 `extract_grid.py --mode bbox` 抠成 8 张独立透明 PNG。
+
+**Prompt 要点**（详细 prompt patterns 见 `huashu-gpt-image` skill）：
+- IP 锚定（"1960s Caltech archive aesthetic" / "Hearthstone-style consistent treatment"）
+- 白底（便于抠图，灰底氛围好但抠透明背景困难）
+- 4×2 不要 5×5（避免末行压缩 bug）
+- Persona finishing（"You are a Wired magazine curator preparing an exhibition photo"）
+
+**反 pattern**：用 emoji 当 icon、用 CSS 剪影代替产品图。
+
+---
+
+### Pattern E · BGM + SFX 双轨制
+
+**问题**：只有动画没有声音，观众潜意识感觉「这玩意像个穷酸 demo」。
+
+**解决**：BGM 长音 + 11 个 SFX cues。
+
+**通用 SFX cue 配方**（适用于工作流 demo）：
+
+| 时点 | SFX | 触发场景 |
+|---|---|---|
+| 0.10s | whoosh | 终端从下方升起 |
+| 3.0s | enter | typewriter 完成、按 enter |
+| 4.0s | slide-in | scene 2 元素入场 |
+| 5-9s × 5 次 | sparkle | 关键过程节点（每代 / 每个 token / 每个数据点）|
+| 14s | click | 切换到 output scene |
+| 17.8s | logo-reveal | hero reveal 时刻 |
+| typewriter | type | 每 2 字符触发一次（密度别太高）|
+
+**频段隔离**：BGM volume 0.32（低频底噪），SFX volume 0.55（中高频 punch），sparkle 0.7（要醒目），logo-reveal 0.85（最强 hero moment）。
+
+**用户控制**：
+- 必须有 ▶ 启动覆盖（浏览器 autoplay 限制）
+- 右上角小 mute 按钮（用户随时切静音）
+- 不要做成「翻到这页就强制响」
+
+---
+
+## 2 · 静态 Dashboard 设计要点
+
+Dashboard 是双层结构的 Layer 1，PM 不点 ▶ 也能看懂这个 skill。
+
+**布局**：3 列 grid（或 1 大 + 2 小），每个 panel 解决一个问题：
+
+| Panel 类型 | 解决什么问题 | 案例 |
+|---|---|---|
+| **Pipeline / Flow Diagram** | 「这个 skill 的工作流程是什么？」| Nuwa 4 阶段 pipeline · Darwin autoresearch loop |
+| **Snapshot / State** | 「跑出来的真实数据长什么样？」| Darwin 8 维 rubric snapshot |
+| **Trajectory / Evolution** | 「多次运行后怎么变化？」| Darwin 5 代 hill-climb 曲线 |
+| **Examples / Gallery** | 「已经产出过哪些东西？」| Nuwa 21 personas gallery |
+| **Strip · Example I/O** | 「输入什么 → 输出什么」| Nuwa example strip：`› nuwa 蒸馏 费曼 → feynman.skill (21 min)` |
+
+**关键约束**：
+- 信息密度要够（每个 panel 都要承载差异化信息）
+- 但不能塞数据 slop（每个数字都要有意义）
+- 配色与 cinematic 一致（同色系，方便切换不突兀）
+
+---
+
+## 3 · 调试与开发工具
+
+任何长动画必须配三个 dev 工具，否则调试会爆炸。
+
+### 工具 1 · `?seek=N` 冻结到第 N 秒
+
+```js
+const seek = parseFloat(params.get('seek'));
+if (!isNaN(seek)) {
+  started = true; muted = true;
+  frozenT = seek;  // render() 用这个 t 而不是 elapsed
+  cinema.classList.add('show'); dash.classList.add('hide');
+}
+
+// render() 里：
+let t = frozenT !== null ? frozenT : (elapsed % T.DURATION);
+```
+
+用法：`http://.../slide.html?seek=12` 直接看第 12 秒画面，不用等播放。
+
+### 工具 2 · `?autoplay=1` 跳过 ▶ overlay
+
+方便 playwright 自动截图测试，也方便嵌入 iframe 时 force 启动。
+
+### 工具 3 · 手动 REPLAY 按钮
+
+右上角小按钮，用户/调试时可以重播任意次。CSS：
+
+```css
+.replay{position:absolute;top:18px;right:18px;background:rgba(212,165,116,0.1);
+  border:1px solid rgba(212,165,116,0.3);color:#D4A574;
+  font-family:monospace;font-size:10px;letter-spacing:.28em;text-transform:uppercase;
+  padding:6px 12px;border-radius:1px;cursor:pointer;backdrop-filter:blur(6px);z-index:6}
+```
+
+---
+
+## 4 · iframe 嵌入坑（如果 cinematic 嵌在 deck 里）
+
+### 坑 1 · 父窗口的 click zone 拦截 iframe 内按钮
+
+如果 deck index.html 加了「左右 22vw 透明 click zone 翻页」，会**覆盖到 iframe 内的 ▶ play 按钮**——用户点按钮被吞成「下一页」。
+
+**修复**：click zone 加 `top: 12vh; bottom: 25vh`，给顶部和底部 25% 不拦截，让 iframe 内的中央 ▶ 和右下角 ▶ 都能点。
+
+### 坑 2 · iframe 抢焦点后键盘事件丢失
+
+用户点过 iframe 后，焦点在 iframe 里，父窗口的 ←/→ 键盘事件收不到。
+
+**修复**：
+```js
+iframe.addEventListener('load', () => {
+  // 注入键盘转发器
+  const doc = iframe.contentDocument;
+  doc.addEventListener('keydown', (e) => {
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: e.key, ... }));
+  });
+  // 点击后焦点拽回父窗口
+  doc.addEventListener('click', () => setTimeout(() => window.focus(), 0));
+});
+```
+
+### 坑 3 · file:// vs https:// 行为差异
+
+本地 file:// 测好的 cinematic 部署后可能崩，因为：
+- file:// 下 iframe contentDocument 同源
+- https:// 下也同源（如果同 host），但 audio autoplay 限制更严格
+
+**修复**：
+- 部署前用 `python3 -m http.server` 起本地 HTTP 测试一遍
+- BGM 必须等用户点击 ▶ 后再 `bgm.play()`，不要 page-load 立刻播
+
+---
+
+## 5 · 反 pattern 速查表
+
+| ❌ 反 pattern | ✅ 正 pattern |
+|---|---|
+| 默认 = 黑屏 ▶ overlay | 默认 = 静态 dashboard，▶ 是辅助 |
+| 4 个 step 横排同屏 fade in | 5 个 scene 全屏切换，每场只 focus 一件事 |
+| 复用模板换文案做不同 demo | 每个 demo 独立视觉语言（盖文案能区分） |
+| emoji / SVG 手画当素材 | gpt-image-2 大图 + extract_grid 抠图 |
+| 无 BGM 无 SFX | BGM + 11 SFX cues 双轨制 |
+| 用 setTimeout 链 schedule | requestAnimationFrame + 全局时间轴 T 对象 |
+| linear 动画 | Expo / cubic-bezier easing |
+| 没有 dev 工具 | `?seek=N` + `?autoplay=1` + REPLAY 按钮 |
+| iframe 内的按钮被父 click zone 吞 | click zone 加 top/bottom margin 给按钮让位 |
+
+---
+
+## 6 · 时间预算
+
+按这套 pattern，一个完整 cinematic demo（含 dashboard）：
+
+| 任务 | 时间 |
+|---|---|
+| 设计 5-scene narrative + 视觉语言 | 30 分钟（要慎重，决定独立性）|
+| Dashboard 静态布局 + 内容 | 1 小时 |
+| Cinematic 5 scenes 实现 | 1.5 小时 |
+| Audio cues 调时序 + replay 按钮 | 30 分钟 |
+| Playwright 截图验证 5 个关键时刻 | 15 分钟 |
+| **单个 demo 总计** | **3-4 小时** |
+
+第二个 demo 复用框架但**视觉语言必须独立**，时间约 2-3 小时。