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

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

@@ -0,0 +1,141 @@
+{
+ "schema": 1,
+ "id": "fixture-golden",
+ "label": "金帧基准设计",
+ "pitch": "验收基准：固定设计，用于像素回归（不是给人看的方案）",
+ "structure": {
+  "segments": 4,
+  "beats": [
+   "hook",
+   "body",
+   "body",
+   "outro"
+  ],
+  "hold_policy": "readable",
+  "target_sec": 30.0
+ },
+ "visual": {
+  "palette": {
+   "bg": [
+    7,
+    14,
+    26
+   ],
+   "bg2": [
+    17,
+    33,
+    54
+   ],
+   "surface": [
+    26,
+    42,
+    64
+   ],
+   "ink": [
+    230,
+    216,
+    207
+   ],
+   "muted": [
+    178,
+    157,
+    143
+   ],
+   "dim": [
+    153,
+    135,
+    122
+   ],
+   "accent": [
+    230,
+    106,
+    23
+   ],
+   "accent2": [
+    92,
+    230,
+    216
+   ],
+   "good": [
+    71,
+    178,
+    98
+   ],
+   "bad": [
+    178,
+    97,
+    89
+   ],
+   "rule": [
+    255,
+    255,
+    255
+   ]
+  },
+  "family": "sans",
+  "typography": {
+   "tracking": 0.0,
+   "line_gap": 1.3,
+   "number": "dim",
+   "ratio": 1.5,
+   "align": "left"
+  },
+  "motif": {
+   "kind": "brackets",
+   "density": 1.0,
+   "detail": {}
+  },
+  "transition": {
+   "kind": "dip",
+   "dur": 0.28
+  },
+  "motion": {
+   "ease": "out3",
+   "enter": [
+    0.45,
+    0.85
+   ],
+   "push": 0.04,
+   "breathe_hz": 0.85
+  },
+  "bias": {
+   "x": 0,
+   "y": 0,
+   "inset": 0
+  },
+  "layout": "left-stack",
+  "hud": "chip-left",
+  "size": "1920x1080",
+  "fps": 30
+ },
+ "audio": {
+  "voice": {
+   "mode": "edge_id",
+   "id": "zh-CN-YunyangNeural",
+   "map": {},
+   "jitter": 0.0,
+   "max_distinct": 1
+  },
+  "music": {
+   "mode": "params",
+   "style": "tech-deep",
+   "scale": "minor",
+   "bpm": 96.0,
+   "key": "Dm",
+   "mood": "steady",
+   "seed": 7
+  },
+  "sfx": {
+   "enabled": false,
+   "density": "none",
+   "gain_db": -6
+  }
+ },
+ "pacing": {
+  "lead": 0.62,
+  "tail": 0.92,
+  "min_dur": 3.0,
+  "hold": 0.0,
+  "item_stagger": 0.3
+ }
+}

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

