Merge branch 'topo-ai:main' into main

README.md

@@ -18,7 +18,8 @@
 | IT 基础设施长图讲解视频 | 基于长图素材生成 HyperFrames 讲解视频、口播、字幕和 timeline | `skills/it-infra-evolution-video/SKILL.md` |
 | 产品介绍视频 | 官网信息提炼、叙事结构、成片节奏 | `skills/product-intro-video/SKILL.md` |
 | 视频音效工作流 | 音效搜索、下载与合成、时间线接入 | `skills/sound-fx-for-video/SKILL.md` |
-| 简笔画动画视频 | 线稿风动画、动作叙事、抽检闭环 | `skills/sketch-animation-video/SKILL.md` |
+| 简笔画动画视频 | 线稿风 + 短画面字；**主动网络搜参考图临摹**；逼真非抽象；GSAP 主时间线 + 可选 Anime.js；抽检闭环 | `skills/sketch-animation-video/SKILL.md` |
+| Anime.js（HyperFrames） | seek 驱动适配、`window.__hfAnime` 注册、与 GSAP 分工 | `skills/animejs/SKILL.md` |
 
 ## Examples
 
@@ -40,6 +41,9 @@
 ### sketch-animation-video
 ![sketch-animation-video preview](docs/assets/preview-sketch-animation-video.gif)
 
+### animejs
+暂无预览（配套 `sketch-animation-video` 与 HyperFrames 动效接入）
+
 ## 使用方式
 
 1. 进入对应 Skill 目录并阅读 `SKILL.md`

