@dsh-gis/dsh-video-studio-skill 0.7.2 → 0.8.1

package/tools/ci_check.py

@@ -23,7 +23,11 @@
   11  体积：单个文件不超过 400 KB（技能要能塞进上下文与包里）
   12  film.json 契约：schemas/film.schema.json + scripts/filmcheck.py 校验模板（规则只留一份）
 
-退出码：0 全过；1 有 FAIL。每一项都打印证据，不打"可能有问题"。
+三档结论（与技能自己的门禁账本同口径）：PASS = 这次真的查了且通过；FAIL = 查了没过；
+SKIP = **这次没执行**（比如本地没装 node / npm），**不等于通过**。
+
+退出码：0 = 无 FAIL；1 = 有 FAIL。加 --strict 时 SKIP 也算失败（本地环境缺工具时用它自证"真的全查了"）。
+每一项都打印证据，不打"可能有问题"。
 """
 from __future__ import annotations
 
@@ -44,29 +48,51 @@ TOOLS = ROOT / "tools"
 REFS = SKILL / "references"
 
 # 技能允许的三方依赖（与 README「环境前提」一一对应；加东西必须先改文档）
-ALLOWED_THIRD_PARTY = {"numpy", "PIL", "cv2", "scipy", "edge_tts", "playwright"}
+ALLOWED_THIRD_PARTY = {"numpy", "PIL", "cv2", "scipy", "edge_tts", "playwright",
+                       # v0.8：ASR 回读门禁（可选，缺了 qaasr 自动降级到 ffmpeg whisper / skipped）
+                       "faster_whisper"}
 # 同目录同级模块（拷走整个目录后仍能互相 import）
 LOCAL_MODULES = {"filmkit", "sfxkit", "scorekit", "webengine", "qa_frames", "render", "selfcheck",
                  "stylekit", "voicekit", "scenes", "scenes_demo",
                  # v0.6.0：门禁账本 / 交付报告 / 签核、阶段新鲜度守卫、film.json 契约校验器
-                 "gates", "stagewatch", "filmcheck"}
+                 "gates", "stagewatch", "filmcheck",
+                 # v0.8.0：渲染前资源闸门、全片 VMAF/SSIM 门禁、ASR 回读门禁
+                 "preflight", "qavmaf", "qaasr"}
 MAX_FILE_BYTES = 400 * 1024
+# 体积检查忽略的目录后缀：.team 是本地调研/自测工作区（gitignore），不随包发布；
+# 媒体文件本来就该大（样例片/参考视频），不该拿"能不能塞进上下文"的尺子量。
+SIZE_SKIP_DIRS = {".git", "node_modules", ".team", "work", "out", "__pycache__", ".venv", "venv"}
+SIZE_SKIP_EXT = {".mp4", ".mp3", ".wav", ".mov", ".webm", ".gif", ".webp", ".zip", ".tgz"}
+
+_results: list[tuple[str, str, str]] = []
+
+# 「跳过」的前缀约定：检查函数返回这些开头的字符串表示**这次没有真的查**。
+# 以前这里只有 bool 两态，"跳过（没装 node）"会被记成 PASS——正是本仓库反复声明的
+# "skipped != 通过"，却在仓库级体检自己的汇总里破了例（本地没装 node 的人会看到
+# PASS 12/12，其实第 2、6 项根本没跑）。现在三档：PASS / FAIL / SKIP。
+SKIP_PREFIXES = ("跳过", "skip")
+
 
-_results: list[tuple[bool, str, str]] = []
+def _is_skip(detail: str) -> bool:
+    head = str(detail or "").strip().lower()
+    return any(head.startswith(p) for p in SKIP_PREFIXES)
 
 
 def check(name: str, fn):
-    """跑一项检查；返回 (ok, name, detail)。任何异常都算 FAIL 并保留消息。"""
+    """跑一项检查；返回 PASS / FAIL / SKIP 三态，detail 保留证据或原因。"""
     try:
         detail = fn() or ""
-        _results.append((True, name, str(detail)))
-        return True
+        if _is_skip(detail):
+            _results.append(("SKIP", name, str(detail)))
+            return "SKIP"
+        _results.append(("PASS", name, str(detail)))
+        return "PASS"
     except AssertionError as e:
-        _results.append((False, name, str(e)))
-        return False
+        _results.append(("FAIL", name, str(e)))
+        return "FAIL"
     except Exception as e:                                      # noqa: BLE001
-        _results.append((False, name, "%s: %s" % (type(e).__name__, e)))
-        return False
+        _results.append(("FAIL", name, "%s: %s" % (type(e).__name__, e)))
+        return "FAIL"
 
 
 # ---------------------------------------------------------------- 1 语法
@@ -141,7 +167,16 @@ def t_json():
     bad_badges = [b for b in badges if b != ver]
     assert not bad_badges, ("README 徽章版本 %s 与 package.json version %s 不一致"
                             % ("/".join(bad_badges), ver))
-    return "%d 个 .json 全部可解析；version=%s 与 README 徽章一致" % (len(files), ver)
+    # CHANGELOG 的第一条标题也必须是当前版本：以前只查 README 徽章，于是"发了新版本但
+    # CHANGELOG 顶部还是上一版"没人发现（历史真发生过，见 v0.7.2 的修复记录）。
+    changelog = ROOT / "CHANGELOG.md"
+    assert changelog.is_file(), "缺 CHANGELOG.md"
+    m = re.search(r"^##\s+(\d+\.\d+\.\d+)", changelog.read_text(encoding="utf-8"), re.M)
+    assert m, "CHANGELOG.md 里找不到 \"## X.Y.Z\" 形式的版本标题"
+    assert m.group(1) == ver, ("CHANGELOG 顶部版本 %s 与 package.json version %s 不一致"
+                               "（发版时两处必须同时改）" % (m.group(1), ver))
+    return ("%d 个 .json 全部可解析；version=%s 与 README 徽章 / CHANGELOG 顶部一致"
+            % (len(files), ver))
 
 
 # ---------------------------------------------------------------- 3 技能清单
@@ -197,22 +232,55 @@ def t_pack():
     files = [f["path"] for f in meta.get("files", [])]
     # 垃圾文件可能出现在**包内任意位置**（实测踩过：队友的临时目录建在 skills/ 下，
     # 于是 skills/tmp_scratch_x/webtest/*.mp4 被一起打进包，体量翻倍）。
-    junk_suffix = (".pyc", ".pyo", ".log", ".tmp", ".orig", ".bak", ".mp4", ".wav", ".mkv", ".tgz")
+    junk_suffix = (".pyc", ".pyo", ".log", ".tmp", ".orig", ".bak", ".mp4", ".wav", ".mkv", ".tgz",
+                   # 二进制/可执行文件：技能包里不该有，出现就是某个进程把缓存写进了源码树。
+                   # 实测踩过：输入法按 %SystemDrive%\ProgramData\...\*.bin 往 cwd 落缓存，
+                   # 当时 cwd 正好是 skills/video-studio/scripts/，两个 172 KB 的 .bin 进了包，
+                   # 而旧的 junk 规则只看 .pyc/.log/.mp4 这些后缀，检查照样 PASS。
+                   ".bin", ".dll", ".exe", ".so", ".dylib", ".pyd", ".db", ".sqlite")
     junk_parts = ("__pycache__", "tmp_scratch_", "node_modules", ".pytest_cache", ".cordis")
     junk = [f for f in files
             if f.endswith(junk_suffix) or any(p in f for p in junk_parts)
-            or f.startswith(("work/", "out/", ".team/"))]
+            or f.startswith(("work/", "out/", ".team/"))
+            # 路径里带 % 段 = 某个环境变量没被展开（Windows 上的典型坏路径）。
+            # 发布包里不可能有合法的含 % 路径段，直接判垃圾，而不是去猜是哪个变量。
+            or any("%" in part for part in f.split("/"))]
     assert not junk, ("包内不该有这些文件（临时产物/日志/媒体，属于打包污染）：%s"
                       % ", ".join(junk[:6]))
-    must = ["index.js", "cordis.patch.yml", "icon.svg", "package.json", "README.md",
-            "skills/video-studio/SKILL.md", "skills/video-studio/scripts/filmkit.py",
-            "skills/video-studio/scripts/render.py", "skills/video-studio/scripts/selfcheck.py",
-            "skills/video-studio/assets/film.json", "skills/video-studio/references/quality-gates.md",
-            "schemas/film.schema.json", "tools/ci_check.py", "tools/estimate.py",
-            "tools/audio_similarity.py", "tools/selftest_noscipy.py"]
+    # 根文件清单仍然手写：它们少一个插件就装不起来，而且数量少、变动少。
+    must = ["index.js", "cordis.patch.yml", "icon.svg", "package.json", "README.md"]
     missing = [m for m in must if m not in files]
     assert not missing, "包内缺文件：%s" % ", ".join(missing)
-    return "%d 个文件 / %.0f KB" % (len(files), meta.get("size", 0) / 1024.0)
+    # 目录部分改成**派生式**：skills/ schemas/ locale/ tools/ docs/ 下磁盘上有的（除缓存/字节码）
+    # 必须全部进包。以前这里是手写 must 列表，于是 v0.6 新增的 gates.py / stagewatch.py、
+    # v0.8 新增的 preflight.py / qavmaf.py / qaasr.py / tools/golden_frames.py 都不在列表里——
+    # "必需文件必须在包里"这条检查对**新增文件天然免疫**，等于只保护了第一版写下的那些路径。
+    shipped_dirs = ("skills", "schemas", "locale", "tools", "docs")
+    on_disk = []
+    for d in shipped_dirs:
+        base = ROOT / d
+        if not base.is_dir():
+            continue
+        for p in sorted(base.rglob("*")):
+            if not p.is_file():
+                continue
+            if "__pycache__" in p.parts or p.suffix == ".pyc":
+                continue
+            rel = p.relative_to(ROOT).as_posix()
+            # 命中 junk 的文件不参与"必须进包"的比对：它们本来就不该进包，
+            # 而"磁盘上有就必须进包"会把垃圾反向当成必需文件（实测：给 package.json 加
+            # "!skills/**/*.bin" 排除规则时，这条派生检查反过来 FAIL 了）。
+            if rel.endswith(junk_suffix) or any(k in rel for k in junk_parts) \
+                    or any("%" in part for part in rel.split("/")):
+                continue
+            on_disk.append(rel)
+    packed_set = {f.replace("\\", "/") for f in files}
+    not_packed = [p for p in on_disk if p not in packed_set]
+    assert not not_packed, (
+        "这些文件在仓库里但没进包（package.json 的 files 漏了？）：%s"
+        % ", ".join(not_packed[:8]))
+    return "%d 个文件 / %.0f KB；%d 个受管目录文件全部进包" % (
+        len(files), meta.get("size", 0) / 1024.0, len(on_disk))
 
 
 # ---------------------------------------------------------------- 6 文档引用
@@ -283,8 +351,9 @@ def t_doc_refs():
 def t_size():
     big = []
     for p in [p for p in ROOT.rglob("*") if p.is_file()
-              and ".git" not in p.parts and "node_modules" not in p.parts
+              and not (set(p.parts) & SIZE_SKIP_DIRS)
               and not str(p.relative_to(ROOT)).startswith("tmp_scratch_")
+              and p.suffix.lower() not in SIZE_SKIP_EXT
               and p.suffix != ".png"]:
         n = p.stat().st_size
         if n > MAX_FILE_BYTES:
@@ -295,16 +364,74 @@ def t_size():
 
 
 # ---------------------------------------------------------------- 8 兼容 Python 3.9（README/THIRD_PARTY 的承诺）
+# 3.10+ 才有、但**语法上**能通过 3.9 解析的 API —— ast.parse(feature_version=(3,9)) 看不见它们。
+# 这正是"门禁看着干净、其实没在查"的典型形态：zip(..., strict=True) 在 3.9 上是 TypeError
+# （zip() takes no keyword arguments），而语法检查一路绿灯。
+# 只查**确定**不兼容且容易误用的这几个；不要按 BinOp|BitOr 一律报错（numpy 位或会刷假失败）。
+def _py39_runtime_violations(tree):
+    """扫 3.10+ 运行期 API。返回 [(行号, 说明)]。"""
+    out = []
+    has_future_annotations = False
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom) and node.module == "__future__":
+            if any(a.name == "annotations" for a in node.names):
+                has_future_annotations = True
+    ann_nodes = set()
+    for node in ast.walk(tree):
+        # 收集"注解位置"的节点：只有这里的 X | Y 才是类型联合，函数体里的是 numpy 位或
+        for attr in ("annotation", "returns"):
+            sub = getattr(node, attr, None)
+            if sub is not None:
+                for x in ast.walk(sub):
+                    ann_nodes.add(id(x))
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            fn = node.func
+            name = getattr(fn, "attr", None) or getattr(fn, "id", None)
+            if name == "zip":
+                for kw in node.keywords:
+                    if kw.arg == "strict":
+                        out.append((node.lineno, "zip(..., strict=...) 需要 Python 3.10+"))
+            if name == "bit_count":
+                out.append((node.lineno, "int.bit_count() 需要 Python 3.10+"))
+            if name == "dataclass":
+                for kw in node.keywords:
+                    if kw.arg in ("slots", "kw_only"):
+                        out.append((node.lineno,
+                                    "dataclass(slots=/kw_only=) 需要 Python 3.10+"))
+        elif isinstance(node, ast.Import):
+            for a in node.names:
+                if a.name.split(".")[0] == "tomllib":
+                    out.append((node.lineno, "tomllib 需要 Python 3.11+"))
+        elif isinstance(node, ast.ImportFrom):
+            if (node.module or "").split(".")[0] == "tomllib":
+                out.append((node.lineno, "tomllib 需要 Python 3.11+"))
+        elif isinstance(node, ast.TryStar):
+            out.append((node.lineno, "except* 需要 Python 3.11+"))
+        elif isinstance(node, ast.Match):
+            out.append((node.lineno, "match/case 需要 Python 3.10+"))
+        elif isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+            if not has_future_annotations and id(node) in ann_nodes:
+                out.append((node.lineno,
+                            "X | Y 类型注解需要 3.10+（用 Union[X, Y] 或加 "
+                            "from __future__ import annotations）"))
+    return out
+
+
 def t_py39():
     bad = []
     for p in _py_files():
         src = p.read_text(encoding="utf-8")
         try:
-            ast.parse(src, filename=str(p), feature_version=(3, 9))
+            tree = ast.parse(src, filename=str(p), feature_version=(3, 9))
         except SyntaxError as e:
             bad.append("%s:%s %s" % (p.name, e.lineno, e.msg))
-    assert not bad, "；".join(bad)
-    return "%d 个 .py 通过 3.9 语法解析（运行期兼容仍需真 3.9 实测）" % len(_py_files())
+            continue
+        for lineno, why in _py39_runtime_violations(tree):
+            bad.append("%s:%s %s" % (p.name, lineno, why))
+    assert not bad, "；".join(bad[:6])
+    return ("%d 个 .py 通过 3.9 语法解析 + 3.10+ 运行期 API 扫描"
+            "（真 3.9 运行仍需实测）" % len(_py_files()))
 
 
 
@@ -410,6 +537,8 @@ def t_film_contract():
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(description="仓库级体检（不需要 ffmpeg / 字体 / 网络）")
     ap.add_argument("-v", "--verbose", action="store_true", help="打印每一节的详细证据")
+    ap.add_argument("--strict", action="store_true",
+                    help="SKIP 也算失败（本地缺 node/npm 时想确认\"真的全查了\"就用它）")
     a = ap.parse_args(argv)
     try:
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")
@@ -433,16 +562,27 @@ def main(argv=None) -> int:
     print("ci_check  %s" % ROOT)
     print("-" * 66)
     for name, fn in checks:
-        ok = check(name, fn)
-    for ok, name, detail in _results:
-        print("  %s %-24s %s" % ("PASS" if ok else "FAIL", name, detail if (ok or a.verbose) else ""))
-    fails = [r for r in _results if not r[0]]
+        check(name, fn)
+    for status, name, detail in _results:
+        # PASS 的 detail 只在 -v 下打印（它通常只是"N 个文件全部可编译"）；FAIL/SKIP 一律打印原因
+        print("  %s %-24s %s" % (status, name, detail if (status != "PASS" or a.verbose) else ""))
+    fails = [r for r in _results if r[0] == "FAIL"]
+    skips = [r for r in _results if r[0] == "SKIP"]
+    n_pass = len(_results) - len(fails) - len(skips)
     print("-" * 66)
-    print("PASS %d / FAIL %d" % (len(_results) - len(fails), len(fails)))
+    print("PASS %d / FAIL %d / SKIP %d" % (n_pass, len(fails), len(skips)))
     if fails:
         print("\n失败项：")
-        for ok, name, detail in fails:
+        for _status, name, detail in fails:
+            print("  - %s：%s" % (name, detail))
+    if skips:
+        print("\n跳过项（**不等于通过**）：")
+        for _status, name, detail in skips:
             print("  - %s：%s" % (name, detail))
+    # 退出码口径：默认只把 FAIL 当失败（CI 里 node/npm 一定在，SKIP 不该出现）；
+    # --strict 把 SKIP 也算失败——本地没装 node 的人想确认"真的全查了"就用它。
+    if a.strict and skips:
+        return 1
     return 1 if fails else 0
 
 

package/tools/estimate.py

@@ -65,6 +65,14 @@ MUX_PER_SEC = 0.045                 # 每片长秒（两遍 loudnorm 解码音
 QA_BASE_SEC = (1.0, 3.0)            # 固定开销：联系表 + 参考帧重渲染
 QA_SEC_PER_SEC = (0.12, 0.25)       # 随片长：帧级深检流式解码 + 响度曲线
 UNMEASURED_BAND = 0.30              # 没有实测的阶段（layout/cues/sfx/audio）给 ±30% 的区间，别假装精确
+# v0.8 G11（全片 VMAF/SSIM）：参考帧由场景函数**重渲一遍**再喂 libvmaf，成本跟帧数走、
+# 与 frames 阶段同量级。实测口径差异极大：qavmaf 作者 29 s 片 12.0 s（≈0.40× 片长）；
+# SKILL.md §12 同一部模板片 14.2 s；同机另一轮负载下 28.8 s。这里取 0.40–1.00× 片长
+# （下限=干净机、上限=争 CPU 的长片外推），固定开销单独列 1–2 s。
+# 注：v0.7.2 那套 1.0–1.6× 的系数没有 v0.8 实测支撑，把 29 s 片算成 31–50 s（实际 12–29 s），
+# 预演总量因此系统性偏大近 2 倍——这类"拍脑袋的悲观系数"比低估更糟：排期会按假的数字走。
+VMAF_BASE_SEC = (1.0, 2.0)          # 起渲染进程 + 参考帧管线搭建
+VMAF_SEC_PER_SEC = (0.40, 1.00)     # 每片长秒（参考帧重渲 + libvmaf 逐帧比）
 
 # 校准出处：换成你自己的机器前，请按 SKILL.md §12 重测并回填——这些数字决定预演准不准。
 CALIBRATION = dict(
@@ -101,6 +109,10 @@ STAGE_LABELS = {
     "frames": "逐帧渲染+编码",
     "mux": "合成成片",
     "qa": "质检+抽帧",
+    # v0.8：交付前的三道新门禁单独列（它们的成本不能藏进 qa 里）
+    "preflight": "渲染前预检",
+    "vmaf": "全片VMAF/SSIM",
+    "asr": "ASR回读",
 }
 
 
@@ -209,6 +221,31 @@ def _fmt_span(lo, hi):
     return "%.1f–%.1f s" % (float(lo), float(hi))
 
 
+def _qavmaf_sample_step(vcfg=None):
+    """qavmaf 的抽样步长（sample 模式每 N 帧取 1 帧）。
+
+    优先级与 render.py 的 _qa_vmaf_gate 一致：先读 film.json 的 qa.vmaf.sample_step，
+    没写才用 qavmaf.SAMPLE_STEP。预演不另抄一份常量，否则改一处漏一处；而"用户显式
+    写了 sample_step=20 却按默认 5 预演"会把这道门禁的成本高估 4 倍。
+    读不到 qavmaf 时按 1（=full）保守估——那种环境下 render.py 的 G11 本来也会记
+    skipped（没有模块），多估不会误导排期，少估才会。
+    """
+    try:
+        if isinstance(vcfg, dict) and vcfg.get("sample_step") is not None:
+            return max(1, int(vcfg["sample_step"]))
+    except (TypeError, ValueError):
+        pass
+    try:
+        scripts = str(Path(__file__).resolve().parent.parent /
+                      "skills" / "video-studio" / "scripts")
+        if scripts not in sys.path:
+            sys.path.insert(0, scripts)
+        import qavmaf
+        return max(1, int(qavmaf.SAMPLE_STEP))
+    except Exception:                                       # noqa: BLE001
+        return 1
+
+
 # ============================================================================
 # 估算核心
 # ============================================================================
@@ -305,18 +342,6 @@ def mux_seconds_pair(frames, jobs, total, script):
     return base * 0.75, base * 1.35
 
 
-def mux_seconds(frames, jobs, total, reencode=False):
-    """mux 阶段墙钟。
-
-    默认 `-c:v copy` + 两遍 loudnorm：视频流不解码不重编码，成本 ≈ 起 ffmpeg + 按片长
-    解码音频跑两遍。实测 29 s 片 1.7–1.9 s。
-    reencode_video=true 时才要重编视频，那时才用 x264 速率并按有效加速比摊。
-    """
-    if reencode:
-        return frames / X264_FPS / _speedup(jobs)
-    return MUX_BASE_SEC + MUX_PER_SEC * max(0.0, float(total))
-
-
 def chunk_plan(frames, fps, jobs, explicit):
     """逐字复刻 render.py 的分块规则（改了那边记得同步这里）。
 
