@biunow/agent-biuart 0.0.0-stage → 0.1.0

package/skills/biuart/references//345/212/250/347/224/273/350/257/255/346/263/225/y5_kinetic_type.md

@@ -0,0 +1,158 @@
+# y5 · 动态文字排版 / 信息图动效（kinetic typography）
+
+> 一句话语法：**字就是演员——每个关键词踩一个重音砸进来，主词大到一眼读完，其余的字从「槽」里升起给耳朵对位；画面里永远只有一个焦点，镜头和底纹一直在动，字落定后不动。**
+
+血统：Saul Bass《North by Northwest》（1959）片头被普遍认作第一次在长片里大规模用动态文字；2008 年后 YouTube 上的歌词/台词 kinetic type（After Effects 一代）把它变成解说视频、清单、语录、数据开场的标准语法。
+
+## 起手必查
+
+1. **先确认这段该让字当主角。** 只有清单、金句、数字、章节卡时用；整段超过 30–60 秒全是字，就换语法，或者每 2 页插一页图、证据物（截图、代码卡、聊天气泡）。
+2. **数字数。** 主词 ≤4 个字，辅句 ≤14 字；同一时刻只有一个东西在入场。超了就拆页，不缩字号硬塞。
+3. **同一页型连续不超过 3 页。** 「大字＋辅句＋左上标签」连翻 4 页就是幻灯片；中间插一页数字砸入、一页证据物，或一次冲进色块的转场。
+4. **每个落点写成拍号或口播里的词。** 不在节拍网格、也不对词的落点，删掉或挪上去。
+5. **字落定后不动。** 动感交给拍点微冲、换页、证据物入场，主词不漂、不呼吸。
+
+---
+
+## ① 适用场景
+
+**用它：**
+- 解说/清单/「X 个阶段」「3 个理由」类的开场与章节卡：信息是**结构**（几个、哪一个、从什么到什么），不是画面。
+- 语录、金句、一句话结论：让观众「看着读」比「听着记」更牢。
+- 数字讲解：一个数字一个镜头，数字本身做主角。
+- 口播里有明确的重音词（「不是写代码，是**说需求**」）。
+
+**别用：**
+- 讲故事、讲情绪起伏 → 没有人脸，观众很难共情（用 y4 角色）。
+- 长段解释性口播配满屏字 → 观众只会读不会听，读也跟不上。整片超过 30–60 秒全是动态字会累，用它做开场、章节卡、结论卡就好。
+- 字很多的列表（>5 条）→ 改成静态信息图慢慢讲。
+
+## ② 画面构成
+
+**构图**：一屏一个主词。主词左对齐压在画面左侧 1/3–1/2（或镜像到右侧），辅句紧贴主词下方，另一侧放一个「证据物」（代码卡、聊天气泡、清单）。上角放小标签（「阶段 01」）和进度轨。四周至少留 130px 边距。
+
+**字号阶梯（示范片）**：主词 340px（普惠体 115 Black）：辅句 96px（105 Heavy）：标签 40px（85 Bold，字距 6px）≈ **3.4 : 1 : 0.4**。主词要在 0.3 秒里被读完，所以主词只给 2 个字。
+
+**配色**：每个章节一个整屏底色，换章节＝换底色（色彩本身就是章节号）。
+
+| 镜头 | 底色 | 主词 | 强调 |
+|---|---|---|---|
+| 标题 | 黄 `#FFD23F` | 墨 `#111111` | 珊瑚圆 `#FF5A36` 里的白「3」 |
+| 01 补全 | 珊瑚 `#FF5A36` | 白 | 黄荧光笔 `#FFD23F` |
+| 02 对话 | 藏青 `#14213D` | 黄 | 黄荧光笔、蓝气泡 `#3A86FF` |
+| 03 代理 | 米白 `#F4EFE6` | 墨 | 珊瑚下划线、绿勾 `#2BB673` |
+
+全片 4 个底色 + 墨 + 白，强调色永远只有一个。
+
+**形状语言**：字是最大的形；辅助形状只用圆角矩形（卡片 r=26、气泡 r=30、键帽 r=22）、正圆（数字底）、斜切色块（荧光笔，斜率 0.18）。背景是 64px 间距的点阵（不透明度 6–10%）。不用描边字、不用投影字（唯一的投影是卡片下 8–18% 的偏移阴影）。
+
+## ③ 运动轨迹
+
+**入场（按「重要性」选方式）**
+
+| 元素 | 方式 | 曲线与时长 |
+|---|---|---|
+| 主词 | **砸**：从 1.7 倍缩到 1，前 0.06s 不透明度 0→1 | 欠阻尼弹簧 `1−e^(−10t)·cos(2π·2.2t)`，过冲约 8%，≈0.35s 停稳 |
+| 标题首词 | 砸＋旋转回正 −8°→0 | 同上 |
+| 辅句、标签 | **槽里升起**：字在基线下的遮罩里从 +1.2 倍字高推到 0 | `expoOut`，0.30–0.35s |
+| 数字/图标/气泡/键帽 | **弹入**：0→1 缩放 | `backOut`，s=2.6–3.0（过冲 17–20%），0.30–0.42s |
+| 卡片 | **滑入**：从 +700px 或下方 +260px，带 3.4° 旋转回正 | `expoOut` 0.40s |
+| 打字 | 按字符截断 | 0.5s 打完 13 个字符（26 字/秒），光标 2Hz 闪 |
+| 代码补全 | 灰字**0 帧**闪现（补全本来就是瞬间出现的）→ 按 Tab 变实色 | 键帽按下压 14%，e^(−18t) 回弹 |
+| 荧光笔 / 下划线 | 从左往右刷出 | `expoOut` 0.30s，在字出现后 1–3 个八分音符再刷 |
+| 关键词放大 | 到强调拍放大到 1.35 倍并钉住，荧光笔跟着放大 | 弹簧 freq 2.5 / decay 9，和配合的动作（按 Tab、打勾）同一拍 |
+| 巨型阶段数字 | 900px、透明度 5–13%、压在画右下、从 1.35 倍落到 1 后斜向慢漂 14/10 px/s | 弹簧 freq 2 / decay 8 |
+| 打勾 | 勾的笔画按弧长画出，框同时 1→1.25→1 | 0.22s；删除线晚 0.08s 再划 |
+
+**出场**：比入场快、用加速曲线（`expoIn`），时长 0.18s，元素之间错开 0.03s，同时缩到 0.6、下落 60px、变透明。**退场比入场快**——观众的注意力在退场开始前就已经走了。示范片标题段最后一拍：除「3」以外全部退场，只剩下一个要冲进去的形。
+
+**错开（stagger）**：同一行的词错开一个八分音符（120 BPM 下 0.25s）；同一组小元素（三个勾）也是一个八分一个。
+
+**持续运动（字落定后不动，动的是别的）**
+- 镜头微漂：两路正弦，振幅 5px，周期约 7s / 2.7s；极慢旋转 ±0.5°。
+- 拍点微冲：每个四分拍整屏放大 1.2%，`e^(−25t)` 衰减（≈0.12s）——画面跟着鼓「呼吸」。
+- 背景点阵斜向平移 36px/s。
+- 结尾一拍：镜头拉远 6%（`expoOut` 0.5s），所有东西缩小一点＝「收束」。
+
+**原片对照（本次抓取的两支 YouTube 歌词 kinetic type 转载，30fps）**：相邻帧完全静止只占 10.3%（DISCORD）/ 21.2%（Charlie Puth），七八成时间画面在动——和 storytime 的 71% 静止正好相反；大的视觉事件（整屏变化 >1.5% 的峰）平均 0.66s / 0.83s 一个，接近**一拍一个**（两支曲速约 105 / 99 BPM，一拍 0.57 / 0.60s）。示范片的大事件密度是一个八分一个（0.25s），比歌词片密一倍——解说开场可以这么密，长片要放到一拍一个。
+
+## ④ 转场（示范片 3 种＋常用 2 种）
+
+1. **穿越放大（zoom through）**：镜头冲进上一屏的某个形（「3」的珊瑚圆），形的颜色＝下一屏的底色，冲满屏后下一屏从 1.25 倍落回 1。前 55% 时间 `expoIn` 放大到 30 倍，后 45% `expoOut` 落定。`TRANSITIONS.fillZoom`（实验时叫 zoomThrough，收进库后改名，免得和 3b1b 的镜头穿越撞名），参数 `cx, cy, k, maxZoom, fill`。
+2. **色带擦除（bands）**：三条斜切色带（黄→白→藏青）接力从左扫到右，错开 12%，最后一条是新画面的底色，色带后面露出新画面。0.5s `expoInOut`。`TRANSITIONS.bands`。
+3. **推（push）**：新旧一起平移，像在一张长画布上滑到下一块。0.35s `expoInOut`。`TRANSITIONS.push`。
+4. **遮罩擦出（mask wipe）**：一个形（圆、矩形条、字本身）当遮罩从小长大露出新画面。可用 `skill` 原有的 `iris`。
+5. **字变形 / 字当转场**：上一屏的某个字放大成整屏的色块，或者一个字甩出画面带走旧画面。
+
+**对位技巧（本次最值钱的一条）**：引擎里转场从新段的 `t0` 开始，所以要让「新画面露出来」的那一帧正好落在小节线，段的起点 = **小节线 − 转场的揭开点 × 转场时长**。示范片：fillZoom 揭开点 p=0.55、时长 0.45 → 起点 1.75（揭开在 2.00）；bands 揭开点 ≈0.6、0.5s → 起点 3.70；push 用 expoInOut，肉眼的「到位」是位移 90% 那一刻（p≈0.58）而不是 p=1 → 起点 5.80（第一版按 p=1 算起点 5.65，审片量到「推完比重拍早 8 帧」）。所有镜头内的落点也写成拍号 `KT.b(n)`，不写秒。
+
+## ⑤ 节奏与文字
+
+- **120 BPM，4 小节＋1 拍收尾（8.5s），每小节一个镜头**（标题 / 阶段一 / 阶段二 / 阶段三），每个镜头里：第 1 拍主词砸（＋背景巨型阶段数字）、第 1.5 拍证据物、第 2 拍辅句、第 3 拍证据物动作、第 3.5 拍关键词放大＋高亮、第 4 拍留白或退场；最后第 16 拍（8.0s）收尾重拍，再静住 0.5s。四个镜头同一套拍位，只换左右和内容——观众第二个镜头起就「知道下一下在哪」，这正是节奏感的来源。
+- **主词落在强拍（每小节第一拍）**，配低频冲击；小元素落在八分音符上，配 pop；转场前 0.3s 一段上扬噪声把耳朵带到下一小节。
+- 每个画面落点都有一个声音，每个重音都有一个画面——示范片音效表在实验归档的 `build_y5.py`（没收进 skill），和 `scenes/*.js` 的拍号一一对应。
+- **停留时间够读**：英文视频文字指南给的下限是 13 字符/秒（SSW）；中文没找到一手标准，按字幕行业的经验上限 7–9 字/秒算（未核实，当经验值用）。主词 2 字至少停 0.5s，辅句 7–8 字至少停 1.0s。
+- 和口播对位时：主词＝口播里的重音词，**画面宁早勿晚、最多早 1 帧**——人对「声音比画面早」比「声音比画面晚」敏感得多（广播声画同步容差 EBU R37 是声音领先 ≤40ms、落后 ≤60ms）。
+
+## ⑥ 代码实现要点
+
+> 收进 skill 后（2026-10-04 v0.4）：本卡「新写」里的通用函数已统一进 `scripts/engine/lib/`（名字已换成统一后的 MO / CAM / DG / TY / CH / UI / CL / TOON），示范片自己的代码在 `scripts/engine/demos/y5_kinetic_type/`。库速查和「怎么为一段口播选语法」见 `references/09-视频动画语法.md`。
+
+- **复用 skill**：引擎（段落表、转场新旧两层、`renderFrame`）、`render.py`、`U.clamp / lerp / rng`、`PAINT` 不需要（这风格不用纹理）。
+- **engine 改动（已并进 skill 引擎）**：`window.BPM` 可配（默认 128，本片 120）；任何段可写 `dur` 秒；转场 `punch:0` 可关（本片用自己的拍点微冲，冲在拍上，不冲在转场起点上）。
+- **新写、现已统一进库**（`lib/motion.js` / `typo.js` / `camera.js`，转场进 `transitions.js`）：
+  - 缓动：`expoOut / expoIn / expoInOut / quintOut / backOut(p, s) / spring(t, freq, decay) / settle(t, amp, freq, decay)`。
+  - 字：`TY.text`（缩放旋转以任意点为轴、描边、字距）、`TY.width`、`TY.rise`（遮罩升起）、`TY.pop`（弹入）、`TY.typed`（打字）、`TY.marker`（荧光笔斜切块）、`TY.underline`。
+  - 镜头：`CAM.with(c, {x, y, z, r}, fn)`、`CAM.drift`。
+  - 转场：`fillZoom`、`bands`、`push`。
+- **本片 `y5_kinetic_type/kinetic.js`**：`KT.b(n)` 拍号、`KT.SZ` 字号阶梯、`KT.bump` 拍点微冲、`KT.slam` 主词砸入、`KT.dots` 点阵、进度轨（画在 `GLOBAL_OVERLAY` 固定层，值只由全片时间决定——skill 02 号「连续叙事锚」的用法；第一版画在各段里，推页时跟着页面跳）、`KT.key / keyMarker`（关键词先升起、到强调拍放大并钉住）、`KT.bigNum`（背景巨型阶段数字）、`KT.cam`。
+- **中文字体**：示范片用阿里巴巴普惠体 3.0 四个字重（Black/Heavy/Bold/Medium）做；开源版因字体许可换成思源黑体 Noto Sans SC 900/800/700/500，family 名沿用 `PuHui-*`，GB2312 全量子集（`scripts/font_subset.py --gb2312`），换题目一般不用重做。
+- **音乐（实验归档里的 `build_y5.py`，没收进 skill）**：numpy 合成鼓（kick 每拍、clap 2/4 拍、hat 反拍）＋贝斯（每小节一个根音的八分音符）＋事件音效（主词＝boom、小元素＝pop、打字＝click、打勾＝升调 pop、转场前＝riser）。
+
+## ⑦ 代表作品与一手参考
+
+- Saul Bass 片头档案（Art of the Title）：https://www.artofthetitle.com/designer/saul-bass/
+- 维基「Kinetic typography」（motion typography / fluid typography 两类、Bass 是长片先驱）：https://en.wikipedia.org/wiki/Kinetic_typography
+- School of Motion《Kinetic Typography in After Effects》Part 2（帧数：小词滑入 4 帧、主词甩入 6 帧＋2 帧过冲回正、镜头推 6 帧＋2 帧回拉；「镜头要晚一点动，像是被声音推着走」）：https://www.schoolofmotion.com/blog/kinetic-typography-after-effects-part-2
+- School of Motion Part 3（下落要加速不要缓停、撞击时整个合成放大再回 100%）：https://schoolofmotion.com/blog/kinetic-typography-after-effects-part-3
+- Dan Ebberts 惯性回弹表达式（`amp·sin(2πft)/e^(decay·t)`，默认 freq 3 / decay 5）：http://www.motionscript.com/articles/bounce-and-overshoot.html
+- Lee, Forlizzi, Hudson,《The Kinetic Typography Engine》（UIST 2002，动态字表达情绪与语气）：https://dl.acm.org/doi/10.1145/571985.571997
+- 视频文字停留时间：https://www.ssw.com.au/rules/post-production-do-you-give-enough-time-to-read-texts-in-your-videos
+- 本次实测的两支转载：DISCORD [Kinetic Typography] https://www.bilibili.com/video/BV1ts411S7Xa ；Charlie Puth – We Don't Talk Anymore (Kinetic Typography) https://www.bilibili.com/video/BV1by4y1r74Y
+
+## ⑧ 最容易做错的 3 件事
+
+1. **所有字一样大、一起动。** 没有层级就没有焦点，观众不知道先读哪个。主词与辅句至少 3:1，同一时刻只让一个东西在「入场」，其余全部静止。
+2. **字一直在漂。** 字在读的时候不能动（会读不进去）。持续运动交给镜头微漂、拍点微冲、背景点阵；字砸进来 0.35s 后就钉住。
+3. **动画不踩拍，或者踩在转场起点上。** 转场的第一帧不是重音，「新画面露出来」那一帧才是。把段起点往前挪「揭开点 × 时长」，再把镜头里每个落点写成拍号；节拍网格以外的落点每多一个，整片就散一分。
+
+---
+
+## 示范片
+
+- 成片：`scripts/engine/demos/y5_kinetic_type/`（渲染 `render.py --film demos/y5_kinetic_type`）（8.5s，60fps，合成配乐 120 BPM）；每镜一帧总览：`assets/动画语法/y5_kinetic_type_总览.jpg`
+- 工程：`scripts/engine/demos/y5_kinetic_type/`（`eras.js`、`kinetic.js`、`k1_title.js / k2_complete.js / k3_chat.js / k4_agent.js`），通用部分在 `scripts/engine/lib/`
+- 镜头表：K1 标题「AI 写代码 的 ③ 个阶段」→ 穿越放大 → K2「补全」（代码卡＋灰字补全＋Tab）→ 色带擦除 → K3「对话」（你一句、它一整段）→ 推 → K4「代理」（TODO 三条自己打勾）＋进度轨满格
+
+## 审片返修（独立 agent 只看成片）
+
+审片结论：「开头 0–2s 是标准的 kinetic type，『3』的圆冲进镜头变成下一段底色是全片最好的设计」「声画对位几乎完美，所有视觉事件都落在 120BPM 网格上、和底鼓同一帧」。「必须改」5 条，处理如下：
+1. **辅句停留太短**（0.6–0.9s）→ 辅句提前一拍出、压到 6–7 个字（「它补完下一行」「一句话换一整段」「你只说要什么」），可读时间 1.0–1.5s（阶段 2 仍偏紧，正式片配口播就够）；全片加 0.5s。
+2. **阶段 2 辅句快撞上 AI 面板**（14px）→ 辅句变短、右对齐，间距 >180px。
+3. **推页早了 8 帧、进度轨跟着跳** → 段起点按 90% 位移重算（5.80）；进度轨移到 `GLOBAL_OVERLAY` 固定层，颜色在揭开那一帧换。
+4. **阶段段落不够 kinetic**（编号太小、关键词只高亮不放大）→ 加背景巨型阶段数字 1/2/3；关键词到强调拍放大 1.35 倍。
+5. **结尾没有收尾的一击、打完勾全变灰** → 加第 16 拍收尾重拍（镜头拉远 6%＋3.5% 冲击＋低频＋高音铃），勾完的字变绿不变灰，内容整体下移 70px 填掉底部空白。
+另外：代码卡改用等宽字体（Menlo）。
+没采纳的：「把每段延长到 2.5–3s、全片 10–11s」——示范片要求约 8 秒，用压字数代替延时长。
+
+## qa.py 数字（返修后，`uv run scripts/qa.py --project scripts/engine --film demos/y5_kinetic_type`）
+
+| 段 | 运动% | 静止帧对% | 跳变 | 均/峰 ms | 确定性 |
+|---|---|---|---|---|---|
+| k1_title | 2.37 | 0.0 | 1（t=1.63，标题退场） | 1.0/1.6 | ✓ |
+| k2_complete | 2.39 | 0.0 | 0 | 1.5/3.2 | ✓ |
+| k3_chat | 2.59 | 0.0 | 1（t=4.54，AI 气泡长出） | 1.6/2.2 | ✓ |
+| k4_agent | 2.88 | 0.0 | 3（t=6.29 Agent＋任务卡；t=8.00/8.04 收尾重拍） | 1.6/2.0 | ✓ |
+
+转场冒烟（整帧峰值）：fillZoom 6.8ms、bands 4.8ms、push 3.8ms。5 个跳变逐个看过帧，全是有意的拍点重音（qa 文档：「有意的节拍闪不算错」）。kinetic 的跳变就该落在拍上——可以拿跳变时刻去对节拍网格，对不上的才是 bug。
+返修后逐帧扫描四条边：0 帧露黑。

