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

package/skills/video-studio/assets/voice_loudness.json

@@ -0,0 +1,16 @@
+{
+ "schema": 1,
+ "_comment": "音色响度补偿（数据，不是身份）：gain_db = 目标响度 - 该音色实测 rms_db，夹在 ±3 dB。换机/换 voice 必须重测（python voicekit.py --calibrate 会对表里的音色重新合成校准句）。designkit 与 voicekit 共用这一份：两处各存一份必然漂移——实测采样器会产出 4 把表里没有的音色。",
+ "target_dbfs": -20.97,
+ "voices": {
+  "zh-CN-YunyangNeural": 3.0,
+  "zh-CN-XiaoxiaoNeural": -2.7,
+  "zh-TW-HsiaoChenNeural": -3.0,
+  "zh-CN-XiaoyiNeural": -0.6,
+  "zh-CN-YunjianNeural": 1.0,
+  "zh-CN-YunxiNeural": 1.9,
+  "zh-CN-YunxiaNeural": 0.3,
+  "zh-CN-liaoning-XiaobeiNeural": 0.0,
+  "zh-CN-shaanxi-XiaoniNeural": -0.3
+ }
+}

package/skills/video-studio/references/appearance.md

@@ -0,0 +1,123 @@
+# 外观定制：设计 DSL 实操手册
+
+> **外观由 `work/design.json` 决定：`propose.py` 现场采样，你确认之后冻结。**
+> 没有现成外观目录可挑，也没有 `style` 字段——剧本不决定长相。
+> 同一份稿子换一份 design.json 就是另一种画面，反之亦然。
+> 这篇讲的是：**想控制画面的哪一块，就改 design.json 的哪个字段，怎么验证它真的生效。**
+
+## 0. 三条正确姿势
+
+| 你想要 | 怎么做 | 不要这样做 |
+|---|---|---|
+| 换一种气质 | `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（它不会） |
+
+## 1. design.json 的六块
+
+| 块 | 决定什么 | 字段 |
+|---|---|---|
+| `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` | 中文标签 / 立意 | 提案卡上显示的那一句话 |
+
+校验：`python <SKILL_DIR>/scripts/designkit.py --lint work/design.json`；
+契约：`<REPO>/schemas/design.schema.json`。**fail-closed**：缺字段/越界/对比度不达标一律报错，
+不会静默回落——设计层不允许「改了不生效也不报错」这种状态存在。
+（实测过 11 个静默失效的旋钮：`voice` 写字符串时 map/jitter 全失效、`pan` 对立体声配方无效……
+每个都"配置生效、画面不动"，且不报错。设计层改成一律报错，这类问题在 `--lint` 就暴露。）
+
+## 2. visual 字段表（能控制什么）
+
+| 字段 | 取值 | 改它会发生什么 |
+|---|---|---|
+| `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 种不同） | 按章节轮换版式；不写则自动派生 2–3 种 |
+| `hud` | `chip-left` / `corner-line` / `none` | 页眉/角落装饰 |
+| `size` / `fps` | `1920x1080` / `30` | 只支持 16:9 横屏（编码时可下采样到 720p） |
+| `subtitle` | 见 §3 | 字幕字号/位置/对齐/背板/圆角/字族/颜色/行数 |
+
+> **能组合出多少种画面？** 离散维度是 8 母题 × 6 转场 × 4 缓动 × 8 编号 × 3 版式 × 3 HUD × 4 字族
+> × 7 情绪 × 2 调式（= 774,144 种），再乘配色这个连续量（色相 0–360° 任意取值）。
+> 这个数字只说明"字段可组合空间足够大"，**不是推荐你从中挑**——好看与否仍由对比度体检、
+> 分镜语法和你的目检决定。
+
+## 3. 字幕样式（visual.subtitle）
+
+字幕的字号 / 位置 / 背板 / 圆角由设计 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 | 决定了折行上限 |
+
+验证：`render.py --stage style` 会打印一行「字幕: ... 对齐=... 背板α=... 圆角=... 最多N行」，
+改 design 后重跑这一行就能看重算结果，不用等渲完。
+
+## 4. 版式轮换（visual.layout_cycle）
+
+```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` 字段。
+
+## 5. 配色怎么改才不出事
+
+配色不是"挑一个好看的颜色"，而是 11 个角色要同时满足对比度：
+`theme_lint` 的门槛是 ink≥7 / muted≥4.5 / dim≥3 / accent≥4.5 / accent2≥4.5（good/bad≥3），
+另外要求 bg 与 bg2 有可感知的亮度差（防纯色底）。
+
+推荐两条路：
+
+1. **让采样器算**（默认）：采样器在 (hue, s, v) 网格里找满足全部门槛的点；
+   实测纯随机取色通过率 35%，网格求解 100%。
+2. **手改色相**：只改 `palette.bg` 的色相/饱和度，然后跑 `designkit.py --lint`；
+   过不了就调一档明度——报错会直接点名哪个角色不达标。
+
+> 片内**不要跨明暗族**：同一部片锁一个明暗族，段界跨族会整屏换底、触发闪烁门禁，观众也看着像换片。
+> 这条在采样器里是硬约束，手改 design 时请自己守住。
+
+## 6. 片内不重复：三层一起用
+
+| 层 | 机制 | 防的是什么 |
+|---|---|---|
+| 段内 | `lines[].type`（10 类构图，grammar 自动选） | 每段都长一个样 |
+| 章内 | `layout_cycle`（按章节轮换） | 全片一张版式 |
+| 片间 | 采样 nonce + 候选 ≥2 维 + 底色色相分叉 + **片间去重台账** | 不同片撞衫 |
+
+## 7. 常见误用
+
+| 现象 | 原因 | 修法 |
+|---|---|---|
+| 改了 `design.json` 画面没变 | 没重跑阶段 / 没重签核 | `render.py --stage explain` 看哪些阶段过时 |
+| `--stage style` 报「找不到设计」 | 工程里没有 `work/design.json` | 先 `propose.py --brief ... --script film.json --work work` 再 `--confirm` |
+| 手改 design 后 `--confirm` 报校验失败 | 字段越界/对比度不达标 | 按报错逐条修；或干脆 `--revise` 重出 |
+| 想"用某套预设当起点" | 没有预设目录，外观只由 design.json 决定 | 现场采样 + `--revise` 表达要求，要复现用 `--seed` |
+| `render.py --preset x` 报错 | render.py 没有 `--preset` 这个参数 | 用 `--brief` 或直接写 design.json |
+| `stylekit.py --list` 只有一段说明、exit 2 | 没有可选外观清单（预期行为） | 看 `designkit.py --list-palettes` 的配色采样示例（那不是可选清单） |

