@remixmate/cli 0.9.46 → 0.9.48

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.46",
-  "generatedAt": "2026-09-23T08:47:39.701Z",
+  "version": "0.9.48",
+  "generatedAt": "2026-09-24T03:37:24.431Z",
   "skills": [
     {
       "id": "doc-parse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.46",
+  "version": "0.9.48",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,9 @@
     "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
     "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
     "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
-    "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py"
+    "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py",
+    "test:image-prompt-compose": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-prompt-compose.py",
+    "test:picture-book-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-picture-book-contract.py"
   },
   "keywords": [
     "claude-code",

package/skills/gen-script/scripts/gen_script.py

@@ -60,10 +60,17 @@ except ImportError:
     _HAS_COUNTDOWN = False
 
 try:
-    from video_dsl.runtime.prompt_enhancer import build_enhanced_prompt
+    from video_dsl.runtime.prompt_enhancer import (
+        COMPOSE_SUBJECT_PLACEHOLDER,
+        SKELETON_PREFIXES,
+        build_enhanced_prompt,
+        is_compose_mode,
+        resolve_style_guide,
+    )
     _HAS_ENHANCER = True
 except ImportError:
     _HAS_ENHANCER = False
+    SKELETON_PREFIXES = ("[骨架待填充]", "[skeleton placeholder]")
 
 # 场景数上限的唯一实现在 dsl_validator（它同时是门禁方）。守护式导入的理由同上：
 # 共享目录可能不在（单测 / 裁剪安装），那时退回历史常量 20，行为与改动前一致。
@@ -188,11 +195,10 @@ def _check_narration_language(narrations, expected):
     """
     cjk_re = __import__("re").compile(r"[\u4e00-\u9fff]")
     latin_re = __import__("re").compile(r"[A-Za-z]")
-    skeleton_prefixes = (NARRATION_SKELETON_MARKER, "[skeleton placeholder]")
     for text in narrations:
         if not isinstance(text, str) or not text.strip():
             continue
-        if text.lstrip().startswith(skeleton_prefixes):
+        if text.lstrip().startswith(SKELETON_PREFIXES):
             continue
         has_cjk = bool(cjk_re.search(text))
         has_latin = bool(latin_re.search(text))
@@ -377,7 +383,7 @@ def estimate_narration_text(label: str, purpose: str, duration: int, topic: str,
 
 
 # 骨架标记：出现此前缀说明 narration 仍是 gen_script 原始骨架，未被 agent 填充真实内容
-NARRATION_SKELETON_MARKER = "[骨架待填充]"
+NARRATION_SKELETON_MARKER = SKELETON_PREFIXES[0]
 
 
 def generate_image_prompt(
@@ -622,9 +628,58 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "primary_visual_type": primary_visual_type,
         "default_layout": caps.get("defaultLayout"),
         "authored_scenes": caps.get("authoredScenes") is True,
+        # 画面文字契约（dsl_validator 按 error 执行）；骨架据此为每个必填 role 留占位
+        "text_layer_rules": caps.get("textLayerRules") if isinstance(caps.get("textLayerRules"), dict) else None,
+        # arc 叙事弧的收尾场景用途（缺省 cta）。绘本收尾是 ending（寓意页），不是「关注我们」
+        "arc_closing_purpose": caps.get("arcClosingPurpose") if isinstance(caps.get("arcClosingPurpose"), str) else None,
+        # 骨架里 transitions.default 的取值；缺省 fade（历史行为）
+        "default_transition": caps.get("defaultTransition") if isinstance(caps.get("defaultTransition"), str) else None,
     }
 
 
+def _slot_reads_visual(template_config: dict | None, purpose: str) -> bool:
+    """这个用途的版式会不会显示背景素材（slotMapping 里有没有读 visuals.background.assetRef）。
+
+    不显示的版式（如绘本的 ending 寓意页）不该规划图片：素材照样会被生成、扣积分，
+    却永远不上屏。模板没声明 slotMapping 时按「会显示」处理，保持历史行为。
+    """
+    mapping = (template_config or {}).get("slotMapping")
+    if not isinstance(mapping, dict) or not mapping:
+        return True
+    slot = mapping.get(purpose) or mapping.get("default") or {}
+    seen: set = set()
+    while isinstance(slot, dict) and "$ref" in slot and slot["$ref"] not in seen:
+        seen.add(slot["$ref"])
+        slot = mapping.get(slot["$ref"]) or {}
+    extractors = (slot or {}).get("propExtractors") if isinstance(slot, dict) else None
+    if not isinstance(extractors, dict):
+        return True
+    return any(
+        isinstance(ex, dict) and str(ex.get("from", "")).endswith("visuals.background.assetRef")
+        for ex in extractors.values()
+    )
+
+
+def _placeholder_text_layers(rules: dict) -> list[dict]:
+    """模板声明了 capabilities.textLayerRules 时，骨架的文字层 = 每个必填 role 一条占位。
+
+    通用骨架给的是「内容要点 N」「关注我们」这类文案，对有文字契约的模板全是错的，
+    而且留着一个没声明的 role（badge）只会让模型以为那里要填东西。占位带骨架前缀，
+    dsl_validator 会拒绝原样提交；带上语言要求，模型不用再去 llmHint 里找。
+    """
+    language = rules.get("language") if isinstance(rules.get("language"), dict) else {}
+    hints = {"en": "English text for this page", "zh": "本页中文译文"}
+    layers = []
+    for role in rules.get("required") or []:
+        if not isinstance(role, str):
+            continue
+        lang = language.get(role)
+        prefix = SKELETON_PREFIXES[1] if lang == "en" else SKELETON_PREFIXES[0]
+        hint = hints.get(lang, role)
+        layers.append({"role": role, "content": f"{prefix} {role}: {hint}"})
+    return layers
+
+
 def _normalize_linebreaks(value: str | None) -> str:
     """把画面文字里的**字面量** ``\\n`` 折成真换行。
 
@@ -788,11 +843,15 @@ def _plan_contract_scenes(
     这类模板由此能产出真正的单场景，而不再被强行补到 3 段。``--scenes`` 只对 arc 生效。
     """
     if contract["scene_strategy"] == "arc":
-        return plan_scenes(
+        plans = plan_scenes(
             topic, duration, scene_count, False,
             language=language,
             max_scenes=contract.get("max_scenes", DEFAULT_MAX_SCENES),
         )
+        closing = contract.get("arc_closing_purpose")
+        if closing and plans and plans[-1]["purpose"] == "cta":
+            plans[-1] = {**plans[-1], "purpose": closing}
+        return plans
 
     fixed = contract["fixed_scenes"] or [{"purpose": "opening"}]
     n = len(fixed)
@@ -1456,6 +1515,13 @@ def build_dsl(
     assets = []
     scenes = []
 
+    # 模板的生图指南。compose 模式（imageStyleGuide.mode == "compose"）下骨架里的
+    # payload.prompt 只是「画面主体」占位 —— 画风 / 配色 / 负向词由 render_video 在旁白
+    # 定稿后统一拼上，这里若先拼一份完整 prompt，agent 会以为写好了，或在它上面叠写。
+    image_style_guide = resolve_style_guide(template_config) if _HAS_ENHANCER else {}
+    image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
+    image_ratio = image_style_guide.get("ratio") or ratio
+
     for idx, plan in enumerate(scene_plans):
         scene_id = f"scene-{idx + 1:02d}"
         # 视觉素材的 assetId 命名遵循类型前缀：image → img-，video → video-
@@ -1469,8 +1535,11 @@ def build_dsl(
             if needs_narration else ""
         )
 
+        # 本场景的版式不显示背景素材（如绘本 ending）→ 不规划视觉素材，免得白生成
+        scene_has_visual = has_visual and _slot_reads_visual(template_config, plan["purpose"])
+
         # 仅 visual-overlay 模板生成视觉素材（slide 无视觉素材，carousel-caption 已提前返回）
-        if has_visual and primary_visual_type == "image":
+        if scene_has_visual and primary_visual_type == "image":
             slot = provided_slots[idx] if idx < len(provided_slots) else ""
             slot_is_ai, slot_prompt = _parse_ai_slot(slot)
             if slot and not slot_is_ai:
@@ -1495,7 +1564,13 @@ def build_dsl(
                     "url": stub_image_url,
                 })
             else:
-                image_result = generate_image_prompt(plan["purpose"], topic, style, narration_text=narration_text)
+                if image_compose:
+                    image_result = {"prompt": COMPOSE_SUBJECT_PLACEHOLDER}
+                else:
+                    image_result = generate_image_prompt(
+                        plan["purpose"], topic, style,
+                        narration_text=narration_text, style_guide=image_style_guide,
+                    )
 
                 # 用户在 AI 段里写了提示词就用他的。**只替换主体，不动 negativePrompt /
                 # guidanceScale**：那两项是模板的护栏（"不要文字水印、不要变形"），把它们
@@ -1507,7 +1582,7 @@ def build_dsl(
                 img_payload = {
                     "prompt": image_result["prompt"],
                     "model": os.environ.get("DEFAULT_IMAGE_MODEL", "doubao/doubao-seedream-5-0-260128"),
-                    "ratio": ratio,
+                    "ratio": image_ratio,
                 }
                 if "negativePrompt" in image_result:
                     img_payload["negativePrompt"] = image_result["negativePrompt"]
@@ -1521,7 +1596,7 @@ def build_dsl(
                     "status": "planned",
                     "payload": img_payload,
                 })
-        elif has_visual and primary_visual_type == "video":
+        elif scene_has_visual and primary_visual_type == "video":
             if stub_video_url:
                 assets.append({
                     "assetId": visual_asset_id,
@@ -1568,7 +1643,7 @@ def build_dsl(
                 },
             })
 
-        if has_visual:
+        if scene_has_visual:
             layout = "text-overlay" if plan["purpose"] in ("opening", "cta") else "full-visual"
             text_layers = []
             if plan["purpose"] == "opening":
@@ -1593,6 +1668,8 @@ def build_dsl(
                 ]
                 if effective_subheadline:
                     text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
+            if contract["text_layer_rules"]:
+                text_layers = _placeholder_text_layers(contract["text_layer_rules"])
 
             scene = {
                 "id": scene_id,
@@ -1660,6 +1737,9 @@ def build_dsl(
                 if effective_subheadline:
                     text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
 
+            if contract["text_layer_rules"]:
+                text_layers = _placeholder_text_layers(contract["text_layer_rules"])
+
             custom_payload = _build_custom_payload(template_config)
             if beat_count is not None:
                 # Field names come from the template's countdown declaration — this
@@ -1702,6 +1782,8 @@ def build_dsl(
             "outputLanguage": output_language,
             "style": style or "",
             "description": _localize_label(output_language, "video_description", topic=topic, duration=duration),
+            # compose 模式：留一个空位让 agent 写全书共用的角色外观设定，每张图都会逐字注入
+            **({"characterSheet": ""} if image_compose and has_visual else {}),
         },
         "global": {
             "aspectRatio": ratio,
@@ -1716,7 +1798,8 @@ def build_dsl(
         },
         "assets": assets,
         "scenes": scenes,
-        "transitions": {"default": "fade", "duration": 0.5},
+        # 模板声明了 capabilities.defaultTransition 就用它（绘本 = none：淡入会露出黑底）
+        "transitions": {"default": contract["default_transition"] or "fade", "duration": 0.5},
     }
 
     if template_id:

package/skills/render-video/scripts/render_video.py

@@ -553,6 +553,26 @@ def _hydrate_dsl_payload(
         LogPrint(f"   {line}", file=sys.stderr)
 
 
+def _compose_image_prompts(dsl: dict, template_id: str | None) -> None:
+    """按模板 imageStyleGuide 把画风套到待生成图片的 prompt 上（就地改 dsl）。
+
+    只对 ``imageStyleGuide.mode == "compose"`` 的模板生效：agent 在 payload.prompt 里
+    只写画面主体，模板的画风 / 配色 / 负向词 / 比例在这里确定地、只一次地拼上去。
+    放在这里（而不是 gen_script）是因为此刻旁白已是定稿，不是骨架占位。
+    其余模板是零成本 no-op；registry 不可达时同样跳过，与 _hydrate_dsl_payload 一致。
+    """
+    try:
+        from registry_loader import get_template  # noqa: E402
+        from video_dsl.runtime.prompt_enhancer import compose_dsl_image_prompts  # noqa: E402
+        template = get_template(template_id) if template_id else None
+    except Exception:  # noqa: BLE001 - 取不到模板就不 compose，prompt 按 agent 写的原样用
+        return
+    if not template:
+        return
+    for line in compose_dsl_image_prompts(dsl, template):
+        LogPrint(f"   {line}", file=sys.stderr)
+
+
 def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> None:
     """动作条数与旁白句数不等时出声。
 
@@ -968,6 +988,13 @@ def resolve_asset_image(asset: dict, private_token: str, timeout: int) -> dict:
         cmd.extend(["--size", payload["ratio"]])
     if payload.get("model"):
         cmd.extend(["--model", payload["model"]])
+    # 模板声明的负向词 / 引导强度 / 种子以前在这里被丢掉，gen-image 从没收到过。
+    if payload.get("negativePrompt"):
+        cmd.extend(["--negative-prompt", str(payload["negativePrompt"])])
+    if payload.get("guidanceScale") is not None:
+        cmd.extend(["--guidance-scale", str(payload["guidanceScale"])])
+    if payload.get("seed") is not None:
+        cmd.extend(["--seed", str(int(payload["seed"]))])
     if private_token:
         cmd.extend(["--priv-token", private_token])
 
@@ -1413,6 +1440,26 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     })
 
 
+def _template_default_tail_pad_frames(template_id: str, fps: int) -> int | None:
+    """模板声明的旁白尾巴默认值（``capabilities.defaultTailPadSec``），换算成帧。
+
+    场景自己的 ``customPayload.tailPadSec`` 仍然优先；这里只替换全局 1.5s 兜底。
+    为什么要模板级：逐场景设置靠模型照着 llmHint 抄，实际经常漏 —— 2026-09-24
+    线上《狼来了》绘本每页结尾 1.9s 空白，86s 里 15s 没有声音。
+    """
+    if not template_id:
+        return None
+    try:
+        from registry_loader import get_template  # type: ignore
+        tpl = get_template(template_id, include_all_statuses=True)
+    except Exception:  # noqa: BLE001 - 取不到模板就走全局默认，不因为这个挡渲染
+        return None
+    value = ((tpl or {}).get("capabilities") or {}).get("defaultTailPadSec")
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+        return None
+    return int(round(float(value) * fps))
+
+
 def adjust_timeline_to_audio(render_plan: dict) -> dict:
     """Post-process: use real TTS audio durations and timestamps to fix
     scene durations and subtitle segments."""
@@ -1422,6 +1469,9 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
     assets_map = {a["assetId"]: a for a in render_plan["resolvedAssets"]}
     current_frame = 0
     adjusted = 0
+    default_tail_pad = _template_default_tail_pad_frames(render_plan.get("templateId", ""), fps)
+    if default_tail_pad is None:
+        default_tail_pad = int(fps * 1.5)
 
     for entry in render_plan["timeline"]:
         # narration assetId 现在直接由 propExtractors 注入到 props.narrationAssetId，
@@ -1445,13 +1495,14 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                 })
             else:
                 audio_frames = math.ceil(audio_ms / 1000.0 * fps)