package/skills/biuart/references//345/212/250/347/224/273/350/257/255/346/263/225/y6_presenter_explainer.md

@@ -0,0 +1,24 @@
+# Y6 · 讲解员式财经科普
+
+一个卡通讲解员在纸面、图表和关键词之间串联信息。适合商业史、产品机制和带情绪反应的知识讲解。参考代码在`scripts/engine/reference_films/spacex/spacex_lin/`；这是第9种语法卡，目前没有独立参数化片段，也不附角色sprite。
+
+## 起手必查
+
+- 分镜先分配版式：侧身讲解、满屏数字、左右对比、角色进入图里、反应特写。不要全片固定人左图右。
+- 生帧至少备全身和胸像两档景别；坐姿和倚靠需要真实的对应帧。
+- 每段第一个`cast`关键帧显式给出`x`和`s`，防止跨段继承造成回归。
+- 嵌套绘制的透明度用`*=`，保留外层淡出。
+- 顶栏年份、字幕和段标题读同一个时间源。
+- 第一版即跑`qa.py`文字框景；浅底无字幕成片再跑`subzone_gate.py`。
+
+## 帧与动作
+
+角色采用AI生成帧，代码控制脚底锚点、位置、大小和换帧。姿势硬切配轻微弹出，避免不同轮廓溶解形成双影。说话和闭嘴随口播时间切换；停顿时停止口型，走路使用完整步态帧。姿势的身高按中位数校齐；反应特写用胸像素材，不把整帧截图硬放大。
+
+数字在口播念到时落定。计数过程中不要提前带「超过」「+」等断言；强调圈在数字落定后出现。高光后的停顿要在脚本和口播阶段留出来。
+
+## 参考实现
+
+`common.js`提供`presenterFrame`、`drawFigure`、`hud`、`yearAt`、`popK`和`L.cast`。`prep_presenter.py`演示切帧及脚底锚点。转场`transitions/lin_page.js`只翻页面，讲解员和顶栏可跨页连续。
+
+已知限制：人物遮字、角色被推镜裁掉仍需肉眼审片；参考代码中的整帧位图推近容易裁切，新片应优先使用场景相机。素材和口播需自行提供，不能直接把本卡当作完整成片模板。

