@remixmate/cli 0.9.71 → 0.9.73

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

@@ -1,21 +1,21 @@
 #!/usr/bin/env python3
-"""
-剪映草稿生成脚本 — 调用 ab-api POST /file/generateJianYing
-通过 PrivToken（X-Priv-Token）认证。
 
-将素材 URL（视频/图片/音频）+ 时长描述打包为剪映可导入的草稿 ZIP。
 
-默认行为（非 --download）:
-  生成完成后直接输出下载 URL，供调用方直接展示，无需落盘。
 
-用法:
-  python gen_jianying_draft.py --title "我的视频" --scenes '[{"videoUrl":"...","duration":5}]'
-  python gen_jianying_draft.py --title "测试" --scenes scenes.json --download -o draft.zip
 
-环境变量:
-  MM_API_BASE_URL                - 后端 API 地址（默认: https://api-agent.remixmate.ai/api）
-  PRIV_TOKEN                     - PrivToken（优先读取；未配置时提示手动输入）
-"""
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 from __future__ import annotations
 
@@ -33,17 +33,17 @@ import uuid
 import zipfile
 
 API_BASE_URL = os.environ.get("MM_API_BASE_URL", "https://api-agent.remixmate.ai/api")
-PRIVATE_TOKEN = ""  # 在 main() 中通过 resolve_token() 初始化
+PRIVATE_TOKEN = ""
 SKILL_NAME = "export-jianying"
 AGENT_NAME = os.environ.get("AGENT_NAME", "")
 
-# 任务状态常量
+
 STATUS_PENDING = "pending"
 STATUS_PROCESSING = "processing"
 STATUS_COMPLETED = "completed"
 STATUS_FAILED = "failed"
 