package/skills/video-studio/references/audio-variation.md

@@ -1,36 +1,36 @@
-# 音频多样性改造（v0.7）—— 接口契约
+# 音频差异机制 —— 接口契约
 
-> 起草：lead，2026-11-09。本文件是本次改造的**唯一定义源**。
-> 三路并行改动的文件写域不重叠，但**接口必须按本文件逐字实现**，否则集成会失败。
-> 诊断证据见 `tools/audio_similarity.py` 的输出（改完后必须重跑，阈值见 §5）。
+> 当前机制一句话：配乐由 `musicgen.py` 参数化编排（bpm/key/scale/mood/seed + 编排参数，
+> 内容指纹与编排参数共同决定和声/动机/鼓型）；音效 seed 由 `content_seed(base, style, content_fp, recipe, t)`
+> 按内容派生；提示音调性跟随配乐（`in_key`）；段落边界前 2.2 s 内的转场 cue 自动 -3 dB
+> （`sfx.duck_transitions`）；混音旁白优先（配乐 -12 dB 基线 + 语音侧链 6/3 dB + SNR 兜底 12 dB）。
+>
+> 阈值由 `tools/audio_similarity.py` 按 §5 判定，诊断证据就是它的输出。
 
 ## 1. 要解决的两个问题（都有实测数据）
 
 | 问题 | 实测 | 根因 |
 |---|---|---|
