@remixmate/cli 0.9.44 → 0.9.45

package/skills/gen-script/skill.json

@@ -34,7 +34,7 @@
       },
       "scenes": {
         "type": "number",
-        "description": "Scene count"
+        "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (e.g. ppt-to-video), pass the page count you saw in doc_parse's summary."
       },
       "voice_id": {
         "type": "string",
@@ -48,6 +48,10 @@
         "type": "string",
         "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
       },
+      "source_document_url": {
+        "type": "string",
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills every scene's customPayload.slide. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
+      },
       "headline": {
         "type": "string",
         "description": "On-screen headline. Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer. This is on-screen copy, so write it for a viewer who has never heard of the subject — a bare identifier (repo name, file name, product code) is not a title. Length limits, line breaks (\\n) and emphasis syntax are per-template: follow the chosen template's llmHint, which gen_script prints in full on stderr."
@@ -114,6 +118,7 @@
       "voice_id",
       "speed",
       "template_id",
+      "source_document_url",
       "headline",
       "subheadline",
       "carousel_items",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V15",
+  "version": "V16",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

package/skills/prepare-video-assets/skill.json

@@ -33,6 +33,10 @@
         "type": "string",
         "description": "Template id. When provided, the script invokes template-registry internally; no separate binding step is needed."
       },
+      "source_document_url": {
+        "type": "string",
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into every scene's customPayload.slide; you neither author nor see it."
+      },
       "binding_json": {
         "type": "string",
         "description": "TemplateBinding JSON as an inline string (alternative to template_id; no file needed)."

package/skills/prepare-video-assets/version.json

@@ -2,6 +2,6 @@
   "skillName": "prepare-video-assets",
   "repoName": "agent-skill-media-maker",
   "skillId": "476",
-  "version": "V1",
+  "version": "V3",
   "skillDescription": "Asset-preparation skill: resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a `job_id` for the subsequent `render_video` call.\n\nUse this skill as soon as the user mentions any of these intents:\n- Generate / prepare video assets, resolve assets, render-ready\n- \"Make me a video about X\" (the agent calls gen_script → prepare_video_assets → render_video)\n- Regenerate one asset (image / audio) for a specific scene\n\nNext step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.\n\n⚠️ Stop-and-confirm gate: this skill runs only after the user has confirmed the script, and after it returns you must show the resolved assets and wait for the user's explicit confirmation. Never call `render_video` in the same turn."
 }

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

@@ -63,6 +63,7 @@ from video_dsl.runtime.timeline_compiler import (
     split_subtitle,
     split_subtitle_from_lines,
     segment_narration,
+    assign_sentence_indices,
 )
 
 # 字幕末尾标点去除（与 timeline_compiler 中的 _strip_trailing_punct 同逻辑）
@@ -507,6 +508,82 @@ def validate_dsl(dsl: dict) -> list:
     return errors_as_strings([e for e in found if getattr(e, "severity", "error") == "error"])
 
 
