@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/creative/creative-ideation/references/methods/triz-principles.md

@@ -0,0 +1,95 @@
+# TRIZ — 发明问题解决理论
+
+Genrich Altshuller，1946–。一种苏联的工程发明方法，源于对数十万件专利的分析。包含 40 个发明原理 + 矛盾矩阵 + Ideal Final Result。被 Samsung、Intel、Boeing、P&G 等公司采用。
+
+## 核心原理
+
+大多数发明问题都是技术矛盾：改善 X 会导致 Y 恶化。这种权衡通常是系统拆解方式带来的人为产物，而非根本性约束。解决方法是明确识别出矛盾，然后应用历史上在专利文献中已成功解决类似矛盾的原理。
+
+**Ideal Final Result**：在没有执行系统的前提下实现所需功能（从某种意义上说，系统自身已经被消除了）。将其作为目标。
+
+## 适用场景
+
+- 工程 / 机构 / 设备发明
+- 可测量的参数冲突（质量/强度、成本/可靠性、速度/精度）
+- 你怀疑这种权衡是表面且不成立的
+- 具有非任意结构的群体头脑风暴
+
+## 不适用场景
+
+- 艺术、社会或表达类问题（TRIZ 需要可测量的参数）
+- 你的“矛盾”只是偏好，而不是参数（“现代但经典”不属于 TRIZ）
+- 存在常规的成熟解决方案；TRIZ 专门用于解决发明问题
+
+## 40 个发明原理
+
+1. **Segmentation** — 分割成独立部分，增加可分割性
+2. **Taking out** — 提取造成干扰的部分；只分离出需要的部分
+3. **Local quality** — 让不同部分具备不同的属性
+4. **Asymmetry** — 用不对称替代对称
+5. **Merging** — 将相同/相似的对象组合在一起；并行化操作
+6. **Universality** — 使一个部分执行多种功能
+7. **Nested doll** — 将一个对象放置在另一个对象内部（套娃）
+8. **Anti-weight** — 通过与升力 / 流体或空气动力结合来补偿重量
+9. **Preliminary anti-action** — 预先施加反向应力
+10. **Preliminary action** — 提前执行所需的操作
+11. **Beforehand cushioning** — 事先准备应急手段
+12. **Equipotentiality** — 改变条件，使对象无需升高或降低
+13. **The other way round** — 颠倒作用；使可动部分固定，固定部分可动
+14. **Spheroidality / curvature** — 用曲线替代直线；用球面替代平面
+15. **Dynamics** — 使刚体可动；让各部分能够改变构型
+16. **Partial or excessive actions** — 如果 100% 实现很困难，则采取稍微少一点或稍微多一点的做法
+17. **Another dimension** — 从 1D 转换到 2D 再到 3D；倾斜；利用另一面
+18. **Mechanical vibration** — 振荡，超声波
+19. **Periodic action** — 用周期性代替连续性；改变频率；引入暂停
+20. **Continuity of useful action** — 消除空转
+21. **Skipping** — 快速越过危险阶段
+22. **Blessing in disguise** — 利用有害因素获得正面效果
+23. **Feedback** — 引入或修改反馈
+24. **Intermediary** — 使用中介物或中介过程
+25. **Self-service** — 使对象自我服务；利用废弃资源
+26. **Copying** — 用廉价的复制品代替易碎/昂贵的原作
+27. **Cheap short-living** — 用一次性的物品代替耐用物品
+28. **Mechanics substitution** — 用感官（光学、声学、电磁）替代机械原理
+29. **Pneumatics and hydraulics** — 用气体/液体代替固体；充气式
+30. **Flexible shells and thin films** — 替代 3D 结构
+31. **Porous materials** — 使其多孔；利用孔隙引入有用物质
+32. **Color changes** — 改变颜色或透明度
+33. **Homogeneity** — 相互作用的对象采用相同材料
+34. **Discarding and recovering** — 部分在使用后消失；恢复消耗品
+35. **Parameter changes** — 改变物理状态、浓度、密度、柔韧性或温度
+36. **Phase transitions** — 利用相变现象
+37. **Thermal expansion** — 利用不同的热膨胀系数
+38. **Strong oxidants** — 富氧，臭氧氧化
+39. **Inert atmosphere** — 惰性环境或真空
+40. **Composite materials** — 从单一材料转向复合材料
+
+## 步骤
+
+1. **陈述矛盾**，格式如下：“我希望改善 X，但 X 的改善会导致 Y 恶化。”如果你无法清晰陈述，说明你面临的还不是 TRIZ 问题。
+2. **与 Ideal Final Result 进行对比。**如果系统自身消除，会是什么样子？
+3. **查找候选原理。** triz40.com 上的矛盾矩阵将（X 参数，Y 参数）映射到推荐的原理。或者浏览上述 40 个原理寻找契合点。
+4. **将原理转化为具体机制。**原理是通用的；而机制则是针对你的具体情境的。
+5. **将候选方案与 Ideal Final Result 对比。**选择最接近的方案。
+
+## 演示案例
+
+**问题**：极短的冲煮时间（60 秒内）与充分萃取（通常为 4 分钟）之间的矛盾。
+**矛盾**：速度与萃取的完整性。
+**候选原理**：1 (Segmentation)、17 (Another dimension)、19 (Periodic action)、35 (Parameter changes)。
+**原理转化**：
+- Segmentation：预先萃取浓缩液；按需稀释。（如 Nespresso。）
+- Another dimension：在压力下进行萃取（如 espresso）。
+- Periodic action：带暂停的脉冲式萃取（如某些 pour-over）。
+- Parameter changes：在不同温度/压力下冲煮（冷萃 = 低温长时间；espresso = 高压短时间）。
+
+**IFR 对比**：最接近“零冲煮时间”的方案是预先萃取的浓缩液 (Segmentation)。通过*在时间上将萃取与交付分离*来解决矛盾。
+
+## 反模式提示
+
+- 不要把 40 个原理当成生成式的检查清单——那是 SCAMPER 的作用。TRIZ 的核心价值在于矛盾视角 + 基于专利推导的先验知识。
+- 务必将原理转化为具体机制，不要停留在原理的名称上。
+- 在不适用的领域（艺术、社会问题、偏好矛盾）不要套用 TRIZ。
+- 不要生造 Altshuller 风格的原理。
+
+工具：triz40.com（交互式矩阵）。来源：Altshuller，*And Suddenly the Inventor Appeared* (1994)。