package/skills/biuart/references//345/217/243/346/222/255API.md

@@ -0,0 +1,125 @@
+# 火山豆包声音复刻 2.0 · 接口细节与实测记录
+
+历史接口记录来自2026-09-13，查询段更新于2026-09-18；新用户先按capabilities.md配置，服务限制以调用时实际响应为准。官方文档：火山引擎文档中心「豆包语音」库（LibraryID 6561）。
+
+## 鉴权
+
+旧版控制台（APP ID + Access Token）：
+
+```
+X-Api-App-Id:      {APPID}
+X-Api-Access-Key:  {Access Token}
+X-Api-Resource-Id: volc.megatts.voiceclone   # 训练 / 查询
+                   seed-icl-2.0              # 合成
+X-Api-Request-Id:  {uuid}
+Content-Type:      application/json
+```
+
+新版控制台改用 `X-Api-Key`（API Key 管理里拿）。旧版官方说会逐步下线。
+
+## 三个接口
+
+| 用途 | 路径 |
+|---|---|
+| 训练音色 | `POST /api/v3/tts/voice_clone` |
+| 查询状态 | `POST /api/v3/tts/get_voice` |
+| 合成 | `POST /api/v3/tts/unidirectional`（HTTP chunked 流式） |
+
+Host 一律 `https://openspeech.bytedance.com`。
+
+### 训练
+
+```json
+{
+  "speaker_id": "S_xxxxxxxx",
+  "audio": { "data": "<base64>", "format": "wav" },
+  "source": 2,
+  "language": 0,
+  "model_type": 5
+}
+```
+
+- **`model_type: 5` 才是复刻 2.0。** 不传或传别的值会训成 1.0。
+- **请求体是单个 `audio` 对象，不是 `audios` 数组。** v1 接口用数组，v3 改了；
+  传数组会报 `45000000 add unmapped key audios`。
+- 可选：`text`（参考音频对应文本，服务端做 WER 校验，差太多返回 `45001109`）、
+  `enable_audio_denoise`（降噪，会损失相似度）、
+  `disable_volume_normalization`（关音量归一化，合成音量更贴参考音频）。
+- 返回 `status`：0 NotFound / 1 Training / 2 Success / 3 Failed / 4 Active。
+  **2 和 4 都可以直接合成。**
+- 返回里 `speaker_status` 是个数组，同时含 1.0 和 2.0 两版；
+  `model_type: 5` 那条才是 2.0，各自带一个一小时有效的 `demo_audio` 试听链接。
+
+### 查询（2026-09-18实测）
+
+v3 `get_voice`请求体使用单数`{"speaker_id":"S_xxxxxxxx"}`，不是`speaker_ids`数组。多个槽逐个查，HTTP错误必须显式报出，不能当成音色不存在。`koubo.py voices`已按此修正。
+
+### 合成
+
+```json
+{
+  "user": { "uid": "koubo" },
+  "req_params": {
+    "text": "...",
+    "speaker": "S_xxxxxxxx",
+    "model": "seed-tts-2.0-expressive",
+    "tone_fidelity": true,
+    "audio_params": { "format": "wav", "sample_rate": 48000, "speech_rate": -20 }
+  }
+}
+```
+
+响应是流式的，每行一个 JSON，音频在 `data` 字段里按 base64 分片，拼起来就是完整文件。
+
+## 两个反直觉的参数位置
+
+1. **`speech_rate` 必须放在 `audio_params` 里。** 放 `req_params` 顶层会被**静默忽略**——
+   不报错，返回 200，音频正常，但语速纹丝不动。
+   实测 `audio_params.speech_rate = -50` 让同一句从 10.36s 变 21.53s（正好 2 倍）。
+   取值 `[-50, 100]`，0 默认，100 = 2.0 倍速，-50 = 0.5 倍速，线性。
+   同样被静默忽略的还有 `speed_ratio`（无论放哪层）——那是别的产品线的参数名。
+
+2. **`tone_fidelity` 放 `req_params` 顶层**，不在 `audio_params` 里。仅 2.0 音色生效。
+
+## 采样率
+
+`sample_rate` 支持 `[8000, 16000, 22050, 24000, 32000, 44100, 48000]`，**默认只有 24000**。
+贴回 48k 剪辑工程一定要显式传 48000，否则听感发闷。
+`ogg_opus` 只支持 48000。流式场景官方建议用 pcm，不建议 wav。
+
+## 其他限制
+
+- 参考音频 **10MB 上限算的是原始文件，不是 base64 后**（实测 9.16MB 的 wav 能过）。
+  支持 wav / mp3 / ogg / m4a / aac / pcm，pcm 仅 24k 单声道。
+- 合成文本单次建议 < 300 字（约 60 秒音频），长文要自己切分再拼。
+- 音色槽位每个 15 次训练机会，可重复覆盖训练。
+- 「音色升级」接口（`/api/v3/tts/upgrade_voice`）只是 V1→V3 迁移，
+  **不能给已有音色追加参考音频**。想换参考音频只能拿同一个槽位重训。
+
+## 常见错误码
+
+| 码 | 含义 | 怎么办 |
+|---|---|---|
+| `45000000` | 请求体字段不对 | 看 message 里的 unmapped key |
+| `45001122` | `no speaker detected` | 参考音频里没人声。先查平均电平，低于 -36dB 基本就是底噪 |
+| `45001109` | `WERError` | 传的 `text` 和音频内容对不上，去掉 text 或改准 |
+| `45000030` | `resource not granted` | 这个 Resource-Id 对应的服务没开通 |
+
+## 网络
+
+`openspeech.bytedance.com` 是国内接口。如果本机开着 socks 代理，
+**光给 requests 传 `proxies=None` 挡不住**——它仍会读环境里的 `ALL_PROXY`，
+表现为间歇性 `SSL: UNEXPECTED_EOF_WHILE_READING`。
+受影响环境可配置`bindings.volcengine.trust_env=false`；默认遵从环境代理，不对所有用户强制绕过。
+
+## 关于「参考音频要喂多长」
+
+历史听选中，较长的干净口播参考比三十秒更像原声。这是单一声音的经验，不是所有音色的统一默认；以用户自己的样本试听和当前服务限制为准。
+
+我这边做过一次时长梯度实测（15/30/60/120/200/400 秒嵌套取样，每档合成 3 次），
+用基频中位数和频谱质心跟真人原声比，各档差异（1.7%~8.5%）和同一档三次之间的
+标准差（1.7~9.5）是同一量级，**在这两个指标上分不出高下**。
+
+但这不构成反驳——这两个指标只覆盖音色的音高和明暗，
+**完全不覆盖韵律、停顿、气口、语气**，而那些恰恰是「听起来像不像本人」的主要成分。
+指标测不出差异，不等于没有差异。以耳朵为准。