+def _hydrate_dsl_payload(
+    dsl: dict, template_id: str | None, source_document_url: str | None
+) -> None:
+    """按模板声明把源文件的每一页填进 ``customPayload``（就地改 dsl）。
+
+    只对声明了 ``capabilities.payloadHydration`` 的模板生效（目前 ppt-to-video）；
+    其余模板这里是零成本 no-op —— 声明驱动，不写 ``if template_id == X``（AGENTS.md）。
+
+    失败一律 exit 2 并把「下一步做什么」打全：这条路上所有失败形态的共同点是
+    *数据源没通*，而历史报错说的是"字段没填"，两者要采取的行动完全不同。
+
+    共享模块导入失败（裁剪安装 / 单测环境）时静默跳过：那时 payloadRequirements
+    的校验会照常报必填缺失，行为退回改动前，不会更糟。
+    """
+    try:
+        from payload_hydrator import HydrationError, hydrate_dsl  # noqa: E402
+    except ImportError:
+        return
+
+    try:
+        from registry_loader import get_template  # noqa: E402
+        template = get_template(template_id) if template_id else None
+    except Exception:  # noqa: BLE001 - registry 不可达时退回"不注入"，由校验兜底报错
+        template = None
+    if not template:
+        return
+
+    try:
+        report = hydrate_dsl(
+            dsl,
+            template,
+            override_url=source_document_url,
+            log=lambda msg: LogPrint(f"   {msg}", file=sys.stderr),
+        )
+    except HydrationError as exc:
+        LogPrint(f"❌ {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    for line in report:
+        LogPrint(f"   {line}", file=sys.stderr)
+
+
+def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> None:
+    """动作条数与旁白句数不等时出声。
+
+    为什么值得单独打一条：这一类缺陷**渲得出来**。它不报错、不退非零、renderJob
+    completed、漏斗记 rendered —— 2026-09-23 线上那条鸡兔同笼成片就是这样交付的，
+    10 步板面配 10 句旁白，听起来该一一对应，实际板面在音频中点就走完了。
+    既然成片本身不会告状，那就必须有人在这里说一句。
+
+    只警告不阻断：步数少于句数有时是作者的本意（末尾一句总结不需要新动作）。
+    真正需要拦的是"作者以为一一对应、实际不是"，而那个判断只有作者做得了 ——
+    所以这里给的是两个数字，不是一个结论。
+    """
+    steps = ((entry.get("props") or {}).get("steps")
+             or (entry.get("props") or {}).get("beats"))
+    if not isinstance(steps, list) or not steps:
+        return
+    sentences = (sentence_indices[-1] + 1) if sentence_indices else 0
+    if sentences == 0 or len(steps) == sentences:
+        return
+
+    scene_id = entry.get("sceneId", "?")
+    tail = (
+        f"末尾 {sentences - len(steps)} 句没有对应动作，画面会在那之前就走完并停住"
+        if len(steps) < sentences
+        else f"多出的 {len(steps) - sentences} 个动作会挤在最后一句上"
+    )
+    LogPrint(
+        f"⚠️  scene {scene_id}: {len(steps)} 个讲解动作 vs 旁白 {sentences} 句 —— {tail}。\n"
+        f"   本模板的动作按**句**对齐（第 i 个动作 = 第 i 句的起点）。要一一对应就让两者等数；"
+        f"   要刻意不等，忽略这条即可。",
+        file=sys.stderr,
+    )
+
+
 def resolve_dimensions(dsl: dict) -> tuple:
     ratio = dsl.get("global", {}).get("aspectRatio", "16:9")
     resolution = dsl.get("global", {}).get("resolution", "1080p")
@@ -1381,14 +1458,24 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
 
                 tts_subs = narration_asset.get("ttsSubtitles", [])
                 if tts_subs:
+                    # 句归属必须在 _strip_subtitle_trailing_punct **之前**算：
+                    # 判据就是句末标点，去掉之后所有段都会被认成同一句。
+                    # 这一层是「第 i 个动作对齐第 i 句」类模板（math-principles-expl
+                    # 的 steps、ppt-to-video 的 beats）唯一能拿到句边界的地方 ——
+                    # TTS 行是按停顿切的，段数远多于句数。
+                    sentence_indices = assign_sentence_indices(
+                        [s.get("text") or "" for s in tts_subs]
+                    )
                     entry["subtitleSegments"] = [
                         {
                             "text": _strip_subtitle_trailing_punct(s["text"].strip()),
                             "startFrame": current_frame + int(s["timeBegin"] / 1000.0 * fps),
                             "endFrame": current_frame + int(s["timeEnd"] / 1000.0 * fps),
+                            "sentenceIndex": sentence_indices[i],
                         }
-                        for s in tts_subs
+                        for i, s in enumerate(tts_subs)
                     ]
+                    _warn_step_sentence_mismatch(entry, sentence_indices)
                 else:
                     # No TTS timestamps — re-distribute existing subtitle
                     # lines across the REAL audio duration, by character
@@ -2177,6 +2264,13 @@ Examples:
     parser.add_argument("--dsl", help="Input DSL file path")
     parser.add_argument("--dsl-json", default=None, help="DSL JSON as an inline string (replaces --dsl; no file needed; preferred for multi-user concurrent flows)")
     parser.add_argument("--template-id", default=None, help="Template id (required unless --render-plan / --job-id is used)")
+    parser.add_argument(
+        "--source-document-url", default=None,
+        help="Source document URL (.pptx) for templates that build their per-scene payload from a "
+             "document (capabilities.payloadHydration, e.g. ppt-to-video). Overrides "
+             "meta.sourceDocument in the DSL. The layout data is fetched here and written into "
+             "every scene's customPayload — it is deliberately never routed through the model.",
+    )
     parser.add_argument("--render-plan", help="Existing RenderPlan file path")
     parser.add_argument("--resolve-only", action="store_true", help="Only resolve assets; do not run the render")
     parser.add_argument("--skip-asset-resolve", action="store_true", help="Skip asset resolution")
@@ -2365,6 +2459,18 @@ Examples:
             )
             sys.exit(2)
 