@@ -1,8 +1,7 @@
 {
- "_comment": "v0.5 模板：style 决定画风+配乐+旁白+节奏。'auto' = 按内容自动选；写死风格 id 可锁定（tech-deep/magazine/paper/vivid/mono/cinema/lo-fi/epic）。删掉 style 字段 = 回到 v0.4 行为（逐样本兼容）。节奏（lead/tail/min_dur/hold）默认由风格给，想覆盖就自己加字段。",
+ "_comment": "自测/演示样例剧本（仓库测试夹具，不是给用户抄的模板）。外观由 work/design.json 决定（propose.py --brief 现场生成后 --confirm 冻结）；v1.0.1 起 style 字段已废弃。文本仅用于跑通全链与金帧/门禁回归，换题材请自己写 lines[]。",
  "title": "测试片 demo",
  "end_text": "完",
- "style": "auto",
  "voice": "zh-CN-YunxiNeural",
  "rate": "+6%",
  "pitch": "+0Hz",

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

@@ -9,6 +9,7 @@
  "fps": 30,
  "script": "skills/video-studio/assets/film.json",
  "scenes": "skills/video-studio/assets/scenes.py",
+ "design": "skills/video-studio/assets/design_fixture.json",
  "font_fp": "05c853d0eb28bcca3125d81c1ce27c9436f66a55",
  "fonts": [
   {
@@ -33,11 +34,13 @@
   "platform": "Windows 11"
  },
  "inputs": {
-  "script_sha1": "2f375a7298ea861684a2d553cb6617ed4351d3e5",
-  "scenes_sha1": "aab9df135ce5a7a3f2750d275dfcdac48405d4a4",
-  "filmkit_sha1": "a582ad1a2b53cf1ae163ab3052d054bc196c7d49",
-  "stylekit_sha1": "4bcbce2048b89c66352455f6e82c0943cc2e0508",
-  "golden_tool_sha1": "17cdc5d64705d54c157cf86f76899393a5d0b8c4"
+  "script_sha1": "9ad24749d19cf0fcec1b7fa62e906ed78ce5501b",
+  "scenes_sha1": "1ff8eaeed66c226a48875580d96d41ff6daad1e3",
+  "filmkit_sha1": "aca2f742ee4e7f7f2e99901a151864d8046d1547",
+  "stylekit_sha1": "869098c23a1d9e704a0ffacbc58da6c987712817",
+  "design_sha1": "f87cc13e4c55040d9de5675933c01aa8220134d1",
+  "designkit_sha1": "074b9705ae0f90a8b35162946142f8c28a3a39db",
+  "golden_tool_sha1": "da09795aaf3cb92bc9e14f9561bb64027917acbf"
  },
  "frames": [
   {
@@ -45,21 +48,21 @@
    "scene": "l01",
    "t_local": 1.2,
    "label": "hook",
-   "sha256": "ee2a70067aeaee0c158c7eef6c26c1228354bf247f05f7330c991ef1946aaaae"
+   "sha256": "155eaa030a519b7ded1c49664e0007314f2a4dc4eb6ef1e4b69d3b70bae0b367"
   },
   {
    "frame": 270,
    "scene": "l03",
    "t_local": 1.6,
    "label": "body",
-   "sha256": "ead954c01f5498782b3a31b8e42638d4f8f42e2faca97df476e0d78a1f9f72f8"
+   "sha256": "9d205ae43f2632c78446d372d8f3194ecfb7a9634ca42c36943ce31fd6be7981"
   },
   {
    "frame": 369,
    "scene": "l04",
    "t_local": 1.5,
    "label": "outro",
-   "sha256": "10463a35429185e7b816fd5ede7107d529e26f4ec8d8640fba84d9897cc77f66"
+   "sha256": "c3ccdbedc567402728677f9f4d7ccf62bb98930bebf52934b8bb2becb0e9fb4f"
   }
  ]
 }

package/skills/video-studio/assets/scenes.py

@@ -1,20 +1,26 @@
 # -*- coding: utf-8 -*-
-"""scenes.py — 场景绘制模板（v0.5.0：画风随内容变化）。
+"""scenes.py — 技能内置的场景渲染器（v1.0.2：默认渲染路径 + 自定义场景的范例）。
+
+⚠ 这**不是**给用户拷走改的模板：v1.0.2 起 render.py 不写 --scenes 时会自动回落到本文件，
+用户工程目录里只需要一个 film.json。想改画面时，在剧本同目录放一个自己的 scenes.py
+（或 --scenes 显式指定），它会被优先发现；本文件就是那份自写场景的**参考实现**：
+10 类构图 / 8 种母题 / 6 种转场 / 35 字段主题 / 版式轮换 / 字幕参数全部从计划里读。
 
 唯一约定：提供 draw_frame(scene, t_local, dur, t_global, script, frame) -> PIL.Image
-  scene   : timeline.json 里的一段（含 id/text/sub/start/end/dur）
+  scene   : timeline.json 里的一段（含 id/text/sub/start/end/dur 与 grammar 注入的
+            scene_type / scene_variant / scene_decor / scene_layout / scene_reason）
   t_local : 本段内已经过秒数
   dur     : 本段总秒数
   t_global: 全片秒数
+  script  : 剧本 dict（含 _style 计划、_total 总时长）
   frame   : 全片帧号（确定性：同一帧号必须画出同一张图）
 
-v0.5.0 画风主题化
-----------------
-剧本里写了 style（或 render.py 把 stylekit 解析出的计划塞进 script["_style"]）时，
-本文件从 stylekit 的主题包里取配色 / 材质 / 字体族 / 版式 / 缓动 / HUD / 镜头缓推，
-8 套风格各长一个样（深蓝科技 / 暖白杂志 / 手绘纸感 / 活力撞色 / 极简黑白 /
-电影青橙 / 暖灰薄荷 / 深黑鎏金）。没写 style 的老项目 = legacy：
-走下面原封不动的 v0.4 绘制函数，逐字节可复现（基线三帧 sha256 由 selfcheck 比对）。
+画风从哪来
+----------
+render.py 把 designkit.design_to_plan() 的计划塞进 script["_style"]（主题 / 视觉语言 /
+版式轮换 / 配乐 / 声线 / 节奏 / 字幕样式）。本文件从这份计划里取配色、材质、字体族、
+版式、缓动、HUD、镜头缓推——**没有任何内置风格表**（v1.0.1 已全部删除）：
+同一份代码画出来是什么样，完全由现场采样并确认过的 design.json 决定。
 
 铁律（决定画质与可复现性）：
   1. 不许用 random / time.time()；要随机用 K.hash2 / K.hash3 / vnoise(seed)
@@ -271,11 +277,31 @@ def _plan(script):
     return got
 
 
+# 主题里这些键的值是 RGB，统一要 (r,g,b) 元组。JSON 往返会把它变成 list，
+# 而 list 不能当缓存键 —— _soft_dot / _bg 之类的 key 里都带着颜色，一旦错位就是
+# "unhashable type: 'list'"。实测触发路径：--stage frames --jobs N 把 script 写成
+# _script_snapshot.json，子进程读回来重建，于是 theme.bg 是 [8,8,10]。
+# 修在**入口**（_scene_theme）而不是每个缓存点：缓存点会越加越多，入口只有一个。
+_THEME_RGB_KEYS = ("bg", "bg2", "surface", "ink", "muted", "dim",
+                   "accent", "accent2", "good", "bad", "rule", "vignette_tint")
+
+
+def _freeze_theme(th):
+    """把主题里的颜色值统一成元组（就地不重复建字面量的前提下返回新 dict）。"""
+    out = dict(th)
+    for k in _THEME_RGB_KEYS:
+        v = out.get(k)
+        if isinstance(v, (list, tuple)) and len(v) >= 3:
+            out[k] = (int(v[0]), int(v[1]), int(v[2]))
+    # scale / card / qa 是嵌套 dict，外面只读不建缓存键，原样保留
+    return out
+
+
 def _scene_theme(plan, scene):
     """本段用哪套主题：全片主题 + 可选的 scene["theme"] 覆盖（只许同明暗族）。"""
     base = plan.get("theme")
     if isinstance(base, dict):
-        th = dict(base)
+        th = _freeze_theme(base)
     else:
         th = dict(ST.THEMES[plan["theme_id"]])
     sid = scene.get("theme")
@@ -293,7 +319,7 @@ def _scene_theme(plan, scene):
                    "场景 %r 想从主题 %s 换到 %s，两者明暗族不同（同片换族会触发闪烁门禁），已忽略"
                    % (scene.get("id"), th.get("id"), sid))
         return th
