@remixmate/cli 0.9.58 → 0.9.59

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.58",
-  "generatedAt": "2026-09-29T10:20:23.290Z",
+  "version": "0.9.59",
+  "generatedAt": "2026-09-29T12:43:37.496Z",
   "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.59",
   "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,77 @@ 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))
 
 
+def _url_without_query(raw_url: str) -> str:
+    """日志里只打对象地址：带签名的 query（Signature / OSSAccessKeyId）不进日志。"""
+    parsed = urllib.parse.urlparse(raw_url)
+    return urllib.parse.urlunparse(parsed._replace(query="", fragment=""))
+
+
+def upload_draft_zip(zip_path: str, file_name: str) -> str:
+    """
+    把后处理过的 ZIP 传回 ab-api（POST /file/uploadJianYingDraft），返回带签名的下载地址。
+
+    为什么必须传回：后处理（字幕样式 / 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:
+            result = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        print(f"❌ draft upload failed (HTTP {e.code})", file=sys.stderr)
+        sys.exit(1)
+    except (urllib.error.URLError, OSError, ConnectionError) as e:
+        print(f"❌ draft upload failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if result.get("code") != 0:
+        print(f"❌ draft upload failed: {result.get('msg', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+    url = (result.get("data") or {}).get("downloadUrl", "")
+    if not url:
+        print("❌ draft upload succeeded but no download URL was returned", file=sys.stderr)
+        sys.exit(1)
+    print("   ✅ uploaded")
+    return url
+
+
 def download_zip(download_url: str, output_path: str) -> None:
     """下载 ZIP 文件到本地"""
-    print(f"\n⬇️  Downloading draft ZIP: {download_url[:80]}...")
+    print(f"\n⬇️  Downloading draft ZIP: {_url_without_query(download_url)}")
     safe_url = _encode_url(download_url)
     try:
         urllib.request.urlretrieve(safe_url, output_path)
@@ -906,6 +1066,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 +1134,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 +1146,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 +1183,38 @@ 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）。
+        print(
+            "⚠️  --scenes was hand-written; omit --scenes/--from-job-id to export the latest prepared "
+            "render job of this conversation 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 +1248,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 +1282,45 @@ 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}")
-
-    # 默认下载 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
+    print(f"   filename: {file_name}")
 
-    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 字幕样式
+    output_path = ""
     if needs_postprocess:
-        postprocess_draft_zip(output_path, scenes)
+        # 后处理必须先把 ZIP 拿到本地。--no-download 时落到临时文件，传回后删掉，
+        # 不在跑脚本的机器（常常是服务器）上留垃圾。
+        keep_local = not args.no_download
+        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)
+        finally:
+            if not keep_local and os.path.exists(output_path):
+                os.remove(output_path)
+                output_path = ""
+    elif not args.no_download:
+        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)
+    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": "V6",
   "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/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."
 }