@@ -343,7 +368,6 @@ def disk_estimate(frames, total, n_lines, n_cues, crf, music_on):
     factor = 2.0 ** ((17.0 - crf) / 6.0)          # crf 每降 6 体积约翻倍（x264 经验值）
     vlo = max(0.3, VIDEO_MBPS[0] * factor)
     vhi = max(0.3, VIDEO_MBPS[1] * factor)
-    vid_lo = total * vlo * 1e6 / 8.0
     vid_hi = total * vhi * 1e6 / 8.0
     out_lo = total * (vlo + AUDIO_MBPS) * 1e6 / 8.0
     out_hi = total * (vhi + AUDIO_MBPS) * 1e6 / 8.0
@@ -396,16 +420,39 @@ def build_report(script_path, script, args):
         _warn("engine=%r 不认识（只能是 pil / web），按 pil 预演" % engine)
         engine = "pil"
 
+    # v0.8：画幅/帧率可以按片配置（只允许 16:9 横屏 + 下采样输出，见 filmkit.video_plan）。
+    # 预演必须跟着走，否则 720p 片会被按 1080p 估帧数与磁盘。
+    try:
+        import sys as _sys
+        _sys.path.insert(0, str(Path(__file__).resolve().parent.parent /
+                               "skills" / "video-studio" / "scripts"))
+        import filmkit as _FK
+        _vp = _FK.video_plan(script)
+    except ImportError as e:
+        # 只把"缺 filmkit"当降级：那是能用模板常量继续估的环境问题。
+        _warn("装载不了 filmkit（%s），画幅/帧率按 %dx%d@%d 估" % (e, W, H, FPS))
+        _vp = dict(fps=FPS, w=W, h=H, out_w=W, out_h=H,
+                   label="%dx%d" % (W, H))
+    except Exception as e:                                  # noqa: BLE001
+        # video 块写错（非 16:9 / 非法 fps / 上采样）时 render.py 会在 st_layout 直接报错，
+        # 预演却静默按默认值算并打印 ok:true——那等于告诉用户"能渲"，必须显式说清楚。
+        _warn("film.json 的 video 块不合法（%s: %s）：render.py 会拒绝这部片子，"
+              "下面的画幅/帧率只是占位估算" % (type(e).__name__, e))
+        _vp = dict(fps=FPS, w=W, h=H, out_w=W, out_h=H,
+                   label="%dx%d" % (W, H))
     tl, tl_path = read_timeline(args.work)
     if tl is not None:
         total = _num(tl.get("total"))
