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

package/skills/video-studio/scripts/qa_frames.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-"""qa_frames.py — 帧级 / 时间轴级深度质检（v0.3.0）。
+"""qa_frames.py — 帧级 / 时间轴级深度质检。
 
-成片质检 v0.2 只看容器、响度、黑帧、锐度，看不出"画面内部"的问题：
+只看容器、响度、黑帧、锐度的容器级质检看不出"画面内部"的问题：
 一帧白闪、一段近黑空窗、音效 cue 与视觉事件没对上——这些只有逐帧解码才能发现。
 
 本模块提供：
@@ -12,9 +12,9 @@
 4. luma_curve / loudness_curve：亮度与响度时间曲线（响度是近似值，见文档）。
 5. static_warnings（"_static_warnings"，报告里进 warnings）：画面长时间"完全没有运动"
    （卡帧 / 忘了加动画）。判据是"最活跃的 8x8 块在 0.5 s 里是否变了 > 1.5 级灰度"，
-   连续 6 s 全部不动才告警——v0.4.0 换掉了原来"全帧平均亮度 3 s 波动 < 0.002"的判据
-   （后者对逐字入场这类局部动画不敏感，自带模板片误报 4 段）。
-6. sync_check：cues.json 的音频提示点与视觉事件配对，报 dt 超容差项。v0.4.0 起支持
+   连续 6 s 全部不动才告警（不用"全帧平均亮度 3 s 波动 < 0.002"这类判据：它对逐字
+   入场这类局部动画不敏感，自带模板片会误报 4 段）。
+6. sync_check：cues.json 的音频提示点与视觉事件配对，报 dt 超容差项。支持
    cue 自带 visual_at / visual_t 画面锚点（PIL 路线没有 window.getEvents() 也能自校验），
    并可用 require_sync（环境变量 QA_REQUIRE_SYNC=1 / CLI --require-sync）把
    "同步门禁没执行"从 warning 升级为 error。
@@ -22,7 +22,7 @@
    （亮度曲线 + 响度曲线 + 闪烁点 + 空窗区 + 同步偏差，一眼看出问题位置）。
 
 判据与阈值来自 ai-history-film（MIT）的实测经验：
-- docs/开发日志.md 第十四轮"单帧闪烁"：逐帧解码成 160x90、每帧减去前后两帧平均、分块统计，
+- 开发日志第十四轮"单帧闪烁"：逐帧解码成 160x90、每帧减去前后两帧平均、分块统计，
   找"只亮一帧"的格子。实测真实异常 10–15，正常运动画面 ≤ 6.4，因此默认阈值 6.0。
 - 第五轮"画面空窗"：逐帧亮度扫出 ≥ 1 s 近黑片段（保留片头、片尾等刻意黑）。
 - video/qa_sync.js：画面视觉事件（闪白/震屏/冲击环）与音频 cue 对照。
@@ -39,7 +39,7 @@ FILMKIT_FFMPEG）。正常 import 不做重活、不打印。
 """
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "1.0.4"
 
 import argparse
 import json
@@ -81,6 +81,10 @@ FLICKER_ISO = 1.5       # 孤立性比值：当前帧异常度 >= 1.5 x 前后
 # "回到原位"闸门：|F[t+1]-F[t-1]| 必须小于 1.6 x 中间帧偏离量。
 # 单帧闪烁 ≈ 0（前后几乎相同）；加速运动 ≈ 2 以上（前后差更多）→ 排除。
 FLICKER_RETURN_RATIO = 1.6
+# 符号一致度下限：块内像素"同向"变化的比例。真闪白/闪黑整块同向（0.75–1.0）；
+# 文字入场 / 母题动画 / 镜头缓推是有增有减的纹理变化（实测 0.42）。
+# 低于此值不判 error（降级 warning 供人复核）——否则零拷贝首片会被 G9 误杀。
+FLICKER_AGREE_MIN = 0.60
 # 与已登记视觉事件（闪白/震屏/冲击环）重合多久内视为"设计好的重击"，不计 error
 FLICKER_EXPLAIN_WIN = 0.2
 # 转化为"可解释设计事件"的 event.kind（小写匹配；cues.json §4.2 的 events 由页面导出）
@@ -98,18 +102,17 @@ TAIL_SKIP = 1.2         # 片尾多少秒内不算（刻意淡出）
 # 音画同步
 SYNC_TOL = 0.06         # dt 容差（秒）
 SYNC_SAME_WIN = 2.0     # 同 kind 配对的最大搜索窗（秒）
-# 异 kind 的"就近配对"现在只用于**确认同步**（|dt| <= tol 才认可），不再有独立的搜索窗；
+# 异 kind 的"就近配对"只用于**确认同步**（|dt| <= tol 才认可），没有独立的搜索窗；
 # 这个常量保留给"events 每项带可选 cue 字段、允许跨 kind 显式配对"的下一版（CONTRACT §5.4 兼容位）。
 SYNC_NEAR_WIN = 0.5
 
-# 画面"长时间静止"警告（可能卡帧 / 忘了加动画）—— v0.4.0 重写判据
+# 画面"长时间静止"警告（可能卡帧 / 忘了加动画）
 #
-# 旧判据（v0.3.0）：160x90 全帧平均亮度在 3 s 滑动窗内波动 < 0.002。
-# 它对**局部动画**天生不敏感：逐字入场、数字滚动、卡片切换只占全屏几个百分点，
-# 平均亮度几乎不动。实测自带模板片（30.10 s）因此报出 4 段假"亮度长时间无变化"
-# （411/814 个窗口命中），而画面一直在动——这是本轮修掉的假阳性。
+# 不用"全帧平均亮度 3 s 滑动窗内波动 < 0.002"这类判据：它对**局部动画**天生不敏感，
+# 逐字入场、数字滚动、卡片切换只占全屏几个百分点，平均亮度几乎不动。实测自带模板片
+# （30.10 s）会因此报出 4 段假"亮度长时间无变化"（411/814 个窗口命中），而画面一直在动。
 #
-# 新判据看"画面里最活跃的 8x8 块，在 0.5 s 里变了多少级灰度"：
+# 本判据看"画面里最活跃的 8x8 块，在 0.5 s 里变了多少级灰度"：
 #   drift[t] = max over 8x8 blocks of mean |F[t] - F[t-lag]| * 255,  lag = 0.5 s * fps
 # 物理含义：把画面切成 8x8 块（160x90 下共 20x11 块，单块占全屏 0.53%），取
 # "0.5 秒内变化最大的那一块的平均变化量"（单位：灰度级 0–255）。
@@ -366,11 +369,16 @@ def sample_frames(path, w=160, h=90, from_s=0.0, to_s=None) -> np.ndarray:
     return np.stack(frames, axis=0)
 
 
-def _block_max(diff, block) -> tuple[float, tuple[int, int, int, int], float]:
-    """把 (h,w) 差异图按 block×block 分块取均值最大，返回 (最大均值, bbox, 该块中值)。
+def _block_max(diff, block, signed=None) -> tuple:
+    """把 (h,w) 差异图按 block×block 分块取均值最大，返回 (最大均值, bbox, 该块中值, 符号一致度)。
 
     中值是复核线索：整块一起变亮（真单帧事件）时中值也高；只有小块元素在动时
     均值被少数像素拉高、中值仍接近 0（见 references/frame-qa.md 的 16.933 s 案例）。
+
+    符号一致度（signed 传带符号的二阶差分时才算）：整块**同向**变亮/变暗
+    = 真闪白/闪黑；文字逐字入场、母题动画、镜头缓推产生的只是**有增有减**的纹理变化，
+    符号一致度低。实测（零拷贝首片）：t=5.867s 被误报的块 score 51.5 / median 44.5，
+    但符号一致度只有 0.42；同一位置人为注入 +50 灰闪白后一致度 0.75。
     """
     h, w = diff.shape
     b = max(1, int(block))