package/extensions/skills/optional/creative/creative-ideation/references/methods/volume-generation.md

@@ -0,0 +1,74 @@
+# 量产创意
+
+快速产生大量想法的三种传统方法：
+- **Crazy 8s** — Google Ventures Sprint 方法。整理收录于 *Sprint* (Knapp et al., 2016)。
+- **Brainwriting 6-3-5** — Bernd Rohrbach，1968年。源自德国设计方法论文献。
+- **James Webb Young** — *A Technique for Producing Ideas* (1940)。这本仅 60 页的书是广告文案人员的经典手册。
+
+## 适用场景
+
+- 有时间压力且旨在产出创意
+- 团队构想（在头脑书写法通常优于口头头脑风暴）
+- 先重数量后重质量的阶段
+- 你需要先产出大量想法，才能从中筛选出少数好点子
+
+## 不适用场景
+
+- 还没有收集到素材（Young 的第 1 阶段：先收集素材）
+- 正确答案很罕见，且你只有看到时才能确定（盲目追求数量反而可能会与之失之交臂）
+- 独立工作且没有时间压力（应改用深思熟虑的方法）
+
+## Crazy 8s
+
+1. 将一张纸折成 8 个格子（或使用印好的网格）。
+2. 设定 **8 分钟** 的倒计时。
+3. 在每个格子中画出一个点子——总共画 8 个点子，每个耗时 1 分钟。
+4. 画图而不是写字。视觉化的形式能迫使你将思考具体化。
+5. 倒计时结束后：挑选出 1–3 个最有力度的格子。
+6. 团队分享。
+
+前 4–5 个格子的内容通常是凑数的；最后 3–4 个才会出现令人惊艳的想法（因为那些轻松能想到的点子已经耗尽了）。
+
+## Brainwriting 6-3-5
+
+在学术创造力研究中，Brainwriting 稳定地优于口头头脑风暴 (Diehl & Stroebe, 1987 及大量重复实验)。口头头脑风暴存在记录在案的“产出阻碍”、“评价顾虑”和“社会懈怠”问题。而 Brainwriting 消除了这三种负面影响。
+
+1. **6 名参与者**，每人手持一张纸。
+2. 每人在 **5 分钟** 内在纸的顶部第一行写下 **3 个想法**。
+3. 传阅纸张。此时每位参与者都能看到上一个人写的 3 个想法；接着写出 3 个 *新* 的想法——可以是在此基础上构建，也可以是全新的点子。
+4. 重复此过程，直到 6 个人都看全所有的纸张。
+5. 结果：30 分钟内产出 6 × 6 × 3 = 108 个想法。
+
+## James Webb Young — 5 个阶段
+
+Young 坦诚地揭示了创意形成的 *时间* 结构。大多数方法想当然地认为想法可以招之即来；而 Young 的观点是通常并非如此，真正起作用的工作都在早期阶段（铺垫期）。
+
+1. **收集素材。** 包括特定领域 *和* 广泛领域的素材。大多数创意产出者都失败在这一步。*“对产品再多了解一个点子，再多收集一点事实材料——很多时候这些微小的积累决定了最终的成败。”*
+2. **脑海消化。** 在脑海中反复咀嚼这些素材。尝试建立初步的、局部的联系。不要急于求成想出最终方案。
+3. **暂时搁置。** 停止思考工作。去睡觉、散步或看场电影。让潜意识去接管。
+4. **灵感降临。** 通常发生在洗澡或散步时。*“它往往会在你最意想不到的时候突然出现。”*
+5. **塑造与完善。** 刚涌现的灵感往往是半成品。必须让其接受现实的检验与打磨。
+
+“暂时搁置”阶段是不可妥协的。如果将其压缩，试图从第 1 步直接跳到第 2 步再到第 4 步，往往只能产出残缺的想法。
+
+## 各种方法的选择策略
+
+| 可用时间 | 团队规模 | 推荐方法 |
+| --- | --- | --- |
+| 8 分钟 | 独立 | Crazy 8s |
+| 8 分钟 | 团队 | Crazy 8s + 分享 |
+| 30 分钟 | 独立 | Crazy 8s + 22 分钟的细化完善 |
+| 30 分钟 | 4–8 人团队 | Brainwriting 6-3-5 |
+| 1 小时 | 团队 | Brainwriting + 30 分钟 Affinity Diagram 分析 |
+| 1 天 | 独立 | Young 的第 1–3 阶段 |
+| 1 周 | 独立或小团队 | 完整的 Young 5 个阶段 |
+
+## 防凑数指南
+
+- **同质化的数量不叫量产。** 8 个结构完全相同的格子，本质只是一个点子画了 8 遍。应通过对不同的格子应用不同的生成方法来强制自己发散思维。
+- 不要为了凑整数而硬挤。如果 8 个格子里只有 5 个有实质内容，就只展示这 5 个。
+- 只向用户展示最核心的 1–3 个，而不是全部 8 个 / 108 个。
+- 不要把量产和深度混为一谈。量产是广度优先的；深度需要后续通过深化方法来达成。
+- 尊重并遵守 Young 的“暂时搁置”阶段。试图在一次工作环节中走完“收集 → 产出”的全流程往往行不通。
+
+参考来源：Young, *A Technique for Producing Ideas* (Advertising Publications, 1940)；Rohrbach, "Methode 635" (*Absatzwirtschaft* 12, 1968)；Knapp et al., *Sprint* (Simon & Schuster, 2016)。

