@remixmate/cli 0.9.45 → 0.9.47

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.45",
-  "generatedAt": "2026-09-23T05:34:40.922Z",
+  "version": "0.9.47",
+  "generatedAt": "2026-09-24T01:36:07.207Z",
   "skills": [
     {
       "id": "doc-parse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.45",
+  "version": "0.9.47",
   "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,8 @@
     "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"
   },
   "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))
@@ -328,7 +334,11 @@ def plan_scenes(
     opening_duration = max(3, round(duration * 0.12))
     ending_duration = max(3, round(duration * 0.12))
     content_total = duration - opening_duration - ending_duration
-    per_content = max(3, round(content_total / content_scenes))
+    # 余数摊到前几段，保证各段加总正好等于 duration。以前是 round(均值) × 段数：
+    # 2026-09-23 线上 ppt-to-video 传 --duration 600 --scenes 23，21 段 × round(21.7)=22
+    # 加总 606s，撞上模板 supportedDurations.max=600 被自己的时长门禁拒掉。
+    # 每段仍有 3s 下限 —— 段数多到摊不开时加总会超出，那是真超出，交给门禁报。
+    base_content, extra_content = divmod(max(content_total, 0), content_scenes)
 
     scenes.append({
         "purpose": "opening",
@@ -339,7 +349,7 @@ def plan_scenes(
     for i in range(content_scenes):
         scenes.append({
             "purpose": "point",
-            "duration": per_content,
+            "duration": max(3, base_content + (1 if i < extra_content else 0)),
             "label": _localize_label(language, "label_point", n=i + 1),
         })
 
@@ -373,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(
@@ -617,6 +627,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "payload_defaults": payload_defaults,
         "primary_visual_type": primary_visual_type,
         "default_layout": caps.get("defaultLayout"),
+        "authored_scenes": caps.get("authoredScenes") is True,
     }
 
 
@@ -791,6 +802,16 @@ def _plan_contract_scenes(
 
     fixed = contract["fixed_scenes"] or [{"purpose": "opening"}]
     n = len(fixed)
+    # 非 arc 策略的场景数由模板钉死，--scenes 不生效 —— 但必须出声。2026-09-23 线上
+    # screen-walkthrough 传 --scenes 6 拿回 2 场，没有任何提示，模型只能自己猜为什么。
+    if scene_count is not None and scene_count != n:
+        print(
+            f"⚠️  requested {scene_count} scene(s) but this template's sceneStrategy="
+            f"{contract['scene_strategy']} always plans {n}: --scenes is ignored here.\n"
+            f"   The DSL below has {n} scenes — read the count back from it before showing "
+            f"the script to the user.",
+            file=sys.stderr,
+        )
     per = max(1, round(duration / n))
     plans = []
     for i, fs in enumerate(fixed):
@@ -1441,6 +1462,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-
@@ -1480,7 +1508,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**：那两项是模板的护栏（"不要文字水印、不要变形"），把它们
@@ -1492,7 +1526,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"]
@@ -1687,6 +1721,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,
@@ -1709,6 +1745,20 @@ def build_dsl(
 
     _record_source_document(dsl, template_config, template_id, source_document_url)
 
+    if contract["authored_scenes"]:
+        # 场景表由调用方按用户素材编写（如按操作时间点切录屏），骨架只提供 meta/global。
+        # 这个标记必须由骨架携带：ab-agent 看到它才会整份采用模型提交的 DSL，
+        # 否则它以骨架为基底合并，新增场景、existing 素材、visuals 都会被静默丢掉。
+        dsl["meta"]["authoredScenes"] = True
+        print(
+            f"ℹ️  template '{template_id}' declares capabilities.authoredScenes: the scene list below "
+            f"is only a placeholder.\n"
+            f"   Write the full DSL yourself from the user's material (scenes, assets, visuals, "
+            f"customPayload) and submit all of it to prepare_video_assets — it is used as-is, "
+            f"not merged onto this skeleton. Keep meta.templateId.",
+            file=sys.stderr,
+        )
+
     _enforce_supported_duration(dsl, template_config, template_id)
 
     return dsl

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

@@ -110,7 +110,10 @@ def _rebalance_subtitle_segments(segs: list[dict]) -> list[dict]:
         for p in parts:
             ratio = len(p) / total_chars
             frames = max(int(total_frames * ratio), 1)
+            # `**seg` 而不是只写三个键：切出来的各部分仍属于**同一句**，
+            # 所以 sentenceIndex 等字段要原样继承（见 build_render_plan 处的说明）。
             expanded.append({
+                **seg,
                 "text": _strip_subtitle_trailing_punct(p.strip()),
                 "startFrame": cur_frame,
                 "endFrame": cur_frame + frames,
@@ -550,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:
     """动作条数与旁白句数不等时出声。
 
@@ -848,9 +871,13 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
             local_subs = split_subtitle_from_lines(lines, duration_frames, fps)
         else:
             local_subs = split_subtitle(narration_text, duration_frames, fps)
+        # ⚠️ 平移帧号时**必须保留原有字段**（`**s`），不要只挑三个键重建。
+        # 这里曾经只搬 text/startFrame/endFrame，于是 timeline_compiler 给每段打上的
+        # `sentenceIndex`（模板用它把动作对齐到**句**而不是段）在这一步被静默丢掉 ——
+        # 下游模板拿不到句边界，只能退回按段对齐，也就是那个错位 bug 本身。
         subtitle_segments = [
             {
-                "text": s["text"],
+                **s,
                 "startFrame": s["startFrame"] + current_frame,
                 "endFrame": s["endFrame"] + current_frame,
             }
@@ -961,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])
 
@@ -1519,6 +1553,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             # 起点为终点。
                             end_f = scene_dur if i == len(old_subs) - 1 else starts[i + 1]
                             new_subs.append({
+                                **s,
                                 "text": text,
                                 "startFrame": current_frame + start_f,
                                 "endFrame": current_frame + end_f,
@@ -1538,6 +1573,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             ratio = _plain(text) / total_chars
                             seg_frames = max(int(sub_span * ratio), fps // 2)
                             new_subs.append({
+                                **s,
                                 "text": text,
                                 "startFrame": current_frame + cursor,
                                 "endFrame": current_frame + cursor + seg_frames,
@@ -1560,7 +1596,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                         rel_start = s["startFrame"] - old_scene_start
                         rel_end = s["endFrame"] - old_scene_start
                         new_subs.append({
-                            "text": s["text"],
+                            **s,
                             "startFrame": current_frame + rel_start,
                             "endFrame": current_frame + rel_end,
                         })
@@ -2471,6 +2507,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/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V27",
+  "version": "V28",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

package/skills/template-registry/scripts/payload_hydrator.py

@@ -56,6 +56,44 @@ SUPPORTED_SOURCES = ("doc-extract",)
 DEFAULT_INDEX_FIELD = "slideIndex"
 
 
+def declared_subfields(template_config: Optional[dict], payload_field: str) -> Optional[set[str]]:
+    """模板为 ``customPayload.<payload_field>`` 声明的子字段名集合。
+
+    注入必须按这个集合**投影**，不能把抽取器返回的整个对象原样塞进去 ——
+    两边的字段集根本不是一回事：
+
+      抽取器返回(每页)  slideIndex / title / text / rawNotes / verdict / coverage /
+                        flags / nodes / beats / mode / modeReason / ambientIds /
+                        background / recommendedSec / canvas …
+      模板声明(slide)    nodes / beats / mode / modeReason / ambientIds /
+                        background / recommendedSec / canvas
+
+    前者多出来的那些是**内容层与抽取器自己的记账字段**（备注原文、质检结论、覆盖率），
+    渲染端一个都不读。而 ``dsl_validator._check_custom_payload_fields`` 会逐字段核对
+    声明表，遇到没声明的就报「the slide does not read 'x' — the value is silently
+    dropped」并整单拒绝。2026-09-23 线上 conv_StrnauS7TaZNUQV4BfLX 就是这样：
+    注入明明成功（23/23 页），却因为多了 5 个字段被校验整单拒掉，而且**重试必然复现**。
+
+    为什么用投影而不是写个黑名单：抽取器以后再加字段（verdict / coverage 就是后加的）
+    黑名单就会再漏一次。声明表是渲染端真正读的那一份，按它投影才不会二次失效。
+
+    声明表读不到时返回 None = 不投影。这与校验层的行为一致：没有
+    ``customPayloadSchema`` 时它也不查字段名，所以不投影不会引入新的失败。
+    """
+    if not template_config:
+        return None
+    cps = template_config.get("customPayloadSchema")
+    if not isinstance(cps, dict):
+        return None
+    node = cps.get(payload_field)
+    if not isinstance(node, dict):
+        return None
+    props = node.get("properties")
+    if not isinstance(props, dict) or not props:
+        return None
+    return set(props.keys())
+
+
 class HydrationError(RuntimeError):
     """注入失败。message 必须直接告诉调用方下一步做什么。
 
@@ -206,6 +244,18 @@ def hydrate_dsl(
     filled = 0
     missing: list[str] = []
 
+    # 按模板声明投影。抽取结果里混着内容层与抽取器记账字段，渲染端一个都不读，
+    # 而校验层见到未声明字段会整单拒绝（见 declared_subfields 的说明）。
+    allowed = declared_subfields(template_config, field)
+    dropped: set[str] = set()
+
+    # 页号只有在模板**声明**了它的时候才写回去。没声明就是未知字段，写了会被校验
+    # 拒掉 —— 这正是上一版的第二个错：既投影不足，又多写了一个 customPayload.slideIndex。
+    index_is_declared = index_field in (declared_subfields(template_config, index_field) or ())
+    if not index_is_declared:
+        cps = (template_config or {}).get("customPayloadSchema")
+        index_is_declared = isinstance(cps, dict) and index_field in cps
+
     for position, scene in enumerate(scenes, start=1):
         payload = _scene_payload(scene)
         if payload.get(field) is not None:
@@ -216,9 +266,14 @@ def hydrate_dsl(
         if page is None:
             missing.append(f"scene {scene.get('id', position)} → page {page_no}")
             continue
-        payload[field] = page
-        # 把页号写回去，让 RenderPlan 里留下"这一场用的是第几页"的痕迹。
-        payload.setdefault(index_field, page_no)
+        if allowed is None:
+            payload[field] = page
+        else:
+            dropped |= {k for k in page if k not in allowed}
+            payload[field] = {k: v for k, v in page.items() if k in allowed}
+        # 留下"这一场用的是第几页"的痕迹 —— 仅当模板声明了这个字段。
+        if index_is_declared:
+            payload.setdefault(index_field, page_no)
         filled += 1
 
     source_meta = result.get("source") or {}
@@ -227,6 +282,13 @@ def hydrate_dsl(
         f"{source_meta.get('slideCount', len(pages))} page(s) of "
         f"{source_meta.get('name', 'the source document')}"
     )
+    if dropped:
+        # 说清丢了什么：这些是内容层/记账字段，渲染端本来就不读。写出来是为了
+        # 抽取器哪天把一个**该读**的字段也归到这里时，有人看得见。
+        report.append(
+            f"   （已按模板声明投影，忽略 {len(dropped)} 个渲染端不读的字段："
+            f"{', '.join(sorted(dropped)[:8])}）"
+        )
 
     if missing:
         # 页号对不上不是警告而是错误：少一页 = 成片里一个空白场景，而它渲得出来。

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V20",
+  "version": "V21",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

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