@dsh-gis/dsh-video-studio-skill 0.9.1 → 1.0.2

package/skills/video-studio/references/style-packs.md

@@ -1,283 +1,121 @@
-# 风格包（Style Packs）：让每部片的画风 / 配乐 / 旁白都不一样
+# 外观定制：设计 DSL 实操手册（v1.0.2）
 
-> v0.5.0 新增。读这一篇之前先读 SKILL.md 的 §5.6。
-> 一句话：**一个 style id 同时决定画风、配乐、旁白声音和节奏**，不能三样各自乱配。
+> **这篇不是「8 套风格选一套」。** v1.0.1 起仓库里没有任何内置风格表——
+> 没有 `STYLES` / `THEMES` / `VISUAL_LANGUAGES` / `presets/`，也没有 `style` 字段。
+> 外观由 `work/design.json` 决定，而它是 `propose.py` 现场采样 + 你确认之后冻结的。
+> 这篇讲的是：**想控制画面的哪一块，就改 design.json 的哪个字段，怎么验证它真的生效。**
 
-## 0. 为什么需要它（v0.4 的病）
+## 0. 三条正确姿势
 
-v0.4 及以前，所有"身份参数"都是模块级常量：
-
-| 层 | 被写死的地方 | 结果 |
+| 你想要 | 怎么做 | 不要这样做 |
 |---|---|---|
-| 画风 | assets/scenes.py 的 THEME 字典 + 3 个绘制函数 | 每部片都是深蓝底 + 橙强调 |
-| 配乐 | scorekit 的 4 个小调 + 3 套和弦进行 + 固定动机 | 每部片都是 Dm / 120BPM 那一套 |
-| 旁白 | render.py 的单个 voice/rate/pitch | 每部片都是同一个声音、同一语速 |
-| 流程 | SKILL.md 教的是 "cp 模板 -> 改 lines[].text" | 模型自然只会改文案 |
-
-结果就是：**内容换了，气质没换**。用户的原话是"背景音乐风格都差不多、旁白声音都差不多、整体画风也差不多"。
-
-## 1. 三层结构
-
-    film.json   style: "auto" | "tech-deep" | ... | "legacy"
-        |
-        v
-    stylekit.resolve_script_style(script)        <- 纯函数，确定性
-        |  +- 关键词打分（title/chapter/text/items）
-        |  +- 三级内容指纹（full / tempo / style）
-        |  +- 显式覆盖（visual.theme / music.style / voice.map / pacing）
-        v
-    work/style.json                               <- 审计产物：能看到"为什么是这套风格"
-        |  +- style / theme_id / chapter_layout
-        |  +- music{bpm,key,mood,seed_effective}
-        |  +- voice{map,policy}
-        |  +- pacing{lead,tail,min_dur,item_stagger}
-        v
-    画面（scenes.py 读主题）    配乐（scorekit 读风格）    旁白（voicekit 读 persona/tone）
-
-## 2. 8 套内置风格
-
-| id | 中文 | 画风 | 配乐 | 旁白 | 适合内容 |
-|---|---|---|---|---|---|
-| tech-deep | 科技深蓝 | 深蓝渐变 + 橙 | 小调 100–124 / 琶音 + 铃声 | 男声叙述 + 青年开场 | AI、工程、数据、科普 |
-| magazine | 杂志暖白 | 米白 + 朱红，衬线体 | 大调 88–100 / 电钢 | 女声叙述 + 权威男声引用 | 报告、复盘、研究 |
-| paper | 手绘纸感 | 牛皮纸 + 靛青，楷体 | 大调 84–92 / 马林巴 | 软糯女声 + 男声引用 | 手工、自然、历史 |
-| vivid | 活力撞色 | 深紫 + 柠檬黄，大字 | 大调 120–132 / 短促和弦 | 活泼女声开场 | 活动、营销、上新 |
-| mono | 极简黑白 | 纯白 + 黑，超宽字距 | 极简 60–68 / 钢片琴 | 沉稳男声 + 女声引用 | 观点、演讲、思辨 |
-| cinema | 电影青橙 | 近黑 + 青橙，扫描线 | 小调 76–84 / 弦乐铺底 | 纪录片男声 + 女声引用 | 纪录、叙事、城市 |
-| lo-fi | 暖灰薄荷 | 暖灰 + 薄荷绿 | 大调 72–84 / 电钢 + 轻鼓 | 温柔女声 | 日常、学习、专注 |
-| epic | 深黑鎏金 | 近黑 + 金，衬线体 | 小调 88–96 / 铜管 + 人声铺 | 有力男声 + 男声开场 | 史诗、宣传、高潮 |
-
-外加 legacy：不写 style 字段时的兼容档，画风/配乐/旁白全部等于 v0.4（配乐逐样本一致）。
-
-查表：
-
-    python stylekit.py --list          # 8 套风格 + 主题 + 对比度
-    python stylekit.py --show cinema   # 单套风格的全部字段
-    python stylekit.py --lint          # 主题对比度门禁（CI 会跑）
-
-## 3. film.json 怎么配
-
-最小配置（推荐，几乎不用写）：
+| 换一种气质 | `propose.py --revise "更冷一点，少装饰，换女声"` 重出方案 | 去找"第 9 套风格"——没有这种目录 |
+| 微调某个细节 | 手改 `work/design.json` 的字段 → `designkit.py --lint` 校验 → `render.py --stage stills` 看 | 直接改 `filmkit.py` 里的常量 |
+| 换整个画面语言 | 写自己的 `scenes.py`（放剧本同目录），实现 `draw_frame(scene, t_local, dur, t_global, script, frame)`（完整签名见 SKILL.md §1） | 期望 `--engine web` 跟随 design（它不会） |
 