@@ -387,7 +395,14 @@ def _block_max(diff, block) -> tuple[float, tuple[int, int, int, int], float]:
     bb = (x0, y0, x1, y1)
     blk = diff[y0:y1, x0:x1]
     med = float(np.median(blk)) if blk.size else 0.0
-    return float(means[r, c]), bb, med
+    agree = None
+    if isinstance(signed, np.ndarray) and signed.shape == diff.shape:
+        sblk = signed[y0:y1, x0:x1].astype(np.float64)
+        if sblk.size:
+            m = float(sblk.mean())
+            # 与"块内平均方向"同向的像素占比：整块同向变亮 ≈ 1.0，纹理/运动互有增减 ≈ 0.5
+            agree = float(np.mean(np.sign(sblk) == np.sign(m))) if m != 0 else 0.0
+    return float(means[r, c]), bb, med, agree
 
 
 def _block_peak(diff, block) -> float:
@@ -434,10 +449,11 @@ def _scan_full(path, w=SAMPLE_W, h=SAMPLE_H, block=FLICKER_BLOCK, fps=None):
         if len(history) > lag:
             history.pop(0)
         if prev2 is not None:
-            diff = np.abs(prev1 - (prev2 + fr) * 0.5) * 255.0
-            s, bb, med = _block_max(diff, block)
+            signed = (prev1 - (prev2 + fr) * 0.5) * 255.0
+            diff = np.abs(signed)
+            s, bb, med, agree = _block_max(diff, block, signed=signed)
             scores.append(float(s))
-            boxes.append((bb, med))
+            boxes.append((bb, med, agree))
             # 同一个块上算"前后两帧彼此差多少"，用于区分闪烁与加速运动
             if bb:
                 x0, y0, x1, y1 = bb
@@ -502,7 +518,9 @@ def _flicker_from_scores(scores, boxes, fps, thresh, returns=None, suppressed=No
             continue
         if s < FLICKER_ISO * max(p, q):
             continue
-        bb, med = boxes[t - 1] if 0 <= t - 1 < len(boxes) else ((0, 0, 0, 0), 0.0)
+        box = boxes[t - 1] if 0 <= t - 1 < len(boxes) else ((0, 0, 0, 0), 0.0, None)
+        bb, med = box[0], box[1]
+        agree = box[2] if len(box) > 2 else None
         r = None
         if returns is not None and t < len(returns):
             r = float(returns[t])
@@ -522,6 +540,7 @@ def _flicker_from_scores(scores, boxes, fps, thresh, returns=None, suppressed=No
                     "bbox": [int(v) for v in bb],
                     "ratio": round(s / max(p, q, 1e-9), 2),
                     "median": round(float(med), 2),
+                    **({"agree": round(float(agree), 2)} if agree is not None else {}),
                     **({"return": round(r, 2)} if r is not None and math.isfinite(r) else {})})
     return out
 
@@ -640,10 +659,10 @@ def _src_of(obj) -> str:
 def _src_compatible(cue, ev) -> bool:
     """两个条目能不能做同步配对：只有**双方都明确标了来源且不同**时才认为时间基准不同。
 
-    v0.7.1 起 render.py 在 engine=web 时把三路 cue 合并（film.json / scenes.py / 页面），
+    render.py 在 engine=web 时把三路 cue 合并（film.json / scenes.py / 页面），
     其中 scenes.py 的 cue 按 PIL 时间轴、页面事件按页面时间轴——跨基准配对会报假 FAIL
     （实测：cue ui_blip @7.725s 配 页面事件 @9.550s，dt=+1.825s）。
-    没标 src 的条目（手写 events / 老版本 cues.json）一律视作兼容，保持向后兼容。
+    没标 src 的条目（手写 events / 缺 src 的 cues.json）一律视作兼容，保持向后兼容。
     """
     cs, es = _src_of(cue), _src_of(ev)
     return not (cs and es and cs != es)
