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

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

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""gates.py — 门禁账本 / 机读交付报告 / 人工签核（v0.6.0）。
+"""gates.py — 门禁账本 / 机读交付报告 / 人工签核。
 
 解决三件事（都是"文档承诺了、代码没做"）：
 
@@ -117,7 +117,7 @@ class GateLedger:
         self.work = str(work or "work")
         self.items = []
         self.t0 = time.time()
-        # v0.8：run_id 是"这一版"的标签（--run-id）。没给就按时间戳生成，
+        # run_id 是"这一版"的标签（--run-id）。没给就按时间戳生成，
         # 保证每次运行在 work/runs/<runId>/ 下都有独立记录，而不是互相覆盖。
         self.run_id = str(run_id or "").strip() or time.strftime("r%Y%m%d-%H%M%S")
         self.script = script or {}
@@ -194,7 +194,7 @@ class GateLedger:
         return d
 
     def input_fingerprints(self):
-        """输入指纹快照（v0.8）：剧本 / scenes / 词级 / 本脚本。
+        """输入指纹快照：剧本 / scenes / 词级 / 本脚本。
 
         为什么要单独记：contentHash 是"一个 16 位 hex"，能判"变了没"，但**说不出
         变了哪个**。批量出片时最常见的问题是"这条用的还是上一版的词级时间戳"，
@@ -219,7 +219,7 @@ class GateLedger:
 
 
 def archive_run(work, ledger, artifacts=None, report_path=None):
-    """把"这一版"的账本快照归档到 work/runs/<runId>/（v0.8）。
+    """把"这一版"的账本快照归档到 work/runs/<runId>/。
 
     只归档**小文件**（gates.json / QC-REPORT.md / run.json）。视频/音频/分块体积大，
     就地保留即可——这里要解决的是"跑了几版之后，谁都说不清上一版的门禁结论是什么"，

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

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""grammar.py — 场景语法：这段内容该长成什么构图（v0.9 新增）。
+"""grammar.py — 场景语法：这段内容该长成什么构图。
 
 为什么单独一个模块
 ------------------
@@ -7,8 +7,8 @@
 （scene type: hero/list/stat/compare/...）是两个**正交**维度：
   - kind 决定旁白声线、语气、配乐能量（voicekit / scorekit 读它）；
   - scene type 决定这段画面长什么样（scenes.py 的 _DRAWERS 读它）。
-v0.8 及以前两者被混成一个 kind，而 scenes.py 只有 hook/body/outro 三个绘制器，
-quote/emphasis/calm 全部回落到 body —— 这就是"8 套风格只是换皮肤"的根因。
+两者被混成一个 kind 时，scenes.py 只有 hook/body/outro 三个绘制器，
+quote/emphasis/calm 全部回落到 body —— 画面因此只有三种骨架，换配色也换不掉"每屏一个样"。
 
 把"内容 -> 构图"的选择逻辑独立出来，有三个好处：
   1. 纯函数、只依赖标准库：可以单测，不需要 PIL / TTS / 渲染；
