@remixmate/cli 0.9.44 → 0.9.46

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.44",
-  "generatedAt": "2026-09-22T14:28:26.210Z",
+  "version": "0.9.46",
+  "generatedAt": "2026-09-23T08:47:39.701Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -14,7 +14,7 @@
         "Turn this PPT / slide deck into a video",
         "Extract text or speaker notes from a .pptx",
         "Use a PowerPoint file as source material",
-        "Get customPayload.slide for ppt-to-video"
+        "Read the page count and speaker notes of a slide deck"
       ],
       "entry": {
         "type": "python",
@@ -437,7 +437,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",
@@ -451,6 +451,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."
@@ -517,6 +521,7 @@
           "voice_id",
           "speed",
           "template_id",
+          "source_document_url",
           "headline",
           "subheadline",
           "carousel_items",
@@ -777,6 +782,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)."
@@ -806,6 +815,7 @@
           "dsl_json",
           "dsl",
           "template_id",
+          "source_document_url",
           "binding_json",
           "binding",
           "save_job",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.44",
+  "version": "0.9.46",
   "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",

package/skills/doc-parse/SKILL.md

@@ -13,14 +13,13 @@ description: |
   - Turn this PPT / slide deck into a video
   - Read / extract / summarize a .pptx, pull the text or the speaker notes out of a deck
   - Use a PowerPoint file as source material for a script
-  - Anything that needs `customPayload.slide` for the `ppt-to-video` template
 
-  Never hand-write `slide` nodes for `ppt-to-video`. A page has dozens of shapes with exact EMU coordinates; transcribing them by eye is guaranteed to drift from the original, and the template's own hint says so.
+  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain `customPayload.slide` — that payload never passes through you; see "Using the result".
 triggers:
   - Turn this PPT / slide deck into a video
   - Extract text or speaker notes from a .pptx
   - Use a PowerPoint file as source material
-  - Get customPayload.slide for ppt-to-video
+  - Read the page count and speaker notes of a slide deck
 ---
 
 # Document Extraction Skill (`doc_parse`)
@@ -50,7 +49,7 @@ That default matters: one page of `layout` with embedded icons can be hundreds o
 
 ## Usage
 