-    {"style": "auto"}
+## 1. design.json 的六块
 
-自动模式：命中题材关键词就锁定对应风格；零命中时按内容指纹稳定落桶
-（同一份稿子永远同一个风格，不同稿子大概率不同）。
-
-想锁定：
-
-    {"style": "cinema"}
-
-想只改某一块（其余跟着风格走）：
-
-    {
-      "style": "magazine",
-      "visual": {
-        "theme": "paper",
-        "layout": "split-right",
-        "theme_overrides": {"vignette": 0.18, "grain": 8.0}
-      },
-      "music": {
-        "style": "lo-fi",
-        "bpm": "auto", "key": "auto", "mood": "calm",
-        "seed": 7, "seed_from_content": true
-      },
-      "voice": {
-        "map": {"hook": "bright_female", "body": "narrator_female"},
-        "jitter": 0.35,
-        "max_distinct": 3
-      },
-      "pacing": {"lead": 0.6, "tail": 0.9, "item_stagger": 0.3}
-    }
-
-逐句覆盖（最高优先级）：
+| 块 | 决定什么 | 字段 |
+|---|---|---|
+| `structure` | 几段、目标时长 | `segments` / `beats` / `hold_policy` / `target_sec` |
+| `visual` | 画面全部外观 | 见 §2 |
+| `audio` | 配乐 / 声线 / 音效 | `music`（scale/bpm/key/mood/seed）/ `voice`（id/map/jitter/max_distinct）/ `sfx`（enabled/density/gain_db） |
+| `pacing` | 节奏 | `lead` / `tail` / `min_dur` / `hold` / `item_stagger` |
+| `id` | 指纹 | `design:<hash>`，由 `designkit.design_fingerprint()` 算出 |
+| `label` / `pitch` | 中文标签 / 立意 | 提案卡上显示的那一句话 |
 
-    {"id": "l03", "kind": "body", "text": "他说：「这不可能」",
-     "voice": "authority_male", "tone": "quote", "lead": 0.8}
+校验：`python <SKILL_DIR>/scripts/designkit.py --lint work/design.json`；
+契约：`<REPO>/schemas/design.schema.json`。**fail-closed**：缺字段/越界/对比度不达标一律报错，
+不会静默回落（这是对 v0.5–v0.9「改了不生效」的直接反思）。
 
-### 字段速查
+## 2. visual 字段表（能控制什么）
 
-| 字段 | 默认 | 说明 |
+| 字段 | 取值 | 改它会发生什么 |
 |---|---|---|
