@remixmate/cli 0.9.44 → 0.9.46

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)

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

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Fill a template-declared ``customPayload`` field from a source document, by reference.
+
+问题（2026-09-23 线上 conv_Sesw2g8oM81 的根因）
+---------------------------------------------
+``ppt-to-video`` 要求每个场景都有 ``customPayload.slide`` —— 一整页 PPT 的节点树、
+坐标、配色、beats。这份数据只有一个合法产出方（ab-render 的 ``/extract`` layout 层），
+而它**体积大到不能过模型**：一页带内嵌图标可达几百 KB，23 页就是好几 MB。
+
+于是模板的 llmHint 写着「把返回的 slides[i].slide 整个填进 customPayload.slide」，
+doc-parse 的 SKILL.md 写着「feed slides[i] straight into customPayload.slide」，而实际
+链路是：doc_parse 把全量写进本地文件 → 模型没有任何文件读取工具 → 拿不到 → 
+prepare_video_assets 报 ``customPayload.slide (required)`` ×N。模型无论怎么改都过不了。
+
+解法
+----
+**不让这份数据过模型**。DSL 里只留一个引用（``meta.sourceDocument``），skill 侧在
+校验之前自己去把全量取回来填进每个场景。模型负责的是它真正能负责的东西：旁白、
+场景与页的对应关系、以及 mode 的下压。
+
+这与 ``extractCustomPayloadOverrides`` / ``extractNarrationOverrides`` 是同一类教训的
+第三次：**合并层丢掉了数据，而下游报的错指向模型**。前两次丢的是 slideId 和 items。
+
+模板怎么声明
+-----------
+``template.json`` 的 ``capabilities.payloadHydration``::
+
+    "payloadHydration": {
+      "payloadField": "slide",        # 要填的 customPayload 字段名
+      "source": "doc-extract",        # 数据来源（目前只有这一个）
+      "docKind": "pptx",
+      "fields": "content,layout",     # 传给 /extract 的层
+      "indexField": "slideIndex"      # 场景→页的映射键（写在 customPayload 里）
+    }
+
+不写 ``if template_id == "ppt-to-video"``（AGENTS.md 明令禁止）：任何模板声明了这一段
+就自动获得同样的行为。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Callable, Optional
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from doc_extract import (  # noqa: E402
+    DocExtractError,
+    extract_document,
+    slides_by_index,
+)
+
+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 必须直接告诉调用方下一步做什么。
+
+    这个类存在的全部意义是替换掉 ``customPayload.slide (required)`` ×20 那种报错 ——
+    它说的是"某个字段没填"，而真相是"这个字段的数据源没有通路"，两者要采取的行动
+    完全不同，而模型只看得到前者。
+    """
+
+
+def hydration_spec(template_config: Optional[dict]) -> Optional[dict]:
+    """读 ``capabilities.payloadHydration``；未声明 / 声明无效返回 None。
+
+    宽容读取：一个写坏的 template.json 不该让所有模板的渲染一起失败。但
+    ``source`` 认不出来时要报错而不是静默跳过 —— 静默跳过会退回到「必填字段缺失」
+    那条死路，也就是这个模块本来要修掉的东西。
+    """
+    caps = (template_config or {}).get("capabilities")
+    if not isinstance(caps, dict):
+        return None
+    spec = caps.get("payloadHydration")
+    if not isinstance(spec, dict) or not spec:
+        return None
+
+    payload_field = spec.get("payloadField")
+    if not isinstance(payload_field, str) or not payload_field:
+        return None
+
+    source = spec.get("source") or "doc-extract"
+    if source not in SUPPORTED_SOURCES:
+        raise HydrationError(
+            f"template declares capabilities.payloadHydration.source='{source}', which this "
+            f"version of remixmate does not implement (supported: {', '.join(SUPPORTED_SOURCES)}). "
+            "Upgrade @remixmate/cli or fix the template."
+        )
+
+    index_field = spec.get("indexField")
+    return {
+        "payload_field": payload_field,
+        "source": source,
+        "doc_kind": spec.get("docKind") or "pptx",
+        "fields": spec.get("fields") or "content,layout",
+        "index_field": index_field if isinstance(index_field, str) and index_field else DEFAULT_INDEX_FIELD,
+    }
+
+
+def source_document_ref(dsl: dict, override_url: Optional[str] = None) -> Optional[dict]:
+    """取 DSL 里的源文件引用。``override_url`` 优先（CLI 显式传入时）。
+
+    位置是 ``meta.sourceDocument`` 而不是场景级：一条片子对一份源文件，写在场景里
+    会得到 23 份同样的 URL，还得处理它们互相矛盾的情况。
+
+    为什么是 ``meta``：ab-agent 的合并层（``applyNarrationToSkeleton``）以 gen_script
+    骨架为基底，只从模型提交的 DSL 里搬 narration 与 customPayload，``meta`` / ``global``
+    归骨架所有。所以写在 meta 的引用能活着穿过合并层，而模型自己往 dsl_json 里写
+    ``meta.sourceDocument`` 会被丢掉 —— 引用必须在 gen_script 那一步就进骨架。
+    """
+    if override_url:
+        return {"url": override_url}
+    meta = dsl.get("meta")
+    if not isinstance(meta, dict):
+        return None
+    ref = meta.get("sourceDocument")
+    if isinstance(ref, str) and ref.strip():
+        return {"url": ref.strip()}
+    if isinstance(ref, dict) and isinstance(ref.get("url"), str) and ref["url"].strip():
+        return {"url": ref["url"].strip(), "kind": ref.get("kind")}
+    return None
+
+
+def _scene_payload(scene: dict) -> dict:
+    payload = scene.get("customPayload")
+    if not isinstance(payload, dict):
+        payload = {}
+        scene["customPayload"] = payload
+    return payload
+
+
+def hydrate_dsl(
+    dsl: dict,
+    template_config: Optional[dict],
+    *,
+    override_url: Optional[str] = None,
+    log: Optional[Callable[[str], None]] = None,
+) -> list[str]:
+    """把源文件的每一页填进对应场景的 ``customPayload.<payloadField>``。
+
+    返回一份给人看的报告行列表（调用方自己决定打到哪）。什么都没做时返回空列表。
+
+    映射规则：场景的 ``customPayload.<indexField>`` 是 1-based 页号，缺省按场景顺序
+    取第 i 页。显式页号优先 —— 用户可能只讲其中几页，或者把两页并成一个场景。
+
+    已有值不覆盖：场景里已经有 ``customPayload.slide`` 时跳过。直接调 CLI 的调试流程
+    会手动塞一份进去，把它冲掉等于让调试者的输入人间蒸发。
+    """
+    emit = log or (lambda _msg: None)
+
+    spec = hydration_spec(template_config)
+    if not spec:
+        return []
+
+    scenes = [s for s in (dsl.get("scenes") or []) if isinstance(s, dict)]
+    if not scenes:
+        return []
+
+    field = spec["payload_field"]
+    index_field = spec["index_field"]
+
+    pending = [s for s in scenes if _scene_payload(s).get(field) is None]
+    if not pending:
+        return [f"customPayload.{field} already present on all {len(scenes)} scene(s); nothing to hydrate"]
+
+    ref = source_document_ref(dsl, override_url)
+    if not ref:
+        template_id = ((dsl.get("meta") or {}).get("templateId")) or "this template"
+        raise HydrationError(
+            f"{len(pending)} of {len(scenes)} scene(s) need customPayload.{field}, and "
+            f"'{template_id}' builds it from the source document rather than from hand-written JSON — "
+            "but the DSL carries no source document reference.\n"
+            "   This field is intentionally NOT something you author: one page of layout data is "
+            "hundreds of KB, so it never travels through the conversation.\n"
+            f"   Fix: pass the document URL once and the pipeline fills all {len(scenes)} scenes itself.\n"
+            "     • preferred — call gen_script with --source-document-url <url> so the reference is "
+            "recorded in meta.sourceDocument\n"
+            "     • or pass --source-document-url <url> to this call directly\n"
+            "   The URL is the same .pptx you gave doc_parse."
+        )
+
+    kind = ref.get("kind") or spec["doc_kind"]
+    emit(f"🧩 hydrating customPayload.{field} from the source document ({kind}, fields={spec['fields']})")
+
+    try:
+        result = extract_document(
+            ref["url"], kind=kind, fields=spec["fields"], log=emit
+        )
+    except DocExtractError as exc:
+        raise HydrationError(
+            f"could not read the source document needed for customPayload.{field}: {exc}"
+        ) from exc
+
+    pages = slides_by_index(result)
+    if not pages:
+        raise HydrationError(
+            f"the source document extraction returned no pages, so customPayload.{field} "
+            "cannot be filled. Check that the URL points at the .pptx file itself."
+        )
+
+    report: list[str] = []
+    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:
+            continue
+        declared = payload.get(index_field)
+        page_no = declared if isinstance(declared, int) and declared > 0 else position
+        page = pages.get(page_no)
+        if page is None:
+            missing.append(f"scene {scene.get('id', position)} → page {page_no}")
+            continue
+        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 {}
+    report.append(
+        f"✅ filled customPayload.{field} on {filled}/{len(scenes)} scene(s) from "
+        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:
+        # 页号对不上不是警告而是错误：少一页 = 成片里一个空白场景，而它渲得出来。
+        raise HydrationError(
+            f"{len(missing)} scene(s) point at a page that the source document does not have "
+            f"({'; '.join(missing[:5])}"
+            f"{f'; … {len(missing)} total' if len(missing) > 5 else ''}).\n"
+            f"   The document has {len(pages)} page(s). Either lower the scene count to match, "
+            f"or fix customPayload.{index_field} on those scenes."
+        )
+
+    # 降级记录要顺着传上来 —— 画面上少一块，这里不说就没人知道为什么。
+    flagged = [
+        f"page {no}: {'; '.join(page.get('flags') or [])}"
+        for no, page in sorted(pages.items())
+        if page.get("flags")
+    ]
+    if flagged:
+        report.append(
+            "⚠️  the extractor refused to reconstruct some elements (they render as an "
+            "approximation): " + " | ".join(flagged[:5])
+        )
+
+    return report

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V18",
+  "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."
 }