@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/video-script-builder/SKILL.md

@@ -1,329 +0,0 @@
----
-name: video-script-builder
-description: "Convert a Chinese video voiceover script (逐字稿、口播稿) into a precise, renderer-bound storyboard specification for AICUT or AICUT, or revise an existing video-spec-hf.md or video-spec-remotion.md. Use when the user asks for 分镜、画面设计、镜头拆解、AICUT/AICUT 实现规划、动画时间轴、字幕或转场规划. Produce exactly one selected storyboard spec; never render video or create a composition. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "erduo1998-cell/video-script-builder"
----
-
-# Video Script Builder v1.4.0
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-## 初始化
-
-用户只询问作者教程、人工帮助或会员时，直接按「作者帮助」回应，不要求先提交逐字稿。其他情况下，用户尚未提供逐字稿、也没有明确要求修改已有 spec 时，原样输出以下 ASCII + 开场白。用户已经提供逐字稿或修改目标时，直接进入启动检查。
-
-```text
-███████╗██╗   ██╗██████╗  ██████╗ ███████╗
-██╔════╝██║   ██║██╔══██╗██╔════╝ ██╔════╝
-███████╗██║   ██║██████╔╝██║  ███╗█████╗
-╚════██║██║   ██║██╔══██╗██║   ██║██╔══╝
-███████║╚██████╔╝██║  ██║╚██████╔╝███████╗
-╚══════╝ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝
-```
-👋 我是 SURGE，你的程序化视频分镜导演。
-
-SURGE，无限涌动。
-
-请粘贴逐字稿。默认输出 HyperFrames 分镜；如需 Remotion，请直接注明。
-```
-
-## 启动检查与框架路由
-
-1. 扫描项目目录：精确查找 `video-spec-hf.md`、`video-spec-remotion.md`；再模糊查找 `*hyperframes*.md`、`*remotion*.md`、`*分镜*.md`。按真实路径去重；模糊候选必须读取开篇框架声明，不能只凭文件名判断。
-2. 按以下优先级锁定渲染框架，写入内部变量 `renderer`，此后不得混用：
-   1. 用户明确指定 HyperFrames 或 Remotion；
-   2. 只找到一种现有 spec 时，沿用该 spec 的框架；
-   3. 同时找到两种 spec 或多个候选时，列出文件并问“改哪个？”；
-   4. 新项目且用户未指定时，为兼容旧行为直接默认 HyperFrames，并在开场说明“需要 Remotion 可切换”。
-3. 用户要求把现有 spec 换框架时，进入“迁移模式”：读取原 spec 的叙事、素材与视觉决策，重新生成目标框架 spec；不要就地替换框架名。
-4. 若用户指定的框架与现有文件冲突，先指出冲突，再按用户最新明确指令创建目标框架文件。
-5. 框架继承不等于允许修改已有文件。只找到一个现有 spec 时：
-   - 用户明确说“修改/继续/迭代现有 spec” → 进入迭代模式；
-   - 用户只粘贴新逐字稿或泛化说“做分镜” → 先问：“检测到项目已有分镜脚本 [filename]。你是想在这个基础上改，还是新开一份？”在回答前不写文件；
-   - 用户选择新开 → 询问目标项目目录，在新目录使用该框架的标准文件名；不得覆盖现有 spec。
-
-### 输出路由表
-
-| `renderer` | 唯一交付物 | 时间模型 | 实现语言 |
-|---|---|---|---|
-| `hyperframes` | `video-spec-hf.md` | 秒 + `data-start` / `data-duration` | HF 组件 + GSAP 胶水 |
-| `remotion` | `video-spec-remotion.md` | 整数 `startFrame` / `durationInFrames` | React 组件 + Remotion API |
-
-🔒 一次任务只输出表中一个文件。禁止生成“通用双框架 spec”，也禁止在一个 Scene 中混写 GSAP 与 Remotion 帧动画。
-
-## 交付边界
-
-本 Skill 只负责导演决策和 renderer-bound spec。交付 spec 后立即停止。
-
-- ❌ 不创建 `index.html`、`Root.tsx`、composition、项目脚手架或配置文件。
-- ❌ 不启动 HyperFrames/Remotion CLI，不预览，不渲染 MP4。
-- ❌ 不下载素材；只记录真实路径、待获取项和 fallback。
-- ❌ 不把完整可运行的 HTML/TSX 当作 spec 内容。
-
-渲染端 Agent 负责安装依赖、实现 composition、处理层级和转场重叠、预览、验证与渲染。
-
-## 核心理念：导演，不是渲染器
-
-先回答“为什么这样拍”，再回答“目标框架如何无歧义地实现”。逐字稿是内容真源；框架只改变实现契约，不改变叙事判断。
-
-### 逐字稿推断
-
-| 推断项 | 方法 |
-|---|---|
-| 总时长 | 中文字符数 ÷ 4，再给停顿留 10–15% buffer |
-| 段落 | 按语义转折词与论证职责切分 |
-| 情绪曲线 | 问题=好奇，恶化=紧张，方案=希望，结论=顿悟 |
-| 平台/画幅 | ≤60s 优先 9:16；更长内容优先 16:9，均标 `[待用户确认]` |
-| 核心信息 | 收尾结论压缩到 ≤12 字 |
-
-任何无法从逐字稿确认的事实写 `[待用户确认]`，禁止编造。
-
-## 分镜流程
-
-### 0. 输入质量门控
-
-- 字数 ≥100；
-- 至少 3 个语义转折；
-- 存在可压缩为 ≤12 字的收尾金句。
-
-任一项不满足时，说明缺什么、为什么、怎么补；不要为了凑镜头编内容。
-
-### 1. 意图卡
-
-技术选型前先写入：
-
-```yaml
-视觉人格: [3 个可执行特征，例如“高对比/大面积留白/字体细”]
-情绪-视觉映射: [情绪拐点 → 速度、密度、色彩、运动]
-视觉母题: [一个元素在 hook / 主体 / 收尾的三次变奏]
-参考拆解: [具体借鉴点，不只写作品名]
-反调预警: [最容易出现的视觉陷阱]
-```
-🔒 没有母题不产出 spec。每个 Scene 必须用 ≤20 字说明选型为什么符合意图卡；相邻镜不能复用同一理由。
-
-意图设定必读 `references/taste-principles.md`。
-```
-
-### 2. 素材盘点
-
-先列已有、待获取与 fallback，再设计镜头。素材路径必须真实或明确标为待获取。
-
-| 层级 | 来源 | 规则 |
-|---|---|---|
-| Tier 1 | 用户/项目已有素材 | 优先复用并记录相对路径 |
-| Tier 2 | GitHub CC0/MIT、公共领域资源 | 记录仓库、文件与许可 |
-| Tier 3 | 框架自带获取能力或浏览器搜索 | 每次只找必需项；需登录就停止 |
-| Fallback | 目标框架可实现的图形/排版 | 不伪装成已获取素材 |
-
-不要默认依赖需要注册或 API key 的图库；不存在“先用占位图以后再换”。
-
-### 3. 叙事与镜头切割
-
-按句号断句，合并连续短句（<8 字），在连词/转折处拆长句（>30 字），排比句每项独立。开/中/收时长约为 15–20% / 60–70% / 10–15%。
-
-每镜记录：旁白原文、叙事职责、屏显关键词、主视觉、辅视觉、密度、冷暖、素材、字幕、转场、音效和选择理由。
-
-节奏选择必读 `references/pacing-rules.md`。
-
-### 4. 画面与品味
-
-- 开镜 hook 必须有占画面主体的视觉锚点，禁纯文字开场。
-- 屏显文字只保留 1–4 个关键词，不能逐字重复字幕。
-- 多数镜头应以视觉/素材承载信息，而不是 PPT 式文字卡。
-- 全片必须有一个“最空”和一个“最满”的镜头，密度差 ≥2 档；密镜 ≤总镜数 25%。
-- 连续两镜不得同密度；连续三镜不得同冷暖；相邻时长差建议 ≥0.5s。
-- 每个 Scene 完成后问“有什么可以删掉？”；能删就删。
-
-## HyperFrames 适配器
-
-仅当 `renderer=hyperframes` 时加载本节资源。
-
-### 选型规则
-
-1. 写 Scene 前读 `references/component-catalog.md`；按场景读 `references/component-recipes.md`、`references/caption-components.md` 与 `references/shader-transitions.md`。
-2. 官方组件优先，手写 CSS 只作 fallback。每镜至少绑定一个组件或素材。
-3. 核心锚点（hook、金句、首尾呼应）必须使用真实官方组件或真实素材，禁 CSS 假组件。
-4. 每 3 镜至少 1 镜在 L1 层使用 3D/VFX；全片 L1 3D/VFX 组件至少 2 种，底板 shader 不计。
-5. 联网时在交付前复核官方 registry；无法复核则标 `[需渲染端复核]`。
-6. 最终 spec 的组件依赖必须逐项写真实组件名与完整命令（例如 `npx hyperframes add vfx-portal`）；不得残留 `<name>`、`<组件名>` 或“分别执行上述命令”式占位。
-
-### 时间与动画
-
-- 使用秒制 `data-start` / `data-duration`。
-- GSAP 只负责跨组件显隐、素材切换和转场触发；组件内部动画由组件负责。
-- 禁止链式 `delay`、`opacity`、布局属性 tween 和无限循环；使用绝对 position、`autoAlpha`、transform 与有界循环。
-- 所有 tween 必须落在 Scene 时间边界内。
-
-填写前读 `references/gsap-patterns.md` 与 `templates/video-script-spec-template.md`。
-
-### HyperFrames 交接
-
-```text
-SURGE → video-spec-hf.md → HyperFrames 渲染 Agent → composition + MP4
-```
-收尾明确提示渲染端通过 `npx hyperframes add` 复核/安装组件，不得换用其他框架。
-```
-
-## Remotion 适配器
-
-仅当 `renderer=remotion` 时加载 `references/remotion-patterns.md` 与 `templates/video-script-spec-remotion-template.md`。
-
-### 选型规则
-
-1. 把每镜写成可复用 React 组件契约：`component`、`props`、`assetBindings`、`animation`，不要声称 Remotion 内置了不存在的视觉组件。
-2. 优先复用目标项目已有组件；未发现实现时标为 `[需渲染端实现]`，并写清输入 props 与视觉验收，不输出完整 TSX。
-3. 3D/WebGL、图表或特殊字体需要额外库时标 `[需渲染端选库/复核许可]`，不得自行编造包名。
-4. 本地素材进入下游项目 `public/`，spec 中以 `staticFile()` 绑定路径；远程素材必须记录 URL 稳定性与 fallback。
-
-### 时间与动画
-
-- 全片锁定 `fps`，所有 Scene 使用整数 `startFrame` 与 `durationInFrames`；秒数只作人类参考。普通 `<Sequence>` 把 `startFrame` 映射到 `from`；`<TransitionSeries.Sequence>` 没有 `from`，其 `startFrame` 只作公式派生的审计坐标。
-- `durationInFrames = round(seconds × fps)`；相邻镜边界以帧为真源，禁止累计小数秒。
-- 组件动画由 `useCurrentFrame()` 驱动，通过 `interpolate()` / `spring()` 计算；禁止 CSS transition、`setTimeout`、运行时随机数和 wall-clock 时间。
-- 普通编排使用 `<Sequence>`；需要镜间转场才使用 `<TransitionSeries>`。
-- Transition 会让两镜重叠并缩短总时长：`total = Σ sceneFrames - Σ transitionFrames`。Overlay 不缩短时间轴。转场不得长于相邻任一 Scene。
-- 动画输入区间必须落在 Scene 的局部帧 `[0, durationInFrames - 1]`，`interpolate()` 默认写明 clamp 策略。
-- 音频优先写 `<Audio>`（`@remotion/media`）契约，记录 `from`、`durationInFrames`、trim 和 volume；不在 spec 阶段执行转码。
-
-### Remotion Scene 必填字段
-
-```yaml
-Scene N: [标签]
-  🔒 帧区间: startFrame=[整数] durationInFrames=[整数]
-  🔒 挂载模型: Sequence from=startFrame | TransitionSeries 顺序派生
-  📐 秒数参考: [startSeconds]s → [endSeconds]s
-  🔒 旁白原文: "[逐字稿片段]"
-  🔒 屏显文字: "[1-4字]" | null
-  🔒 component: [PascalCase 名]
-  🔒 props: {[可序列化输入]}
-  🔒 assetBindings: [staticFile 路径或远程 URL + fallback]
-  🔒 animation: [局部帧区间 → interpolate/spring → 视觉属性]
-  🔒 caption: [组件/数据/词级时间戳策略]
-  🔒 transition: [presentation + timing + durationInFrames] | cut | overlay
-  🎬 选择理由: [≤20字]
-  🎨 可调范围: [帧/位置/比例的数值范围]
-
-### Remotion 交接
-
-```text
-SURGE → video-spec-remotion.md → Remotion 渲染 Agent → React composition + MP4
-```
-收尾明确提示渲染端先核对目标项目的 Remotion 版本、现有组件和许可，再按 spec 实现；不得换用 HyperFrames 或把帧数改回模糊秒数。
-```
-
-## 音频、字幕与转场
-
-共同的内容决策读 `references/audio-workflow.md`；框架实现以当前 adapter 为准。
-
-- 旁白、BGM、音效必须各自记录源、起止、音量和 fallback。
-- 逐词字幕没有时间戳时标 `[待转录]`，不要按字数伪造精确词级时间。
-- 全片至少使用两种字幕表现，但变化必须与段落情绪一致。
-- 全片至少两种转场；任一强转场 ≤总镜数 30%，闪白与 glitch 各 ≤2 次。
-- 转场是叙事标点，不是每镜必加；普通 cut 是合法选择。
-
-## 12 条硬阻断
-
-输出前读取 `references/quality-checklist.md`，逐条通过：
-
-1. **框架绑定**：文件名、开篇声明、时间模型和交接对象全部对应 `renderer`。
-2. **单一交付**：本次只生成目标 spec，没有 composition、代码项目或渲染物。
-3. **结构完整**：意图卡与 §1–10 齐全，未知项明确标注。
-4. **时间闭合**：Scene 连续、无负数/空洞，结尾等于总时长；Remotion 还要核对 transition overlap 公式。
-5. **镜头覆盖**：每镜至少一个真实素材、官方组件（HF）或明确组件契约（Remotion）。
-6. **开镜锚点**：hook 在开头 3 秒内且不是纯文字/纯底板。
-7. **字幕去重**：屏显关键词不逐字重复旁白/字幕；词级时间戳不伪造。
-8. **动画确定性**：动画在 Scene 边界内；HF 符合 GSAP 纪律，Remotion 符合帧驱动纪律。
-9. **多样性**：组件/构图/字幕/转场不过度重复，并符合 renderer 的真实能力。
-10. **意图一致**：每镜有不重复的选择理由，视觉母题在 hook/主体/收尾至少出现 3 次。
-11. **节奏与密度**：存在呼吸和高潮，密度/冷暖/时长不机械重复，强效果不过量。
-12. **可交接**：路径、依赖、fallback、开放问题和渲染反馈区无歧义，渲染端无需猜测。
-
-任一项失败就先修正，不带病交付。
-
-## 输出结构
-
-两种模板都使用相同的 10 节语义骨架，字段实现按框架分开：
-
-1. 视频基本盘
-2. 叙事结构
-3. 表达手段
-4. 视觉与渲染规范
-5. 素材清单
-6. 分镜表
-7. 音频时间轴
-8. 参考与反例
-9. 开放问题
-10. 渲染反馈
-
-## References 路由
-
-| 时机 | 必读 |
-|---|---|
-| 意图设定 | `references/taste-principles.md` |
-| 时间轴切割 | `references/pacing-rules.md` |
-| 音频规划 | `references/audio-workflow.md` |
-| HyperFrames 选型 | `references/component-catalog.md` + `references/component-recipes.md` + `references/caption-components.md` + `references/shader-transitions.md` |
-| HyperFrames 动画 | `references/gsap-patterns.md` |
-| Remotion 实现契约 | `references/remotion-patterns.md` |
-| 输出前 | `references/quality-checklist.md` |
-| 迭代/迁移前 | `references/common-pitfalls.md` |
-| 填写 spec | 当前 renderer 对应的 `templates/` 模板 |
-
-## 交付收尾
-
-spec 通过 12 条阻断后：
-
-1. 报告框架、文件名、镜头数、总时长/总帧数、画幅、核心信息、组件/素材统计；
-2. 告知下一步交给对应渲染 Agent；
-3. 停止，不继续实现或渲染。
-
-```text
-分镜脚本 [video-spec-hf.md | video-spec-remotion.md] 已生成。
-
-🎬 框架：[HyperFrames | Remotion]
-📊 [N] 镜 · [总时长]s [Remotion: / 总帧数 frames] · [平台] [画幅]
-🎯 核心信息：[≤12字]
-🧩 实现单元：[组件/组件契约统计]
-🖼️ 素材：[已有/待获取/fallback 统计]
-
-下一步：将这份 spec 交给对应框架的渲染 Agent，由它创建 composition、预览并渲染 MP4。
-
-## 作者帮助（按需）
-
-用户主动询问作者教程、人工帮助或会员，或合理自助排查后仍受阻时，按需读 [作者帮助`author-support.md`，在对话中提供相关可选入口，不写入分镜 spec。普通成功、一次可恢复错误或用户已拒绝时不推荐；同一会话同一问题只由主 Agent 主动推荐一次，不中断已授权排查。已是会员则指向资料库。不自动注册、购买或上传私人数据；仍只交付选定框架的一份 spec，不扩展为渲染或代做 Skill。
-
-## Source
-
-Rewritten for AICUT from [`erduo1998-cell/video-script-builder`](https://github.com/erduo1998-cell/video-script-builder)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/video-script-builder/examples/quick-start-transcript.md

@@ -1,19 +0,0 @@
-# 快速试跑逐字稿
-
-把下面内容连同其中一句提示词交给 Agent：
-
-> HyperFrames：请使用 video-script-builder，把下面逐字稿拆成适合 9:16 短视频的 HyperFrames 分镜规格。
->
-> Remotion：请使用 video-script-builder，把下面逐字稿拆成适合 9:16、30fps 短视频的 Remotion 分镜规格。
-
----
-
-很多人以为，做视频最难的是把画面做得炫。
-
-但真正让一条视频变得混乱的，往往不是特效不够，而是每一个镜头都在临时决定。文案写完了才去找素材，素材找到了才想转场，最后所有东西都堆在时间线上，却没有一个统一的视觉意图。
-
-所以，正确的顺序不是先打开剪辑软件，而是先把导演决策写下来：这句话要让观众感到什么，用什么画面承担信息，什么时候该密，什么时候必须留白。
-
-当这些决定变成一份精确的分镜规格，渲染就不再依赖猜测。组件、素材、时间码和动画边界都有出处，任何人接手都知道下一步该做什么。
-
-先把决定写清楚，再把画面做出来。

package/skills/video-script-builder/references/audio-workflow.md

@@ -1,84 +0,0 @@
----
-name: audio-workflow
-description: HyperFrames/Remotion 双后端的旁白、BGM、字幕时间戳与音效规划。只写入 spec，不在分镜阶段执行生成或转码。
----
-
-# BGM / TTS / 音频时间轴
-
-## 共同原则
-
-- 本 Skill 只规划音频，不执行 TTS、转录、转码或素材下载。
-- 没有真实逐词时间戳时写 `[待转录]`，禁止按字数均分伪造时间戳。
-- 语速基准：中文约 4 字/秒，最终以真实音频时长和转录结果为准。
-
-## HyperFrames 下游工作流
-
-本 Skill 只在 spec 中规划音频，不执行以下命令。命令由渲染端在用户批准后运行。
-
-```bash
-# 1. 使用本地 Kokoro 生成中文 TTS 旁白
-npx hyperframes tts "逐字稿全文" --voice zf_xiaobei --speed 1.0 -o assets/narration.wav
-
-# 2. 转录中文时间戳（如需逐词高亮；禁止使用 .en 模型）
-npx hyperframes transcribe assets/narration.wav --model small --language zh
-
-# 3. 根据时间戳对齐 GSAP 字幕动画
-```
-
-`--speed` 用于调整语速；实际可用参数由渲染端按当前 CLI 复核。
-
-## Remotion 下游契约
-
-Remotion spec 不绑定某个 TTS 提供商。已有音频放入下游项目 `public/`，用 `staticFile()` 引用；音频组件优先使用 `@remotion/media` 的 `<Audio>`。
-
-```yaml
-旁白:
-  src: staticFile("audio/narration.wav")
-  from: 0
-  durationInFrames: [整数]
-  trimBefore: 0
-  trimAfter: [整数帧或 null]
-  volume: 1
-BGM:
-  src: staticFile("audio/bgm.mp3")
-  from: 0
-  durationInFrames: [总帧数]
-  volume: [静态值或 frame-driven 函数契约]
-字幕时间戳: [真实词级数据路径或 `[待转录]`]
-```
-
-- `from`、`durationInFrames`、trim 均以整数帧为真源。
-- 音量变化写成 `frame → interpolate() → volume` 契约，不使用 CSS/运行时时钟。
-- 远程音频必须记录稳定 URL、许可与本地 fallback；不要假定渲染时网络可用。
-
-## BGM 参数模板
-
-```yaml
-类型: 氛围电子 (ambient electronic)
-特征: 低沉 sub-bass pad + 轻微 rhythmic pulse (80-90 bpm)
-旁白存在时 volume: 0.12 (作为底色, 不抢旁白)
-旁白静默时 volume: 0.20
-段落切换 swell: 0.12 → 0.22 → 0.12, 0.5s 内完成
-来源: Pixabay Music / YouTube Audio Library
-```
-
-## 音效使用纪律
-
-- 仅用于关键动效的同步强调（弹入/闪屏/揭晓）
-- 每个音效标注触发时间码（对齐 GSAP timeline position）
-- volume: 0.15-0.35，不盖过旁白
-- 无音效的 Scene 必须写 `🔒 音效: 无`
-
-## 音频标签示例
-
-```html
-<!-- BGM: 全片 -->
-<audio id="bgm" data-start="0" data-duration="411"
-  data-track-index="4" src="assets/bgm.mp3" loop data-volume="0.12">
-</audio>
-
-<!-- TTS 旁白: 全片 -->
-<audio id="narration" data-start="0" data-duration="411"
-  data-track-index="5" src="assets/narration.wav" data-volume="1">
-</audio>
-```

package/skills/video-script-builder/references/caption-components.md

@@ -1,70 +0,0 @@
----
-name: 字幕组件
-description: HyperFrames 16 种官方字幕组件完整参考，用于分镜制作时根据情绪/场景选择字幕展示风格。替代旧版手写 CSS 字幕方案。
----
-
-# 字幕组件
-
-## 字幕设计哲学
-
-HyperFrames 的字幕不是简单的"底部文字条"。16 种官方字幕组件覆盖了从极简（weight-shift）到爆炸（kinetic-slam）的完整情绪光谱。
-
-**核心理念**：字幕风格必须匹配镜头的情绪强度。柔和的内容配柔和的字幕，冲击力内容配冲击力字幕。不要让字幕与画面情绪打架。
-
-## 字幕风格选择表
-
-| 情绪/场景 | 推荐字幕组件 | 视觉效果 |
-|-----------|------------|---------|
-| Hook/冲击 | caption-kinetic-slam | 全屏大字交替方向弹入 |
-| 数据/事实 | caption-highlight | TikTok 式红色背景扫过关键词 |
-| 技术/AI感 | caption-matrix-decode | 字符乱码后解码揭示 |
-| 游戏/赛博 | caption-glitch-rgb | RGB 色散+CRT 扫描线 |
-| 温暖/人文 | caption-weight-shift | 优雅字重渐变过渡 |
-| 高端/品牌 | caption-editorial-emphasis | 双字体+戏剧性大小对比 |
-| 氛围/沉浸 | caption-texture | 流动纹理遮罩（6种纹理可选） |
-| 专业/讲解 | caption-pill-karaoke | 药丸容器+逐词卡拉OK |
-| 能量/爆发 | caption-particle-burst | 关键词触发彩色粒子爆炸 |
-| 简约/干净 | caption-clip-wipe | 左到右 clip-path 逐词揭示 |
-| 3D/深度 | caption-parallax-layers | 背后3D文字层叠+纵向拉伸 |
-| 夜店/霓虹 | caption-neon-glow | 青色+品红霓虹发光 |
-
-### 补充组件
-
-以下组件用于上述表格未覆盖的特殊场景：
-
-| 组件名 | 适用场景 | 视觉效果 | 安装命令 |
-|--------|---------|---------|----------|
-| caption-gradient-fill | 渐变品牌风格 | 渐变色填充文字 | `npx hyperframes add caption-gradient-fill` |
-| caption-emoji-pop | 轻松/社交媒体风格 | Emoji 弹跳伴随文字 | `npx hyperframes add caption-emoji-pop` |
-| caption-neon-accent | 霓虹强调（比 glow 更克制） | 单色霓虹描边 | `npx hyperframes add caption-neon-accent` |
-| caption-blend-difference | 实验性/艺术风格 | mix-blend-mode 差异混合 | `npx hyperframes add caption-blend-difference` |
-
-## 字幕 vs 屏显文字
-
-**关键规则：不要用字幕组件展示屏显文字。**
-
-```
-屏显文字（Screen Text）：
-- 1-4 个关键词
-- 出现在画面中央或特定位置
-- 通常使用 vfx-text-cursor 或其他 VFX 组件
-- 是画面的有机组成部分
-
-字幕（Subtitle）：
-- 完整的口播文案
-- 出现在画面底部区域
-- 使用本页的 16 种字幕组件之一
-- 是配音的文字伴随
-```
-
-**特殊情况**：当使用 `caption-kinetic-slam` 或 `caption-particle-burst` 时，字幕本身已经具有强烈的视觉冲击力，此时**字幕就是屏显文字**——不要再另外放一份相同内容的屏显文字，会导致画面冗余。
-
-## 字幕轨道管理
-
-每个镜头使用**一种**字幕组件。组件之间可以切换：
-
-- 同一段落内：字幕组件保持不变，保证视觉一致性
-- 段落切换时：可以更换字幕组件以匹配新的情绪基调
-- 全片建议不超过 3 种字幕组件（开篇 1 种、主体 1 种、结尾可选 1 种）
-
-所有字幕组件通过 `npx hyperframes add <name>` 安装，安装后引入对应的 CSS/JS 代码片段即可使用。

package/skills/video-script-builder/references/common-pitfalls.md

@@ -1,80 +0,0 @@
----
-name: common-pitfalls
-description: HyperFrames/Remotion 双后端的常见执行偏差与渲染反馈采集框架。经对应渲染 Agent 实际执行后回填，反向校准 SKILL.md 和模板。
----
-
-# 常见执行偏差
-
-> ⚠️ 本文件是活的——每轮 Agent B 渲染反馈后更新。
-
-## 反馈采集机制
-
-`video-spec-hf.md` 或 `video-spec-remotion.md` 的 §10 由对应渲染 Agent 填写。每次渲染完成后记录：
-
-1. **直接可执行的 Scene**：哪些 Scene 的实现单元、素材绑定和框架专属动画契约无需修改即可落地
-2. **需要修改的 Scene**：哪些 Scene 不得不改，具体改了什么
-3. **理解偏差**：Agent B 是否误解了某些指令
-
-## 已知偏差模式
-
-### 模式 1: Agent 绕过 HyperFrames 手写 HTML
-
-- **表现**: Agent 产出 video-spec-hf.md 后，又创建了 index.html 和 preview.html，将 spec 中各 Scene 的 HTML/CSS/GSAP 代码块拼接成独立文件，完全绕过 HyperFrames 框架。这样产出的 HTML 缺少 `class="clip"`、`window.__timelines` 注册、`data-composition-id` 等 HF 框架必需结构，无法正确渲染。
-- **根因**: 旧版 skill (v1.1) 的 spec 中每个 Scene 都有完整可执行的 HTML/CSS/GSAP 代码块。Agent 看到可执行代码自然想"帮你做出来"，没有明确的 STOP 指令。
-- **修复 (v1.2)**:
-  1. spec 不再包含完整的 HTML 结构代码块，改为组件引用 + 素材路径 + GSAP 胶水指令，从根本上消除"可以直接拼成 HTML"的错觉
-  2. SKILL.md §13 交付收尾硬 gate：禁止创建任何非 spec 文件（index.html / preview.html / compositions/）
-  3. 每个 Scene 的 GSAP 代码块只写胶水逻辑（入场/停留/退场时间点和触发顺序），不写完整 tween——完整 tween 由组件自带
-
-### 模式 2: 渲染 Agent 擅自更换 spec 绑定的框架
-
-- **表现**: `video-spec-hf.md` 被改用 Remotion/Manim/MoviePy，或 `video-spec-remotion.md` 被改用 HyperFrames/GSAP。结果是组件契约、时间模型和转场计算失效。
-- **根因**: spec 未声明渲染框架绑定，或下游把“支持双后端”误解为“单份 spec 可任意换后端”。
-- **修复 (v1.2.1)**:
-  1. 两个模板开篇分别声明 HyperFrames 或 Remotion，并明确禁止换框架。
-  2. 文件名与时间模型绑定：HF 用秒和 `data-*`；Remotion 用整数帧和 `Sequence`。
-  3. SKILL 与质量清单检查一次只交付一种 renderer-bound spec。
-  4. 收尾明确交给对应框架渲染 Agent。
-
-### 模式 3: 把双后端做成一份混合 spec
-
-- **表现**: 同一 Scene 同时出现 `data-start`、GSAP、`from`、`durationInFrames` 和 `useCurrentFrame()`，让下游自行挑选。
-- **根因**: 为了“复用”而把真正不同的执行契约压在同一层。
-- **修复 (v1.4.0)**: 只复用意图、叙事、素材与 10 节语义骨架；模板、时间模型、动画语法和交接文件完全分开。迁移时重新生成目标 spec，不做字符串替换。
-
-### 模式 4: Remotion 仍按秒或运行时时钟驱动
-
-- **表现**: Scene 使用小数秒作为真源，动画依赖 CSS transition、`setTimeout`、`Date.now()` 或未设 seed 的随机数，seek/逐帧渲染不确定。
-- **根因**: 把网页实时动画习惯带入离线逐帧渲染。
-- **修复 (v1.4.0)**: 锁定 fps，所有 Scene 使用整数 `startFrame` / `durationInFrames`；普通 Sequence 才映射到 `from`，TransitionSeries 使用派生 startFrame 台账。动画只由 `useCurrentFrame()` 驱动，并写明 `interpolate()` clamp 或 `spring()` 参数。
-
-### 模式 5: 忽略 Remotion 转场重叠
-
-- **表现**: 把所有 Scene 帧数直接相加作为总时长，同时又使用 `TransitionSeries.Transition`，导致成片比目标短。
-- **根因**: 不知道 transition 会让前后 Scene 同时渲染并缩短时间轴。
-- **修复 (v1.4.0)**: 使用 `总帧数 = Σ sceneFrames - Σ transitionFrames`；Overlay 不扣时长；转场时长不得超过任一相邻 Scene。
-
-## 渲染反馈评分维度
-
-Agent B 拿到分镜脚本后，从以下维度评分（1-5）：
-
-| 维度 | 1 分 | 5 分 |
-|------|------|------|
-| 实现单元完整性 | 多个 Scene 缺组件/props/素材绑定 | HF 组件可复核；Remotion 组件契约可实现 |
-| 动画可执行性 | 动画语法或时间边界含糊 | HF 胶水或 Remotion 帧公式均精确 |
-| 时间一致性 | Scene、转场、音频对不上 | 目标框架时间轴闭合 |
-| 无歧义程度 | Agent B 不得不自己做大量判断 | Agent B 无需任何猜测 |
-
-## 采集流程
-
-```
-Agent A 产出一个 renderer-bound spec
-        ↓
-对应框架 Agent B 实现/渲染，遇到问题记录
-        ↓
-Agent B 回填 §10 渲染反馈
-        ↓
-人工/Agent A 审阅反馈 → 更新本文件
-        ↓
-反馈驱动的改进 → 更新 SKILL.md / 模板
-```