-Whole deck, both layers (what `ppt-to-video` needs):
+Whole deck, both layers. The layout layer is what makes the per-page summary useful — it is where `mode` and the beat count come from, and those drive how you cut the narration:
 
 ```bash
 python3 <SkillDir>/scripts/extract_via_render.py --url "https://oss.example.com/deck.pptx"
@@ -96,7 +95,38 @@ python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" -
 
 ## Using the result
 
-**For the picture** — feed `slides[i]` straight into the template's `customPayload.slide`. Do not edit the coordinates, and do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+### For the picture — you don't. Pass the URL instead.
+
+The `layout` layer is written to a file, and **in the agent runtime you have no file-reading tool** (`Read` / `Bash` / `Glob` are deliberately not exposed — see `mcp-tools.ts`). So the file on disk is not a handoff to you, and `web_read` will not open it either: it only accepts http/https.
+
+That is on purpose. One page of layout with embedded icons runs to hundreds of KB; a 23-page deck is several MB. It would bury everything else in your context and you would still only be copying bytes.
+
+So the picture travels **by reference**:
+
+```bash
+# 1. here: read the words and count the pages
+doc_parse  --url "https://…/deck.pptx"
+
+# 2. pass the SAME url to gen_script, plus one scene per page
+gen_script --template-id ppt-to-video \
+           --source-document-url "https://…/deck.pptx" \
+           --scenes 23
+```
+
+`gen_script` records it at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.slide` before validation. You never see that data, and you never hand-write it.
+
+What you *do* own from this result:
+
+| You read | You do |
+| --- | --- |
+| page count | pass it as `--scenes` (then read the real count back off the returned DSL) |
+| `rawNotes` / `text` per page | write the narration (see below) |
+| `mode` + beat count per page | cut the narration into that many sentences |
+| `flags` | tell the user which elements the extractor could not reconstruct |
+
+Do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it by writing `customPayload.mode`. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+
+> If `prepare_video_assets` ever tells you `customPayload.slide (required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
 
 **For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
 

package/skills/doc-parse/scripts/extract_via_render.py

@@ -2,7 +2,7 @@
 """
 文档抽取脚本 — 通过 ab-render HTTP 接口实现，本地不需要任何 Office/解析依赖。
 
-调用链：
+调用链（实现在共享模块 ``doc_extract``）：
   POST $RENDER_API_URL/extract        → { taskId }
   POST $RENDER_API_URL/extractStatus  → { status, progress, result?, error? }
 
@@ -14,6 +14,11 @@
 直接进对话正文会撑爆上下文，还会让用户在聊天记录里滚过一屏 base64。默认写文件 +
 打一份人能读的摘要；确实要管道传全量时用 --json-output（或只要 content 层）。
 
+⚠️ 关于 layout 层的用法，看清楚这一条：**它不是给你读的**。在 ab-agent 里模型没有
+任何文件读取工具（这是有意的安全收窄），所以落盘的那个文件你打不开。需要 layout 的
+模板（ppt-to-video）按引用取数：把同一个文档 URL 传给 ``gen_script --source-document-url``，
+渲染管线会自己把每一页填进 ``customPayload.slide``。见 SKILL.md「Using the result」。
+
 必要环境变量（由 ab-agent 自动注入）：
   RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）
   PRIV_TOKEN       ab-api 私有 token
@@ -26,99 +31,22 @@ import argparse
 import json
 import os
 import sys
-import time
-import urllib.error
-import urllib.request
-
-# ─── 环境变量 ─────────────────────────────────────────────────────────────────
-
-RENDER_API_URL = (
-    os.environ.get("RENDER_API_URL")
-    or os.environ.get("REMOTION_RENDER_API_URL")
-    or "https://api-render.remixmate.ai"
-).rstrip("/")
-PRIV_TOKEN = os.environ.get("PRIV_TOKEN", "")
-CONVERSATION_ID = os.environ.get("CONVERSATION_ID", "")
-
-# ─── HTTP 工具 ────────────────────────────────────────────────────────────────
-
-
-def api_post(path: str, body: dict, timeout: int = 30) -> dict:
-    """向 ab-render 发送 POST 请求，返回解析后的 JSON。"""
-    url = f"{RENDER_API_URL}{path}"
-    data = json.dumps(body).encode()
-
-    headers: dict[str, str] = {
-        "Content-Type": "application/json",
-        "X-Priv-Token": PRIV_TOKEN,
-    }
-    if CONVERSATION_ID:
-        headers["x-conversation-id"] = CONVERSATION_ID
-
-    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
-    try:
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            return json.loads(resp.read())
-    except urllib.error.HTTPError as e:
-        body_text = e.read().decode(errors="replace")
-        raise RuntimeError(f"HTTP {e.code}: {body_text}") from e
-
-
-def log(msg: str, silent: bool = False) -> None:
-    if not silent:
-        print(msg, flush=True)
-
-
-# ─── 摘要 ─────────────────────────────────────────────────────────────────────
-
-
-def summarize(result: dict, out_path: str | None) -> str:
-    """
-    人能读的一页纸。**这是这个 skill 存在的一半价值** —— 端点给的是全量结构，
-    决定"喂多少进上下文"是入口层的责任（设计文档 §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)
+# 共享 Python lib 在 skills/template-registry/scripts/（见 AGENTS.md 的约定）。
+# 抽取的 submit/poll 逻辑住在那里而不是这里，因为渲染管线也要用同一份 —— 见
+# doc_extract 模块头的说明。
+sys.path.insert(
+    0,
+    os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "template-registry", "scripts")
+    ),
+)
 
-
-# ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+from doc_extract import (  # noqa: E402
+    DocExtractError,
+    extract_document,
+    summarize,
+)
 
 
 def main() -> None:
@@ -141,77 +69,46 @@ def main() -> None:
     )
     args = parser.parse_args()
 
-    if not PRIV_TOKEN:
-        print(
-            "❌ PRIV_TOKEN env var is not configured — /extract requires auth.",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    fields = [f.strip() for f in args.fields.split(",") if f.strip()]
+    # 管道模式下 stdout 只能有那一份 JSON，进度行一律走 stderr。
+    def log(msg: str) -> None:
+        print(msg, file=sys.stderr if args.json_output else sys.stdout, flush=True)
 
-    # ── 1. Submit ────────────────────────────────────────────────────────────
-    log(f"[doc-parse] Submitting extraction: {args.url[:80]}", args.json_output)
-
-    body: dict = {"documentUrl": args.url, "kind": args.kind, "fields": fields}
-    if args.slide is not None:
-        body["slide"] = args.slide
-
-    resp = api_post("/extract", body)
-    if resp.get("code") != 0:
-        print(f"❌ submission failed: {resp.get('msg', 'unknown error')}", file=sys.stderr)
+    try:
+        result = extract_document(
+            args.url,
+            kind=args.kind,
+            fields=args.fields,
+            slide=args.slide,
+            log=log,
+        )
+    except DocExtractError as exc:
+        # 端点的错误已经是人话（格式不对/超页数/超体积），原样透出，不要再包一层。
+        print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)
 
-    task_id: str = resp["data"]["taskId"]
-    log(f"[doc-parse] task accepted, taskId={task_id}", args.json_output)
-
-    # ── 2. Poll ──────────────────────────────────────────────────────────────
-    max_wait_sec = 600
-    poll_interval = 2
-    elapsed = 0
+    if args.json_output:
+        print(json.dumps(result, ensure_ascii=False))
+        return
 
-    while elapsed < max_wait_sec:
-        time.sleep(poll_interval)
-        elapsed += poll_interval
+    # 默认落盘 + 摘要：layout 层直接打进 stdout 会撑爆上下文（见文件头）。
+    out_path = args.out or f"./{(result.get('source') or {}).get('name', 'document')}.extract.json"
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
 
-        try:
-            status_resp = api_post("/extractStatus", {"taskId": task_id})
-        except Exception as e:  # noqa: BLE001
-            log(f"[doc-parse] polling error (will retry): {e}", args.json_output)
-            continue
+    print("\n✅ 抽取完成\n")
+    print(summarize(result, out_path))
 
-        if status_resp.get("code") != 0:
-            log(f"[doc-parse] polling error code (will retry): {status_resp.get('msg')}", args.json_output)
-            continue
-
-        task = status_resp["data"]
-        status = task.get("status", "unknown")
-
-        if status == "succeeded":
-            result = task.get("result") or {}
-
-            if args.json_output:
-                print(json.dumps(result, ensure_ascii=False))
-                return
-
-            # 默认落盘 + 摘要：layout 层直接打进 stdout 会撑爆上下文（见文件头）。
-            out_path = args.out or f"./{(result.get('source') or {}).get('name', 'document')}.extract.json"
-            with open(out_path, "w", encoding="utf-8") as f:
-                json.dump(result, f, ensure_ascii=False, indent=2)
-
-            print("\n✅ 抽取完成\n")
-            print(summarize(result, out_path))
-            return
-
-        if status == "failed":
-            # 端点的错误已经是人话（格式不对/超页数/超体积），原样透出，不要再包一层。
-            print(f"❌ extraction failed: {task.get('error', 'unknown error')}", file=sys.stderr)
-            sys.exit(1)
-
-        log(f"[doc-parse] status={status} elapsed={elapsed}s", args.json_output)
-
-    print(f"❌ extraction timed out (over {max_wait_sec}s)", file=sys.stderr)
-    sys.exit(1)
+    if "layout" in (result.get("source") or {}).get("fields", []):
+        # 这段是为了堵住一个具体的失败模式：上一版这里只说"已写入 <文件>"，读到它的
+        # 模型会理所当然地去读那个文件，然后发现自己没有文件读取工具，接着就没有
+        # 第二条路了。所以把下一步明确写出来。
+        print(
+            "\n📎 下一步：**不要去读上面那个文件，也不要手写 slide 节点**。\n"
+            "   画面数据按引用进管线 —— 把同一个文档 URL 传给 gen_script：\n"
+            f"     gen_script --template-id <id> --source-document-url \"{args.url[:100]}\"\n"
+            "   之后 prepare_video_assets 会自己把每一页填进对应场景的 customPayload.slide。\n"
+            "   你要写的是旁白（用上面每页的备注改写）与场景数（= 页数）。"
+        )
 
 
 if __name__ == "__main__":

package/skills/gen-script/SKILL.md

@@ -62,6 +62,35 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 7. If `template_registry list_examples=true` does return files locally, read them as an extra sample — never as a substitute for step 1.
 8. After generation, run the schema check and show the script summary to the user for confirmation.
 
+### Document-driven templates: pass the source URL, don't author the payload
+
+Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` (today: `ppt-to-video`, which fills `customPayload.slide` from a `.pptx`).
+
+For those, pass **`--source-document-url`** — the same URL you gave `doc_parse`:
+
+```bash
+gen_script --template-id ppt-to-video \
+           --source-document-url "https://…/deck.pptx" \
+           --scenes 23 --duration 600
+```
+
+It is recorded at `meta.sourceDocument`, and `prepare_video_assets` fetches the layout itself and fills every scene before validation runs.
+
+Two things follow, and both matter:
+
+- **You cannot supply this payload yourself, so don't try.** One page of layout data is hundreds of KB. It is not in any tool result you can read, and the file `doc_parse` writes is not openable from the agent runtime. `customPayload.slide (required)` on every scene means the *reference* is missing, not the data.
+- **The reference has to be set here, at `gen_script` time.** The agent layer merges your submitted `dsl_json` onto the cached skeleton and keeps `meta` / `global` from the skeleton — so writing `meta.sourceDocument` into `dsl_json` yourself is silently dropped. If you already generated a skeleton without it, either re-run `gen_script` or pass `source_document_url` to `prepare_video_assets`.
+
+Scene count for these templates is **one scene per page**, taken from `doc_parse`'s summary. Such templates raise `capabilities.maxScenes` above the default 20 for exactly this reason.
+
+### Scene count: read it back, never assume it
+
+`--scenes` is a request, not a guarantee. It is clamped to `[3, capabilities.maxScenes]` (default max 20), and a clamp is a **stderr warning, not an error** — the call still succeeds and returns a DSL with a different number of scenes than you asked for.
+
+So after every call, take the scene count from `scenes[]` in the returned DSL. Do not describe scene 21 of a 20-scene DSL to the user. A 23-page deck once got clamped to 20 here; the agent wrote 23 scenes' worth of narration anyway, the user confirmed a 23-scene script, and the mismatch only surfaced three tool calls later as a payload error that said nothing about scene counts.
+
+If the count you need is above the template's maximum, say so and stop — do not quietly ship fewer scenes than the source material has.
+
 ### Multi-layout templates: pick a layout per scene
 
 When a template's `customPayloadSchema.slideId.enum` holds more than one value (today `html-slide` and `html-slide-blackboard`, 16 layouts each), **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
@@ -94,6 +123,8 @@ Two consequences for the agent:
 - **Forbidden**: reusing a single `slideId` across the whole video on a multi-layout template because it was the first one in the enum.
 - **Forbidden**: the user specified a template, but the agent first generated a generic DSL and then passed `--template-id` to `template-registry` to force-bind it.
 - **Forbidden**: continuing into binding / rendering despite knowing that template-specific fields, scene shapes, or binding details are missing.
+- **Forbidden**: showing the user a confirmation summary whose scene count differs from `scenes[]` in the returned DSL.
+- **Forbidden**: omitting `--source-document-url` for a template that declares `capabilities.payloadHydration`, or trying to hand-write the payload it hydrates.
 - **Forbidden**: silently degrading to a generic DSL because the current script cannot support a template, leaving the failure to the downstream stage.
 
 ### When a template is not yet supported