-| style | 无（= legacy） | 风格 id / "auto" / "legacy" |
-| visual.theme | — | 等价于锁 style；与 style 1:1 |
-| visual.layout | 风格默认 | left-stack / center-stack / split-right |
-| visual.theme_overrides | — | 深合并覆盖主题单字段 |
-| music.style | 跟随 style | 只换配乐风格 |
-| music.bpm | "auto" | 数字或 "auto"（按风格梯度 + 指纹） |
-| music.key | "auto" | 调名或 "auto"（按风格调池 + 指纹） |
-| music.mood | 风格默认 | calm/reflective/hopeful/steady/driving/tense/uplifting |
-| music.seed_from_content | 非 legacy 时 true | 音色细节由内容指纹派生 |
-| voice.map | 风格默认 | kind -> persona 名 |
-| voice.jitter | 0.35 | 语速/音高微扰，0 = 关 |
-| voice.max_distinct | 3 | 全片最多几把声音 |
-| pacing.* | 风格默认 | 语前留白/语后留白/最短段长/条目落位步长 |
-| lines[].persona / lines[].voice / lines[].tone | — | 逐句覆盖（最高优先级，voicekit 真的读这三个） |
-| lines[].lead | — | 逐句语前留白（filmkit.build_timeline 读） |
-| lines[].rate / pitch / volume / tail | — | **当前不生效**（保留字段）：voicekit 只认 persona/voice/tone，filmcheck 会对这三个报"未知键"；要改语速/音高请换 persona 或 tone，或在顶层写 rate/pitch/volume |
-
-## 4. 三级指纹：改错别字不会换整首曲子
+| `palette` | 11 个颜色角色（bg/bg2/surface/ink/muted/dim/accent/accent2/good/bad/rule），每个 `[r,g,b]` | 整片色调。它不是"从 8 套配色里挑"，而是**连续色相空间**里的一点：改 `bg` 的色相，其余角色会按对比度网格重新求解 |
+| `family` | `sans` / `serif` / `kai` / `round` | 全片字族（标题优先，字幕默认跟随） |
+| `typography` | `tracking`（字距）/ `line_gap`（行距）/ `number`（编号写法，8 种）/ `ratio`（字号比例）/ `align` | 文字气质；`number` 决定"01 / 壹 / I / 1.0"这类编号外观 |
+| `motif` | `kind`（8 种：brackets / hairlines / handdrawn / slabs / minimal / letterbox / signal / rays）× `density`（0.55–1.00） | 装饰语言：四角括线 / 细线页眉 / 手绘框 / 色块 / 极简 / 遮幅 / 信号条 / 放射线 |
+| `transition` | `kind`（dip / wash / paper / wipe / cut / iris）+ `dur`（秒） | 段与段之间的转场 |
+| `motion` | `ease`（out3/out5/inOut3/outBack）/ `enter`(dx,dy) / `push`（镜头缓推）/ `breathe_hz` | 入场与镜头运动 |
+| `bias` | `x` / `y` / `inset` | 整屏重心偏移与安全区收缩 |
+| `layout` | `left-stack` / `center-stack` / `split-right` | 默认版式 |
+| `layout_cycle` | 版式数组（≥2 种不同） | **v1.0.2**：按章节轮换版式；不写则自动派生 2–3 种 |
+| `hud` | `chip-left` / `corner-line` / `none` | 页眉/角落装饰 |
+| `size` / `fps` | `1920x1080` / `30` | 只支持 16:9 横屏（编码时可下采样到 720p） |
+| `subtitle` | 见 §3 | **v1.0.2**：字幕字号/位置/对齐/背板/圆角/字族/颜色/行数 |
+
+> **能组合出多少种画面？** 离散维度是 8 母题 × 6 转场 × 4 缓动 × 8 编号 × 3 版式 × 3 HUD × 4 字族
+> × 7 情绪 × 2 调式（= 774,144 种），再乘配色这个连续量（色相 0–360° 任意取值）。
+> 这个数字只说明"字段可组合空间足够大"，**不是推荐你从中挑**——好看与否仍由对比度体检、
+> 分镜语法和你的目检决定。
+
+## 3. 字幕样式（visual.subtitle，v1.0.2）
+
+以前字幕的字号 / 位置 / 背板 / 圆角是 `filmkit` 的写死常量，所以**任何两条片子**的字幕带一模一样。
+现在进设计 DSL；**不写 = 默认值，与过去逐像素一致**（老 `design.json` 不受影响）。
+
+```json
+"subtitle": {"size": 46, "y": 560, "align": "left", "plate_alpha": 170,
+             "radius": 10, "family": "sans", "color": [245, 245, 245], "max_lines": 2}
+```
+
+| 字段 | 默认 | 取值 | 备注 |
+|---|---|---|---|
+| `size` | 46 | 20–96 | 采样器默认跑 40–56 |
+| `y` | null | 0–1030 | null = 贴底安全区；采样器 1/3 概率抬高到 560–880 |
+| `align` | center | center / left | |
+| `plate_alpha` | 170 | 0–255 | 采样器默认 96–194 |
+| `radius` | 10 | 0–48 | 采样器默认 2–20 |
+| `family` | null | sans / serif / kai / round | null = 跟随大标题字族 |
+| `color` | null | [r,g,b] 或 #rrggbb | null = 默认墨色 |
+| `max_lines` | 2 | 1–3 | 决定了折行上限 |
 
-| 指纹 | 由什么算 | 决定 |
-|---|---|---|
-| full | 标题 + 全部台词 | 音色细节（seed 派生） |
-| tempo | 标题 + kind 序列 + 体量桶 | BPM 与调性 |
-| style | 标题（配合关键词评分破平） | 风格 id |
+验证：`render.py --stage style` 会打印一行「字幕: ... 对齐=... 背板α=... 圆角=... 最多N行」，
+改 design 后重跑这一行就能看重算结果，不用等渲完。
 