-| A. 跨视频配乐雷同 | 同风格/同 bpm/同调、只换内容指纹：corr **0.966** | 指纹只改 seed（音色细节），和弦进行/动机/鼓型/段落骨架全固定 |
+| A. 跨视频配乐雷同 | 同 bpm/同调/同编排参数、只换内容指纹：corr **0.966** | 指纹只改 seed（音色细节），和弦进行/动机/鼓型/段落骨架全固定 |
 | B. 跨视频音效雷同 | 同 cue 序列两次渲染逐样本相同 | `CueBus.build_audio` seed = `seed_base + i`，只跟 cue 顺序有关 |
 | C. 片内配乐与音效难分 | impact 质心 1001 Hz / whoosh 1589 Hz / music 5451 Hz；提示音硬编码 Dm 五声 | 提示音调性硬编码 + 配乐过门与 sfx 轨同边界同频段 + duck 仅 2.5–4.5 dB |
 
-## 2. 改动总览（按写域分三路）
+## 2. 各层由谁负责
 
-| 路 | 负责文件 | 改什么 |
+| 层 | 负责文件 | 做什么 |
 |---|---|---|
-| A 配乐变奏 | `skills/video-studio/scripts/scorekit.py` | 指纹参与**和声/动机/鼓型/结构**，不再只影响音色细节 |
-| B 音效差异化 | `skills/video-studio/scripts/sfxkit.py`、`assets/scenes.py`、`assets/film.json` | `in_key` 跟随配乐调性；`cues()` 按画面内容生成；模板 cue 去固定化 |
-| C 接线与混音 | `skills/video-studio/scripts/filmkit.py`（lead）、`render.py`（lead）、`stylekit.py`（只读）、`selfcheck.py`（lead） | CueBus 内容派生 seed、调性传给 sfxkit、duck 加深、风格过门避让 |
-
-**写域规则**：A 路只改 scorekit.py；B 路只改 sfxkit.py / assets/scenes.py / assets/film.json；
-C 路由 lead 改 filmkit.py / render.py / selfcheck.py。**任何一路不得改别人的文件**（包括顺手"优化"）。
+| 配乐编排 | `skills/video-studio/scripts/musicgen.py` | 按 bpm / key / scale / mood / seed 编排；`sections` / `progressions` / `motif` / `drums` / `voices` / `energy_curve` 真的参与事件展开；内容指纹进 seed 与变奏参数 |
+| 音效差异化 | `skills/video-studio/scripts/sfxkit.py`、`assets/scenes.py`、`assets/film.json` | `in_key` 跟随配乐调性；`content_seed` 内容派生 seed；`cues()` 按画面内容生成；夹具 cue 不固定三条 |
+| 接线与混音 | `skills/video-studio/scripts/filmkit.py`、`render.py`、`selfcheck.py` | CueBus 内容派生 seed、调性透传、duck 分级、过门避让、旁白优先 |
 
 ## 3. 接口契约（逐字实现，向后兼容）
 
-### 3.1 sfxkit（B 路）
+### 3.1 sfxkit
 
 ```python
-# 1) 调性跟随：新增 key 参数，默认 None = 旧行为（Dm 五声）
+# 1) 调性跟随：key 参数，默认 None = 固定 D 小调五声
 def in_key(freq: float, key: str | None = None) -> float:
-    """key=None -> 旧行为（硬编码 D 小调五声，逐样本兼容）。
+    """key=None -> 固定 D 小调五声（不随配乐调性变，逐样本可复现）。
     key 给 "Dm"/"C"/"Am"/... -> 吸附到该调（小调用自然小调五声，大调用大调五声）。"""
 
 # 2) 所有走 in_key 的配方接受 key（通过 **kw 透传，签名末位加 key=None 或直接从 kw 取）：
@@ -39,121 +39,102 @@ def in_key(freq: float, key: str | None = None) -> float:
 
 # 3) 内容派生 seed 的辅助函数（供 filmkit.CueBus 用）
 def content_seed(base: int, style: str, content_fp: str, recipe: str, t: float) -> int:
-    """稳定的 32 位非负 int：sha1(\"v0.7|%d|%s|%s|%s|%.3f\") -> int(h[:8],16)%9000+1000。"""
+    """稳定的 32 位非负 int：sha1("<固定盐>|<base>|<style>|<content_fp>|<recipe>|<t 三位小数>")
+    -> int(h[:8], 16) % 9000 + 1000。"""
 ```
 