-    return dict(alt)
+    return _freeze_theme(alt)
 
 
 # ---------------- 包内小工具 ----------------
@@ -1194,13 +1220,19 @@ def _draw_hero(scene, t, dur, tg, script, frame, plan, th):
     lh = int(size * gap)
     ksize = int(th["scale"]["kicker"][0])
     kicker = scene.get("kicker") or "00 · 开场"
+    y = float(lay["title_y"]) + bdy
 
+    # kicker 的纵向位置必须**跟着标题字号走**，不能直接用布局表里的固定 y。
+    # 为什么：布局表给的是 left-stack 的 title_y=300 / kicker_y=250，只差 50px；
+    # 而 hero 的标题字号是 96px（display 档），字形往上顶穿 kicker —— 实测封面上
+    # "00 · 开场"直接压在"价值与代价来自同一个选择"中间。
+    # 按字号算间距后，换字体/换字号档（visual 语言包会改 ratio）都不会再压。
+    _ky = min(float(lay["kicker_y"]), y - size * 1.05 - ksize * 0.35)
     p0 = ease(rng(t, 0.05, 0.85))
     _draw_text(img, th, v, kicker, ax + _entrance_x(th, p0, align),
-               float(lay["kicker_y"]) + _entrance_y(th, p0), ksize, "bold",
+               _ky + _entrance_y(th, p0), ksize, "bold",
                th["accent"], align, p0, trk * 0.5)
 
