npm - @autoaiai/aicut - Versions diffs - 0.1.11 → 0.1.13 - Mend

@autoaiai/aicut 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1063) hide show

package/skills/video-shotcraft-vincentwei10/references/music-beat-sync.md DELETED Viewed

@@ -1,257 +0,0 @@
-# music-beat-sync — BGM 节奏分析与卡点方法论
-强节奏 BGM 的片子，**所有转场和关键动效必须落在拍上**。本文档给出从
-"拿到一首曲子"到"成片切点误差 ≤3 帧"的完整可复现流程。实测：一支
-70s、18 镜、131.97 BPM 的强鼓点宣传片按此法制作，渲后回测全部切点
-误差 ≤2.2f（感知阈值约 3f）。
-## 目录
-- 何时启用
-- 节拍网格测定
-- 鼓点分类与能量结构
-- 网格验收与产物
-- 用拍号编排时间线
-- 渲后回测
-- 工具备忘
-## 0. 何时启用
-阶段 0 先检查用户是否已指定音乐。
-- 已选好 → 走本文档：先分析节奏，再让分镜的每个切点/动效锚到拍号
-- 未选 → BGM 选型放到阶段 6（见 pipeline.md），此时动效时间线按
-  内容节奏排，不强行卡点
-**铁律：音乐先行。** 网格没验收通过之前不设计分镜；时长对不上时改
-时间参数，不删改用户文案。分析全程用浮点秒记录时刻，**换算成帧只发生
-在进 Remotion 的最后一步**（提前取整会让误差在管线里滚雪球）。
-## 1. 节拍网格测定（不要相信 beat_track 的 tempo 标量）
-用 `uv run --with librosa --with scipy --python 3.11` 跑一次性脚本：
-```python
-import numpy as np, librosa
-y, sr = librosa.load("bgm.mp3", sr=None, mono=True)
-tempo, beats = librosa.beat.beat_track(y=y, sr=sr, tightness=400, units="time")
-# 关键一步：对 beat 序列做最小二乘等距网格拟合，求真实 BPM 与相位。
-# beat_track 返回的 tempo 标量可能偏差 2%+（实测 129.2 vs 真值 131.97），
-# 但它输出的 beat 时刻序列本身是好的——用整个序列拟合直线 t_i = t0 + i*T：
-i = np.arange(len(beats))
-A = np.vstack([i, np.ones_like(i)]).T
-(T, t0), *_ = np.linalg.lstsq(A, beats, rcond=None)
-bpm = 60.0 / T
-residual = beats - (t0 + i * T)
-print(f"BPM={bpm:.2f}  t0={t0:.4f}s  T={T:.5f}s  残差±{np.abs(residual).max()*1000:.0f}ms")
-```
-验收标准：残差 ≤ ±15ms（半帧内）说明曲子是机器鼓点、网格可信；
-残差大说明有变速段，需要分段拟合。
-**半倍/双倍歧义必查**：beat 检测常在 2x/0.5x 之间跳（70 BPM 报成
-140）。判据不是听感，是下一节的鼓点数据——正确的网格下 kick 应该
-主要落在整数拍；如果 kick 一半落拍一半落半拍，多半是网格快了一倍。
-拿 0.5x/1x/2x 三个候选按 §3 的指标各算一遍分数，选覆盖率最高的。
-**复杂曲先分离鼓 stem**：人声/贝斯厚的编曲会把鼓的攻击埋掉，
-beat_track 和 onset 都会漂。轻量方案 `librosa.effects.hpss` 取打击
-成分；重方案 Demucs 分离整条鼓轨（见 §6），之后所有鼓点检测都在
-鼓 stem 上做，不在全混音上做。
-## 2. 鼓点分类与能量结构（决定什么钉在哪一拍）
-### 2a. 三分类瞬态检测
-不同鼓件驱动不同类型的动效，分频段各测一遍（在鼓 stem 或 hpss
-打击成分上）：
-| 类别 | 频段 | 驱动的动效 |
-|------|------|-----------|
-| kick | 40–160 Hz | 冲击 / slam / 骤缩——画面"被砸"的一拍 |
-| snare | 150–500 Hz 体 + 1–3 kHz 打击面（两者都要有） | 替换 / 闪切 / 构图切换——"换一件事"的一拍 |
-| hihat | 6–14 kHz | 微动密度——hihat 密的段落微动效可以密，稀的段落必须收 |
-```python
-from scipy.signal import butter, sosfilt
-def band_env(y, sr, lo, hi):
-    sos = butter(4, [lo, hi], btype="band", fs=sr, output="sos")
-    env = librosa.onset.onset_strength(y=sosfilt(sos, y), sr=sr)
-    return env, librosa.times_like(env, sr=sr)
-kick_env, times = band_env(y, sr, 40, 160)
-# 把每个整数拍位置的 env 能量列出来，排序找最强 hit：
-for n in range(int((times[-1]-t0)/T)):
-    t = t0 + n*T
-    e = kick_env[np.argmin(np.abs(times - t))]
-    # 记录 (拍号 n, 能量 e)，取 top 若干作为"大 slam 候选拍"
-```
-命中记成 `{t 秒, s 强度, k 类别}` 的列表存档，设计分镜时按类别取用。
-**命中表是候选池，不是触发器。** 检测到的每个 kick 不等于都要配一次
-画面冲击——强鼓点曲（tech-house 类）kick 几乎每拍都有，逐拍执行
-"被砸"就是"镜头随节奏抖动"（实际用户投诉，见 aesthetic-rules R4）。
-kick→冲击的映射只用于从候选池里选出 §2b 的最强 hit（全片 2–3 处）；
-其余 kick 只作为切点和元素级动效的**时机**参照，不驱动画面幅度。
-### 2b. RMS 能量曲线与结构表
-`librosa.feature.rms` 拉全曲能量曲线，配合鼓点密度切出段落边界。
-产出两样东西进设计 spec：
-- **音乐结构表**：能量从第几拍起满、breakdown/静默段在第几拍——
-  分镜的能量曲线要贴着它排（breakdown 处放品牌呼吸位是天然结构），
-  高能段镜头可以多层动效并行，低能段收到 1–2 层
-- **最强 hit 拍号清单**：全片 2–3 个最大 slam（开题/高潮/收尾）
-  必须钉在这些拍上
-**易错点（实测踩过）**：最大 slam 钉在了 b52.5（两拍之间）而最强
-kick 在整数拍 b52 上，渲后回测偏差 +5.75f。强鼓点曲的重音几乎总在
-整数拍上，半拍钉点必须有 env 数据支持，不能凭听感。
-## 3. 网格验收与产物（先验收，后分镜）
-拿候选网格（含 0.5x/1x/2x）逐一对齐最近的真实鼓点瞬态，算四个指标：
-| 指标 | 含义 | 门槛 |
-|------|------|------|
-| match | 网格拍命中真实瞬态的比例 | ≥98% |
-| mean_abs_ms | 平均绝对对齐误差 | <10ms |
-| drift | 残差对时间做线性回归的斜率（漂移） | 全曲累计 <5ms |
-| 首拍有效性 | 网格第 0 拍是否落在真实的音乐攻击上 | 必须 |
-按分数选出获胜网格，把**所有候选和获胜理由**写进分析产物留档。
-拿不准时给候选网格各合成一条 click 轨叠回原曲听一遍，但最终以
-指标定夺，不以听感定夺。
-分析产物随项目留档（是每一个切点的审计链）：
-```text
-analysis/
-  beat_data.json    # bpm, t0, T, beats[], hits[{t,s,k}], rms[], sections[]
-  grid_drift.json   # 各候选网格的 match/误差/漂移 与获胜理由
-  click_*.wav       # 候选 click 轨（可选，听感复核用）
-```
-`beat_data.json` 里的时刻永远是浮点秒、不预取整；下游只依赖
-`bpm / beats / hits / rms / sections` 这几个字段名。
-## 4. 时间线用拍号写，不用帧号写
-Remotion 项目里把网格常量化，一切镜头边界/动效关键帧用 `beatF()` 表达：
-```ts
-export const FPS = 30;
-export const SOURCE_BEAT0 = 0.2244;  // 源音乐分析 t0，秒，与 beat_data.json 一致
-export const BEAT_INT = 0.45465;     // T，秒
-export const OUTPUT_AUDIO_OFFSET_SEC = 0; // 渲后回测确认有输出音轨偏移时填实测值（§5b）
-export const beatT = (n: number) =>
-  SOURCE_BEAT0 + OUTPUT_AUDIO_OFFSET_SEC + n * BEAT_INT;           // 拍→秒
-export const beatF = (n: number) => Math.round(beatT(n) * FPS);    // 拍→帧
-export const SHOTS = {
-  s0_open:  { from: 0,        to: beatF(8) },
-  s1_slam:  { from: beatF(8), to: beatF(16) },
-  // …每个镜头边界都是 beatF(整数拍)；镜头内部动效用局部拍：
-};
-export const localBeat = (shot: {from: number}, n: number) => beatF(n) - shot.from;
-```
-好处：换曲/换段落时改两个常量全片重排；SFX 钉帧表也写 `beatF(n)`，
-与画面共用同一事实源，永不错位。源分析值与渲染偏移分开记账：
-`SOURCE_BEAT0` 是审计真值永不改，输出偏移只进 `OUTPUT_AUDIO_OFFSET_SEC`。
-**锚点绑定规则**（哪些用网格、哪些用真实瞬态）：
-- 密集规则切点（每拍/每两拍一切）→ 用获胜网格的 `beatF(n)`
-- 稀疏重音、孤立定格 → **钉真实瞬态**，不用网格插值点（网格在稀疏
-  处的微小漂移会被单个重音放大成可感偏差）
-- 结尾定格 → 最后一个真实瞬态 + RMS 静默确认（防止钉在余韵尾巴上）
-- 视频素材/SFX 按**内部峰值**对齐，不按文件头对齐：
-  `素材起始 = 目标拍时刻 − (峰值时刻 − 裁剪偏移)`；峰值用音频能量
-  包络或 FFmpeg 帧差定位
-设计规矩：
-- 镜头时长以拍为单位（4/8 拍一镜），加速段可用半拍/四分之一拍阶梯
-  （如 CUT_BEATS = [48, 49.5, 50.5, 51, 51.25] 的收敛逼近）
-- 每拍一动作的步进类镜头（清单逐项、马赛克逐格）直接 map 拍号
-- BGM 鼓点已密时 SFX 克制：只钉画面独有动作，大 slam 只给 2–3 处，
-  其余让位给 BGM 的鼓
-- **全画面级冲击有硬上限**（整画面 scale 泵/震屏/闪帧/负片帧等一切
-  作用于整画面或相机层的瞬时冲击）：全片 ≤3 处、与 §2b 最强 hit
-  清单一一对应、相邻两处间隔 ≥16 拍；节拍泵类连打单次 ≤4 拍
-  且全片 ≤1 次，打完接足 hold（各卡标注值是底线）。
-  计数单位是**一次手法使用**（一张卡的一次应用 = 一个名额），含
-  多次内部闪帧的卡（连闪/多刀切串）不逐帧重复计数，其内部
-  结构由各卡自身的参数表与次数上限管辖
-- **卡点动效默认落在主角元素层**（卡片/标题/数字），整画面与相机层
-  默认不参与逐拍运动；"每拍一动作"指内容步进（清单逐项/马赛克
-  逐格），不是画面幅度脉冲
-- 结构性运动（形变/运镜/位姿）用连续帧函数；冲击事件（出现/替换/
-  闪/骤缩）在选定的那一帧上开关。多层动效同帧命中构成重音；要错
-  开只错 1–2 帧且必须是设计意图，不允许来自取整的意外错位
-## 5. 渲后回测（闭环，必做）
-### 5a. 两种误差分开报，不混为一谈
-- **音频真值误差**：设计切点秒值 vs 真实瞬态秒值的距离，验的是
-  分析管线；门槛：平均 <5ms，全部 ±33ms 内，90% 在 ±15ms 内
-- **视觉量化误差**：秒值换算到最近可渲染帧引入的取整误差，验的是
-  帧率够不够；`beatF()` 取整那一步的误差就是它，逐锚点记录
-最近帧取整的误差上限由 FPS 决定：30fps 是 ±16.7ms、60fps 是
-±8.3ms、120fps 是 ±4.2ms。**30fps 交付不要声称 <5ms 的视觉精度**；
-量化误差报表超出容忍时升帧率，而不是去改音频分析。
-### 5b. 渲出成片抽音轨回测
-```bash
-ffmpeg -i out/promo.mp4 -vn -acodec pcm_s16le /tmp/render-audio.wav
-```
-对渲出音轨重跑第 1 步的网格拟合（BGM 从视频里量，不从源文件量——
-这样连音频编码/对齐偏移一起验），然后逐一对比：
-**设计切点帧号 vs 最近测得拍的帧号**，输出误差表。
-| 判定 | 误差 |
-|------|------|
-| 合格 | ≤3f（感知阈值） |
-| 理想 | ≤1.5f |
-| 必修 | >3f 的任何切点 |
-误差超标的钉点回第 4 步改拍号或帧偏移，重渲再测，直到全表合格。
-**系统性同向偏移先查输出音轨偏移，不逐点手改。** 误差表若呈同向
-等量偏移（所有切点一致 +N 帧），根因几乎总是渲染输出链路的音轨
-偏移（AAC encoder priming 等编码/封装环节，48kHz 典型 ≈1.28f，
-机制与实测方法见 sound-design §4.6），不是节拍分析错。诊断：拿
-BGM 原文件与渲出音轨做归一化交叉相关量出偏移量。修复：**输出偏移
-单设常量，不写回源分析值**——`beat_data.json` 里的 t0 是源音乐的
-分析真值和审计基准，混入渲染偏移会在换 codec/重新分析时造成二次
-补偿。代码里分开记账：
-```ts
-export const SOURCE_BEAT0 = 0.2244;        // 源音乐分析 t0，与 beat_data.json 一致，永不掺入渲染偏移
-export const OUTPUT_AUDIO_OFFSET_SEC = 0.0427; // 输出音轨偏移，按渲染管线实测（sound-design §4.6）
-export const beatT = (n: number) => SOURCE_BEAT0 + OUTPUT_AUDIO_OFFSET_SEC + n * BEAT_INT;
-```
-全片切点随 `beatT` 一次归位，**不要逐锚点手改拍号**；SFX 侧的补偿
-走 sound-design §4.6 的同一常量。这类错位的观感危害不止"不准"：
-冲击画面差 2–3 帧听不出是跟着鼓的，合理的卡点动效会被读作无端抖动。
-## 6. 工具备忘
-- librosa 不在系统 python：`uv run --with librosa --with scipy --python 3.11 script.py`
-- 只有人声/复杂编曲的曲子 beat_track 会漂：先用 `librosa.effects.hpss`
-  分离打击成分再测；仍不干净时上 Demucs 分离鼓轨——
-  `uvx --from demucs demucs --two-stems=drums -n htdemucs bgm.mp3 -o analysis/`，
-  之后 §1/§2 全部在 `drums.wav` 上跑
-- BPM 拿不稳（多方法交叉验证）：madmom 的 RNN+DBN 和 Essentia 的
-  RhythmExtractor2013 可作 librosa 之外的第二、第三票；三者对不齐时
-  回 §3 用瞬态覆盖率投票，不猜
-- 变速曲（DJ 转场、accelerando）：先用 librosa 局部 tempogram
-  （约 5s 窗）确认变速点，再按能量段分段拟合，各段各自 t0/T