@@ -656,7 +675,7 @@ def _compatible_events(cue, events) -> list:
 def _match_cue(cue, events, tol) -> tuple[dict | None, float | None, str]:
     """给一个 cue 找对应视觉事件。
 
-    规则（v0.3.0 收紧）：
+    规则：
       1. 同 kind：kind == cue.type，搜索窗 SYNC_SAME_WIN（2 s）；
       2. 异 kind：只取时间最近者，且**只有 |dt| <= tol 时才认可**（用作"确实同步了"的佐证）。
          超过容差就不配对——跨 kind 的"最近事件"不是"预期事件"，据此判超差会制造假 FAIL。
@@ -695,10 +714,10 @@ def sync_check(cues, events, tol=SYNC_TOL) -> list[dict]:
 
     返回 [{"cue","cue_t","event_t","dt"}]，dt = event_t - cue_t（秒，3 位小数）。
     配对规则（按优先级）：
-      0. **cue 自带视觉锚点**（v0.4.0 新增）：cue 里写了数值 visual_at / visual_t 时，
+      0. **cue 自带视觉锚点**：cue 里写了数值 visual_at / visual_t 时，
          直接拿它当"这条音效对应的画面时刻"自校验，不需要 events。
          这条是给 PIL 路线补的口子——pil 引擎没有 window.getEvents()，events 恒空，
-         原来的 sync 检查在 PIL 路线**永远是空的**，但 SKILL.md §7 把"
+         没有这条口子 sync 检查在 PIL 路线**永远是空的**，但 SKILL.md §7 把"
          dt ≤ 60 ms"写成通用门禁（文档承诺、代码没做到）。
          用法：scenes.py 的 cues() 钩子里返回
              {"at": "l03+0.35", "type": "impact", "visual_at": "abs:12.42"}
@@ -708,7 +727,7 @@ def sync_check(cues, events, tol=SYNC_TOL) -> list[dict]:
          超过容差就不配对——跨 kind 的"最近事件"不是"预期事件"，据此判超差会制造假 FAIL。
     配不上的 cue 视为"没有对应视觉事件"，不判超差（很多音效本来就没有画面事件）。
     ⚠ 命名约定见 references/frame-qa.md §2.5：events 与 cue 不同名时本检查会静默全过。
-    ⚠ 来源（src）过滤（v0.7.1 起）：cue 与事件**双方都标了 src 且不同**时不配对——web 引擎
+    ⚠ 来源（src）过滤：cue 与事件**双方都标了 src 且不同**时不配对——web 引擎
     三路合并时 PIL 时间轴的 cue 与页面事件基准不同，跨基准配对会报假 FAIL。跳过数量由
     _sync_coverage().src_skipped 计数并在 _load_cues 里转成 warning（不静默）。
     """
@@ -852,7 +871,7 @@ def _load_cues(cues_json):
     cues = [c for c in (data.get("cues") or []) if isinstance(c, dict)]
     raw_events = [e for e in (data.get("events") or []) if isinstance(e, dict)]
     # 只认"带有限数值 t"的事件：sync_check 内部本来就这么过滤（e.get("t") is not None），
-    # 但 _sync_coverage / 命名约定守卫以前拿的是**未过滤**的列表 —— 于是 events 里只要有
+    # 但 _sync_coverage / 命名约定守卫必须用**过滤后**的列表 —— 否则 events 里只要有
     # {"kind": "impact"} 这种缺 t 的条目，judged 就会被算成 1，命名约定守卫也被骗过，
     # 结果是"门禁看起来在查、实际一条都没判"且不报警（实测：cues=1/events=[{kind:impact}]
     # -> coverage judged=1，report errors=[] warnings=[]）。