skills/animejs/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: animejs
+description: Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.
+---
+
+# Anime.js for HyperFrames
+
+HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.
+
+## Contract
+
+- Create animations or timelines synchronously during composition initialization.
+- Set `autoplay: false` so Anime.js does not advance on its own clock.
+- Register every returned animation or timeline on `window.__hfAnime`.
+- Use finite durations and loop counts.
+- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.
+
+The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time in milliseconds.
+
+## Basic Pattern
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/animejs@4.0.2/lib/anime.iife.min.js"></script>
+<script>
+  const anim = anime({
+    targets: ".mark",
+    translateX: 280,
+    rotate: "1turn",
+    opacity: [0, 1],
+    duration: 1200,
+    easing: "easeOutExpo",
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Timeline Pattern
+
+```html
+<script>
+  const tl = anime.timeline({
+    autoplay: false,
+    easing: "easeOutCubic",
+  });
+
+  tl.add({
+    targets: ".title",
+    translateY: [40, 0],
+    opacity: [0, 1],
+    duration: 650,
+  }).add(
+    {
+      targets: ".accent",
+      scaleX: [0, 1],
+      duration: 450,
+    },
+    250,
+  );
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(tl);
+</script>
+```
+
+## Module Builds
+
+If you use an ES module build, the adapter does not care how the instance was created. It only needs the returned object to expose `seek()`, `pause()`, and preferably `play()`:
+
+```html
+<script type="module">
+  import { animate } from "https://cdn.jsdelivr.net/npm/animejs/+esm";
+
+  const anim = animate(".chip", {
+    x: "18rem",
+    duration: 900,
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Good Uses
+
+- Small SVG and DOM flourishes where Anime.js syntax is compact.
+- Imported Anime.js examples that can be made seek-driven.
+- Multiple independent micro-animations pushed into the same registry.
+
+Use GSAP for complex scene sequencing unless the user specifically asks for Anime.js. GSAP is still the primary HyperFrames authoring path.
+
+## Avoid
+
+- Leaving `autoplay` at the Anime.js default.
+- Depending on `anime.running` auto-discovery instead of explicit `window.__hfAnime.push(...)`.
+- Infinite loops. Compute a finite repeat count from the composition duration.
+- Building animations in timers, promises, event handlers, or after async asset loads.
+
+## Validation
+
+After editing a composition that uses Anime.js:
+
+```bash
+npx hyperframes lint
+npx hyperframes validate
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/animejs.ts`.
+- Anime.js documentation for `autoplay`, `pause()`, and `seek()`: https://animejs.com/documentation/

skills/sketch-animation-video/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: sketch-animation-video
-description: 使用 HyperFrames 制作简笔画/手绘线稿动画短视频。适用于简笔画动画、白板风、线稿动效、3-10 秒解释型片段，强调“无字幕可懂”的动作叙事、可复用模板与自检修复闭环。
+description: 使用 HyperFrames 制作简笔画/手绘线稿动画短视频。适用于简笔画动画、白板风、线稿动效、3-10 秒解释型片段；默认**简笔画 + 简短画面字**；具象物体须**主动网络检索参考图并临摹**线稿，以**逼真可辨认为主、拒绝默认抽象**；动效以 GSAP 为主时间线，可选 Anime.js 微动效（须 seek 驱动）；可复用模板与自检修复闭环。
 disable-model-invocation: true
 ---
 
 # 简笔画动画视频 Skill（HyperFrames）
 
 用于生产「简笔画 / 手绘线稿」风格短视频（3-10 秒）。
-核心目标：**信息表达优先**、**动作语义清晰**、**可快速迭代**。
+核心目标：**信息表达优先**、**动作语义清晰**、**具象造型逼真可辨**、**可快速迭代**。
 
 ## 1) 适用场景（触发词）
 
@@ -15,7 +15,7 @@ disable-model-invocation: true
 
 - 简笔画动画、手绘动画、白板风、线稿风
 - 3-5 秒开场、功能解释、概念隐喻动画
-- 希望通过动作直接表达含义（不依赖长文本）
+- 希望通过**动作 + 少量画面字**表达含义（默认不交付「纯动画无字」）
 - 需要 HyperFrames 可预览、可校验、可导出 MP4
 
 ---
@@ -25,13 +25,26 @@ disable-model-invocation: true
 - **HyperFrames**：编排与渲染（`data-*` 时序属性）
 - **HTML + CSS**：布局与视觉（纸张底、网格、线稿样式）
 - **SVG**：人物、图标、符号、道具等简笔画元素
-- **GSAP**：时间线动画（入场/传递/激活/输出/收尾）
+- **GSAP（主）**：场景时间线（入场/传递/激活/输出/收尾）
+- **Anime.js（可选）**：独立微动效、SVG 点缀、从示例迁移的 seek 驱动动画；与 GSAP 分工，不替代主时间线
 - **命令**：`npm run dev`、`npm run check`、`npm run render`
 
 建议版本：
 
 - `hyperframes@0.5.x`
 - `gsap@3.14.x`
+- `animejs@4.0.x`（仅在使用 Anime.js 时引入）
+
+### 动效库选型
+
+| 场景 | 推荐 |
+|---|---|
+| 整段场景编排、多元素错峰、对照叙事 | **GSAP** |
+| 单个 SVG/DOM 点缀、弹性/旋转/描边等短动效 | **Anime.js** |
+| 用户指定 Anime.js 或提供 Anime.js 示例 | **Anime.js**（按 `skills/animejs/SKILL.md` 改造为 seek 驱动） |
+| 同一片段既要编排又要点缀 | GSAP 管主链，Anime.js 管局部；避免同一 `transform` 被两套库同时写 |
+
+Anime.js 接入细则见同仓库 **`skills/animejs/SKILL.md`**（`autoplay: false`、`window.__hfAnime` 注册、有限时长）。
 
 ---
 
@@ -47,8 +60,17 @@ disable-model-invocation: true
 ### 叙事优先级
 
 1. **先表达语义，再追求美观**
-2. **无字幕可懂**：隐藏说明文本后，观众仍能看懂核心含义
+2. **画面字 + 动画，缺一不可（默认）**：至少包含**短标题 + 一句说明**（或等价信息层：标签 / 关键词 / 步骤号）。纯线稿动效**不能**作为唯一信息载体——观众静音扫一眼也要知道「这一段在讲什么」。长口播字幕由剪辑叠加时，画面字仍建议保留「钩子级」短文案。仅当用户**明确要求**「成片不要任何画面字、只靠口播」时，才改为纯隐喻，并须用更直白、可辨认的主体造型补足语义。
-3. **动作隐喻优先**：对照 / 因果 / 冲突 / 结果
+3. **动作承担强化与记忆点**：对照 / 因果 / 冲突 / 结果；动画与文字分工——字说清「是什么」，动效说清「关系/过程」。
+
+### 简笔画造型：逼真可辨为主，禁止默认「抽象符号画」
+
+- **总原则**：以**画得形象、看得懂是什么**为先，**不要**用圆角方块、单弧、火柴棍等**几何抽象**顶替真实物体（除非用户**明确要求**极简图标风）。
+- **参考图来源（执行方主动，不必等用户投喂）**：凡是人物、动物、食物、器械、产品外观、建筑体块等需要**像**的内容，执行方须**自行使用网络检索**（多关键词、多图交叉比对；优先百科/新闻/品牌官网/图库等可追溯来源），看清真实比例与关键结构后，再**临摹**进 SVG（先抓外轮廓与识别特征，再减笔），**禁止无参考凭印象硬编坐标**。
+- **用户已提供照片 / 指定链接时**：以用户素材为**最高优先级**，网络图仅作补充校验。
+- **视角**：用户未指定时，由执行方根据**辨识度、构图、与文案/动线的避让**自行选择正视、侧视、四分之三等；若物体非对称强烈（如锤头、车侧影），优先选**最能看出特征**的角度。
+- **复杂对象**（产品、界面、器械）：允许略多几笔或轻辅助线，但必须仍以「像」为先；宁可少动效也要先把轮廓临摹对。
+- **抽检**：遮住标题后，主体仍应可辨；若像「图标不像实物」，回到参考图改轮廓，而不是改文案糊弄过去。
 
 ### 典型表达范式
 
@@ -97,34 +119,46 @@ disable-model-invocation: true
 - 用 GSAP 的 `xPercent: -50` 替代 CSS 的 `translateX(-50%)`
 - 或使用 `fromTo` 明确保留同一 transform 语义
 
-### C. 文案开关规范
+### C. 画面文案与开关规范
 
-若需要“辅助口播提示文案”，必须做成可控开关，不要硬编码在最终导出里。
+- **默认**：成片包含精简画面字（小标签 + 标题 + 一句说明），与简笔画分区排版（常见：上文下画），时间轴上**宜先出字再出线稿动效**，避免「只有动效不知道讲什么」。
+- 若用户要求剪辑时叠自己的字幕、希望**成片零画面字**：再做成显式开关（如 CSS 类 / 变量）或单独导出「无字版」；无字版须相应加强主体可辨认性（见上文「要像」），并通过用户确认。
 
 ### D. 删除元素后检查
 
-删除节点后同步检查 GSAP 选择器，避免出现空选择器（如 `""`）导致运行时报错。
+删除节点后同步检查 GSAP / Anime.js 的 `targets` 选择器，避免出现空选择器（如 `""`）导致运行时报错。
+
+### E. Anime.js 与 HyperFrames 适配
+
+仅在需要时使用 Anime.js，并遵守以下约定（详见 `skills/animejs/SKILL.md`）：
+
+- 初始化阶段**同步**创建动画，设置 `autoplay: false`
+- 将每个实例 `push` 到 `window.__hfAnime`
+- 使用**有限** `duration` / 循环次数，禁止依赖墙钟或无限循环
+- 与 §B 相同：`transform` 勿在 CSS 与 Anime.js 间互相覆盖；居中位移优先用动画属性或包装层
+- 复杂场景编排仍用 GSAP；不要把整段简笔画叙事全部塞进 Anime.js timeline
 
 ---
 
 ## 7) 交付流程（必须执行）
 
 1. 明确目标：时长、比例、语义重点、是否保留角标
-2. 先做静态 Hero Frame，再接 GSAP 时间线
+2. **具象线稿前置**：凡须画「像」的主体，先完成**网络参考图检索 → 定视角 → 临摹定稿**（见 §3），再进入静态排版；勿先动 GSAP 再在糊轮廓上修修补补。
-3. 执行 `npm run check`
+3. 先做静态 Hero Frame，再接 GSAP 主时间线（局部点缀按需补 Anime.js，并注册 `window.__hfAnime`）
-4. 导出 `npm run render`
+4. 执行 `npm run check`
-5. 抽检截图并修复（见第 9 节）
+5. 导出 `npm run render`
-6. 向用户回报：改动点 + 最新成片路径
+6. 抽检截图并修复（见第 9 节）
+7. 向用户回报：改动点 + 最新成片路径（必要时附一句所选视角与参考来源类型，便于复核）
 
 ---
 
 ## 8) 质量标准（验收）
 
 - 画面在 3-10 秒（或目标时长）内表达完整
+- **默认含短画面字**：标题 + 一句说明（或与用户约定的等价信息层）；无字版须为显式需求并加强造型可读性
 - 主体不遮挡、不过界、不过度拥挤
-- 线稿风格一致（线宽、轮廓、颜色逻辑一致）
+- 线稿风格一致（线宽、轮廓、颜色逻辑一致）；**人物/物品须逼真可辨**，非抽象几何符号；造型须经过参考图临摹路径（见 §3），非空想
-- 动画节奏自然，不生硬、不抢读
+- 动画节奏自然，不生硬、不抢读；字与动效层级清晰（字可读优先）
-- **无字幕可懂**（关键）
 - `check` 通过后再宣称完成
 
 ---
@@ -136,14 +170,14 @@ disable-model-invocation: true
 ### 抽检步骤
 
 1. 抽取至少 4 帧关键截图（建议 `20% / 45% / 70% / 90%`）
-2. 检查：结构、节奏、线稿质量、语义清晰度
+2. 检查：结构、节奏、**画面字是否说清主题**、线稿质量、**造型是否像参考对象**、语义清晰度
-3. 有问题就改 HTML/CSS/SVG/GSAP 并重跑 `check + render`
+3. 有问题就改 HTML/CSS/SVG/GSAP（及 Anime.js，若使用）并重跑 `check + render`
 4. 复检通过后再交付
 
 ### 修复优先级
 
 1. 结构（位置、层级、比例、裁切）
-2. 线稿（轮廓识别、粗细统一、节点形态）
+2. 线稿（轮廓识别、**与参考图是否一致可辨**、粗细统一、节点形态）
 3. 语义（谁在做什么、为什么、结果如何）
 4. 动效（时长、缓动、错峰、运动路径）
 5. 细节（颜色、阴影、点缀）
@@ -167,7 +201,8 @@ disable-model-invocation: true
 主题是 **[一句话主题]**。  
 画面流程：**输入元素出现 -> 进入核心模块 -> 输出结果**。  
 风格要求：米白纸背景、深色线稿、强调色不超过 3 种。  
-限制：不依赖长字幕，观众静音看画面也能理解主要含义。  
+画面字：必须有**短标题 + 一句说明**，与动效分区；具象物体由执行方**自行网络检索参考图并临摹**线稿（见 §3）。  
+限制：不靠长段落小字；静音扫一眼能懂主题。  
 交付：先给静态构图，再补 GSAP 时间线，最后执行 `check` 和 `render`。」  
 
 ### 模板 B：对照叙事（8-12 秒）
@@ -176,7 +211,8 @@ disable-model-invocation: true
 左侧是 **传统流程**，右侧是 **智能流程**，需要清楚体现效率差异。  
 两侧都要有完整动作链路（开始 -> 处理 -> 结果），并在中段形成明显对比。  
 风格统一为手绘线稿，线宽和颜色逻辑一致。  
-限制：字幕只做辅助，核心信息必须靠动作表达。  
+画面字：两侧或关键步骤须有**标题级短字**点题；动作表达对比关系。  
+限制：不用长字幕；人物/道具须逼真可辨；执行方须主动网络检索参考图并临摹，勿交付抽象符号画。  
 交付：提供关键帧抽检结果（20%/45%/70%/90%）和修复说明。」  
 
 ### 模板 C：可复用组件导向（适合批量场景）
@@ -185,6 +221,6 @@ disable-model-invocation: true
 组件前缀使用 `paper-*`、`person-*`、`input-*`、`core-*`、`output-*`、`fx-*`。  
 时长 **[X 秒]**，目标语义是 **[目标语义]**。  
 先完成静态 Hero Frame，再补入场、传递、激活、收尾四段动效。  
-必须保证：无越界、无遮挡、无空选择器报错、可通过 `check`。  
+必须保证：无越界、无遮挡、无空选择器报错、可通过 `check`；**含默认短画面字**；具象造型经**网络参考图临摹**，逼真优先、非默认抽象。  
 最终输出 MP4，并附上“问题 -> 修复 -> 成片路径 -> 是否通过抽检”的汇报。」