-所以：改一个错别字 -> full 变（音色纹理微变），tempo/style 不变（还是同一首曲子、同一个调）；
-换一部片 -> 三个都变。`music.seed_from_content: false` 只锁住 **seed 派生**（音色细节）；
-`full` 指纹仍会传给 scorekit 参与结构变奏（和弦替换/动机偏移/鼓型 ghost，见
-[audio-variation.md](audio-variation.md) §3.3）。要把声音完全锁回 v0.4 行为，只能不写 `style`（legacy）。
+## 4. 版式轮换（visual.layout_cycle，v1.0.2）
 
-## 5. 片内变化：整体是一套，但每段有呼吸
+```json
+"layout_cycle": ["split-right", "left-stack", "center-stack"]
+```
 
-**锁三件事**（全片一致，否则会"花"）：
+- 元素取 `left-stack` / `center-stack` / `split-right`；**至少 2 种不同版式**，只写一种会被校验拒绝。
+- 由 `grammar.plan_scenes` 按**章节**轮换：同一章内固定，换章才换（观众视角一章是一段整体）。
+- 不写时 `design_to_plan` 按设计指纹自动派生 2–3 种，**默认就不是全片一张版式**。
+- 审计：`--stage layout` 打印每段构图；`work/storyboard.json` 每段都有 `layout` 字段。
 
-1. 明暗族（全深色 or 全浅色）
-2. accent 色相
-3. 字体族与字号阶梯
+## 5. 配色怎么改才不出事
 
-**其余可以按章节变**：
+配色不是"挑一个好看的颜色"，而是 11 个角色要同时满足对比度：
+`theme_lint` 的门槛是 ink≥7 / muted≥4.5 / dim≥3 / accent≥4.5 / accent2≥4.5（good/bad≥3），
+另外要求 bg 与 bg2 有可感知的亮度差（防纯色底）。
 
-- 版式骨架轮换（同一 chapter 内不变）：left-stack / center-stack / split-right
-- 背景明度微移、纹理强度、accent 出现的面积
-- 配乐：逐小节能量弧线、配器进出（1 小节渐入渐出）、主奏轮换、动机变形
-- 旁白：hook/body/quote/outro 的语气档（语速、音高、停顿）
+推荐两条路：
 
-**禁止**：同一部片里跨明暗族换主题（深蓝段直接切暖白段）。实测这会精确触发
-qa_frames 的单帧闪烁门禁（阈值 6.0 灰度，整屏换底可达 100+ 级），而且观众看着像"换了一部片"。
-真需要强对比，把它做成两个片子，或登记成带 visual_at 的视觉事件。
+1. **让采样器算**（默认）：采样器在 (hue, s, v) 网格里找满足全部门槛的点；
+   实测纯随机取色通过率 35%，网格求解 100%。
+2. **手改色相**：只改 `palette.bg` 的色相/饱和度，然后跑 `designkit.py --lint`；
+   过不了就调一档明度——报错会直接点名哪个角色不达标。
 
-## 6. 门禁：主题必须过对比度体检
+> 片内**不要跨明暗族**：同一部片锁一个明暗族，段界跨族会整屏换底、触发闪烁门禁，观众也看着像换片。
+> 这条在采样器里是硬约束，手改 design 时请自己守住。
 
-stylekit.theme_lint(theme) 在 --stage style 就拦，不用等渲完 300 帧：
+## 6. 片内不重复：三层一起用
 
-| 角色 | 对背景的最低对比度 | 理由 |
+| 层 | 机制 | 防的是什么 |
 |---|---|---|
-| ink（正文/标题） | 7.0 | WCAG AAA 正文线 |
-| muted（副标） | 4.5 | WCAG AA |
-| dim（HUD 小字） | 3.0 | 装饰级 |
-| accent / accent2 | 4.5 | 强调色常当文字用 |
-| good / bad | 3.0（对卡片底） | 只承载图形，靠位置+颜色双编码 |
-| bg 与 bg2 亮度差 | >= 0.002 | 防纯色底 |
-
-加第 9 套风格时：先写 _theme(...)，再跑 python stylekit.py --lint，过了再进 STYLES。
-
-## 7. 加一套自己的风格（5 步）
+| 段内 | `lines[].type`（10 类构图，grammar 自动选） | 每段都长一个样 |
+| 章内 | `layout_cycle`（v1.0.2，按章节轮换） | 全片一张版式 |
+| 片间 | 采样 nonce + 候选 ≥2 维 + 底色色相分叉 + **片间去重台账** | 不同片撞衫 |
 