-        fps = int(_num(tl.get("fps"), FPS)) or FPS
+        fps = int(_num(tl.get("fps"), _vp["fps"])) or _vp["fps"]
         frames = int(_num(tl.get("frames"), round(total * fps)))
         source = "timeline"
         source_note = "真实帧数：%s" % tl_path
     else:
         total, _scenes = estimate_timeline(script)
-        fps = FPS
+        # v0.8：没有 timeline.json 时也必须用 film.json 的 video.fps —— 定死 30 会让
+        # 24/25/50/60 fps 的片子帧数、磁盘、分块全部按 30 fps 算（24 fps 高估 25%，
+        # 60 fps 低估一半），而 render.py 的 build_timeline(fps=vp["fps"]) 用的是真实值。
+        fps = int(_vp["fps"])
         frames = int(round(total * fps))
         source = "script_estimate"
         source_note = ("粗估（等效字数 ÷ %.1f 字/秒 + lead/tail + hold；没有 %s）"
@@ -463,6 +510,51 @@ def build_report(script_path, script, args):
     mux_lo, mux_hi = mux_seconds_pair(frames, jobs_eff, total, script)
     qa_lo = max(0.5, QA_BASE_SEC[0] + total * QA_SEC_PER_SEC[0])
     qa_hi = max(qa_lo, QA_BASE_SEC[1] + total * QA_SEC_PER_SEC[1])
+    # v0.8 的三个新门禁：预检（固定小开销）、全片 VMAF/SSIM、ASR 回读。
+    # 实测口径（29.0 s 模板片）：preflight 0.4 s；VMAF full 12–29 s（0.40–1.00× 片长，
+    # 参考帧重渲与 libvmaf 都在里面，见 VMAF_* 常量注释）；ASR small ≈ 6–10 s。
+    # 这三项全在**交付前**跑，不写进预演就等于"预演说 40 s、实际 90 s"——所以单独列 stage。
+    qcfg = script.get("qa") or {}
+    if not isinstance(qcfg, dict):
+        qcfg = {}
+    # render.py 的 _qa_vmaf_gate / _qa_asr_gate 都用 isinstance 兜住了非 dict 的配置块；
+    # 预演以前直接 .get()，于是 "qa": {"vmaf": "off"} 这种（用户以为写了个开关）
+    # 会在 --json 下甩 AttributeError traceback、退出码 1——比 render 还不宽容。
+    vcfg = qcfg.get("vmaf")
+    if not isinstance(vcfg, dict):
+        if vcfg is not None:
+            _warn("qa.vmaf 不是对象（收到 %r）：按默认 full 预演（render.py 会忽略这个值）"
+                  % (vcfg,))
+        vcfg = {}
+    vmaf_mode = str(vcfg.get("mode") or "full").lower()
+    vmaf_on = vmaf_mode != "off" and engine == "pil"      # web 路线没有可重渲参考帧
+    # sample 模式（qavmaf 每 SAMPLE_STEP 帧取 1 帧）只渲/比 1/step 的帧，固定开销不变。
+    # 预演以前不看 mode，于是 --vmaf sample 的真实成本被按全片算：29 s 片实测 sample
+    # 2.95 s vs full 12.0 s，而预演两边都给同一个数（片长越长错得越多）。
+    vmaf_step = 1
+    if vmaf_mode == "sample":
+        vmaf_step = _qavmaf_sample_step(vcfg)
+    # sample 只压缩"逐帧"那一半，固定开销照付。
+    vmaf_lo = (VMAF_BASE_SEC[0] + total * VMAF_SEC_PER_SEC[0] / vmaf_step) if vmaf_on else 0.0
+    vmaf_hi = (VMAF_BASE_SEC[1] + total * VMAF_SEC_PER_SEC[1] / vmaf_step) if vmaf_on else 0.0
+    acfg = qcfg.get("asr")
+    if not isinstance(acfg, dict):
+        if acfg is not None:
+            _warn("qa.asr 不是对象（收到 %r）：按默认（开）预演" % (acfg,))
+        acfg = {}
+    asr_on = bool(acfg.get("enabled", True)) != False    # noqa: E712  默认开
+    asr_lo = (total * 0.18 + 3.5) if asr_on else 0.0
+    asr_hi = (total * 0.35 + 6.5) if asr_on else 0.0
+    pre_lo, pre_hi = (0.3, 0.8)
+    if not vmaf_on:
+        vmaf_note = "本次不跑（--vmaf off 或 engine=web）"
+    elif vmaf_mode == "sample":
+        vmaf_note = ("sample 模式每 %d 帧取 1 帧：逐帧成本只算 1/%d，参考帧管线固定开销照付。"
+                     "同机负载不同实测能差近 2×（SKILL.md §12：14.2 s / 另一轮 28.8 s）"
+                     % (vmaf_step, vmaf_step))
+    else:
+        vmaf_note = ("全片逐帧比较（参考帧=场景函数重渲染，不是成片抽帧）。同机负载不同"
+                     "实测能差近 2×（SKILL.md §12：14.2 s / 另一轮 28.8 s）")
 
     stages = [
         dict(stage="tts", lo=tts_lo, hi=tts_hi, measured=True,
@@ -496,8 +588,15 @@ def build_report(script_path, script, args):
         dict(stage="mux", lo=mux_lo, hi=mux_hi, measured=True,
              note=("-c:v copy + 两遍 loudnorm（实测 29 s 片 1.7–1.9 s，与帧数无关）；"
                    "reencode_video=true 才走 x264 %.0f fps" % X264_FPS)),
+        dict(stage="preflight", lo=pre_lo, hi=pre_hi, measured=True,
+             note="渲染前资源预检（缺字形/坏音频/缺字体；实测 0.4 s，渲一帧之前就失败）"),
         dict(stage="qa", lo=qa_lo, hi=qa_hi, measured=True,
              note=("联系表 + 锐度参考帧重渲染 + 帧级深检（实测 29 s 片 6.2–6.8 s，不是 1 s）")),
+        dict(stage="vmaf", lo=vmaf_lo, hi=vmaf_hi, measured=False, note=vmaf_note),
+        dict(stage="asr", lo=asr_lo, hi=asr_hi, measured=False,
+             note=("ASR 回读（faster-whisper small / CPU int8，RTF≈0.17 + 加载 2–3 s；"
+                   "实测 29 s 片 6–10 s）"
+                   if asr_on else "本次不跑（qa.asr.enabled=false）")),
     ]
     total_lo = sum(s["lo"] for s in stages)
     total_hi = sum(s["hi"] for s in stages)
@@ -508,9 +607,13 @@ def build_report(script_path, script, args):
     disk = disk_estimate(frames, total, n, n_cues, crf, music_on)
 
     # ---- 分块（render.py 规则）----
+    # 这里必须传**用户请求的 jobs**，不能传 jobs_eff：render.py 的 chunk_frames 公式用的是
+    # --jobs 原值（它不按核数封顶），而 jobs_eff 是给"加速比模型"封顶到 CORES 的。
+    # 传错的话 --jobs 16（24 线程机器上合法）会算出 chunk=120/8 段，render 实际是
+    # chunk=60/15 段——预演与实现"逐字一致"的承诺当场失效。
     explicit = int(_num(script.get("chunk_frames"), 0))
-    chunk, nseg = chunk_plan(frames, fps, jobs_eff, explicit)
-    chunk = dict(jobs=jobs_eff, jobs_requested=jobs_req, chunk_frames=chunk,
+    chunk, nseg = chunk_plan(frames, fps, jobs_req, explicit)
+    chunk = dict(jobs=jobs_req, jobs_requested=jobs_req, chunk_frames=chunk,
                  segments=nseg, explicit=bool(explicit),
                  rule="chunk = chunk_frames 或 round(frames/jobs/fps/4)*4*fps，"
                       "再按 fps 取整、最小 2×fps")
@@ -521,7 +624,10 @@ def build_report(script_path, script, args):
         "source": source,
         "source_note": source_note,
         "video": {"title": script.get("title"),
-                  "width": W, "height": H, "fps": fps, "frames": frames,
+                  # v0.8：内部构图恒为 1080p，交付尺寸可以更小（_vp 从 film.json 的 video 块来）
+                  "width": _vp["w"], "height": _vp["h"],
+                  "out_width": _vp["out_w"], "out_height": _vp["out_h"],
+                  "fps": fps, "frames": frames,
                   "duration_s": round(total, 3), "engine": engine,
                   "crf": crf, "preset": preset, "bpm": mus.get("bpm", script.get("bpm")),
                   "style": script.get("style", None)},
@@ -547,7 +653,8 @@ def build_report(script_path, script, args):
                        "share": round(share, 3),
                        "advice": bottleneck_advice(worst["stage"], engine, jobs_eff)},
         "assumptions": [
-            "分辨率 1920x1080@%d 由 filmkit.W/H/FPS 写死，film.json 改不了" % FPS,
+            "内部构图恒为 1920x1080；交付尺寸/帧率可写 film.json 的 video 块"
+            "（v0.8，只允许 16:9 横屏且只能下采样；本次按 %d fps 估）" % fps,
             "lead=%.2f / tail=%.2f / min_dur=%.1f（v0.5 body 基准；剧本写了就以剧本为准）"
             % (DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR),
             "tts 耗时按 %d 句 ÷ workers × %.1f–%.1f s（每句每 worker）；实际受网络波动影响"
@@ -556,6 +663,10 @@ def build_report(script_path, script, args):
             % (PARALLEL_EFF, CORES),
             "mux 默认 -c:v copy，只跟片长有关；reencode_video=true 才按帧数重编",
             "layout/cues/audio/sfx 给 ±%d%% 经验区间（无单阶段实测）" % int(UNMEASURED_BAND * 100),
+            "v0.8 新增门禁口径：preflight 0.4 s 固定；vmaf ≈ %.2f–%.2f× 片长 + %.1f–%.1f s"
+            "（参考帧重渲染 + libvmaf；同机负载不同实测差近 2×）；asr ≈ 0.18–0.35× 片长 + "
+            "3.5–6.5 s（faster-whisper small / CPU int8）"
+            % (VMAF_SEC_PER_SEC[0], VMAF_SEC_PER_SEC[1], VMAF_BASE_SEC[0], VMAF_BASE_SEC[1]),
             "基准来源见 calibration 字段（机型/日期/样本）；换机请重测后回填顶部常量",
         ],
         "baseline": BASELINE_NOTE,