-### 3.2 filmkit.CueBus.build_audio（C 路，lead）
+`<固定盐>` 是代码里写死的字符串常量：`sfxkit.content_seed` 与 `filmkit.content_seed` 逐字相同。
+要复刻就照抄实现里的拼接串，**不要自己另拼一份**——换个盐等于换一套 seed，
+"A1 同参数换指纹可区分"的验收直接失效。
+
+### 3.2 filmkit.CueBus.build_audio
 
 ```python
 def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
                 seed_base=1000, verbose=True,
-                style=None,           # 风格 id；None = 旧行为
-                content_fp=None,      # 内容指纹 full；None = 旧行为
-                key=None):            # 配乐调性；None = 旧行为（sfxkit 用 Dm）
+                style=None,           # 设计标识（design:<hash>）；None = 位置派生
+                content_fp=None,      # 内容指纹 full；None = 位置派生
+                key=None):            # 配乐调性；None = 提示音按 D 小调五声
     """每条 cue 的 seed：
-       - style/content_fp 任一为 None -> seed = seed_base + i（旧路径，逐样本兼容）
+       - style / content_fp 任一为 None -> seed = seed_base + i（位置派生，逐样本可复现）
        - 都给 -> seed = sfxkit.content_seed(seed_base, style, content_fp, kind, t)
     并把 key 透传给配方（render(kind, seed=..., key=key, **params)）。"""
 ```
 
-### 3.3 scorekit.render_styled（A 路）
-
-签名不变。**内部**行为变化：
-
-- `full` 指纹（已有 `fingerprint` 参数，当前只用于 seed）必须影响**和声与动机**：
-  - 和弦替换：按指纹从该风格的 `progressions` 里选 tier，再对**每两小节**做一次稳定替换
-    （从同大小的替代级数集里挑：i↔i7 / VI↔VI7 / III↔III7 / VII↔VII7；大调侧 I↔Imaj7 / IV↔IVmaj7）。
-    只在与乐句末/片尾规则不冲突时替换。
-  - 动机变形：`motif` 的每个 (拍, 级数, 时值) 按指纹做 **±1 级数的稳定偏移**，
-    只改级数不改节奏；问题句偏移与答句偏移必须独立派生（保证两部片子不会同步变形）。
-  - 鼓型：`drums[tier]` 的 kick 落点按指纹加 **最多一个 ghost 落点**（在 0.5 拍网格上，
-    不与现有落点重复）；clap 位置按指纹 ±0.5 拍。
-- **必须保证**：同 `fingerprint` 逐采样一致；不同 fingerprint 的相关性显著下降（§5 阈值）。
-- 新增报告字段：`variation`（dict：`{"chord_swaps": n, "motif_shifts": n, "drum_ghosts": n}`），
-  写进 work/score.json，方便审计。
-- legacy 路径（style=None）**逐字节不变**（`scorekit.py --selftest` 的第 20 条会验；
-  别和 `selfcheck.py` 的编号搞混——那边第 21 条只查 scorekit 同 seed 确定性）。
+`render.py` 的 `_sfx_seed_context` 就是这条的调用方：它从 `resolve_style` 解出的设计计划里取
+`style` / `fingerprint.full` / `music.key`；`sfx.content_seed=false`（或计划里没有指纹）时返回全 None，
+`build_audio` 于是走位置派生。
 
-### 3.4 assets/scenes.py 的 cues()（B 路）
+### 3.3 assets/scenes.py 的 cues()
 
-现在只出 `ui_blip × items` + `answer_chime × outro`。改为按画面事件生成，并且**类型按场景 kind 与内容变化**：
+按画面事件生成，**类型按场景 kind 与内容变化**：
 
 - `hook`：段首 `impact`（size 按字数 0.9~1.3），落定 `riser`。