-1. stylekit.THEMES["my-style"] = _theme(...)（配色 + 材质 + 排版 + 版式 + 动态 + HUD）
-2. stylekit.STYLES["my-style"] = {...}（theme / layouts / music{bpm_ladder,keys,mood} / voice / pacing）
-3. STYLE_IDS 元组末尾追加（只追加不改顺序，否则指纹映射会漂）
-4. python stylekit.py --lint 全绿；配乐侧在 scorekit.MUSIC_STYLES 里加同名条目
-5. 用 3 段样片跑 --stage stills 亲眼看（铁律 6：能出图 != 没问题）
-
-## 8. 常见误用
+## 7. 常见误用
 
 | 现象 | 原因 | 修法 |
 |---|---|---|
-| 画面换了、配乐还是老的 | 只改了 visual.theme 没改 music.style | 直接改 style，或两个都写 |
-| 同一部片前后像两部片 | 段界跨了明暗族 | 用同族主题；或拆成两部 |
-| 改台词后配乐变了 | 改了标题或 kind 结构 -> tempo 指纹变（BPM/调性跟着换） | 写死 music.key / music.bpm（`seed_from_content:false` 只管音色 seed，压不住 BPM/调性变化） |
-| 旁白听感像广播剧 | max_distinct 太大 / 相邻句频繁换人 | 降到 2，靠 tone 而不是换人做变化 |
-| 字幕在浅色主题上看不清 | 用了 v0.4 的黑底白字 | 传 theme= 给 draw_subtitle（render.py 已自动传） |
-
-## 9. 视觉语言包（v0.9）：结构签名，不只是配色
-
-### 9.1 为什么还要这一层
-
-v0.5 的 `STYLES` / `THEMES` 管的是**皮肤**：配色、字体族、纹理、颗粒、字距、缓动、HUD、
-3 种版式几何。8 套风格共用同一批绘制器与同一套装饰，于是"换风格"在画面上只剩换色——
-灰度量出来的构图骨架（前景占比 / 重心 / 边缘占用 / 左右对称）几乎不动。
-
-`stylekit.VISUAL_LANGUAGES` 补的是**结构签名**：同一段内容在两套风格下，剪影必须能区分。
-它是纯数据（不 import PIL / filmkit，否则与 `scenes.py` 成环），与 `STYLES` 同层，
-`--stage style` 一起体检。
-
-### 9.2 五组签名字段
-
-| 组 | 字段 | 取值 / 例子 | 谁读它 |
-|---|---|---|---|
-| `motion` | `ease` | `out3` / `out5` / `inOut3` / `outBack` | `scenes.py`（所有绘制器的入场缓动） |
-| | `breathe_hz` | 0.28–1.10（Hz） | `scenes.py`（强调线/下划线/光点呼吸频率） |
-| | `enter` | `(起, 止)` 秒，如 `(0.70, 1.20)` | **已声明、visual_lint 会查、绘制器暂未读** |
-| | `push` | 0–0.16（背景缓推幅度） | **已声明、visual_lint 会查、绘制器暂未读**（主题自带的 `push` 仍生效） |
-| `motif` | `kind` | `brackets` / `hairlines` / `handdrawn` / `slabs` / `minimal` / `letterbox` / `signal` / `rays` | `scenes._motif_layer` 烘焙母题、`scenes._plate` 合成进背景底版；v0.9.1 起逐帧只 copy/EXTENT（约 1.3–2.0 ms），不再逐帧 paste（实测 5.6 ms） |
-| | `density` | 0–1（母题浓度；0 只允许 `minimal`） | `scenes._decor_scale`（再乘片内密度档 0.55/0.75/1.0） |
-| | `detail` | 母题专属参数（`corner`/`rule_step`/`wobble`/`top`/`bars`/`rays` …） | 同上 |
-| `transition` | `kind` | `dip` / `wash` / `paper` / `wipe` / `cut` / `iris` | `scenes._apply_veil`（段首 ≤0.45 s 内生效） |
-| | `dur` | 0–0.60 秒 | 同上；超过 0.60 s 会糊掉 3–6 s 节奏下限 |
-| `typography` | `tracking` | 0–8 px（字距；与主题自带字距相加） | `scenes._tracking` |
-| | `line_gap` | 1.15–1.55（行高倍数） | `scenes._gap` |
-| | `number` | `dim` / `serif` / `cn` / `block` / `roman` / `timecode` / `dot` / `gilt` | `scenes._number_text`（章节编号、列表序号、流程节点号） |
-| | `align` / `ratio` | `left`/`center`/`right`；display:body 字号比 1.0–3.6 | **已声明、visual_lint 会查、绘制器暂未读** |
-| `bias` | `x` / `y` / `inset` | px，如 `{"x": -150, "y": 80, "inset": 40}` | `scenes._bias`（整体重心偏移；`inset` 只作用于左对齐起点） |
-
-两条设计约束（改的时候别破）：
-
-1. **每条签名都要"能被剪影看出差别"**：只改颜色/字重/描边的项不算签名。
-2. **受单帧预算约束**：装饰必须在烘焙阶段合成进底版（`_plate`），逐帧只剩 copy/EXTENT；
-   禁每帧全屏 GaussianBlur（实测 30–60 ms）、全屏双线性 resize（29 ms）与全屏 RGBA paste
-   （实测 5.6 ms——0.9.0 就是栽在这，0.9.1 才改掉），预算 25 ms。
-
-### 9.3 8 套风格的签名摘要
-
-| 风格 | motion（ease / 呼吸） | motif（母题 / 密度） | transition | typography（字距 / 行高 / 编号） | bias(x,y,inset) |
-|---|---|---|---|---|---|
-| tech-deep | out3 / 0.85 | brackets / 1.00（四角 L 括角 + 刻度尺 + 扫描线） | dip 0.28 s | 0 / 1.30 / dim | (0, 0, 0) |
-| magazine | out5 / 0.50 | hairlines / 0.85（双横线页眉 + 栏间线 + 页码位） | wash 0.35 s | 2 / 1.34 / serif | (+60, −20, 0) |
-| paper | inOut3 / 0.42 | handdrawn / 1.00（手绘内框 + 胶带 + 印章） | paper 0.35 s | 1 / 1.36 / cn（一、二、三） | (−150, +80, 40) |
-| vivid | outBack / 1.10 | slabs / 1.00（粗色块 + 斜切 + 贴纸） | wipe 0.20 s | 1 / 1.26 / block | (0, +40, 0) |
-| mono | inOut3 / 0.35 | minimal / 0.55（极细线 + 直角框） | cut 0.00 s | 6 / 1.40 / roman | (0, 0, 0) |
-| cinema | inOut3 / 0.30 | letterbox / 1.00（上下遮幅 + 光斑） | dip 0.45 s | 3 / 1.38 / timecode | (0, +30, 0) |
-| lo-fi | out3 / 0.60 | signal / 0.90（信号条 + 时间戳） | wash 0.30 s | 1 / 1.36 / dot | (+60, −70, 0) |
-| epic | out5 / 0.28 | rays / 1.00（放射射线 + 金线框） | iris 0.40 s | 4 / 1.32 / gilt | (0, −30, 0) |
-| legacy | out3 / 0.85 | brackets / 1.00（detail 为空） | cut 0.00 s | 0 / 1.30 / dim | 不参与（走老绘制器） |
-
-`layout_cycle` 字段也写在每套里（版式轮换顺序），但**当前没有消费者**——
-按章节轮换版式的逻辑在 `STYLES[style]["layouts"]` 那一层（见 §5 与 SKILL §5.5）。
-
-### 9.4 `visual_lint` 查什么
-
-在 `--stage style` 就拦（`render.py` 解析风格时调用，坏配置直接 `SystemExit`），
-不用等渲到第 300 帧才发现"每段转场糊 1 秒"：
-
-| 检查 | 线 |
-|---|---|
-| `motif.kind` | 必须在 `VISUAL_MOTIFS` 的 8 个里 |
-| `transition.kind` | 必须在 `VISUAL_TRANSITIONS` 的 6 个里 |
-| `transition.dur` | 0–0.60 s |
-| `typography.number` | 必须在 `NUMBER_STYLES` 的 8 个里 |
-| `typography.ratio` | 1.0–3.6 |
-| `typography.tracking` | 0–8 px |
-| `typography.line_gap` | 1.15–1.55 |
-| `motif.density` | 0–1；为 0 只允许 `minimal` |
-| `motion.enter` | `(起, 止)` 且 0 < 起 ≤ 止 ≤ 1.6 s |
-| `motion.push` | 0–0.16（超过会把内容推出安全区） |
-
-`selfcheck` 第 53 条另查两件 `visual_lint` 查不到的：8 套签名齐全（motion / typography 都有），
-且**母题 / 转场 / 重心三元组不重复**（全同 = 这套语言只是复制粘贴）。
-
-剪影是否真的可区分，由 `tools/silhouette_qa.py`（门禁 G13）量：同内容同段落在两套风格下
-各渲 3 帧 → 灰度 → 480×270 → 四角亮度中位数三值化 → 比前景占比 F / 质心 (Cx,Cy) /
-四边覆盖率 B / 左右对称度 S；五项里任一项达标即 PASS（ΔF≥6pp、|ΔCx|≥8pp、|ΔCy|≥8pp、
-ΔB≥14pp、ΔS≥0.20），同一指标必须 3 帧全达标。当前实测 **28 对全过（同明暗族 12/12）**；
-改造前基线同族只过 8/12。
-
-### 9.5 加第 9 套风格时，视觉语言要补什么
-
-主题与风格包的 5 步见 §7；v0.9 起还要多做四步，**否则新风格在剪影上仍然只是换色**：
-
-1. **`stylekit.VISUAL_LANGUAGES["my-style"]` 写全五组**：motion（ease / enter / push /
-   breathe_hz）、motif（kind + density + detail）、transition（kind + dur）、
-   typography（tracking / line_gap / align / number / ratio）、bias（x / y / inset）。
-   照抄一套现有签名再改配色 = 白做，第 53 条会报"母题/转场/重心完全相同"。
-2. **母题不要临时发明新名字**：`motif.kind` 必须是 `VISUAL_MOTIFS` 里的 8 个之一。
-   确实需要新图形语言时，先在 `scenes._motif_layer` 里实现一个分支、加进 `VISUAL_MOTIFS`，
-   再在风格里引用——顺序反了会 `visual_lint` 直接拦。
-3. **跑 `python stylekit.py --lint`**（主题对比度）与**单独跑 `visual_lint`**
-   （写个三行的 `.py` 调 `stylekit.visual_lint("my-style")`，或直接 `--stage style`）。
-4. **跑剪影门禁**：`python tools/silhouette_qa.py --styles my-style,tech-deep,...`，
-   确认新风格与其余 8 套两两可区分；再跑 `selfcheck`（第 53 条会要求三元组不重复）。
-5. **看片**：`--stage stills` 渲 3 段亲眼确认母题/转场/字距不是"看着像另一套"——
-   数字过了不等于观感对了（铁律 6）。
-
+| 改了 `design.json` 画面没变 | 没重跑阶段 / 没重签核 | `render.py --stage explain` 看哪些阶段过时 |
+| `--stage style` 报「找不到设计」 | 工程里没有 `work/design.json` | 先 `propose.py --brief ... --script film.json --work work` 再 `--confirm` |
+| 手改 design 后 `--confirm` 报校验失败 | 字段越界/对比度不达标 | 按报错逐条修；或干脆 `--revise` 重出 |
+| 想"用某套预设当起点" | v1.0.1 已删除全部预设 | 没有这条路：现场采样 + `--revise` 表达要求，要复现用 `--seed` |
+| `render.py --preset x` 报错 | `--preset` 已删除 | 用 `--brief` 或直接写 design.json |
+| `stylekit.py --list` 只有一段说明、exit 2 | 内置风格表已删除（预期行为） | 看 `designkit.py --list-palettes` 的配色采样示例（那不是可选清单） |