@@ -963,7 +982,7 @@ def _visual_event_times(events) -> list[float]:
 def _static_segments(drift, fps, blacks=None) -> list[tuple[float, float]]:
     """画面长时间"完全没有运动"（卡帧 / 忘了加动画）-> [(t0, t1)] 秒区间。
 
-    判据（v0.4.0 重写，替换原来的"全帧平均亮度 3 s 波动 < 0.002"）：
+    判据（不用"全帧平均亮度 3 s 波动 < 0.002"，理由见下）：
       对每个窗口起点 i，看 (i+lag, i+w] 这 w-lag 个 drift 值（drift[t] = "t 与 t-lag
       之间最活跃的 8x8 块平均变了多少级灰度"）是否都 <= FLAT_DRIFT_EPS。
     全部命中 → 这 6 秒里画面里任何一个 8x8 块在任意 0.5 s 内都没动过，人眼就是一张定格。
@@ -1019,7 +1038,7 @@ def _static_warnings(drift, fps, blacks=None) -> list[str]:
     for t0, t1 in segs:
         out.append(
             "画面长时间静止（可能卡帧/忘了加动画）：%.2f–%.2fs（连续 %.1fs 内最活跃的 8x8 块"
-            "在任意 %.1f s 里的变化都 < %.1f 级灰度；判据见 references/frame-qa.md §2.7）"
+            "在任意 %.1f s 里的变化都 < %.1f 级灰度；判据见 references/frame-qa.md §2.4b）"
             % (t0, t1, t1 - t0, FLAT_LAG_S, FLAT_DRIFT_EPS))
     return out
 
@@ -1042,7 +1061,7 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
     cues_json 可以是路径或已载入的 dict；events 里闪白/震屏/冲击环时刻会用来排除
     "设计好的重击"（记 warning，不记 error）。
 
-    require_sync（v0.4.0 新增）：把"音画同步门禁没能执行"从 warning 升级为 error。
+    require_sync：把"音画同步门禁没能执行"从 warning 升级为 error。
       默认 None = 读环境变量 QA_REQUIRE_SYNC（1/true/yes/on 时开启），便于不改进 render.py
       就整体开闸（render.py 的 st_qa 调的正是本函数）。
       背景：SKILL.md §7 把"音画同步 dt ≤ 60 ms"写成通用门禁，但 --engine pil 时 cues.json
@@ -1079,13 +1098,28 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
         fl["expected"] = any(abs(fl["t"] - te) <= FLICKER_EXPLAIN_WIN for te in explained_times)
 
     errors = []
+    textured = []
     for fl in flicker:
         if fl.get("expected"):
             continue
         bb = fl.get("bbox") or [0, 0, 0, 0]
-        errors.append("单帧闪烁 t=%.3fs score=%.1f（孤立比值 %.2f，块中值 %.2f，异常块 %d,%d–%d,%d，阈值 %.1f）"
-                      % (fl["t"], fl["score"], fl.get("ratio", 0.0), fl.get("median", 0.0),
-                         bb[0], bb[1], bb[2], bb[3], FLICKER_THRESH))
+        msg = ("t=%.3fs score=%.1f（孤立比值 %.2f，块中值 %.2f，异常块 %d,%d–%d,%d，阈值 %.1f）"
+               % (fl["t"], fl["score"], fl.get("ratio", 0.0), fl.get("median", 0.0),
+                  bb[0], bb[1], bb[2], bb[3], FLICKER_THRESH))
+        # 符号一致度 = 块内像素是否**同向**变亮/变暗。
+        # 真闪白/闪黑整块同向（实测 0.75–1.0）；文字逐字入场、母题动画、镜头缓推
+        # 是"有增有减"的纹理变化（实测 0.42）。不降级的后果是首片就 fail 在 G9
+        # （零拷贝自测实测：t=5.867s 标题逐字入场被误判）。
+        # 处理：低于阈值不静默放过，降级为 warning 并保留全部数值，交给人工复核。
+        fl["sign_agree"] = fl.get("agree")
+        if fl.get("agree") is not None and float(fl["agree"]) < FLICKER_AGREE_MIN:
+            textured.append(msg + ("，符号一致度 %.2f < %.2f → 判为纹理/动画扰动"
+                                   % (float(fl["agree"]), FLICKER_AGREE_MIN)))
+            continue
+        errors.append("单帧闪烁 " + msg)
+    for msg in textured:
+        warnings.append("疑似非闪烁（块内像素有增有减，像是文字/母题动画）：" + msg
+                        + "；若画面确有单帧闪白，调低 FLICKER_AGREE_MIN 或登记设计事件")
     explained = sum(1 for fl in flicker if fl.get("expected"))
     if explained:
         warnings.append("已排除 %d 处与已登记视觉事件（闪白/震屏/冲击环）重合的单帧闪烁；"
@@ -1147,7 +1181,7 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
     rep = {"flicker": flicker, "black_windows": blacks, "luma": luma, "loudness": loud,
            "sync": sync, "errors": errors, "warnings": warnings,
            # sync_info：同步门禁到底查了多少（render.py:1172 一直在读 deep["sync_info"]["judged"]，
-           # 但 report() 以前从来不写这个键 —— 所以 QC 报告的 G9 永远显示"同步未判"）。
+           # 缺了这个键 QC 报告的 G9 就永远显示"同步未判"）。
            "sync_info": dict(sync_info)}
     if out_json:
         _write_json(rep, out_json)
@@ -1396,7 +1430,7 @@ def _draw_png(rep, film, fps, duration, events, out_png):
              "重合（设计重击，不计 error）" % SYNC_TOL)
     d.text((PLOT_ML, 788), foot1, fill=gray, font=f_small)
     d.text((PLOT_ML, 808), foot2, fill=gray, font=f_small)
-    d.text((W - PLOT_MR, 808), "qa_frames v0.3.0", fill=(160, 163, 172), font=f_small,
+    d.text((W - PLOT_MR, 808), "qa_frames", fill=(160, 163, 172), font=f_small,
            anchor="ra")
 
     out_png = str(out_png)
@@ -1854,8 +1888,8 @@ def selftest() -> int:
                          out_json=out_json, out_png=out_png)
             keys = {"flicker", "black_windows", "luma", "loudness", "sync",
                     "errors", "warnings"}
-            # sync_info 是 v0.7.2 的**增量**字段（render.py 的 G9 从 deep["sync_info"]["judged"]
-            # 读"同步到底判了几条"，以前 report() 不写它 -> QC 报告永远显示"同步未判"）。
+            # sync_info 是报告里的**增量**字段（render.py 的 G9 从 deep["sync_info"]["judged"]
+            # 读"同步到底判了几条"，缺了它 -> QC 报告永远显示"同步未判"）。
             # 契约 §4.5 的 7 个键必须齐全，允许额外的只读统计键。
             if not keys.issubset(set(rep)):
                 return False, "顶层字段 %s 缺 §4.5 键" % sorted(keys - set(rep))
@@ -1985,7 +2019,7 @@ def selftest() -> int:
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(
         prog="qa_frames.py",
-        description="帧级 / 时间轴级深度质检：单帧闪烁、画面空窗、音画同步（v0.3.0）")
+        description="帧级 / 时间轴级深度质检：单帧闪烁、画面空窗、音画同步")
     ap.add_argument("film", nargs="?", help="成片路径（.mp4 等）")
     ap.add_argument("--cues", default=None,
                     help="work/cues.json（§4.2：cues 音频提示点 + events 视觉事件）")

package/skills/video-studio/scripts/qaasr.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-"""qaasr.py — ASR 回读校验（v0.8.0）。
+"""qaasr.py — ASR 回读校验。
 
-v0.7 及以前的质检只看"容器 / 响度 / 帧 / 音画同步"，都建立在一个假设上：
+容器 / 响度 / 帧 / 音画同步这几层质检，都建立在一个假设上：
 **成片音轨里念的就是剧本那几句话**。可是 TTS 缓存串了、换声线时漏了某句、
 混音把某一段压没了、重新渲了但音轨是旧的——这些从容器和波形上都看不出来。
 本模块把成片音轨转回文字，和剧本逐句对账：
@@ -66,7 +66,7 @@ tiny 只适合快速冒烟（错字多、时间戳只到整秒）。默认 model
 """
 from __future__ import annotations
 
