| name | cut |
| description | 控制 剪映 (JianYing/CapCut) 与 Adobe Premiere Pro 两款视频剪辑软件的统一 skill。 让 AI 编程 agent（Codex CLI / Claude Code / OpenCode / Kimi Code / Qwen Code 等任意支持 skill 或 MCP 的工具） 能够读取当前时间轴状态、批量导入素材、裁切片段、添加字幕与转场、混音、并触发导出渲染。 使用本 skill 的场景包括但不限于：用户说"帮我把这些视频剪一下"、"自动给视频加字幕"、 "在剪映里把这段切两半"、"让 Premiere 把这几个素材按顺序排到时间轴上"、"批量加水印"、 "导出 1080p"、"读取一下我剪映里现在有什么素材"、"自动做个 vlog 混剪"。 涵盖视频剪辑、字幕生成、特效转场、音频处理、批量渲染、跨平台（Windows + macOS）。 只要用户提到 剪映、CapCut、JianYing、Premiere、Pr、视频剪辑、时间轴、轨道、片段、字幕、转场、 调色、混音、渲染导出 等任何视频后期相关词，都应优先使用本 skill。 |
Cut — 统一的视频剪辑操控 skill
本 skill 让你（agent）像操作一个视频剪辑助理一样操作 剪映 与 Premiere Pro。
两种软件共用一套上层接口（CLI / MCP / HTTP），底层各走各的实现路径：
剪映走 draft 文件操控（解析编辑 draft_content.json），Premiere 走 pymiere（Python 封装 ExtendScript）。
设计哲学：剪映没有官方 API，但它的工程文件是 JSON，结构公开可解析；
Premiere 有官方扩展机制但接入繁琐，pymiere 已封装好大部分常用操作。
本 skill 把两条路径抽象成同一组动词（import / split / trim / text / transition / effect / audio / export），
agent 只需要学一套接口。
兼容性
- Python 3.9+
- 剪映专业版 5.x+（Windows/macOS，draft 文件操控模式）
- Adobe Premiere Pro 2022+（通过 pymiere，需运行中并启用脚本接口）
- 可选：pyautogui（剪映导出辅助）、ffmpeg/ffprobe（音频预处理与导出 QA）、Flask（HTTP API）
0. 触发判断（你应该用本 skill 当……）
只要满足以下任一条件，立即读本 skill 的 references/ 深入：
- 用户提到剪映、CapCut、JianYing、Premiere、Pr、视频剪辑
- 用户给出多个视频/音频文件并要求"剪"、"拼接"、"加字幕"、"加转场"、"批量导出"
- 用户已经在剪映/Premiere 里有项目，想读取当前状态或继续编辑
- 用户要做 vlog、混剪、教学视频、产品演示视频等后期工作流
- 用户问"怎么用代码/agent 控制剪映"、"Premiere 能不能脚本化"
不要把本 skill 用于：纯 ffmpeg 命令行转码（用 ffmpeg skill）、视频理解分析（用 video-understand）、AI 生成视频（用 image-generation/video-understand）。
1. 工作流速总（30 秒上手）
无论用哪种集成形态，工作流都是 4 步：
1. detect → 检测本机平台、剪映/Premiere 安装、活跃项目
2. get_state → 读取当前项目状态（素材池、轨道、片段、选中元素）
3. plan/edit → 对一句话需求先生成专业剪辑计划，再执行 import / split / trim / text / transition / effect / audio
4. export + qa → 触发渲染输出并做成片质量验收
第 2 步是关键：本 skill 强调"上下文感知"。在你做任何修改前，先调一次 cut-cli get-state 或对应 MCP 工具，把当前项目快照读进来，再决定下一步。盲目修改 draft 文件很容易让剪映加载失败。
2. 集成形态总览
本 skill 同时提供 4 种调用方式，按场景选择：
| 形态 | 适用场景 | 入口 | 学习成本 |
|---|
| 纯 SKILL.md 文档 | agent 想自己写代码、需要深度定制 | 本文件 + references/ | 最低 |
| 内置 CLI（cut-cli） | Codex/Kimi/Qwen 等 shell 友好的 agent | python -m cut.cli | 低 |
| MCP Server | Claude Desktop / OpenCode / 任何 MCP 客户端 | python -m cut.mcp_server | 中 |
| HTTP API | 长任务、Web 集成、跨进程协作 | python -m cut.http_api | 中 |
推荐路径：
- Codex CLI / Kimi Code / Qwen Code → 用 CLI（最快上手）
- Claude Code / Claude Desktop → 用 MCP Server（原生支持 tool_call）
- OpenCode → CLI 或 MCP 都行
- 需要长期协作（如渲染队列）→ HTTP API
具体安装与配置见 references/agent-integration.md。
3. 后端选择
每个操作都可以指定 --backend（CLI）/ backend 参数（MCP/HTTP）：
| Backend | 标识 | 实现路径 | 限制 |
|---|
| 剪映 | jianying | 直接读写 draft_content.json | 修改后需重启剪映生效；导出需 UI 辅助 |
| Premiere | premiere | pymiere → ExtendScript | 需 Premiere 运行中；首次需信任脚本 |
剪映后端的最大特点是离线编辑：你甚至不需要剪映开着就能改 draft，改完用户重开项目即可看到效果。
Premiere 后端是在线编辑：必须 Premiere 处于打开状态，所有操作实时反映在 UI 上。
4. 核心操作动词（与命令一一对应）
| 动词 | 含义 | 剪映支持 | Premiere 支持 |
|---|
detect | 检测环境与活跃项目 | ✅ | ✅ |
get-state | 读取项目概要（上下文感知核心） | ✅ | ✅ |
list-materials | 列出素材池 | ✅ | ✅ |
get-timeline | 读取所有轨道与片段 | ✅ | ✅ |
import | 导入视频/音频/图片到素材池 | ✅ | ✅ |
split | 在指定时间点把片段切成两段 | ✅ | ✅ |
trim | 调整片段入点/出点 | ✅ | ✅ |
add-text | 添加文字/标题/字幕 | ✅ | ✅ |
add-transition | 在两段之间加转场 | ✅ | ✅ |
add-effect | 应用特效（滤镜/调色/动画） | ✅ | ✅ |
set-audio | 音量/淡入淡出/降噪 | ✅ | ✅ |
export | 导出渲染（剪映需 UI 辅助） | ⚠️ | ✅ |
plan / create_plan | 从一句话生成专业剪辑执行计划 | ✅ | ✅ |
qa / quality_check | 导出后成片质量验收 | ✅ | ✅ |
详细参数、返回结构、错误码见 references/jianying-operations.md 与 references/premiere-operations.md。
5. 上下文感知（最重要的事）
修改前必读状态。本 skill 的 state 模块提供以下只读接口：
from cut.context import get_project_state
state = get_project_state(backend="jianying")
agent 拿到这个快照后，再决定要不要 split / trim / add-text。这避免了"瞎改 draft"导致的崩溃。
更多上下文接口见 references/context-awareness.md。
5.5 专业剪辑导演层（一句话到执行计划）
当用户只给一句话（例如"自动做个旅行 vlog"、"剪成 30 分钟影视解说"）时，不要直接堆命令。
先调用 python -m cut.cli plan "<用户需求>" 或 MCP cut.create_plan：
- 识别长视频/短视频、平台、目标时长、节奏、叙事结构
- 生成 edit decision list：素材导入、粗剪、字幕、转场、混音、调色、导出、QA
- 先读
get-state，再按计划执行具体剪辑动作
- 导出后调用
quality_check 验证时长、码率、视频/音频流、分辨率、帧率
导演层是确定性计划器，不替代真正素材理解；如需要镜头语义理解、ASR 或节拍检测，应结合 examples/ 或外部识别服务生成素材标签后再规划。
6. 跨平台路径与差异
剪映 draft 路径因平台而异：
| 平台 | 路径 |
|---|
| Windows | %LOCALAPPDATA%\JianyingPro\User Data\Projects\com.lveditor.draft\ |
| macOS | ~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft/ |
| Windows (CapCut 国际版) | %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\ |
| macOS (CapCut 国际版) | ~/Movies/CapCut/User Data/Projects/com.lveditor.draft/ |
cut.platform.detect() 会自动找路径、识别剪映版本、检测 Premiere 安装。永远不要硬编码路径，永远走 platform 模块。
完整差异表与检测逻辑见 references/cross-platform.md。
7. 剪映 draft 文件结构（必读）
draft_content.json 是剪映项目的核心，所有素材、轨道、片段、特效、动画都在里面。
你不需要全部记住，但需要理解三层结构：
materials → tracks → segments
(素材池) (轨道) (片段)
materials 是仓库，记录所有导入的原始素材（视频/音频/图片/文本/贴纸/特效资源）tracks 是时间轴上的轨道，按类型分组（video/audio/text/sticker/effect）segments 是轨道上的具体片段，每个 segment 引用一个 material 的 ID，并指定在时间轴上的位置（target_timerange）和素材内部的入点（source_timerange）
完整 schema（含 material_animations、effects 链路、scale_x/scale_y/transform、keyframe_refs 等）见 references/jianying-draft-schema.md。
修改 draft 前务必读这份文档，否则容易写坏结构。
8. Premiere pymiere 集成要点
pymiere 通过 ExtendScript 桥接 Premiere，要求：
- Premiere Pro 已打开，并加载了一个项目
- 首次运行需在 Premiere 中"编辑 → 首选项 → 脚本"启用脚本调试（具体版本路径略有差异）
- pymiere 通过 CEP WebSocket 与 Premiere 通信，第一次调用会有 2-3 秒延迟
pymiere 的对象层级：
import pymiere
app = pymiere.objects.app
project = app.project
seq = project.activeSequence
tracks = seq.videoTracks
clip = tracks[0].clips[0]
完整 API 列表与反向读取模板见 references/premiere-operations.md。
9. 安全规则（强制遵守）
- 永远先备份 draft：剪映后端任何写操作前，自动复制
draft_content.json 到 .bak。cut.jianying.draft.Draft 类已内置此行为，但如果你直接改文件，必须自己 cp 一份。
- Premiere 操作不可撤销链式调用：pymiere 的
undo 不可靠，做连续修改前调 app.project.save() 先存档。
- 不要并发写 draft：剪映后端用文件锁，但你仍应串行调用。
- 不要修改
draft_meta_info.json：那是剪映的索引文件，改了会导致项目列表错乱。只改 draft_content.json。
- 导出大文件用 HTTP API：CLI 会阻塞，MCP 超时 30s，HTTP API 是异步的。
10. 快速示例
示例 A：用 CLI 读取剪映项目状态
$ python -m cut.cli detect
{
"platform": "darwin",
"jianying": {"installed": true, "version": "5.9.0", "drafts_dir": "/Users/me/Movies/JianyingPro/User Data/Projects/com.lveditor.draft"},
"premiere": {"installed": true, "version": "24.0", "running": false}
}
$ python -m cut.cli get-state --backend jianying --project my_vlog
{... 见第 5 节 ...}
示例 B：用 MCP tool_call 切分片段
{"tool": "cut.split", "input": {
"backend": "premiere",
"track_index": 0,
"clip_index": 2,
"at_seconds": 15.5
}}
示例 C：用 Python 直接调
from cut.jianying.draft import Draft
from cut.jianying.segments import split_segment
draft = Draft.open(project_name="my_vlog")
track = draft.video_tracks[0]
seg = track.segments[2]
split_segment(draft, seg, at_us=15_500_000)
draft.save()
print("完成。请在剪映中重新打开项目查看。")
更多完整示例（批量裁切、ASR 自动字幕、双轨混剪）见 examples/ 目录。
11. 文件导航
| 你想做的事 | 看哪里 |
|---|
| 理解剪映 draft 文件结构 | references/jianying-draft-schema.md |
| 查剪映某操作的具体参数与返回 | references/jianying-operations.md |
| 查 Premiere pymiere 操作 | references/premiere-operations.md |
| 处理 Win/Mac 差异 | references/cross-platform.md |
| 实现上下文感知/反向读取 | references/context-awareness.md |
| 从一句话生成专业剪辑计划并做成片 QA | references/professional-workflow.md |
| 集成到某个 agent 工具 | references/agent-integration.md |
| 看完整端到端示例 | examples/*.py |
| 看 CLI 完整命令参考 | scripts/cut/cli.py 顶部 docstring |
12. 故障排查速查
| 症状 | 原因 | 解决 |
|---|
| 剪映打开项目提示"文件已损坏" | draft 改坏了 | 用 .bak 恢复；检查 JSON 合法性 |
| pymiere 连接超时 | Premiere 未运行 / 未启用脚本 | 开 Premiere → 首选项启用脚本 |
cut-cli detect 找不到剪映 | 路径检测失败 | 看 references/cross-platform.md 手动指定 |
| split 后片段不见了 | source_timerange 越界 | 先 get-timeline 看 segment 的 source_range |
| 字幕添加后位置错乱 | 没指定 track_index | 默认追加到第一条 text 轨，需精确指定 |
13. 版本与兼容性
- v1.0：剪映 draft 操控 + Premiere pymiere 封装 + CLI + MCP + HTTP
- 剪映支持版本：5.0+（draft schema 在 4.x 与 5.x 有差异，目前以 5.x 为准）
- Premiere 支持版本：2022+（pymiere 要求）
- Python：3.9+（因 pymiere 依赖 3.9+）
向后兼容策略：剪映版本升级导致 draft schema 变化时，platform.detect() 会返回 schema_version，Draft.open() 据此选择解析器。如遇不兼容，会抛出 UnsupportedSchemaError 并提示用户升级 skill。
下一步建议：先读 references/agent-integration.md 选择你的 agent 集成方式，再读对应后端的 operations 文档。