-    y = float(lay["title_y"]) + bdy
     for i, ln in enumerate(lines):
         p = ease(rng(t, 0.12 + 0.13 * i, 0.88 + 0.13 * i))
         _draw_text(img, th, v, ln, ax + _entrance_x(th, p, align),
@@ -1513,10 +1545,23 @@ def _draw_stat(scene, t, dur, tg, script, frame, plan, th):
         d.rectangle([v.x(bx + i * (bw + gapb)), v.y(760), v.x(bx + i * (bw + gapb) + bw),
                      v.y(768)], fill=_rgba(th["accent"] if on else th["rule"],
                                            int((150 if on else 34))))
+    # 次要统计：**数值 + 单位 + 标签**都要画出来。
+    # v1.0 修：早先这里只画了 s["label"]，于是 stats[] 里的第 2、3 项（例如
+    # "338207 次 / 工具调用"、"22.62 B / Token 重放"）在画面上只剩两个光秃秃的词，
+    # 并且行距 30px < 字号，两行直接叠在一起 —— 观众看到的是"工具调用/Token 重放"两行字
+    # 糊在一块、数字完全消失。数字卡的价值就在数字，丢数字等于这段白做。
+    nsize = int(th["scale"]["body"][0] - 6)
+    step = int(nsize * 1.75)          # 行距必须大于字号，否则相邻两行会压在一起
     for j, s in enumerate(notes):
         pn = ease(rng(t, 0.6 + 0.15 * j, 1.3 + 0.15 * j))
-        txt = str(s.get("label") or "")
-        _draw_text(img, th, v, txt, W * 0.5, 800.0 + j * 30, int(th["scale"]["body"][0] - 6),
+        val = str(s.get("value") if s.get("value") is not None else "").strip()
+        unit = str(s.get("unit") or "").strip()
+        lbl = str(s.get("label") or "").strip()
+        head = val + ((" " + unit) if unit else "")
+        txt = (head + "  " + lbl) if head else lbl
+        if not txt:
+            continue
+        _draw_text(img, th, v, txt, W * 0.5, 796.0 + j * step, nsize,
                    "reg", th["muted"], "center", pn)
 
     img = _apply_veil(img, th, lang, scene, t, s_bg)
@@ -2003,18 +2048,18 @@ _KIND_TO_TYPE = {
 def draw_frame(scene, t_local, dur, t_global, script, frame):
     """按帧画一张 1920x1080 RGB 图。
 
-    派发顺序（v0.9）：
-      1. legacy（film.json 没有 style 字段）-> v0.4 三个老绘制器，逐字节不变；
-      2. 非 legacy -> 按 scene_type（grammar.py 选好、render.py 写进 timeline）派发到
-         10 类构图之一；没有 scene_type 的旧 timeline 按 kind 映射到兼容类型。
+    v1.0 / D3 起只有一条路：按 scene_type（grammar.py 选好、render.py 写进 timeline）
+    派发到 10 类构图之一；没有 scene_type 的旧 timeline 按 kind 映射到兼容类型。
+
+    原来的第 1 条分支（legacy —— film.json 不写 style 就走 v0.4 三个老绘制器）**已删除**：
+    stylekit 不再产出 legacy 计划（不写设计会直接报错），那条分支永远走不到。
+    留着死分支比删掉更危险——它会让"legacy 还能用"的错觉一直存在。
+
     未命中的类型回落到 list（"有条目就画条目"是最不会丢信息的兜底），
     并 warn 一次——静默画错构图比报错更糟。
     """
     plan = _plan(script)
     kind = scene.get("kind") or "body"
-    if plan.get("legacy"):
-        fn = _LEGACY_DRAWERS.get(kind) or _legacy_scene_body
-        return fn(scene, t_local, dur, t_global, script, frame)
     th = _scene_theme(plan, scene)
     stype = str(scene.get("scene_type") or "").strip()
     if not stype:

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/audio-variation.md

@@ -1,5 +1,9 @@
-# 音频多样性改造（v0.7）—— 接口契约
+# 音频多样性改造（v0.7）—— 接口契约（**已归档**）
 
+> **v1.0.1 起本文描述的 scorekit 风格层已删除**（`MUSIC_STYLES` / `render_styled` /
+> 指纹结构变奏）。保留本文是因为音效侧契约（sfxkit / CueBus / duck / 旁白优先）仍然有效；
+> 「A 路配乐变奏」那一节只作历史记录——现在配乐由 `musicgen.py` 参数化编排，没有风格表。
+>
 > 起草：lead，2026-11-09。本文件是本次改造的**唯一定义源**。
 > 三路并行改动的文件写域不重叠，但**接口必须按本文件逐字实现**，否则集成会失败。
 > 诊断证据见 `tools/audio_similarity.py` 的输出（改完后必须重跑，阈值见 §5）。
@@ -16,11 +20,11 @@
 
 | 路 | 负责文件 | 改什么 |
 |---|---|---|
-| A 配乐变奏 | `skills/video-studio/scripts/scorekit.py` | 指纹参与**和声/动机/鼓型/结构**，不再只影响音色细节 |
+| A 配乐变奏（**v1.0.1 已删除**） | 原 `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；
+**写域规则（历史）**：A 路只改 scorekit.py；B 路只改 sfxkit.py / assets/scenes.py / assets/film.json；
 C 路由 lead 改 filmkit.py / render.py / selfcheck.py。**任何一路不得改别人的文件**（包括顺手"优化"）。
 
 ## 3. 接口契约（逐字实现，向后兼容）
@@ -56,7 +60,7 @@ def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
     并把 key 透传给配方（render(kind, seed=..., key=key, **params)）。"""
 ```
 
-### 3.3 scorekit.render_styled（A 路）
+### 3.3 scorekit.render_styled（A 路）——**v1.0.1 已删除，仅存档**
 
 签名不变。**内部**行为变化：
 
@@ -71,8 +75,8 @@ def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
 - **必须保证**：同 `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 确定性）。
+- legacy 路径（style=None）**逐字节不变**（`scorekit.py --selftest` 的 legacy 条会验）。
+  （v1.0.1：`render_styled` 已删除，这一条现在只说明历史契约。）
 
 ### 3.4 assets/scenes.py 的 cues()（B 路）
 
@@ -99,7 +103,7 @@ def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
 - `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 轨在
+  另外新增**过门避让**：配乐在 music.wav 里已经有段落过门，sfx 轨在
   [段落边界 - 2.2s, 边界] 区间内的 whoosh/riser/reverse_swell 需要自动 -3 dB（在 filmkit 里做，
   或 st_sfx 后处理；由 lead 决定实现位置，**B 路不要碰**）。
 
@@ -129,11 +133,11 @@ def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
 > 下面 1–4 的路径都按**仓库根**写（`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。
+1. `python skills/video-studio/scripts/selfcheck.py` 全 PASS（现在 **67 条**；v0.7.2 时的 43 条、v0.8 的 51 条是旧的）。
+2. `python skills/video-studio/scripts/musicgen.py --selftest` 全 PASS（原第 2 条要求 scorekit 风格层自测，v1.0.1 已随风格层删除）。
 3. `python skills/video-studio/scripts/sfxkit.py --selftest` 全 PASS。
 4. `python <REPO>/tools/ci_check.py` 全 PASS（在包根执行）。
-5. legacy 逐样本不变：`scorekit.py --selftest` 第 20 条 + `selfcheck.py` 第 26（风格 legacy）/33（音效 legacy）条，**这些断言不要改**。
+5. 音效 legacy 逐样本不变：`selfcheck.py` 的音效 legacy 断言（v1.0.1 起风格 legacy 断言随风格层一并删除）。
 
 ## 6. 协作规则
 
@@ -156,4 +160,4 @@ def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
 **回归基线**（改前先录、改后逐条比对）：
 
 - sfxkit 9 条渲染的 sha256（ui_blip ×3 / answer_chime / text_stream ×2 / data_chirp / roulette_tick ×2）逐条相同。
-- scorekit legacy 路径（style=None）6 s 渲染逐样本与 v0.6 相同。
+- 配乐 legacy 路径（scorekit，style=None）6 s 渲染逐样本与 v0.6 相同（v1.0.1 起该路径只保留合成原语，不再承担成片配乐）。

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

@@ -1,7 +1,7 @@
 # 音频：采样级混音、配乐与音效
 
 > **v0.3.0 新增三节**（§10–§12 是新的推荐做法，§1–§9.5 是底层原理与手写示例，仍然有效）：
-> §10 提示点系统（声音跟着画面走）、§11 程序化配乐（scorekit）、§12 程序化音效（sfxkit）。
+> §10 提示点系统（声音跟着画面走）、§11 程序化配乐（musicgen 参数化编排）、§12 程序化音效（sfxkit）。
 > 先读 §10——它决定了另外两节怎么用。
 
 ## 1. 为什么不用 ffmpeg 混音
@@ -139,33 +139,33 @@ trimmed = K.trim_silence(pcm, thresh_db=-42.0, keep_ms=80)   # 不是 trim_tail
 # 轻 EQ：200 Hz 以下衰减 2 dB（去闷），3 kHz 提 1 dB（清晰度）
 ```
 
-### 7.1 声线（persona）与语气（tone）—— v0.5.0
+### 7.1 声线（edge voice id）与语气（tone）—— v1.0.1 起没有 persona 身份表
 
-v0.4 及以前全片只有一个 `voice/rate/pitch`，于是"每部片的旁白都差不多"。
-v0.5 引入 **persona（声线）× tone（语气档）**，由 `voicekit.py` 解析成逐句 spec：
+> **v0.5 的 persona 表（`bright_female` / `narrator_male` 之类 9 个身份）在 v1.0.0 已删除。**
+> 现在 `voice` 只认**裸 edge-tts voice id**（如 `zh-CN-YunxiNeural`）+ 实测响度补偿表
+> `assets/voice_loudness.json`；tone 的 6 档（hook/body/quote/outro/emphasis/calm）保留。
 
 ```json
-{"voice": {"map": {"hook": "bright_female", "body": "narrator_female", "quote": "authority_male"},
+{"voice": {"id": "zh-CN-YunxiNeural",
+           "map": {"hook": "zh-CN-YunxiaNeural", "body": "zh-CN-YunxiNeural",
+                   "quote": "zh-CN-YunyangNeural", "outro": "zh-CN-YunxiNeural"},
            "jitter": 0.35, "max_distinct": 3}}
 ```
 
 ```bash
-python voicekit.py --list          # 9 个 persona + 6 个 tone（含实测响度补偿 gain_db）
-python voicekit.py --plan film.json  # 打印某份剧本的逐句声线计划（不发请求）
+python <SKILL_DIR>/scripts/voicekit.py --list    # 音色响度表（裸 id + 实测 gain_db）与 6 档 tone
+python <SKILL_DIR>/scripts/voicekit.py --plan film.json   # 打印逐句声线计划（不发请求）
 ```
 
-- **persona** 决定 edge-tts 音色 id + 基线 rate/pitch/volume/gain_db；
+- **voice id** 直接就是 edge-tts 的音色名；`--list` 里带的是**实测响度补偿**（不同音色天然差 3–7 dB，
+  实测跨度 6.0 dB）。写了表里没有的音色，补偿回落 0 = 旁白电平没校准。
 - **tone** 决定相对偏移与句前/句后停顿：hook / body / quote / outro / emphasis / calm
-  （`body` 严格等于 v0.4 基准：lead 0.62 / tail 0.92 / 所有 delta=0）；
-- **内容规则**会自动升级语气：引号句 -> quote（并换到 quote 声线）、数字密集 -> emphasis、
-  问句/感叹 -> 稍快稍亮、长句 -> 降速加尾部留白；显式 `lines[].voice/tone` 优先级最高；
-- **jitter**（默认 0.35）用 sha1 派生 ±1.5% / ±1Hz / ±0.04s 的微扰，去掉"每句等距等音量"的机械感；
+  （`body` 严格等于 v0.4 基准：lead 0.62 / tail 0.92 / 所有 delta=0）。
+- **内容规则**会自动升级语气：引号句 → quote（并换到 quote 声线）、数字密集 → emphasis、
+  问句/感叹 → 稍快稍亮、长句 → 降速加尾部留白；显式 `lines[].voice/tone` 优先级最高。
+- **jitter**（默认 0.35）用 sha1 派生 ±1.5% / ±1Hz / ±0.04s 的微扰，去掉"每句等距等音量"的机械感。
 - **governor** 限制全片最多 `max_distinct` 把声音、相邻句不换人 —— 超过就变成广播剧，不是旁白。
 
-**响度校准**：不同音色的响度天然差 3–7 dB（实测 narrator_female 比 narrator_male 响约 5.7 dB），
-persona 表里的 `gain_db` 是**实测回填**的（`voicekit.py --calibrate` 可复测）。
-混音侧每句只应用一次增益（v0.5 顺手修掉了 v0.4 `voice_gain` 被乘两次的静默 bug）。
-
 **缓存键 v2**：`sha1(v2|text|voice|rate|pitch|volume|trim|trim_db)`。v0.4 的 key 不含 trim，
 于是把 `trim_silence` 改成 false 仍会命中旧的裁剪版 —— "关了裁剪其实没关"。v1 key 仍然保留给老缓存。
 
@@ -306,25 +306,27 @@ python qa_frames.py out/film.mp4 --cues work/cues.json   # 看音画同步 dt
 **音画同步 dt > 60 ms 就是错**：人眼/耳对 40–60 ms 以内的错位不敏感，超过就会"感觉哪里不对但说不出来"。
 dt 大的典型原因：cue 挂在字幕出现的时刻上，而画面重击晚 100 ms——应该挂在动画时刻上。
 
-## 11. 程序化配乐（scorekit，v0.3.0）
+## 11. 程序化配乐（musicgen，v1.0.1）
+
+> **v1.0.1 起没有「配乐模板」了。** 以前这一节讲的是 scorekit 的 9 套 `MUSIC_STYLES`
+> 风格表（选一个 id 得到一种配乐性格）——那套表已删除。现在配乐由 `musicgen.py`
+> 按参数**现场编排**：没有可选曲风，只有参数。下面仍然是「一张和弦表贯穿全片」的技术思路，
+> 实现落到了参数化编排器上。
 
 ```python
-import scorekit as sk
-samples, report = sk.render(389.0, bpm=120, key="Dm",
-                            anchors=timeline["scenes"],   # [{id,kind,start,end}]
-                            seed=7)                       # 同 seed 逐采样一致
-sk.save("work/music.wav", samples)
+import musicgen as MG
+# 参数就是「设计」：bpm / key / scale / mood / seed，加可选的编排参数
+samples, report = MG.render(389.0, bpm=120, key="Dm", scale="minor",
+                            mood="steady", seed=7)   # 同参数逐采样一致
+MG.save("work/music.wav", samples)
 ```
 
-或者用面向对象的写法（要更细的控制时）：
+要更细的控制就传 `sections` / `progressions` / `motif` / `drums` / `voices` ——
+它们真的参与事件展开，不是死旋钮（接口见 `musicgen.py` 模块 docstring）。
 
-```python
-sc = sk.Score(389.0, bpm=120, key="Dm", seed=7)
-sc.plan_from_anchors(timeline["scenes"], default_energy=0.5)   # 自动分段，边界对齐小节
-sc.section("finale", 360.0, 389.0, energy=0.95)
-sc.suck(360.0, db=-6, dur=0.22)                                # 最终重击前"吸一口气"
-samples = sc.render()
-```
+底层原语（吸气、分段能量、过门）仍在 `scorekit.py` 里，但**它不是配乐引擎**：
+它只提供和声表 / 律动层 / 混音 / 响度测量这些可复用件。要自己拼一条非常规配乐可以直接
+调它的 `Score` 再用 `scorekit.save()` 落盘；成片链路用的是 musicgen。
 
 ### 11.1 为什么"一张和弦表贯穿全片"
 
@@ -439,7 +441,7 @@ v0.5 的 style pack 决定的是**风格**（8 套），不是**这一部的具
 
 | 层 | 行为 | 开关 |
 |---|---|---|
-| 配乐和声/动机/鼓型 | 内容指纹做稳定局部替换（每两小节、±1 级数、ghost 击） | `style: auto`（默认）；`seed_from_content: false` **只关 seed 派生**（音符细节不再随内容变），结构变奏照旧——`render.py` 只要不是 legacy 就把 `fingerprint` 传给 scorekit（`st_score` 里 `fp_hex` 那段）。想连结构一起回到旧行为只有不写 `style`（legacy） |
+| 配乐和声/动机/鼓型 | v0.7 时代由内容指纹驱动结构变奏（每两小节、±1 级数、ghost 击）；**v1.0.1 起改由 musicgen 的编排参数直接决定**（没有可挑的曲风表） | `music.seed_from_content` 仍控制 seed 是否掺指纹；结构差来自 `music.sections` / `music.progressions` 等参数，而不是「换一套风格」 |
 | 音效 seed | `content_seed(base, style, fp, type, t)`，随内容变 | `sfx.content_seed`（默认 true；false = 旧 seed_base+i） |
 | 提示音调性 | `in_key(freq, key)` 跟随配乐调性 | `CueBus.build_audio(key=...)`，render.py 自动传 |
 | 段落边界 | [边界-2.2s, 边界] 内的 whoosh/riser 自动 -3 dB | `sfx.duck_transitions`（默认 true） |
@@ -477,6 +479,6 @@ D 组构造"有人声段 + 间隙"，量人声段旁白/背景响度差。任何
 ### 13.4 改音频代码后的自检清单
 
 1. `python <REPO>/tools/audio_similarity.py --strict` —— A/B/C 三组达标（在包根执行）。
-2. `python selfcheck.py` —— 55 条全 PASS（第 33 条盯 legacy 逐样本兼容，第 35–38 条盯旁白优先，第 39 条盯音频边界）。
-3. `python scorekit.py --selftest` / `python sfxkit.py --selftest` —— 各自全 PASS。
-4. 改 `assets/scenes.py` 的 `cues()` 后，跑一次 `--stage cues` 看类型分布是否覆盖 hook/body/quote/outro。
+2. `python <SKILL_DIR>/scripts/selfcheck.py` —— **67 条**全 PASS（第 33 条盯 legacy 逐样本兼容，第 35–38 条盯旁白优先，第 39 条盯音频边界）。
+3. `python musicgen.py --selftest` / `python sfxkit.py --selftest` —— 各自全 PASS（musicgen 的 26 项覆盖编排与确定性）。
+4. 改 `assets/scenes.py` 的 `cues()` 后，跑一次 `--stage cues` 看类型分布是否覆盖 hook/body/quote/outro。

package/skills/video-studio/references/change-impact.md

@@ -23,7 +23,7 @@
 | `lines[].sub`（字幕文案） | sub.srt / sub.ass / timeline 的字幕窗口 / frames / mux / qa | `layout → frames → mux → qa`（TTS 可复用） | 帧数÷40 s |
 | `lines[].hold` / `lead` / `tail` / `bar` | timeline / cues / frames / mux / qa | 同上 | 帧数÷40 s |
 | `lines[].kind` | 声线计划 / 配乐分段 / 画面版式（scenes 按 kind 选绘制函数） | `style → tts → layout → …` 全链 | 全片 |
-| `style`（含 `"auto"` 结果变了） | style.json / voice_plan / tts(换声线时) / score / audio / frames / qa | 看 `--stage explain`：通常是全链 | 全片 |
+| `work/design.json`（设计变了：配色/字体/母题/版式/字幕/配乐/声线） | style.json / storyboard / voice_plan / tts(换声线时) / score / audio / frames / qa | 看 `--stage explain`：通常是全链 | 全片 |
 | `bpm` / `music.*` | score / audio / mux | `score → audio → mux → qa` | 秒级 |
 | `sfx.cues` / `scenes.py 的 cues()` | cues.json / sfx.wav / audio.wav / mux | `cues → sfx → audio → mux → qa` | 秒级 |
 | `scenes.py`（画面代码） | frames / qa（参考帧失效） | `frames → mux → qa`（音轨可复用） | 帧数÷40 s |
@@ -36,7 +36,7 @@
 | 错误做法 | 后果 | 正确做法 |
 |---|---|---|
 | 改了 `text` 只重跑 `tts` | 新语音配旧时间轴 → 字幕漂移、音效错位 | 跑 `--stage explain`，按它给的最小重跑命令 |
-| 改了 `style` 只重跑 `frames` | 画风换了但配乐/声线还是旧的（或反之） | `style` 是所有下游的上游，通常整链重跑 |
+| 改了 `design.json`（或重新 `--confirm` 了另一份）只重跑 `frames` | 画风换了但配乐/声线还是旧的（或反之） | 设计是所有下游的上游，通常整链重跑；`--stage style` 先看解析结果 |
 | 手工删 `work/segments/_plan.json` 绕过指纹 | 拼接出的片子画面和旁白对不上，且**不报错** | 删 `work/segments` 整目录重渲 |
 
 ## 3. 一条命令代替这张表
@@ -51,4 +51,4 @@ python scripts/stagewatch.py --work work --json   # 机读（给脚本/agent 用
 
 签核（`--stage accept`）绑的是**内容指纹**（剧本 + scenes.py + 引擎）。
 所以：**改了上面表里任何一项，之前的签核都会自动失效**，需要重新看、重新签。
-这不是麻烦，是这套机制存在的意义——否则"我签过了"会变成一张永远有效的空头支票。
+这不是麻烦，是这套机制存在的意义——否则"我签过了"会变成一张永远有效的空头支票。

package/skills/video-studio/references/frame-qa.md

@@ -122,7 +122,7 @@ r[t] = |F[t+1] - F[t-1]|      # 同一块上的"前后两帧彼此差多少"
 | 判定 | 记 error | 跳过 |
 
 没有这道闸时，**每一段"缓动入场 / 逐字入场 / 转场黑场起坡"的最快帧都会被报成闪烁**。
-实测反例（本技能自带的 `assets/web/` 模板片）：12 s 的片子里报了 3 处——
+实测反例（本技能自带的 `assets/web/` 示例片）：12 s 的片子里报了 3 处——
 
 | 时刻 | score | 真相 |
 |---|---|---|
@@ -188,7 +188,7 @@ drift[t] = max over 8x8 blocks of mean |F[t] - F[t-lag]| * 255     (lag = FLAT_L
 人眼看到的就是一张静止的图。用"最活跃块"而不是"全帧均值"，是因为逐字入场、数字滚动、卡片切换
 只占全屏几个百分点，全帧均值几乎不动，而观众显然看得到它们在动。
 
-为什么旧判据要废：全帧均值对局部动画天生不敏感。自带模板片（30.10 s）实测误报 **4 段**
+为什么旧判据要废：全帧均值对局部动画天生不敏感。自带示例片（30.10 s）实测误报 **4 段**
 （411/814 个滑动窗口命中），而画面一直在动。新判据在同一片上 **0 段**。
 
 实测分布（160×90 解码，H.264）：