@remixmate/cli 0.9.50 → 0.9.52

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

@@ -32,10 +32,27 @@ List vs. detail (why ``--json-output`` no longer dumps everything):
   programmatic callers, guarded by a size check so it can't silently recreate
   the overflow.
 
+Slide menu (why --template-id no longer returns every slideSchemas body):
+  slideSchemas is two thirds of a multi-layout template (html-slide: 24.6 K of
+  37.2 K chars, 26 layouts), while one video uses 5–9 layouts. Returning all of
+  it every time pushed the detail view past the agent's tool-result size cap
+  (the result got spilled to a file the agent cannot open, so it re-called
+  with other flags), and the agent re-read the whole thing on the next turn
+  anyway. So detail mode returns a per-layout *menu* — description, field
+  names, list key / item fields / maxItems, and whether narration must be
+  split into items — which is enough to choose layouts and draft a script;
+  ``--slide-id`` then returns the exact schemas of the chosen layouts for
+  writing ``templateData``. Registry consumers inside the pipeline (validator,
+  render) read the registry directly and are unaffected.
+
 Flags:
   --list-templates                 (accepted; listing is the default verb)
   --template-id <id>               print the FULL definition of this template
-                                   (repeatable); this is the detail verb
+                                   (repeatable); this is the detail verb.
+                                   Multi-layout templates come back with a
+                                   slideSchemas *menu* (see "Slide menu" below)
+  --slide-id <slideId|all>         detail mode: expand these layouts' full
+                                   templateData schemas (repeatable)
   --full                           in list mode, emit full definitions instead
                                    of summaries (size-guarded; prefer
                                    --template-id)
@@ -159,6 +176,96 @@ def _detail_hint(template_id: str = "<templateId>") -> str:
     )
 
 
+# ----- Slide menu (--template-id without --slide-id) -------------------------
+
+_SLIDE_EXPAND_ALL = "all"
+
+
+def _slide_schema_ids(tpl: dict) -> list[str]:
+    ss = tpl.get("slideSchemas")
+    if not isinstance(ss, dict):
+        return []
+    return [k for k, v in ss.items() if not k.startswith("_") and isinstance(v, dict)]
+
+
+def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
+    """One layout's menu row: enough to pick it and draft a script, not to fill it."""
+    props = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
+    entry: dict = {}
+    if schema.get("description"):
+        entry["description"] = schema["description"]
+    entry["fields"] = list(props.keys())
+    if schema.get("required"):
+        entry["required"] = schema["required"]
+    # The card list: the line-sync key when declared, else the first array of objects.
+    list_key = line_sync_key if line_sync_key in props else None
+    if list_key is None:
+        for k, v in props.items():
+            if isinstance(v, dict) and v.get("type") == "array" and isinstance(v.get("items"), dict) \
+                    and v["items"].get("type") == "object":
+                list_key = k
+                break
+    if list_key is not None:
+        arr = props[list_key]
+        item = arr.get("items") if isinstance(arr.get("items"), dict) else {}
+        item_props = item.get("properties") if isinstance(item.get("properties"), dict) else {}
+        lst = {"key": list_key, "itemFields": list(item_props.keys())}
+        if item.get("required"):
+            lst["itemRequired"] = item["required"]
+        if "maxItems" in arr:
+            lst["maxItems"] = arr["maxItems"]
+        entry["list"] = lst
+    if line_sync_key:
+        # The single most expensive miss in practice: authoring one narration
+        # block for a layout that lights cards one by one (validator rejects it).
+        entry["narration"] = (
+            f"items — one audio.narration.items line per templateData.{line_sync_key} entry, no text"
+        )
+        static = [k for k, v in props.items() if isinstance(v, dict) and v.get("x-staticHighlight")]
+        if static:
+            entry["narrationStaticAlternative"] = f"set templateData.{static[0]} to keep it static instead"
+    return entry
+
+
+def _apply_slide_view(tpl: dict, slide_ids: list[str] | None) -> dict:
+    """Return tpl with slideSchemas reduced to a menu, or to the requested layouts."""
+    ss = tpl.get("slideSchemas")
+    if not isinstance(ss, dict):
+        return tpl
+    ids = _slide_schema_ids(tpl)
+    out = dict(tpl)
+    if slide_ids and _SLIDE_EXPAND_ALL in slide_ids:
+        out["slideSchemas"] = {k: v for k, v in ss.items() if k != "_comment"}
+        return out
+    line_sync = tpl.get("lineSyncSlides") if isinstance(tpl.get("lineSyncSlides"), dict) else {}
+    if slide_ids:
+        view: dict = {
+            "_view": (
+                f"Full templateData schemas for: {', '.join(slide_ids)}. Copy field names from here. "
+                "Other layouts are omitted — pass their ids in slide_id to read them."
+            ),
+        }
+        if isinstance(ss.get("_shared"), dict):
+            view["_shared"] = ss["_shared"]
+        for sid in slide_ids:
+            view[sid] = ss[sid]
+        out["slideSchemas"] = view
+        return out
+    menu: dict = {
+        "_view": (
+            "MENU ONLY — per-layout summary, not the full schema. Use it to choose layouts and draft the "
+            "script. Before writing templateData, call template_registry again with this template_id and "
+            "slide_id=<each chosen layout> (repeatable) to get their exact field schemas. "
+            "If you already did that earlier in this conversation, do not call it again."
+        ),
+    }
+    for sid in ids:
+        lk = line_sync.get(sid)
+        menu[sid] = _menu_entry(ss[sid], lk if isinstance(lk, str) else None)
+    out["slideSchemas"] = menu
+    return out
+
+
 # ----- Examples discovery (--list-examples) ---------------------------------
 #
 # Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