-- `body`：条目落位仍用 `ui_blip`，但 **pitch 由条目文本 sha1 派生**（json 的 items 文本）；
+- `body`：条目落位用 `ui_blip`，但 **pitch 由条目文本 sha1 派生**（json 的 items 文本）；
   最后一个条目后加 `answer_chime`（若 kind=body 且 items≥3）；段尾 `whoosh`（going 到下一段）。
 - `quote`：`reverse_swell` + 落定 `impact`（轻）。
 - `outro`：`answer_chime` + 片尾 `sub_drop`。
-- 不许再出现"每段都一样的三连击"：同类型 cue 在一段内重复时，`gain` 必须递减（-2/-4/-6），pitch 必须不同。
-- **保持向后兼容**：仍有 `stagger` 对齐逻辑（与 _draw_items 同节拍），返回 schema 不变。
+- 不许出现"每段都一样的三连击"：同类型 cue 在一段内重复时，`gain` 必须递减（-2/-4/-6），pitch 必须不同。
+- **对齐**：stagger 对齐逻辑（与 `_draw_items` 同节拍）保留，返回 schema 不变。
 
-### 3.5 assets/film.json 模板（B 路）
+### 3.4 assets/film.json 夹具
 
-模板里的 `sfx.cues` 固定三条 whoosh/riser/impact 是"跨片雷同"的直接来源之一。改为：
+模板里的 `sfx.cues` 只保留 1 条转场 whoosh 作为示例，并注明"具体提示点交给 `scenes.py` 的 `cues()` 钩子"
+（固定三条 whoosh/riser/impact 是"跨片雷同"的直接来源之一）。
 
-- 模板只保留 1 条转场 whoosh 作为示例，并加注释说明"具体提示点建议交给 scenes.py 的 cues() 钩子"。
-- `sfx` 增加可选字段 `content_seed: true`（默认 true）：走内容派生 seed；显式 false 回到旧行为。
+- `sfx` 的 `content_seed: true`（默认）：走内容派生 seed；显式 `false` 回到 `seed_base + i`。
 
-## 4. render.py 接线（C 路，lead）
+## 4. render.py 接线
 
-- `st_score`：把 `plan_s["music"]["key"]` 与 `plan_s` 的 `fingerprint` 传给 sfx 阶段（经 `script["_style"]`）。
-- `st_sfx`：读 `script["_style"]`，把 `style` / `content_fp` / `key` / `sfx.content_seed` 传给
-  `bus.build_audio(...)`；没有 `_style`（legacy）时不传，保持旧行为。
-- `st_audio`：duck 默认值改为按风格：在现有表基础上整体 +1.0 dB，且 `music.duck_db` 显式值仍然优先。
-  另外新增**过门避让**：`scorekit` 的过门音效已经在 music.wav 里，sfx 轨在
-  [段落边界 - 2.2s, 边界] 区间内的 whoosh/riser/reverse_swell 需要自动 -3 dB（在 filmkit 里做，
-  或 st_sfx 后处理；由 lead 决定实现位置，**B 路不要碰**）。
+- `_sfx_seed_context`：从设计计划取 `style` / `fingerprint.full` / `music.key`；
+  `sfx.content_seed=false` 或计划没有指纹时返回全 None -> `build_audio` 走位置派生。
+- `st_sfx`：把上面三样传给 `bus.build_audio(...)`；`sfx.duck_transitions`（默认 true）
+  决定是否做过门避让。
+- `st_audio`：duck 默认值按风格分级——`mono` 3.0 / `lo-fi`、`magazine` 3.5 / `cinema`、`epic` 5.5 /
+  其余 4.0；`music.duck_db` 显式值永远优先。
+  另外**过门避让**：配乐在 music.wav 里已经有段落过门，sfx 轨在
+  [段落边界 - 2.2s, 边界] 区间内的 whoosh/riser/reverse_swell 需要自动 -3 dB
+  （`_duck_transition_sfx` 实现，`sfx.duck_transitions=false` 可关）。
 
 ## 5. 验收阈值（改完必须重跑 `python <REPO>/tools/audio_similarity.py`）
 