package/skills/video-studio/references/v08-quality.md

@@ -80,7 +80,7 @@ python preflight.py --script film.json --work work --engine pil --json
 
 ### 2.3 阈值 92 / 96 是怎么来的（**只有一份权威定义**）
 
-判据来自 qavmaf 作者对**同一部模板片**（参考帧含字幕与片头片尾淡入淡出）的三组实测：
+判据来自 qavmaf 作者对**同一部示例片**（参考帧含字幕与片头片尾淡入淡出）的三组实测：
 crf17 → **97.24**（pass）、crf30 → **95.74**（pass + warning）、二次编码 + 缩放坏片 → **29.45**（fail）。
 
 **阈值只有一份**：权威定义是 `qavmaf.py` 的 `VMAF_PASS=92.0` / `VMAF_WARN=96.0`
@@ -124,7 +124,7 @@ qavmaf 会在报告里打 warning 提醒这一点，但**不因此改判**——
 
 | 项 | 实测 |
 |---|---|
-| 29.011 s 模板片全片（870 帧，1080p 交付） | **14.2 s**（同机负载高时同一份代码测到过 28.8 s，见下"成本口径"） |
+| 29.011 s 示例片全片（870 帧，1080p 交付） | **14.2 s**（同机负载高时同一份代码测到过 28.8 s，见下"成本口径"） |
 | 720p@24 交付（696 帧） | **7.2 s**（帧数少 + libvmaf 比较分辨率低） |
 | 分项吞吐 | 参考帧渲染受 ffmpeg 消费速度限制；libvmaf threads=min(8, CPU) 时约 124–160 帧/秒（threads=0 只有约 20 帧/秒） |
 | 抽样模式 | `--vmaf sample`（每 5 帧取 1）实测 8.0 s 跑完 184 帧，VMAF 与全片差 0.34 分 |
