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

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

@@ -782,6 +782,33 @@ def tv_filter(x, kind: str, freq, q: float = 0.7071, gain_db: float = 0.0,
     return y
 
 
+def _resonator_ir(f: float, t60: float, amp: float, n_max: int,
+                  sr: int = SR) -> np.ndarray:
+    """模态谐振器的解析冲激响应 h[n] = amp · r^n · sin(ωn)，长度 ≤ n_max。
+
+    为什么不复用通用的 _iir_ir()：无 scipy 时 resonator 也要走 FFT 卷积，而金属/
+    玻璃模态的 t60 可达 5~7 s（见 MATERIALS 的 eta 量级），-80 dB 衰减长度约
+    1.33·t60·sr ≈ 40 万采样。旧的 _iir_ir(cap=20000) 在 0.42 s 处把 IR 砍成 0：
+    截断点在 -25 dB 上直接跳变，听感是长尾里多一下“咔”，且与 scipy 路径的
+    产物长度/尾音全不同（references/sfx-design.md §12 要求静态滤波与 scipy
+    相对误差 ≤ 2e-4，实测旧兜底最差 -8 dB）。这个二阶系统的 IR 有闭式解，
+    一次向量化算完，比逐样本 Python 递推快两三个数量级。
+    长度取 min(n_max, -80 dB 衰减长度)：输出只取前 n_max 个采样，h 超过 n_max
+    的部分不可能影响这些采样，所以这个截断是精确的、不是近似。
+    """
+    n_max = int(max(0, n_max))
+    if n_max == 0:
+        return np.zeros(0)
+    a1 = math.exp(-LN1000 / (max(float(t60), 1e-5) * float(sr)))
+    w = 2.0 * np.pi * float(f) / float(sr)
+    # 借 _ir_len() 的极点半径估计（它已处理不衰减/数值退化），保证与旧路径同口径
+    a = np.array([1.0, -2.0 * a1 * math.cos(w), a1 * a1])
+    b = np.array([0.0, float(amp) * a1 * math.sin(w)])
+    L = int(_ir_len(b, a, cap=n_max))
+    k = np.arange(L, dtype=float)
+    return float(amp) * np.power(a1, k) * np.sin(w * k)
+
+
 def resonator(excitation, f: float, t60: float, amp: float = 1.0,
               sr: int = SR) -> np.ndarray:
     """单个模态：二阶谐振器，冲激响应为 amp · r^n · sin(ωn)（指数衰减的正弦）。"""
@@ -794,7 +821,7 @@ def resonator(excitation, f: float, t60: float, amp: float = 1.0,
     a = np.array([1.0, -2.0 * a1 * math.cos(w), a1 * a1])
     if _sig is not None:
         return _sig.lfilter(b, a, x, axis=0)
-    return _fftconv(x, _iir_ir(b, a, _ir_len(b, a, cap=20000)))[: len(x)]
+    return _fftconv(x, _resonator_ir(f, t60, amp, len(x), sr))[: len(x)]
 
 
 def resonator_bank(excitation, freqs, t60s, amps, sr: int = SR) -> np.ndarray:
@@ -1000,13 +1027,31 @@ class Body:
         y = np.zeros(n)
         if not events:
             return y
-        # 多声道但共用事件：先把激励按模态分组（每个模态一份稀疏激励）
-        exc = np.zeros(n)
-        for i, (f, t60) in enumerate(zip(self.freqs, self.t60s)):
-            exc[:] = 0.0
-            for s, pulse, w in events:
-                exc[s:s + len(pulse)] += w[i] * pulse
-            y += resonator(exc, float(f), float(t60), 1.0, sr)
+        if _sig is not None:
+            # 有 scipy：逐模态 lfilter（保持 v0.7 及以前的产物逐样本不变——用户成片不出新声音）
+            exc = np.zeros(n)
+            for i, (f, t60) in enumerate(zip(self.freqs, self.t60s)):
+                exc[:] = 0.0
+                for s, pulse, w in events:
+                    exc[s:s + len(pulse)] += w[i] * pulse
+                y += resonator(exc, float(f), float(t60), 1.0, sr)
+            return y
+        # 无 scipy：先按事件把「加权模态 IR」合成一条，再与力脉冲卷积一次（N 模态 → 1 次 FFT）。
+        # 等价性：每个事件的模态权重 w_i 是标量，Σ_i w_i·conv(pulse, h_i) = conv(pulse, Σ_i w_i·h_i)
+        # 可换序；所以合并只减少 FFT 次数，不改变结果。只在兜底路径合并：有 scipy 的产物保持原样。
+        # 代价：IR 长度仍按 -80 dB 衰减截断，且只保留到输出末尾（h 超过 n-s 的部分影响不到输出）。
+        for s, pulse, w in events:
+            lcap = n - s
+            if lcap <= 0 or len(pulse) == 0:
+                continue
+            h = np.zeros(lcap)
+            for i, (f, t60) in enumerate(zip(self.freqs, self.t60s)):
+                if w[i] == 0.0:
+                    continue
+                hi = _resonator_ir(float(f), float(t60), float(w[i]), lcap, sr)
+                h[: len(hi)] += hi
+            seg = _fftconv(pulse, h)[:lcap]
+            y[s:s + len(seg)] += seg
         return y
 
 
@@ -2436,6 +2481,11 @@ def data_chirp(seed=0, dur=0.8, rate=28.0, base=1800.0, **kw):
     v0.7：音高跟随 **kw 里的 key（None = 旧行为 D 小调五声）。
     """
     r = float(rate)
+    # rate 是"每秒脉冲数"，必须为正：rate=0 会在下面 i / r 抛 ZeroDivisionError（内部
+    # 堆栈，用户看不出是参数问题）；rate<0 时 int(dur*r) 为负、事件时刻为负，_place 会
+    # 静默丢掉大部分脉冲——只剩哑音。与 _enum 同口径：认识但非法的值必须响亮报错。
+    if not math.isfinite(r) or r <= 0.0:
+        raise ValueError("data_chirp: rate 必须是正数（每秒脉冲数），收到 %r" % (rate,))
     n = max(2, int(float(dur) * r))
     g = rng(seed)
     x = _bus(dur, stereo=False)
@@ -3239,19 +3289,85 @@ def selftest() -> int:
         return "环境声响度贴合 master（±1.5 LU）"
 
     def t_fallback():
+        # v0.8：这条以前只查"输出是有限值"——等于只验了"没崩"，兜底路径的幅度
+        # 正确性完全没查（references/sfx-design.md §12 承诺静态滤波与 scipy 相对
+        # 误差 ≤ 2e-4）。现在按当前环境选参照：
+        #   有 scipy：同一函数跑两遍（scipy 路径 vs 兜底路径）逐样本比 —— 直接验"等价"；
+        #   无 scipy：没有 scipy 路径可比，改用**解析参照**（双二阶的阶跃稳态/频响、
+        #            谐振器的闭式冲激响应 amp·r^n·sin(ωn)），这样 CI 的 noscipy 任务
+        #            也在查"数值对不对"，而不是自己和自己比出一个假 PASS。
         old = globals().get("_sig")
+        has_ref = old is not None
+        S = globals()
         try:
-            globals()["_sig"] = None                    # 模拟没装 scipy
-            x = np.random.default_rng(0).standard_normal(24000)
-            y = lowpass(x, 1000.0)
-            if not np.all(np.isfinite(y)):
-                raise ValueError("无 scipy 兜底 lowpass 输出非有限值")
+            x = np.random.default_rng(0).standard_normal(24000) * 0.1
+            worst = 0.0
+
+            def cmp_paths(fn):
+                """有 scipy 时：两条路径逐样本相对误差；无 scipy 时返回 None。"""
+                if not has_ref:
+                    return None
+                S["_sig"] = old
+                a = fn()
+                S["_sig"] = None
+                b = fn()
+                d = float(np.max(np.abs(a - b))) / max(float(np.max(np.abs(a))), 1e-12)
+                return d
+
+            # 1) 静态滤波：有 scipy 比路径；无 scipy 用"阶跃稳态 = 解析 DC 增益"
+            for kind, f0, dc in (("lowpass", 1000.0, 1.0), ("highpass", 1000.0, 0.0)):
+                S["_sig"] = None
+                step = np.concatenate([np.zeros(4800), np.ones(43200)])
+                y = sosfilt(biquad(kind, f0), step)
+                err = abs(float(np.mean(y[-1000:])) - dc)
+                if err > 2e-3:
+                    raise ValueError("无 scipy %s(%g) 阶跃稳态 %.6f 偏离 DC 增益 %.3f"
+                                     % (kind, f0, float(np.mean(y[-1000:])), dc))
+                worst = max(worst, err)
+            d = cmp_paths(lambda: lowpass(x, 1000.0))
+            if d is not None:
+                if d > 2e-4:
+                    raise ValueError("无 scipy 静态滤波与 scipy 相对误差 %.2e > 2e-4" % d)
+                worst = max(worst, d)
+
+            # 2) 谐振器：闭式解。h[n] = amp·r^n·sin(ωn)（本函数构造的 b/a 决定的）。
+            #    注意激励必须**够长**：旧兜底把 IR 截断在 20000 采样，若只喂 4096 点冲激，
+            #    输出前 4096 点与解析解一致，截断根本测不出来（第一版断言就踩过这个坑）。
+            #    这里用 30000 点白噪声：t60=3 s 的 -80 dB 长度约 19.2 万采样，输出第 2 万点之后
+            #    的错误才会暴露，相对误差会到 3e-2 量级（远大于下面 2e-4 的阈值）。
+            n = 30000
+            exc = np.random.default_rng(7).standard_normal(n)
+            for f, t60, amp in ((300.0, 1.0, 0.7), (220.0, 3.0, 1.0)):
+                r0 = math.exp(-LN1000 / (t60 * float(SR)))
+                w0 = 2.0 * math.pi * f / float(SR)
+                k = np.arange(n, dtype=float)
+                h_ref = amp * np.power(r0, k) * np.sin(w0 * k)     # 解析 IR（独立于被测代码）
+                # 参照卷积用 FFT（30000×30000 直接 np.convolve 是 9e8 次乘加，实测要 20 s，
+                # 会把这个自检从 60 s 预算里挤爆）；零填充到 2 的幂即可，长度不足部分不影响
+                # 前 n 个输出采样。
+                L = n + len(h_ref) - 1
+                N = 1 << int(L - 1).bit_length()
+                ref = np.fft.irfft(np.fft.rfft(exc, N) * np.fft.rfft(h_ref, N), N)[:n]
+                S["_sig"] = None
+                h = resonator(exc, f, t60, amp)
+                err = float(np.max(np.abs(h - ref))) / max(float(np.max(np.abs(ref))), 1e-12)
+                if err > 2e-4:
+                    raise ValueError("无 scipy 谐振器 f=%g t60=%g 与闭式解相对误差 %.2e > 2e-4"
+                                     "（IR 被截断？）" % (f, t60, err))
+                worst = max(worst, err)
+
+            # 3) 时变滤波：文档承认"块中心系数 + 重叠相加"是近似（高频控制信号会平滑），
+            #    只查能跑 + 不出 NaN/Inf，不设等价阈值。
+            S["_sig"] = None
             z = tv_filter(x, "bandpass", np.linspace(300.0, 4000.0, len(x)), 0.9)
             if not np.all(np.isfinite(z)):
                 raise ValueError("无 scipy 兜底 tv_filter 输出非有限值")
         finally:
             globals()["_sig"] = old
-        return "无 scipy 兜底路径可用（短冲激响应 + FFT 卷积）"
+        if has_ref:
+            return "兜底 vs scipy：静态滤波/谐振器 ≤2e-4（实测 %.1e）/ tv_filter 可用" % worst
+        return ("无 scipy 环境：静态滤波阶跃稳态 DC 增益 / 谐振器闭式解 均 ≤2e-3（实测 %.1e）+ "
+                "tv_filter 可用（本环境没有 scipy 路径可比，用解析参照）" % worst)
 
     def t_analysis():
         m = analyze(render("impact", seed=6))

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

@@ -143,7 +143,7 @@ def _producer_of(art):
 
 # 硬类型：这些永远参与 --strict-stale 判定（产物丢了 / 源头改了 / 上游自己就过时）
 HARD_KINDS = ("source-changed", "output-missing", "no-manifest", "input-stale")
-SOFT_KINDS = ("input-pending",)
+SOFT_KINDS = ("input-pending", "source-pending")
 
 
 def _src_fp(kind, sources):
@@ -234,14 +234,27 @@ def check(work, stage, sources=None, self_built=False, pending=(), _seen=None):
     for kind in (io.get("sources") or []):
         now = _src_fp(kind, sources)
         was = old_src.get(kind, "missing")
-        if now != was:
-            fname = {"script": "剧本 film.json", "scenes": "画面代码 scenes.py"}.get(kind, kind)
+        if now == was:
+            continue
+        fname = {"script": "剧本 film.json", "scenes": "画面代码 scenes.py"}.get(kind, kind)
+        if str(stage) in planned:
+            # 源头变了 + 本轮马上就要重跑本阶段 = 正常待办，不是过时。
+            # 不软化的话，「改一句台词 -> --stage all --strict-stale」会在第一个 stage
+            # 直接失败（"没重跑却装了旧内容"——其实马上就要重跑），把主工作流堵死；
+            # 与 inputs 的 input-pending 是同一套语义，只是源头走的是另一个循环。
             issues.append(dict(
-                stage=str(stage), kind="source-changed", file=kind,
-                reason="%s 在本阶段上次跑完之后改过（%s -> %s），但本阶段没有重跑；"
-                       "它现在装的还是旧内容" % (fname, was, now),
+                stage=str(stage), kind="source-pending", file=kind, soft=True,
+                reason="%s 在上次跑本阶段之后变了（%s -> %s）；本阶段本轮会重跑，"
+                       "按新内容重算" % (fname, was, now),
                 rerun=RERUN_HINT.get(str(stage), ""),
             ))
+            continue
+        issues.append(dict(
+            stage=str(stage), kind="source-changed", file=kind,
+            reason="%s 在本阶段上次跑完之后改过（%s -> %s），但本阶段没有重跑；"
+                   "它现在装的还是旧内容" % (fname, was, now),
+            rerun=RERUN_HINT.get(str(stage), ""),
+        ))
     old_inputs = rec.get("inputs") or {}
     for name in io["inputs"]:
         now = _fp(name, work)

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

@@ -334,7 +334,7 @@ THEMES["lo-fi"] = _theme(
     ("深夜", "学习", "效率", "专注", "写作", "整理", "笔记", "书", "日常", "房间"),
     # 冷调灰绿：和 paper（暖牛皮纸）在色相上分开，不靠"亮度差不多"硬撑
     dict(bg=(232, 238, 236), bg2=(210, 220, 216), surface=(244, 248, 246),
-         ink=(44, 52, 50), muted=(86, 100, 96), dim=(112, 126, 122),
+         ink=(44, 52, 50), muted=(84, 98, 94), dim=(112, 126, 122),
          accent=(20, 86, 84), accent2=(104, 72, 96),
          good=(40, 100, 72), bad=(146, 52, 50), rule=(44, 52, 50)),
     dict(vignette=0.12, vignette_tint=(206, 200, 190), grain=7.0, grain_freq=0.24,
@@ -531,6 +531,205 @@ STYLES[LEGACY_STYLE] = {
     "pacing": {"lead": 0.55, "tail": 0.85, "min_dur": 3.0, "hold": 0.0},
 }
 
+# ============================================================================
+# 四、视觉语言包（VISUAL_LANGUAGES）：v0.9
+# ============================================================================
+#
+# 为什么还要一层
+# -------------
+# v0.5 的 THEMES 只管"皮肤"：配色、字体族、纹理、颗粒、字距、缓动、HUD、3 种版式几何。
+# 8 套风格共用同一批版式与同一套装饰（开场放射线 + 收尾光点环），所以换风格只是换色，
+# 构图骨架（剪影）没变 —— 这正是"每个视频都差不多"的根因。
+#
+# 这一层补的是**结构签名**，四组：
+#   motion     入场怎么进、镜头怎么推、呼吸元素多快
+#   motif      这套风格独有的装饰图形语言（直角括角 / 手绘内框 / letterbox / 信号条 …）
+#   transition 段与段之间怎么过（dip / wash / 纸卷 / 斜擦 / 硬切 / 放射环）
+#   typography 字距、行高、对齐、编号写法、display:body 字号比
+#
+# 设计原则（与 THEMES 一致）
+#   1. 纯数据：不 import PIL / filmkit，scenes.py 反过来读我，成环就炸。
+#   2. 只追加不改顺序：新风格往 STYLE_IDS 末尾追加，老风格的指纹映射不漂。
+#   3. 每条签名都必须"能被剪影看出差别"：只改颜色/字重的项不算签名。
+#   4. 全部受 PIL 预算约束：装饰要么预烘焙成静态层，要么是 O(几) 次 ImageDraw 调用；
+#      禁每帧全屏 GaussianBlur（实测 30–60ms）与全屏双线性 resize（29ms），预算 25ms。
+#
+# 剪影判据（tools/silhouette_qa.py 用的口径，也是 P1 的验收标准）
+#   同一段内容在两种风格下渲 3 帧 → 灰度 → 以四角亮度中位数为基准三值化 →
+#   比较 前景占比 F / 前景质心 (Cx,Cy) / 四边覆盖率 B / 左右对称度 S。
+#   五项里至少一项达标才算"这套风格真的不一样"：
+#     ΔF ≥ 6pp、|ΔCx| ≥ 8pp、|ΔCy| ≥ 8pp、ΔB ≥ 14pp、ΔS ≥ 0.20
+
+VISUAL_MOTIFS = ("brackets", "hairlines", "handdrawn", "slabs",
+                 "minimal", "letterbox", "signal", "rays")
+VISUAL_TRANSITIONS = ("dip", "wash", "paper", "wipe", "cut", "iris")
+NUMBER_STYLES = ("dim", "serif", "cn", "block", "roman", "timecode", "dot", "gilt")
+
+VISUAL_LANGUAGES = {}
+
+VISUAL_LANGUAGES["tech-deep"] = {
+    "motion": {"ease": "out3", "enter": (0.45, 0.85), "push": 0.04, "breathe_hz": 0.85},
+    "motif": {"kind": "brackets", "density": 1.0,
+              "detail": {"corner": 24, "rule_step": 120, "scan": True}},
+    "transition": {"kind": "dip", "dur": 0.28},
+    "typography": {"tracking": 0.0, "line_gap": 1.30, "align": "left",
+                   "number": "dim", "ratio": 1.50},
+    "bias": {"x": 0, "y": 0, "inset": 0},
+    "layout_cycle": ("left-stack", "split-right", "center-stack"),
+}
+
+VISUAL_LANGUAGES["magazine"] = {
+    "motion": {"ease": "out5", "enter": (0.60, 1.10), "push": 0.001, "breathe_hz": 0.50},
+    "motif": {"kind": "hairlines", "density": 0.85,
+              "detail": {"header_rule": True, "column_rule": True, "pageno": True}},
+    "transition": {"kind": "wash", "dur": 0.35},
+    "typography": {"tracking": 2.0, "line_gap": 1.34, "align": "right",
+                   "number": "serif", "ratio": 1.53},
+    "bias": {"x": 60, "y": -20, "inset": 0},
+    "layout_cycle": ("split-right", "left-stack", "center-stack"),
+}
+
+VISUAL_LANGUAGES["paper"] = {
+    "motion": {"ease": "inOut3", "enter": (0.55, 1.00), "push": 0.03, "breathe_hz": 0.42},
+    "motif": {"kind": "handdrawn", "density": 1.0,
+              "detail": {"wobble": 3.0, "seal": True, "tape": True}},
+    "transition": {"kind": "paper", "dur": 0.35},
+    "typography": {"tracking": 1.0, "line_gap": 1.36, "align": "left",
+                   "number": "cn", "ratio": 1.53},
+    # 重心偏移（px）：paper 是"手账"气质——内容整体压在左下、右侧留出大片空白给框与胶带；
+    # 这不是配色能表达的差异，是构图差异（剪影 Cx/Cy 直接反映它）。
+    "bias": {"x": -150, "y": 80, "inset": 40},
+    "layout_cycle": ("left-stack", "center-stack", "split-right"),
+}
+
+VISUAL_LANGUAGES["vivid"] = {
+    "motion": {"ease": "outBack", "enter": (0.35, 0.70), "push": 0.10, "breathe_hz": 1.10},
+    "motif": {"kind": "slabs", "density": 1.0,
+              "detail": {"bar_h": 24, "slant": 18, "sticker": True}},
+    "transition": {"kind": "wipe", "dur": 0.20},
+    "typography": {"tracking": 1.0, "line_gap": 1.26, "align": "center",
+                   "number": "block", "ratio": 2.97},
+    "bias": {"x": 0, "y": 40, "inset": 0},
+    "layout_cycle": ("center-stack", "left-stack", "split-right"),
+}
+
+VISUAL_LANGUAGES["mono"] = {
+    "motion": {"ease": "inOut3", "enter": (0.50, 0.90), "push": 0.02, "breathe_hz": 0.35},
+    "motif": {"kind": "minimal", "density": 0.55,
+              "detail": {"rule_h": 2, "box_radius": 0}},
+    "transition": {"kind": "cut", "dur": 0.0},
+    "typography": {"tracking": 6.0, "line_gap": 1.40, "align": "center",
+                   "number": "roman", "ratio": 3.15},
+    "bias": {"x": 0, "y": 0, "inset": 0},
+    "layout_cycle": ("center-stack", "center-stack", "center-stack"),
+}
+
+VISUAL_LANGUAGES["cinema"] = {
+    "motion": {"ease": "inOut3", "enter": (0.70, 1.20), "push": 0.12, "breathe_hz": 0.30},
+    "motif": {"kind": "letterbox", "density": 1.0,
+              "detail": {"top": 40, "bottom": 44, "flares": True}},
+    "transition": {"kind": "dip", "dur": 0.45},
+    "typography": {"tracking": 3.0, "line_gap": 1.38, "align": "center",
+                   "number": "timecode", "ratio": 1.62},
+    "bias": {"x": 0, "y": 30, "inset": 0},
+    "layout_cycle": ("center-stack", "left-stack", "split-right"),
+}
+
+VISUAL_LANGUAGES["lo-fi"] = {
+    "motion": {"ease": "out3", "enter": (0.45, 0.85), "push": 0.05, "breathe_hz": 0.60},
+    "motif": {"kind": "signal", "density": 0.90,
+              "detail": {"bars": 12, "radius": 18, "note": True}},
+    "transition": {"kind": "wash", "dur": 0.30},
+    "typography": {"tracking": 1.0, "line_gap": 1.36, "align": "left",
+                   "number": "dot", "ratio": 1.48},
+    # lo-fi 是"桌面便签"气质：整体右移、内容偏上，底部留给信号条与时间戳。
+    "bias": {"x": 60, "y": -70, "inset": 0},
+    "layout_cycle": ("left-stack", "split-right", "center-stack"),
+}
+
+VISUAL_LANGUAGES["epic"] = {
+    "motion": {"ease": "out5", "enter": (0.70, 1.20), "push": 0.14, "breathe_hz": 0.28},
+    "motif": {"kind": "rays", "density": 1.0,
+              "detail": {"rays": 18, "rule_gap": 26, "frame": True}},
+    "transition": {"kind": "iris", "dur": 0.40},
+    "typography": {"tracking": 4.0, "line_gap": 1.32, "align": "center",
+                   "number": "gilt", "ratio": 3.18},
+    "bias": {"x": 0, "y": -30, "inset": 0},
+    "layout_cycle": ("center-stack", "center-stack", "center-stack"),
+}
+
+# legacy：v0.4 行为，没有视觉语言（scenes.py 走 _LEGACY_DRAWERS，不会读到这张表）
+VISUAL_LANGUAGES[LEGACY_STYLE] = {
+    "motion": {"ease": "out3", "enter": (0.45, 0.85), "push": 0.04, "breathe_hz": 0.85},
+    "motif": {"kind": "brackets", "density": 1.0, "detail": {}},
+    "transition": {"kind": "cut", "dur": 0.0},
+    "typography": {"tracking": 0.0, "line_gap": 1.30, "align": "left",
+                   "number": "dim", "ratio": 1.50},
+    "layout_cycle": ("left-stack",),
+}
+
+
+def visual_language(style_id):
+    """取风格的结构签名；未知 id 退到默认风格（不让拼写错误炸掉渲染）。"""
+    sid = str(style_id or "").strip()
+    got = VISUAL_LANGUAGES.get(sid)
+    if got is not None:
+        return got
+    return VISUAL_LANGUAGES[DEFAULT_STYLE]
+
+
+def visual_lint(style_id):
+    """结构签名体检（--stage style 就拦，不等到渲完 300 帧）。返回问题列表，空 = 过。"""
+    bad = []
+    sid = str(style_id or "")
+    if sid not in VISUAL_LANGUAGES:
+        return ["风格 %r 没有视觉语言包" % sid]
+    vl = VISUAL_LANGUAGES[sid]
+    mo = vl.get("motion") or {}
+    mf = vl.get("motif") or {}          # 注意：mo = motion，mf = motif，别混用
+    tr = vl.get("transition") or {}
+    ty = vl.get("typography") or {}
+    if str(mf.get("kind")) not in VISUAL_MOTIFS:
+        bad.append("motif.kind=%r 不在 %s 里" % (mf.get("kind"), " / ".join(VISUAL_MOTIFS)))
+    if str(tr.get("kind")) not in VISUAL_TRANSITIONS:
+        bad.append("transition.kind=%r 不在 %s 里"
+                   % (tr.get("kind"), " / ".join(VISUAL_TRANSITIONS)))
+    if not 0.0 <= float(tr.get("dur") or 0.0) <= 0.60:
+        # 段界 veil 超过 0.6s 会吃掉 3–6s 节奏下限，也会把两段内容糊在一起
+        bad.append("transition.dur=%r 必须在 0~0.60s（段界 veil 上限）" % tr.get("dur"))
+    if str(ty.get("number")) not in NUMBER_STYLES:
+        bad.append("typography.number=%r 不在 %s 里"
+                   % (ty.get("number"), " / ".join(NUMBER_STYLES)))
+    if not 1.0 <= float(ty.get("ratio") or 0.0) <= 3.6:
+        bad.append("typography.ratio=%r 必须在 1.0~3.6（display:body 字号比）" % ty.get("ratio"))
+    if not 0.0 <= float(ty.get("tracking") or 0.0) <= 8.0:
+        bad.append("typography.tracking=%r 必须在 0~8px" % ty.get("tracking"))
+    if not 1.15 <= float(ty.get("line_gap") or 0.0) <= 1.55:
+        bad.append("typography.line_gap=%r 必须在 1.15~1.55" % ty.get("line_gap"))
+    if not 0.0 <= float(mf.get("density") or 0.0) <= 1.0:
+        bad.append("motif.density=%r 必须在 0~1" % mf.get("density"))
+    if float(mf.get("density") or 0.0) <= 0.0 and str(mf.get("kind")) != "minimal":
+        bad.append("motif.density=0 只允许用于 minimal（否则等于没有装饰语言）")
+    enter = mo.get("enter") or (0.45, 0.85)
+    if (not isinstance(enter, (list, tuple)) or len(enter) != 2
+            or not 0.0 < float(enter[0]) <= float(enter[1]) <= 1.6):
+        bad.append("motion.enter=%r 必须是 (起, 止) 且 0 < 起 <= 止 <= 1.6 秒" % (enter,))
+    if not 0.0 <= float(mo.get("push") or 0.0) <= 0.16:
+        # push > 0.16 时背景层放大后内容会被推出 SAFE（_bg_plate 只裁不缩）
+        bad.append("motion.push=%r 必须在 0~0.16（超过会把内容推出安全区）" % mo.get("push"))
+    return bad
+
+
+def visual_lint_all():
+    """全部内置风格的视觉语言体检，返回 {style_id: [问题]}（只有有问题的才在里面）。"""
+    out = {}
+    for sid in STYLE_IDS:
+        bad = visual_lint(sid)
+        if bad:
+            out[sid] = bad
+    return out
+
+
 ALL_STYLE_IDS = (LEGACY_STYLE,) + STYLE_IDS
 
 
@@ -633,7 +832,11 @@ def score_styles(script):
             score += 1.0 if sid in ("cinema", "paper", "mono") else 0.0
         if prof["hook"] > 0 and prof["outro"] > 0:
             score += 0.5 if sid in ("tech-deep", "vivid", "epic") else 0.0
-        score += (int(fp["style"][:4], 16) % 7) * 0.0001      # 指纹破平
+        # 指纹破平：必须把**风格 id** 混进哈希，否则这一项对所有行是同一个常数，
+        # 等于没破平（v0.8 深审实测：旧写法在"AI 报告"上 tech-deep / magazine 同分 12.0，
+        # 永远按 STYLE_IDS 顺序选 tech-deep）。幅度上限 0.0006 << 最小真实分差 0.5，
+        # 只在精确同分时起作用，且不改变"改错别字不换风格"（指纹只吃标题）。
+        score += (_digest("tiebreak", fp["style"], sid) % 7) * 0.0001
         rows.append((sid, round(score, 4), hits))
     rows.sort(key=lambda r: (-r[1], STYLE_IDS.index(r[0])))
     return rows
@@ -645,7 +848,12 @@ def pick_style(script):
     best_id, best_score, best_hits = rows[0]
     fp = fingerprint(script)
     if best_score >= 1.0:
-        reason = ["关键词命中：%s" % "、".join(dict.fromkeys(best_hits))[:80]]
+        if best_hits:
+            reason = ["关键词命中：%s" % "、".join(dict.fromkeys(best_hits))[:80]]
+        else:
+            # 分数可以只由结构加分（items / 长句 / hook+outro）凑到 1.0 以上，
+            # 这时旧文案会写"关键词命中："后面空一截 —— 等于向用户报告没发生的事。
+            reason = ["无关键词命中，按题材结构加分选中（items / 长句 / hook+outro）"]
     else:
         pool = list(STYLE_IDS)
         best_id = pool[int(fp["tempo"], 16) % len(pool)]
@@ -816,6 +1024,15 @@ def resolve_script_style(script):
     # theme_overrides 走带校验的合并（颜色支持 "#rrggbb"，非法值在这里就报错，
     # 不要等到 scenes.py 渲到第 300 帧才 int("#") 崩——见 apply_theme_overrides）
     theme = apply_theme_overrides(THEMES[pack["theme"]], vis.get("theme_overrides"))
+    # visual.layout 是"显式换整片版式"：旧的实现只把它写进 chapter_layout，而
+    # PIL 路线渲染读的是 theme["layout"]、web 路线读 layout_default —— 两条路线都不看
+    # chapter_layout，于是这条文档化的覆盖等于没写（v0.8 深审实测：visual.layout=
+    # split-right 的帧与默认帧 sha256 完全相同）。这里补写 theme["layout"] 与 layout_default，
+    # 让两条路线都跟着走；theme_overrides 更具体，它显式写了 layout 时以它为准。
+    if explicit_layout and "layout" not in (vis.get("theme_overrides") or {}):
+        theme["layout"] = explicit_layout
+    if explicit_layout:
+        chap_layout = {ch: str(theme["layout"]) for ch in chapters}
 
     return {
         "version": 1,
@@ -831,7 +1048,7 @@ def resolve_script_style(script):
         # 主题字典随计划一起返回：scenes.py 的 _scene_theme 优先用它（含 theme_overrides），
         # 也方便 render.py 直接传给 draw_subtitle/write_ass，不必再按 id 查一次。
         "theme": theme,
-        "layout_default": layouts[0],
+        "layout_default": str(theme["layout"]) if explicit_layout else layouts[0],
         "chapter_layout": chap_layout,
         "music": {
             "style": music_style,
@@ -854,7 +1071,8 @@ def resolve_script_style(script):
 # 七、门禁：主题体检（对比度 / 明暗 / 结构）
 # ============================================================================
 #
-# 阈值不是拍脑袋：以 v0.4 现行主题实测值当基线（ink 16.3 / muted 7.8 / accent 7.0）。
+# 阈值不是拍脑袋：以 v0.4 现行主题实测值当基线（tech-deep：ink 16.3 / muted 7.8 / accent 7.0，
+# 那是旧版按 bg/bg2 中点量的；v0.8 改成按两端最差值量后同一主题是 14.8 / 7.1 / 6.3，仍远高于线）。
 
 LINT_LIMITS = {
     "ink": 7.0,          # 正文级（WCAG AAA 正文线）
@@ -868,18 +1086,30 @@ LINT_LIMITS = {
 }
 
 
+def bg_contrast(th, role):
+    """文字色对背景的**最差**对比度：bg/bg2 是上下两端的主渐变（scenes._bg 按行插值），
+    任何一行文字都可能落在两端附近，所以取二者较小值，而不是看中点。
+
+    为什么不能只看中点：lo-fi 的 muted(86,100,96) 对 bg 5.28、对 bg2 只有 4.42，
+    中点平均 4.84 把 AA 4.5 的门槛"平均"过去了 —— 实测过（v0.8 深审），
+    这一版把门槛改成端点最差值，并同时下调 lo-fi 的 muted 到 (84,98,94)
+    （bg 5.44 / bg2 4.56，两端都过）。
+    """
+    return min(contrast(th[role], th["bg"]), contrast(th[role], th["bg2"]))
+
+
 def theme_lint(th):
     """主题体检，返回问题列表（空 = 过）。坏主题在 load 阶段就拦，别等渲完 300 帧。"""
     if not isinstance(th, dict):
         return ["主题不是 dict：%r" % (th,)]
     bad = []
-    bgs = midpoint(th["bg"], th["bg2"])
     for role, need in (("ink", LINT_LIMITS["ink"]), ("muted", LINT_LIMITS["muted"]),
                        ("dim", LINT_LIMITS["dim"]), ("accent", LINT_LIMITS["accent"]),
                        ("accent2", LINT_LIMITS["accent2"])):
-        got = contrast(th[role], bgs)
+        got = bg_contrast(th, role)
         if got < need:
-            bad.append("%s 对背景对比度 %.2f < %.1f" % (role, got, need))
+            bad.append("%s 对背景对比度 %.2f < %.1f（bg/bg2 两端取最差）"
+                       % (role, got, need))
     for role in ("good", "bad"):
         got = contrast(th[role], th["surface"])
         if got < LINT_LIMITS[role]:
@@ -947,7 +1177,6 @@ def blend_theme(a, b, p):
 def _describe(sid):
     pack = STYLES[sid]
     th = THEMES[pack["theme"]]
-    bgs = midpoint(th["bg"], th["bg2"])
     lines = [
         "[%s] %s  （theme=%s / layouts=%s）" % (sid, pack["name"], pack["theme"],
                                                 ",".join(pack["layouts"])),
@@ -961,9 +1190,10 @@ def _describe(sid):
         % (pack["pacing"]["lead"], pack["pacing"]["tail"], pack["pacing"]["min_dur"]),
         "  palette   : bg=%s bg2=%s ink=%s accent=%s"
         % (th["bg"], th["bg2"], th["ink"], th["accent"]),
-        "  contrast  : ink %.2f / muted %.2f / dim %.2f / accent %.2f"
-        % (contrast(th["ink"], bgs), contrast(th["muted"], bgs),
-           contrast(th["dim"], bgs), contrast(th["accent"], bgs)),
+        # 与 theme_lint 同口径：bg/bg2 两端取最差（旧版打中点值，会掩盖端点不达标）
+        "  contrast  : ink %.2f / muted %.2f / dim %.2f / accent %.2f（bg/bg2 最差端）"
+        % (bg_contrast(th, "ink"), bg_contrast(th, "muted"),
+           bg_contrast(th, "dim"), bg_contrast(th, "accent")),
         "  font      : family=%s display=%spx hud=%s"
         % (th["family"], th["scale"]["display"][0], th["hud"]),
     ]

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

@@ -207,8 +207,12 @@ except Exception:                        # noqa: BLE001 — stylekit 缺失时
 # ============================================================================
 # 三、小工具：参数解析/格式化、汉字计数、抖动
 # ============================================================================
-_PCT_RE = re.compile(r"^\s*([+-]?)(\d+)\s*%\s*$")
-_HZ_RE = re.compile(r"^\s*([+-]?)(\d+)\s*Hz\s*$")
+# 允许小数（"+4.5%"）：edge-tts 只收整数百分比，所以解析后按 _round_half_away 取整。
+# 以前正则只认整数，"+4.5%" 解析失败 → 静默回落 0 —— 而 0 与 "+0%" 在 spec_key 里
+# 是**同一个 TTS 缓存键**，于是"把语速从 0 调到 4.5%"完全没生效，还复用了旧音频。
+# 这是配置写对了却不生效里最难查的一类：没有报错、没有日志、听起来就是"没反应"。
+_PCT_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*%\s*$")
+_HZ_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*Hz\s*$")
 
 
 def _round_half_away(v):
@@ -218,24 +222,24 @@ def _round_half_away(v):
 
 
 def parse_pct(v, default=0):
-    """'+4%' -> 4；'-3%' -> -3；数字原样取整；解析失败回落 default。"""
+    """'+4%' -> 4；'-3%' -> -3；'+4.5%' -> 5（取整）；数字原样取整；解析失败回落 default。"""
     if isinstance(v, (int, float)) and not isinstance(v, bool):
         return int(_round_half_away(v))
     m = _PCT_RE.match(str(v if v is not None else ""))
     if not m:
         return int(default)
-    n = int(m.group(2))
+    n = int(_round_half_away(float(m.group(2))))
     return -n if m.group(1) == "-" else n
 
 
 def parse_hz(v, default=0):
-    """'+2Hz' -> 2；解析失败回落 default。"""
+    """'+2Hz' -> 2；'+2.5Hz' -> 3（取整）；解析失败回落 default。"""
     if isinstance(v, (int, float)) and not isinstance(v, bool):
         return int(_round_half_away(v))
     m = _HZ_RE.match(str(v if v is not None else ""))
     if not m:
         return int(default)
-    n = int(m.group(2))
+    n = int(_round_half_away(float(m.group(2))))
     return -n if m.group(1) == "-" else n
 
 
@@ -306,7 +310,11 @@ def _quantize(v, u):
 # ============================================================================
 # 四、文本规则（说什么）：全部确定性，命中即返回理由
 # ============================================================================
-_QUOTE_OPEN = ('"', "\u201c", "\u300c", "\u300e", "\u300a")
+# 引语起始符。**不含书名号 《（《）**：正文里出现"《设计模式》"是书名，不是引用某人在说话。
+# 实测踩过：把 《 算进引语后，"今天我们聊《设计模式》"这句的 tone 被判成 quote，
+# 进而触发 rule:quote:persona，把 persona 从 narrator_male 换成 narrator_female ——
+# 旁白中途换人，听感像换了主播（而这句根本没有人引语）。
+_QUOTE_OPEN = ('"', "\u201c", "\u300c", "\u300e")
 _QUOTE_WORDS = ("他说", "她说", "有人问", "所谓", "据称")
 _NUM_UNITS = ("%", "万", "亿", "年", "倍")
 _TURN_WORDS = ("但是", "然而", "不过", "其实", "问题是")