package/skills/biuart/references//350/211/262/346/235/277.md

@@ -0,0 +1,38 @@
+# 色板：一支片一套色
+
+镜头表表前的「色板」一行，从这里挑一套写名字，或者按文末的规则自己定 3–6 个色值。所有参数化片段的 spec 写同一个 `"theme"`，scenes 里也只用这几个色（加减明暗、透明度可以，别引入新色相）。
+
+## 先说禁区
+
+**蓝紫渐变底、深紫星空底、霓虹青紫光效、紫色毛玻璃**：作者原话「我们需要规避下蓝、紫渐变的垃圾配色，这种非常ai slop」。这几样是 AI 做动画最常落进去的默认色，观众一眼就读成「AI 做的」。
+
+`deliver.py` 会量出来：一帧里 30% 以上是蓝紫（色相 225°–300°、饱和度 ≥0.30）就算蓝紫帧，蓝紫帧占全片 30% 以上红灯，不出片。题材本身就要蓝紫时（用户点名的赛博朋克紫、梵高星月夜这类风格画面），交付时加 `--allow-blue-purple "理由"`，降为黄灯，理由写进交付说明的事实段。
+
+海军蓝平涂（色相约 210°，见下面 navy）不在禁区里：它是有意图的单一底色，不是渐变也不发光。
+
+## 八套现成色板
+
+每套 6 个键：`bg` 底、`surface` 卡片／纸／面板、`ink` 主字、`sub` 次字和细线、`accent` 主强调、`accent2` 副强调。片段 spec 里写 `"theme": "wood"`，或者写成对象 `{"name": "wood", "accent": "#B8452A"}` 只改其中一个键。
+
+| 名字 | 适合 | bg | surface | ink | sub | accent | accent2 |
+|---|---|---|---|---|---|---|---|
+| `paper` 纸本 | 人文、历史、读书、解释一个道理 | #F3EDE2 | #FBF8F2 | #1B1A17 | #6B655B | #C8402F | #2F5D62 |
+| `poster` 海报黄 | 观点、冲突、要一句话砸进去的科普 | #FFD23F | #FFF6D6 | #111111 | #4A4433 | #FF5A36 | #14213D |
+| `ink` 深墨 | 科技、夜景、严肃话题 | #121417 | #1E2226 | #F2EFE8 | #A39E93 | #F2B33D | #5FB3A1 |
+| `navy` 海军 | 产品、数据、手机与电子设备（平涂，不渐变） | #0D1B2A | #16293D | #EEF3F6 | #8FA3B3 | #5CC8E0 | #F2A93B |
+| `bauhaus` 包豪斯 | 设计、结构、几何、流程 | #EFE9DD | #FFFFFF | #111111 | #555555 | #D62828 | #1D4E89 |
+| `snow` 雪原 | 冬天、医疗、清洁、实验室 | #E9EEF0 | #FFFFFF | #1F2A30 | #5E6B72 | #D9482B | #3E7C8C |
+| `wood` 暖木 | 生活、厨房、手作、家里的事 | #EDE3D1 | #F7F1E6 | #2B2622 | #7A6E62 | #C4552D | #3F5B4B |
+| `chalk` 黑板 | 课堂、推导、公式、讲题 | #23302B | #2E3D37 | #F1EFE6 | #A9B3AA | #F4D35E | #E87D5A |
+
+## 自己定一套
+
+- 3–6 个色：一个底，一个面，一个主字，一个次字，一两个强调。强调色一镜里只用来指一个东西。
+- 底色先定：亮底（纸、雪、木）还是暗底（墨、海军、黑板），全片不在亮暗之间来回跳。
+- 色值避开蓝紫区：色相 225°–300° 且饱和度 ≥0.30 的色不当底、不大面积用。`storyboard_lint` 查色板里的色值，落在这一区红灯。
+- 不用渐变底，不加霓虹外发光。要层次就用纸纹、颗粒、明暗两层平涂。
+- 有真实素材（截图、照片）时，从素材里取一两个色当强调，底色仍然用这一套。
+
+## 自检
+
+交付前把抽帧排成一排看：底色是不是从头到尾同一个亮度区间，强调色是不是只有那一两个，有没有哪一镜突然冒出白底柱状图、紫色星空、霓虹边框这种「别的片子的颜色」。有，就把那一镜按色板重画。