@@ -136,7 +136,7 @@ qavmaf 会在报告里打 warning 提醒这一点，但**不因此改判**——
 所以这里只写"这一跑"的数，不写承诺。纯 libvmaf 比较（参考帧已就绪）约 1.2× 实时——
 **别把"纯比较的 1.2×"当成端到端成本**。
 
-**v0.8 之后 qa 比渲染还贵**：29 s 模板片 `--stage all --cost` 实测总 **47.3 s**，
+**v0.8 之后 qa 比渲染还贵**：29 s 示例片 `--stage all --cost` 实测总 **47.3 s**，
 其中 `frames` 12.5 s、`qa` 23.9 s（VMAF 14.2 + ASR 8.7 + 其余）；v0.7 的全链约 28 s。
 决策影响：**批量出片的瓶颈从渲染转到质检**——想压回渲染量级就 `--vmaf off` 或 `--vmaf sample`。
 
@@ -188,13 +188,13 @@ v0.7 及以前的质检只看"容器 / 响度 / 帧 / 音画同步"，都建立
 
 ### 3.4 为什么默认线是 0.85 而不是 0.95
 
-实测（29 s 模板片，含 "DeepSeek 4.1 Flash / DeepSeek Harness" 这类中英混排专名）：
+实测（29 s 示例片，含 "DeepSeek 4.1 Flash / DeepSeek Harness" 这类中英混排专名）：
 
 | 场景 | 召回 |
 |---|---|