-                # DSL 里 scene.customPayload.tailPadSec 可覆盖默认 1.5s 尾巴
-                # （比如开场卡片要紧接下一场，设 0 直接贴音频结束）。
+                # DSL 里 scene.customPayload.tailPadSec 可覆盖默认尾巴
+                # （比如开场卡片要紧接下一场，设 0 直接贴音频结束）；默认值是模板的
+                # capabilities.defaultTailPadSec，没声明时 1.5s。
                 tail_pad_override = entry.get("tailPadFrames")
                 tail_pad = (
                     int(tail_pad_override)
                     if isinstance(tail_pad_override, int) and tail_pad_override >= 0
-                    else int(fps * 1.5)
+                    else default_tail_pad
                 )
                 min_dur = int(fps * 2)     # minimum 2 seconds per scene
                 # 用户在 DSL 里指定的 scene 下限（minDurationSec → minDurationFrames），
@@ -2480,6 +2531,10 @@ Examples:
         # conv_Sesw2g8oM81 的表现就是 scenes[0..19].customPayload.slide (required)）。
         _hydrate_dsl_payload(dsl, args.template_id, args.source_document_url)
 
+        # compose 模式模板：agent 只写了画面主体，这里拼上模板画风（旁白此刻已定稿）。
+        # --job-id / --render-plan 不走这里：计划已落库，不再改 prompt。
+        _compose_image_prompts(dsl, args.template_id)
+
         errors = validate_dsl(dsl)
         if errors:
             LogPrint("❌ DSL validation failed:", file=sys.stderr)

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

