capcut-cli：实践指南

作者：袖梨 2026-10-04

准备试用capcut-cli之前，先别急着安装；这个项目提供的是独立的非官方 CLI 用于编辑 CapCut 和 JianYing（剪映）项目 — 字幕、时间、速度、音量、模板，将长格式剪成短格式，不需要API。对软件开发任务来说，依赖、接口和异常处理往往比主路径更影响采用往往决定它能否落地，不能只用安装成功来判断。短测时我会在隔离分支完成一个可回滚的小任务，并保留安装步骤、接口契约、测试结果和错误信息的结果，方便团队复盘。如果团队属于需要可检查开发流程而非单次演示的工程师，它有继续测试的理由；否则先看替代方案会更省时间。

renezander030/capcut-cli 项目截图 1

capcut-cli

英语 | 中文

从终端或任何 LLM 代理创建和编辑真实的 CapCut / JianYing 项目。

在 CapCut 中打开结果，每个轨道仍然可编辑。 capcut-cli 直接在本地草稿存储上工作：JSON 输入、JSON 输出（无上传）、API、MCP 服务器或 HTTP 守护程序。

同样来自维护者： 500 年冻结的时间：印加儿童之谜，来自 青铜时代玩笑 的 14:49 纪录片。

raw recording → silence-aware cuts + styled captions → editable CapCut / JianYing draft

▶ 带字幕的输出示例（60 秒）

https://github.com/user-attachments/assets/4e6ee99c-0745-4cfb-8e9b-ad873fb1259b

安装并打开您的第一个可编辑草稿

先决条件： 节点 ≥ 18（仅限内置 - 无本机模块）。可选工具解锁特定命令：用于 caption 的 Whisper、用于 render 的 FFmpeg、用于自动媒体元数据的 ffprobe 以及用于 translate 的 ANTHROPIC_API_KEY。

npm install -g capcut-cli

来自 Python：pip install capcut 包装相同的二进制文件 - capcut.run("quickstart", "my-short", video="clip.mp4", ratio="9:16") - 请参阅 python/README.md。

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

结果： 一个真正的本地项目，在可编辑轨道上包含视频和字幕 - 而不是扁平导出。在 CapCut 或 JianYing 中打开它以进行检查、调整和渲染。发布点击仍然是人性化的。

有用？ 明星 capcut-cli 帮助其他编辑和代理构建者找到它。

如需 AI 代理的更多实用工具，从视频自动化到发货前检查，在 GitHub 上关注 René。

从源代码构建：git clone https://github.com/renezander030/capcut-cli && cd capcut-cli && npm install && npm run build（然后 npm link 以公开 capcut）。或者运行任何命令而不安装：npx capcut-cli <command>。