-__version__ = "0.8.0"
+__version__ = "1.0.4"
 
 import argparse
 import json
@@ -101,7 +101,7 @@ AUDIO_SR = 16000
 OFFSET_WARN_S = 0.35
 # 召回率的 pass / fail 线。**权威值在 render.py**（QA_ASR_RECALL_PASS / QA_ASR_RECALL_WARN，
 # G12 门禁从这里读），本模块只是把默认值对齐，避免"同一部片、CLI 判 fail、门禁判 pass"：
-# 同一事实只能有一个权威值（CHANGELOG v0.4 D 节）。
+# 同一事实只能有一个权威值。
 # 为什么是 0.85 / 0.72 而不是 0.95 / 0.90：中文旁白实测（模板片，faster-whisper small）
 # 干净成片召回只有 0.81–0.83 —— 中英混排专名（"DeepSeek 4.1 Flash"→DIXX 变体）是 ASR 的
 # 正常误差，不是片子坏了；低于 0.72 才说明"整句丢了 / 音轨跟剧本不是一套"。
@@ -821,9 +821,13 @@ def _judge(scenes, segments, *, recall_pass=QA_RECALL_PASS, recall_warn=QA_RECAL
     assigned = _assign_text(scenes, segments)
     per_line, missing, offsets, offset_ref = [], [], {}, {}
     tot_ref, tot_hit = 0, 0
+    lost_counter = Counter()                            # 全片"ref 有、ASR 没对上"的字符
     for sc, got in zip(scenes, assigned):
         ref = _norm_text(sc.get("text"))
         hyp = _norm_text(got["text"])
+        lost = Counter(ref) - Counter(hyp) if ref else Counter()
+        if lost:
+            lost_counter.update(lost.elements())
         hit = sum((Counter(ref) & Counter(hyp)).values()) if ref else 0
         r = (hit / float(len(ref))) if ref else 1.0
         tot_ref += len(ref)
@@ -833,6 +837,8 @@ def _judge(scenes, segments, *, recall_pass=QA_RECALL_PASS, recall_warn=QA_RECAL
             "end": round(float(sc["end"]), 3), "ref_chars": len(ref),
             "asr_chars": len(hyp), "hit_chars": hit, "recall": round(r, 4),
             "asr_text": got["text"][:200],
+            # 单段掉分定位：这一段里"剧本有、ASR 没对上"的字（最多 6 个）
+            "lost": ["%s×%d" % (ch, n) for ch, n in lost.most_common(6)] if lost else [],
         })
         if ref and r < MISS_LINE_RECALL:
             missing.append(sc["id"])
@@ -866,8 +872,21 @@ def _judge(scenes, segments, *, recall_pass=QA_RECALL_PASS, recall_warn=QA_RECAL
                       % (recall, recall_warn, tot_ref, tot_hit))
         status = "fail"
     elif recall < recall_pass - 1e-12:
+        # 只报"召回 0.813"没法修：实测掉分几乎全在中英混排专名（"DeepSeek 4.1 Flash"
+        # 被听成 DIXX 之类）。这里把"剧本里有、成片里没对上"的字符按次数排出来，
+        # 让 agent 知道该改哪几个词（改读法 / 加同音别名 / 换掉 ASR 不认的写法）。
         warnings.append("ASR 回读字符召回 %.3f 低于 pass 线 %.2f（但高于 fail 线 %.2f）："
                         "pass 但记 warning，别当完全没问题" % (recall, recall_pass, recall_warn))
+        if lost_counter:
+            tips = "、".join("%s×%d" % (ch, n) for ch, n in lost_counter.most_common(12))
+            warnings.append("成片里没对上的字（ref 有 / ASR 无，按次数）：%s —— 多是专名读法，"
+                            "改剧本写法或在 film.json 的 qa.asr 放宽" % tips)
+        worst = sorted((p for p in per_line if p.get("lost")),
+                       key=lambda p: float(p.get("recall") or 0.0))[:2]
+        for p in worst:
+            warnings.append("最差段落 %s（召回 %.2f，%d/%d 字）：没对上 %s；ASR 实际读到 %r"
+                            % (p["id"], float(p["recall"]), p["hit_chars"], p["ref_chars"],
+                               "、".join(p["lost"]), p["asr_text"][:50]))
         status = "pass"
     else:
         status = "pass"