-| 指标 | 改前 | 目标 | 落地实测（2026-11-09） |
+| 指标 | 目标 | 实测 | 不这么做时 |
 |---|---|---|---|
-| A 同风格换指纹 corr | 0.966 | **≤ 0.85**（仍要像同一风格，但不能像同一首） | **0.645** |
-| A 换风格 corr | 0.534 | ≤ 0.52（不能变得更像） | **0.514**（v0.7.2 复测，余量 0.006；连跑 3 次逐位相同。余量薄是有意的：抬到 0.53 就离改造前的 0.534 只剩 0.004，这条门禁就没意义了） |
-| B 同 cue 序列跨片逐样本相同 | True | **False**（不同内容指纹必须不同） | False（同 fp 仍逐样本相同） |
-| B legacy（不传 style/fp） | True | **必须仍为 True**（向后兼容） | True |
-| C duck 默认 | 2.5–4.5 dB | 3.5–5.5 dB | 4.0（mono 3.0 / cinema 5.5） |
-| D 人声段旁白/背景响度差 | 约 1.5 dB（配乐 -1.5 无侧链） | **≥ 12 dB** | **15.0 dB** |
-| D 旁白处背景额外让位 | 0 | ≥ 4 dB | 6.0 dB |
-
-> v0.7.1 追加 D 组（旁白优先）：视频以旁白为主，BGM 与音效是可选层。`mix_film` 的
+| A1 同参数换内容指纹 corr | **≤ 0.85**（仍要像同一部片子，但不能像同一首） | **0.645** | 0.966 |
+| A2 换编排参数 corr | ≤ 0.52（不能变得更像） | **0.514**（连跑 3 次逐位相同） | 0.534 |
+| B1 同 cue 序列跨片逐样本相同 | **False**（不同内容指纹必须不同） | False（同 fp 仍逐样本相同） | True |
+| B2 位置派生（不传 style/fp） | **必须仍为 True**（向后兼容） | True | — |
+| C1 duck 默认 | 3.5–5.5 dB | 4.0（mono 3.0 / cinema 5.5） | 2.5–4.5 dB |
+| D1 人声段旁白/背景响度差 | **≥ 12 dB** | **15.0 dB** | 约 1.5 dB（配乐 -1.5、无侧链） |
+| D2 旁白处背景额外让位 | ≥ 4 dB | 6.0 dB | 0 |
+
+> A2 的余量只有 0.006，是有意的：抬到 0.53 就离 0.534 只剩 0.004，这条门禁就没意义了。
+> D 组守的是"旁白优先"：视频以旁白为主，BGM 与音效是可选层。`mix_film` 的
 > `voice_duck_db=6` / `voice_duck_sfx_db=3` + `music.gain_db=-12` 把"人声比背景响 12 dB"
 > 从文档口号变成可执行断言（selfcheck 35/36 条 + 本脚本 D 组）。
 
-**已知边界（不是回归，是设计取舍）**：同风格不同内容指纹有约 1/3 概率落到同一个
-和弦进行档位偏移上，此时两段配乐 corr 约 0.93（只剩七和弦色彩与鼓型 ghost 的差别）。
-要再压下去需要"每段独立选档"或"同档时轮转"，会削弱"片内是一条曲子"的连贯性，
-本轮不做；`--strict` 用固定的 content-a / content-b 做验收，两者落在不同档。
-
 另有硬性回归（任何一条红都不算完成）：
 
-> 下面 1–4 的路径都按**仓库根**写（`python skills/video-studio/scripts/…`）；如果你已经 `cd` 进技能目录，
+> 下面 1–5 的路径都按**仓库根**写（`python skills/video-studio/scripts/…`）；如果你已经 `cd` 进技能目录，
 > 去掉 `skills/video-studio/` 前缀即可。`<REPO>` = 仓库根 / 装好后的包根。
 