@@ -1132,6 +1132,77 @@ def _check_narration_language_strict(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+_TEXT_LAYER_SKELETON_PREFIXES = ("[骨架待填充]", "[skeleton placeholder]")
+
+
+def _check_text_layer_rules(dsl: dict) -> list[ValidationError]:
+    """模板声明 ``capabilities.textLayerRules`` 时，逐场景检查画面文字层。
+
+    声明形状::
+
+        "textLayerRules": {
+          "required": ["headline", "subheadline"],          # 每个场景都必须有且非空
+          "language": {"headline": "en", "subheadline": "zh"}  # en = 不含中文；zh = 须含中文
+        }
+
+    为什么是 error 而不是 llmHint：2026-09-24 线上《狼来了》绘本整本没有一行中文译文，
+    封面把中英文都塞进了 headline —— llmHint 写得清清楚楚，模型没照做，而当时没有
+    任何一道门拦它，成片照出，书页上留着一大块给译文的空白。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    rules = (tpl.get("capabilities") or {}).get("textLayerRules")
+    if not isinstance(rules, dict):
+        return []
+    required = [r for r in (rules.get("required") or []) if isinstance(r, str)]
+    language = rules.get("language") if isinstance(rules.get("language"), dict) else {}
+    tid = tpl.get("templateId", "<unknown>")
+
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"#{idx}")
+        layers: dict[str, tuple[int, str]] = {}
+        for li, layer in enumerate(scene.get("textLayers") or []):
+            if not isinstance(layer, dict):
+                continue
+            role = layer.get("role")
+            content = layer.get("content")
+            if isinstance(role, str) and role not in layers:
+                layers[role] = (li, content.strip() if isinstance(content, str) else "")
+
+        for role in required:
+            li, content = layers.get(role, (None, ""))
+            path = f"scenes[{idx}].textLayers" + (f"[{li}].content" if li is not None else "")
+            if not content:
+                errors.append(ValidationError(
+                    path,
+                    f"scene '{sid}': template '{tid}' requires a non-empty textLayers role '{role}'"
+                    + (f" (language: {language[role]})" if role in language else ""),
+                ))
+            elif content.startswith(_TEXT_LAYER_SKELETON_PREFIXES):
+                errors.append(ValidationError(
+                    path, f"scene '{sid}': textLayers role '{role}' is still the gen_script placeholder",
+                ))
+
+        for role, lang in language.items():
+            li, content = layers.get(role, (None, ""))
+            if li is None or not content or content.startswith(_TEXT_LAYER_SKELETON_PREFIXES):
+                continue
+            path = f"scenes[{idx}].textLayers[{li}].content"
+            if lang == "en" and _contains_cjk(content):
+                others = [r for r, l in language.items() if l == "zh"]
+                hint = f"; put the Chinese in role '{others[0]}'" if others else ""
+                errors.append(ValidationError(
+                    path, f"scene '{sid}': role '{role}' must be English only (no CJK characters){hint}",
+                ))
+            elif lang == "zh" and not _contains_cjk(content):
+                errors.append(ValidationError(
+                    path, f"scene '{sid}': role '{role}' must be Chinese (the translation of this page)",
+                ))
+    return errors
+
+
 # ════════════════════════════════════════════════════════════════════════════
 # Aggregator presets
 # ════════════════════════════════════════════════════════════════════════════
@@ -1188,6 +1259,7 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     # 是**渲得出来但错位**,只有在真要渲之前说才来得及。
     errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
+    errors += _check_text_layer_rules(dsl)
     return errors
 
 
@@ -1222,4 +1294,5 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_line_sync_narration(dsl)
     errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
+    errors += _check_text_layer_rules(dsl)
     return errors

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

@@ -4,6 +4,9 @@
 纯函数模块，无外部依赖。主要入口:
   - build_enhanced_prompt()  : 根据 purpose/topic/style/narration/styleGuide 构建增强 prompt
   - enrich_asset_payload()   : 一站式入口，自动判断并增强 asset payload
+  - compose_image_payload()  : imageStyleGuide.mode == "compose" 的模板专用 —— agent 只写
+                               画面主体，这里在旁白定稿后确定地、只一次地套上模板画风
+                               （见 docs/picture-book-image-prompt-design.md）
 """
 
 import re
@@ -39,19 +42,54 @@ DEFAULT_PURPOSE_PATTERNS: dict[str, str] = {
 # prompt 长度阈值：超过此字符数的 prompt 视为已精心编写
 WELL_CRAFTED_THRESHOLD = 80
 
+# gen_script 骨架占位的前缀。旁白与 compose 模式的图片主体共用这一组：以它开头说明
+# agent 还没把内容填进来。gen_script 从这里导入，两边不各写一份。
+SKELETON_PREFIXES = ("[骨架待填充]", "[skeleton placeholder]")
+
+# compose 模式下 gen_script 写进 payload.prompt 的占位：告诉 agent 这里只填「画什么」。
+COMPOSE_SUBJECT_PLACEHOLDER = (
+    f"{SKELETON_PREFIXES[0]} 本页画面主体：谁、在哪、在做什么、什么表情、什么光线"
+)
+
+# compose 模式下，模板没给本 purpose 写 promptTemplate 时的兜底
+COMPOSE_DEFAULT_TEMPLATE = "{subject}。{character_sheet}"
+
+_CJK_CHAR = re.compile(r"[\u4e00-\u9fff\u3400-\u4dbf]")
+
 # ---------------------------------------------------------------------------
 # 工具函数
 # ---------------------------------------------------------------------------
 
 
+def _is_mostly_latin(text: str) -> bool:
+    """CJK 字符占非空白字符不足 10% —— 按英文等拼音文字处理。"""
+    chars = [c for c in text if not c.isspace()]
+    if not chars:
+        return False
+    return sum(1 for c in chars if _CJK_CHAR.match(c)) / len(chars) < 0.1
+
+
 def summarize_narration(text: str, max_chars: int = 60) -> str:
     """从旁白文本提取视觉关键信息，去除口语化填充词。
 
+    英文旁白不套中文填充词正则（"了""的话"之类对英文无意义，反而可能误删），
+    按单词边界截断，上限放宽到 200 字符 —— 60 字符的英文常常只剩半句。
+
     >>> summarize_narration("那么接下来我们来看一下AI如何帮你高效背单词")
     'AI如何帮你高效背单词'
+    >>> summarize_narration("A tiny seed slept in the warm, dark soil.")
+    'A tiny seed slept in the warm, dark soil'
     """
     if not text:
         return ""
+    if _is_mostly_latin(text):
+        limit = max(max_chars, 200)
+        cleaned = _PUNCT.sub(" ", text).strip().rstrip(".!?;:,")
+        if len(cleaned) > limit:
+            cut = cleaned[:limit]
+            space = cut.rfind(" ")
+            cleaned = (cut[:space] if space > 0 else cut).rstrip(".!?;:,")
+        return cleaned or text[:limit]
     # 去除填充词
     cleaned = _FILLER_PATTERNS.sub("", text)
     # 归一化标点 → 空格
@@ -69,7 +107,7 @@ def extract_scene_context(scene: dict) -> dict:
     """从 DSL scene 提取视觉相关上下文。
 
     Returns:
-        dict with keys: narration_text, title, badge, purpose
+        dict with keys: narration_text, title, badge, headline, subheadline, purpose
     """
     purpose = scene.get("purpose", "default")
     narration_text = ""
@@ -78,19 +116,19 @@ def extract_scene_context(scene: dict) -> dict:
     if isinstance(narration, dict):
         narration_text = narration.get("text", "")
 
-    title = ""
-    badge = ""
-    for layer in scene.get("textLayers", []):
+    layers_by_role: dict[str, str] = {}
+    for layer in scene.get("textLayers", []) or []:
         role = layer.get("role", "")
-        if role == "title" and not title:
-            title = layer.get("content", "")
-        elif role == "badge" and not badge:
-            badge = layer.get("content", "")
+        content = layer.get("content", "")
+        if role and isinstance(content, str) and role not in layers_by_role:
+            layers_by_role[role] = content
 
     return {
-        "narration_text": narration_text,
-        "title": title,
-        "badge": badge,
+        "narration_text": narration_text or "",
+        "title": layers_by_role.get("title", ""),
+        "badge": layers_by_role.get("badge", ""),
+        "headline": layers_by_role.get("headline", ""),
+        "subheadline": layers_by_role.get("subheadline", ""),
         "purpose": purpose,
     }
 
@@ -170,7 +208,7 @@ def build_enhanced_prompt(
         )
 
     # 格式化模板（安全替换）
-    prompt = _safe_format(prompt_template, vars_)
+    prompt = _tidy_punctuation(_safe_format(prompt_template, vars_))
 
     # 追加 styleModifier
     style_modifier = override.get("styleModifier", "")
@@ -213,6 +251,38 @@ def _safe_format(template: str, vars_: dict) -> str:
         return result
 
 
+_EMPTY_BRACKETS = re.compile(r"[（(]\s*[）)]")
+_PUNCT_BEFORE_CLOSE = re.compile(r"[，。、；,;.\s]+(?=[）)])")
+# 两个及以上相邻的分隔标点（中间可夹空白）：空变量替换后留下的「，，」「。，」「, 。」等
+_PUNCT_RUN = re.compile(r"[，。、；,;.]\s*(?:[，。、；,;.]\s*)+")
+_LEADING_PUNCT = re.compile(r"^[\s，。、；,;.]+")
+_TRAILING_SOFT_PUNCT = re.compile(r"[\s，、；,;]+$")
+_MULTI_SPACE = re.compile(r"[ \t]{2,}")
+
+
+def _collapse_punct_run(match: "re.Match[str]") -> str:
+    run = match.group(0)
+    return "。" if ("。" in run or "." in run) else "，"
+
+
+def _tidy_punctuation(text: str) -> str:
+    """清理模板变量为空时留下的标点噪声。
+
+    ``{style_suffix}`` / ``{character_sheet}`` 这类变量常为空，替换后会留下
+    「，，」「。。」「（）」和行首孤立的逗号。连续分隔符合并成一个（含句号就留句号），
+    去掉空括号、行首标点、行尾逗号，多余空格压成一个。单词间的单个空格不动。
+    """
+    if not text:
+        return ""
+    out = _PUNCT_BEFORE_CLOSE.sub("", text)
+    out = _EMPTY_BRACKETS.sub("", out)
+    out = _PUNCT_RUN.sub(_collapse_punct_run, out)
+    out = _MULTI_SPACE.sub(" ", out)
+    out = _LEADING_PUNCT.sub("", out)
+    out = _TRAILING_SOFT_PUNCT.sub("", out)
+    return out.strip()
+
+
 # ---------------------------------------------------------------------------
 # 一站式入口
 # ---------------------------------------------------------------------------
@@ -272,3 +342,152 @@ def enrich_asset_payload(
         payload["guidanceScale"] = enhanced["guidanceScale"]
 
     return payload
+
+
+# ---------------------------------------------------------------------------
+# compose 模式：agent 写「画什么」，模板管「怎么画」
+# ---------------------------------------------------------------------------
+
+
+def is_compose_mode(style_guide: Optional[dict]) -> bool:
+    return bool(style_guide) and style_guide.get("mode") == "compose"
+
+
+def _style_guide_stamp(template: dict) -> str:
+    return f"{template.get('templateId', '')}@{template.get('version', '')}"
+
+
+def _is_placeholder_subject(text: str) -> bool:
+    return not text or text.startswith(SKELETON_PREFIXES)
+
+
+def compose_image_payload(
+    payload: dict,
+    scene: Optional[dict],
+    template: Optional[dict],
+    dsl_meta: Optional[dict] = None,
+    variant_id: str = "",
+) -> dict:
+    """把模板的 imageStyleGuide 套到一个 gen-image 素材的 payload 上（compose 模式专用）。
+
+    ``payload.prompt`` 在 compose 模式下的语义是**画面主体**（这一页画什么），不含画风。
+    这里拼出最终 prompt = promptTemplate(主体 / 角色设定 / 文字层…) + styleModifier +
+    baseStyle + colorDirective，并补上 negativePrompt / ratio / guidanceScale / seed。
+
+    - 非 compose 模板：原样返回（不改变 legacy 模板的行为）。
+    - 幂等：``styleGuideApplied`` 等于当前模板版本时原样返回；版本变了则从
+      ``promptSubject``（上次 compose 前的主体）重新拼，画风不会叠两遍。
+    - 主体为空或仍是骨架占位时退回本场景的旁白全文 / 文字层。
+
+    返回新 dict，不修改入参。
+    """
+    guide = resolve_style_guide(template, variant_id)
+    if not is_compose_mode(guide):
+        return payload
+    stamp = _style_guide_stamp(template or {})
+    if payload.get("styleGuideApplied") == stamp:
+        return payload
+
+    meta = dsl_meta or {}
+    ctx = extract_scene_context(scene) if scene else {}
+    purpose = ctx.get("purpose") or "point"
+
+    # 上次 compose 过（模板升版后重跑）→ 主体在 promptSubject 里，prompt 已是成品
+    subject = str(payload.get("promptSubject") or payload.get("prompt") or "").strip()
+    if _is_placeholder_subject(subject):
+        subject = (
+            ctx.get("narration_text", "").strip()
+            or ctx.get("subheadline", "").strip()
+            or ctx.get("headline", "").strip()
+        )
+        if _is_placeholder_subject(subject):
+            subject = str(meta.get("topic") or meta.get("title") or "").strip()
+
+    style = meta.get("style", "")
+    vars_ = {
+        "subject": subject,
+        "scene_text": ctx.get("narration_text", ""),
+        "scene_headline": ctx.get("headline", ""),
+        "scene_subheadline": ctx.get("subheadline", ""),
+        "scene_title": ctx.get("title", "") or ctx.get("headline", ""),
+        "character_sheet": str(meta.get("characterSheet") or "").strip(),
+        "topic": str(meta.get("topic") or meta.get("title") or ""),
+        "style_suffix": f"{style}风格" if style else "",
+        # 旧变量名兼容：legacy promptTemplate 里写的 {narration_summary} 在这里就是主体
+        "narration_summary": subject,
+    }
+
+    overrides = guide.get("purposeOverrides", {}) or {}
+    override = overrides.get(purpose) or {}
+    parts = [
+        # 没有针对本 purpose 的模板（如 cta / ending）时角色设定照样注入 —— 否则恰好
+        # 这一页的主角会换个样子。
+        _safe_format(override.get("promptTemplate") or COMPOSE_DEFAULT_TEMPLATE, vars_),
+        override.get("styleModifier", ""),
+        guide.get("baseStyle", ""),
+        guide.get("colorDirective", ""),
+    ]
+    prompt = _tidy_punctuation("，".join(p.strip() for p in parts if p and p.strip()))
+
+    out = dict(payload)
+    out["prompt"] = prompt
+    out["promptSubject"] = subject
+    if not out.get("negativePrompt"):
+        out["negativePrompt"] = override.get("negativePrompt") or guide.get("negativePrompt")
+    if guide.get("ratio"):
+        out["ratio"] = guide["ratio"]
+    if out.get("guidanceScale") is None and guide.get("guidanceScale") is not None:
+        out["guidanceScale"] = guide["guidanceScale"]
+    if out.get("seed") is None and guide.get("seed") is not None:
+        out["seed"] = guide["seed"]
+    out["styleGuideApplied"] = stamp
+    return {k: v for k, v in out.items() if v not in (None, "")}
+
+
+def _scene_refs(node, asset_id: str) -> bool:
+    if isinstance(node, dict):
+        return any(
+            (k == "assetRef" and v == asset_id) or _scene_refs(v, asset_id)
+            for k, v in node.items()
+        )
+    if isinstance(node, list):
+        return any(_scene_refs(v, asset_id) for v in node)
+    return False
+
+
+def compose_dsl_image_prompts(dsl: dict, template: Optional[dict]) -> list[str]:
+    """对整份 DSL 里待生成的图片素材逐个 compose（就地改 dsl），返回日志行。
+
+    只处理 ``type=image, source=gen-image, status∈{planned, missing}``；已生成 / 自带的图
+    不动。非 compose 模板是零成本 no-op（返回空列表）。
+    """
+    meta = dsl.get("meta") or {}
+    variant_id = str(meta.get("variantId") or "")
+    if not is_compose_mode(resolve_style_guide(template, variant_id)):
+        return []
+
+    scenes = dsl.get("scenes") or []
+    logs: list[str] = []
+    if not str(meta.get("characterSheet") or "").strip():
+        logs.append(
+            "⚠️  meta.characterSheet is empty — every image is generated independently, "
+            "so the main character may look different on each page"
+        )
+    for asset in dsl.get("assets") or []:
+        if not isinstance(asset, dict):
+            continue
+        if asset.get("type") != "image" or asset.get("source") != "gen-image":
+            continue
+        if asset.get("status", "planned") not in ("planned", "missing"):
+            continue
+        asset_id = asset.get("assetId", "")
+        scene = next((s for s in scenes if _scene_refs(s, asset_id)), None)
+        before = asset.get("payload") or {}
+        after = compose_image_payload(before, scene, template, meta, variant_id)
+        if after is before:
+            continue
+        asset["payload"] = after
+        subject = after.get("promptSubject", "")
+        short = subject if len(subject) <= 60 else subject[:60] + "…"
+        logs.append(f"🎨 {asset_id} composed (subject: {short})")
+    return logs

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

@@ -19,13 +19,23 @@ from typing import Optional
 
 CHARS_PER_SECOND = 5.0
 
-_PRIMARY_BREAK = re.compile(r"(?<=[。！？；\n])")
+# 英文句末：`.!?`（可跟一个收尾引号/括号）且后面是空白。以前只认中文标点，英文旁白
+# 从来不在句号处断，只能落到逗号 / 30 字空格硬切，切出 `went home. A few days later,`
+# 这种跨句的行，所有段的 sentenceIndex 也全是 0。常见缩写后的句点不算句末。
+_EN_SENTENCE_END = (
+    r"(?:(?<=[.!?])|(?<=[.!?][\"'\u201d\u2019)]))"
+    r"(?<!\bMr\.)(?<!\bMs\.)(?<!\bDr\.)(?<!\bSt\.)(?<!\bMrs\.)(?<!\be\.g\.)(?<!\bi\.e\.)(?<!\bvs\.)"
+    r"(?=\s)"
+)
+_PRIMARY_BREAK = re.compile(r"(?<=[。！？；\n])|" + _EN_SENTENCE_END)
 # 次级断点**不含顿号 `、`**。顿号是并列项之间的分隔，在它上面下刀就是把一串并列
 # 拦腰切开（`调研、策划、` ／ `开发、分析，…`）。这一层只数字符、分不出标点的语义
 # 强度，所以干脆不碰它 —— 真需要再切时交给渲染端，那边是分级的（句末 > 冒号 >
 # 逗号 > 顿号 > 空格），只有前面几级都切不动才会降到顿号。
 _SECONDARY_BREAK = re.compile(r"(?<=[，,：:])")
-_PRIMARY_TAIL = re.compile(r"[。！？；\n]\s*$")
+_PRIMARY_TAIL = re.compile(
+    r"(?:[。！？；\n]|(?<!\bMr)(?<!\bMs)(?<!\bDr)(?<!\bSt)(?<!\bMrs)(?<!\bvs)[.!?][\"'\u201d\u2019)]?)\s*$"
+)
 
 # ─── 这两个上限管的是「喂给 TTS 的行」，不再是「一屏字幕」 ────────────────
 #