package/extensions/skills/optional/creative/hyperframes/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: hyperframes
+description: 使用 HyperFrames 创建基于 HTML 的视频合成、动画标题卡、社交叠加层、带有字幕的谈话头像视频、音频反应可视化以及 shader 过渡效果。HTML 是视频的唯一事实来源。当用户希望从 HTML 合成中渲染出 MP4/WebM，希望在媒体上为文本/Logo/图表制作动画，需要与音频同步的字幕，需要 TTS 旁白，或者希望将网站转换为视频时使用。
+version: 1.0.0
+author: heygen-com
+license: Apache-2.0
+platforms: [linux, macos, windows]
+prerequisites:
+  commands: [node, ffmpeg, npx]
+metadata:
+  hermes:
+    tags: [creative, video, animation, html, gsap, motion-graphics]
+    related_skills: [manim-video, meme-generation]
+    category: creative
+    requires_toolsets: [terminal]
+---
+
+# HyperFrames
+
+HTML 是视频的唯一事实来源。一个合成（composition）就是一个带有用于控制时间的 `data-*` 属性、用于动画的 GSAP 时间轴，以及用于外观的 CSS 的 HTML 文件。HyperFrames 引擎逐帧捕获页面，并使用 FFmpeg 编码为 MP4/WebM。
+
+**`manim-video` 的互补：** 如果是数学/几何讲解类视频（方程式、3B1B 风格），请使用 `manim-video`。如果是动态图形、带有字幕的谈话头像、产品演示、社交叠加层、shader 过渡，以及任何由真实视频/音频媒体驱动的内容，请使用 `hyperframes`。
+
+## 何时使用
+
+- 用户要求从文本、脚本或网站渲染视频
+- 动画标题卡、下半角字幕条（lower thirds）或排版片头
+- 带字幕的旁白视频（TTS + 与波形同步的字幕）
+- 音频反应可视化（节拍同步、频谱条、脉冲发光）
+- 场景间的过渡（交叉淡入淡出、擦除、shader 扭曲、白光闪烁穿过）
+- 社交叠加层（Instagram/TikTok/YouTube 风格）
+- 网站转视频工作流（捕获 URL，制作宣传片）
+- 任何必须确定性渲染为视频文件的 HTML/CSS/JS 动画
+
+**不要**将此技能用于：
+- 纯数学/方程式动画（→ `manim-video`）
+- 图像生成或表情包（→ `meme-generation`，图像模型）
+- 实时视频会议或流媒体直播
+
+## 快速 参考
+
+```bash
+npx hyperframes init my-video               # 脚手架初始化项目
+cd my-video
+npx hyperframes lint                        # 在预览/渲染前进行验证
+npx hyperframes preview                     # 实时重载浏览器预览 (端口 3002)
+npx hyperframes render --output final.mp4   # 渲染为 MP4
+npx hyperframes doctor                      # 诊断环境问题
+```
+
+渲染参数：`--quality draft|standard|high` · `--fps 24|30|60` · `--format mp4|webm` · `--docker` (可复现) · `--strict`。
+
+完整的 CLI 参考：[references/cli.md](references/cli.md)。
+
+## 配置 (一次性)
+
+```bash
+bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
+```
+
+该脚本会：
+1. 验证是否安装了 Node.js >= 22 和 FFmpeg（如果未安装，会打印修复说明）。
+2. 全局安装 `hyperframes` CLI（`npm install -g hyperframes@>=0.4.2`）。
+3. 通过 Puppeteer 预缓存 `chrome-headless-shell` —— 这是通过 Chrome 的 `HeadlessExperimental.beginFrame` 捕获路径获得最佳渲染质量所**必需的**。
+4. 运行 `npx hyperframes doctor` 并报告结果。
+
+如果设置失败，请参阅 [references/troubleshooting.md](references/troubleshooting.md)。
+
+## 操作流程
+
+### 1. 在编写 HTML 前 计划
+
+在接触代码之前，请先在宏观层面上明确以下几点：
+- **什么** —— 叙事弧线、关键时刻、情感节奏
+- **结构** —— 合成、轨道（视频/音频/叠加层）、持续时间
+- **视觉特征** —— 颜色、字体、运动特质（爆发性 / 电影感 / 流畅 / 科技感）
+- **关键帧** —— 对于每个场景，即最多元素同时可见的时刻。这是你首先要构建的静态布局。
+
+**视觉特征检查点 (强制要求)。** 在编写任何合成 HTML 之前，必须定义视觉特征。**不要**使用默认或通用的颜色编写合成（使用了 `#333`、`#3b82f6`、`Roboto` 就暴露了跳过了这一步）。按以下顺序检查：
+
+1. **项目根目录有 `DESIGN.md` 吗？** → 使用其指定的精确颜色、字体、运动规则以及“禁止事项”约束。
+2. **用户指定了风格**（例如“瑞士脉冲”、“暗黑科技风”、“奢侈品牌”）？ → 生成一个包含 `## Style Prompt`、`## Colors`（3-5 个十六进制代码及其用途）、`## Typography`（1-2 个字体族）、`## What NOT to Do`（3-5 个反模式）的简易 `DESIGN.md`。
+3. **以上都没有？** → 在编写任何 HTML 之前，先询问 3 个问题：
+   - 氛围？（爆发性 / 电影感 / 流畅 / 科技感 / 混乱 / 温暖）
+   - 亮色还是暗色画布？
+   - 有指定的品牌颜色、字体或视觉参考吗？
+
+   然后根据回答生成 `DESIGN.md`。每个合成的调色板和排版都必须能追溯回 `DESIGN.md` 或用户的明确指示。
+
+### 2. 脚手架初始化
+
+```bash
+npx hyperframes init my-video --non-interactive
+```
+
+模板包括：`blank`、`warm-grain`、`play-mode`、`swiss-grid`、`vignelli`、`decision-tree`、`kinetic-type`、`product-promo`、`nyt-graph`。传入 `--example <name>` 来选择一个，传入 `--video clip.mp4` 或 `--audio track.mp3` 以搭配媒体进行种子初始化。
+
+### 3. 先布局后动画
+
+首先为**关键帧**编写静态 HTML+CSS —— 暂时不要使用 GSAP。`.scene-content` 容器必须填满场景（`width:100%; height:100%; padding:Npx`），并使用 `display:flex` + `gap`。使用 padding 将内容向内推 —— 永远不要在内容容器上使用 `position: absolute; top: Npx`（当内容高于剩余空间时会溢出）。
+
+只有当关键帧看起来没问题后，才添加 `gsap.from()` 入场（动画**至** CSS 位置）和 `gsap.to()` 出场（从该位置开始动画）。
+
+有关完整的数据属性模式和合成规则，请参阅 [references/composition.md](references/composition.md)。
+
+### 4. 使用 GSAP 制作动画
+
+每个合成都必须：
+- 注册其时间轴：`window.__timelines["<composition-id>"] = tl`
+- 初始为暂停状态：`gsap.timeline({ paused: true })` —— 由播放器控制回放
+- 使用有限的 `repeat` 值（禁止 `repeat: -1` —— 会破坏捕获引擎）。计算方式：`repeat: Math.ceil(duration / cycleDuration) - 1`。
+- 保持确定性 —— 禁止 `Math.random()`、`Date.now()` 或基于墙上时钟的逻辑。如果需要伪随机性，请使用带有种子的 PRNG。
+- 同步构建 —— 在构建时间轴时禁止使用 `async`/`await`、`setTimeout` 或 Promises。
+
+有关核心 GSAP API（tween、缓动、stagger、时间轴），请参阅 [references/gsap.md](references/gsap.md)。
+
+### 5. 场景间的过渡
+
+多场景合成需要过渡。规则：
+1. **场景之间必须始终使用过渡** —— 不要跳剪。
+2. **每个场景元素上必须始终使用入场动画**（`gsap.from(...)`）。
+3. **永远不要使用出场动画**，最后一个场景除外 —— 过渡本身就是出场。
+4. 最后一个场景可以淡出。
+
+使用 `npx hyperframes add <transition-name>` 来安装 shader 过渡效果（`flash-through-white`、`liquid-wipe` 等）。完整列表：`npx hyperframes add --list`。
+
+### 6. 音频、字幕、TTS、音频反应、高亮
+
+- **音频：** 始终是一个单独的 `<audio>` 元素（视频是 `muted playsinline`）。
+- **TTS：** `npx hyperframes tts "Script text" --voice af_nova --output narration.wav`。使用 `--list` 列出语音。语音 ID 的首字母编码了语言（`a`/`b`=英语，`e`=西班牙语，`f`=法语，`j`=日语，`z`=普通话等） —— CLI 会自动推断音素分析器的区域设置；只有在需要覆盖时才传入 `--lang`。非英语音素分析需要系统全局安装 `espeak-ng`。
+- **字幕：** `npx hyperframes transcribe narration.wav` → 词级转录文本。根据转录文本的基调选择风格（hype 激昂 / corporate 商务 / tutorial 教程 / storytelling 叙事 / social 社交 —— 参见 `references/features.md` 中的表格）。**语言规则：** 除非确认音频是英语，否则永远不要使用 `.en` whisper 模型 —— 对于非英语音频，`.en` 会进行翻译而不是转录。每个字幕组必须在其出场 tween 之后强制执行 `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` 销毁 —— 否则字幕组会在随后的组中保持可见并造成重叠泄漏。
+- **音频反应可视化：** 预先提取音频频段（低频 / 中频 / 高频），并在时间轴内使用 `for` 循环结合 `tl.call(draw, [], f / fps)` 逐帧采样 —— 单个长 tween 无法对音频做出反应。将低频映射到 `scale`（脉冲），高频映射到 `textShadow`/`boxShadow`（发光），整体振幅映射到 `opacity`/`y`/`backgroundColor`。避免使用均衡器条等陈词滥调 —— 让内容引导视觉，让音频驱动其行为。
+- **标记风格高亮：** 用于强调文本的荧光笔、圆圈、爆发、涂鸦、勾勒效果，它们是确定性的 CSS+GSAP —— 参见 `references/features.md#marker-highlighting`。完全可定位查找，无动画 SVG 滤镜。
+- **场景过渡：** 每个多场景合成必须使用过渡（禁止跳剪）。从 CSS 原语（推拉、模糊交叉淡入淡出、穿透缩放、交错块）中挑选，或通过 `npx hyperframes add` 使用 shader 过渡（`flash-through-white`、`liquid-wipe`、`cross-warp-morph`、`chromatic-split` 等）。氛围与能量参考表位于 `references/features.md#transitions`。不要在同一个合成中混用 CSS 和 shader 过渡。
+
+### 7. Lint、验证、检查、预览、渲染
+
+```bash
+npx hyperframes lint              # 捕获缺失的 data-composition-id、重叠的轨道、未注册的时间轴
+npx hyperframes validate          # 在 5 个时间点进行 WCAG 对比度审计
+npx hyperframes inspect           # 视觉布局审计 —— 溢出、画框外元素、被遮挡的文本
+npx hyperframes preview           # 实时浏览器预览
+npx hyperframes render --quality draft --output draft.mp4    # 快速迭代
+npx hyperframes render --quality high --output final.mp4     # 最终交付
+```
+
+`hyperframes validate` 会对每个文本元素背后的背景像素进行采样，并在对比度低于 4.5:1（大文本为 3:1）时发出警告。`hyperframes inspect` 是布局层面的配套工具 —— 在多个时间点运行页面，并标记静态 lint 无法察觉的问题（例如：仅在 4.5 秒时换行超出安全区域的字幕、当其标题为最长变体时导致溢出的卡片、最终位于过渡 shader 背后的元素）。对于包含对话气泡、卡片、字幕或排版紧凑的合成，尤其要运行 `inspect`。
+
+### 8. 网站转视频 (如果用户提供 URL)
+
+使用 [references/website-to-video.md](references/website-to-video.md) 中的 7 步从捕获到视频的工作流：捕获 → DESIGN.md → SCRIPT.md → 故事板 → 合成 → 渲染 → 交付。
+
+## 常见陷阱
+
+- **找不到 `HeadlessExperimental.beginFrame'`** —— Chromium 147+ 移除了此协议。确保你使用的是 `hyperframes@>=0.4.2`（会自动检测并回退到截图模式）。逃生舱：`export PRODUCER_FORCE_SCREENSHOT=true`。请参阅 [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294) 和 [references/troubleshooting.md](references/troubleshooting.md)。
+- **系统 Chrome (而非 `chrome-headless-shell`)** —— 渲染会挂起 120 秒然后超时。运行 `npx puppeteer browsers install chrome-headless-shell`（setup.sh 会执行此操作）。`hyperframes doctor` 会报告将使用哪个二进制文件。
+- **任何地方出现 `repeat: -1`** —— 会破坏捕获引擎。始终计算有限的重复次数。
+- **对稍后入场的剪辑元素使用 `gsap.set()`** —— 该元素在页面加载时不存在。请在时间轴内部，于该剪辑的 `data-start` 时刻或之后使用 `tl.set(selector, vars, timePosition)`。
+- **内容文本内包含 `<br>`** —— 强制换行无法获知渲染后的字体宽度，因此自然换行 + `<br>` 会导致双重换行。使用 `max-width` 让文本自然换行。例外情况：刻意让每个单词独占一行的简短展示标题。
+- **对 `visibility` 或 `display` 进行动画处理** —— GSAP 无法对这些属性进行 tween。请使用 `autoAlpha`（同时处理 visibility 和 opacity）。
+- **调用 `video.play()` 或 `audio.play()`** —— 播放由框架控制。永远不要自行调用这些方法。
+- **异步构建时间轴** —— 捕获引擎在页面加载后同步读取 `window.__timelines`。永远不要将时间轴构建包装在 `async`、`setTimeout` 或 Promise 中。
+- **包裹在 `<template>` 中的独立 `index.html`** —— 会对浏览器隐藏所有内容。只有通过 `data-composition-src` 加载的**子合成**才使用 `<template>`。
+- **使用视频轨道来播放音频** —— 始终使用静音的 `<video>` + 独立的 `<audio>`。
+
+## 验证
+
+在渲染前后：
+
+1. **Lint + validate + inspect 通过：** `npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect`（lint 捕获结构性问题，validate 捕获对比度问题，inspect 捕获视觉布局/溢出问题 —— 如果出现警告，请参阅 troubleshooting.md）。
+2. **动画编排** —— 对于新的合成或重大的动画更改，运行动画映射。`npx hyperframes init` 会将技能脚本复制到项目中，因此路径是项目局部的：
+   ```bash
+   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+     --out <composition-dir>/.hyperframes/anim-map
+   ```
+   输出一个包含各 tween 摘要、ASCII 甘特图时间轴、stagger 检测、死区（>1s 无动画）、元素生命周期以及标记（`offscreen`、`collision`、`invisible`、`paced-fast` <0.2s、`paced-slow` >2s）的 `animation-map.json`。扫描摘要和标记 —— 修复或说明每一项的理由。微小编辑可跳过。
+3. **文件存在且非空：** `ls -lh final.mp4`。
+4. **持续时间匹配 `data-duration`：** `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4`。
+5. **视觉检查：** 提取合成中段的一帧：`ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png`。
+6. **如果预期有音频，则检查音频是否存在：** `ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1`。
+
+如果 `hyperframes render` 失败，请运行 `npx hyperframes doctor` 并在反馈问题时附上其输出。
+
+## 参考资料
+
+- [composition.md](references/composition.md) — 数据属性、时间轴契约、不可妥协的规则、排版/素材规则
+- [cli.md](references/cli.md) — 所有 CLI 命令（init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark）
+- [gsap.md](references/gsap.md) — HyperFrames 的核心 GSAP API（tween、缓动、stagger、时间轴、matchMedia）
+- [features.md](references/features.md) — 字幕、TTS、音频反应、标记高亮、过渡（按需加载）
+- [website-to-video.md](references/website-to-video.md) — 7 步从捕获到视频的工作流
+- [troubleshooting.md](references/troubleshooting.md) — OpenClaw 修复、环境变量、常见渲染错误