@@ -879,6 +898,7 @@ def _judge(scenes, segments, *, recall_pass=QA_RECALL_PASS, recall_warn=QA_RECAL
         detail += "；最大偏移 %s %+.2fs" % (worst[0], float(worst[1]))
     return {
         "recall": round(recall, 4), "ref_chars": tot_ref, "hit_chars": tot_hit,
+        "lost_top": [{"ch": ch, "n": n} for ch, n in lost_counter.most_common(20)],
         "per_line": per_line, "missing_lines": missing,
         "offsets": offsets, "offset_ref": offset_ref, "offset_warn_s": float(offset_warn),
         "gate": {"id": "asr", "title": "ASR 回读（原稿 vs 成片旁白）",
@@ -1145,7 +1165,7 @@ def report(film_mp4, tl, script=None, *, model_size="small", lang="zh", out_json
         rep["audio_s"] = audio_info.get("duration")     # 前面探测过，不重复跑 ffprobe
     judged = _judge(scenes, rep["asr_segments"], recall_pass=recall_pass,
                     recall_warn=recall_warn, offset_warn=offset_warn)
-    for key in ("recall", "ref_chars", "hit_chars", "per_line", "missing_lines",
+    for key in ("recall", "ref_chars", "hit_chars", "lost_top", "per_line", "missing_lines",
                 "offsets", "offset_ref", "gate", "warnings", "errors"):
         rep[key] = judged[key]
     if asr.get("parse_skipped"):
@@ -1491,8 +1511,7 @@ def _utf8_stdout() -> None:
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(
         prog="qaasr.py",
-        description="ASR 回读校验：把成片音轨转回文字，与 timeline/剧本做字符级召回与偏移检查"
-                    "（v0.8.0）")
+        description="ASR 回读校验：把成片音轨转回文字，与 timeline/剧本做字符级召回与偏移检查")
     ap.add_argument("film", nargs="?", help="成片路径（有音轨即可，视频轨不参与）")
     ap.add_argument("--timeline", default=None,
                     help="work/timeline.json（scenes[].id/start/end，可选 voice_start/voice_end/text）")

package/skills/video-studio/scripts/qavmaf.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""qavmaf.py — 全片 VMAF/SSIM 画质门禁（v0.8.0）。
+"""qavmaf.py — 全片 VMAF/SSIM 画质门禁。
 
 为什么要有它
 ------------
@@ -83,7 +83,7 @@ report(film_mp4, tl, scenes_mod, script, *, mode="full", out_json=None,
      · 宽高比不是 16:9 横屏（本项目只做 16:9 缩放输出）；
      · 成片尺寸与 timeline.video 声明的交付尺寸不一致（顶层规格被改动）；
      · 读不出成片分辨率。
-   - v0.8 的"下采样交付"是合法配置：内部构图恒 1920x1080，编码时 lanczos
+   - "下采样交付"是合法配置：内部构图恒 1920x1080，编码时 lanczos
      缩到 1280x720 / 960x540。此时本模块**在成片分辨率下比较**——参考流在
      ffmpeg 滤镜图里用 scale=w:h:flags=lanczos 缩到成片分辨率（与 FrameSink
      编码时同口径，不用 PIL resize）；返回 dict 的 ref_scale 记录映射关系。
@@ -108,7 +108,7 @@ CLI
 """
 from __future__ import annotations
 
-__version__ = "0.8.0"
+__version__ = "1.0.4"
 
 import argparse
 import importlib.util
@@ -451,14 +451,34 @@ def _as_script(script) -> dict:
 
 # ---------------------------------------------------------------- 参考帧管线（复刻 render.py）
 def _looks_legacy(script) -> bool:
-    """有没有"风格"信息：没有就是 v0.4 legacy 外观（与 stylekit 的判据一致）。"""
+    """有没有"风格"信息：没有就是 legacy 外观（与 stylekit 的判据一致）。"""
     vis = script.get("visual") if isinstance(script.get("visual"), dict) else {}
     mus = script.get("music") if isinstance(script.get("music"), dict) else {}
     return ("style" not in script) and not vis.get("theme") and not mus.get("style")
 
 
 def _style_plan(script) -> dict:
-    """解析剧本风格计划：优先复用 script["_style"]，否则调 stylekit（纯函数、确定性）。"""
+    """解析剧本风格计划：**design 优先**，其次 script["_style"]，最后 stylekit。
+
+    为什么必须先看 design："这一版长什么样"由 work/design.json 决定，
+    而 qavmaf 是**独立进程**——它拿到的 script 里没有 render 塞进去的 _style。
+    直接调 stylekit 会把 design 路径的片子解析成 tech-deep（默认风格），
+    参考帧用一套主题、成片用另一套：实测 VMAF 1.50、同源抽查 MAE=0.0384。
+    这不是"画质劣化"，是**参考帧根本不是同一部片**。
+    """
+    # ① design（与 render._plan_from_design 同一口径）
+    design = script.get("design") if isinstance(script, dict) else None
+    if isinstance(design, dict) and design:
+        import designkit as DK
+        bad = DK.validate_design(design)
+        if bad:
+            raise LookupError("design.json 没过校验，参考帧无法与成片同源：%s" % "；".join(bad[:3]))
+        return DK.design_to_plan(design)
+    # ② 调用方已经解析过（extract_frames 会塞进来）
+    cached = script.get("_style") if isinstance(script, dict) else None
+    if isinstance(cached, dict) and cached:
+        return cached
+    # ③ 老路径：stylekit
     try:
         import stylekit as ST
     except Exception as e:              # noqa: BLE001
@@ -495,7 +515,7 @@ ASPECT_TOL = 0.01                 # 宽高比容差（与 filmkit.video_plan 一
 def _declared_out_size(tl, script):
     """交付规格：timeline.video（render.py 写出的快照）优先，其次剧本里的 video 块。
 
-    返回 (out_w, out_h)；未声明时返回 None（老 timeline 升级前生成，行为同 v0.7）。
+    返回 (out_w, out_h)；未声明时返回 None（老 timeline 没有 video 块时的行为）。
     """
     for src in ((tl or {}).get("video"), (script or {}).get("video")):
         if not isinstance(src, dict):
@@ -518,7 +538,7 @@ def _judge_sizes(info, tl, script, comp_w, comp_h):
       "scale"  成片是 16:9 下采样交付，参考流在 ffmpeg 滤镜图里 lanczos 缩到成片尺寸
       "fail"   结构性不符：上采样 / 非 16:9 / 读不出尺寸 / 与声明交付尺寸不一致
 
-    v0.8 的合法配置是"内部构图恒 1920x1080，编码时 lanczos 缩到 1280x720/960x540"。
+    合法配置是"内部构图恒 1920x1080，编码时 lanczos 缩到 1280x720/960x540"。
     上采样不是合法交付（只会把 1080p 包装成更高分辨率），这里明确挡住。
     """
     fw, fh = info.get("width"), info.get("height")
@@ -563,10 +583,17 @@ def _prepare_script(script, tl):
     """
     sc = dict(script)                   # 浅拷贝：不改调用方的对象
     sc["_total"] = float(_f(tl.get("total"), 0.0))
-    plan = sc.get("_style")
-    if not isinstance(plan, dict):
+    # design 必须**优先于**缓存的 _style：调用方（render.st_qa）可能已经用一个
+    # 错误的 _style 污染过 script —— 它自己解析时没传 work、读不到 design.json，
+    # 于是 _style 是 stylekit 的 auto 结果。看到 _style 就直接用，等于沿用那个错误。
+    if isinstance(sc.get("design"), dict) and sc["design"]:
         plan = _style_plan(sc)
         sc["_style"] = plan
+    else:
+        plan = sc.get("_style")
+        if not isinstance(plan, dict):
+            plan = _style_plan(sc)
+            sc["_style"] = plan
     legacy = bool((plan or {}).get("legacy"))
     if legacy:
         return sc, None
@@ -577,22 +604,48 @@ def _prepare_script(script, tl):
     return sc, theme
 
 
-def _draw_subtitle_like_render(frame, text, theme, words):
-    """烧字幕，与 render.py 同口径（v0.8 起带 words 词边界折行）。
+def _sub_kw_for(script) -> dict:
+    """从已解析的风格计划里取字幕样式参数（与 render.py:_sub_kw 同口径）。
+
+    ⚠ 为什么参考帧必须传这些参数（实测的**误杀好片**缺陷）：
+    render.py 的 frames / stills 阶段会传 design 的 visual.subtitle（size/align/
+    plate_alpha/radius/max_lines/family/y）；参考帧不传就永远是 filmkit 的模块
+    默认值（size=46 等）。同一部片（设计 size=52 / radius=14 / plate_alpha=180）
+    实测 VMAF 91.33 —— 被阈值 92 判 fail，而两条路径用同一份参数时 ≥96。
+    门禁误杀好片比漏查更有害，所以这里必须与主渲染路径吃同一份参数。
+
+    实现在 filmkit.subtitle_kwargs（**不复制第二份**：两份迟早漂移）；
+    老版 filmkit 没有这个函数时退回空 dict（= 旧行为，跨版本兼容）。
+    """
+    plan = script.get("_style") if isinstance(script, dict) else None
+    fn = getattr(_K, "subtitle_kwargs", None)
+    if fn is None:                      # 老 filmkit：还没有字幕样式参数
+        return {}
+    try:
+        kw = fn(plan)
+    except Exception:                   # noqa: BLE001 —— 样式解析失败不该挡住整片门禁
+        return {}
+    return kw if isinstance(kw, dict) else {}
+
 
-    ⚠ 参考帧为什么不传 words 是个**会误杀好片**的缺陷（实测）：
+def _draw_subtitle_like_render(frame, text, theme, words, kw=None):
+    """烧字幕，与 render.py 同口径（带 words 词边界折行与设计字幕样式）。
+
+    ⚠ 参考帧不传 words 也是**会误杀好片**的缺陷（实测）：
     render.py 的 frames / stills 阶段调 draw_subtitle 时总会传 words，
     字幕会按词边界折行（"…整整 / 一句旁白"）；参考帧不传就退回字符折行
     （"…整整一 / 句旁白"）。38 字字幕只差一个断点、约 2% 像素不同，
     但近静态画面的 VMAF 从 99.95 掉到 8.55 —— 门禁会把同源的好片判 fail。
-    老版 filmkit 的 draw_subtitle 没有 words 形参，TypeError 时退回旧调用。
+    kw 是 design 的字幕样式（见 _sub_kw_for）；老版 filmkit 的 draw_subtitle
+    没有 words 形参，TypeError 时退回旧调用（保留）。
     """
+    kw = kw or {}
     if not words:
-        return _K.draw_subtitle(frame, text, theme=theme)
+        return _K.draw_subtitle(frame, text, theme=theme, **kw)
     try:
-        return _K.draw_subtitle(frame, text, theme=theme, words=words)
+        return _K.draw_subtitle(frame, text, theme=theme, words=words, **kw)
     except TypeError:                   # 老 filmkit：没有 words 形参（保持旧行为）
-        return _K.draw_subtitle(frame, text, theme=theme)
+        return _K.draw_subtitle(frame, text, theme=theme, **kw)
 
 
 def _draw_ref_frame(scenes, scenes_mod, script, theme, fi, fps, total):
@@ -625,7 +678,9 @@ def _draw_ref_frame(scenes, scenes_mod, script, theme, fi, fps, total):
             words = fn(scenes, t, hold) if fn is not None else None
         except Exception:               # noqa: BLE001 —— 词表异常不该让参考帧渲不出来
             words = None
-        frame = _draw_subtitle_like_render(frame, text, theme, words)
+        # 字幕样式也必须与主渲染路径同源（见 _sub_kw_for 的实测说明）
+        frame = _draw_subtitle_like_render(frame, text, theme, words,
+                                           kw=_sub_kw_for(script))
     fade = 1.0
     if t < 0.5:
         fade *= _K.ease_out(t / 0.5)
@@ -650,7 +705,7 @@ def _build_filtergraph(fps, step, threads, has_ssim, vmaf_log, ssim_log, dist_fp
       libvmaf/ssim 的 framesync 会按"最近的下界时间戳"凑对，容易错帧。
     - 抽样（step>1）只对成片做 select，参考侧本来只喂抽中的帧，两边帧数天然相等。
     - split=2：**只渲染一遍**参考帧，同时喂 VMAF 与 SSIM 两个滤镜。
-    - ref_scale：v0.8 下采样交付时，把参考流用 lanczos 缩到成片分辨率再比——
+    - ref_scale：下采样交付时，把参考流用 lanczos 缩到成片分辨率再比——
       与 filmkit.FrameSink 编码时的 -vf scale=out_w:out_h:flags=lanczos 同口径
       （不在 PIL 侧缩，避免两套插值口径混用）。
     """
@@ -868,7 +923,7 @@ def report(film_mp4, tl, scenes_mod, script, *, mode="full", out_json=None,
         warnings.append("ffmpeg 构建不含 ssim 滤镜，本次只算 VMAF（SSIM 记为 skipped）")
     rep["ffmpeg"] = ff
 
-    # ---- 3. 成片探测 + 结构性校验（含 v0.8 下采样交付） ----
+    # ---- 3. 成片探测 + 结构性校验（含下采样交付） ----
     info = _probe_film(film)
     rep["film_info"] = info
     W, H = int(getattr(_K, "W", 1920)), int(getattr(_K, "H", 1080))
@@ -1229,13 +1284,24 @@ def draw_frame(scene, t_local, dur, t_global, script, frame):
             fp.write(scenes_src)
         script = {"title": "qavmaf selftest", "lines": [
             {"id": "l01", "text": "一", "sub": "自检"}]}
+        # 没有内置风格表：合成剧本也必须自带一份**现场生成**的设计，
+        # 否则 _style_plan() 解析不出主题（"不写 style 就走老外观"的兼容路径已移除），
+        # 参考帧无法渲染。这里用 designkit 现场采样（seed 固定 = 可复现）、
+        # design_to_plan 与 render 同一口径，**不引入任何写死主题/模板**。
+        try:
+            import designkit as _DK
+            _design = _DK.sample_designs({"topic": "qavmaf selftest"}, n=1, seed=1)[0]
+            script["_style"] = _DK.design_to_plan(_design)
+        except Exception as e:          # noqa: BLE001 —— 缺 designkit 也要给出可读的 FAIL
+            print("[FAIL] 自检需要 designkit.py 现场生成设计（无内置风格）：%s" % e)
+            return 1
         scenes = [dict(script["lines"][0], start=0.0, end=n / float(fps),
                        dur=n / float(fps), voice_start=0.0, voice_end=n / float(fps))]
         tl = {"total": n / float(fps), "fps": fps, "frames": n, "scenes": scenes,
               "video": {"out_w": W, "out_h": H, "scale": False}}
-        # v0.8 下采样交付：内部构图仍 1920x1080，交付 1280x720（编码时 lanczos 缩）
+        # 下采样交付：内部构图仍 1920x1080，交付 1280x720（编码时 lanczos 缩）
         tl720 = dict(tl, video={"out_w": 1280, "out_h": 720, "scale": True})
-        # 老 timeline（v0.7 及以前没有 video 块）：只按"构图同尺寸"校验
+        # 老 timeline（没有 video 块）：只按"构图同尺寸"校验
         tl_legacy = {k: v for k, v in tl.items() if k != "video"}
         # 非法：声明 2560x1440 输出（内部构图只有 1080p，等于上采样）
         tl_up = dict(tl, video={"out_w": 2560, "out_h": 1440, "scale": True})
@@ -1310,7 +1376,7 @@ def draw_frame(scene, t_local, dur, t_global, script, frame):
             return ok and any_w, "frames_compared=%s" % rep["frames_compared"]
 
         def c_downscale_pass():
-            # v0.8 合法配置：1920x1080 内部构图 -> 1280x720 交付，必须 pass；
+            # 合法配置：1920x1080 内部构图 -> 1280x720 交付，必须 pass；
             # 且与 1080p 同规格成片的 VMAF 差 < 3 分（阈值可比）
             rep = report(film_720, tl720, mod, script, mode="full", log=None)
             v1080 = report(film_ok, mode="full", log=None, **base)["vmaf"]["score"]
@@ -1388,7 +1454,7 @@ def draw_frame(scene, t_local, dur, t_global, script, frame):
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(
         prog="qavmaf.py",
-        description="全片 VMAF/SSIM 画质门禁：参考帧由场景函数实时渲染（v0.8.0）")
+        description="全片 VMAF/SSIM 画质门禁：参考帧由场景函数实时渲染")
     ap.add_argument("--film", default=None, help="成片路径（mp4）")
     ap.add_argument("--timeline", default=None, help="work/timeline.json")
     ap.add_argument("--scenes", default=None, help="scenes.py（含 draw_frame）")