-| 干净模板片 1080p（4 段全对上、缺句 0） | **0.803** |
-| 干净模板片 720p@24（同剧本） | **0.853** |
-| 干净模板片（另一轮） | **0.811 – 0.828** |
+| 干净示例片 1080p（4 段全对上、缺句 0） | **0.803** |
+| 干净示例片 720p@24（同剧本） | **0.853** |
+| 干净示例片（另一轮） | **0.811 – 0.828** |
 | 丢句反证：把 l03 从音轨剪掉、timeline 仍写 3 句 | **0.677**（`missing_lines=["l03"]`、gate=fail、exit 1） |
 
 0.803–0.853 不是流水线坏了，是 ASR 对中英混排专名的正常误差——实测把 "DeepSeek 4.1 Flash"
@@ -203,7 +203,7 @@ v0.7 及以前的质检只看"容器 / 响度 / 帧 / 音画同步"，都建立
 
 - **< 0.72 才说明"整句丢了 / 音轨跟剧本不是一套"**——这是真正要阻断的；
 - 0.72–0.85 给 warning：仍然出片，但提示可能是缓存串了；
-- **≥ 0.95 会把干净的模板片判成 fail**，所以不能拿短测试片的 0.985（19.87 s 纯中文素材，
+- **≥ 0.95 会把干净的示例片判成 fail**，所以不能拿短测试片的 0.985（19.87 s 纯中文素材，
   没有专名）当默认线。
 
 ### 3.5 实测耗时

package/skills/video-studio/references/web-engine.md

@@ -164,7 +164,7 @@ PNG 截图比 JPEG q94 慢但无压缩伪影，本模块按契约固定 PNG。
 
 ## 10. 和别的模块怎么接
 
-- **配乐 / 音效**：webengine.py cues 输出 work/cues.json（§4.2），scorekit/sfxkit 按 t 对齐；
+- **配乐 / 音效**：webengine.py cues 输出 work/cues.json（§4.2），musicgen / sfxkit 按 t 对齐；
   页面 cue 的 type 用 sfxkit 配方名（ui_blip / whoosh / impact / data_chirp ...）。
 - **音画同步质检**：页面 S.event 登记的视觉事件进 work/cues.json 的 events，qa_frames.sync_check 用。
 - **合成成片**：webengine 只出无声画面；配音/配乐/混音由 filmkit 音频总线和 render.py 的 mux 阶段负责。

package/skills/video-studio/references/word-timeline.md

@@ -97,13 +97,13 @@ G10 会因此记 `skipped` 或 `fail`（看是全部为空还是个别句为空
 ### 4.1 词间有 0.1–0.3 s 的空隙
 
 edge-tts 的 WordBoundary 只覆盖"发音区间"，相邻词之间的停顿**不在任何事件里**。
-所以 `covered = Σ dur` 永远小于句长。模板片实测 4 句 64 词，覆盖率约 0.7 量级。
+所以 `covered = Σ dur` 永远小于句长。示例片实测 4 句 64 词，覆盖率约 0.7 量级。
 **判据不能写 `covered == dur`**——G10 的覆盖率下限是 **45%**（低于它才是"明显少了"）。
 
 ### 4.2 句尾静音不在事件里（约 0.5 s）
 
 排轴用的是**整句实测时长**，不是词时长求和。G10 只检查"末词终点离句尾不超过 **0.40 s**"
-（模板片实测 0.09 s）。这条超过 0.40 s，通常不是"片子坏了"，而是词事件本身整体错位了。
+（示例片实测 0.09 s）。这条超过 0.40 s，通常不是"片子坏了"，而是词事件本身整体错位了。
 
 ### 4.3 裁剪会让词整体提前（`words_shift`）