@@ -77,7 +77,7 @@ DOWNGRADE = {
 MAX_REPEAT = 2
 
 # ============================================================================
-# 二、确定性哈希（与 stylekit._digest 同口径：sha1 前 8 位）
+# 二、确定性哈希（sha1 前 8 位；禁 hash()：str hash 每次进程带随机盐）
 # ============================================================================
 
 
@@ -136,7 +136,7 @@ def _narrative_of(line):
     """只取"叙述文字"（标题/正文/副标），**不含 items**。
 
     为什么关键词判断必须排除 items：条目是"要点的载荷"，不是"这段在讲什么"。
-    实测反例：模板片第 3 段正文讲"画质三件事"，条目里写的是
+    实测反例：夹具片第 3 段正文讲"画质三件事"，条目里写的是
     "rawvideo -> libx264 CRF17"，其中 "->" 命中了顺序词表，
     于是整段被误判成"流程轴"——画面上出现一条横轴连着四个不相干的要点。
     条目里的箭头/破折号是排版符号，不是叙事顺序。
@@ -235,7 +235,7 @@ def score_types(line, idx, total, dur, chapter, prev_chapter, prev_types):
         add("outro", 5.0, "末段/收尾")
     # 章节卡是"纯标题卡"：章节变了 + 没有条目 + 标题短 + 段也短，才配得上整屏只有一个编号。
     # 三个条件都是实测加上的：
-    #   · 有 items 的段用章节卡会把要点吃掉（模板片 5 条要点的 body 曾被选成 chapter）；
+    #   · 有 items 的段用章节卡会把要点吃掉（夹具片 5 条要点的 body 曾被选成 chapter）；
     #   · 带数字/引语的段有更具体的构图，章节卡会把信息量砍掉；
     #   · 设计稿规定章节卡 ≤3.4s，长段做章节卡等于"整屏只有一个编号停 6 秒"，观众会走。
     if (chapter and chapter != prev_chapter and n_items == 0
@@ -476,7 +476,7 @@ def plan_scenes(scenes, script=None, plan=None):
       ① plan["chapter_layout"] 显式指定（按章名查，查不到用 layout_default）；
       ② plan["layout_cycle"]（≥2 种版式且没有显式 chapter_layout）：按章节首次
          出现的顺序循环取位，**同一章内版式固定**——防止"全片一张版式"；
-      ③ 都没有：layout_default（与 v1.0.1 完全一致）。
+      ③ 都没有：layout_default。
 
     **没有 chapter 的剧本**：按"每段自成一章"处理（轮换照常推进）。
     为什么不把空 chapter 当成"全片同一章"：那样 layout_cycle 在常见的不写 chapter
@@ -492,7 +492,7 @@ def plan_scenes(scenes, script=None, plan=None):
     prev_variant = {}
     chapter_layout = plan.get("chapter_layout") if isinstance(plan.get("chapter_layout"), dict) else {}
     default_layout = plan.get("layout_default") or "left-stack"
-    # ---- 片内版式轮换（v1.0.2）：design_to_plan 会派生 layout_cycle ----
+    # ---- 片内版式轮换：design_to_plan 会派生 layout_cycle ----
     # 为什么需要：没有它时一章只能用一种版式（layout_default），8 段片子 8 屏同骨架 ——
     # 正好是用户原则 5 说的"同一视频内部大面积/长时间重复"。
     # 生效条件（两条都不满足就与过去逐字节一致，金帧/既有自检不漂）：
@@ -568,9 +568,9 @@ def describe(storyboard):
 def _cli(argv=None):
     """自测入口：python grammar.py [film.json] —— 只读，不渲染。
 
-    v1.0.2：加 argparse（在此之前 `--help` 会被当成 film.json 路径，FileNotFoundError，
+    用 argparse 解析（否则 `--help` 会被当成 film.json 路径，FileNotFoundError，
     与仓库里其它 17 个脚本的 CLI 约定不一致）。不传 film.json 时仍打印用法与 10 类构图，
-    退出码 0（保持 v0.9 的行为，便于老 CI 探活）。
+    退出码 0（便于 CI 探活）。
     """
     import argparse
     import json

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

@@ -1,8 +1,7 @@
 # -*- coding: utf-8 -*-
 """musicgen.py — P2 参数化配乐编排器（纯 numpy + stdlib，确定性、可单独 import）。
 
-D3 目标：删掉 scorekit.MUSIC_STYLES 的 9 套硬编码风格表后，配乐不再由 style id
-决定，而是由一组可采样参数现场编排：
+配乐不由 style id 决定（本仓库没有曲风表），而是由一组可采样参数现场编排：
 
     render(duration, *, bpm=96.0, key='Dm', scale='minor', mood='steady',
            seed=0, sections=None, progressions=None, motif=None,
@@ -1017,7 +1016,7 @@ def _build_plan(duration, bpm, key, scale, mood, seed, sections, progressions,
                        dtype=np.float64)
     # 一小节的能量取"小节内最响的时刻"，窗口 **±0.20 小节**（约半小节）。
     #
-    # 历史：① 只取中心点 -> 段落与小节网格错位时 climax 永远触发不了；
+    # 取舍：① 只取中心点 -> 段落与小节网格错位时 climax 永远触发不了；
     #       ② 窗口放宽到 ±0.42 几乎盖满整小节 -> 收尾小节被前一节的高潮污染
     #          （实测 8 s / 96 BPM 的 outro 被判成 climax）。
     # ±0.20 是两头都照顾的取值：段切在中心附近偏差 ≤0.2 小节能被捕获，
@@ -1284,7 +1283,7 @@ def _arrange(plan):
     # 都在 C5 以上；250–520 Hz 这个"有厚度的区间"没有持续音。
     # 解法不是再开一个合成器，而是让 pad 多叠一层中音区和弦（+12 半音后限幅），
     # 用同一套包络与 pan，成本近零、也不会引入新的调性信息。
-    # 实测各层频段分布（12 s，改造前）：pad 全在 250–2000 Hz（120–250 Hz 只有 0.7%）、
+    # 实测各层频段分布（12 s）：pad 全在 250–2000 Hz（120–250 Hz 只有 0.7%）、
     # bass 96% 在 20–120 Hz、arp/lead 90%+ 在 500 Hz 以上 —— 所以 120–250 Hz 是挖空的。
     # 补法：把和弦**根音再降一个八度**叠一层（MIDI 40–55，即 82–196 Hz 的上半段），
     # 它的基频正好落在 120–250 Hz；用 pad 音色与包络，音量压到 pad 的 0.42 倍，

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

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""preflight.py — 渲染前资源闸门（v0.8.0）。
+"""preflight.py — 渲染前资源闸门。
 
 为什么要有它：缺字形（✓ / emoji / 生僻字）和坏 TTS 音频都是「渲染完才报」的问题——
 filmkit.glyph_missing_chars() 检测本身是准的（正常中文 []，✓/↵/emoji 检出），
@@ -12,7 +12,7 @@ preflight 不新写检测器，只把现成检测前移，并把结论整理成
   2 glyphs      所有上屏文本逐字过 filmkit.glyph_missing_chars；
                 字段：text / sub / big / kicker / lead / note / title / end_text /
                 chapter / items[].text（含 timeline.scenes 里的同名字段）
-                按模板实际绘制权重检测：big/kicker=bold、lead=light、sub=reg+light、
+                按夹具实际绘制权重检测：big/kicker=bold、lead=light、sub=reg+light、
                 items=reg、title/chapter=reg、text=bold+reg
   3 tts         work/tts/*.mp3 若存在，必须能被 ffprobe 解析出音频流；
                 文件名要能对上行 id，时长要与台词长度相符（过短=截断/坏缓存）
@@ -40,7 +40,7 @@ ffmpeg/ffprobe 探测口径与 filmkit 一致：FILMKIT_FFMPEG 优先，找不
 """
 from __future__ import annotations
 
-__version__ = "0.8.0"
+__version__ = "1.0.4"
 
 import argparse
 import json
@@ -70,7 +70,7 @@ FIELD_WEIGHTS = {
     "big": ("bold",),
     "kicker": ("bold",),
     "lead": ("light",),
-    "note": ("bold",),              # 模板未用；按 QA 的 check_glyphs 口径（bold）兜底
+    "note": ("bold",),              # 夹具未用；按 QA 的 check_glyphs 口径（bold）兜底
     "title": ("reg", "bold"),       # 右下角 brand 画 reg；hook 缺 big 时画 bold
     "end_text": ("bold",),
     "chapter": ("reg",),
@@ -635,7 +635,7 @@ def _check_web_page(script, engine, errors, warnings, checks):
     entry = _web_entry(script)
     if not os.path.isfile(entry):
         tpl = _skill_web_template()
-        # v1.0.2 wording: assets/web is a demo page for smoke-testing the web path, not a template.
+        # assets/web is a demo page for smoke-testing the web path, not a template.
         # This skill ships no templates: web-path films need the user own page (PIL path is zero-copy).
         if tpl:
             hint = ("（web 引擎需要**你自己的页面**：把技能自带的**示例页**拷到 %s 只能跑通链路，"

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

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""previewkit.py — 离线方案预览（v1.0）：先看 3 个方案，再出片。
+"""previewkit.py — 离线方案预览：先看 3 个方案，再出片。
 
 解决什么问题
 -------------
@@ -16,11 +16,11 @@
 编码函数）。产出的 PNG 与真实成片的差别只在"哪一帧是哪一句"，不在"这一帧画成什么样"——
 后者正是方案预览要回答的问题。
 
-12 秒样音（v1.1）
+12 秒样音
 -----------------
 ``render_audio_preview`` 是本文件唯一会"出声"的地方：按设计里的 bpm/key/scale/mood/seed
 生成 12 秒配乐，回答"这一版的情绪对不对"。优先走 musicgen（参数化作曲器）；它没就绪时
-退回 scorekit 的 legacy 路径（v1.0.1 起 scorekit 没有风格表，那条路只保证"还能出声"，
+退回 scorekit 的 legacy 路径（scorekit 没有风格表，那条路只保证"还能出声"，
 音乐固定为 Dm/120，不能当作方案预览）。两条都不在就返回 ok=False。**样音失败绝不
 打断提案**：提案是决策环节，不该因为配乐引擎没装好就整条断掉。
 
@@ -56,7 +56,7 @@ times 的语义：**全片绝对秒**（0 <= t <= total）。也接受 ``[scene_
 """
 from __future__ import annotations
 
-__version__ = "1.1.0"
+__version__ = "1.0.4"
 
 import argparse
 import hashlib
@@ -75,11 +75,10 @@ ASSETS = os.path.normpath(os.path.join(HERE, os.pardir, "assets"))
 def _default_scenes():
     """默认 scenes.py：**先看同目录**，再回落到 <skill>/assets/。
 
-    为什么不能只写死 assets/：SKILL.md 教用户把 scripts/*.py 拷到工作目录
-    （myfilm/ 下有 film.json、scenes.py、各脚本），此时本模块位于 myfilm/，
-    而 <myfilm>/../assets/scenes.py 根本不存在 —— 实测报
-    "scenes.py 不存在：<myfilm>/../assets/scenes.py"，提案直接跑不起来。
-    仓库内部使用（脚本仍在 <skill>/scripts/）时，同目录没有 scenes.py，回落到 assets/。
+    为什么不能只写死 assets/：用户可能把自己的 scenes.py 放在**剧本同目录**（myfilm/ 下只有
+    film.json 与 scenes.py），此时按相对路径推出来的 <myfilm>/../assets/scenes.py 根本不存在——
+    实测报 "scenes.py 不存在：<myfilm>/../assets/scenes.py"，提案直接跑不起来。
+    脚本仍在 <skill>/scripts/ 时，同目录通常没有 scenes.py，于是回落到 assets/。
     """
     for cand in (os.path.join(HERE, "scenes.py"),
                  os.path.join(ASSETS, "scenes.py")):
@@ -480,7 +479,7 @@ def _musicgen():
 def _scorekit():
     """惰性 import scorekit：它拉起 numpy，import 期就要几百毫秒，默认不该付这笔钱。
 
-    v1.0.1 起 scorekit 的 9 套配乐风格表已删除（零模板），它只剩 legacy 逐样本兼容
+    scorekit 的配乐风格表已经没有了（零模板），它只剩 legacy 逐样本兼容
     路径（固定 Dm/120、无 style/mood 参数）。这里保留它只是"兜底还能出声"：
     musicgen 没就绪时不至于整条样音链路断掉。
     """
@@ -522,7 +521,7 @@ def _render_musicgen(params, path, secs):
 
 
 def _render_scorekit(params, path, secs):
-    """兜底：scorekit 的 legacy 路径（v1.0.1 起没有 style/mood 参数，别传）。"""
+    """兜底：scorekit 的 legacy 路径（没有 style/mood 参数，别传）。"""
     K = _scorekit()
     samples, report = K.render(secs, bpm=params["bpm"], key=params["key"],
                                seed=params["seed"])
@@ -606,7 +605,7 @@ def render_audio_preview(design, out_dir, seconds=AUDIO_PREVIEW_SECONDS):
     """生成一个候选的 12 秒样音（48 kHz 立体声），返回结果 dict，**绝不抛异常**。
 
     为什么优先 musicgen：它直接吃设计里的 bpm/key/scale/mood/seed，12 秒一次合成；
-    没就绪就退回 scorekit 的 legacy 路径（v1.0.1 起它没有风格表，出的是固定 Dm/120），
+    没就绪就退回 scorekit 的 legacy 路径（它没有风格表，出的是固定 Dm/120），
     engine 字段会写明是谁出的，调用方据此知道这条样音能不能代表方案。
     两条都不可用时返回 {"ok": False, "reason": ...}——提案是决策环节，配乐引擎缺位不该
     让整条提案断掉，但也不许假装成功（ok=True 却指着一个不存在的文件比报错更糟）。

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

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""propose.py — 提案器（v1.0）：先出 N 个方案，用户确认后才允许出片。
+"""propose.py — 提案器：先出 N 个方案，用户确认后才允许出片。
 
 为什么单独一个入口而不是塞进 render.py
 --------------------------------------
@@ -15,7 +15,7 @@ render.py 的 13 个 stage 是一条"内容 → 成片"的生产线；提案是*
     revise   ->  rev2（不覆盖 rev1，带 feedback 原文）
     diff     ->  两个 rev 的设计向量差异
 
-每次都不一样：同 brief 不传 seed 会得到**不同**的候选（v1.0.1 起，满足"每条视频都不同"）；
+每次都不一样：同 brief 不传 seed 会得到**不同**的候选（满足"每条视频都不同"）；
 可复现：显式 --seed 时同 seed 得到同一组候选（designkit 内部 sha1 派生，禁 random）。
 离线：预览只走合成时间轴（previewkit），**不联网、不合成旁白**；--with-audio 才多生成
       12 秒样音（仍全程离线，musicgen/scorekit 任选其一）。
@@ -89,10 +89,10 @@ def _sha(obj, n=16):
 
 
 # ============================================================================
-# 片间去重：设计台账（v1.0.2）
+# 片间去重：设计台账
 # ============================================================================
 #
-# 用户原则 5：**不同视频的整体风格不能大面积重复**。v1.0.1 的"每条视频都不同"
+# 用户原则 5：**不同视频的整体风格不能大面积重复**。只靠采样 nonce 的"每条视频都不同"
 # 靠的是采样 nonce —— 同一 brief 两次采样确实不同，但**没有记住已经交付过什么**：
 # 连续拍同题材的三条片，仍有概率撞到相近的配色/版式组合（设计空间大，但不是保证）。
 # 台账把"最近交付过的设计"记在用户级目录里，提案时主动避开它们：
@@ -233,9 +233,9 @@ _NEGATIVE_WORDS = ("不要", "不想要", "别用", "别", "避开", "排除", "
 
 
 
-# ---------------------------------------------------------------- 时长解析（v1.0.2）
-# brief 里最常见的硬要求之一就是时长（"做个 2 分钟的""60 秒短视频"）。v1.0.1 之前
-# 它**完全不生效**：_brief_of 只填 topic/must_have/avoid，duration_target 恒为 None，
+# ---------------------------------------------------------------- 时长解析
+# brief 里最常见的硬要求之一就是时长（"做个 2 分钟的""60 秒短视频"）。不解析它
+# 就**完全不生效**：_brief_of 只填 topic/must_have/avoid，duration_target 恒为 None，
 # 连 design.structure.target_sec 都不会有值。用户以为要求被接住了，成片却按台词长度来。
 # 这里把它解析出来：① 影响候选的段落数（designkit 按目标时长决定 segments）；
 # ② 渲染时对账"目标 vs 实测"，差超过 15% 当场告警——**不截断旁白**，只把事实说清。
@@ -304,7 +304,7 @@ def parse_duration(text):
 def _brief_of(text, script):
     """把用户一句话变成 brief dict。剧本的标题是隐含 topic（避免空 brief）。
 
-    v1.0.1 修：以前这里把整句话塞进 topic 就完事，**must_have/avoid 恒为空数组**。
+    以前这里把整句话塞进 topic 就完事，**must_have/avoid 恒为空数组**。
     后果是 `--brief "深蓝配色的科技解说"` 里的"深蓝"完全不生效 —— 实测采出来的是
     h087 / h316（橙 / 紫），用户看到的需求与结果无关。designkit 明明有一张
     32 个词的关键词表（_constraint_words），但没人喂给它。
@@ -336,7 +336,7 @@ def _brief_of(text, script):
                 continue                       # 认不出来的短句留给 topic，由上层提示
             neg = any(w in seg for w in _NEGATIVE_WORDS)
             (avoid if neg else must).append(seg)
-    # v1.0.2：时长要求也要接住（以前恒为 None，用户写了「2 分钟」等于没写）。
+    # 时长要求也要接住（漏了就是恒为 None，用户写了「2 分钟」等于没写）。
     dt = parse_duration(text)
     return {"topic": topic, "duration_target": dt,
             "must_have": must, "avoid": avoid}
@@ -401,9 +401,9 @@ def make_proposal(brief_text, script, work, n=3, seed=None, n_frames=4, json_out
     parent = prev.get("rev") if prev else None
     feedback = str(brief_text or "").strip() if rev > 1 else ""
 
-    # v1.0 起唯一的出方案方式是**按 brief 现场采样**：没有预设、没有模板可套。
+    # 唯一的出方案方式是**按 brief 现场采样**：没有预设、没有模板可套。
     #
-    # v1.0.2 片间去重：读台账里最近交付过的设计，若这批候选与其中某一份"太像"
+    # 片间去重：读台账里最近交付过的设计，若这批候选与其中某一份"太像"
     # （离散维度差距 < LEDGER_MIN_GAP），换 nonce 重采一次，最多试 LEDGER_RETRIES 轮，
     # 取"最后一批"里与历史距离最大的那组。重试仍近就**明说**（不静默放过）。
     recent = [] if no_ledger else ledger_load()

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
@@ -83,7 +83,7 @@ FLICKER_ISO = 1.5       # 孤立性比值：当前帧异常度 >= 1.5 x 前后
 FLICKER_RETURN_RATIO = 1.6
 # 符号一致度下限：块内像素"同向"变化的比例。真闪白/闪黑整块同向（0.75–1.0）；
 # 文字入场 / 母题动画 / 镜头缓推是有增有减的纹理变化（实测 0.42）。
-# 低于此值不判 error（降级 warning 供人复核）——v1.0.2 修掉零拷贝首片的 G9 误杀。
+# 低于此值不判 error（降级 warning 供人复核）——否则零拷贝首片会被 G9 误杀。
 FLICKER_AGREE_MIN = 0.60
 # 与已登记视觉事件（闪白/震屏/冲击环）重合多久内视为"设计好的重击"，不计 error
 FLICKER_EXPLAIN_WIN = 0.2
@@ -102,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）。
@@ -376,9 +375,9 @@ def _block_max(diff, block, signed=None) -> tuple:
     中值是复核线索：整块一起变亮（真单帧事件）时中值也高；只有小块元素在动时
     均值被少数像素拉高、中值仍接近 0（见 references/frame-qa.md 的 16.933 s 案例）。
 
-    v1.0.2 加符号一致度（signed 传带符号的二阶差分时才算）：整块**同向**变亮/变暗
+    符号一致度（signed 传带符号的二阶差分时才算）：整块**同向**变亮/变暗
     = 真闪白/闪黑；文字逐字入场、母题动画、镜头缓推产生的只是**有增有减**的纹理变化，
-    符号一致度低。实测（v1.0.2 零拷贝首片）：t=5.867s 被误报的块 score 51.5 / median 44.5，
+    符号一致度低。实测（零拷贝首片）：t=5.867s 被误报的块 score 51.5 / median 44.5，
     但符号一致度只有 0.42；同一位置人为注入 +50 灰闪白后一致度 0.75。
     """
     h, w = diff.shape
@@ -660,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)
@@ -676,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。
@@ -715,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"}
@@ -728,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（不静默）。
     """
@@ -872,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=[]）。
@@ -983,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 内都没动过，人眼就是一张定格。
@@ -1039,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
 
@@ -1062,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
@@ -1107,10 +1106,10 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
         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))
-        # v1.0.2：符号一致度 = 块内像素是否**同向**变亮/变暗。
+        # 符号一致度 = 块内像素是否**同向**变亮/变暗。
         # 真闪白/闪黑整块同向（实测 0.75–1.0）；文字逐字入场、母题动画、镜头缓推
-        # 是"有增有减"的纹理变化（实测 0.42）。后者以前会被判成闪烁，让新用户首片
-        # 就 fail 在 G9（零拷贝自测实测：t=5.867s 标题逐字入场被误判）。
+        # 是"有增有减"的纹理变化（实测 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:
@@ -1182,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)
@@ -1431,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)
@@ -1889,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))
@@ -2020,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 视觉事件）")