@remixmate/cli 0.9.44 → 0.9.46

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -29,6 +29,35 @@ VALID_RATIOS = {"16:9", "9:16", "1:1", "4:3", "3:4", "21:9"}
 VALID_RESOLUTIONS = {"480p", "720p", "1080p", "4k"}
 VALID_PURPOSES = {"opening", "intro", "point", "example", "explanation", "transition", "highlight", "cta", "ending"}
 VALID_LAYOUTS = {"full-visual", "split-left-right", "split-top-bottom", "picture-in-picture", "text-overlay", "avatar-with-bg", "kenburns"}
+
+# 场景数上限的兜底值。叙事弧类模板的合理上界——20 段以上的短视频必然过碎。
+# "一页素材一个场景"的模板（ppt-to-video）场景数由源文件页数决定，应当用
+# ``capabilities.maxScenes`` 抬高；这个常量只是没声明时的默认。
+DEFAULT_MAX_SCENES = 20
+
+# 声明式上界的上界。模板可以抬高 maxScenes，但不能抬到无限——一次请求排上千个场景
+# 会在下游（TTS 逐场景合成、Remotion 逐场景渲染）变成一次谁也杀不掉的长任务。
+MAX_SCENES_CEILING = 200
+
+
+def max_scenes_for_template(template_config: Optional[dict]) -> int:
+    """模板声明的场景数上限，缺省 ``DEFAULT_MAX_SCENES``。
+
+    单一实现：gen-script 规划场景时用它决定 clamp 到几，dsl_validator 用它做门禁。
+    两边各写一份 ``min(n, 20)`` 正是这个仓库反复栽的那种跟头。
+
+    宽容读取：非正整数、非数字、capabilities 缺失一律回落到默认值，不抛异常——
+    一个写坏的 template.json 不该让所有模板的场景规划一起失败。
+    """
+    caps = (template_config or {}).get("capabilities")
+    if not isinstance(caps, dict):
+        return DEFAULT_MAX_SCENES
+    declared = caps.get("maxScenes")
+    if isinstance(declared, bool) or not isinstance(declared, int):
+        return DEFAULT_MAX_SCENES
+    if declared < 1:
+        return DEFAULT_MAX_SCENES
+    return min(declared, MAX_SCENES_CEILING)
 VALID_ASSET_TYPES = {"image", "video", "audio", "avatar", "subtitle", "bgm"}
 VALID_ASSET_SOURCES = {"existing", "gen-image", "gen-video", "gen-voice", "gen-digital-human"}
 
@@ -245,14 +274,30 @@ def _check_scenes_min(dsl: dict) -> list[ValidationError]:
 
 
 def _check_scenes_max(dsl: dict) -> list[ValidationError]:
-    """Scenes 上限 20。仅 gen-script 历史规则集 + 完整版用——render-video
+    """Scenes 上限。仅 gen-script 历史规则集 + 完整版用——render-video
     历史不查上限,合并时若同时启用此检查会"原本能过的 DSL 现在被拒",
     故只在 ``validate_structural`` / ``validate_dsl`` 启用。
