@remixmate/cli 0.9.38 → 0.9.39

package/dist/manifest.json

@@ -1,8 +1,81 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.38",
-  "generatedAt": "2026-09-21T11:34:27.703Z",
+  "version": "0.9.39",
+  "generatedAt": "2026-09-21T14:35:49.704Z",
   "skills": [
+    {
+      "id": "doc-parse",
+      "toolName": "doc_parse",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Document Extraction",
+      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+      "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"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/extract_via_render.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "RENDER_API_URL",
+        "PRIV_TOKEN",
+        "CONVERSATION_ID"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "pptx"
+            ],
+            "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+          },
+          "fields": {
+            "type": "string",
+            "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+          },
+          "slide": {
+            "type": "number",
+            "description": "Only extract this 1-based page. Omit for the whole deck."
+          },
+          "out": {
+            "type": "string",
+            "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+          },
+          "json_output": {
+            "type": "boolean",
+            "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "url",
+          "fields"
+        ],
+        "advanced": [
+          "slide",
+          "kind"
+        ],
+        "hidden": [
+          "out",
+          "json_output"
+        ]
+      }
+    },
     {
       "id": "export-jianying",
       "toolName": "export_jianying",

package/package.json

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

@@ -0,0 +1,124 @@
+---
+name: doc-parse
+description: |
+  Document extraction skill — turn a `.pptx` into structured data through the ab-render `/extract` endpoint.
+
+  Two layers, picked with `--fields`:
+  - **content** — per-page `title`, `text[]`, and `rawNotes` (the speaker notes). Small, no base64. This is the narration source material.
+  - **layout** — the full `slide` payload the `ppt-to-video` template renders from: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. Large (icons are embedded as data URIs).
+
+  Deterministic: the endpoint parses OOXML, it does **not** call a model. Notes come back verbatim — rewriting them into narration is your job, not the endpoint's.
+
+  Use this skill immediately whenever the user asks for any of:
+  - 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.
+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
+---
+
+# Document Extraction Skill (`doc_parse`)
+
+Entry script **`scripts/extract_via_render.py`**, pure Python (stdlib only — no Office libraries, no local install).
+
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Never hardcode an absolute path.
+
+## How it works
+
+```
+POST $RENDER_API_URL/extract        → { taskId }
+POST $RENDER_API_URL/extractStatus  → { status, result? }   (polled for you)
+```
+
+The heavy lifting (download, unzip, OOXML parsing, geometry) happens server-side. The script submits, polls, then **writes the full JSON to a file and prints a per-page summary**.
+
+That default matters: one page of `layout` with embedded icons can be hundreds of KB. Printing it would fill your context with base64 and bury the three facts you actually need — the page's mode, its beat count, and whether it has speaker notes.
+
+## Environment
+
+| Var | Meaning | Default |
+| --- | --- | --- |
+| `RENDER_API_URL` | ab-render base URL (falls back to `REMOTION_RENDER_API_URL`) | `https://api-render.remixmate.ai` |
+| `PRIV_TOKEN` | ab-api private token — **required**, the endpoint refuses anonymous calls | — |
+| `CONVERSATION_ID` | Conversation id, for provenance | — |
+
+## Usage
+
+Whole deck, both layers (what `ppt-to-video` needs):
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://oss.example.com/deck.pptx"
+```
+
+Text and notes only — summarizing a deck, or writing narration without touching the visuals:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --fields content
+```
+
+One page:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --slide 3
+```
+
+## Output
+
+```jsonc
+{
+  "source": { "url": "…", "name": "deck.pptx", "slideCount": 12, "canvas": [1920, 1080], "fields": ["content","layout"] },
+  "slides": [
+    {
+      "slideIndex": 1,
+      // content 层
+      "title": "产品介绍",
+      "text": ["三大优势", "…"],
+      "rawNotes": "备注页原文，逐字返回，未经改写",
+      // layout 层
+      "mode": "sequenced",
+      "modeReason": "4×1 格点，4 块 + 2 组页面家具",
+      "nodes": [ /* … */ ],
+      "beats": [ { "reveal": ["n12","n13"] } ],
+      "ambientIds": ["n2"],
+      "recommendedSec": 5.3,
+      "background": { "color": "#FFFFFF" },
+      "flags": ["unsupported_geom:rightArrow×3"]
+    }
+  ]
+}
+```
+
+## 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 words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
+
+| Source | What it is | What to do | Can you check yourself? |
+| --- | --- | --- | --- |
+| `rawNotes` | already a script, written to be spoken | re-cut into one sentence per beat, make it spoken-register, drop stage directions (“as you can see here”, “(next slide)”) and non-script items (citations, TODOs) | **yes** — the original is right there |
+| `text` | bullet points, sometimes just keywords | expand into sentences | **no** — there is nothing to check against |
+
+Two rules:
+
+1. **Do not introduce facts that are not on the slide.** This is the user's own deck; inventing content puts words in their mouth.
+2. **Talk about it, don't read it out.** The body text is already on screen. Narrating it verbatim gives the viewer the same sentence three times — on the slide, in the subtitle, and in the voice-over.
+
+When a page had no notes and you wrote the narration from `text`, say so and ask the user to look it over. Do not ship it silently.
+
+## Failure modes
+
+Errors come back as plain sentences; pass them to the user as-is rather than retrying:
+
+- a binary `.ppt` (PowerPoint 97-2003) — it must be re-saved as `.pptx`, the formats are unrelated
+- not a zip at all, or a zip without `ppt/slides/`
+- the deck exceeds the per-call page limit — extract page by page with `--slide`, or split the file
+- the file is too large, or unpacks to too much
+
+`flags` on a page is **not** an error: it records what the extractor refused to reconstruct. Surface it — a silently missing element on screen is worse than a mentioned one.

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

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""
+文档抽取脚本 — 通过 ab-render HTTP 接口实现，本地不需要任何 Office/解析依赖。
+
+调用链：
+  POST $RENDER_API_URL/extract        → { taskId }
+  POST $RENDER_API_URL/extractStatus  → { status, progress, result?, error? }
+
+两层产物（--fields）：
+  content   title / text[] / rawNotes —— 正文与备注页，轻量，不含任何 base64
+  layout    slide{nodes,beats,mode,…} —— 坐标形状，带内嵌图标，**体积很大**
+
+默认**不把完整结果打到 stdout**：一页 PPT 的 layout 带上内嵌图标可能几百 KB，
+直接进对话正文会撑爆上下文，还会让用户在聊天记录里滚过一屏 base64。默认写文件 +
+打一份人能读的摘要；确实要管道传全量时用 --json-output（或只要 content 层）。
+
+必要环境变量（由 ab-agent 自动注入）：
+  RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）
+  PRIV_TOKEN       ab-api 私有 token
+
+可选环境变量：
+  CONVERSATION_ID  对话 ID，用于留痕与产物归属
+"""
+
+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)
+
+
+# ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Document extraction — calls the ab-render /extract endpoint"
+    )
+    parser.add_argument("--url", required=True, help="Direct document URL (.pptx)")
+    parser.add_argument("--kind", default="pptx", choices=["pptx"], help="Document kind (default pptx)")
+    parser.add_argument("--slide", type=int, help="Only extract this 1-based page")
+    parser.add_argument(
+        "--fields", default="content,layout",
+        help="Comma-separated: content / layout (default both)",
+    )
+    parser.add_argument(
+        "--out", help="Write the full JSON result here (default: ./<name>.extract.json)",
+    )
+    parser.add_argument(
+        "--json-output", action="store_true",
+        help="Pipeline mode: emit the full JSON on stdout (careful: layout is large)",
+    )
+    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()]
+
+    # ── 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)
+        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
+
+    while elapsed < max_wait_sec:
+        time.sleep(poll_interval)
+        elapsed += poll_interval
+
+        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
+
+        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 __name__ == "__main__":
+    main()

package/skills/doc-parse/skill.json

@@ -0,0 +1,54 @@
+{
+  "name": "doc-parse",
+  "toolName": "doc_parse",
+  "tier": "tool",
+  "category": "consuming",
+  "title": "Document Extraction",
+  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+  "auth": "required",
+  "envVars": [
+    "RENDER_API_URL",
+    "PRIV_TOKEN",
+    "CONVERSATION_ID"
+  ],
+  "entry": {
+    "type": "python",
+    "scriptPath": "scripts/extract_via_render.py"
+  },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+      },
+      "kind": {
+        "type": "string",
+        "enum": ["pptx"],
+        "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+      },
+      "fields": {
+        "type": "string",
+        "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+      },
+      "slide": {
+        "type": "number",
+        "description": "Only extract this 1-based page. Omit for the whole deck."
+      },
+      "out": {
+        "type": "string",
+        "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+      },
+      "json_output": {
+        "type": "boolean",
+        "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+      }
+    },
+    "required": ["url"]
+  },
+  "ui": {
+    "primary": ["url", "fields"],
+    "advanced": ["slide", "kind"],
+    "hidden": ["out", "json_output"]
+  }
+}