capcut-edit

capcut-edit

通过支持版本感知的存储编辑 CapCut / JianYing 草稿的 CLI。v0.11 可检测并同步 draft_content.json、draft_info.json、draft_meta_info.json 和 template-2.tmp 中可读取的时间线。

项目位置

• macOS：~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/
• Windows：%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\
• Windows（JianYing / 剪映）：%LOCALAPPDATA%\JianyingPro\User Data\Projects\com.lveditor.draft\<project>\

核心原则 — 确定性脚本

任何涉及多次调用 capcut、任何算术运算或任何分支的操作方案，都应以参数化 shell 脚本的形式放在 scripts/ 中。Claude 使用输入参数调用脚本；脚本按固定顺序运行。如果某个操作方案可以写成脚本，就必须写成脚本，而不是在 references/ 中用文字描述。

references/workflows.md 只说明要调用哪个脚本以及原因，绝不描述可据此重构的操作步骤。

渐进式呈现

先概览，再深入查看所需内容。绝不要倾倒完整的项目 JSON。

capcut info <project> -H           # overview
capcut doctor -H                   # installed media/transcription capabilities
capcut diagnose <project> -H       # canonical files, divergence, editor safety
capcut tracks <project> -H         # all tracks
capcut materials <project> -H      # material summary
capcut segments <project> -H       # segments with timing
capcut segment <project> <id>      # one item, full detail

输出模式

• JSON（默认）：通过管道传给 jq，再传给脚本。
• -H：易读的表格。
• -q：静默模式，仅返回退出代码——用于脚本中的写入命令。

批量写入

echo '{"cmd":"set-text","id":"a1b2c3","text":"Fixed"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>

操作：set-text、shift、shift-all、speed、volume、opacity、trim。

批量操作具有事务性：只要有一项操作失败，就不会写入任何内容。仅当用户明确接受部分提交时才使用 --continue-on-error；即便如此，命令仍会以非零状态退出。

查看位置

• references/api-reference.md — 所有命令、所有标志、所有值格式（时间、百分比、角度）、ID 前缀规则和 .bak 不变式。
• ../../docs/command-reference.md — 生成的 command-contract v2，包含带类型的位置参数/选项、可变性、前置条件、输出形式和退出代码。
• references/workflows.md — 操作方案 = 要运行哪个 scripts/X.sh 以及原因。
• references/pitfalls.md — 先关闭项目、.bak、音频上的 clip=null、结合 speed 计算 source_timerange、alpha 关键帧无法渲染，应使用动画素材等。
• 枚举发现 — 调用 capcut enums --<category>（或使用 -H 查看表格）列出所有 CapCut 标识。类别：--transitions、--masks、--image-intros、--image-outros、--image-combos、--text-intros、--text-outros、--text-loop-anims、--scene-effects、--character-effects、--audio-effects、--fonts。添加 --jianying 可切换命名空间。enums.json 包由 python3 scripts/extract-enums.py 生成一次；运行时不依赖 Python。
• scripts/ — 客户端库。当前包含：
  • anim.sh — 添加 9 种 CapCut 片头/片尾动画中的任意一种；fade-in.sh 和 fade-out.sh 是轻量封装脚本。
  • ken-burns.sh — 通过 capcut keyframe --batch 设置缩放和平移关键帧（运动属性可以渲染；alpha 无法渲染——请改用 anim.sh fade-in）。
  • long-to-short.sh — 剪切一个范围，并添加标题和 CTA 文本。
  • stamp-cta.sh — 应用已保存的文本模板（参见 assets/examples/subscribe-cta.json）。
  • _test.sh — 使用测试夹具运行每个封装脚本；此处有任何更改后都要运行。
• assets/examples/ — 用于手动编辑的原始 JSON 片段。

脚本会自行解析 capcut 入口点，因此即使安装在 capcut-cli 检出目录之外，此技能也能正常使用：优先使用 $CAPCUT_CLI（指向 dist/index.js 或启动器的显式路径），其次使用仓库构建版本，再其次使用已安装的 node_modules/capcut-cli，最后使用 PATH 中的 capcut-cli/capcut。.js 入口由 node 运行；启动器（来自 PATH，或由 $CAPCUT_CLI 指向的启动器）则直接运行。anim.sh 会根据平台解析 CapCut 效果缓存目录；$CAPCUT_EFFECT_CACHE 可覆盖该目录。

不变量

• 编辑前请先在 CapCut 中关闭项目；编辑后再重新打开。
• 每次写入都会先检查冲突、以原子方式准备，并同步到所有可读取的时间线目标。每个目标都会收到 .bak 和滚动历史快照。
• 除非用户明确接受覆盖磁盘上已更改的状态或打开的编辑器，否则绝不传入 --force-write。
• 音频片段的 clip 为 null（没有不透明度／缩放）。
• capcut cut 会写入 --out，绝不会修改源文件。
• ID：UUID 的前 6 个或更多字符必须与前缀匹配。
• 时间格式：1.5s、500ms、+0.5s、-1s、1:30、0:05.5，裸数字表示秒。

v0.11 高价值路径

• 完整草稿：capcut compile spec.json --check，然后运行 capcut compile spec.json --out <dir>。规范支持 refs、变换、装饰器、模板、字幕、关键帧和淡入淡出。
• 卡拉 OK：capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke。
• 代理：capcut render <project> --all-video-tracks --burn-captions；先运行 doctor 检查 FFmpeg 功能标志。
• 自动化：capcut serve --workers N --retries N --timeout MS；为作业设置稳定的 id 字段，并让运行器按项目串行执行写入。
• Agent 架构：CLI v0.28.0 或更高版本中，先运行 capcut describe --compact 发现命令，然后通过 capcut describe --command <name> 获取完整契约（可重复查询多个名称）。不带参数的 capcut describe 会返回完整注册表，并且适用于较旧版本。以这些契约为准；不要抓取帮助文本或自行臆造标志。