package/skills/biuart/references//350/247/222/350/211/262/347/262/276/347/273/206/345/272/246.md

@@ -0,0 +1,61 @@
+# 角色精细度：要么画到位，要么不出脸
+
+画面里只要出现人、拟人角色、吉祥物、机器人，或者长了脸的东西，开工前读这一页。作者看过多个模型做的片子，原话是：
+
+- 「很多视频里用到的小人和机器人角色都太差了，我们应该自己来定义一部分的精细度和用力的要求」
+- 「颜色和人的风格形象都有些ai slop」「金币和小人形象的界面有些ai slop」
+
+**粗糙的角色比没有角色更差。** 观众看见一个圆头豆豆眼的小人，第一反应是「AI 做的」，后面讲得再好也被这一眼拖下去。
+
+## 先选路：三条通用路线与两张平面卡通卡的窄例外
+
+镜头表表前的「角色」一行，写的就是这里选了哪条：
+
+| 角色行写 | 什么时候走 | 怎么做 |
+|---|---|---|
+| `帧库 <路径>` | 有生图能力（当前会话有生图工具，或用户给了角色图） | 按 `references/10-角色.md` 的 B／C 法做 AI 生帧帧库，过下面的「交付线」 |
+| `只出手和背影` | 没有生图能力，但故事需要一个人 | 只画手（握着物、指着物、把物放进口袋）、背影、剪影、过肩；脸不出画 |
+| `无` | 故事可以只靠物讲 | 物本身做主角：一块电池、一袋面包、一本书，靠形状、颜色、动作讲，不给它加脸 |
+
+**37/52号平面卡通例外。** 明确选择Rick & Morty或南方公园方向时，可按对应卡设计原创语义SVG角色。镜头表写`画风：37_rick_morty …`或`画风：52_south_park …`，角色写`角色：原创语义SVG …`。这是手段的例外，不是免检：核剪影、身份、部件层级、接触、表情与动作；平涂、简化关节按该风格判断，不强加下面第2/4/5条的写实结构、双层明暗与三处材质细节。真人/写实或其它画风不适用；仅写「SVG」不启用例外。南方公园研究卡已有单场景原型，新角色和新题材仍需重新设计与验证。`y4`依旧只接受帧库，SVG例外不能绕过其输入契约。
+
+**停用的**（代码画出来就是 AI 味，lint 和评审都会拦）：
+
+- 通用 Q 版小人：圆头、豆豆眼、腮红、没脖子、身体是一个圆角矩形。
+- 白壳机器人：白色圆壳、蓝色面罩、一根天线，悬浮或喷火。
+- 长了脸的东西：带笑脸的金币、会皱眉的锂离子、有眼睛的小球、表情包式的电池。
+- 火柴人、哈林小人，用来演故事时（白板语法里画一个示意符号不算演故事）。
+
+**例外：全片主角是一个拟物角色。** 一支会跳的画笔、一盏台灯，作为整支片的主角，按「三方向硬门」出过造型、用户挑定了，可以有脸和表情：作者做宣传片时，无脸画笔被判「太正式了太无聊了」，改成有脸的卡通画笔才过。区别在用力：主角是设计出来的（身份道具、身体结构、表演），过下面的交付线；停用的是顺手给金币、小球、离子画上的表情包脸。
+
+`y4` 片段只接受帧库（`data.character.frames`），没有帧库启动就失败。引擎里代码画的角色（`lib/toon.js` 的 neutral／bun／author）不再给成片用。
+
+## 交付线：帧库角色要过这八条
+
+做出来先截一张角色特写（放大到 2 倍），对着下面逐条打勾，写进交付说明。过不了的，回到生图那一步重做，或改走「只出手和背影」。
+
+1. **剪影认得出**：把角色涂成纯黑，还认得出是谁、在做什么动作。圆＋圆角矩形拼出来的人认不出。
+2. **比例有骨架**：有脖子、肩膀、手肘、手腕；头身比按画风定，同一角色在全片里不变。
+3. **手是手**：看得出手指或手套的形状，能真的握住物（物在手里，不是贴在手边）。
+4. **至少两层明暗**：底色＋阴影，再加高光或边缘光；光的方向和场景一致。
+5. **至少三处材质细节**：衣褶、缝线、发丝分组、布料纹理、鞋带、表带……挑这个角色身上该有的。
+6. **表演是具体的**：每次出场有一个和这一镜内容对得上的表情＋姿势（皱眉看手机、松一口气把手机揣进兜里），不是只眨眼、只上下浮动。
+7. **和画风同一套**：角色的线条、上色、色板和背景同一种画法，不是一张贴纸贴在别的画上。
+8. **前后一致**：同一个角色每一镜的五官、发型、衣服、配色一致。
+
+## 物不加脸：怎么让物「演」
+
+把概念讲活不需要给它画脸。
+
+- **用形状和动作**：锂离子在冷的时候挤成一团、走得慢；热起来散开、跑得快。电量条在冷风里一格一格缩下去。
+- **用尺度**：一个东西从手心大小砸到铺满画面。
+- **用对比**：同一个物左右两份，一份冻住、一份正常。
+- **用真实的物**：真实的电池剖面、真实的冰霜纹理、真实的屏幕截图。
+
+## 自检
+
+交付前抽 6 帧有角色或物的画面并排看，问三个问题：
+
+1. 有没有一眼像「AI 默认小人」或「白壳机器人」的东西？有，就换路。
+2. 有没有给不该有脸的东西画了脸？有，就去掉脸，改用动作讲。
+3. 角色和背景是不是同一种画法？不是，就按画风重做角色，或者让人只出手。