-1. `python skills/video-studio/scripts/selfcheck.py` 全 PASS（现在 55 条；v0.7.2 时的 43 条、v0.8 的 51 条是旧的）。
-2. `python skills/video-studio/scripts/scorekit.py --selftest` 全 PASS。
-3. `python skills/video-studio/scripts/sfxkit.py --selftest` 全 PASS。
+1. `python skills/video-studio/scripts/selfcheck.py` 全 PASS（**69 条**）。
+2. `python skills/video-studio/scripts/musicgen.py --selftest` 全 PASS（26 项）。
+3. `python skills/video-studio/scripts/sfxkit.py --selftest` 全 PASS（16 条）。
 4. `python <REPO>/tools/ci_check.py` 全 PASS（在包根执行）。
-5. legacy 逐样本不变：`scorekit.py --selftest` 第 20 条 + `selfcheck.py` 第 26（风格 legacy）/33（音效 legacy）条，**这些断言不要改**。
-
-## 6. 协作规则
+5. 音效位置派生的逐样本可复现：`selfcheck.py` 守着这条（`sfx.content_seed=false` 时与 `seed_base + i` 同值）。
 
-- 每个 teammate 只跑自己文件的 `--selftest`，**全量 selfcheck / ci_check 由 lead 统一跑**（避免并行抢 CPU 和临时目录）。
-- 改完在 `CHANGELOG.md` 追加的条目由 lead 统一写（teammate 不要改 CHANGELOG）。
-- 任何接口拿不准的地方，按本文件逐字实现；本文件没写的自由发挥请控制在"不改变签名"的范围内。
-- 完成后向 lead 报告：改了哪些函数、自测输出摘要、与契约的偏差（如果有）。
+## 6. 实现备注
 
-## 7. 实现备注（落地后回填，2026-11-09）
+几处落地细节（不改契约本身）：
 
-三路改动全部落盘后，实测与契约之间的**已知偏差**都记在这里（不改契约本身）：
-
-| 项 | 契约原文 | 实际实现 | 判断 |
-|---|---|---|---|
-| 配乐 tier 选择 | §3.3 只列了和弦替换/动机偏移/鼓型 ghost | 额外让指纹从 `progressions` 的 calm/body/drive 三档里选一档（该风格自带的三套进行，不发明新和弦） | 接受：单靠七和弦替换压不到 0.85，实测换 tier 后 0.966 → 0.645；仍是"同风格同一套素材" |
-| `roulette_tick` 调性 | §3.1 列进"走 in_key 的配方" | v0.6 本来没走 in_key；实现为 key=None 保持旧公式、key 非空才吸附 | 接受：不破坏 legacy 逐样本 |
-| 同段重复 cue 的 gain | §3.4 写 -2/-4/-6 | 每次再降 2 dB 不封顶（items 很多时会到 -2n） | 待观察：模板 5 条时最末一条 -8 dB；若听感偏轻改 `_cue_gain_decay` 一行 |
-| `content_seed` 实现位置 | §3.1 放 sfxkit | filmkit 与 sfxkit 各有一份逐字相同的实现（filmkit 走函数内延迟 import，模块级 from 会改导入时机） | 接受：两侧同参同值已核对；注释互相指认 |
+| 项 | 现状 |
+|---|---|
+| `content_seed` 实现位置 | `filmkit` 与 `sfxkit` 各有一份逐字相同的实现（`filmkit` 走函数内延迟 import，模块级 `from` 会改导入时机）；两侧同参同值 |
+| 同段重复 cue 的 gain | 每次再降 2 dB、不封顶（items 很多时会到 -2n）；模板 5 条时最末一条 -8 dB；要改听感就改 `_cue_gain_decay` 一行 |
+| `roulette_tick` 调性 | `key=None` 走原公式（D 小调五声）；`key` 非空才吸附 |
 
-**回归基线**（改前先录、改后逐条比对）：
+**回归基线**：
 
 - sfxkit 9 条渲染的 sha256（ui_blip ×3 / answer_chime / text_stream ×2 / data_chirp / roulette_tick ×2）逐条相同。
-- scorekit legacy 路径（style=None）6 s 渲染逐样本与 v0.6 相同。
+- scorekit 的 `render()` 只承担合成原语（成片配乐走 musicgen）：同 seed 逐样本一致（`scorekit.py --selftest` 第 18 条）。