剪映 AI 编辑 MCP + Skill

自然语言剪辑规划、视频观察与草稿执行相互分离：视频观察器负责本地元数据、字幕和代表帧；Skill 负责需求引导、画面理解与紧凑编辑清单；MCP 负责确定性生成、参考草稿复用、批量换料、安全校验和本地阶段进度。

验证基线：剪映专业版 10.0.5.13816、pyJianYingDraft 0.3.0、MCP Python SDK 1.29.0。

目录

• src/jianying_ai_mcp/：批处理 MCP 服务
• skills/jianying-ai-editor/：可复用 Skill
• docs/capability_matrix.md：完整测试结论
• configs/：客户端配置样例
• tests/：从零生成、参考复用、批量换料及安全边界测试

MCP 工具

• get_jianying_capabilities：版本、能力与限制
• analyze_reference_draft：从明文或本机可解密草稿提取剪辑蓝图
• build_draft：一次提交编辑清单，从零生成草稿
• build_from_reference：复制蓝图并按轨道/片段换料换字
• batch_from_template：一个模板批量生成多份草稿
• analyze_video_source：提取带时间戳字幕和代表帧，支持缓存与局部复查
• save_video_observations：保存 Agent 实际读取代表帧后的结构化理解
• get_video_analysis_context：按时间范围和页码读取长字幕与缓存上下文

工具默认 dry_run=true，会在项目暂存区完整生成和校验，但不发布到剪映目录。正式发布不会覆盖同名草稿。

启动

Python 3.12：

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

需要分析在线视频时改用 -e ".[video-url]"。本地视频只需要系统已有的 ffmpeg/ffprobe，不需要 yt-dlp。

Skill 可从仓库安装到支持 Agent Skills 的客户端：

npx skills add . -g

然后按客户端使用 MCP 配置样例。

启动服务：

.\.venv\Scripts\python.exe -m jianying_ai_mcp

服务使用 stdio MCP；普通日志不写 stdout。客户端支持时会显示 [阶段] 日志和 progress，其他客户端仍可从返回值的 stages 查看阶段。

环境变量

• JIANYING_DRAFT_ROOT：剪映草稿根目录
• JIANYING_MCP_WORK_ROOT：暂存和参考蓝图目录
• JIANYING_EXE：剪映程序路径，用于检测版本
• JIANYING_DRAFT_CRYPTO：可选的 jy-draftc.exe 兼容读取器；启用加密草稿学习/复制
• JIANYING_MCP_TRANSPORT：默认 stdio，也可使用 sse 或 streamable-http
• JIANYING_FFMPEG / JIANYING_FFPROBE：视频观察器使用的可执行文件
• JIANYING_YT_DLP：可选，仅 URL 输入需要
• GROQ_API_KEY / OPENAI_API_KEY：可选，仅无字幕时的 Whisper 转写需要

ffmpeg/ffprobe 可从 PATH 自动发现，也可通过环境变量显式配置。视频和画面始终留在本机；只有无字幕且启用 Whisper API 时会上传压缩音频。

加密草稿读取

剪映保存后的 draft_content.json 可能是加密文本。0.3 通过已审计的 MIT 开源 jy-draftc 接口调用本机剪映目录中的 videoeditor.dll，支持分析、参考复制和批量换料。读取时会先复制到一次性工作目录，解密结果用完即删，绝不原地改写参考草稿。

仓库包含最小读取器源码 native/jy_draft_crypto.cpp，可用 MinGW-w64 执行 g++ -std=c++17 -O2 -municode -static -o jy-draftc.exe native/jy_draft_crypto.cpp 构建。随后配置 JIANYING_DRAFT_CRYPTO；JIANYING_EXE 必须指向同一套剪映安装。先调用 get_jianying_capabilities，确认 encrypted_draft_reader.available=true 再读取加密草稿。

视频理解

推荐先调用 analyze_video_source(detail="efficient", max_frames=24~40) 粗看。Agent 必须实际读取返回的代表帧后，才能调用 save_video_observations 声称理解画面。长视频先读字幕定位，再对候选区间用 start/end 局部复查，避免一次输入大量图片。

当前为语句级字幕时间戳，不是逐字强制对齐；代表帧也不是完整逐帧视频流。快动作、口型级同步、音乐节拍仍需专用分析器。

配置格式见 OpenCode 配置 和 通用 stdio 配置。

验证

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

测试前可使用 测试与反馈清单。

当前边界

当前不自动操作剪映内置音乐/音效库、TTS、节拍卡点和自动导出。独立视频观察器已支持旁挂字幕及可选 Whisper 语句级转写，但不等同于剪映内置字幕识别。蒙版、模糊背景及音量关键帧因当前版本实测不稳定而被显式拒绝。参考草稿支持明文 JSON；配置本地读取器后也支持有权访问的剪映加密草稿。

第三方许可说明见 THIRD_PARTY_NOTICES.md。

每次工具调用都返回版本兼容提示。若剪映版本与 10.0.5.13816 不同，客户端必须向用户说明预设、在线资源和草稿结构可能变化，并先生成小样抽检。