@remixmate/cli 0.9.58 → 0.9.60

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.58",
-  "generatedAt": "2026-09-29T10:20:23.290Z",
+  "version": "0.9.60",
+  "generatedAt": "2026-09-30T02:10:05.308Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -82,7 +82,7 @@
       "tier": "orchestration",
       "category": "consuming",
       "title": "Jianying (CapCut) Draft Export",
-      "summary": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
+      "summary": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. By default exports the latest prepared render job of the current conversation (no scenes needed).",
       "triggers": [
         "Export to Jianying, Jianying draft, package for Jianying, import into Jianying",
         "Export materials to the Jianying format, generate a Jianying project",
@@ -102,13 +102,17 @@
       "parameters": {
         "type": "object",
         "properties": {
+          "from_job_id": {
+            "type": "number",
+            "description": "Render job id to export (the `jobId` printed by prepare_video_assets). Omit it together with scenes to export the latest prepared job of the current conversation — preferred, because asset URLs copied from chat history go stale after re-renders"
+          },
           "from_render_plan": {
             "type": "string",
-            "description": "Build the draft from a RenderPlan JSON (replaces --scenes)"
+            "description": "Build the draft from a local RenderPlan JSON file (local debugging only)"
           },
           "scenes": {
             "type": "string",
-            "description": "Scene array as JSON (inline string or file path)"
+            "description": "Hand-written scene array as JSON — only for assets that never went through prepare_video_assets. Fields per scene: imageUrl | videoUrl (one required), duration (seconds, required), audioUrl, audioDuration, subtitleText, textLayers, width, height. Any other field (text, image, audio…) is rejected"
           },
           "title": {
             "type": "string",
@@ -128,15 +132,15 @@
               "mac",
               "windows"
             ],
-            "description": "Draft-root preset"
+            "description": "OS of the computer that will open the draft"
           },
           "draft_root_path": {
             "type": "string",
-            "description": "Explicit Jianying draft root path (overrides --system)"
+            "description": "Absolute Jianying draft root on the user's computer (Jianying → Settings → Draft location), e.g. /Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft or C:/Users/<username>/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft. Required when the agent runs on a server; never guess the username, ask the user"
           },
           "no_download": {
             "type": "boolean",
-            "description": "Do not download the ZIP; print the URL only"
+            "description": "Do not keep a local copy of the ZIP; print the download URL only"
           },
           "output": {
             "type": "string",
@@ -147,7 +151,8 @@
       },
       "ui": {
         "primary": [
-          "system"
+          "system",
+          "draft_root_path"
         ],
         "advanced": [],
         "hidden": [
@@ -155,9 +160,9 @@
           "width",
           "height",
           "output",
+          "from_job_id",
           "from_render_plan",
           "scenes",
-          "draft_root_path",
           "no_download"
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.58",
+  "version": "0.9.60",
   "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/export-jianying/SKILL.md

@@ -44,24 +44,37 @@ There is no dedicated env file; the **process environment** variables of the cal
 
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_jianying_draft.py`; never hard-code paths.
 2. **Pick the input form**:
-   - **Form A (recommended)**: `--from-job-id` — load the RenderPlan from the database without passing a file path (safe for multi-user concurrent flows).
-   - **Form B (fallback, single-user / local debugging)**: `--from-render-plan` — read a local `render-plan.json`.
-3. **Draft root**: by default the `--system mac` preset resolves the target Jianying draft directory; switch with `--system windows`, or override with `--draft-root-path`. This path is sent to the API as `draftRootPath` and embedded in the draft files.
-4. **By default download the ZIP** locally (`--output` sets the path); pass `--no-download` if you only need the download URL (this flag is ignored when scenes contain `textLayers` / `subtitleText`).
+   - **Default (recommended)**: pass **no** `--scenes` / `--from-job-id`. When `CONVERSATION_ID` is set (always true inside the agent), the script exports the latest render job of this conversation that has prepared assets — i.e. whatever the user last re-rendered, including voices or images they changed in the editor.
+   - **`--from-job-id <jobId>`**: export a specific earlier job.
+   - **`--scenes`**: only for assets that never went through `prepare_video_assets`. **Never** rebuild scenes from URLs in the chat history: earlier tables go stale after every re-render, and you cannot see previous tool results.
+   - `--from-render-plan`: local debugging only.
+3. **Draft root**: pass the user's real Jianying draft directory via `--draft-root-path` (an absolute path on **the user's computer**). It is sent to the API as `draftRootPath` and embedded in the draft files, so a wrong path makes Jianying lose the media. If the user already gave a path (e.g. a `草稿目录` / `Draft folder` line in their message), use it verbatim. Otherwise ask for it — never guess the username. The path is only optional when this script runs on the user's own computer of the `--system` OS; anywhere else (e.g. a server-side agent) the script exits with an error asking for it.
+4. **Download URL**: pass `--no-download` in the agent (no local copy is kept). When subtitles / textLayers need styling the script still fetches the ZIP to a temp file, styles it, uploads it back and prints the URL of the **styled** ZIP. The printed `download URL:` is a signed link that expires after 7 days — give it to the user exactly as printed, including the whole `?Expires=…&Signature=…` query; never strip or re-encode it.
 5. **Async job**: draft generation is async (assets must be downloaded and packaged); the script polls until completion.
+6. **Report what is actually in the draft**: repeat the `📦 Draft contents` block (scene count, narration audio N/N, subtitles N/N, draft root). Don't claim subtitles or a particular voice version the block doesn't show.
 
-### Load the RenderPlan from the database (recommended, multi-user safe)
+### Export the latest prepared job of this conversation (default)
 
-When `prepare_video_assets` was invoked with `--save-job` (default) and persisted the RenderPlan, load it directly via `--from-job-id` — no file path required:
+```bash
+python3 <SkillDir>/scripts/gen_jianying_draft.py \
+  --system mac \
+  --draft-root-path "/Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft" \
+  --no-download
+```
+
+- Requires `PRIV_TOKEN` and `CONVERSATION_ID` (both injected by the agent). The title defaults to the plan's title.
+- Fails with a clear message if the conversation has no prepared job yet — run `prepare_video_assets` first.
+
+### Load a specific job from the database
 
 ```bash
 python3 <SkillDir>/scripts/gen_jianying_draft.py \
   --from-job-id <jobId> \
-  --title "My Video"
+  --system mac \
+  --draft-root-path "/Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft"
 ```
 
 - `<jobId>` is the task id printed by `prepare_video_assets` (the line `📦 render job jobId: N`).
-- Requires the `PRIV_TOKEN` and `MM_BACKEND_API_URL` env vars.
 
 ### Read from a RenderPlan file (fallback, single-user / local debugging)
 
@@ -145,23 +158,26 @@ python3 <SkillDir>/scripts/gen_jianying_draft.py \
 
 ### Specify the Jianying draft root
 
-Default is `--system mac`. Switch to the Windows preset:
+macOS:
 
 ```bash
 python3 <SkillDir>/scripts/gen_jianying_draft.py \
-  --title "Win draft" --system windows \
+  --title "Mac draft" --system mac \
+  --draft-root-path "/Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft" \
   --scenes '[{"videoUrl":"https://example.com/v.mp4","duration":5}]'
 ```
 
-Explicitly specify a path (overrides `--system`):
+Windows:
 
 ```bash
 python3 <SkillDir>/scripts/gen_jianying_draft.py \
-  --title "Custom path" \
-  --draft-root-path "/Users/yourname/Movies/JianyingPro/User Data/Projects/com.lveditor.draft" \
+  --title "Win draft" --system windows \
+  --draft-root-path "C:/Users/<username>/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft" \
   --scenes '[{"videoUrl":"https://example.com/v.mp4","duration":5}]'
 ```
 
+`<username>` is a placeholder for the user's real value — the script rejects paths that still contain `<...>`, start with `~`, contain `%VAR%` / `$VAR`, or are not absolute. Users who moved their draft folder can copy the exact path from Jianying → Settings → Draft location.
+
 ### Only print the download URL (no file write)
 
 ```bash
@@ -170,7 +186,7 @@ python3 <SkillDir>/scripts/gen_jianying_draft.py \
   --scenes '[{"videoUrl":"https://example.com/v.mp4","duration":5}]'
 ```
 
-6. **Show the result**: by default the script prints the download URL and saves the ZIP to `--output`. At the end it prints "extract into the draft root → restart Jianying" to import. With `--no-download`, only the download URL is printed.
+**Show the result**: the script prints `📦 Draft contents`, the signed `download URL:` and the import steps. Without `--no-download` it also keeps the ZIP at `--output`.
 
 See every option: `python3 <SkillDir>/scripts/gen_jianying_draft.py --help`.
 
@@ -178,31 +194,31 @@ See every option: `python3 <SkillDir>/scripts/gen_jianying_draft.py --help`.
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--from-render-plan` | Convert from a RenderPlan JSON automatically (replaces `--scenes`). | — |
-| `--from-job-id` | Load the RenderPlan from the database (pass a jobId, replaces `--from-render-plan`). | — |
-| `--scenes` | Scenes JSON (inline string or file path). | required (unless using `--from-render-plan` or `--from-job-id`) |
-| `--title` | Draft title. | required (optional when using `--from-render-plan`) |
+| `--from-job-id` | Load the RenderPlan of a specific job from the database. | latest prepared job of `CONVERSATION_ID` when no source is given |
+| `--from-render-plan` | Convert a local RenderPlan JSON (local debugging). | — |
+| `--scenes` | Hand-written scenes JSON (inline string or file path); unknown fields are rejected. | — |
+| `--title` | Draft title. | plan title (required with `--scenes`) |
 | `--width` | Canvas width in pixels. | `1080` |
 | `--height` | Canvas height in pixels. | `1920` |
 | `--draft-name` | Jianying draft name. | same as title |
-| `--system` | Draft-root preset: `mac` / `windows`. | `mac` |
-| `--draft-root-path` | Explicit Jianying draft root path (overrides `--system`). | resolved from `--system` |
-| `--no-download` | Skip the ZIP download; print only the URL (ignored when textLayers / subtitleText is present). | off |
+| `--system` | OS of the computer that will open the draft: `mac` / `windows`. | `mac` |
+| `--draft-root-path` | Absolute Jianying draft root on the user's computer. | required unless the script runs on that computer |
+| `--no-download` | Keep no local copy; print only the (post-processed, signed) URL. | off |
 | `-o` / `--output` | Download path. | `jianying_draft.zip` |
 | `--poll-interval` | Polling interval (seconds). | `5` |
 | `--max-wait` | Maximum wait time (seconds). | `300` |
 | `--private-token` | Override the token. | see table above |
 
-### Draft-root presets
+### Default draft roots
 
-| `--system` | Resolved path |
-|------------|---------------|
-| `mac` | `~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft` (`~` expands on the runner machine). |
-| `windows` | `%LOCALAPPDATA%/JianyingPro/User Data/Projects/com.lveditor.draft` (literal, not expanded — the target Windows machine resolves it). |
+| `--system` | Jianying default (replace `<username>`) | Derived automatically only when |
+|------------|------------------------------------------|---------------------------------|
+| `mac` | `/Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft` | the script runs on macOS |
+| `windows` | `C:/Users/<username>/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft` | the script runs on Windows with `LOCALAPPDATA` set |
 
 ## Scene JSON shape
 
-Fields supported per scene:
+Fields supported per scene (anything else — e.g. `text`, `image`, `audio` — makes the script exit with the correct field name; `id` is ignored):
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -240,11 +256,8 @@ When `textLayers` is present the script downloads the ZIP and post-processes `dr
 
 ## How to import into Jianying
 
-1. By default the draft ZIP is saved to `--output` (default `jianying_draft.zip`).
-2. Extract the ZIP into the "draft root" the script prints — i.e. the `draftRootPath` passed to the API:
-   - mac default: `~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft/`
-   - windows default: `%LOCALAPPDATA%/JianyingPro/User Data/Projects/com.lveditor.draft/`
-   - custom: the path passed via `--draft-root-path`
+1. Download the ZIP from the printed `download URL:` (or use the local `--output` file).
+2. Extract the ZIP into exactly the draft root that was passed as `--draft-root-path` (the script prints it as `draft root:`). Tell the user that path verbatim — not a generic `~/...` one.
 3. Start (or restart) Jianying; the draft appears in the project list.
 
 > The backend embeds `draftRootPath` into `draft_content.json` / `draft_meta_info.json`. As long as the extraction directory matches the path that was passed in, Jianying resolves the material paths correctly without extra rewrites.
@@ -253,5 +266,8 @@ When `textLayers` is present the script downloads the ZIP and post-processes `dr
 
 - **401** / **token missing** (non-OpenClaw): check or set the token via the Feishu link above.
 - **Business `code != 0`**: read the `msg` printed on stderr.
+- **`unsupported field(s)`**: rename the field as the message says — or better, drop `--scenes` and export the latest job.
+- **`no render job with a saved RenderPlan`**: the conversation has no prepared assets yet; run `prepare_video_assets` first.
+- **`--draft-root-path is required` / `invalid --draft-root-path`**: ask the user for the real path; don't retry with a guessed one.
 - **Generation timeout**: increase `--max-wait` or retry later.
 - **Network**: check connectivity and `MM_API_BASE_URL`.

package/skills/export-jianying/scripts/gen_jianying_draft.py

@@ -22,7 +22,9 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
+import tempfile
 import time
 import urllib.error
 import urllib.parse
@@ -75,30 +77,87 @@ PILL_SUBTITLE_POSITION_Y = -0.458
 # 剪映草稿根目录解析
 # ---------------------------------------------------------------------------
 
-DRAFT_ROOT_PRESETS = {
-    "mac": "~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft",
-    # Windows 预设保留字面量 %LOCALAPPDATA%：在 Mac 上执行时不展开，
-    # 原样传给 API；用户在 Windows 解压时目录会自然匹配。
-    "windows": "%LOCALAPPDATA%/JianyingPro/User Data/Projects/com.lveditor.draft",
+# 剪映把 draftRootPath 原样写进 draft_meta_info.json（draft_root_path / draft_fold_path），
+# 所以它必须是**用户电脑上**的绝对路径。
+#
+# 2026-09-29 事故：agent 在服务器上跑本脚本，mac 预设 `~/...` 被 expanduser 成
+# `/root/Movies/...` 写进了草稿，用户 Mac 上根本没有这个目录。`~` / `%LOCALAPPDATA%`
+# 只能在「脚本就跑在那台目标电脑上」时展开，其余情况必须由调用方显式给出路径。
+DRAFT_ROOT_SUFFIX = ("JianyingPro", "User Data", "Projects", "com.lveditor.draft")
+
+# 报错时给调用方看的路径样例（<username> 要换成用户电脑上的真实用户名）。
+DRAFT_ROOT_TEMPLATES = {
+    "mac": "/Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft",
+    "windows": "C:/Users/<username>/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft",
 }
 
+_WINDOWS_ABS_PATH = re.compile(r"^[A-Za-z]:[\\/]")
+
+
+def draft_root_path_error(path: str) -> str:
+    """校验显式给出的草稿根目录；合法返回空串，否则返回原因。"""
+    if "<" in path or ">" in path:
+        return "still contains a placeholder such as <username>; replace it with the real value"
+    if path.startswith("~"):
+        return "'~' would expand on the machine running this script, not on the user's computer; pass an absolute path"
+    if "%" in path or "$" in path:
+        return "environment variables are not expanded; pass an absolute path"
+    if not (path.startswith("/") or _WINDOWS_ABS_PATH.match(path)):
+        return "must be an absolute path (/Users/... on macOS, C:/... on Windows)"
+    return ""
+
+
+def _local_draft_root(system: str) -> str:
+    """脚本恰好跑在目标系统上时，按本机环境推出草稿根目录；推不出返回空串。"""
+    if system == "mac" and sys.platform == "darwin":
+        return os.path.join(os.path.expanduser("~/Movies"), *DRAFT_ROOT_SUFFIX)
+    if system == "windows" and os.name == "nt":
+        local_app_data = os.environ.get("LOCALAPPDATA", "")
+        if local_app_data:
+            return os.path.join(local_app_data, *DRAFT_ROOT_SUFFIX)
+    return ""
+
 
 def resolve_draft_root_path(explicit: str, system: str) -> str:
     """
     解析剪映草稿根目录，按优先级：
-    1. 显式 --draft-root-path（做 expanduser）
-    2. --system 预设（mac → expanduser，windows → 字面量）
+    1. 显式 --draft-root-path：原样使用（不做 expanduser），但必须是绝对路径；
+    2. 未给路径且脚本就跑在 --system 指定的系统上：按本机 HOME / LOCALAPPDATA 推出；
+    3. 其余情况（典型是服务端 agent）：报错，要求调用方向用户要路径。
     返回值始终作为 draftRootPath 传给 API。
     """
-    if explicit:
-        return os.path.expanduser(explicit)
-    preset = DRAFT_ROOT_PRESETS.get(system)
-    if not preset:
+    if system not in DRAFT_ROOT_TEMPLATES:
         print(f"❌ unsupported --system value: {system} (supported: mac / windows)", file=sys.stderr)
         sys.exit(1)
-    if system == "mac":
-        return os.path.expanduser(preset)
-    return preset
+    template = DRAFT_ROOT_TEMPLATES[system]
+
+    if explicit:
+        path = explicit.strip()
+        # 去掉末尾分隔符，但保留 "C:/" 与 "/" 这种根本身。
+        while len(path) > 3 and path[-1] in "/\\":
+            path = path[:-1]
+        reason = draft_root_path_error(path)
+        if reason:
+            print(f"❌ invalid --draft-root-path {path!r}: {reason}", file=sys.stderr)
+            print(f"   expected shape on {system}: {template}", file=sys.stderr)
+            sys.exit(1)
+        return path
+
+    local = _local_draft_root(system)
+    if local:
+        return local
+
+    print(
+        f"❌ --draft-root-path is required: this script is not running on the user's {system} computer, "
+        f"so the Jianying draft directory cannot be derived here.",
+        file=sys.stderr,
+    )
+    print(f"   expected shape: {template}", file=sys.stderr)
+    print(
+        "   Ask the user for the real path (Jianying → Settings → Draft location) and pass it via --draft-root-path.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
 
 
 def resolve_token() -> str:
@@ -456,6 +515,42 @@ def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
     return scenes, width, height
 
 
+# --scenes 里认的字段。后端 JianYingSceneInput 只收前 8 个，textLayers 由本脚本后处理消费。
+SCENE_FIELDS = (
+    "videoUrl", "imageUrl", "duration", "width", "height",
+    "audioUrl", "audioDuration", "subtitleText", "textLayers",
+)
+# 纯标识、不影响草稿内容的字段：写了也无害，放行。
+SCENE_IGNORED_FIELDS = ("id", "sceneId")
+# 常见误写 → 正确字段名。
+#
+# 2026-09-29 线上会话：模型先写 image/audio 被拦，改成 imageUrl/audioUrl 后却把旁白
+# 写成了 text —— 这个字段以前被静默丢掉，草稿里没有字幕，模型还告诉用户「已包含字幕」。
+# 未知字段一律报错，比静默丢值强。
+SCENE_FIELD_ALIASES = {
+    "image": "imageUrl", "img": "imageUrl", "imageURL": "imageUrl", "image_url": "imageUrl",
+    "video": "videoUrl", "videoURL": "videoUrl", "video_url": "videoUrl",
+    "audio": "audioUrl", "audioURL": "audioUrl", "audio_url": "audioUrl",
+    "narration": "subtitleText", "text": "subtitleText", "subtitle": "subtitleText",
+    "caption": "subtitleText", "subtitle_text": "subtitleText",
+    "audio_duration": "audioDuration",
+}
+
+
+def unknown_field_error(index: int, scene: dict) -> None:
+    """scene 里出现不认识的字段就退出，并指出该用哪个字段名。"""
+    unknown = [k for k in scene if k not in SCENE_FIELDS and k not in SCENE_IGNORED_FIELDS]
+    if not unknown:
+        return
+    hints = []
+    for key in unknown:
+        target = SCENE_FIELD_ALIASES.get(key)
+        hints.append(f"'{key}' → use '{target}'" if target else f"'{key}' is not supported")
+    print(f"❌ scene {index + 1} has unsupported field(s): {'; '.join(hints)}", file=sys.stderr)
+    print(f"   supported fields: {', '.join(SCENE_FIELDS)}", file=sys.stderr)
+    sys.exit(1)
+
+
 def parse_scenes(scenes_arg: str) -> list:
     """解析 --scenes 参数：支持 inline JSON 字符串或文件路径"""
     # 尝试作为文件路径读取
@@ -489,6 +584,7 @@ def parse_scenes(scenes_arg: str) -> list:
         if not isinstance(scene, dict):
             print(f"❌ scene {i + 1} is malformed: must be an object", file=sys.stderr)
             sys.exit(1)
+        unknown_field_error(i, scene)
         if not scene.get("videoUrl") and not scene.get("imageUrl"):
             print(f"❌ scene {i + 1} is missing videoUrl or imageUrl", file=sys.stderr)
             sys.exit(1)
@@ -626,13 +722,80 @@ def poll_task_status(task_id: str, poll_interval: int = 5, max_wait: int = 300)
 def _encode_url(raw_url: str) -> str:
     """对 URL 中的非 ASCII 字符做 percent-encoding（保留已编码部分和合法字符）"""
     parsed = urllib.parse.urlparse(raw_url)
-    encoded_path = urllib.parse.quote(parsed.path, safe="/:@!$&'()*+,;=-._~")
+    # '%' 必须留在 safe 里：ab-api 返回的地址已经是编码过的（中文文件名 → %E9%A3…），
+    # 再编一次会变成 %25E9，对象 key 对不上；带签名的地址还会 SignatureDoesNotMatch。
+    encoded_path = urllib.parse.quote(parsed.path, safe="/:@!$&'()*+,;=-._~%")
     return urllib.parse.urlunparse(parsed._replace(path=encoded_path))
 
 
+class DraftUploadError(RuntimeError):
+    """后处理 ZIP 传回失败。调用方据此降级为交付后端原始 ZIP，而不是整次导出失败。"""
+
+
+def upload_draft_zip(zip_path: str, file_name: str) -> str:
+    """
+    把后处理过的 ZIP 传回 ab-api（POST /file/uploadJianYingDraft），返回带签名的下载地址。
+    失败抛 DraftUploadError（带 HTTP 状态码 / 业务 msg）。
+
+    为什么必须传回：后处理（字幕样式 / textLayers）是在跑脚本的这台机器上做的。
+    服务端 agent 的本地文件用户拿不到，不传回的话用户下载到的仍是后端生成的原始 ZIP，
+    后处理等于白做。
+    """
+    boundary = "----RemixmateJianYing" + uuid.uuid4().hex
+    with open(zip_path, "rb") as f:
+        zip_data = f.read()
+    # filename 里放 ASCII 占位，真实（可能含中文的）文件名走独立的 fileName 字段，
+    # 避免 multipart 头部编码在不同服务端实现间的差异。
+    parts = [
+        f"--{boundary}".encode(),
+        b'Content-Disposition: form-data; name="fileName"',
+        b"",
+        file_name.encode("utf-8"),
+        f"--{boundary}".encode(),
+        b'Content-Disposition: form-data; name="file"; filename="draft.zip"',
+        b"Content-Type: application/zip",
+        b"",
+        zip_data,
+        f"--{boundary}--".encode(),
+        b"",
+    ]
+    body = b"\r\n".join(parts)
+
+    print(f"\n⬆️  Uploading post-processed draft ({len(zip_data) / 1024 / 1024:.1f} MB)...")
+    req = urllib.request.Request(
+        f"{API_BASE_URL}/file/uploadJianYingDraft",
+        data=body,
+        headers=_build_headers(f"multipart/form-data; boundary={boundary}"),
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=600) as resp:
+            raw = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        # 网关（413 请求体过大、404 路由未上线）返回的是 HTML，只取一小段帮定位。
+        snippet = e.read().decode("utf-8", errors="replace")[:200].replace("\n", " ")
+        raise DraftUploadError(f"HTTP {e.code} {e.reason}: {snippet}") from e
+    except (urllib.error.URLError, OSError, ConnectionError) as e:
+        raise DraftUploadError(f"network error: {e}") from e
+
+    try:
+        result = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise DraftUploadError(f"non-JSON response: {raw[:200]}") from e
+    if result.get("code") != 0:
+        raise DraftUploadError(f"API error: {result.get('msg', 'unknown error')}")
+    url = (result.get("data") or {}).get("downloadUrl", "")
+    if not url:
+        raise DraftUploadError("upload succeeded but no download URL was returned")
+    print("   ✅ uploaded")
+    return url
+
+
 def download_zip(download_url: str, output_path: str) -> None:
     """下载 ZIP 文件到本地"""
-    print(f"\n⬇️  Downloading draft ZIP: {download_url[:80]}...")
+    # 不打印地址：去掉签名的地址打开就是 403，而模型会把 stdout 里任何像链接的东西
+    # 转交给用户（conv_U9oYmHmE1iJbx2qETDuh 就是把这一行当成了下载链接）。
+    print("\n⬇️  Downloading draft ZIP for post-processing...")
     safe_url = _encode_url(download_url)
     try:
         urllib.request.urlretrieve(safe_url, output_path)
@@ -906,6 +1069,39 @@ def has_text_layers(scenes: list) -> bool:
     return any(scene.get("textLayers") for scene in scenes)
 
 
+def _render_job_client():
+    """
+    导入共享的 render_job_client（在 skills/template-registry/scripts/，跨 skill 共享
+    Python 的约定位置，render-video 也是这么引的）。
+    """
+    shared = os.path.join(os.path.dirname(__file__), "..", "..", "template-registry", "scripts")
+    if shared not in sys.path:
+        sys.path.insert(0, shared)
+    import render_job_client  # noqa: PLC0415 — 路径注入之后才能导入
+
+    return render_job_client
+
+
+def print_draft_summary(scenes: list, width: int, height: int, draft_root_path: str) -> None:
+    """
+    打印草稿里**实际**装了什么。
+
+    调用方（agent）要据此向用户转述，而不是凭自己传了什么去猜——线上会话里模型把
+    被丢掉的字幕也说成「已包含」。
+    """
+    total = len(scenes)
+    video = sum(1 for s in scenes if s.get("videoUrl"))
+    image = sum(1 for s in scenes if s.get("imageUrl") and not s.get("videoUrl"))
+    audio = sum(1 for s in scenes if s.get("audioUrl"))
+    subtitle = sum(1 for s in scenes if s.get("subtitleText") or s.get("textLayers"))
+    duration = sum(float(s.get("duration") or 0) for s in scenes)
+    print("\n📦 Draft contents:")
+    print(f"   scenes: {total} (video {video}, image {image}), total {duration:.1f}s, canvas {width}x{height}")
+    print(f"   narration audio: {audio}/{total} scene(s)")
+    print(f"   subtitles / text layers: {subtitle}/{total} scene(s)")
+    print(f"   draft root written into the draft: {draft_root_path}")
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(
         description="Jianying draft generator — packages asset URLs into a Jianying-importable draft ZIP",
@@ -941,7 +1137,10 @@ Scene fields:
         "--from-job-id",
         type=int,
         default=0,
-        help="Load the RenderPlan from the database (pass a jobId, replaces --from-render-plan; requires PRIV_TOKEN)",
+        help=(
+            "Load the RenderPlan from the database (pass a jobId; requires PRIV_TOKEN). When no source is given "
+            "and CONVERSATION_ID is set, the latest prepared job of that conversation is used automatically"
+        ),
     )
     parser.add_argument("--width", type=int, default=1080, help="Canvas width (default 1080)")
     parser.add_argument("--height", type=int, default=1920, help="Canvas height (default 1920)")
@@ -950,17 +1149,24 @@ Scene fields:
         "--system",
         choices=["mac", "windows"],
         default="mac",
-        help="Pick the draft-root preset by OS (default: mac)",
+        help="OS of the computer that will open the draft (default: mac)",
     )
     parser.add_argument(
         "--draft-root-path",
         default="",
-        help="Explicitly specify the Jianying draft root path (overrides the --system preset)",
+        help=(
+            "Absolute Jianying draft root on the user's computer, e.g. "
+            f"{DRAFT_ROOT_TEMPLATES['mac']} or {DRAFT_ROOT_TEMPLATES['windows']}. "
+            "Required unless this script runs on that computer itself; '~' and %%VARS%% are rejected"
+        ),
     )
     parser.add_argument(
         "--no-download",
         action="store_true",
-        help="Skip the ZIP download; only print the download URL (ignored when scenes include textLayers / subtitleText)",
+        help=(
+            "Do not keep a local copy of the ZIP; only print the download URL. When subtitles / textLayers "
+            "need post-processing the ZIP is fetched to a temp file, styled, uploaded back and the temp file removed"
+        ),
     )
     parser.add_argument("-o", "--output", default=None, help="Download path (default jianying_draft_{timestamp}.zip, prevents multi-user collisions)")
     parser.add_argument("--poll-interval", type=int, default=5, help="Polling interval (seconds, default 5)")
@@ -980,22 +1186,46 @@ Scene fields:
         print("❌ PrivToken not configured", file=sys.stderr)
         sys.exit(1)
 
+    conversation_id = os.environ.get("CONVERSATION_ID", "").strip()
+
+    # 没给任何素材来源、但处在一个会话里（ab-agent 会注入 CONVERSATION_ID）：
+    # 默认导出这个会话最近一版已准备好素材的任务。
+    if not (args.from_job_id or args.from_render_plan or args.scenes) and conversation_id:
+        rjc = _render_job_client()
+        try:
+            latest = rjc.latest_job(conversation_id, PRIVATE_TOKEN)
+        except RuntimeError as e:
+            print(f"❌ could not find the latest prepared render job of this conversation: {e}", file=sys.stderr)
+            print("   run prepare_video_assets first, or pass --from-job-id / --scenes", file=sys.stderr)
+            sys.exit(1)
+        args.from_job_id = int(latest["jobId"])
+        print(
+            f"📋 using the latest prepared render job of this conversation: "
+            f"jobId={args.from_job_id} (attempt {latest.get('attempt', '?')}, updated {latest.get('updateTime', '?')})"
+        )
+    elif args.scenes and conversation_id:
+        # 手写 scenes 时模型只能从聊天记录里拼素材 URL，而多轮之间它看不到之前的工具结果，
+        # 很容易拼出过期的旧版素材（线上会话里就是把用户改过的 v3 配音换回了 v1）。
+        #
+        # 只在会话里**真有**准备好的任务时才提醒：纯数字人 / 纯生图的会话没有 RenderPlan，
+        # 手写 scenes 是唯一的路，这时提醒只会让模型怀疑自己（conv_U9oYmHmE1iJbx2qETDuh）。
+        try:
+            latest = _render_job_client().latest_job(conversation_id, PRIVATE_TOKEN)
+        except RuntimeError:
+            latest = None
+        if latest:
+            print(
+                f"⚠️  --scenes was hand-written, but this conversation has a prepared render job "
+                f"(jobId={latest['jobId']}); omit --scenes to export it instead of URLs copied from chat history",
+                file=sys.stderr,
+            )
+
     # --from-job-id 模式：从数据库加载 RenderPlan
     if args.from_job_id:
         print(f"📋 loading RenderPlan from database (jobId={args.from_job_id})...")
-        if not PRIVATE_TOKEN:
-            print("❌ --from-job-id mode requires PRIV_TOKEN", file=sys.stderr)
-            sys.exit(1)
-        # render_job_client lives in skills/template-registry/scripts/ — the
-        # shared location for cross-skill Python helpers (matches the pattern
-        # render-video uses for the same import).
-        _template_registry_scripts = os.path.join(
-            os.path.dirname(__file__), "..", "..", "template-registry", "scripts"
-        )
-        sys.path.insert(0, _template_registry_scripts)
-        from render_job_client import get_plan as rjc_get_plan
+        rjc = _render_job_client()
         try:
-            render_plan_str = rjc_get_plan(args.from_job_id, PRIVATE_TOKEN)
+            render_plan_str = rjc.get_plan(args.from_job_id, PRIVATE_TOKEN)
         except RuntimeError as e:
             print(f"❌ failed to fetch RenderPlan: {e}", file=sys.stderr)
             sys.exit(1)
@@ -1029,7 +1259,7 @@ Scene fields:
     else:
         # 传统模式：必须提供 --scenes 和 --title
         if not args.scenes:
-            print("❌ provide --scenes or --from-render-plan", file=sys.stderr)
+            print("❌ provide --from-job-id, --from-render-plan or --scenes", file=sys.stderr)
             parser.print_help()
             sys.exit(1)
         if not args.title:
@@ -1063,34 +1293,57 @@ Scene fields:
     result_data = poll_task_status(task_id, args.poll_interval, args.max_wait)
 
     download_url = result_data.get("downloadUrl", "")
-    file_name = result_data.get("fileName", "")
+    file_name = result_data.get("fileName", "") or "jianying_draft.zip"
 
     if not download_url:
         print("❌ generation finished but no download URL was returned", file=sys.stderr)
         sys.exit(1)
 
     print(f"\n🎉 Jianying draft generated successfully!")
-    if file_name:
-        print(f"   filename: {file_name}")
-    print(f"   download URL: {download_url}")
+    print(f"   filename: {file_name}")
 
-    # 默认下载 ZIP；含 textLayers/subtitleText 时强制下载以便后处理
-    if args.no_download and not needs_postprocess:
-        print(f"\n💡 To download the ZIP, drop --no-download (or open the URL above)")
-        return
-
-    if args.no_download and needs_postprocess:
-        print("⚠️  textLayers/subtitleText detected; --no-download is ignored (post-processing is local)")
-
-    output_path = args.output or f"jianying_draft_{int(time.time())}.zip"
-    download_zip(download_url, output_path)
-
-    # 后处理 textLayers / Pill 字幕样式
+    # 在 agent 里（有 CONVERSATION_ID）本地文件落在服务器上，用户拿不到：除非显式给了
+    # --output，否则不留副本。conv_U9oYmHmE1iJbx2qETDuh 一次导出在服务器 cwd 里留了 3 个 5MB 的 ZIP。
+    keep_local = bool(args.output) or (not args.no_download and not conversation_id)
+    styled = True
+    output_path = ""
+    if needs_postprocess:
+        # 后处理必须先把 ZIP 拿到本地；不保留副本时落到临时文件，用完删掉。
+        if keep_local:
+            output_path = args.output or f"jianying_draft_{int(time.time())}.zip"
+        else:
+            fd, output_path = tempfile.mkstemp(prefix="jianying_draft_", suffix=".zip")
+            os.close(fd)
+        try:
+            download_zip(download_url, output_path)
+            postprocess_draft_zip(output_path, scenes)
+            # 用户拿到的链接必须指向后处理之后的版本，否则字幕样式 / textLayers 全部丢失。
+            download_url = upload_draft_zip(output_path, file_name)
+        except DraftUploadError as e:
+            # 降级而不是失败：后端生成的原始 ZIP 已经包含素材、配音和字幕文本，只是没有
+            # 套字幕样式 / textLayers。整次失败的话模型只会原样重试（每次再生成一遍草稿），
+            # 用户什么都拿不到。
+            styled = False
+            print(f"⚠️  could not upload the styled draft ({e}); delivering the backend draft instead.", file=sys.stderr)
+            print("   subtitle text is included, but the pill subtitle style / textLayers were NOT applied. "
+                  "Do not retry the same call; report this to the user.", file=sys.stderr)
+        finally:
+            if not keep_local and os.path.exists(output_path):
+                os.remove(output_path)
+                output_path = ""
+    elif keep_local:
+        output_path = args.output or f"jianying_draft_{int(time.time())}.zip"
+        download_zip(download_url, output_path)
+
+    print_draft_summary(scenes, args.width, args.height, draft_root_path)
     if needs_postprocess:
-        postprocess_draft_zip(output_path, scenes)
+        print(f"   subtitle styling applied: {'yes' if styled else 'NO (upload failed, backend draft delivered)'}")
+    print(f"\n   download URL: {download_url}")
+    if output_path:
+        print(f"   local file: {output_path}")
 
     print(f"\n💡 How to import into Jianying:")
-    print(f"   1. Extract {output_path} into the Jianying draft directory:")
+    print(f"   1. Download and extract the ZIP into exactly this directory on the user's computer:")
     print(f"      {draft_root_path}")
     print(f"   2. Start or restart Jianying; the draft will appear in your project list")
 

package/skills/export-jianying/skill.json

@@ -4,7 +4,7 @@
   "tier": "orchestration",
   "category": "consuming",
   "title": "Jianying (CapCut) Draft Export",
-  "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
+  "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. By default exports the latest prepared render job of the current conversation (no scenes needed).",
   "auth": "required",
   "envVars": [
     "PRIV_TOKEN",
@@ -15,13 +15,17 @@
   "parameters": {
     "type": "object",
     "properties": {
+      "from_job_id": {
+        "type": "number",
+        "description": "Render job id to export (the `jobId` printed by prepare_video_assets). Omit it together with scenes to export the latest prepared job of the current conversation — preferred, because asset URLs copied from chat history go stale after re-renders"
+      },
       "from_render_plan": {
         "type": "string",
-        "description": "Build the draft from a RenderPlan JSON (replaces --scenes)"
+        "description": "Build the draft from a local RenderPlan JSON file (local debugging only)"
       },
       "scenes": {
         "type": "string",
-        "description": "Scene array as JSON (inline string or file path)"
+        "description": "Hand-written scene array as JSON — only for assets that never went through prepare_video_assets. Fields per scene: imageUrl | videoUrl (one required), duration (seconds, required), audioUrl, audioDuration, subtitleText, textLayers, width, height. Any other field (text, image, audio…) is rejected"
       },
       "title": {
         "type": "string",
@@ -41,15 +45,15 @@
           "mac",
           "windows"
         ],
-        "description": "Draft-root preset"
+        "description": "OS of the computer that will open the draft"
       },
       "draft_root_path": {
         "type": "string",
-        "description": "Explicit Jianying draft root path (overrides --system)"
+        "description": "Absolute Jianying draft root on the user's computer (Jianying → Settings → Draft location), e.g. /Users/<username>/Movies/JianyingPro/User Data/Projects/com.lveditor.draft or C:/Users/<username>/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft. Required when the agent runs on a server; never guess the username, ask the user"
       },
       "no_download": {
         "type": "boolean",
-        "description": "Do not download the ZIP; print the URL only"
+        "description": "Do not keep a local copy of the ZIP; print the download URL only"
       },
       "output": {
         "type": "string",
@@ -60,7 +64,8 @@
   },
   "ui": {
     "primary": [
-      "system"
+      "system",
+      "draft_root_path"
     ],
     "advanced": [],
     "hidden": [
@@ -68,9 +73,9 @@
       "width",
       "height",
       "output",
+      "from_job_id",
       "from_render_plan",
       "scenes",
-      "draft_root_path",
       "no_download"
     ]
   }

package/skills/export-jianying/version.json

@@ -2,6 +2,6 @@
   "skillName": "export-jianying",
   "repoName": "agent-skill-media-maker",
   "skillId": "554",
-  "version": "V4",
+  "version": "V7",
   "skillDescription": "Jianying (CapCut) draft-generation skill. Packages asset URLs into a draft ZIP that Jianying can import; supports automatic conversion from a RenderPlan (calls ab-api /file/generateJianYing).\n\nUse this skill as soon as the user mentions any of these intents:\n- Export to Jianying, Jianying draft, package for Jianying, import into Jianying\n- Export materials to the Jianying format, generate a Jianying project\n- Bundle video / image / audio into a Jianying draft\n- Export a Jianying draft from a RenderPlan\n\nEven when the user does not say \"Jianying\" explicitly, use this skill whenever they want to package materials into a draft that can be edited in Jianying."
 }

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

@@ -1516,7 +1516,12 @@ def resolve_digital_human_segments(
                     else:
                         local = dhs.concat_drive_audio(pieces, out_dir, asset_id, ffmpeg)
                         from upload_video import upload_media_file
-                        url = upload_media_file(local, title=f"digital-human drive {asset_id}")["fileUrl"]
+                        url = upload_media_file(
+                            local,
+                            title=f"digital-human drive {asset_id}",
+                            role="dh_drive_audio",
+                            retention="intermediate",
+                        )["fileUrl"]
                         total = sum(p["durationSec"] for p in pieces)
                         log(f"{asset_id}: drive audio for {len(pieces)} scene(s), {total:.1f}s")
                 payload["audioUrl"] = url
@@ -3064,11 +3069,18 @@ Examples:
 
                 upload_title = upload_title_hint
                 LogPrint(f"\n📤 Uploading video to OSS...", file=sys.stderr)
-                upload_result = upload_media_file(file_path=output_path, title=upload_title)
+                upload_result = upload_media_file(
+                    file_path=output_path,
+                    title=upload_title,
+                    role="final_video",
+                    retention="output",
+                )
                 manifest["upload"] = {
                     "fileUrl": upload_result["fileUrl"],
                     "title": upload_title,
                     "uploadedAt": now_iso(),
+                    # ab-api 保存 manifest 时按 fileId 给成片建语义卡 / 片段 / 血缘
+                    "fileId": upload_result.get("fileId"),
                 }
                 if manifest_path:
                     save_json(manifest, manifest_path)

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

@@ -8,9 +8,11 @@
   `<MM_API_BASE_URL>/file/uploadMediaFile`，解析响应 JSON，输出 fileUrl。
 
 用法:
-  python3 upload_video.py --file output/video.mp4
-  python3 upload_video.py --file output/video.mp4 --title "我的视频"
-  python3 upload_video.py --file output/video.mp4 --json-output
+  python3 upload_video.py --file output/video.mp4 --role final_video
+  python3 upload_video.py --file output/video.mp4 --role final_video --title "我的视频"
+  python3 upload_video.py --file output/video.mp4 --role final_video --json-output
+
+环境变量 PRIV_TOKEN 必填（接口在 ab-api 私有组，产物落素材表并归到调用者名下）。
 
 环境变量:
   MM_API_BASE_URL - API 根地址（默认 MM_API_BASE_URL 环境变量或 https://api-agent.remixmate.ai/api）
@@ -39,9 +41,9 @@ def _guess_content_type(file_path: str) -> str:
     return ctype or "application/octet-stream"
 
 
-def _build_multipart_body(file_path: str, title: str = None) -> (bytes, str):
+def _build_multipart_body(file_path: str, fields: dict) -> (bytes, str):
     """
-    手动构建 multipart/form-data body。
+    手动构建 multipart/form-data body。fields 里值为空的字段不发。
 
     返回 (body_bytes, content_type_header)。
     """
@@ -49,12 +51,13 @@ def _build_multipart_body(file_path: str, title: str = None) -> (bytes, str):
     crlf = b"\r\n"
     parts = []
 
-    # title 字段（可选）
-    if title:
+    for name, value in fields.items():
+        if value in (None, ""):
+            continue
         parts.append(("--" + boundary).encode("utf-8"))
-        parts.append(b'Content-Disposition: form-data; name="title"')
+        parts.append(f'Content-Disposition: form-data; name="{name}"'.encode("utf-8"))
         parts.append(b"")
-        parts.append(title.encode("utf-8"))
+        parts.append(str(value).encode("utf-8"))
 
     # file 字段
     file_name = os.path.basename(file_path)
@@ -87,13 +90,21 @@ def upload_media_file(
     api_base_url: str = None,
     title: str = None,
     timeout: int = 600,
+    *,
+    role: str,
+    retention: str = None,
 ) -> dict:
     """
-    将本地媒体文件以 multipart/form-data 形式上传到 ab-api。
+    将本地媒体文件以 multipart/form-data 形式上传到 ab-api，并落素材表。
+
+    role 必填：素材语义角色（final_video / dh_drive_audio / source_audio ...），由调用方
+    按「这是什么」声明——ab-api 不再按文件类型猜。retention 可选（intermediate / output / user）。
 
-    返回服务端 data 字段，通常形如 {"fileUrl": "https://..."}。
+    返回服务端 data 字段，形如 {"fileUrl": "https://...", "fileId": 123, "fileUid": "file_xxx"}。
     上传失败会抛出异常。
     """
+    if not role:
+        raise ValueError("upload_media_file: role is required")
     if not os.path.exists(file_path):
         raise FileNotFoundError(f"file not found: {file_path}")
 
@@ -101,14 +112,22 @@ def upload_media_file(
     url = f"{api_base_url}/file/uploadMediaFile"
 
     file_size = os.path.getsize(file_path)
-    print(f"📤 Uploading: {file_path} ({file_size / 1024 / 1024:.2f} MB)", file=sys.stderr)
+    print(f"📤 Uploading: {file_path} ({file_size / 1024 / 1024:.2f} MB, role={role})", file=sys.stderr)
     print(f"   target: {url}", file=sys.stderr)
 
-    body, content_type = _build_multipart_body(file_path, title=title)
+    body, content_type = _build_multipart_body(
+        file_path, {"title": title, "role": role, "retention": retention}
+    )
+    # 该接口在 ab-api 私有组：产物要落素材表、归到调用者名下，必须带 PrivToken。
     headers = {
         "Content-Type": content_type,
         "Content-Length": str(len(body)),
+        "X-Priv-Token": os.environ.get("PRIV_TOKEN", ""),
+        "x-invoke-skill": "render-video",
     }
+    conversation_id = os.environ.get("CONVERSATION_ID", "")
+    if conversation_id:
+        headers["x-conversation-id"] = conversation_id
 
     # Use http.client directly to avoid urllib RemoteDisconnected issues
     # with servers that return 'connection: close'
@@ -161,6 +180,17 @@ def main():
     parser = argparse.ArgumentParser(description="Upload a media file to ab-api / Alibaba Cloud OSS")
     parser.add_argument("--file", required=True, help="Local file path")
     parser.add_argument("--title", default=None, help="File title (optional, defaults to filename)")
+    parser.add_argument(
+        "--role",
+        required=True,
+        help="Asset role, e.g. final_video / dh_drive_audio / source_audio (required)",
+    )
+    parser.add_argument(
+        "--retention",
+        default=None,
+        choices=["intermediate", "output", "user"],
+        help="Retention policy (optional)",
+    )
     parser.add_argument(
         "--api-base-url",
         default=None,
@@ -177,6 +207,8 @@ def main():
             api_base_url=args.api_base_url,
             title=args.title,
             timeout=args.timeout,
+            role=args.role,
+            retention=args.retention,
         )
     except Exception as e:
         print(f"❌ {e}", file=sys.stderr)

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V33",
+  "version": "V34",
   "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/render_job_client.py

@@ -172,6 +172,23 @@ def save_manifest(job_id: int, manifest: dict, priv_token: str) -> None:
     _post("/renderJob/saveManifest", {"jobId": job_id, "manifest": manifest}, priv_token)
 
 
+def latest_job(conversation_id: str, priv_token: str) -> dict:
+    """
+    按会话取最近一次**已存 RenderPlan** 的渲染任务摘要（POST /renderJob/latest）。
+
+    多轮对话里模型看不到之前的工具结果，拿不到 jobId；消费上一轮成果的 skill
+    （如 export-jianying）用注入的 CONVERSATION_ID 反查最新一版，而不是让模型从
+    聊天记录里拼素材 URL —— 那样会拿到过期的旧版素材。
+
+    Returns:
+        {"jobId": int, "status": str, "attempt": int, "createTime": str, "updateTime": str}
+    """
+    data = _post("/renderJob/latest", {"conversationId": conversation_id}, priv_token)
+    if not data.get("jobId"):
+        raise RuntimeError("no render job with a saved RenderPlan in this conversation")
+    return data
+
+
 def get_job(job_id: int, priv_token: str) -> dict:
     """
     获取渲染任务完整详情。

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V25",
+  "version": "V26",
   "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/video-parser/scripts/deconstruct_video.py

@@ -197,6 +197,13 @@ def upload_audio(audio_path: str) -> str:
     body += b'Content-Disposition: form-data; name="title"\r\n\r\n'
     body += filename.encode()
     body += b"\r\n"
+    # role / retention：ab-api 落素材表时必填角色。抽离音频只为 ASR，属中间产物；
+    # 源视频是第三方的，检索侧据 role 默认排除（license=third_party_unknown）。
+    for name, value in (("role", "source_audio"), ("retention", "intermediate")):
+        body += f"--{boundary}\r\n".encode()
+        body += f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode()
+        body += value.encode()
+        body += b"\r\n"
     # 结束
     body += f"--{boundary}--\r\n".encode()
 
@@ -207,6 +214,8 @@ def upload_audio(audio_path: str) -> str:
     }
     if AGENT_NAME:
         headers["x-invoke-agent"] = AGENT_NAME
+    if os.environ.get("CONVERSATION_ID"):
+        headers["x-conversation-id"] = os.environ["CONVERSATION_ID"]
 
     req = urllib.request.Request(url, data=body, headers=headers, method="POST")
 

package/skills/video-parser/version.json

@@ -2,6 +2,6 @@
   "skillName": "video-parser",
   "repoName": "agent-skill-media-maker",
   "skillId": "553",
-  "version": "V2",
+  "version": "V3",
   "skillDescription": "Video deconstruction skill. Splits a video into reusable content assets — audio, ASR transcript, scene segments, keyframe images.\n\nUse this skill as soon as the user mentions any of these intents:\n- Deconstruct / split / analyze / parse a video\n- Extract keyframes, extract the script from a video, transcribe a video\n- Pull content assets or raw material out of a video\n\nEven when the user does not say \"deconstruct\" explicitly, use this skill whenever they want to extract script text, keyframes, or structured information from a video."
 }

package/skills/web-screenshot/scripts/_media_upload.py

@@ -83,6 +83,8 @@ def _submit(
         "coverAtSec": str(cover_at_sec),
         "resolveCdn": "1" if resolve_cdn else "0",
         "ext": ext,
+        # 素材角色：ab-api 按它落 file.role（录屏贡献 video_clip 能力、按成品保留）
+        "role": "screen_record",
     }
     if title:
         query["title"] = title
@@ -230,4 +232,79 @@ def finalize_recording(
     )
 
 
-__all__ = ["finalize_recording", "FinalizeError"]
+DEFAULT_ABAPI_BASE_URL = "https://api-agent.remixmate.ai/api"
+
+# 分镜里承载「画面在讲什么」的文本字段（caption / title-card / type 等场景）
+_STORY_TEXT_KEYS = ("title", "subtitle", "text", "caption", "label", "content")
+
+
+def storyboard_text(story: Optional[dict]) -> str:
+    """把分镜里的可读文本收成一段：标题卡、字幕条、打字内容等，按场景顺序拼接。
+
+    录屏本身没有旁白，这段文本就是它最便宜的语义——生产者手上现成有，不需要 ASR。
+    """
+    if not isinstance(story, dict):
+        return ""
+    parts: list[str] = []
+    for scene in story.get("scenes") or []:
+        if not isinstance(scene, dict):
+            continue
+        for key in _STORY_TEXT_KEYS:
+            val = scene.get(key)
+            if isinstance(val, str) and val.strip():
+                parts.append(val.strip())
+    seen: set[str] = set()
+    out = [p for p in parts if not (p in seen or seen.add(p))]
+    return "\n".join(out)
+
+
+def annotate_asset(
+    *,
+    private_token: str,
+    file_id: Optional[int],
+    file_url: str,
+    text: str,
+    source_url: str,
+    duration_sec: Optional[float],
+    request_timeout: float = 30.0,
+) -> None:
+    """把录屏的语义写进 ab-api 素材库（POST /asset/annotate）：分镜文本 + 来源页面。
+
+    分镜里没有逐场景时间戳，整条录屏作为一个片段。失败抛 FinalizeError，调用方只记日志——
+    语义是附加信息，不能让「录屏已完成」失败。见 ab-platform/docs/asset-semantic-library-design.md §6.1。
+    """
+    if not private_token or not (file_id or file_url):
+        return
+    base = (os.environ.get("MM_API_BASE_URL") or DEFAULT_ABAPI_BASE_URL).rstrip("/")
+    payload: dict = {"provenance": {"sourceUrl": source_url, "producer": SKILL_NAME}}
+    if file_id:
+        payload["fileId"] = int(file_id)
+    else:
+        payload["fileUrl"] = file_url
+    if text:
+        payload["text"] = text
+        if isinstance(duration_sec, (int, float)) and duration_sec > 0:
+            payload["segments"] = [
+                {"startSec": 0, "endSec": round(float(duration_sec), 2), "text": text, "shot": "screen_record"}
+            ]
+    headers = _headers(
+        private_token,
+        content_type="application/json",
+        conversation_id=os.environ.get("CONVERSATION_ID") or None,
+    )
+    req = urllib.request.Request(
+        f"{base}/asset/annotate",
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=request_timeout) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError) as exc:
+        raise FinalizeError(f"/asset/annotate 网络错误: {exc}") from exc
+    if result.get("code") != 0:
+        raise FinalizeError(f"/asset/annotate code={result.get('code')}: {result.get('msg')}")
+
+
+__all__ = ["finalize_recording", "FinalizeError", "annotate_asset", "storyboard_text"]

package/skills/web-screenshot/scripts/record.py

@@ -23,7 +23,12 @@ from _media_screenshot import (  # noqa: E402
     template,
     trim,
 )
-from _media_upload import finalize_recording  # noqa: E402
+from _media_upload import (  # noqa: E402
+    FinalizeError,
+    annotate_asset,
+    finalize_recording,
+    storyboard_text,
+)
 
 
 def main() -> None:
@@ -253,6 +258,19 @@ def main() -> None:
     vod_ref = result.get("vodRef") or ""
     file_id = result.get("fileId")
 
+    # 语义入库：分镜文本 + 来源页面。失败只提示，不影响录屏结果。
+    try:
+        annotate_asset(
+            private_token=priv_token,
+            file_id=file_id,
+            file_url=cdn_url,
+            text=storyboard_text(story),
+            source_url=cfg.get("url", ""),
+            duration_sec=duration if isinstance(duration, (int, float)) else None,
+        )
+    except FinalizeError as e:
+        print(f"[record] 录屏语义写入素材库失败（不影响录屏）：{e}", file=sys.stderr)
+
     # 上传成功，默认删本地 webm（VOD 已持有），除非 --keep-webm
     if not args.keep_webm:
         try:

package/skills/web-screenshot/version.json

@@ -2,6 +2,6 @@
   "skillName": "web-screenshot",
   "repoName": "agent-skill-media-maker",
   "skillId": "555",
-  "version": "V6",
+  "version": "V7",
   "skillDescription": "Web-page screenshot skill (still images only, png/jpg), built on Playwright Python — captures any URL to a local image file.\nSupports: full-page / viewport / element / region capture, device emulation, waiting for dynamic content, hiding or masking distracting elements, and static annotations (highlight box / arrow / caption / numbered sequence / redact / code-line highlight).\n\nImages only (`.png` / `.jpg`). For video (`.webm` / screen recording / storyboard clips) use web-record / `web_record`.\n\nUse this skill immediately whenever the user asks for any of:\n- Web page screenshot, screen capture, full-page screenshot, long screenshot\n- Capture a specific element / region, partial screenshot, focus on an area\n- Hide or mask elements before capturing (cookie banner, sensitive information)\n- Annotate a still screenshot (highlight box / arrow / label / caption bar / numbering)\n- Highlight lines L5-L20 of a file and screenshot it\n- Wait for an element to appear, then capture\n- Mobile / device-emulated screenshot (iPhone / Pixel, etc.)\n- Capture with cookies / a logged-in session / storageState\n\nEven when the user does not say \"playwright\", any request to screenshot a URL and get a local image file should route here."
 }