package/skills/video-shotcraft-vincentwei10/references/pipeline.md DELETED Viewed

@@ -1,401 +0,0 @@
-# pipeline — 八阶段制作流水线
-八阶段，方向性问题不进昂贵的逐镜头阶段。
-实证细节来自多支已交付宣传片的复盘（模板片见 `template/`）。
-## 目录
-- 阶段 0：产品理解与执行约束
-- 阶段 1：视觉方向与 styleframe
-- 阶段 2：功能到镜头映射
-- 阶段 3：分镜与制作放行
-- 阶段 4：最终素材采集
-- 阶段 5：逐镜头实现
-- 阶段 6：声音设计
-- 阶段 7：独立终检与交付
-本文件是**自主自由创作**的完整流水线：阶段 0–3 的判断由 Agent 根据项目内容
-自主完成并记录，不逐阶段等待用户确认，然后连续进入阶段 4–7。用户已给出的
-用途、受众、功能、画幅、音频或数据要求都是硬约束。
-直接使用 Ink Press 模板不进入本流水线，按 `template/TEMPLATE.md` 的原有替换
-流程执行；模板文档引用阶段 4 时只借用其中的素材采集方法。
-**共同创作从 `guided-free-creation.md` 进入本文件时，不要从头重跑。** 该流程
-已经完成并确认阶段 0–3；直接从阶段 4 最终素材采集继续，不重新询问或重新设计。
-两处执行原则（实战复盘已吸收）：
-1. **最终设计 spec 与分镜共同构成制作放行。** 分镜表长在设计 spec 里
-   （`| # | 时间 | 镜头 | 关键动效 |` 四列）；确认放行不重新打开已确认的
-   业务或创意问题，只补实现必要的未决项。
-2. **验收贯穿全程，不是最后一个阶段。** 每个镜头任务以 `npx remotion still`
-   静帧肉眼验收收尾（产物按版本归档 `out/qa/`），每轮反馈修改后整片重渲。
-   阶段 7 只是把这套贯穿动作升级为对照 aesthetic-rules.md 的正式自检报告。
-另注顺序弹性：styleframe 可以先用 HTML 与少量安全预检素材；重要的是**逐镜头
-实现开始前最终素材必须依据已定案的分镜采集**——素材方向错误拖到逐镜头阶段后
-才暴露，代价是整套场景报废。
----
-## 阶段 0：产品理解与执行约束
-在写视频代码或采集最终素材前，只读检查项目的定位、主要功能、页面状态、视觉
-tokens、启动方式和数据风险。根据项目证据和用户已有描述，生成产品简报与需求到
-执行决策表，明确用途、受众、核心卖点、必须展示功能、时长/画幅/语言、音频和
-数据口径对本片的实际影响。
-自主自由创作由 Agent 对缺省项作动态判断并写入设计 spec，不暂停要求用户确认。
-用户指定了 BGM 时，先按 `references/music-beat-sync.md` 分析节奏；未指定时由 Agent
-根据产品与发布场景在阶段 6 选型。公开演示数据可在确认其公开属性后使用；客户、
-个人、内部、密钥、实时或其他敏感数据一律先虚构、脱敏或冻结。
-**产出**：产品简报；需求到执行决策表；明确的数据与音频约束。
----
-## 阶段 1：视觉方向与 styleframe
-**目标**：用最便宜的产物锁定全片色板、字体、光感与运镜气质，
-让所有方向性争论发生在写第一行 Remotion 代码之前。
-**具体操作**：
-1. 根据当前项目生成最多 3 个文字方向。每个方向附一组**动效性格 tokens**
-   （推导法见下方“品牌→动效参数”表），但不要把 Ink Press 作为固定选项。
-2. Agent 依据产品视觉、用途和受众自主选择最合适的方向，并把选择与取舍写入
-   设计 spec；不暂停等待用户选择。
-3. 对选定方向**不渲染视频、不写 Remotion 代码**，写一个纯 HTML/CSS
-   styleframe 页，包含 2–3 张 1920×1080 静态关键画面。
-4. 用 Playwright/Puppeteer 截图验证字体、色板、材质、构图、光感与信息密度；
-   缓动和运镜速度仍以 tokens、Gallery 样片或短运动测试判断。若已有严格品牌规范
-   或明确参考片，可记录理由后跳过 styleframe。
-5. 若用户给了参考片：下载后 ffmpeg 抽帧（`select=eq(n,…)` 抽 ~100 帧、
-   `tile=4x5` 拼 contact sheet），逐个动画/转场/特效做 motion breakdown，
-   写成"手法｜参考片实现｜取舍"三列表进设计 spec——**选择性适配，
-   不强行套用**。图片参考同理：它描述的是"某一类镜头"的感觉，
-   不是全片风格令。
-**品牌→动效参数推导**。不凭手感挑 easing/时长，先把品牌放到两根轴上，
-再从最近的预设起步：
-- **能量轴**：低（沉稳/premium/机构感）↔ 高（运动/startup/娱乐）——
-  决定时长、过冲、squash 幅度；
-- **调性轴**：严肃（金融/医疗/enterprise）↔ 活泼（消费/社交/儿童）——
-  决定路径曲直、次级动作多寡。产品视觉本身是证据（锐利几何形→工程感，
-  圆角+亮色→柔和活泼）；用户口述的品牌词覆盖视觉推断。
-| 预设（品类） | 主时长@30fps | 入场 easing | 过冲 | squash |
-|---|---|---|---|---|
-| 专业信赖（fintech/enterprise/B2B）| ~21f | bezier(0,0,0.2,1) | 1.0 不弹 | 0 |
-| 精致高端（奢侈品/时尚）| ~48f | bezier(0.4,0,0.6,1) | ≤1.02 | 0 |
-| 活力大胆（体育/游戏/startup）| ~18f | bezier(0.16,1,0.3,1) | 1.12 | 0.25 |
-| 活泼愉悦（消费/社交）| ~27f | bezier(0.34,1.56,0.64,1) | 1.08 | 0.18 |
-| 平静关怀（健康/教育）| ~42f | ease-in-out 对称 | 1.0 | ≤0.04 |
-| 亲和友好（小微/社区）| ~26f | bezier(0.25,0.46,0.45,0.94) | 1.04 | 0.08 |
-用法：定预设 → 按两轴微调 → tokens 写进设计 spec。自检两条：
-①用三个词描述成片动效，与品牌词对得上吗；②同一套 tokens 必须同时管
-入场/转场/hold 节奏——一个品牌一种动效嗓音，混用两套读作拼盘。
-注意预设值与库内硬判例冲突时判例赢：落地要弹的场合 y1 必须 >1，
-"专业信赖不弹"指的是无落地隐喻的淡入/推移类动作。
-**产出**：选定方向的 styleframe；色板/字体/光感 tokens + 动效性格 tokens；
-（有参考片时）motion breakdown 表。
-**常见坑**：
-- 用渲染视频做风格提案：太贵，改方向的心理成本也高。静态帧足够定调。
-- 参考驱动的风格 move 全局一刀切：风格化机位逐镜头决定（信息密集的
-  列表/堆叠镜头正视更可读）。
----
-## 阶段 2：功能到镜头映射
-**目标**：为每个必须展示的功能选定合适的运动语法，不在此阶段提前写完整分镜。
-**具体操作**：
-1. **先列产品功能清单，逐一对应镜头**。核心功能漏拍等于返工；
-   一种动画手法（飞入/堆叠/翻页）全片只当一次主角，同质化即返工信号。
-2. 扫描 `references/shots/` 全部卡片的 frontmatter，根据用途、能量、建议时长、
-   限制和所需页面状态，为每项功能选择首选与备选卡；Agent 自主定案并记录依据。
-3. 完整读取选中卡片，并按“参考实现”定位准确 demo 源码。没有合适卡片时可新写，
-   但必须在设计 spec 中说明范围与验证风险。
-**产出**：功能到镜头映射表；选中卡名、变体、demo 源码和参考样片定位。
----
-## 阶段 3：分镜与制作放行
-**目标**：把已定案的功能与镜头映射排成有能量曲线的完整镜头序列，并转成帧级
-实施计划。自主自由创作由 Agent 自行放行，不暂停等待确认。
-**具体操作**：
-1. 先查 `references/sequences/` 有无适用的桥段模板；有则按其填空流程分配段位
-   与帧预算，再把映射好的镜头排成低能量开场→功能段与呼吸位交替→高能量收尾。
-2. **已有指定 BGM 时**：先出音乐结构表（满能量起点/breakdown 拍号，
-   见 music-beat-sync.md §2），镜头边界全部锚到拍号，最强 hit 分给
-   全片 2–3 个大 slam；breakdown 段天然是品牌呼吸位。
-3. 写完整分镜表：镜头顺序、时长、功能信息、具体页面状态、镜头卡与变体、主动作、
-   素材来源、字幕、转场和 SFX。每镜只讲一个主要动效。
-4. 排时间线时**预留 hold/rest 帧预算**：品牌字标落定 hold ≥1s（30f）、
-   批量动效收尾 0.5s 静止、开场主体动作 ≥3s。节奏返工是单向的——
-   过快必返工、放慢从未被否。
-5. Agent 检查分镜与产品简报、需求决策、视觉方向和镜头映射一致后自行放行，
-   把分镜转译成帧级时间轴进实施计划：
-   `| shot | from | duration | 内容 |`（卡点片则 from/to 全用 `beatF(n)`
-   表达），并给每镜头指定源文件与验收帧号。
-**产出**：设计 spec（含风格 tokens + motion breakdown + 分镜表）；
-帧级时间轴。
-**常见坑**：
-- 没对功能清单，凭手感排镜头：核心功能漏拍、动画手法同质化，两种都返工。
-- 开场贪多：开场信息宁少而聚焦，一个主角、一条完整动作弧。
-- 时长预算不含呼吸位：动效排满每一帧，后期逐镜头补 hold 等于全线挪帧。
----
-## 阶段 4：最终素材采集
-**前置条件**：最终设计 spec 与分镜已经放行。共同创作以用户确认作为放行；自主
-自由创作以 Agent 完成一致性检查并记录为放行。此前为 styleframe 采过的少量安全
-截图只能作为方向验证，不得直接替代最终素材。
-**目标**：严格按最终分镜拿到全部镜头所需的真实页面素材，包括全页纹理、元素
-切片和坐标表，为 2.5D 运镜与页面空间动画打地基。
-**具体操作**：
-1. 起产品本地 dev server（桌面端产品则用窗口截图工具，同样出三件套）。
-2. 复制 `assets/scripts/capture-template.mjs` 进项目，改 BASE_URL 与选择器，
-   跑一次产出三件套：
-   - **全页 2x 截图**：viewport 1920×1080、`deviceScaleFactor: 2`；截图前
-     `document.fonts.ready` + 600ms settle，实时同步页额外再等 1.5–2s。
-   - **per-element cutout**：按语义选择器逐元素截图；悬浮件用透明底，需要
-     “卡片飞入空板”的镜头则额外截空 backplate。
-   - **layout.json**：记录每个元素在整页坐标系下的 `{x,y,w,h}` bbox 与每页
-     `pageH`，供飞行目标位、遮罩位置和入场区域直接使用。
-3. 支持按页/按元素增量重采。活数据源先按阶段 0 的数据口径冻结、虚构或脱敏，
-   再进行最终采集。
-**产出**：`public/textures/` 全页图、元素切片与空 backplate；`layout.json`；
-可重跑的 capture 脚本。
-**常见坑**：
-- 在分镜放行前做全量采集：页面状态和素材范围尚未确定，会造成重复采集。
-- 手搓 HTML 复刻既有页面：复刻默认走真实截图；手搓 UI 只用于非复刻场景。
-- 活数据源不锁定，或只截整页不记录 layout 坐标。
----
-## 阶段 5：逐镜头实现
-**前置条件**：需已有可跑的 Remotion 项目（30fps、1920×1080，`src/index.ts`
-注册 Composition；新项目可 `npx create-video@latest` 初始化后把
-`assets/lib/` 组件 copy 进去；走模板路线则直接从 `template/` 起步）。
-**目标**：按帧级时间轴逐镜头落地，每镜头完成即自证质量——
-验收在这个阶段就开始，不留到最后。
-**具体操作**：
-1. **每镜头先解析再三读**（硬规则，不可跳）：用
-   `gallery/api/library.json` 校验卡名和 `style-key` → 读对应配方卡全文 →
-   按卡片“参考实现”定位并读准确的 demo TSX 全文 → copy `assets/lib/`
-   对应组件进项目。同时保存该 style 的 Gallery 参考样片路径，供实现对照和终检。
-   标为“仅供参考，需要自定义实现”的样式不默认推荐，用户明确点名后才可实现并
-   标注风险；标为“缺少预览”的样式不得声称已按动态样片复刻。
-   demo 代码是调校过的参数真相（缓动、时值配比、
-   摘罩时机、已知坑的规避写法都在里面）——允许按目标产品做适配性
-   改动，但配方卡"已知坑/命门"标注的参数不得降档，质量标准只升不降。
-   凭卡名和理解新写＝放弃全部调校积累，实测质感差一档。
-2. **PageCam 是一切"真实页面"镜头的地基**：整页纹理 + 关键帧 2.5D 相机 +
-   页面空间 overlay，children 按页面 CSS px 定位、与 layout.json 共坐标系。
-3. **静帧验收（最高频动作）**：每镜头在计划里写死 2 个验收帧号，
-   完成即跑 `npx remotion still src/index.ts <Comp> out/qa/<name>.png
-   --frame=<N>`，自己肉眼检查构图/穿帮/文字锐度后才算完成。
-   静帧产物按迭代版本归档 `out/qa/`，用户贴帧反馈时可直接对号。
-4. **每轮修改后整片渲染**：`npx remotion render src/index.ts <Comp>
-   out/promo.mp4`，再用 `ffmpeg -i out/promo.mp4 -vf "select=eq(n,…)"`
-   从成片抽关键帧回看。实际形态是"改哪个镜头就 still 哪几帧，
-   然后整片重渲"，成本可接受且杜绝接缝意外。
-5. 像素级自检备小工具：裁剪放大看文字锐度（crop）、两帧像素 diff、
-   量元素 bbox 对构图。
-6. **确定性渲染铁律**：禁 `Date.now()` / `Math.random()` / 无参 `new Date()`。
-   一切伪随机用固定种子（mulberry32/哈希函数，seed 从 index 派生），
-   保证逐帧可复现、渲染间零抖动。
-7. 对照 `references/aesthetic-rules.md` 边做边自检（不等阶段 7）：
-   落地要弹的缓动 y1 必须 >1、光效裁进圆角、3D 下文字糊先查
-   栅格化路径（CSS `zoom` 布局级放大，而非 transform scale）而不是调 DoF。
-8. 指代含糊的用户反馈（"第一个标题"）先确认对象再动手；改错立即整
-   commit revert 重来，不在错误版本上打补丁——每个改动独立 commit
-   以便干净回滚。
-9. **为交付后的动效工作台留好接口**（`references/workbench.md` §2–3）：时间表只写一份
-   （`SHOTS` 是唯一事实源，字幕表 / SFX 钉帧 / 转场点从它派生并 `export`）；镜头的语境级
-   参数（文案 / 颜色 / 字号 / 位置）做成带默认值的 props，节奏命门保持常量；
-   `src/workbench.ts` 里 import 这些表、给每个单元补 `component` / `props` / `schema`。
-   模板路线已自带（`template/src/workbench.ts`），自由创作在时间线定稿后补写，
-   交付前 `cd workbench && npm run parity` 证明拆解无损。
-**产出**：逐镜头 commit；`out/qa/` 静帧档案；每轮全片渲染 mp4；`src/workbench.ts` 清单。
-**阶段输出**：整片渲染视频（每轮迭代一版）+ 关键静帧。自主自由创作不因该输出
-暂停等待确认；用户主动反馈时再纳入下一轮。
-用户可能以"从成片截帧贴图"方式给反馈，双方基于帧评审。
-**常见坑**：
-- 首检交给用户：交付前必须自己抽帧看片，"镜头视角很差，
-  而且有小抖动"这种问题不该由用户发现。
-- 跳过 demo 代码直接写：参数是几轮真实裁决调校出来的，
-  新写的版本几乎必然回踩已知坑。
-- 产品宣传片默认不加手持 shake；相机噪声只在明确追求纪实感时用。
-- 装饰性 glint/泛光群发：批量元素入场靠运动本身。单点高质量光效可做，
-  群发即廉价。
-- 3D 推进下文字发糊：根因是纹理源分辨率/栅格化路径，先查素材链路
-  （2x 纹理 + CSS zoom + 关键元素 4x 单独截图），别先动相机和景深。
-- 飞入动画终点悬空：元素必须落进页面布局的真实槽位（嵌入、归位、
-  排进滚动流），悬浮在页面上方不落地会显得假。
----
-## 阶段 6：声音设计
-**目标**：BGM 定全片能量骨架，SFX 逐拍钉在动效关键帧上，
-音色符合"产品宣传片"片种而非 UI 事件语义。
-**前置条件（最贵的顺序教训）**：**画面时间线锁定后才开始。**
-画面每动一次，钉帧表就要全体重对。若画面确实又改了，收尾动作固定
-包含"全表 SFX 帧号重对"，音画错位是必查项。
-**具体操作**（细节与判例见 `references/sound-design.md`）：
-1. 读 `references/sound-design.md`，从 `assets/audio/sfx/<类别>/` 复制音效
-   （免费商用授权，来源见 `assets/audio/ATTRIBUTION.md`）。音效按场景分 16
-   个类别目录，先按需要的动作定类别（运镜→transition、落地→impact、
-   打字→text、翻页→paper、光效→**light**…），再在类别里挑音色。
-   注意词汇表的 `sparkle` 对应的目录名是 `light/`，库里没有 `sparkle/`。
-2. **BGM**：用户已指定 → 阶段 0 已做节奏分析，此处只做混音
-   （音量压低 ~0.34 给 SFX 留 headroom，interpolate 首尾淡入淡出）。
-   未指定 → 按片种选强鼓点、强节奏的电子底（tech-house 类），判据是
-   "典型的产品宣传视频"气质而不是"好听"；候选曲必须垫进成片试听，
-   单听曲子选型不可靠；`assets/audio/bgm/` 有节奏感强的备选。
-   BGM 的 `<Audio>` 用布尔 inputProp（如 `bgm`，默认 `true`）单独包住，
-   与 SFX 解耦——终渲要从同一时间线出带 BGM / 无 BGM 两版成片。
-3. **SFX 用电影系词汇按镜头语言选**：运镜=whoosh、落地=impact、
-   铺垫=riser、光效=sparkle（目录 `light/`）、转场=transition；
-   禁用游戏音包**音色**（合成器 pluck/bloop、卡通弹跳一耳朵出戏）。
-   注意"禁游戏音"禁的是音色不是动作——画面真有点击/开关/碎裂就该配
-   它的拟音，判别问句见 aesthetic-rules S1。但 **`ui/` 要逐个试听、不能
-   整目录放行**：18 个里只有 `switch-*` 等少数是真实开关拟音，一半以上是
-   合成反馈音（tone/bleep/notification），正属 S1 排除的质感——逐文件
-   取舍表见 sound-design 3.3。`glass/` 是真实碎裂材质音，不在禁列。
-4. **声明式钉帧表集中管理 + 相对钉帧**：单文件 `{ from, src, volume }[]`
-   数组，逐条注释对应的画面动作，每条包 `<Sequence from={s.from}>`。
-   **from 一律写相对表达式**——`SHOTS.x.from + offset`，卡点片写
-   `beatF(n)`——绝不写裸数字帧号。时间线平移时钉帧表自动跟随，
-   免除全表重钉。**长样本（>5s，库里 21 个）必须显式给 `durationInFrames`**
-   ——靠 Sequence 截断而非剪音频文件；漏给会拖到动作结束后还在响。
-   清单与截断判据见 sound-design 4.1。
-5. 连发防机枪感三招：双样本交替、音量阶梯递减（如 pop 六连
-   0.40→0.25）、间隔加速贴动画曲线（密到糊成一片时让声音淡出成 swoosh）。
-6. 通用音之外留"贴画面定制"槽位：有辨识度的画面动作配它自己的拟音
-   （打字画面配键盘声、逐条落入配逐个 pop），泛用 swoosh 盖不住。
-7. 强鼓点 BGM 的片子 SFX 克制：鼓点本身就是节拍音，SFX 只钉画面
-   独有动作，大 slam 只给 2–3 处峰值。
-8. 结尾固定句式：riser（组装段起）→ impact（字标落地，全片音量峰值）
-   → sparkle（余韵，取自 `sfx/light/`）。
-9. **音量按素材实测峰值给，不照抄区间**：`volume` 是乘法系数不是目标
-   音量——常规 0.2–0.6 的前提是素材峰值贴近 0dB。库里 7 个录得轻的素材
-   （峰值 <-12dB，最轻 -24.6dB）给到 1.0 仍比 BGM 低十几 dB，会被鼓底
-   盖住：**首选换同类别里录得好的素材，或预归一化后入库**；必要时可给
-   >1 的增益（Remotion 支持真实放大，但预览钳到 1.0，须以渲染产物验峰
-   防削波）。名单与三条出路见 sound-design 4.1。
-**产出**：带声整片；SFX 钉帧表（相对帧表达式+音源+音量+注释）；
-音频文件入 repo 并记录来源授权。
-**阶段输出**：带声整片渲染。自主自由创作继续进入终检，不暂停等待确认。
-**常见坑**：
-- 画面没锁就铺音效：全表重对的连带成本（见前置条件）。
-- 按 UI 事件语义选音色（合成器 confirmation/minimize 提示音）：片种错位，整批推翻。
-  但别过度矫正到"完全不给交互动作配音"——那违反 S4 拟音优先。
-- 长样本不给 durationInFrames：声音盖过后续镜头（库里 21 个 >5s）。
-- 照抄 0.2–0.6 音量区间不看素材峰值：轻音素材钉了等于没钉。
-- 凭感觉散铺音效不建表：帧号漂移后无法整体平移，也无法和分镜表对照。
----
-## 阶段 7：验收
-**目标**：把贯穿全程的静帧/整片自检升级为一次正式的全片过检，
-同时验证成片是否忠实执行当前模式下确认或记录的产品简报、需求到执行决策表、视觉方向、镜头映射和分镜，
-对照终检与审美准则逐条出报告，然后终渲交付。
-**具体操作**：
-1. 全片渲染最新版，ffmpeg 抽全部关键帧（每镜头至少：入场中、
-   动作峰值、落定后三帧）。配了 BGM 的片子在此处就渲出两版——带 BGM 版
-   和无 BGM 版（保留 SFX），无 BGM 版靠阶段 6 预留的 `bgm` inputProp
-   从同一时间线渲出：写一个 `props-nobgm.json`（内容 `{"bgm":false}`）
-   然后 `npx remotion render … --props=props-nobgm.json`（跨平台可靠；
-   macOS/Linux 也可内联 `--props='{"bgm":false}'`，Windows shell 会剥掉
-   内联 JSON 的双引号，必须走文件）。不另建工程、不用 ffmpeg 后期抽轨。
-   命名区分（如 `promo.mp4` / `promo-nobgm.mp4`）。
-2. **独立终检（必做）**：派一个干净上下文的 subagent 做第三方审查。
-   不给它制作过程中的辩解、修改历史或“应该通过”的暗示，只提供：最新版成片
-   （配 BGM 的片子含两版，供 A8 校验）、
-   抽出的关键帧、创作模式、产品简报、需求到执行决策表、确认或记录的视觉方向/tokens、styleframe 或跳过理由、
-   功能到镜头映射、
-   Gallery 卡名与具体变体、`library.json` 中对应记录、卡片文档定位到的准确
-   demo TSX、Gallery 参考样片或从中抽出的关键帧、最终分镜、选中的镜头卡、
-   `references/final-review.md` 和 `references/aesthetic-rules.md`。
-3. 审查 Agent 按 `final-review.md` 检查产品目标、功能完整性、视觉方向一致性、
-   镜头卡/变体还原度、分镜一致性、数据安全、音画同步和视觉技术质量。逐镜头
-   看帧+看片，给出 "F2 ✗（第 340 帧缺少已确认的知识图谱功能）" 或
-   "Q2 ✗（第 615 帧文字发糊）" 式结论，每条问题附可复核帧号/截图。
-   镜头卡适配不要求和 Gallery 样片像素级相同，但必须保留动作语法、关键时值、
-   已知坑/命门参数和用户点名的具体变体。
-4. 内容级自查：每个镜头问"给了什么新信息"，重复镜头/重复 tagline 删；
-   文案按最终画面重写一遍，纯动画段落也要有解说 caption，不留哑巴段落。
-5. 音画对齐终检：逐条 SFX 对帧回放，确认无错位（时间线若在阶段 6 后
-   还动过，先重对再验）。卡点片按 music-beat-sync.md §5 做渲后回测，
-   全部切点误差 ≤3f 才算过。
-6. 审查报告的修复项回到阶段 3/5/6 小循环：方案或分镜偏差回阶段 3，画面实现
-   问题回阶段 5，声音问题回阶段 6；直到 checklist 通过后终渲出片。
-   终渲重复步骤 1 的双版本渲染——配 BGM 的片子交付带 BGM / 无 BGM 两版，
-   无 BGM 版方便用户后期自配音乐或平台配乐。
-**产出**：独立审查报告（final-review + aesthetic-rules checklist + 帧号证据）
-+ 终渲成片（带 BGM / 无 BGM 两版）。
-**交付物**：审查报告 + 成片两版（带 BGM + 无 BGM）。
-交付后先 `node workbench/scripts/open.mjs <工程目录>` 主动打开动效工作台（浏览器自动
-把成片拆成多轨，用户可视化微调后直接导出；见 `references/workbench.md`），再在最后按
-1-2-3 依次说三件事：① 发布时推荐（非强制）在简介 @ 一下
-skill 作者（三个平台账号都带链接）；② 邀请把成片放到作品展示页（用日常语言
-说，可留自己的账号）；③ 可以导出剪映工程文件（需要则读
-`references/jianying-export.md` 执行）。逐条口径与账号链接见 `SKILL.md`
-「交付收尾」。
-**常见坑**：
-- 把验收当"最后才做的事"：本阶段只是收口。若前五阶段没做静帧自检，
-  这里堆积的问题量会让 checklist 失去意义——验收贯穿全程是定式。
-- 自检报告流于"全部 ✓"：用户会读清屏幕上每个字、会自己截帧对比——
-  报告里每条结论都应附可复核的帧号/截图。
-- 制作 agent 自己出审查报告：确认偏差不可避免，独立 subagent 审查
-  不可省略。
-- 只查“好不好看”不查“是否符合当前模式的制作基准”：功能漏拍、视觉方向漂移、
-  镜头变体用错和未经确认的数据都属于终检失败。