-# textLayer 角色预设（fontSize/color/bold/position/shadow）
+
 ROLE_PRESETS = {
     "headline":    {"fontSize": 15, "color": "#FFFFFF", "bold": True,  "position": {"x": 0, "y": -0.35}, "shadow": True},
     "subheadline": {"fontSize": 8,  "color": "#F0C040", "bold": False, "position": {"x": 0, "y": 0.38},  "shadow": False},
@@ -52,7 +52,7 @@ ROLE_PRESETS = {
     "caption":     {"fontSize": 6,  "color": "#CCCCCC", "bold": False, "position": {"x": 0, "y": 0.44}},
 }
 
-# Pill 字幕样式（匹配 Remotion SubtitleBar "pill" 风格）
+
 PILL_SUBTITLE_STYLE = {
     "font_size": 8.0,
     "background_style": 1,
@@ -73,19 +73,19 @@ PILL_SUBTITLE_STYLE = {
 
 PILL_SUBTITLE_POSITION_Y = -0.458
 
-# ---------------------------------------------------------------------------
-# 剪映草稿根目录解析
-# ---------------------------------------------------------------------------
 
-# 剪映把 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",
@@ -95,7 +95,7 @@ _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("~"):
@@ -108,7 +108,7 @@ def draft_root_path_error(path: str) -> str:
 
 
 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":
@@ -119,13 +119,13 @@ def _local_draft_root(system: str) -> str:
 
 
 def resolve_draft_root_path(explicit: str, system: str) -> str:
-    """
-    解析剪映草稿根目录，按优先级：
-    1. 显式 --draft-root-path：原样使用（不做 expanduser），但必须是绝对路径；
-    2. 未给路径且脚本就跑在 --system 指定的系统上：按本机 HOME / LOCALAPPDATA 推出；
-    3. 其余情况（典型是服务端 agent）：报错，要求调用方向用户要路径。
-    返回值始终作为 draftRootPath 传给 API。
-    """
+
+
+
+
+
+
+
     if system not in DRAFT_ROOT_TEMPLATES:
         print(f"❌ unsupported --system value: {system} (supported: mac / windows)", file=sys.stderr)
         sys.exit(1)
@@ -133,7 +133,7 @@ def resolve_draft_root_path(explicit: str, system: str) -> str:
 
     if explicit:
         path = explicit.strip()
-        # 去掉末尾分隔符，但保留 "C:/" 与 "/" 这种根本身。
+
         while len(path) > 3 and path[-1] in "/\\":
             path = path[:-1]
         reason = draft_root_path_error(path)
@@ -161,7 +161,7 @@ def resolve_draft_root_path(explicit: str, system: str) -> str:
 
 
 def resolve_token() -> str:
-    """优先从 PRIV_TOKEN 环境变量读取 token，取不到则报错退出"""
+
     token = os.environ.get("PRIV_TOKEN", "")
     if not token:
         if sys.stdin.isatty():
@@ -173,12 +173,12 @@ def resolve_token() -> str:
 
 
 def gen_jianying_uuid() -> str:
-    """生成剪映风格的大写 UUID"""
+
     return str(uuid.uuid4()).upper()
 
 
 def hex_to_rgb_float(hex_color: str) -> list:
-    """'#RRGGBB' → [r, g, b]（0.0~1.0）"""
+
     hex_color = hex_color.lstrip("#")
     r = int(hex_color[0:2], 16) / 255.0
     g = int(hex_color[2:4], 16) / 255.0
@@ -187,7 +187,7 @@ def hex_to_rgb_float(hex_color: str) -> list:
 
 
 def build_text_content_json(text: str, style: dict) -> str:
-    """构建剪映 text material 的 content JSON 字符串（双重编码格式）"""
+
     rgb = hex_to_rgb_float(style.get("color", "#FFFFFF"))
     font_size = style.get("fontSize", 8)
     char_count = len(text)
@@ -212,7 +212,7 @@ def build_text_content_json(text: str, style: dict) -> str:
 
 
 def _build_headers(content_type: str = "application/json") -> dict:
-    """构建统一请求头（X-Priv-Token 认证头）"""
+
     headers = {
         "X-Priv-Token": PRIVATE_TOKEN,
         "x-invoke-skill": SKILL_NAME,
@@ -225,10 +225,10 @@ def _build_headers(content_type: str = "application/json") -> dict:
 
 
 def api_request(path: str, payload: dict, *, exit_on_error: bool = True) -> dict:
-    """
-    通用 API 请求函数（统一 POST 方法）
-    exit_on_error=False 时网络/连接错误会抛出异常而非直接退出（供轮询重试使用）
-    """
+
+
+
+
     if not PRIVATE_TOKEN:
         print("❌ PrivToken not configured: set the PRIV_TOKEN env var", file=sys.stderr)
         sys.exit(1)
@@ -254,10 +254,10 @@ def api_request(path: str, payload: dict, *, exit_on_error: bool = True) -> dict
 
 
 def build_text_material(material_id: str, text: str, style: dict) -> dict:
-    """
-    构建完整的剪映 text material dict（对应 materials.texts[] 中一项）。
-    style 包含 fontSize / color / bold / shadow / backgroundColor 等。
-    """
+
+
+
+
     content_json = build_text_content_json(text, style)
     font_size = style.get("fontSize", 8)
     color_hex = style.get("color", "#FFFFFF")
@@ -374,10 +374,10 @@ def build_text_segment(
     duration_us: int,
     position: dict,
 ) -> dict:
-    """
-    构建完整的剪映 text track segment dict。
-    position: {"x": float, "y": float} 归一化坐标。
-    """
+
+
+
+
     return {
         "caption_info": None,
         "check_flag": 7,
@@ -432,13 +432,13 @@ def build_text_segment(
 
 
 def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
-    """
-    将 RenderPlan JSON 转换为剪映草稿的 scenes 列表。
-    返回 (scenes, width, height)。
 
-    从 render-plan.json 中提取每个 scene 的素材 URL、时长、字幕文本，
-    自动映射为 gen_jianying_draft 所需的 scenes JSON 格式。
-    """
+
+
+
+
+
+
     timeline = render_plan.get("timeline", [])
     resolved_assets = {a["assetId"]: a for a in render_plan.get("resolvedAssets", [])}
     render_config = render_plan.get("renderConfig", {})
@@ -453,7 +453,7 @@ def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
         duration_sec = round(duration_frames / fps, 2) if fps else 5.0
         scene["duration"] = duration_sec
 
-        # 提取视觉素材（图片或视频）
+
         for layer in entry.get("layers", []):
             if layer.get("type") == "visual":
                 asset = resolved_assets.get(layer.get("assetId", ""))
@@ -465,7 +465,7 @@ def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
                         scene["imageUrl"] = asset["url"]
                 break
 
-        # 提取音频素材（TTS 旁白）
+
         for layer in entry.get("layers", []):
             if layer.get("type") == "audio":
                 asset = resolved_assets.get(layer.get("assetId", ""))
@@ -475,14 +475,14 @@ def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
                         scene["audioDuration"] = round(asset["duration"] / 1000.0, 2)
                 break
 
-        # 提取字幕文本（从 subtitleSegments 拼接）
+
         subtitle_segments = entry.get("subtitleSegments", [])
         if subtitle_segments:
             subtitle_text = " ".join(seg.get("text", "") for seg in subtitle_segments if seg.get("text"))
             if subtitle_text.strip():
                 scene["subtitleText"] = subtitle_text.strip()
 
-        # 提取 textLayers（从 props 中的 textLayers 或 scene 级别的文本信息）
+
         props = entry.get("props", {})
         title_text = props.get("titleText", "")
         if title_text:
@@ -491,18 +491,18 @@ def convert_render_plan_to_scenes(render_plan: dict) -> tuple:
                 "content": title_text,
                 "role": "headline",
             })
-            # 如果有 subtitleText 也加入
+
             if scene.get("subtitleText"):
                 text_layers.append({
                     "content": scene["subtitleText"],
                     "role": "subheadline",
                 })
-                del scene["subtitleText"]  # 避免重复
+                del scene["subtitleText"]
             scene["textLayers"] = text_layers
 
-        # 如果没有视觉素材，跳过该场景（剪映需要每个场景有 videoUrl 或 imageUrl）
+
         if not scene.get("videoUrl") and not scene.get("imageUrl"):
-            # 尝试用占位图
+
             print(f"   ⚠️  scene {entry.get('sceneId', '?')} has no visual asset, skipping", file=sys.stderr)
             continue
 
@@ -515,18 +515,18 @@ 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",
@@ -538,7 +538,7 @@ SCENE_FIELD_ALIASES = {
 
 
 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
@@ -552,8 +552,8 @@ def unknown_field_error(index: int, scene: dict) -> None:
 
 
 def parse_scenes(scenes_arg: str) -> list:
-    """解析 --scenes 参数：支持 inline JSON 字符串或文件路径"""
-    # 尝试作为文件路径读取
+
+
     if os.path.isfile(scenes_arg):
         with open(scenes_arg, "r", encoding="utf-8") as f:
             content = f.read()
@@ -563,7 +563,7 @@ def parse_scenes(scenes_arg: str) -> list:
             print(f"❌ failed to parse scenes JSON file: {e}", file=sys.stderr)
             sys.exit(1)
     else:
-        # 尝试作为 inline JSON 解析
+
         try:
             scenes = json.loads(scenes_arg)
         except json.JSONDecodeError as e:
@@ -579,7 +579,7 @@ def parse_scenes(scenes_arg: str) -> list:
         print("❌ scenes list cannot be empty", file=sys.stderr)
         sys.exit(1)
 
-    # 基本校验
+
     for i, scene in enumerate(scenes):
         if not isinstance(scene, dict):
             print(f"❌ scene {i + 1} is malformed: must be an object", file=sys.stderr)
@@ -592,7 +592,7 @@ def parse_scenes(scenes_arg: str) -> list:
             print(f"❌ scene {i + 1} is missing a valid duration (must be > 0)", file=sys.stderr)
             sys.exit(1)
 
-        # textLayers 校验
+
         text_layers = scene.get("textLayers")
         if text_layers is not None:
             if not isinstance(text_layers, list):
@@ -617,7 +617,7 @@ def create_jianying_task(
     height: int = 1920,
     draft_name: str = "",
 ) -> str:
-    """创建剪映草稿生成任务，返回 taskId"""
+
     print("📦 Submitting Jianying draft generation task...")
     print(f"   title: {title}")
     print(f"   scenes: {len(scenes)}")
@@ -638,7 +638,7 @@ def create_jianying_task(
 
     result = api_request("/file/generateJianYing", payload)
 
-    # 检查业务状态码
+
     if result.get("code") != 0:
         msg = result.get("msg", "未知错误")
         print(f"❌ API returned an error: {msg}", file=sys.stderr)
@@ -655,10 +655,10 @@ def create_jianying_task(
 
 
 def poll_task_status(task_id: str, poll_interval: int = 5, max_wait: int = 300) -> dict:
-    """
-    轮询剪映草稿生成状态，返回最终结果。
-    网络瞬断时自动重试（最多连续 5 次），不会因单次网络抖动而中断。
-    """
+
+
+
+
     print(f"\n⏳ Waiting for draft generation (up to {max_wait} s)...")
 
     start_time = time.time()
@@ -684,10 +684,10 @@ def poll_task_status(task_id: str, poll_interval: int = 5, max_wait: int = 300)
             time.sleep(poll_interval)
             continue
 
-        # 请求成功，重置连续错误计数
+
         consecutive_errors = 0
 
-        # 检查业务状态码
+
         if result.get("code") != 0:
             msg = result.get("msg", "未知错误")
             print(f"\n❌ status query failed: {msg}", file=sys.stderr)
@@ -696,7 +696,7 @@ def poll_task_status(task_id: str, poll_interval: int = 5, max_wait: int = 300)
         result_data = result.get("data") or {}
         status = result_data.get("status", "unknown")
 
-        # 打印状态
+
         status_icons = {
             STATUS_PENDING: "⏳",
             STATUS_PROCESSING: "🔄",
@@ -707,7 +707,7 @@ def poll_task_status(task_id: str, poll_interval: int = 5, max_wait: int = 300)
         print(f"\r   {icon} status: {status} | elapsed: {elapsed:.0f}s", end="", flush=True)
 
         if status == STATUS_COMPLETED:
-            print()  # 换行
+            print()
             return result_data
 
         if status == STATUS_FAILED:
@@ -720,32 +720,32 @@ 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)
-    # '%' 必须留在 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，而不是整次导出失败。"""
+    pass
 
 
 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"',
@@ -772,7 +772,7 @@ def upload_draft_zip(zip_path: str, file_name: str) -> str:
         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:
@@ -792,9 +792,9 @@ def upload_draft_zip(zip_path: str, file_name: str) -> str:
 
 
 def download_zip(download_url: str, output_path: str) -> None:
-    """下载 ZIP 文件到本地"""
-    # 不打印地址：去掉签名的地址打开就是 403，而模型会把 stdout 里任何像链接的东西
-    # 转交给用户（conv_U9oYmHmE1iJbx2qETDuh 就是把这一行当成了下载链接）。
+
+
+
     print("\n⬇️  Downloading draft ZIP for post-processing...")
     safe_url = _encode_url(download_url)
     try:
@@ -812,11 +812,11 @@ def download_zip(download_url: str, output_path: str) -> None:
 
 
 def _resolve_layer_style(layer: dict) -> dict:
-    """将 textLayer 字段与角色预设合并，返回最终有效样式"""
+
     role = layer.get("role", "subheadline")
     preset = ROLE_PRESETS.get(role, ROLE_PRESETS["subheadline"])
-    style = dict(preset)  # 浅拷贝预设
-    # 用户显式字段覆盖预设
+    style = dict(preset)
+
     for key in ("fontSize", "color", "bold", "shadow", "backgroundColor"):
         if key in layer:
             style[key] = layer[key]
@@ -826,11 +826,11 @@ def _resolve_layer_style(layer: dict) -> dict:
 
 
 def apply_text_layers(draft: dict, scenes: list) -> None:
-    """
-    核心后处理：遍历场景 textLayers，修改/新增 draft 中的文本素材与轨道片段。
-    直接原地修改 draft dict。
-    """
-    # 1. 找到 video track，提取每个片段的时间范围
+
+
+
+
+
     video_track = None
     for track in draft.get("tracks", []):
         if track.get("type") == "video":
@@ -848,7 +848,7 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
             file=sys.stderr,
         )
 
-    # 2. 找到 text track，不存在则创建
+
     text_track = None
     for track in draft.get("tracks", []):
         if track.get("type") == "text":
@@ -869,21 +869,21 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
     text_segments = text_track.get("segments", [])
     texts_materials = draft.get("materials", {}).get("texts", [])
 
-    # 建立 target_timerange.start → text_segment 索引映射
+
     seg_by_start: dict[int, int] = {}
     for idx, seg in enumerate(text_segments):
         start = seg.get("target_timerange", {}).get("start", -1)
         seg_by_start[start] = idx
 
-    # 建立 material_id → texts 索引映射
+
     mat_by_id: dict[str, int] = {}
     for idx, mat in enumerate(texts_materials):
         mat_by_id[mat["id"]] = idx
 
-    # 额外的 text track 列表（用于放置第 2+ 个 textLayer 的片段）
+
     extra_text_tracks: list[dict] = []
 
-    # 3. 遍历每个场景
+
     match_count = min(len(video_segments), len(scenes))
     for i in range(match_count):
         scene = scenes[i]
@@ -903,12 +903,12 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
             position = style.get("position", {"x": 0, "y": 0})
 
             if layer_idx == 0 and start_us in seg_by_start:
-                # 替换已有文本素材
+
                 seg_idx = seg_by_start[start_us]
                 existing_seg = text_segments[seg_idx]
                 mat_id = existing_seg.get("material_id", "")
 
-                # 更新素材
+
                 if mat_id in mat_by_id:
                     mat = texts_materials[mat_by_id[mat_id]]
                     mat["content"] = build_text_content_json(content, style)
@@ -920,11 +920,11 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
                     mat["background_color"] = bg_color
                     mat["background_style"] = 1 if bg_color else 0
 
-                # 更新片段位置
+
                 existing_seg["clip"]["transform"]["x"] = position.get("x", 0)
                 existing_seg["clip"]["transform"]["y"] = position.get("y", 0)
             else:
-                # 新增素材 + 片段
+
                 new_mat_id = gen_jianying_uuid()
                 new_seg_id = gen_jianying_uuid()
 
@@ -936,7 +936,7 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
                     new_seg_id, new_mat_id, start_us, duration_us, position
                 )
 
-                # 第 2+ 个 textLayer 放入额外 track（每个 layer_idx 一条 track）
+
                 extra_idx = layer_idx - 1 if (layer_idx > 0 and start_us in seg_by_start) else layer_idx
                 while extra_idx >= len(extra_text_tracks):
                     new_track = {
@@ -951,30 +951,30 @@ def apply_text_layers(draft: dict, scenes: list) -> None:
                     extra_text_tracks.append(new_track)
                 extra_text_tracks[extra_idx]["segments"].append(new_segment)
 
-    # 将额外 text tracks 追加到 draft
+
     for et in extra_text_tracks:
         if et["segments"]:
             draft["tracks"].append(et)
 
-    # 更新 materials.texts 引用（因为可能通过 append 改变了列表内容）
+
     draft["materials"]["texts"] = texts_materials
 
     print(f"   ✅ textLayers post-processing finished")
 
 
 def apply_subtitle_pill_style(draft: dict) -> None:
-    """
-    将 Pill 字幕样式（匹配 Remotion SubtitleBar "pill" 风格）应用到 draft 中的
-    所有 text materials 和 text segments。直接原地修改 draft dict。
-    """
+
+
+
+
     texts_materials = draft.get("materials", {}).get("texts", []) or []
 
-    # 1. 覆盖每个 text material 的样式属性
+
     for mat in texts_materials:
         for key, value in PILL_SUBTITLE_STYLE.items():
             mat[key] = value
 
-        # 更新 material 内嵌 content JSON 的 styles[0].size
+
         content_raw = mat.get("content", "")
         if content_raw:
             try:
@@ -984,10 +984,10 @@ def apply_subtitle_pill_style(draft: dict) -> None:
                     styles[0]["size"] = PILL_SUBTITLE_STYLE["font_size"]
                 mat["content"] = json.dumps(content_obj, ensure_ascii=False)
             except (json.JSONDecodeError, TypeError):
-                # 若 content 非 JSON（极少数情况），跳过内嵌更新
+
                 pass
 
-    # 2. 将每个 text segment 的 clip.transform.y 设为 PILL_SUBTITLE_POSITION_Y
+
     for track in draft.get("tracks", []):
         if track.get("type") != "text":
             continue
@@ -1000,16 +1000,16 @@ def apply_subtitle_pill_style(draft: dict) -> None:
 
 
 def postprocess_draft_zip(zip_path: str, scenes: list) -> None:
-    """
-    后处理剪映草稿 ZIP：读取 draft_content.json，修改文本层，重新打包。
-    同时处理 draft_content.json 和 draft_info.json（两者内容相同）。
-    """
+
+
+
+
     print(f"\n🔧 Post-processing draft ZIP (applying textLayers)...")
 
     tmp_path = zip_path + ".tmp"
 
     with zipfile.ZipFile(zip_path, "r") as zin:
-        # 读取 draft_content.json
+
         draft_json_name = None
         draft_info_name = None
         for name in zin.namelist():
@@ -1024,71 +1024,71 @@ def postprocess_draft_zip(zip_path: str, scenes: list) -> None:
 
         draft_data = json.loads(zin.read(draft_json_name).decode("utf-8"))
 
-        # 应用 textLayers 修改
+
         apply_text_layers(draft_data, scenes)
 
-        # 应用 Pill 字幕样式（匹配 Remotion SubtitleBar）
+
         apply_subtitle_pill_style(draft_data)
 
         modified_json = json.dumps(draft_data, ensure_ascii=False, indent=4).encode("utf-8")
 
-        # 写入新 ZIP
+
         with zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zout:
             for item in zin.infolist():
                 if item.filename == draft_json_name:
                     zout.writestr(item, modified_json)
                 elif item.filename == draft_info_name:
-                    # draft_info.json 内容同 draft_content.json
+
                     zout.writestr(item, modified_json)
                 else:
                     zout.writestr(item, zin.read(item.filename))
 
-    # 原子替换
+
     os.replace(tmp_path, zip_path)
     print(f"   ✅ draft ZIP post-processing finished: {zip_path}")
 
 
 def prepare_api_scenes(scenes: list) -> list:
-    """
-    为 API 调用准备场景列表：剥离 textLayers，自动派生 subtitleText。
-    返回新列表（不修改原始 scenes）。
-    """
+
+
+
+
     api_scenes = []
     for scene in scenes:
         api_scene = {k: v for k, v in scene.items() if k != "textLayers"}
         text_layers = scene.get("textLayers")
         if text_layers and not api_scene.get("subtitleText"):
-            # 从第一个 textLayer 派生 subtitleText
+
             api_scene["subtitleText"] = text_layers[0].get("content", "")
         api_scenes.append(api_scene)
     return api_scenes
 
 
 def has_text_layers(scenes: list) -> bool:
-    """检查场景列表中是否有任何场景包含 textLayers"""
+
     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 — 路径注入之后才能导入
+    import render_job_client
 
     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"))
@@ -1175,7 +1175,7 @@ Scene fields:
 
     args = parser.parse_args()
 
-    # 初始化 token
+
     global PRIVATE_TOKEN
     if args.priv_token:
         PRIVATE_TOKEN = args.priv_token
@@ -1188,8 +1188,8 @@ Scene fields:
 
     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:
@@ -1204,11 +1204,11 @@ Scene fields:
             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:
@@ -1220,7 +1220,7 @@ Scene fields:
                 file=sys.stderr,
             )
 
-    # --from-job-id 模式：从数据库加载 RenderPlan
+
     if args.from_job_id:
         print(f"📋 loading RenderPlan from database (jobId={args.from_job_id})...")
         rjc = _render_job_client()
@@ -1238,7 +1238,7 @@ Scene fields:
             dsl_meta = render_plan.get("dslMeta", {})
             args.title = dsl_meta.get("title", "") or "RenderPlan 草稿"
         print(f"   ✅ converted {len(scenes)} scene(s), canvas {args.width}x{args.height}")
-    # --from-render-plan 模式：从 RenderPlan 自动转换
+
     elif args.from_render_plan:
         if not os.path.isfile(args.from_render_plan):
             print(f"❌ RenderPlan file does not exist: {args.from_render_plan}", file=sys.stderr)
@@ -1247,17 +1247,17 @@ Scene fields:
         with open(args.from_render_plan, "r", encoding="utf-8") as f:
             render_plan = json.load(f)
         scenes, rp_width, rp_height = convert_render_plan_to_scenes(render_plan)
-        # 使用 RenderPlan 中的画布尺寸（除非用户显式指定）
+
         if args.width == 1080 and args.height == 1920:
             args.width = rp_width
             args.height = rp_height
-        # 自动推导标题（优先从 dslMeta.title 读取）
+
         if not args.title:
             dsl_meta = render_plan.get("dslMeta", {})
             args.title = dsl_meta.get("title", "") or "RenderPlan 草稿"
         print(f"   ✅ converted {len(scenes)} scene(s), canvas {args.width}x{args.height}")
     else:
-        # 传统模式：必须提供 --scenes 和 --title
+
         if not args.scenes:
             print("❌ provide --from-job-id, --from-render-plan or --scenes", file=sys.stderr)
             parser.print_help()
@@ -1268,18 +1268,18 @@ Scene fields:
             sys.exit(1)
         scenes = parse_scenes(args.scenes)
 
-    # 解析草稿根目录（始终作为 draftRootPath 传给 API）
+
     draft_root_path = resolve_draft_root_path(args.draft_root_path, args.system)
 
-    # 检测是否需要后处理（textLayers 或任意字幕文本都需要应用 pill 样式）
+
     needs_postprocess = has_text_layers(scenes) or any(s.get("subtitleText") for s in scenes)
     if needs_postprocess:
         print("📝 textLayers or subtitleText detected; post-processing after generation (incl. Pill subtitle styling)")
 
-    # 为 API 调用准备场景（剥离 textLayers，派生 subtitleText）
+
     api_scenes = prepare_api_scenes(scenes)
 
-    # 提交任务
+
     task_id = create_jianying_task(
         title=args.title,
         scenes=api_scenes,
@@ -1289,7 +1289,7 @@ Scene fields:
         draft_name=args.draft_name,
     )
 
-    # 轮询状态
+
     result_data = poll_task_status(task_id, args.poll_interval, args.max_wait)
 
     download_url = result_data.get("downloadUrl", "")
@@ -1302,13 +1302,13 @@ Scene fields:
     print(f"\n🎉 Jianying draft generated successfully!")
     print(f"   filename: {file_name}")
 
-    # 在 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:
@@ -1317,12 +1317,12 @@ Scene fields:
         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. "