[!IMPORTANT] 使用旧版本之前先升级。 使用 0.17.2 及以下版本制作的夹具捆绑包可能包含稳定的设备标识符，并且必须视为未经消毒的 (#59)。 0.17.0 之前的版本还包含本地 command/filter 注入路径和不安全的临时文件或凭证输出行为。这些问题分别在 0.18.0 和 0.17.1 中得到修复。运行 npm install -g capcut-cli@latest 并查看 变更日志 了解完整详细信息。

免责声明： 这是一个独立的、社区维护的项目。 不隶属于、赞助或认可 CapCut、JianYing 或 ByteDance Ltd。“CapCut”和“JianYing”（剪映）是 ByteDance Ltd 的商标。所有产品名称、徽标和品牌是其各自所有者的财产，此处仅用于识别（命名）目的。

任何 LLM 代理都可以驱动的 CapCut / JianYing 的独立 CLI — 零依赖性，无服务器，两个命名空间位于一个二进制文件中。

JSON in，JSON out：每个命令直接读取和写入本地草稿存储，没有 MCP 服务器或 HTTP 守护程序。在较新的 CapCut 版本上，它会检测并同步每个可读时间轴目标，而不是假设 draft_content.json 是唯一的事实来源。这为任何模型（Claude、DeepSeek、GLM、Kimi）提供了检查、构建、字幕、字幕、翻译和长格式剪切的确定性边界。

有四种使用方式：

  • CLI — npm install -g capcut-cli，然后 capcut <command> <project>
  • 库 — import { loadDraft, lintDraft, saveDraft } from "capcut-cli"（类型化，零深度）
  • 队列运行程序 — capcut serve 从标准输入读取 JSONL 作业，适用于 n8n / Make / Coze
  • 代理沙箱（实验性） — 为三个只读 MCP 工具构建 capcut-core.wasm，具有零文件系统、网络、环境、时钟、随机、stdio 或进程导入

为您的代理人提供技能

一条命令将 capcut-edit 技能安装到 Claude Code、Codex、Cursor、OpenCode 以及 skills 安装程序支持的其他代理中：

npx skills add renezander030/capcut-cli

Claude Code 也可以将其作为插件加载：

/plugin marketplace add renezander030/capcut-cli
/plugin install capcut-cli@capcut-cli

该技能教会代理每个命令、渐进披露习惯（首先检查，切勿转储整个草稿）、草稿存储在 macOS 和 Windows 上的位置，以及淡入淡出、Ken Burns 和长到快捷切换的确定性脚本。它会触发英文和中文请求（剪映、字幕、草稿）。

面向代理的无能力 Wasm 工具

将 AI 助手与 capcut-cli 一起使用吗？给它一个更安全的“看，不要碰”模式。

可选的 Wasm 工具可以让 AI：

  • 描述 CapCut 项目内部的内容；
  • 显示两个版本之间发生了什么变化；和
  • 发现常见的时间线和字幕问题。

它只能检查您交给它的项目信息。它无法浏览您的文件、上网、读取密码或 API 密钥、打开其他应用程序或更改项目。

当您希望 AI 以尽可能少的访问权限审阅草稿时使用它。 当您自己使用 capcut-cli 或希望 AI 进行编辑或渲染时请跳过它 - 普通的 CLI 仍然可以完成这些工作。此功能是实验性的、可选的，除非您进行设置，否则不会改变任何内容。 技术细节和设置 →

实验性 wasm/capcut-core 源包将确定性 JSON-in/JSON-out 边界移动到 WebAssembly 组件中：

  • inspect 与 capcut info 匹配以获得有效草稿。
  • diff 与 capcut diff 匹配进行结构更改。
  • lint-portable 运行 capcut lint 的显式、奇偶校验测试子集，不需要主机文件或媒体探测。

主机读取草稿并将其 JSON 作为工具输入传递。该组件本身没有环境功能，并且 CI 在通过 Wassette over MCP 行使所有三个功能之前证明构建世界具有零导入。从源代码检查中，使用 npm --prefix wasm/capcut-core ci && npm run wasm:verify 构建它；设置和安全详细信息位于 组件 README 中。

使用 capcut-cli 构建

  • OpenChatCut — 将代理编辑的时间线、本地媒体、音频和字幕导出到真实的 CapCut / JianYing 草稿中以供审核和渲染。

用 capcut-cli 构建了一些东西？ 打开一个展示问题，其中包含公共链接、关于其功能的一句话以及可选的屏幕截图或演示。

项目描述由其维护者批准。纳入并不意味着认可或隶属关系。

命令

默认为 JSON（通过管道传输到 jq）；添加 -H 作为人类可读的表格。传递 --jianying 以使用 JianYing 枚举命名空间。运行 capcut <command> --help 以获得完整标志。

集团 命令
检查 info · tracks · materials · version · lint
浏览/钻取 segments · texts · segment · material
创建 init · quickstart · compile（根据 JSON 规范构建草案）
预览 render（低分辨率 ffmpeg 代理 — 不是 CapCut 的最终渲染）
添加 add-video · add-audio · add-text（支持维基媒体 URLs，已通过许可证检查）
编辑/动画 修剪·速度·音量·过渡·遮罩·text/image动画·缓和曲线
模板 应用和提取可重用布局·make-preset（便携式文本样式预设）
字幕和 i18n caption · import-srt · export-srt (line/word SRT + VTT) · translate (多语言草稿克隆)
效果 sfx · chroma（色度键） · matting（智能背景去除）
长→短 cut · detect-scenes（ffmpeg 场景切换检测） · detect-silence · detect-retakes（重复拍摄）
自动化 serve（无状态JSONL运行器）·migrate·doctor·sync-timelines（8.7镜像修复）

每个命令、选项和退出代码的完整参考：docs/command-reference.md（简体中文：docs/command-reference.zh-CN.md）。

商业工作

与赞助分开：如果您正在将 capcut-cli 构建到产品中，或者您需要它做一些它尚未完成的事情，我会承担少量的集成工作。写信给 [email protected] 并说明您正在构建的内容。

它是如何运作的

CapCut/JianYing 将每个项目存储为本地 JSON。 capcut-cli 加载该存储，根据版本感知模式进行验证，应用您的编辑，然后以原子方式将其写回（使用 .bak）。任何地方都没有上传项目文件；没有任何东西作为服务运行。请参阅 docs/version-support.md 了解 CapCut/JianYing 版本和它理解的架构标志。

文档和示例

  • docs/command-reference.md — 每个命令和标志 (简体中文)
  • docs/quickstart.zh-CN.md — 剪映快速上手（JianYing-first 快速入门，简体中文）
  • 示例/ — 端到端配方（VO 对齐、服务自动化、批量字幕校正）
  • docs/version-support.md · docs/jianying-encryption.md
  • CHANGELOG.md · 发布 — 新增内容
  • Draftcat — 兄弟项目：受治理的 AI 管道（Go、MIT），相同的单二进制、无 API 设计
  • Skillgate — 兄弟项目：确定性终点线门（节点，MIT），用于当您的代理在测试通过之前报告“完成”时

商标

CapCut™和JianYing™（剪映）是ByteDance Ltd的商标。该项目是非官方的，不隶属于ByteDance，也不受其认可；这些标记主要用于描述互操作性。

相关文章

精彩推荐