@@ -217,6 +324,9 @@ def main() -> None:
                     help="List every available template (summaries; the default verb).")
     ap.add_argument("--template-id", action="append", dest="template_ids", metavar="ID",
                     help="Print this template's FULL definition (repeatable).")
+    ap.add_argument("--slide-id", action="append", dest="slide_ids", metavar="SLIDE_ID",
+                    help="Detail mode: expand these layouts' full slideSchemas (repeatable; "
+                         "'all' = every layout). Without it multi-layout templates return a menu.")
     ap.add_argument("--full", action="store_true",
                     help="List mode: emit full definitions instead of summaries "
                          "(size-guarded; prefer --template-id).")
@@ -326,13 +436,28 @@ def main() -> None:
             known = ", ".join(sorted(str(t.get("templateId")) for t in templates))
             print(f"   Available ids: {known}", file=sys.stderr)
             sys.exit(1)
-        if args.json_output:
-            print(json.dumps({"templates": picked}, ensure_ascii=False))
-        else:
-            # Pretty-printed rather than tabular: the whole point of detail mode
-            # is the nested contract (customPayloadSchema / slotMapping), which
-            # a table cannot show.
-            print(json.dumps({"templates": picked}, ensure_ascii=False, indent=2))
+        if args.slide_ids:
+            wanted = [s for s in args.slide_ids if s != _SLIDE_EXPAND_ALL]
+            known_slides = {sid for t in picked for sid in _slide_schema_ids(t)}
+            if not known_slides:
+                print("⚠️  --slide-id ignored: this template has no slideSchemas (single layout).",
+                      file=sys.stderr)
+            else:
+                unknown = [s for s in wanted if s not in known_slides]
+                if unknown:
+                    print(f"❌ Unknown slide id(s): {', '.join(unknown)}", file=sys.stderr)
+                    print(f"   Legal slide ids: {', '.join(sorted(known_slides))}", file=sys.stderr)
+                    sys.exit(1)
+        picked = [
+            _apply_slide_view(t, [s for s in (args.slide_ids or []) if s in _slide_schema_ids(t)
+                                  or s == _SLIDE_EXPAND_ALL] or None)
+            for t in picked
+        ]
+        # Always compact, with or without --json-output. Every caller is an LLM
+        # tool call: indent=2 nearly doubled the size (html-slide 37 K → 65 K
+        # chars), which alone pushed the plain call past the tool-result cap and
+        # got it spilled to a file the agent cannot read. Humans can `| jq`.
+        print(json.dumps({"templates": picked}, ensure_ascii=False))
         return
 
     visible = [

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

@@ -22,9 +22,8 @@
   鉴权：只读 PRIV_TOKEN 环境变量。凭证库 / 钥匙串 / 设备授权流由 CLI 的 Node 侧
   唯一鉴权入口负责（src/auth/ensure.ts），并在 spawn 时注入本进程环境。
 
-  monorepo / 显式本地文件等其它来源已**移除**。需要离线 / pinned 数据的维护脚本
-  （check_contracts.py / sync_registry.py）直接走 template_paths 读 monorepo，
-  那是 monorepo-only 工具，不是运行时数据源。
+  monorepo / 显式本地文件等其它来源已**移除**。模板仓库自己的维护工具住在
+  template-library，不经过本模块。
 
 P1.2 — list/detail split (待后端就绪)：
   100+ 模板时 ``GET /api/template/list`` 应该只返摘要（id / name / aspects /
@@ -379,7 +378,7 @@ def load_registry_indexed(
     """Return registry as ``{templateId: template_dict}``.
 
     Filters by the process-wide status gate unless ``include_all_statuses``
-    is set (used by maintenance tooling like ``check_contracts``). Templates
+    is set (e.g. render-video reading an already-chosen template). Templates
     missing ``status`` are treated as ``stable`` for backwards compatibility.
 
     ``ttl_seconds`` / ``http_timeout`` are accepted for API symmetry with

package/skills/template-registry/skill.json

@@ -12,9 +12,9 @@
     "type": "object",
     "properties": {
       "list_templates": { "type": "boolean", "description": "List available templates as summaries — templateId / name / description / aspect ratios / language / status / styleTags / variantIds / key capabilities / a truncated llmHint (default behavior; also implied when other flags are passed)." },
-      "template_id": { "type": "string", "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template." },
+      "template_id": { "type": "string", "description": "Return this template's full authoring contract instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. Multi-layout templates return slideSchemas as a MENU (per layout: description, field names, card-list key / item fields / maxItems, and whether narration must be split into items) — enough to pick layouts and draft the script. Read it once per conversation; it does not change between turns." },
+      "slide_id": { "type": "array", "items": { "type": "string" }, "description": "With template_id: return the FULL templateData schema for these layouts (the slideIds you chose from the menu). Call this once, right before writing templateData, with every layout the script uses. 'all' returns every layout (large — avoid)." },
       "full": { "type": "boolean", "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters." },
-      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)." },
       "filter_tag": { "type": "string", "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'." },
       "filter_aspect": { "type": "string", "description": "Show only templates that declare this aspect ratio. E.g. '9:16' / '16:9' / '1:1'." },
       "filter_language": { "type": "string", "description": "Show only templates whose contentLanguage includes this code ('zh' or 'en'). Templates with no declared language are always shown (treated as language-agnostic)." },

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V22",
+  "version": "V24",
   "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/README.md

@@ -9,27 +9,17 @@ video_dsl/
 ├── schema/                    # DSL Schema 定义
 │   ├── video-dsl-v1alpha1.json          # Video DSL JSON Schema
 │   ├── template-binding-v1alpha1.json    # 模板绑定 Schema
-│   ├── render-plan-v1alpha1.json         # RenderPlan Schema
-│   └── examples/                         # 各模板的 DSL + Binding 示例
-│       ├── ai-learning-tips.dsl.json
-│       ├── ai-learning-tips.binding.json
-│       ├── html-slide-demo.dsl.json
-│       └── ...
-├── runtime/                   # DSL 运行时工具
-│   ├── dsl_validator.py       # DSL Schema 校验
-│   ├── template_binder.py     # Scene → Slot 绑定（从 @ab-templates/metadata 读取模板）
-│   ├── timeline_compiler.py   # 时间线编译（帧号、字幕切片、旁白分段）
-│   ├── asset_adapter.py       # 素材适配器
-│   └── prompt_enhancer.py     # Prompt 增强
-└── library/                   # 可复用组件库（预留）
-    ├── blocks/                # 功能块（如 CTA、数字人、全屏背景）
-    ├── components/            # 基础组件（音频、文本、背景、装饰）
-    ├── scenes/                # 场景模板（开场钩子、知识点、绘本页）
-    └── videos/                # 完整视频模板（英文绘本等）
+│   └── render-plan-v1alpha1.json         # RenderPlan Schema
+└── runtime/                   # DSL 运行时工具（通用机制，不认识任何具体模板）
+    ├── dsl_validator.py       # DSL 校验（读模板声明做契约检查）
+    ├── payload_contract.py    # customPayload 必填字段检查
+    ├── timeline_compiler.py   # 时间线编译（帧号、字幕切片、旁白分段）
+    └── prompt_enhancer.py     # Prompt 增强
 ```
 
-> **注意**：模板元数据（template.json / registry.json）已迁移至独立的 `template-library` 仓库，
-> 通过 `@ab-templates/metadata` 包发布。`template_binder.py` 直接读取该包产出的 `registry.json`。
+> **注意**：模板元数据（template.json / registry.json）住在独立的 `template-library` 仓库，
+> 运行时经 ab-api 下发，由 `scripts/registry_loader.py` 读取；DSL → TemplateBinding 在 `scripts/match_template.py`。
+> 逐模板的契约与写法只在各自的 `template.json` 里，本目录不列模板、不带模板示例。
 
 ## 核心概念
 
@@ -51,46 +41,13 @@ video_dsl/
                    [render-video] → RenderPlan → MP4 / 剪映草稿
 ```
 
-## 模板列表
-
-| 模板 ID | 名称 | 适用场景 |
-|---------|------|----------|
-| `image-slide` | 图片幻灯片 | 通用知识分享、产品介绍（含 tech 科技风变体） |
-| `picture-book-en` | 英文绘本视频 | 儿童英语启蒙、双语绘本故事 |
-| `image-slideshow` | 图片轮播视频 | 知识分享、种草笔记、技巧总结 |
-| `knowledge-slides` | 知识幻灯片 | 方法论拆解、教程讲解、知识科普 |
-| `html-slide` | 知识看板 | 知识科普、概念讲解、白板风格内容 |
-
 ## runtime 模块说明
 
 | 模块 | 职责 | 被谁调用 |
 |------|------|----------|
 | `dsl_validator.py` | DSL JSON Schema 校验与参数标准化 | gen-script、render-video |
-| `template_binder.py` | 将 DSL scene 映射到模板 slot，生成 TemplateBinding（从 @ab-templates/metadata 读取模板定义） | template-registry |
 | `timeline_compiler.py` | 帧号计算、字幕切片（`split_subtitle`）、旁白分段（`segment_narration`） | render-video（跨 skill import） |
-| `asset_adapter.py` | 素材格式适配 | render-video |
+| `payload_contract.py` | customPayload 必填字段 / 计划素材检查 | dsl_validator、render-video |
 | `prompt_enhancer.py` | 图片 prompt 增强 | render-video |
 
 **注意**：`timeline_compiler.py` 被 `render-video/scripts/render_video.py` 直接 import，修改函数签名需两个 skill 同步测试。
-
-## library 组件库（预留）
-
-`library/` 目录采用四层分级设计，用于存放可复用的 DSL 片段：
-
-- **components/**：最小粒度的基础组件（音频、文本、背景、头像、装饰、媒体、叠加层）
-- **blocks/**：由多个 component 组合而成的功能块（CTA 按钮、数字人区域、全屏背景图、标题区、产品卡片、配音条、双语字幕）
-- **scenes/**：完整的场景模板（开场钩子、知识点讲解、绘本封面/内页/结尾、CTA 结尾、数字人口播）
-- **videos/**：完整的视频模板（英文绘本等）
-
-组件库当前为目录骨架，后续可填充具体的 JSON 片段供 Agent 和 gen_script.py 复用。
-
-## 示例文件
-
-`schema/examples/` 下包含各模板的完整 DSL + Binding 示例，是 Agent 生成 DSL 时的权威参考：
-
-- `ai-learning-tips.*` — image-slide 模板示例
-- `html-slide-demo.*` — html-slide 模板示例
-- `knowledge-slides-demo.*` — knowledge-slides 模板示例
-- `animal-friends-picturebook.*` — picture-book-en 模板示例
-
-Agent 在为指定模板生成 DSL 时，必须先读取对应示例，按模板原生要求生成。

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

@@ -6,6 +6,5 @@ and gen-script). Public modules:
 
     - timeline_compiler  : DSL → Remotion frame-axis timeline + subtitle splits
     - prompt_enhancer    : LLM image-prompt enrichment used by gen-script
-    - template_binder    : registry summary writer (sync_registry helper)
     - dsl_validator      : DSL validation (structural / integrity / full presets)
 """

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

@@ -31,7 +31,7 @@ VALID_PURPOSES = {"opening", "intro", "point", "example", "explanation", "transi
 VALID_LAYOUTS = {"full-visual", "split-left-right", "split-top-bottom", "picture-in-picture", "text-overlay", "avatar-with-bg", "kenburns"}
 
 # 场景数上限的兜底值。叙事弧类模板的合理上界——20 段以上的短视频必然过碎。
-# "一页素材一个场景"的模板（ppt-to-video）场景数由源文件页数决定，应当用
+# "一页素材一个场景"的模板（capabilities.payloadHydration）场景数由源文件页数决定，应当用
 # ``capabilities.maxScenes`` 抬高；这个常量只是没声明时的默认。
 DEFAULT_MAX_SCENES = 20
 
@@ -61,21 +61,17 @@ def max_scenes_for_template(template_config: Optional[dict]) -> int:
 VALID_ASSET_TYPES = {"image", "video", "audio", "avatar", "subtitle", "bgm"}
 VALID_ASSET_SOURCES = {"existing", "gen-image", "gen-video", "gen-voice", "gen-digital-human"}
 
-# 由 Composition 消费、而非 slide 组件消费的字段。前八个与模板侧
-# utils/slidePayload.ts 的 FRAME_LEVEL_KEYS 同源 ——「整包态」binder 会把它们混进
-# templateData，出现在那里是正当的，不该被当成未声明字段。highlightMap 同理（模板
-# 一般在 slideSchemas._shared 里声明它，这里兜底没声明的情况）。
-_SLIDE_FRAME_LEVEL_KEYS = frozenset({
-    "slideId",
-    "titleText",
-    "subtitleText",
-    "watermarkText",
-    "narrationAssetId",
-    "narrationSrc",
-    "background",
-    "templateData",
-    "highlightMap",
-})
+def _frame_level_keys(tpl: dict) -> frozenset:
+    """模板声明的 frame 级字段（``capabilities.frameLevelKeys.keys``）。
+
+    这些字段由 Composition 消费、不属于任何 slide 载荷；「整包态」binder 会把它们
+    混进 templateData，出现在那里是正当的，不该被当成未声明字段。名单是模板的事实，
+    CLI 不保留副本 —— 没声明的模板就是空集。``highlightMap`` 这类跨版式字段走
+    ``slideSchemas._shared``，不在这里。
+    """
+    spec = (tpl.get("capabilities") or {}).get("frameLevelKeys")
+    keys = spec.get("keys") if isinstance(spec, dict) else None
+    return frozenset(k for k in keys if isinstance(k, str)) if isinstance(keys, list) else frozenset()
 
 # CJK 汉字范围（简繁通用）+ 常见中文标点
 _CJK_PATTERN = re.compile(r"[一-鿿㐀-䶿＀-￯　-〿]")
@@ -144,11 +140,32 @@ def _line_sync_slides_for_template(template_id: Optional[str]) -> dict[str, str]
     O(1) lookup via ``registry_loader.get_template``; safe to call once per
     scene at 100+ templates without scanning the full list.
     """
-    tpl = _get_template_cfg(template_id)
-    if not tpl:
-        return {}
-    spec = tpl.get("lineSyncSlides") or {}
-    return {k: v for k, v in spec.items() if isinstance(v, str)}
+    return line_sync_slides(_get_template_cfg(template_id))
+
+
+def line_sync_slides(tpl: Optional[dict]) -> dict[str, str]:
+    """模板的 ``lineSyncSlides`` 声明：slideId → templateData 里卡片数组的键。
+
+    校验层（narration.items 数对齐）与 render-video（自动 highlightMap 的上限裁剪）
+    读的是同一份声明，CLI 不保留任何卡片键表的副本。
+    """
+    spec = (tpl or {}).get("lineSyncSlides") or {}
+    return {k: v for k, v in spec.items() if not k.startswith("_") and isinstance(v, str)}
+
+
+def step_alignment_field(tpl: Optional[dict]) -> Optional[str]:
+    """模板 ``capabilities.stepAlignment`` 声明的动作数组字段；未声明返回 None。
+
+    只认 ``alignTo`` 缺省或 ``narration-sentences``（第 i 个动作 = 第 i 句旁白）。
+    """
+    caps = (tpl or {}).get("capabilities")
+    spec = caps.get("stepAlignment") if isinstance(caps, dict) else None
+    if not isinstance(spec, dict):
+        return None
+    if spec.get("alignTo") not in (None, "narration-sentences"):
+        return None
+    field = spec.get("payloadField")
+    return field if isinstance(field, str) and field else None
 
 
 def _get_template_cfg(template_id: Optional[str]) -> Optional[dict]:
@@ -280,7 +297,7 @@ def _check_scenes_max(dsl: dict) -> list[ValidationError]:
 
     上限由模板的 ``capabilities.maxScenes`` 声明,缺省 ``DEFAULT_MAX_SCENES``(20)。
     20 这个数字是给"叙事弧"类模板定的——一条 60 秒短视频排到 20 段已经过碎。但
-    "一页素材一个场景"的模板(ppt-to-video 逐页讲解)的场景数由源文件页数决定,
+    "一页素材一个场景"的模板(逐页讲解一份源文件)的场景数由源文件页数决定,
     跟叙事节奏无关:2026-09-23 线上一份 23 页 PPT 就是在这里被砍到 20 页,
     而且砍得毫无声响,直到下游报 ``customPayload.slide (required)`` ×20 才暴露。
     所以上限改成模板自己声明,并且这里的报错要说清它是谁定的。
@@ -576,8 +593,7 @@ def _check_slide_cross_field(dsl: dict) -> list[ValidationError]:
     schemas = tpl.get("slideSchemas")
     if not isinstance(schemas, dict):
         return []
-    line_sync = {k: v for k, v in (tpl.get("lineSyncSlides") or {}).items()
-                 if isinstance(v, str)}
+    line_sync = line_sync_slides(tpl)
 
     errors: list[ValidationError] = []
 
@@ -673,8 +689,7 @@ def _check_line_sync_narration(dsl: dict) -> list[ValidationError]:
     tpl = _get_template_cfg(_pick_template_id(dsl))
     if not tpl:
         return []
-    line_sync = {k: v for k, v in (tpl.get("lineSyncSlides") or {}).items()
-                 if isinstance(v, str)}
+    line_sync = line_sync_slides(tpl)
     if not line_sync:
         return []
     schemas = tpl.get("slideSchemas") if isinstance(tpl.get("slideSchemas"), dict) else {}
@@ -751,14 +766,8 @@ def _check_step_narration_alignment(dsl: dict) -> list[ValidationError]:
     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"):
+    field = step_alignment_field(tpl)
+    if not field:
         return []
 
     try:
@@ -813,6 +822,66 @@ def _check_step_narration_alignment(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_duration_estimate(dsl: dict) -> list[ValidationError]:
+    """按旁白字数估出的成片时长明显超过 ``meta.targetDuration`` → warning。
+
+    为什么要有:旁白字数决定时长,但没有任何一环在出素材之前核对过。2026-09-27 线上
+    一条 html-slide 会话,确认稿写 75s、每场 8–9s,每场却写了 45–58 字,还有 7 场是
+    分行旁白(每行之间有停顿)—— 成片 116.9s,用户确认的是一个从来不可能兑现的数。
+
+    只报 warning 不拦:走到这里用户已经确认过脚本,再拦只会多一轮来回;它存在的意义
+    是让这件事**有人看见**(模型据此如实告知用户,复盘据此定位)。估算口径见
+    ``narration_budget``。骨架占位旁白还没填时不估 —— 那是另一条检查的事。
+    """
+    try:
+        from . import narration_budget as nb
+    except ImportError:
+        return []
+
+    meta = dsl.get("meta") or {}
+    target = meta.get("targetDuration")
+    if isinstance(target, bool) or not isinstance(target, (int, float)) or target <= 0:
+        return []
+    narration_cfg = ((dsl.get("global") or {}).get("narration") or {})
+    speed = narration_cfg.get("speed")
+    speed = float(speed) if isinstance(speed, (int, float)) and not isinstance(speed, bool) and speed > 0 else 1.0
+    tail = nb.template_tail_pad_sec(_get_template_cfg(_pick_template_id(dsl)))
+
+    total = 0.0
+    narrated = 0
+    overruns: list[tuple[float, str, float, float]] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        lines = nb.narration_lines(narration)
+        if any(line.startswith(("[骨架待填充]", "[skeleton placeholder]")) for line in lines):
+            return []
+        planned = scene.get("duration")
+        planned = float(planned) if isinstance(planned, (int, float)) and not isinstance(planned, bool) else 0.0
+        est = nb.estimate_scene_sec(narration, speed, tail)
+        if est > 0:
+            narrated += 1
+            if planned > 0 and est - planned > 1.0:
+                overruns.append((est - planned, scene.get("id", f"scenes[{idx}]"), est, planned))
+        total += max(est, planned) if est > 0 else planned
+
+    if not narrated or total <= target * (1 + nb.OVERRUN_WARN_RATIO):
+        return []
+
+    overruns.sort(reverse=True)
+    detail = "; ".join(f"{sid} ≈{est:.0f}s (planned {planned:.0f}s)" for _, sid, est, planned in overruns[:5])
+    return [ValidationError(
+        "meta.targetDuration",
+        f"estimated video length ≈{total:.0f}s vs target {target:.0f}s "
+        f"(+{(total / target - 1) * 100:.0f}%) at narration speed {speed:g}× — "
+        f"~{nb.PLAN_CHARS_PER_SEC_1X * speed:.1f} zh chars/s, +{nb.LINE_PAUSE_SEC}s per extra "
+        f"narration line, +{tail:g}s tail per scene. Longest overruns: {detail or 'n/a'}. "
+        "Report the real length to the user (not the target) when you show the result; "
+        "narration drives duration, so to hit the target the narration must get shorter "
+        "or use fewer items.",
+        severity="warning",
+    )]
+
+
 def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
     """逐版式校验 ``customPayload.templateData`` 的字段名。
 
@@ -877,7 +946,7 @@ def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
             extra_allowed=shared,
             # frame 级字段由 Composition 消费,「整包态」binder 会把它们混进
             # templateData —— 出现在这里是正当的,不算未声明字段。
-            skip_keys=_SLIDE_FRAME_LEVEL_KEYS,
+            skip_keys=_frame_level_keys(tpl),
         )
 
     return errors
@@ -1260,6 +1329,8 @@ 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)
+    # warning,不阻断。见 _check_duration_estimate。
+    errors += _check_duration_estimate(dsl)
     return errors
 
 
@@ -1295,4 +1366,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     errors += _check_text_layer_rules(dsl)
+    # warning,不阻断。见 _check_duration_estimate。
+    errors += _check_duration_estimate(dsl)
     return errors