package/skills/biuart/references//351/225/234/345/244/264/350/241/250/346/250/241/346/235/277.md

@@ -0,0 +1,80 @@
+# 镜头表模板：先镜头表，再动手
+
+轨道档的第 1 步。开阔档也建议先写一张，lint 可跑可不跑。
+
+一张镜头表就是这支片子的分镜：先锁一套画风，再每行一镜，写清楚这一镜画面里**有什么物、它在做什么、镜头怎么动、屏上有几个字、用什么做**。写得出这张表，片子就不会变成一页越堆越长的 PPT，也不会变成每镜一种画风的拼贴；写不出某一行，说明那一镜还没想清楚，先别写代码。
+
+## 怎么写
+
+复制下面这段到 `<项目>/镜头表.md`，先填表前三行，再一行一镜往下填：
+
+```markdown
+画风：（一句话：一张风格卡或一种画法，全片只用这一种）
+色板：（references/色板.md 里的名字，或 3–6 个 #色值）
+角色：（无／只出手和背影／帧库 <路径>）
+
+| 时间段 | 画面里的物 | 它在做什么 | 镜头 | 屏上字 | 做法 |
+|---|---|---|---|---|---|
+| 0–3 | （名词：一个人、一个东西） | （动词：它正在干什么） | 停／缓推／拉远／横移／快推／砸入／切 | （≤8 字，可空） | （y4 片段 镜01.json／scenes/xxx.js／素材 照片） |
+```
+
+| 列 | 写什么 | 不要写 |
+|---|---|---|
+| 时间段 | `0–3`、`3–7.5` 或 `0:03–0:07`，前一镜的结束就是后一镜的开始 | |
+| 画面里的物 | 名词，画面上能指着说「就是它」的东西：一片面包、一粒孢子、主角的手 | 标题、要点、文字、列表、标签、字幕、卡片、背景、画面、图标；空镜、纯色、黑场、渐变底（主角不在画里） |
+| 它在做什么 | 动词，这个物自己的动作：飘进来、裂开、钻进去、被切掉 | 出现、显示、展示、淡入、逐条出现 |
+| 镜头 | 这一镜的主动作，按「观众这一刻该看哪」来选：停／缓推／拉远／横移／快推／砸入／切。快推、砸入是重音，只给揭晓、反转、关键数字；推进去之后要有来有回。各动作的用法和时长见 `references/镜头语言.md` | 每镜都推一次；每镜都匀速慢推 |
+| 屏上字 | 每镜 ≤8 字，可以空；口播原文交给字幕 | 整句口播、三行要点 |
+| 做法 | 用什么做：哪个语法的参数化片段（写 spec 文件名）、`scenes/<id>.js` 代码画、真实素材满幅 | 每镜换一种语法 |
+| 标签（可选列） | 这一镜贴在物旁边的小标签，用顿号隔开 | 一镜超过 3 个；一排发光胶囊 |
+
+表前三行（画风锁）：
+
+- **画风**：一句话写清全片用哪一种画法，例如「暖木色纸本插画，平涂加细铅笔线，厨房午后侧光」。换场景可以，换画风不行：卡通人、暗色代码屏、星空图标、白底柱状图、纸张、网页截图轮流出现，每一镜单看都不错，整片就是拼贴。
+- **色板**：`references/色板.md` 里的一套，或 3–6 个色值。所有片段 spec 写同一个 `"theme"`，scenes 也只用这几个色。不用蓝紫渐变、深紫星空、霓虹青紫。用户点名要蓝紫（赛博朋克紫、梵高星月夜）才加一行「允许蓝紫：理由」。
+- **角色**：画面里要出现人或拟人角色，先读 `references/角色精细度.md`。有生图能力就 AI 生帧，写「帧库 <路径>」；没有就写「只出手和背影」或「无」，用手、背影、剪影、物件讲故事。代码画的 Q 版小人、白壳机器人、长了脸的金币和小球已经停用。
+
+五条要求，写完逐条对：
+
+1. **开头 3 秒是一个具体的小场景，结尾也落在主角或主物的一个动作上**：开头是一个人或一个物在做一件和题目有关的事，不是标题，不是「今天我们来讲」；结尾是放进口袋、合上书、拉远看全貌这类动作，字可以写在画里的物上，不收在居中金句卡上。
+2. **全片一个例子贯穿、一套画风到底**：同一片面包、同一双手、同一台机器从头走到尾，各镜讲的是它身上发生的事；每一镜都在画风锁那一行写的画风里。
+3. **一镜 2–6 秒**：个别镜可以到 8 秒。
+4. **文字主导的镜头 ≤30%**：物列是标题/字、屏上字 7 个以上、或用 y5 动态文字做的，都算文字主导。
+5. **相邻两镜不用同一构图**：这一镜是满幅特写，下一镜就换成横移、换成另一个物、换个景别。换的是构图和镜头，不是画风。
+
+做法列的两条硬线（轨道档第 3 步也写着）：**单个参数化片段最多撑 8 秒**（同一个 .json 在表里合计不超过 8 秒）；**一支片最多用 2 种片段语法**，所有 spec 写同一个 `theme`，其余镜头用 scenes 按同一套色板画，或真实素材满幅。
+
+## 检查
+
+```sh
+uv run <skill>/scripts/storyboard_lint.py <项目>/镜头表.md --script <项目>/文稿.txt   # 有口播稿就带上 --script
+```
+
+逐镜给红黄绿和改法，有红灯非零退出。红灯就改镜头表、重跑，**红灯没清不许开始写代码**。黄灯可以做，交付说明里逐条写理由。lint 查的是：表前画风、色板、角色三行有没有写；色板里有没有蓝紫色值；角色行是不是代码画的小人，物列里有没有机器人、小人、火柴人而角色不是帧库，用了 y4 却没有帧库，有没有给金币、小球长脸；物列不能空、不能只是版面词、不能是空镜/纯色/黑场这类空画面；做什么列要有动作；屏上字 ≤8；第一镜和最后一镜都不能是文字主导；文字主导 ≤30%；给了 `--script` 时屏上字里的数字（百分数、年份、带单位的数）要在文稿里找得到（文稿写「百分之六十」也认）；有「标签」列时一镜超过 3 个标签报黄；单镜 2–6 秒（6–8 秒黄、超过 8 秒红）；连续三镜同一个镜头动作报黄（「停」「横移」不算）、连续三镜都往里推报黄、快推／砸入／甩超过镜头数三分之一报黄；做法列里同一个片段合计超过 8 秒、片段语法超过 2 种报红。「一个例子贯穿」「每镜真的是同一种画风」「相邻构图不同」机器查不了，自己对。
+
+## 示例：为什么面包会发霉（54 秒，横屏）
+
+这是写法示范：题材、物和镜头顺序不要搬进你的片子。贯穿全片的是同一袋吐司和主人小满的一双手，脸不出画。
+
+画风：暖木色纸本插画，平涂加细铅笔线，所有镜头同一束厨房午后侧光
+色板：wood
+角色：只出手（小满的手，不出脸）
+
+| 时间段 | 画面里的物 | 它在做什么 | 镜头 | 屏上字 | 做法 |
+|---|---|---|---|---|---|
+| 0–3 | 小满的手和一袋吐司 | 手撕开面包袋，指尖停在一块青绿色斑点上 | 停 | | scenes/kitchen.js |
+| 3–6 | 那块绿斑 | 绿斑边缘一圈白毛，像地图一样往外扩 | 缓推 | 三天前还没有 | 素材 霉面包照片满幅 |
+| 6–10 | 一粒孢子 | 孢子从窗缝飘进来，翻着跟头落到面包上 | 横移 | 孢子 | scenes/spore.js |
+| 10–14 | 那粒孢子 | 孢子壳裂开，伸出一根白丝扎进面包 | 快推 | | scenes/spore.js |
+| 14–18 | 面包切面的气孔 | 白丝沿着气孔分叉，像树根一样往下钻 | 拉远 | 菌丝 | scenes/hyphae.js |
+| 18–22 | 面包里的淀粉粒 | 菌丝尖端喷出酶，把淀粉粒剪成一颗颗糖 | 缓推 | 淀粉→糖 | scenes/hyphae.js |
+| 22–26 | 厨房墙上的温湿度计 | 指针从 15°C 滑到 28°C，袋子内壁凝出水珠 | 切 | 28°C | scenes/kitchen.js |
+| 26–31 | 两条霉斑面积曲线 | 台面那条一路往上冲，冰箱那条贴着底爬 | 停 | 冰箱里慢得多 | t3 片段 镜08.json |
+| 31–35 | 霉斑表面的小柱子 | 一根根小柱顶起黑色孢子球，孢子球砰地炸开 | 砸入 | | scenes/hyphae.js |
+| 35–39 | 一团孢子云 | 孢子云飘过桌面，落向旁边那袋馒头 | 横移 | 下一站 | scenes/spore.js |
+| 39–43 | 小满的手和面包刀 | 刀尖比着绿斑那一角，想切掉剩下的接着吃 | 停 | 切掉就行？ | scenes/kitchen.js |
+| 43–47 | 被切开的面包剖面 | 透视一层层剥开，看不见的菌丝早已爬满半片 | 快推 | 看不见的部分 | scenes/hyphae.js |
+| 47–51 | 小满的手和垃圾桶 | 手把整袋吐司丢进去，扣上盖子 | 切 | | scenes/kitchen.js |
+| 51–54 | 小满的手和一袋新吐司 | 手把新吐司塞进冷冻层，门一关，霜慢慢爬上袋子 | 拉远 | 冷、干、密封 | scenes/kitchen.js |
+
+为什么这张表能过：表前锁了一种画风、一套色板，人只出手；开头是一双手撕开袋子看见霉斑，不是标题；结尾回到同一双手，把新吐司塞进冷冻层，三个字写在画里，不是一张金句卡；同一袋吐司从头到尾；14 镜里没有一镜是文字主导；唯一的参数化片段是第 8 镜的 t3 曲线，它的 spec 写 `"theme": "wood"`，和 scenes 同一套色；镜头跟着「观众这一刻该看哪」走：要看清细节时缓推（绿斑、淀粉粒），跟着一个会动的东西时横移（孢子、孢子云），要看全貌时拉远（菌丝往下钻、关上冷冻门收尾），画面自己在动时停住（曲线在长、刀尖在比划）；快推和砸入只用了三次，留给孢子壳裂开、孢子球炸开、剖面揭开这三个「原来如此」。推进去之后用拉远、横移、停或硬切换开，没有连续三镜往里推。第 8 镜的曲线是示意，成片里要标「示意数据」。

