pyJianYingDraft 草稿自动化三步走：模板导入、自然语言化与那些没填完的坑

背景与热点解读

下午泡了杯茶，刷 GitHub 的时候又看到 pyJianYingDraft 的更新。这个库我关注挺久了，2026 年 7 月刚发布 0.3.0 大重构版本，算是目前最活跃的剪映草稿自动化 Python 工具。说实话，每次看到这类项目我都手痒——谁不想用代码批量生成视频草稿，然后让剪映直接打开编辑呢？

但现实总是比理想骨感。pyJianYingDraft 的 README 里写得挺坦诚，0.3.0 虽然经过大规模重构，支持了音视频轨道、文本、特效、转场及基于模板的素材替换，但已知局限性一长串：新版剪映（10.8+）视频蒙版支持不完整、批量导出在剪映 7+ 不可用、新版模板为非明文 JSON 需要额外读取器、从其他工程导入的轨道在新版可能排序异常。这些不是小问题，是直接卡住自动化流程的硬伤。

不过话说回来，这条技术路线本身是成立的。最近 Bilibili 上有个演示视频，用 jianying MCP 方案实现了自然语言到自动剪辑的完整操作——大模型接收指令，通过 MCP 协议调用剪辑工具，自动组装时间线并生成剪映可用草稿。端到端效果看着确实爽，贴纸添加、音效插入、字幕生成一气呵成。但视频后半段也暴露了部分特效组合在自动化流程中无法正常生效的边界情况，这正是我下面要重点聊的核心痛点。

技术原理拆解

先说清楚 pyJianYingDraft 到底在干什么。剪映的工程文件本质上就是一坨 JSON，里面描述了时间线、轨道、素材路径、特效参数、文本样式等等。pyJianYingDraft 做的事情就是用 Python 代码构建这坨 JSON，直接在文件系统层生成剪映草稿目录，跳过 UI 操作。

整个自动化链路可以拆成三步走。

第一步：加载模板

这是整个流程的地基。思路很简单——你不可能每次都从零手写 JSON，太容易出错也太慢。正确做法是准备一批经过人工验证的草稿模板，然后用 pyJianYingDraft 加载这些模板文件进行解析。

pyJianYingDraft 支持加载 v5.9 及以下版本的未加密草稿文件。加载之后，你可以解析出模板里的所有可变参数：视频素材路径和时长、美颜参数（磨皮强度、瘦脸程度等）、特效列表（哪些是片段级特效，哪些是轨道级特效）、人名条的位置坐标和样式、字幕的字体字号颜色描边位置、关键词的高亮样式、片头和片尾的模板结构。

这一步的关键在于"分析出具体的样式规则"。CSDN 上有篇实践博客把这个流程讲得比较完整，核心就是读取已有工程文件、解析 JSON 结构、提取可变素材槽位。你把一套验证过的模板拆解清楚，就知道哪些部分是固定的骨架，哪些部分是需要动态替换的血肉。

第二步：自然语言化

模板加载完，接下来就是把模板中的可变部分对应成大模型能理解的自然语言指令。这一步是整个流程中最有意思也最有挑战的环节。

举个例子，你的模板里有一个贴纸轨道槽位，传统做法是你写代码去填这个槽位。但现在你想让 AI 来做这件事——用户说"在这里加一个爱心贴纸"，大模型需要理解这句话，然后转化成对 pyJianYingDraft API 的结构化调用。

这里有两种路径。路径一：pyJianYingDraft 加 MCP 协议，把 pyJianYingDraft 的能力封装成 MCP 工具，大模型通过 system prompt 知道有哪些工具可用（比如 create_subtitle_draft、add_sticker、add_audio_effect），用户用自然语言描述需求，AI 解析提取参数后触发对应工具调用。ai-skills.video 上有一篇文章详细描述了这个方案，提供了系统提示词示例，展示了如何将大模型指令转化为结构化调用，跳过 UI 操作在文件系统层完成自动化草稿创建。路径二：VectCutAPI 的 MCP 功能。VectCutAPI 是专门为 AI Agent 设计的云端视频剪辑工具，全面兼容 MCP 协议。开发者通过本地 JSON 配置启动 stdio 通信服务，预设了创建项目、插入素材、添加关键帧、保存工程等指令。保存后生成以 dfd_ 开头的文件夹，复制到剪映草稿目录就能直接打开编辑。相比 pyJianYingDraft，VectCutAPI 在特效规范化方面更完整一些，涵盖了视频与音频轨道管理、图文排版、字幕同步、视觉特效引擎及关键帧动画等模块。

两条路径各有优劣。pyJianYingDraft 是本地库，灵活但需要自己封装 MCP 层；VectCutAPI 开箱即用但依赖云端服务。实际项目中两者可以互补：简单场景用 pyJianYingDraft 直接生成，复杂特效场景用 VectCutAPI 兜底。

第三步：直面现实问题

好，现在到了我最想吐槽的部分。

代码示例或实操演示

讲了一堆原理，来点实际的。下面是一个用 pyJianYingDraft 加载模板并替换素材的简化流程：

from pyJianYingDraft import Draft

# 第一步：加载已验证的草稿模板
draft = Draft.load("templates/beauty_vlog_template.draft")