package/extensions/skills/optional/creative/hyperframes/references/cli.md

@@ -0,0 +1,185 @@
+# HyperFrames CLI
+
+所有操作均通过 `npx hyperframes`（或在运行 `npm install -g hyperframes` 后使用全局安装的 `hyperframes`）执行。要求 Node.js >= 22 和 FFmpeg。
+
+## 工作流
+
+1. **脚手架** — `npx hyperframes init my-video`（或者如果从网站开始，则使用 `npx hyperframes capture <url>`）
+2. **编写** — 创作 HTML composition（参见 `composition.md`）
+3. **Lint** — `npx hyperframes lint`
+4. **验证** — `npx hyperframes validate`（WCAG 对比度审计）
+5. **检查** — `npx hyperframes inspect`（视觉布局审计）
+6. **预览** — `npx hyperframes preview`
+7. **渲染** — `npx hyperframes render`
+
+在预览/渲染之前务必执行 lint —— 它能捕获缺失的 `data-composition-id`、重叠的轨道以及未注册的 timeline。
+
+## init — 搭建项目
+
+```bash
+npx hyperframes init my-video                        # 交互式向导
+npx hyperframes init my-video --example warm-grain   # 选择一个示例模板
+npx hyperframes init my-video --video clip.mp4       # 使用视频文件作为种子
+npx hyperframes init my-video --audio track.mp3      # 使用音频文件作为种子
+npx hyperframes init my-video --non-interactive      # 跳过提示（用于 CI / agent）
+```
+
+模板：`blank`、`warm-grain`、`play-mode`、`swiss-grid`、`vignelli`、`decision-tree`、`kinetic-type`、`product-promo`、`nyt-graph`。
+
+`init` 会创建正确的文件结构、复制媒体文件、使用 Whisper 转录音频，并安装编写技能。请使用此命令，而不是手动创建文件。
+
+## capture — 网站 → 可编辑组件
+
+```bash
+npx hyperframes capture https://example.com                  # → captures/example.com/
+npx hyperframes capture https://stripe.com -o stripe-video   # 自定义输出目录
+npx hyperframes capture https://example.com --json           # 机器可读的输出
+npx hyperframes capture https://example.com --skip-assets    # 跳过图像/SVG
+```
+
+默认将网站捕获到 `captures/<hostname>/capture/` 目录下，生成 `capture/screenshots/`、`capture/assets/`、`capture/extracted/`（tokens.json、visible-text.txt、fonts.json）以及一个自包含的快照。
+
+所有后续步骤（DESIGN.md、SCRIPT.md、STORYBOARD、composition）都会从 `capture/` 子文件夹读取数据 —— 参见 `website-to-video.md`。
+
+## lint
+
+```bash
+npx hyperframes lint                # 当前目录
+npx hyperframes lint ./my-project   # 特定项目
+npx hyperframes lint --verbose      # 包含 info 级别的发现
+npx hyperframes lint --json         # 机器可读的输出
+```
+
+对 `index.html` 和 `compositions/` 中的所有文件执行 lint。报告错误（必须修复）、警告（建议修复）和信息（仅在提供了 `--verbose` 时显示）。
+
+## validate
+
+```bash
+npx hyperframes validate                 # 在 5 个时间点进行 WCAG 对比度审计
+npx hyperframes validate --no-contrast   # 在迭代时跳过
+```
+
+跳转至 5 个时间点，对页面进行截图，在每个文本元素背后的背景像素上取样，并在对比度低于 4.5:1（普通文本）或 3:1（大文本 —— 24px 以上，或 19px 以上粗体）时发出警告。在最终渲染之前运行。
+
+## inspect
+
+```bash
+npx hyperframes inspect                 # 在 5 个时间点进行视觉布局审计
+npx hyperframes inspect ./my-project    # 特定项目
+npx hyperframes inspect --json          # agent 可读的发现结果
+npx hyperframes inspect --samples 15    # 更密集的时间线扫描
+npx hyperframes inspect --at 1.5,4,7.25 # 明确的 hero-frame 时间戳
+```
+
+请在执行 `lint` 和 `validate` 之后使用此命令，特别是对于包含对话气泡、卡片、字幕或紧凑排版的 composition。它会报告溢出、超出边界的元素、被遮挡的文本、对比度警告以及各时间点的布局摘要 —— 它可以捕获纯时间线 lint 无法察觉的问题（例如，仅在特定时间点换行并超出安全区域的字幕）。
+
+`npx hyperframes layout` 是用于相同视觉检查过程的兼容性别名。
+
+## preview
+
+```bash
+npx hyperframes preview                # 提供当前目录服务（端口 3002）
+npx hyperframes preview --port 4567    # 自定义端口
+```
+
+在文件更改时执行热重载。自动在您的浏览器中打开 Studio。
+
+## render
+
+```bash
+npx hyperframes render                              # 标准 MP4
+npx hyperframes render --output final.mp4           # 指定名称的输出
+npx hyperframes render --quality draft              # 快速迭代
+npx hyperframes render --fps 60 --quality high      # 最终交付
+npx hyperframes render --format webm                # 透明 WebM
+npx hyperframes render --docker                     # 字节完全一致的可重现渲染
+```
+
+| 标志 | 选项 | 默认值 | 说明 |
+| -------------- | ----------------------- | ------------------------------ | --------------------------- |
+| `--output` | 路径 | `renders/<name>_<timestamp>.mp4` | 输出路径 |
+| `--fps` | 24, 30, 60 | 30 | 60fps 会使渲染时间翻倍 |
+| `--quality` | `draft`, `standard`, `high` | 标准 | draft 用于迭代 |
+| `--format` | `mp4`, `webm` | mp4 | WebM 支持透明度 |
+| `--workers` | 1–8 或 `auto` | auto | 每个 worker 都会启动一个 Chrome |
+| `--docker` | flag | off | 可重现的输出 |
+| `--gpu` | flag | off | GPU 加速编码 |
+| `--strict` | flag | off | 遇到 lint 错误时失败 |
+| `--strict-all` | flag | off | 遇到错误和警告时均失败 |
+
+**质量指南：** 迭代时使用 `draft`，审查时使用 `standard`，最终交付时使用 `high`。
+
+## transcribe
+
+```bash
+npx hyperframes transcribe audio.mp3
+npx hyperframes transcribe video.mp4 --model medium.en --language en
+npx hyperframes transcribe subtitles.srt     # 导入现有文件
+npx hyperframes transcribe subtitles.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+生成适合字幕组件的词级时间轴。首次运行将下载 Whisper 模型（之后会被缓存）。
+
+## tts
+
+```bash
+npx hyperframes tts "Text here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+npx hyperframes tts --list                    # 显示所有语音
+```
+
+使用 Kokoro（本地运行，无需 API 密钥）。Voice ID 的首字母代表语言：`a` 美式英语、`b` 英式英语、`e` 西班牙语、`f` 法语、`h` 印地语、`i` 意大利语、`j` 日语、`p` 巴西葡萄牙语、`z` 普通话。CLI 会根据该前缀自动推断 phonemizer 区域设置 —— 仅在需要覆盖时传入 `--lang`（例如特殊风格的口音）。有效的 `--lang` 代码包括：`en-us`、`en-gb`、`es`、`fr-fr`、`hi`、`it`、`pt-br`、`ja`、`zh`。非英语音素化处理需要在系统范围内安装 `espeak-ng`（`apt-get install espeak-ng` / `brew install espeak-ng`）。
+
+## doctor
+
+```bash
+npx hyperframes doctor
+```
+
+检查环境：
+- Node.js >= 22
+- FFmpeg 存在于 PATH 中
+- 可用 RAM（渲染非常消耗内存 —— 最少需要 4 GB）
+- Chrome 二进制文件解析（相比于系统 Chrome，更推荐使用 `chrome-headless-shell`）
+- 当前的 `hyperframes` 版本
+
+当渲染失败时，请**首先**运行此命令。有关输出结果的解释，请参见 `troubleshooting.md`。
+
+## browser
+
+```bash
+npx hyperframes browser --install      # 安装内置的 chrome-headless-shell
+npx hyperframes browser --path         # 打印解析出的浏览器二进制文件路径
+npx hyperframes browser --clean        # 清除内置浏览器缓存
+```
+
+## info
+
+```bash
+npx hyperframes info
+```
+
+打印版本、Node 版本、FFmpeg 版本、操作系统以及解析出的浏览器路径 —— 在提交 bug 报告时非常有用。
+
+## upgrade
+
+```bash
+npx hyperframes upgrade -y
+```
+
+检查并安装更新。如果您遇到 `HeadlessExperimental.beginFrame` 错误，请运行此命令 —— 自动检测修复程序已在 `hyperframes@0.4.2` 中提供（提交号 4c72ba4，2026 年 3 月）。
+
+## 其他
+
+```bash
+npx hyperframes compositions    # 列出项目中的 composition
+npx hyperframes docs            # 在浏览器中打开文档
+npx hyperframes benchmark .     # 对渲染性能进行基准测试
+npx hyperframes add <block>     # 从目录安装 block/component
+npx hyperframes add --list      # 浏览目录
+```
+
+热门的目录 block：`flash-through-white`（shader 过渡）、`instagram-follow`（社交叠加层）、`data-chart`（动态图表）、`lower-third`（人物访谈叠加层）。请访问 [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog)。