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

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 冻结），这里没有 style 字段。文本仅用于跑通全链与金帧/门禁回归，换题材请自己写 lines[]。",
  "title": "测试片 demo",
  "end_text": "完",
- "style": "auto",
  "voice": "zh-CN-YunxiNeural",
  "rate": "+6%",
  "pitch": "+0Hz",
@@ -18,7 +17,6 @@
  "music": {
   "enabled": true,
   "mode": "score",
-  "style": "auto",
   "mood": "auto",
   "bpm": "auto",
   "key": "auto",
@@ -55,7 +53,7 @@
   "enabled": true,
   "gain_db": 0,
   "content_seed": true,
-  "_comment": "v0.7 去固定化（references/audio-variation.md §3.5）：模板只留 1 条转场 whoosh 作示例，具体提示点建议交给 assets/scenes.py 的 cues() 钩子按画面内容生成（hook=impact+riser；body=ui_blip 按条目文本定音高 + answer_chime + 段尾 whoosh；quote=reverse_swell+impact；outro=answer_chime+sub_drop）。content_seed=true（默认）= 每条 cue 的 seed 由 style/content_fp 派生（不同片子同一位置也不同），显式 false 回到 v0.6 的 seed_base+i 旧行为。",
+  "_comment": "夹具只留 1 条转场 whoosh 作示例（见 references/audio-variation.md §3.4）；具体提示点交给 assets/scenes.py 的 cues() 钩子按画面内容生成（hook=impact+riser；body=ui_blip 按条目文本定音高 + answer_chime + 段尾 whoosh；quote=reverse_swell+impact；outro=answer_chime+sub_drop）。content_seed=true（默认）= 每条 cue 的 seed 由 style/content_fp 派生（不同片子同一位置也不同），显式 false 时按 seed_base+i 只跟 cue 顺序。",
   "cues": [
    {
     "at": "l02-0.15",

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

@@ -1,7 +1,7 @@
 {
  "version": 1,
- "generator": "golden_frames.py v0.8.0",
- "comment": "金帧基线：字体指纹+环境指纹一致时，每一帧像素 sha256 必须相同；换机/字体/Pillow 版本不同判 skipped（不误报），同环境像素变了才是 fail。改动模板（film.json / scenes.py / stylekit 主题）后请 --write 重录并提交本文件。",
+ "generator": "golden_frames.py v1.0.4",
+ "comment": "金帧基线：字体指纹+环境指纹一致时，每一帧像素 sha256 必须相同；换机/字体/Pillow 版本不同判 skipped（不误报），同环境像素变了才是 fail。改动夹具（film.json / scenes.py / 设计）后请 --write 重录并提交本文件。",
  "canvas": [
   1920,
   1080
@@ -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": "6f70eabff4a90ba4c488aada0af81e806c3cce92",
+  "scenes_sha1": "13902dfa5a23edec00eb5306dbc5297e6403ac1c",
+  "filmkit_sha1": "752eeda4b47a739925b60d4d6b98fee99261d905",
+  "stylekit_sha1": "bff8f89bf09ff64e12a96d7a1dbb241319553db4",
+  "design_sha1": "f87cc13e4c55040d9de5675933c01aa8220134d1",
+  "designkit_sha1": "785d699349bfef56b9acfbb94dd4f2b92ab3444e",
+  "golden_tool_sha1": "1807499ab7d15d466aeba3aef361c95fe4e5c387"
  },
  "frames": [
   {
@@ -45,21 +48,21 @@
    "scene": "l01",
    "t_local": 1.2,
    "label": "hook",
-   "sha256": "ee2a70067aeaee0c158c7eef6c26c1228354bf247f05f7330c991ef1946aaaae"
+   "sha256": "af738e3252e22abd3034c794b515ba0fde0d25eb41c6fa6ae8e1efdbff055a21"
   },
   {
    "frame": 270,
    "scene": "l03",
    "t_local": 1.6,
    "label": "body",
-   "sha256": "ead954c01f5498782b3a31b8e42638d4f8f42e2faca97df476e0d78a1f9f72f8"
+   "sha256": "b86f97ab6a9120446700bc2c790944ebe7db6fbc24ed20871f79426a94a0980e"
   },
   {
    "frame": 369,
    "scene": "l04",
    "t_local": 1.5,
    "label": "outro",
-   "sha256": "10463a35429185e7b816fd5ede7107d529e26f4ec8d8640fba84d9897cc77f66"
+   "sha256": "1850ff2313378c1fe0e7579aeb433c1d1fce072478f5924b913244095d2991f0"
   }
  ]
 }

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

@@ -1,20 +1,26 @@
 # -*- coding: utf-8 -*-
-"""scenes.py — 场景绘制模板（v0.5.0：画风随内容变化）。
+"""scenes.py — 技能内置的场景渲染器（默认渲染路径 + 自定义场景的范例）。
+
+⚠ 这**不是**给用户拷走改的模板：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、镜头缓推——**没有任何内置风格表**：
+同一份代码画出来是什么样，完全由现场采样并确认过的 design.json 决定。
 
 铁律（决定画质与可复现性）：
   1. 不许用 random / time.time()；要随机用 K.hash2 / K.hash3 / vnoise(seed)
@@ -56,10 +62,10 @@ import filmkit as K
 from filmkit import W, H, clamp, smooth, ease_out, rng
 
 # ============================================================================
-# 零、v0.4 兼容层（legacy 逐字节基线，别动这里的任何一行）
+# 零、legacy 绘制器（逐字节基线，别动这里的任何一行）
 # ============================================================================
 #
-# legacy = 老项目（film.json 没有 style 字段）。这组函数是 v0.4 的原文，
+# legacy = 老项目（film.json 没有 style 字段）。这组函数是逐字节基线，
 # 一个字符都不许改：Lead 的基线三帧 sha256 直接对拍这里的输出。
 # 新主题化代码只在 _legacy_* 之外生长，互不影响。
 
@@ -237,7 +243,7 @@ _LEGACY_DRAWERS = {
 
 
 # ============================================================================
-# 一、风格计划 / 主题（v0.5）
+# 一、风格计划 / 主题
 # ============================================================================
 
 _PLAN_CACHE = {}
@@ -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)
 
 
 # ---------------- 包内小工具 ----------------
@@ -332,14 +358,14 @@ def _ease(name):
 _EASES = {}
 
 
-# ---------------- 字体：family 是 v0.5 新加的参数（旧 filmkit 没有，自动回退） ----------------
+# ---------------- 字体：family 参数（旧 filmkit 没有就自动回退） ----------------
 
 _FONT_CACHE = {}
 _FAMILY_OK = None
 
 
 def _family_ok():
-    """filmkit.font 是否支持 family=...（Lead 在 v0.5 加；老版本没有就回退旧签名）。"""
+    """filmkit.font 是否支持 family=...（老版本没有就回退旧签名）。"""
     global _FAMILY_OK
     if _FAMILY_OK is None:
         try:
@@ -427,7 +453,7 @@ class _View(object):
 
     为什么不是整帧重采样：实测 1080p 双线性整帧变换 29ms/帧（预算 15ms），
     而整帧按 push 放大又会把 150px 边距的内容推出 SAFE。所以分两层：
-      背景层做**真缩放**（EXTENT + NEAREST，1.7~3.5ms，见 _bg_plate）；
+      背景层做**真缩放**（端点预烘 + blend，约 4.4ms，见 _plate_zoom/_bg_plate）；
       前景层做同向**视差**（0.35x，位置与卡片尺寸随镜头收放，字形不重采样保清晰）。
     """
     __slots__ = ("s", "cx", "cy")
@@ -573,15 +599,63 @@ def _bg(th):
     return im
 
 
-def _bg_plate(th, s):
-    """逐帧背景：按镜头缩放取景（NEAREST 重采样，实测 1.7~3.5ms/帧）。"""
-    base = _bg(th)
+_ZOOM_ORDER = []
+
+
+def _zoom_tag(th, extra=None):
+    """取景端点的缓存标签：主题决定底图，extra 用来区分装饰母题档位。"""
+    return _hashable(("zoom", th.get("id"), th["bg"], th["bg2"], th["texture"],
+                      th["grain"], th["grain_freq"], th["vignette"],
+                      th["vignette_tint"], th["texture_alpha"], extra))
+
+
+def _plate_zoom(src, s, th, tag):
+    """按镜头缓推取景：端点预烘 + 逐帧 blend。
+
+    为什么不再用 NEAREST 直采：底图把颗粒（`_grain_layer`）一起烘了进去，颗粒是
+    逐像素的高频图案；NEAREST 在缓慢缩放时采样网格会整像素跳变，颗粒图案随之整体
+    错位 1px，观感就是"满屏噪点在沸腾"——用户实测反馈是"明显的抖动感"，而背景-only
+    的帧差只有 4~6 灰阶，单帧闪烁门禁根本抓不到。
+
+    做法：s=1.0 与 s=1+push 两个端点各烘一张 BILINEAR 底版（每张约 60ms，只做一次），
+    逐帧用 `Image.blend` 在两端点间线性插值（实测 4.4ms/帧）。端点内部是**平滑重采样**，
+    没有 NEAREST 的网格跳变，帧差降到 0~1 灰阶；同时保留颗粒质感（不是把 grain 抹掉）。
+
+    上限取 1+push：`_push_scale` 恒 <= 1+push，超出的 s 一律钳到端点上，不会外推。
+    """
     if s <= 1.0008:
-        return base.copy()
-    bw, bh = W / s, H / s
-    x0 = (W - bw) * 0.5
-    y0 = (H - bh) * 0.5
-    return base.transform((W, H), Image.EXTENT, (x0, y0, x0 + bw, y0 + bh), Image.NEAREST)
+        return src.copy()
+    cap = 1.0 + max(0.0, float(th.get("push") or _DEFAULT_PUSH))
+    if cap <= 1.0008:
+        return src.copy()
+    s = min(float(s), cap)
+    key = _hashable(("zpts", tag, round(cap, 6)))
+    pair = _CACHE.get(key)
+    if pair is None:
+        lo = src.copy()
+        bw, bh = W / cap, H / cap
+        x0 = (W - bw) * 0.5
+        y0 = (H - bh) * 0.5
+        hi = src.transform((W, H), Image.EXTENT, (x0, y0, x0 + bw, y0 + bh), Image.BILINEAR)
+        pair = (lo, hi)
+        _CACHE[key] = pair
+        _ZOOM_ORDER.append(key)
+        while len(_ZOOM_ORDER) > 4:              # 一对端点约 12MB，限量防多片同进程膨胀
+            old = _ZOOM_ORDER.pop(0)
+            if old != key:
+                _CACHE.pop(old, None)
+    lo, hi = pair
+    w = (s - 1.0) / (cap - 1.0)
+    if w <= 0.0:
+        return lo.copy()
+    if w >= 1.0:
+        return hi.copy()
+    return Image.blend(lo, hi, w)
+
+
+def _bg_plate(th, s):
+    """逐帧背景：按镜头缩放取景（端点预烘 + blend，约 4.4ms/帧；见 _plate_zoom）。"""
+    return _plate_zoom(_bg(th), s, th, _zoom_tag(th, "bg"))
 
 
 # ---------------- 版式几何（全部从 ST.LAYOUTS 取） ----------------
@@ -604,7 +678,7 @@ def _panel_x(lay):
 def _panel_boxes(lay, th, n, y_floor, v):
     """条目卡片布局：选列数 + 压缩卡片高度，保证①不压标题②不越字幕带（856）。
 
-    panel_gap 在 stylekit 里是**行距（pitch）**不是间隙：v0.4 用 240 + i*118 排卡片，
+    panel_gap 在 stylekit 里是**行距（pitch）**不是间隙：按 240 + i*118 排卡片时，
     所以 pitch 至少得比卡片高度多 6px，否则卡片会叠在一起。条目多时先加列，再压高度，
     最后才截断——静默重叠或画到字幕带下面比少画两条更糟。
     """
@@ -748,14 +822,14 @@ def _hud(img, th, chapter, progress, title):
 
 
 # ============================================================================
-# 三、场景语法（v0.9：10 类构图 × 8 套视觉语言）
+# 三、场景语法（10 类构图 × 8 套视觉语言）
 # ============================================================================
 #
 # 为什么重写这一节
 # ---------------
-# v0.5 的 _draw_hook / _draw_body / _draw_outro 是"一套骨架 + 换色"：背景板 → 眉标 →
+# 旧的 _draw_hook / _draw_body / _draw_outro 是"一套骨架 + 换色"：背景板 → 眉标 →
 # 大字 → 副标题 → 强调线 → HUD，三种 kind 只差字号与位置。于是 8 套风格换完只剩配色不同。
-# v0.9 把"画什么"（scene type，由 grammar.py 按内容选）与"怎么画"（视觉语言，由 stylekit
+# 现在把"画什么"（scene type，由 grammar.py 按内容选）与"怎么画"（视觉语言，由 stylekit
 # 的 VISUAL_LANGUAGES 给）拆开：
 #   · 10 类构图各自有独立的视觉重心与留白（hero 偏左上 / statement 正中 / compare 强制对称 …）
 #   · 每套风格有自己的装饰母题（括角 / 手绘内框 / letterbox / 信号条 …）与转场签名
@@ -889,9 +963,9 @@ def _motif_layer(th, lang):
     """把该风格独有的装饰图形烘焙成一张全屏 RGBA 图层（不含动态）。
 
     为什么烘焙：这些图形是静态的（括角、页眉线、letterbox、信号条），
-    逐帧重画一次就是 3–8ms。注意：v0.9.0 这里写的是"paste 只要 0.3ms"，
-    实测全屏 RGBA paste 是 **5.6ms**（Pillow 13 / 1080p），所以 v0.9.1 起
-    装饰直接烘焙进底版（见 _plate），逐帧只 copy 底版，不再单独 paste。
+    逐帧重画一次就是 3–8ms。注意：全屏 RGBA paste 实测是 **5.6ms**
+    （Pillow 13 / 1080p），所以装饰直接烘焙进底版（见 _plate），
+    逐帧只 copy 底版，不再单独 paste。
     """
     mf = lang.get("motif") or _DEFAULT_LANG["motif"]
     key = _motif_key(th, lang)
@@ -1018,10 +1092,10 @@ _PLATE_ORDER = []
 
 
 def _plate(th, lang, scene, s_bg):
-    """背景板 + 装饰母题合成后的整帧底版（v0.9.1）。
+    """背景板 + 装饰母题合成后的整帧底版。
 
     这是单帧预算里最大的一处优化：装饰是静态的，逐帧单独 paste 一张全屏 RGBA 要 5.6ms，
-    合成进底版后逐帧只剩 copy（1.3ms）或 EXTENT 缩放（1.7–2.0ms）。
+    合成进底版后逐帧只剩 copy（1.3ms）或端点 blend 取景（约 4.4ms，见 _plate_zoom）。
     顺带一个好处：镜头缓推现在会把装饰一起推——装饰本来就该跟着镜头走，
     以前"背景推、装饰不动"在强 push 的风格（cinema 0.12 / epic 0.14）里其实是穿帮。
 
@@ -1046,12 +1120,7 @@ def _plate(th, lang, scene, s_bg):
             old = _PLATE_ORDER.pop(0)
             if old != key:
                 _CACHE.pop(old, None)
-    if s_bg <= 1.0008:
-        return got.copy()
-    bw, bh = W / s_bg, H / s_bg
-    x0 = (W - bw) * 0.5
-    y0 = (H - bh) * 0.5
-    return got.transform((W, H), Image.EXTENT, (x0, y0, x0 + bw, y0 + bh), Image.NEAREST)
+    return _plate_zoom(got, s_bg, th, _zoom_tag(th, key))
 
 
 def _apply_motif(img, th, lang, scene):
@@ -1069,7 +1138,7 @@ def _apply_veil(img, th, lang, scene, t_local, s_bg):
     """段首从背景"长出来"的过场。不做跨场景 cross-dissolve（draw_frame 拿不到上一段帧），
     只做"从本段背景板渐显 / 擦入"，观感是 dip 而不是 dissolve。
 
-    为什么必须做：v0.9 起相邻两段可能是完全不同的构图（数字卡 → 左右对比），
+    为什么必须做：相邻两段可能是完全不同的构图（数字卡 → 左右对比），
     整屏瞬切会精确触发 qa_frames 的单帧闪烁门禁（8x8 分块灰度差 ≥6.0），
     观众看着也像"换了一部片"。
     """
@@ -1194,13 +1263,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),
@@ -1209,7 +1284,7 @@ def _draw_hero(scene, t, dur, tg, script, frame, plan, th):
 
     sub = scene.get("lead") or scene.get("sub") or ""
     # 副标题与大字重复时不要画第二遍：模板片里 big 与 sub 都是"零素材，全代码生成"，
-    # 照抄会让画面出现两行一样的字（v0.9 实测第一版就是这样）。
+    # 照抄会让画面出现两行一样的字（实测踩到过）。
     if sub and (str(sub).strip() == str(big).strip()
                 or (len(str(sub)) >= 6 and str(sub).strip() in str(big).strip())):
         sub = ""
@@ -1386,7 +1461,7 @@ def _draw_list(scene, t, dur, tg, script, frame, plan, th):
     body = max(22, int(th["scale"]["body"][0]) - 1)
     # 行高：优先"每条 96–118px"，条目多时往下压，硬下限 56px（再低中文就糊成一片）。
     # 为什么不是固定行高：模板片 5 条要点在 9.3s 的段里，固定 118px 会溢出 856 硬边界，
-    # 于是第 5 条被静默截断（v0.9 第一版实测），观众看到"五步"只列出四步。
+    # 于是第 5 条被静默截断（实测踩到过），观众看到"五步"只列出四步。
     avail = 856.0 - top
     row_h = avail / max(1, len(items)) if items else 118.0
     row_h = min(118.0, max(56.0, row_h - 6.0))
@@ -1513,10 +1588,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))))
+    # 次要统计：**数值 + 单位 + 标签**都要画出来。
+    # 这里必须把数值也画出来：只画 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)
@@ -1570,7 +1658,7 @@ def _draw_compare(scene, t, dur, tg, script, frame, plan, th):
 
     # 两栏内容垂直居中（上界 360，下界 800）：只有一两条时不会全挤在顶部留一大片空白。
     # 栏头：优先 sides 里作者写的 head；没有就**不要**写"左/右"这种零信息标签
-    # （v0.9 第一版实测：观众看到"左 / 右"会以为画面坏了），改画一个 VS 徽标在中缝上方。
+    # （实测：观众看到"左 / 右"会以为画面坏了），改画一个 VS 徽标在中缝上方。
     cols = [("left", 150.0, 700.0, -1), ("right", W - 850.0, 700.0, 1)]
     max_rows = max(len((sides.get("left") or {}).get("items") or []),
                    len((sides.get("right") or {}).get("items") or []), 1)
@@ -1717,7 +1805,7 @@ def _draw_quote(scene, t, dur, tg, script, frame, plan, th):
     by = str(by or "")
 
     # 巨型引号：**用字形**，不用矢量线。
-    # v0.9 第一版画的是两条短线拼成的「《」，实测看起来像播放器的"快退"图标，
+    # 用两条短线拼「《」实测看起来像播放器的"快退"图标，
     # 观众会以为点错了什么。雅黑粗体的 U+201C 是有字形的（preflight 查过不缺口），
     # 直接放大 150px 就是最标准的引语符号。
     pq = ease(rng(t, 0.0, 0.45))
@@ -1924,7 +2012,7 @@ def _draw_outro(scene, t, dur, tg, script, frame, plan, th):
     gap = _gap(th, lang)
     ph = _phase(scene)
 
-    # 光点环：数量随视觉语言母题走（epic 18 / cinema 12 / mono 0），且比 v0.5 更少
+    # 光点环：数量随视觉语言母题走（epic 18 / cinema 12 / mono 0）
     mf = str((lang.get("motif") or {}).get("kind") or "minimal")
     ring_n = {"rays": 18, "letterbox": 12, "brackets": 10, "signal": 8,
               "handdrawn": 6, "slabs": 12, "hairlines": 6, "minimal": 0}.get(mf, 8)
@@ -2003,18 +2091,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 映射到兼容类型。
+    只有一条路：按 scene_type（grammar.py 选好、render.py 写进 timeline）
+    派发到 10 类构图之一；没有 scene_type 的旧 timeline 按 kind 映射到兼容类型。
+
+    原来的第 1 条分支（legacy —— film.json 不写 style 就走三个老绘制器）**已删除**：
+    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:
@@ -2028,7 +2116,7 @@ def draw_frame(scene, t_local, dur, t_global, script, frame):
     return fn(scene, t_local, dur, t_global, script, frame, plan, th)
 
 
-# ---------------- 提示点（v0.3.0 起可选；v0.7 按 kind 与内容生成） ----------------
+# ---------------- 提示点（按 kind 与内容生成） ----------------
 def _sha1_int(*parts):
     """把若干文本片段拼起来取 sha1 前 8 位（提示点"内容派生"的稳定来源）。"""
     raw = "|".join(str(p) for p in parts).encode("utf-8")
@@ -2038,8 +2126,8 @@ def _sha1_int(*parts):
 def _item_pitch(text, base=1760.0):
     """条目文本 -> ui_blip 音高（sha1 派生，不用序号）。
 
-    v0.7 契约 §3.4：body 条目的 pitch 必须由**条目文本**派生，不再按序号
-    （旧实现 1760+110*i 每片都一样）——同一句文案换到别的片子里仍是同一个音高，
+    契约 §3.4：body 条目的 pitch 必须由**条目文本**派生，不再按序号
+    （1760+110*i 每片都一样）——同一句文案换到别的片子里仍是同一个音高，
     不同文案落到 -5~+7 半音的不同音级；万一两条碰撞，_dedupe_segment 会再升半音。
     """
     off = _sha1_int("pitch", text) % 13 - 5
@@ -2049,7 +2137,7 @@ def _item_pitch(text, base=1760.0):
 def _cue_gain_decay(gain, repeat):
     """同段内同类型 cue 第 repeat 次重复（0 起）时的增益：每次再低 2 dB（-2/-4/-6/…）。
 
-    v0.7 契约 §3.4：不许再出现"每段都一模一样的三连击"——同类型重复必须**严格递减**
+    契约 §3.4：不许出现"每段都一模一样的三连击"——同类型重复必须**严格递减**
     （第 2 次 -2、第 3 次 -4、第 4 次 -6……），且 pitch 必须不同。
     """
     return round(float(gain) - 2.0 * int(repeat), 2)
@@ -2085,11 +2173,11 @@ def cues(tl, script):
     好处是"声音跟着画面的像素走"：这里算的是卡片落位、数字滚完的时刻，
     画面一改，声音自动跟着改，不用回来手工对时间。
 
-    v0.5：条目落位步长与场景绘制共用 plan["pacing"]["item_stagger"]，
-    两边读同一个数，否则音效会错位（这是 v0.4 写死 0.32 留下的坑）。
+    条目落位步长与场景绘制共用 plan["pacing"]["item_stagger"]，
+    两边读同一个数，否则音效会错位（写死 0.32 时踩过这个坑）。
 
-    v0.7（references/audio-variation.md §3.4）：提示点改为按**场景 kind 与内容**生成，
-    不再是"每段 ui_blip 三连 + 结尾 answer_chime"的同质化固定套路（跨片音效雷同的
+    见 references/audio-variation.md §3.3：提示点按**场景 kind 与内容**生成，
+    不是"每段 ui_blip 三连 + 结尾 answer_chime"的同质化固定套路（跨片音效雷同的
     来源之一）：
       hook  : 段首 impact（size 按字数 0.9~1.3）+ 落定 riser
       body  : 条目落位 ui_blip（pitch 由条目文本 sha1 派生）+ items>=3 补 answer_chime