用命令行改写剪映与 CapCut 草稿（capcut-cli）

剪映和 CapCut 的工程其实是本地的一份 JSON 草稿，轨道、素材路径、文本样式、时间点都记在里面。要批量改字幕、统一调速、把一条长视频拆成几十条短视频时，在界面里逐个拖动并不现实；先导出成片再处理，又会把可继续编辑的轨道结构丢掉。

capcut-cli 是用 JavaScript 写的命令行工具，直接读写 CapCut 与剪映的本地草稿文件，JSON 进 JSON 出，把字幕、时间线、素材改动写回仍可编辑的工程。

它不联网，不需要 API Key，也不起 HTTP 服务或 MCP server，全部操作落在本地草稿库上。除了命令行，它还提供可 import 的库、从 stdin 读 JSONL 任务的队列模式，以及一个实验性的 WebAssembly 只读沙箱。作者说明这是社区项目，与 CapCut、剪映、字节跳动没有隶属关系，两个名字是字节跳动的商标。

主要功能

仓库里提到约三十多个子命令，下面按用途挑主要的写。

• 查看与诊断：capcut info <project> 读草稿概况，tracks、materials、segments、texts 分别列出轨道、素材、片段与文本，doctor 做环境与草稿检查。检查类命令提供 --json 输出，方便交给脚本或模型解析，官方定位就是「任何 LLM agent 都能驱动的确定性 JSON 边界」。
• 快速起稿：capcut quickstart my-first --video clip.mp4 --srt captions.srt 一条命令建出带视频与字幕的可编辑工程，比手工搭时间线快得多。
• 字幕与翻译：caption 生成字幕；caption --words <file.json|-> 用外部对齐器输出的逐词时间戳建字幕，自动识别 Whisper / whisper.cpp 的 segments[].words[]、WhisperX 的 word_segments[] 以及纯 {word|text|char, ...} 结构，机器上因此不必装 Whisper；caption --audio-stream 支持多音轨转写；translate 需要 ANTHROPIC_API_KEY。
• 时间线与素材编辑：create、build、add-video、add-audio、add-text、add-sfx 增删内容，replace-media 替换素材，relink --dir <folder> --recursive 递归搜索嵌套的素材目录。
• 模板：templates/*.json 里带 caption-pop、lower-third、hook-question 等模板，用 templates 命令列出可选项，再用 apply-template 套到草稿上。
• 校验与修复：lint 检查时间线问题，lint --frame-grid --fix 处理帧网格取整，另有 segment-overlap、segment-offscreen 两项检查；--min-script-match 作为中英文字符级对齐的写入闸门；diff 比较两个版本的结构变化；compile 从骨架生成工程。
• 批处理与自动化：capcut serve 从 stdin 读 JSONL 任务，官方文档给了 n8n / Make / Coze 的接入示例；batch --plan 与 --apply-plan 先出计划再执行；render --strict 与 --verify 做渲染保真度统计和输出时长核对。
• Agent 集成：npx skills add renezander030/capcut-cli 把 capcut-edit 技能装进 Claude Code、Codex、Cursor、OpenCode 等；Claude Code 也能以插件形式加载；实验性的 wasm/capcut-core 提供 inspect、diff、lint-portable 三个只读工具，通过 Wassette 走 MCP，不读写文件、不联网。

项目仓库在 https://github.com/renezander030/capcut-cli，采用 MIT 许可证，主要语言是 JavaScript（53.8%）与 TypeScript（43.2%）。当前 Star 889，Fork 91，开放 Issue 5 个，最近一次提交在 2026-10-14。

安装与依赖

前置要求是 Node ≥ 18，只用内置模块，没有原生依赖。全局安装一条命令：

npm install -g capcut-cli

不想安装可以直接跑 npx capcut-cli <command>。Python 用户用 pip install capcut 包同一个二进制，例如 capcut.run("quickstart", "my-short", video="clip.mp4", ratio="9:16")。从源码装则是 git clone https://github.com/renezander030/capcut-cli && cd capcut-cli && npm install && npm run build，再 npm link 暴露 capcut 命令。仓库里有 README.zh-CN.md 中文文档。

几个可选组件决定你能否用上特定命令：caption 默认需要 Whisper，render 需要 FFmpeg，自动读取媒体元数据需要 ffprobe，translate 需要 ANTHROPIC_API_KEY。不装这些，其余命令照常使用。

如果你用过旧版本，先升级。0.17.2 及以前生成的 fixture 包可能带有稳定设备标识；0.17.0 及以前还存在本地命令与滤镜注入路径、不安全的临时文件与凭据输出行为。前者在 0.18.0、后者在 0.17.1 修复，官方建议执行 npm install -g capcut-cli@latest。

最短能跑通的用法

capcut doctor
capcut quickstart my-first --video clip.mp4 --srt captions.srt
capcut info ./my-first/ -H

三步分别是：检查本机环境，在当前目录下建一个叫 my-first 的工程并把视频与字幕放上轨道，再把工程信息读回来确认。打开生成的工程，轨道仍是可编辑状态，不是压平的成片。

关键参数

• --video / --srt：quickstart 的输入，指定素材视频与字幕文件。
• --json：检查类命令输出结构化 JSON，拼到脚本或交给模型时用这个。
• --words <file.json|->：从外部对齐器的逐词时间戳建字幕，- 表示从标准输入读。
• --audio-stream：多音轨转写时指定音轨。
• --active-timeline：新版本 CapCut 的活跃文档可能不在项目根目录，这个开关显式跟随 Timelines/project.json 指针；遇到无效、已删除、符号链接或冲突的选中时间线会拒绝执行。
• --dir <folder> 与 --recursive：relink 用，递归搜索嵌套素材目录；重名文件会记在 ambiguous 里且不做改动。
• --frame-grid 与 --fix：lint 的帧网格检查与修复开关。
• --min-script-match：中英文字符级对齐的写入闸门，不达阈值就不写。
• --lexicon：tts 的发音词典。
• --strict 与 --verify：render 的保真度统计与输出时长核对。
• --plan 与 --apply-plan：先把批量计划绑定到草稿，复核后再执行。

结果在哪里看

写入的目标是本地草稿库里的工程目录，改完用 CapCut 或剪映打开继续调整、渲染，发布这一步仍然由人点。macOS 上草稿库位于 ~/Movies/CapCut/User Data/ 下面，Windows 的具体路径在 README 节选里没有写出来，仓库提到 agent 技能里会教这两个平台的位置。

终端本身也会给结果。info、tracks 这类命令直接打印内容，加 --json 得到可解析的结构。fixture 命令会生成 SANITIZE_REPORT.json，记录脱敏检查是否通过，检查失败会返回非零退出码。restore --list 会列出每一步背后对应的命令。完整的版本变更看仓库里的 CHANGELOG.md。

实际使用中的坑

• CapCut 7.x 的改动被丢弃（待解决）：真实的 CapCut 7.7 工程把活跃文档放在 Timelines/<main_timeline_id>/draft_info.json，而项目根目录下的 draft_content.json 不是当前生效的那份。这是 Issue 列表里讨论最多的一条（13 条评论），到目前仍标记为待解决，用 7.x 的读者需要先用 diagnose --active-timeline 看清结构再动手。
• CapCut 8.7（Windows）改了不生效（已解决）：有用户反馈 add-video / edit 的改动被忽略，原因是该版本的时间线可能由 template-2.tmp 与 draft_meta_info.json 驱动，而不是 draft_content.json。后续版本已处理。
• 文件名冲突静默跳过（已解决）：add-video 与 add-audio 把源文件复制进 assets/video/<basename> 时，只按文件名判断，重名会被直接跳过且不给警告。后来补上了提示。
• 文本区间偏移按字节算（已解决）：text-ranges 一度把调用方的 code unit 索引转成 UTF-16LE 字节再写入 content.styles[].range，而 CapCut 国际版按 code unit 存储，中文与 emoji 的区间因此错位。已修复。

和同类放在一起看

这两个对比项都被标为同功能，但取向不同，capcut-cli 在这两件事上都不占优：它不带任何现成的影片风格包，也不碰 CapCut 的付费素材解锁。你要的是「打开就有一套成片风格」，该去看 lemo-opuscar；你要的是解锁 Pro 素材与无水印导出，该去看 cap-cut-Unlocker。capcut-cli 的适用范围只有一类：本地草稿文件的批量修改与自动化。

适合谁

手上有一批剪映或 CapCut 工程要批量改字幕、统一调速、做长转短，并且希望脚本或 AI agent 能直接驱动的人，这个项目对得上。它把草稿当成结构化数据来读写，检查类命令又能先看清结构再动手，适合接进已有的自动化流程。

做完就想要一份成片、不想再打开剪辑软件的人，它帮不上忙，渲染与发布仍在 CapCut 或剪映里完成。只偶尔改一两条视频的人，学命令行的成本高于直接在界面里拖。用最新版 CapCut 且工程结构特殊的人要留意上面提到的活跃时间线问题，先 diagnose 再写。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。