+
+    上限由模板的 ``capabilities.maxScenes`` 声明,缺省 ``DEFAULT_MAX_SCENES``(20)。
+    20 这个数字是给"叙事弧"类模板定的——一条 60 秒短视频排到 20 段已经过碎。但
+    "一页素材一个场景"的模板(ppt-to-video 逐页讲解)的场景数由源文件页数决定,
+    跟叙事节奏无关:2026-09-23 线上一份 23 页 PPT 就是在这里被砍到 20 页,
+    而且砍得毫无声响,直到下游报 ``customPayload.slide (required)`` ×20 才暴露。
+    所以上限改成模板自己声明,并且这里的报错要说清它是谁定的。
     """
     scenes = dsl.get("scenes", [])
-    if isinstance(scenes, list) and len(scenes) > 20:
+    if not isinstance(scenes, list):
+        return []
+    template_id = _pick_template_id(dsl)
+    limit = max_scenes_for_template(_get_template_cfg(template_id))
+    if len(scenes) > limit:
+        source = (
+            f"template '{template_id}' declares capabilities.maxScenes={limit}"
+            if limit != DEFAULT_MAX_SCENES
+            else f"the default limit is {limit}; a template can raise it via capabilities.maxScenes"
+        )
         return [ValidationError(
-            "scenes", f"must contain at most 20 scenes, got {len(scenes)}",
+            "scenes", f"must contain at most {limit} scenes, got {len(scenes)} ({source})",
         )]
     return []
 
@@ -684,6 +729,90 @@ def _check_line_sync_narration(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_step_narration_alignment(dsl: dict) -> list[ValidationError]:
+    """声明「动作与旁白一一对应」的模板：动作条数应当等于旁白句数。
+
+    由模板的 ``capabilities.stepAlignment`` 声明触发,不写死模板名::
+
+        "stepAlignment": {
+          "payloadField": "steps",       # customPayload 里放动作数组的字段
+          "alignTo": "narration-sentences"
+        }
+
+    为什么值得单独查:这一类失配**渲得出来**。动作按句下标对齐,条数不等时多出的
+    句子没有任何动作(画面停住)或多出的动作挤在最后一句上,而退出码是 0、
+    renderJob 是 completed、漏斗记 rendered —— 缺陷只存在于成片里,没有任何
+    自动信号会告状。2026-09-23 线上那条鸡兔同笼就是这么交付的。
+
+    严重度是 **warning**:步数少于句数有时确实是作者的本意(末尾一句总结不配动作)。
+    真正要判断的是"作者以为一一对应、实际不是",只有作者做得了这个判断,所以这里
+    给两个数字,不给结论。但它必须被打出来 —— 上一版连数字都没有。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    caps = tpl.get("capabilities")
+    spec = caps.get("stepAlignment") if isinstance(caps, dict) else None
+    if not isinstance(spec, dict):
+        return []
+    field = spec.get("payloadField")
+    if not isinstance(field, str) or not field:
+        return []
+    if spec.get("alignTo") not in (None, "narration-sentences"):
+        return []
+
+    try:
+        from .timeline_compiler import count_narration_sentences
+    except ImportError:
+        return []
+
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload")
+        if not isinstance(custom, dict):
+            continue
+        steps = custom.get(field)
+        if not isinstance(steps, list) or not steps:
+            continue  # 不给 steps 走模板自己的兜底,不是本检查的事
+
+        # 全部显式写了 atSec 的步骤不参与下标对齐,不该算失配。
+        # 排除 bool:Python 里 True 是 int 的实例,而渲染端用 `typeof === "number"`
+        # 判断,不认 true。两边口径必须一致,否则这里放行的东西那边仍按下标对齐。
+        def _has_explicit_at_sec(step: object) -> bool:
+            if not isinstance(step, dict):
+                return False
+            at = step.get("atSec")
+            return isinstance(at, (int, float)) and not isinstance(at, bool)
+
+        if all(_has_explicit_at_sec(s) for s in steps):
+            continue
+
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        text = narration.get("text")
+        if not isinstance(text, str) or not text.strip():
+            continue
+        sentences = count_narration_sentences(text)
+        if sentences == 0 or len(steps) == sentences:
+            continue
+
+        sid = scene.get("id", f"scenes[{idx}]")
+        tail = (
+            f"最后 {sentences - len(steps)} 句旁白没有对应动作,画面会在那之前走完并停住"
+            if len(steps) < sentences
+            else f"多出的 {len(steps) - sentences} 个动作会挤在最后一句上"
+        )
+        errors.append(ValidationError(
+            f"scenes[{idx}].customPayload.{field}",
+            f"scene '{sid}': {len(steps)} 个动作 vs 旁白 {sentences} 句 —— {tail}。"
+            f"本模板的动作按**句**对齐(第 i 个动作 = 第 i 句的起拍帧),"
+            f"要一一对应就让两者等数;确实想不等就忽略这条(它不阻断渲染)。"
+            f"注意句数按句末标点(。！？；)统计,一句里放两个句末标点会被数成两句。",
+            severity="warning",
+        ))
+
+    return errors
+
+
 def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
     """逐版式校验 ``customPayload.templateData`` 的字段名。
 
@@ -1055,6 +1184,9 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_payload_fields(dsl)
     errors += _check_custom_payload_fields(dsl)
     errors += _check_line_sync_narration(dsl)
+    # warning,不阻断。放在 integrity 里是因为这是 render-video 的入口:失配的后果
+    # 是**渲得出来但错位**,只有在真要渲之前说才来得及。
+    errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     return errors
 
@@ -1088,5 +1220,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_payload_fields(dsl)
     errors += _check_custom_payload_fields(dsl)
     errors += _check_line_sync_narration(dsl)
+    errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     return errors

package/skills/template-registry/video_dsl/runtime/timeline_compiler.py

@@ -171,6 +171,49 @@ def _merge_short(segments: list[str], min_len: int) -> list[str]:
     return merged
 
 
+def assign_sentence_indices(raw_texts: list[str]) -> list[int]:
+    """给每个字幕/TTS 段标注它属于原旁白的第几**句**（0-based）。
+
+    为什么必须单独标：一段 **不等于** 一句。``segment_narration`` 在句末断行之后，
+    还会把超过 ``MAX_SEGMENT_CHARS`` 的长句在逗号处继续切 —— 那是为了让 TTS 按真实
+    停顿返回时间戳，跟"句"没关系。于是 35 字的一句话会变成 3 段。
+
+    靠下标把「第 i 个动作」对齐到「第 i 段字幕」的模板（math-principles-expl 的
+    ``steps``、ppt-to-video 的 ``beats``）因此会整体错位，而且是**静默**的：
+    2026-09-23 线上一条鸡兔同笼成片里 10 句旁白被切成约 19 段，板面 10 步在音频
+    播到一半就走完，之后画面冻结、旁白继续，全程零报错、终态 completed。
+
+    判据：一段是某句的**末段**，当且仅当它以句末标点（``。！？；`` 或换行）结尾。
+    这与 ``_PRIMARY_BREAK`` 是同一个集合 —— 切的时候用它断，标的时候用它认，
+    所以两边不会漂移。
+
+    ⚠️ 必须传**未去尾标点**的原文。``_strip_trailing_punct`` 之后句末标点就没了，
+    那时所有段都会被认成同一句。
+
+    极少数情况下一段会跨句：``_merge_short`` 为了不让 TTS 行短到丢语气，会把一个
+    过短的段向后并（比如整句只有「对吗？」三个字）。这时该段归**它起始的那一句**，
+    因为调用方要的是「这句话从哪一帧开始被说出来」。
+    """
+    indices: list[int] = []
+    sentence = 0
+    for text in raw_texts:
+        indices.append(sentence)
+        if _PRIMARY_TAIL.search(text or ""):
+            sentence += 1
+    return indices
+
+
+def count_narration_sentences(text: str) -> int:
+    """数一段旁白有多少句。与 ``assign_sentence_indices`` 同一判据。
+
+    给校验层用：模板声明「steps 与旁白一一对应」时，用它和 steps 条数比对。
+    """
+    if not text or not text.strip():
+        return 0
+    chunks = [s for s in _PRIMARY_BREAK.split(text.strip()) if s.strip()]
+    return len(chunks)
+
+
 def _plain_len(text: str) -> int:
     """计算去掉 **...** 标记后的纯文本字符数，用于更准确的时间分配。"""
     return len(_EMPHASIS_MARKS.sub("", text))
@@ -232,15 +275,18 @@ def split_subtitle_from_lines(
         max(duration_frames - 2 * padding_frames, fps),
         max(estimated_audio_frames, fps),
     )
+    # 句归属必须在去尾标点**之前**算 —— 去掉「。」之后就认不出句末了。
+    sentence_indices = assign_sentence_indices(segments)
     result: list[dict] = []
     current_frame = padding_frames
-    for seg in segments:
+    for i, seg in enumerate(segments):
         ratio = _plain_len(seg) / total_chars
         frames = max(int(usable_frames * ratio), fps // 2)
         result.append({
             "text": _strip_trailing_punct(seg.strip()),
             "startFrame": current_frame,
             "endFrame": current_frame + frames,
+            "sentenceIndex": sentence_indices[i],
         })
         current_frame += frames
     return result
@@ -262,15 +308,18 @@ def split_subtitle(text: str, duration_frames: int, fps: int, padding_frames: in
         max(duration_frames - 2 * padding_frames, fps),
         max(estimated_audio_frames, fps),
     )
+    # 句归属必须在去尾标点**之前**算（见 assign_sentence_indices）。
+    sentence_indices = assign_sentence_indices(segments)
     result: list[dict] = []
     current_frame = padding_frames
-    for seg in segments:
+    for i, seg in enumerate(segments):
         ratio = _plain_len(seg) / total_plain
         frames = max(int(usable_frames * ratio), fps // 2)
         result.append({
             "text": _strip_trailing_punct(seg.strip()),
             "startFrame": current_frame,
             "endFrame": current_frame + frames,
+            "sentenceIndex": sentence_indices[i],
         })
         current_frame += frames