CapCut Export 用于把一个已完成的分层剪辑转换为 CapCut 桌面版草稿，让剪辑者可以在 CapCut 中抓取任意元素继续编辑，比如微调字幕、替换卡片、静音某个音效，而不是只能收到一个已经烘焙好的 MP4。
使用前提
工具面向 macOS，且需已安装 CapCut 桌面版，草稿目录位于 ~/Movies/CapCut/User Data/Projects/com.lveditor.draft/。需要 Python 3，并在虚拟环境中安装 pyJianYingDraft（pip install pyJianYingDraft），不建议全局安装，因为该库更新较快、不同版本 API 会有差异。ffmpeg 需在 PATH 中（或通过 FFMPEG 环境变量指定），用于拆分卡片渲染和抓取封面缩略图。可选安装 PIL（pip install pillow）以生成程序化暗角 PNG。此外还需要完成剪辑的各个渲染通道，这是剪辑技能的工作，不是本技能负责的。
输入
需要准备：基础素材视频文件（已按画布比例重新构图）；仅卡片通道的渲染（只显示图形卡片，不透明背景可以，卡片会作为不透明片段堆叠）；Alpha 特效通道（所有需要带透明度叠加在素材上的内容，如进度条、漏光，需以 --format mov 渲染为 true-alpha ProRes、yuva444p，MP4 无法携带 alpha）；逐词转录 JSON（[{"text","start","end"},...]）用于原生字幕；VO/音乐/音效文件（剪辑中实际使用的音频，每个音效命中一个文件）；以及剪辑的时间数据（缩放边界、卡片进出时间、音效命中列表、字幕样式节拍），填入脚本的 CONFIG 块。
工作流程
将模板 scripts/export-capcut-template.py 复制到剪辑项目文件夹，填写 CONFIG 块（时长、卡片、命中、字幕窗口）。脚本会自动把媒体暂存到本地磁盘 ~/Movies/capcut-export-media（可用 CAPCUT_MEDIA_DIR 覆盖）。这一步不是可选的整洁工作：草稿引用外部卷上的媒体可能触发 macOS 权限（TCC）提示，导致 CapCut 内媒体解析失败，所有引用文件应保留在启动磁盘上。随后构建草稿：.venv/bin/python export-capcut-template.py，草稿写入 ~/Movies/capcut-draft-staging/<name>/。然后打补丁：使用 --skip-build --patch-native <原生草稿文件夹路径> 重新运行。完全退出 CapCut（Cmd+Q），再运行 --skip-build --install --register。打开 CapCut 验证轨道；若打不开则进入调试。
模式差异
pyJianYingDraft 面向剪映（中国版 CapCut）草稿格式，写入 draft_content.json 且 new_version 为 "110.0.0"。当前 CapCut 桌面版（国际版）加载 draft_info.json，new_version 约为 "181.0.0"，并包含 8 个旧模式没有的顶层键：draft_type、function_assistant_info、is_drop_frame_timecode、lyrics_effects、mixed_track_mode_on、path、smart_ads_info、uneven_animation_template_info。--patch-native 会在目标机器上用 CapCut 原生创建一个临时项目，然后从原生草稿克隆这 8 个键到生成的草稿，复制 new_version/version 字段，将 path 设为草稿最终安装文件夹，并同时写出 draft_content.json 和 draft_info.json 两个文件名。
草稿安装与注册表
仅把文件夹复制到 com.lveditor.draft/ 不够，CapCut 只列出在 root_meta_info.json（顶层键 all_draft_store）中注册的草稿。脚本会先备份 root_meta_info.json（时间戳 .bak-*）。只能在 CapCut 完全退出时编辑注册表，因为 CapCut 退出时会重写它；脚本在检测到 CapCut 进程时会拒绝运行 --install/--register。新条目通过克隆原生条目并修正 draft_name、所有包含旧名称的路径字段、新的全大写 UUID draft_id、tm_duration（微秒）、时间戳、draft_cover（脚本用 ffmpeg 抓取一帧作为 draft_cover.jpg）。
轨道布局
从下到上：footage 为基础视频，在每个缩放边界切分，每段在 ClipSettings 中设置自己的 scale_x/scale_y，使推近效果保持可编辑；overlay 为定位的第二视频（如分屏节拍中的头部卡片带），用 ClipSettings(scale_x, scale_y, transform_y)，负 transform_y 向下、正向上；cards 为每张图形卡片一个不透明片段，先渲染仅卡片通道，再用 ffmpeg 在卡片边界切分（-crf 16 -g 15 保持切点帧精确）；fx 为整条时间线的一个 alpha 叠加层（true-alpha ProRes .mov），不拆分；image-N 为静态 PNG（暗角等），作为图像片段放在指定窗口；captions 为原生 TextSegments，使用 TextStyle(size, bold, italic, color)、TextBorder(width, color)，位置通过 ClipSettings(transform_y=...)，在 CapCut 中完全可编辑；text-N 为 CTA/关键词弹出，放在额外轨道；vo、music、sfx-N 为音频，每个音效命中一个片段，便于单独调整。
文本轨道硬性规则
一条轨道不能放置重叠片段，两个同时出现的文本必须放在不同轨道，脚本会把额外文本贪心地放到 text-1、text-2 等。字幕窗口必须严格单调，转写器的逐词时间戳经常重叠，脚本会在创建片段前强制 start ≥ prev_end + 2ms 且 end ≤ next_start − 40ms；跳过这一步 add_segment 会抛错，或更糟，CapCut 渲染错误。
pyJianYingDraft API 注意事项
每个片段时长必须钳制到素材时长：d = min(d, material.duration/1e6 - source_start)，否则库会抛错；material.duration 以微秒为单位。VideoSegment(material, target_timerange, source_timerange=…, volume=…, clip_settings=…) 中 source_timerange 选择文件播放的切片，静帧/完整片段可省略。TextStyle(italic=…) 并非每个版本都有，需用 try/except TypeError 包裹并降级为非斜体。时间范围用 trange("12.5s", "0.8s")（开始、时长）构建。
调试
当 CapCut 拒绝或弄乱草稿时，方法是与同一 CapCut 安装生成的原生草稿做 diff。先在 CapCut 中创建一个最小原生项目（一个视频、一个字幕、一个音频），退出 CapCut。美化打印两份草稿：python3 -m json.tool <native>/draft_info.json > a.json，对自己的草稿同样处理，然后先 diff 顶层键，再 diff 每条轨道/每个片段结构。先修复最高层差异（缺失键、版本字符串、路径），重新安装测试，只在草稿能打开但元素损坏时才向下迭代。注册表问题与模式问题表现不同：草稿从未出现在项目列表 = 注册表问题；草稿出现但打开报错 = 模式问题。如果 CapCut 打开时“修复”了草稿，立即复制修复后的 draft_info.json 出来与所写内容 diff——CapCut 刚告诉了你正确的模式。
脚本
scripts/export-capcut-template.py 是完整导出模板，CONFIG 块在顶部，提供 --patch-native、--install、--register、--skip-build 参数，运行前应阅读其 docstring。
状态说明
草稿生成可用且已充分理解；“现代 CapCut 打开它”这一步是有文档记录的进行中工作。pyJianYingDraft 写入剪映时代草稿，当前 CapCut 桌面版期望更新的模式。补丁已在脚本中实现，但尚未在当前 CapCut 构建上端到端现场验证，最后一公里应视为调试工作，而不是保证一次成功。