+        # ── 按引用注入模板声明的大 payload（必须在校验之前）─────────────
+        #
+        # ppt-to-video 这类模板的画面数据（customPayload.slide：一整页的节点树、
+        # 坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
+        # 而它体积大到不能过模型（一页几百 KB，23 页好几 MB）。所以 DSL 里只带一个
+        # 引用（meta.sourceDocument），在这里把全量取回来填进每个场景。
+        #
+        # 为什么必须在 validate_dsl 之前：那道校验读的就是 capabilities.payloadRequirements
+        # 的必填项。放在后面 = 每次都被自己还没填的字段拒掉（2026-09-23 线上
+        # conv_Sesw2g8oM81 的表现就是 scenes[0..19].customPayload.slide (required)）。
+        _hydrate_dsl_payload(dsl, args.template_id, args.source_document_url)
+
         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": "V25",
+  "version": "V27",
   "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/doc_extract.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Shared document extraction client — ab-render ``/extract`` submit + poll.
+
+为什么这段逻辑住在共享目录而不是 doc-parse skill 里：**有两个消费方，而且它们要的
+形态相反**。
+
+  doc-parse（给模型看）      → 摘要进 stdout，全量落盘。layout 层一页带内嵌图标可达
+                              几百 KB，进对话正文会撑爆上下文。
+  payload_hydrator（给机器用）→ 要的就是全量 layout，直接填进 DSL 的 customPayload。
+
+第二个消费方以前不存在，于是 ppt-to-video 是这样断的：抽取结果只有落盘一条出路，而
+模型在 ab-agent 里**没有任何文件读取工具**（``mcp-tools.ts`` 的 ALLOWED_TOOL_NAMES 刻意
+只放行 MCP skill，内置 Read/Bash 全部排除，那是对的——bypassPermissions 下放开读写等于
+把 .env 里的 PRIV_TOKEN 交出去）。模型能看到「完整结果已写入 ./source.pptx.layout.json」，
+然后无论如何也读不到它。2026-09-23 线上那条会话在这里试了 ``web_read file://``，被
+「--url 只接受 http/https」打回，接着整条链路就没有第二条路了。
+
+结论：**layout 数据不该过模型**。它从 ab-render 出来，直接进 DSL，中间不经过上下文。
+这个模块就是那条直连的通道。
+
+环境变量（由 ab-agent 注入，与 doc-parse skill 同一套）：
+  RENDER_API_URL / REMOTION_RENDER_API_URL   ab-render 地址
+  PRIV_TOKEN                                 ab-api 私有 token（端点拒绝匿名调用）
+  CONVERSATION_ID                            留痕用，可选
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Callable, Optional
+
+DEFAULT_RENDER_API_URL = "https://api-render.remixmate.ai"
+
+# 端点是异步任务制：submit 拿 taskId，再轮询 extractStatus。
+DEFAULT_MAX_WAIT_SEC = 600
+DEFAULT_POLL_INTERVAL_SEC = 2
+
+SUPPORTED_KINDS = ("pptx",)
+
+
+class DocExtractError(RuntimeError):
+    """抽取失败。
+
+    message 直接面向调用方的 stderr —— ab-render 的抽取错误本来就是人话
+    （「不是 zip」「超页数上限」「.ppt 需另存为 .pptx」），再包一层只会让它更远。
+    """
+
+
+def render_api_url() -> str:
+    return (
+        os.environ.get("RENDER_API_URL")
+        or os.environ.get("REMOTION_RENDER_API_URL")
+        or DEFAULT_RENDER_API_URL
+    ).rstrip("/")
+
+
+def _api_post(path: str, body: dict, timeout: int = 30) -> dict:
+    url = f"{render_api_url()}{path}"
+    headers = {
+        "Content-Type": "application/json",
+        "X-Priv-Token": os.environ.get("PRIV_TOKEN", ""),
+    }
+    conversation_id = os.environ.get("CONVERSATION_ID", "")
+    if conversation_id:
+        headers["x-conversation-id"] = conversation_id
+
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode(), headers=headers, method="POST"
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310 - fixed https base
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode(errors="replace")
+        raise DocExtractError(f"HTTP {exc.code} from {path}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise DocExtractError(f"cannot reach ab-render at {url}: {exc.reason}") from exc
+
+
+def extract_document(
+    url: str,
+    *,
+    kind: str = "pptx",
+    fields: str | list[str] = "content,layout",
+    slide: Optional[int] = None,
+    max_wait_sec: int = DEFAULT_MAX_WAIT_SEC,
+    poll_interval_sec: int = DEFAULT_POLL_INTERVAL_SEC,
+    log: Optional[Callable[[str], None]] = None,
+) -> dict:
+    """Submit + poll one extraction; return the endpoint's ``result`` dict.
+
+    ``log`` 收到的是进度行，调用方自己决定丢到 stderr 还是丢掉。这里**不直接写
+    stdout** —— doc-parse 的 ``--json-output`` 管道模式要求 stdout 只有那一份 JSON。
+    """
+    emit = log or (lambda _msg: None)
+
+    if not os.environ.get("PRIV_TOKEN"):
+        raise DocExtractError(
+            "PRIV_TOKEN env var is not configured — the /extract endpoint refuses anonymous calls."
+        )
+    if kind not in SUPPORTED_KINDS:
+        raise DocExtractError(
+            f"unsupported document kind '{kind}' (supported: {', '.join(SUPPORTED_KINDS)})"
+        )
+    if not isinstance(url, str) or not url.lower().startswith(("http://", "https://")):
+        raise DocExtractError(
+            f"document url must be http/https, got {url!r}. "
+            "Pass the file URL itself (what the asset library returns), not a page or share link."
+        )
+
+    field_list = (
+        [f.strip() for f in fields.split(",") if f.strip()]
+        if isinstance(fields, str)
+        else [str(f).strip() for f in fields if str(f).strip()]
+    )
+
+    body: dict = {"documentUrl": url, "kind": kind, "fields": field_list}
+    if slide is not None:
+        body["slide"] = slide
+
+    emit(f"[doc-extract] submitting: {url[:80]}")
+    resp = _api_post("/extract", body)
+    if resp.get("code") != 0:
+        raise DocExtractError(f"submission failed: {resp.get('msg', 'unknown error')}")
+
+    task_id = ((resp.get("data") or {}).get("taskId")) or ""
+    if not task_id:
+        raise DocExtractError(f"/extract did not return a taskId: {resp}")
+    emit(f"[doc-extract] task accepted, taskId={task_id}")
+
+    elapsed = 0
+    while elapsed < max_wait_sec:
+        time.sleep(poll_interval_sec)
+        elapsed += poll_interval_sec
+
+        try:
+            status_resp = _api_post("/extractStatus", {"taskId": task_id})
+        except DocExtractError as exc:
+            # 网络抖动不是任务失败：任务还在服务端跑着，重试轮询。
+            emit(f"[doc-extract] polling error (will retry): {exc}")
+            continue
+
+        if status_resp.get("code") != 0:
+            emit(f"[doc-extract] polling error code (will retry): {status_resp.get('msg')}")
+            continue
+
+        task = status_resp.get("data") or {}
+        status = task.get("status", "unknown")
+
+        if status == "succeeded":
+            return task.get("result") or {}
+        if status == "failed":
+            raise DocExtractError(f"extraction failed: {task.get('error', 'unknown error')}")
+
+        emit(f"[doc-extract] status={status} elapsed={elapsed}s")
+
+    raise DocExtractError(f"extraction timed out after {max_wait_sec}s (taskId={task_id})")
+
+
+def slides_by_index(result: dict) -> dict[int, dict]:
+    """``slides[]`` 按 1-based ``slideIndex`` 建索引。
+
+    不用列表位置当页号：``--slide N`` 单页抽取时列表只有一项，而它的 slideIndex 是 N。
+    按位置取会把第 7 页当第 1 页用，而且画面看起来"有内容"，没人会发现。
+    """
+    index: dict[int, dict] = {}
+    for position, slide in enumerate(result.get("slides") or [], start=1):
+        if not isinstance(slide, dict):
+            continue
+        raw = slide.get("slideIndex")
+        index[raw if isinstance(raw, int) and raw > 0 else position] = slide
+    return index
+
+
+def summarize(result: dict, out_path: Optional[str] = None) -> str:
+    """人能读的一页纸。
+
+    **这是 doc-parse 存在的一半价值** —— 端点给的是全量结构，决定"喂多少进上下文"
+    是入口层的责任（设计文档 §4.4）。每页一行：页码、档位、拍数、标题、讲稿来源。
+    档位与拍数决定后面怎么写旁白，讲稿来源决定走严格改写还是扩写。
+    """
+    src = result.get("source", {})
+    lines = [
+        f"共 {src.get('slideCount', '?')} 页，本次抽到 {len(result.get('slides', []))} 页"
+        f"（fields={'+'.join(src.get('fields', []))}）",
+        "",
+    ]
+
+    for s in result.get("slides", []):
+        idx = s.get("slideIndex", "?")
+        bits = [f"第 {idx} 页"]
+
+        if s.get("mode"):
+            beats = len(s.get("beats") or [])
+            bits.append(f"{s['mode']}/{beats} 拍")
+        if s.get("title"):
+            bits.append(f"「{s['title']}」")
+
+        notes = (s.get("rawNotes") or "").strip()
+        if notes:
+            head = notes.replace("\n", " ")[:40]
+            bits.append(f"备注 {len(notes)} 字：{head}…")
+        elif "rawNotes" in s:
+            bits.append("无备注（旁白需按正文扩写）")
+
+        lines.append("  " + " · ".join(bits))
+
+        if s.get("modeReason"):
+            lines.append(f"      判定：{s['modeReason']}")
+        flags = s.get("flags") or []
+        if flags:
+            # flag 是显式的降级记录，不是日志 —— 画面上少一块，这里不说就没人知道为什么。
+            lines.append(f"      ⚠ 降级：{'; '.join(flags[:3])}")
+
+    if out_path:
+        lines += ["", f"完整结果已写入：{out_path}"]
+    return "\n".join(lines)
+
+
+def stderr_logger(msg: str) -> None:
+    print(msg, file=sys.stderr, flush=True)