package/skills/biuart/references//351/225/234/345/244/264/350/257/255/350/250/200.md

@@ -0,0 +1,73 @@
+# 镜头语言：镜头怎么用
+
+SKILL.md「导演的要求：镜头怎么用」的展开。这页的每个数字都写了**什么时候生效、什么时候不用管**。数字来自参考片实测和作者表过态的片子，是起点，不是配额；你有更好的镜头设计就去做，做完正常速度看一遍、和参考并排看。
+
+## 一、动镜头之前问三句
+
+1. **观众这一刻该看哪？在当前景别下看得清吗？** 看得清就不动。画面自己在动（实拍录像、正在描的线、正在长的曲线、正在倒的水）就更不用动，镜头一动反而抢戏。
+2. **这一下是过渡还是重音？** 把视线带到下一处、交代关系、铺情绪，是过渡，用缓的。揭晓、反转、关键数字落地、笑点，是重音，才用快的。
+3. **上一个镜头动作是什么？** 推进去了就要找机会拉出来或横移开，别一镜接一镜只往里推。同一种动作连用三次，观众就感觉到节拍器了。
+
+## 二、动作表
+
+| 动作 | 拿来做什么 | 参考数 | 数从哪来 | 什么时候不用管这个数 | 引擎 |
+|---|---|---|---|---|---|
+| 停 | 观众在读字、画面自己在动、笑点后的沉默 | 停多久按口播，没有上下限 | Vox 停留段帧差 0.0–0.1；3b1b 的 wait 是静止的 | — | 不写动作 |
+| 缓推 | 带视线到下一处细节、情绪往前推一步 | 0.6–1.5s，sineInOut；推到「要看的东西能读」为止，常见 10–40% | Vox 推进照片 1.0–1.5s、找卡 0.5–0.9s；3b1b 原生推镜约 1s；Heer & Robertson 2007 建议统计图表的数据过渡约 1s、缓入缓出（说的是图表过渡，这里借来类比） | 推的距离很大（2 倍以上）时可以到 2s；跟音乐拍点走时按拍子 | `CAM.track` 的 `push`（默认 0.9s）、`to` |
+| 拉远 | 回到全貌、交代「它在哪」、段落收束、结尾 | 0.8–2s，起步快、长尾落定 | Vox 拉出约 1s；Kurzgesagt 快速拉远揭示 0.2–2s，长尾 | 尺度穿行（从细胞拉到地球）按 y1 卡「④」的时长 | `pull`（默认 1.1s，`MO.longTail`） |
+| 横移／找下一件 | 同一面墙、同一张桌上从一件走到下一件；跟着一个会动的东西 | 0.5–0.9s，sineInOut；沿红线追 1.3–1.8s，长尾 | Vox 实测 | 跟随运动物体时速度跟物体走 | `glide`（默认 0.7s） |
+| 快推 | 重音：揭晓、反转、关键数字 | 0.25–0.35s 推近 18–32% 后停 | 诺奖文学片 r3 被认可时用的数（07 号第 29 条，同时还换了素材和底色）；School of Motion 动态文字「镜头推 6 帧＋2 帧回拉」 | 动态文字（y5）里快推就是主语法，跟着重音走；其它语法里它是少数 | `punch`、`to` 写 `dur: MO.PULSE.punch` |
+| 快移／甩镜 | 视线突然转移（「我打开电脑 →（屏幕）」）、喜剧节奏 | 0.26–0.30s，带运动模糊 | y4 甩镜实测 0.26s expoInOut | — | `pan`、`TRANSITIONS.whip` |
+| 砸入 | 大字、数字、盖章、新画面落下的那一下 | 0.17s，1.55→0.94→1.0 | 认可片实做 | 一镜最多一次；不要每次切镜都砸 | `slam`、`MO.slam` |
+| 硬切／跳近 | 换景别不靠运镜：反应特写、跳近一档 | 0 帧 | y4 storytime：定住＋跳近，笑点靠切 | — | `cut` |
+| 慢漂、匀速慢推 | 氛围镜头、艺术风格画面「画一直是活的」、MV 抒情段、5 秒以上的情绪长镜头 | 1–4%/s 当起点 | 没有认可片实测：这是 y1、y2 示范片里的数（4%/s、1%/s），用在解说镜头上被判成旧做法；用在氛围镜头上没被否过，做完和参考并排看 | **解说片里每镜都慢推几个百分点就是 PPT**（07 号第 29 条那支片子），这一种用法不行 | `CAM.drift`、`CAM.at` |
+
+时长常量都在 `MO.PULSE`，`CAM.track` 不写 kind 就是缓推；`pull` 不写 k 正好抵消一次默认缓推，回全貌最稳是写 `z: base.z`。参数化片段（t2、y1、y2）的 highlight 默认缓推过去，spec 顶层的 `data` 里写 `"camera": "snap"`（`{"data": {"camera": "snap"}}`，直接写在 spec 顶层（和 grammar 同级）或写进某条 cue 的 data 都不生效，也不报错）才换成快推，整段片段都会变成快推，所以只给需要重音的那一段这样写。
+
+## 三、次数和密度：什么时候管，什么时候不用管
+
+**原则**：重音动作像文章里的加粗，全篇都加粗就等于没有重点。推近要有来有回。
+
+| 情况 | 管不管 | 怎么判断 |
+|---|---|---|
+| 解说、科普、财经、白板、Vox 类片子 | 管 | 快推＋砸入＋甩，占镜头数的三分之一以下（lint ⑯）；不连着三镜往里推（lint ⑮）；成片「推近次数」每分钟 8 次以上 film_gate 报黄，用正常速度看一遍 |
+| 抖音、视频号片子的前 3 秒钩子 | 不管密度 | 钩子可以密，3 秒之后回到正常节奏 |
+| 动态文字（y5）、音乐卡点段落 | 不管快推次数 | 镜头跟着拍点和重音走，节奏由音乐给 |
+| 故事、喜剧（y4） | 管推，不管切 | 主要靠定住＋硬切跳近；推镜很少 |
+| MV、情绪片 | 跟着情绪管 | 作者原话（2026-10-11）：「运镜和转场都显得单调、干涩，缺乏多样性，缺乏情绪的表达」。主歌缓推、慢漂，副歌才加快，间奏拉远，转场峰值踩拍点 |
+| 艺术风格速通、穿越类 | 不管推近，管「画是不是活的」 | 每幕一个主动作＋2 个母题循环；镜头可以一直慢漂 |
+| 3b1b（t1） | 管推 | 镜头跟着要看的对象走：smooth 一次推到约 1s，wait 里静止；结论落地才快推 |
+| 发布会、截图教程（t2） | 管推 | 截图满幅，讲到看不清的那块才缓推过去，一张图一两次，讲完拉回整张或横移到下一块 |
+| 财经图表（t3） | 管推 | 图表自己在长时镜头停住；点到某个数据时缓推约 1s，全片最关键的一两个数才快推 |
+| Kurzgesagt（y1） | 管推，不管环境层 | 环境层可以一直轻轻动；点名节点缓推，钻进、拉出按尺度穿行的时长 |
+| Vox 调查桌（y2）、白板（y3） | 管推，横移随意 | 整张世界画布，镜头在件与件之间横移是主语法，可以连着用；推近给要读的那一行，读完拉出 |
+
+**反面标尺**：2026-10-12 一支诺奖经济学竖屏短片，102 秒、44 镜，代码里推近约 48 次（平均 2.1 秒一次），全部往里推，每次 0.28 秒推近 10–26%，几乎没有拉远和横移。作者原话：「有非常非常多zoom in的镜头运动。次数太多，而且节奏太快了，一点都不smooth」。film_gate 在这支片上量到推近每分钟约 12 次（这是下限，实拍录像上的推近有一半量不到）。
+
+## 四、真实素材满幅时：最容易掉进的坑
+
+一镜一张满幅照片或录像时，镜头唯一能做的就是往里推，于是整片变成「切一张、推一下、切一张、推一下」。那支诺奖短片就是这样。办法：
+
+- **实拍录像本身在动，就停住**。录像里的人在走、手在动，再叠一层推近，观众会觉得晃。
+- **一张图最多推一两次**，而且只在「这一处在全景下读不清」时才推。念到一个名词就推一次，是在给口播配节拍器。
+- **换个进场方式**：从近景拉出来露出全貌；从一侧横移进来；从上一镜的落点硬切到同景别。
+- **几件素材要连着讲，就摆进同一张世界画布**（`MD.print` 冲印件摆在调查桌上，见 y2 卡），镜头在件与件之间横移，这时推近和横移交替出现，自然就有来有回。
+- **切镜不等于要重新推一次**。每镜都从 1.0 起推，叠起来就是一推一推的 zoom in。
+- **调查桌不是把素材缩小摆着**。镜头停在一件上时，它要占画面八九成（y2 卡）；露出大片桌面只该出现在移动途中和收尾拉远。2026-10-12 的 A/B 里，新规则下的那支改用调查桌，推近从 15 次降到 8 次，但停下来时照片只占半个画宽，米色桌面露得多。
+- **竖屏放横版插图，先裁再摆**。16:9 的插图整张摆进 9:16，只剩中间一条，上下全是空的；按口播正在讲的那一块裁成竖构图再做冲印件或满幅，整张只留给收尾拉远。同一天两个独立 agent 各自踩到这一条。
+
+## 五、怎么自检
+
+- 镜头表阶段：`storyboard_lint.py` 查连续三镜同一动作（停不算）、连续三镜往里推、重音超过三分之一、整表没有任何动作。
+- 成片阶段：`film_gate.py` 的「推近次数」黄灯说明推得多，去看；「快动帧占比」红灯说明整片几乎没动。注意：1 秒左右推近 20% 的缓推，和 0.28 秒快推在这一项上记的分差不多（2026-10-12 用诺奖短片三帧实测：0.28s 推 3 帧、1.0s 推 4–7 帧、2.0s 推 3–10 帧记作快动），不需要为了过门把镜头改快。
+- **运镜顺不顺，抽帧看不出来**。静帧拼图只能看构图，镜头节奏一定要用正常速度把成片从头看一遍，至少看最密的那 30 秒。
+
+## 六、出处与历史
+
+| 日期 | 片子 | 发生了什么 | 落到这页哪里 |
+|---|---|---|---|
+| 2026-10-08 | 一支诺奖文学科普片 r2 → r3 | r2 每镜匀速推近 7.5%，还有固定米底、标题栏、相框，被判「完全是放ppt的感觉」；r3 同时换了四样：真人录像满幅、深色真实环境、去掉页框、停住 → 0.28s 快推 → 停住，「现在好多了，做完直接发吧」 | 慢漂那一行的「不行的用法」、快推那一行的出处。四样一起换，分不清是哪一样起的作用；后来却只把「每个口播节点都快推」写成了规则，等于把「每镜同一个动作」这个病换了个速度。2026-10-12 作者回看时说「文学片很一般，物理的还不错」 |
+| 2026-10-10 | Claude 的一天开场 r4 | 「很不错，就按这个节奏继续吧」：砸入、0.35s 猛拉开成剖面全景、纸飞机横移，静帧里加浮尘 | 被认可的是一组混着用的动作，拉开和横移都在里面 |
+| 2026-10-05 | SpaceX 白板 | 作者选了 r6；r17 比 r6 多推近 5 次（没确认是不是这一点打动了作者） | 待确认 |
+| 2026-10-11 | 七里香莫奈 MV | 「运镜和转场都显得单调、干涩，缺乏多样性，缺乏情绪的表达」 | 第三节 MV 一行 |
+| 2026-10-12 | 诺奖经济学短片 | 「有非常非常多zoom in的镜头运动。次数太多，而且节奏太快了，一点都不smooth」 | 第三节反面标尺、第四节 |