# 解析模板结构，提取可变参数
for track in draft.tracks:
    print(f"轨道类型: {track.type}, 片段数: {len(track.segments)}")
    for seg in track.segments:
        print(f"  素材: {seg.material_id}, 时长: {seg.duration}")
        if hasattr(seg, 'effects'):
            for eff in seg.effects:
                print(f"    特效: {eff.type}, 参数: {eff.params}")

# 替换视频素材
video_track = draft.get_track("video")
video_track.segments[0].replace_material("new_video.mp4")

# 替换字幕文本
text_track = draft.get_track("text")
text_track.segments[0].text = "今天天气真好"

# 导出新的草稿文件
draft.save("output/new_draft.draft")

这个例子展示了模板加载的核心思路：加载到解析到替换可变部分再到导出。实际项目中，解析阶段会复杂得多，你需要遍历所有轨道，提取美颜参数、特效配置、人名条坐标、字幕样式、关键词样式、片头片尾结构，建立一份完整的"模板参数表"。

接下来是自然语言化的部分。用 MCP 封装后，系统提示词里的工具定义大致长这样：

{
  "tools": [
    {
      "name": "add_sticker",
      "description": "在指定时间点的视频轨道上添加贴纸",
      "parameters": {
        "type": "object",
        "properties": {
          "time_start": {"type": "number", "description": "开始时间（秒）"},
          "sticker_id": {"type": "string", "description": "贴纸素材ID"},
          "position": {"type": "object", "description": "贴纸位置坐标"}
        }
      }
    },
    {
      "name": "add_audio_effect",
      "description": "在指定轨道添加音效",
      "parameters": {
        "type": "object",
        "properties": {
          "track_index": {"type": "number"},
          "audio_path": {"type": "string"}
        }
      }
    }
  ]
}

大模型收到"在视频第 5 秒加一个爱心贴纸"这样的自然语言指令后，会调用 add_sticker 工具，传入 time_start: 5 和对应的贴纸参数。服务端收到调用后，再通过 pyJianYingDraft 或 VectCutAPI 修改底层 JSON，生成最终草稿。这条链路跑通之后，用户体验确实很丝滑。

实践建议

摸了这么多坑之后，给几条实在的建议。

模板要准备多套，且分版本管理。 剪映的草稿格式在不同版本之间有差异，v5.9 的未加密草稿和 10.8+ 的格式不完全兼容。你的模板库要按剪映版本分组管理，加载时先检查版本兼容性，别等到生成完草稿才发现剪映打不开。

模板解析结果要持久化。 每次加载都解析一遍 JSON 太慢。建议第一次解析后把"模板参数表"存成结构化 JSON 文件，后续直接读参数表，模板文件只做素材替换。这样模板加载从秒级降到毫秒级。

自然语言映射要做约束。 大模型很聪明，但它生成的参数可能超出模板支持范围。比如模板里字幕位置只有"顶部居中"和"底部居中"两个槽位，AI 却生成了"左上角偏移 20px"的坐标。你需要在工具定义里约束参数范围，或者在服务端做参数校验和兜底，否则生成的草稿在剪映里打开会出各种奇怪的错位。

特效组合要白名单化。 这是 pyJianYingDraft 最大的坑——不是所有特效组合都能正常工作。片段级特效和轨道级特效同时设置时，草稿文件在剪映里打开可能表现异常。建议维护一份"已验证特效组合白名单"，AI 生成的特效指令必须在白名单内，否则降级处理或提示用户手动调整。

pyJianYingDraft 和 VectCutAPI 配合使用。 简单的轨道管理和素材替换用 pyJianYingDraft 就够了，遇到复杂特效场景优先用 VectCutAPI 的 MCP 工具兜底。两者生成的草稿格式有差异，需要在中间层做格式转换适配。

总结与展望

回到最开始的问题：用 pyJianYingDraft 实现 AI 直接到剪映草稿的自动化，这条路走通了吗？

我的结论是：走通了一半。

模板加载和自然语言化的框架是成立的，MCP 协议让大模型调用剪辑能力这件事变得可操作。但 pyJianYingDraft 在规范化方面的不足是实打实的硬伤。最典型的就是视频片段特效和整个视频的特效不能同时支持——这不是一个无关紧要的边缘 case，而是实际视频制作中非常常见的需求组合。你想给某个片段加个放大特效，同时给整条视频加个色调滤镜？抱歉，当前版本的草稿结构可能无法正确表达这种组合，剪映打开后效果会丢失或错乱。

除了特效组合问题，还有几个缺口需要填：新版剪映模板的加密格式需要额外读取器支持；从其他工程导入的轨道在新版可能排序异常；批量导出功能在剪映 7+ 不可用。这些都是阻碍"AI 直达剪映草稿"这条路线落地的问题。

所以最终要想真正实现 AI 直接到剪映草稿的完整支持，还是需要持续开发。一方面要完善 pyJianYingDraft 对特效规范化的支持，至少把片段特效和整体特效的共存问题解决掉；另一方面 VectCutAPI 这类方案在特效引擎上更完整，可以作为补充，但也要解决本地草稿格式兼容的问题。

总的来说，这是一个正在快速演进但远未成熟的领域。pyJianYingDraft 0.3.0 已经迈出了很大一步，MCP 协议的接入让 AI 自然语言到草稿生成变得可行。但距离"AI 说一句话，剪映直接出片"这个终极目标，中间还有不少开发工作要做。下午茶喝完了，坑还在那儿，但至少方向是对的——保持关注，持续填坑。