用 AI Agent + MCP 驱动剪映草稿自动化：基于 pyJianYingDraft 的工程实践

本文从一线 AI-Native 全栈工程师视角，详细拆解如何利用 pyJianYingDraft 开源库 + MCP 协议 + AI Agent，实现剪映视频草稿的智能化生成。包含完整的架构设计、JSON 结构分析、二次开发方向和 Agent 能力设计。

一、为什么需要 AI 驱动的剪映草稿自动化？

视频剪辑是内容创作的核心环节，但剪映（JianYing Pro）的草稿操作本质上是大量重复性的 UI 点击：拖素材、设定时长、调整位置、添加字幕……这些操作如果能让 AI 来"理解意图并生成"，效率提升是数量级的。

核心思路：剪映的草稿本质是一个 draft_content.json 文件。如果我们能用 AI 生成这个 JSON，就等于用 AI 完成了剪辑工作。

二、前提条件：理解 draft_content.json 的本质

2.1 草稿文件的存储位置

剪映专业版的每个项目都存储在本地目录下，核心文件为：

项目目录/
├── draft_content.json    # 草稿核心数据（轨道、片段、素材引用）
├── draft_meta_info.json  # 项目元信息（名称、创建时间）
└── Resources/            # 引用的媒体资源

2.2 draft_content.json 核心结构

draft_content.json 是一个复杂的嵌套 JSON，核心结构如下：

{
  "id": "项目唯一ID",
  "name": "项目名称",
  "duration": 30000000,
  "tracks": [
    {
      "type": "video",
      "segments": [
        {
          "id": "片段ID",
          "material_id": "素材引用ID",
          "target_timerange": {
            "start": 0,
            "duration": 5000000
          },
          "source_timerange": {
            "start": 0,
            "duration": 5000000
          },
          "extra_material_refs": []
        }
      ]
    }
  ],
  "materials": {
    "videos": [
      {
        "id": "素材ID",
        "path": "/path/to/video.mp4",
        "type": "video",
        "width": 1920,
        "height": 1080,
        "duration": 10000000
      }
    ],
    "audios": [],
    "texts": [],
    "stickers": [],
    "effects": [],
    "canvases": [],
    "speeds": []
  },
  "canvas_config": {
    "width": 1920,
    "height": 1080,
    "ratio": "16:9"
  }
}

关键理解：

• 时间单位：全部使用微秒（microseconds），1秒 = 1,000,000 微秒
• 轨道（Track）：类似 Photoshop 的图层，每个轨道包含多个片段
• 片段（Segment）：通过 material_id 引用 materials 中的具体素材，并通过 target_timerange 定义在时间线上的位置
• 素材（Material）：实际的视频、音频、文字、贴纸等资源定义

2.3 AI 生成的核心挑战

直接让大模型生成完整的 draft_content.json 几乎不可能，原因包括：

1. 结构复杂：嵌套层级深，字段多，ID 引用关系复杂
2. 时间精度：微秒级的时间计算对 LLM 不友好
3. 业务语义缺失：JSON 字段名不具备自然语言可读性
4. 版本兼容：不同版本的剪映 JSON 格式有差异

因此，我们需要一个"中间语言层"——将 JSON 转化为自然语言描述，再由 AI 操作这个语义层。

三、完整技术方案设计

3.1 架构总览

用户意图输入
"制作一个30秒产品宣传片，包含3个场景，配上背景音乐"
        |
        v
AI Agent 编排层
- 理解用户意图
- 决策素材选择、时间编排、位置布局
- 生成"自然语言草稿指令"
        |
        v
MCP Server（草稿工具层）
- 接收自然语言指令
- 通过 pyJianYingDraft 转换为 draft_content.json
- 处理 ID 生成、时间换算、引用关系
        |
        v
draft_content.json 输出
写入剪映项目目录 → 打开剪映即可看到完整草稿

3.2 阶段 A：模板导入与自然语言转换

为什么需要"语言化"？

从第三方导入的草稿模板（比如从素材网站下载的专业模板）包含大量技术细节。AI 不需要理解每一个 JSON 字段，只需要知道"这个模板里有什么内容，在什么位置"。

自然语言转换示例

原始 JSON 片段：

{
  "type": "video",
  "segments": [
    {
      "material_id": "mat_001",
      "target_timerange": {"start": 0, "duration": 5000000},
      "source_timerange": {"start": 2000000, "duration": 5000000}
    }
  ]
}

转换为自然语言描述：

轨道_视频_1:
  片段1:
    类型: 视频
    素材: mat_001.mp4
    时间线位置: 0秒 ~ 5秒
    素材截取: 从第2秒开始，取5秒

模板语言化解析器设计

class DraftLanguageConverter:
    """将 draft_content.json 转换为自然语言描述"""

    SEGMENT_TYPE_MAP = {
        "video": "视频", "audio": "音频", "text": "文字/字幕",
        "sticker": "贴纸", "effect": "特效", "filter": "滤镜"
    }

    def convert_to_natural_language(self, draft_json: dict) -> str:
        """将完整草稿 JSON 转换为结构化自然语言"""
        result = []
        result.append(f"项目名称: {draft_json['name']}")
        cc = draft_json['canvas_config']
        result.append(f"画布尺寸: {cc['width']}x{cc['height']}")
        result.append(f"总时长: {self._us_to_seconds(draft_json['duration'])}秒")

        for track in draft_json["tracks"]:
            track_type = self.SEGMENT_TYPE_MAP.get(track["type"], track["type"])
            result.append(f"【{track_type}轨道】")
            for i, seg in enumerate(track["segments"]):
                mat = self._find_material(seg["material_id"], draft_json["materials"])
                start_us = seg['target_timerange']['start']
                dur_us = seg['target_timerange']['duration']
                result.append(f"  片段{i+1}:")
                result.append(f"    类型: {track_type}")
                result.append(f"    素材: {mat.get('path', mat.get('content', '未知'))}")
                result.append(f"    时间线: {self._us_to_seconds(start_us)}秒 ~ "
                            f"{self._us_to_seconds(start_us + dur_us)}秒")

        return "\n".join(result)

    def _us_to_seconds(self, us: int) -> float:
        return round(us / 1_000_000, 2)

    def _find_material(self, mid: str, materials: dict) -> dict:
        for cat, items in materials.items():
            if isinstance(items, list):
                for item in items:
                    if item.get("id") == mid:
                        return item
        return {}

3.3 阶段 B：通过 MCP Server 将自然语言指令转回草稿 JSON

MCP（Model Context Protocol）是当前 AI Agent 调用外部工具的标准协议。我们设计一个专门的 MCP Server 来处理草稿生成，暴露以下核心工具：

MCP 交互流程示例

Agent → MCP Server:
  1. call_tool("load_template", {"template_path": "/templates/promo.json"})
     ← 返回自然语言描述

  2. call_tool("create_draft", {"name": "产品宣传片_v1", "canvas": "16:9"})
     ← 草稿创建成功

  3. call_tool("add_video_segment", {
       "video_path": "/assets/intro.mp4",
       "start_time": "0s", "duration": "5s"
     })
     ← 视频片段添加成功

  4. call_tool("add_text_overlay", {
       "text": "张明 - 产品经理",
       "start_time": "6s", "duration": "4s",
       "position": {"x": 0.15, "y": 0.85},
       "style": "name_tag"
     })
     ← 人名条添加成功

  5. call_tool("add_audio_segment", {
       "audio_path": "/assets/bgm.mp3",
       "start_time": "0s", "duration": "30s",
       "volume": 0.3, "audio_type": "music"
     })
     ← 背景音乐添加成功

  6. call_tool("export_draft", {
       "output_dir": "/JianYing/drafts/产品宣传片_v1"
     })
     ← 导出成功

3.4 阶段 C：AI Agent 的智能决策层

这是整个方案中最有价值的部分——让 AI 来做"剪辑师"的决策。

Agent 需要决策的关键问题

Agent 核心设计

class VideoEditingAgent:
    """AI 剪辑 Agent - 核心决策层"""

    def __init__(self, llm_client, mcp_client):
        self.llm = llm_client
        self.mcp = mcp_client

    async def generate_promo_video(self, user_request, assets):
        # Step 1: 分析素材
        asset_analysis = await self._analyze_assets(assets)
        # Step 2: 规划视频结构
        video_plan = await self._plan_structure(user_request, asset_analysis)
        # Step 3: 决策时间和布局
        timeline = await self._design_timeline(video_plan)
        # Step 4: 通过 MCP 逐步生成草稿
        await self.mcp.call_tool("create_draft", {
            "name": video_plan["title"],
            "canvas": video_plan.get("canvas", "16:9")
        })
        for seg in timeline["segments"]:
            tool_map = {
                "video": "add_video_segment",
                "text": "add_text_overlay",
                "audio": "add_audio_segment",
                "sticker": "add_sticker",
                "sound_effect": "add_sound_effect"
            }
            await self.mcp.call_tool(tool_map[seg["type"]], seg)
        # Step 5: 导出
        return await self.mcp.call_tool("export_draft", {
            "output_dir": video_plan["output_dir"]
        })

关键决策场景详解

场景1：人名条（Name Tag）定位

async def _decide_name_tag_position(self, frame_analysis, speaker_info):
    """
    决策人名条位置：
    - 分析视频帧，检测人物位置
    - 人名条放在人物旁边但不遮挡主体
    - 通常在画面下方 15% 区域
    """
    return {
        "text": f"{speaker_info['name']} - {speaker_info['title']}",
        "start_time": speaker_info["speech_start"],
        "duration": "4s",
        "position": {"x": 0.15, "y": 0.85},
        "style": "name_tag",
        "font_size": 32
    }

场景2：关键词音效触发

async def _detect_keyword_moments(self, transcript):
    """从语音识别结果中检测关键词，在关键点添加音效"""
    prompt = f"从以下文本中提取适合用音效强调的关键词及其时间戳：{transcript}"
    keywords = await self.llm.chat(prompt)
    return [{
        "type": "sound_effect",
        "effect_path": f"/assets/sfx/{kw['category']}.wav",
        "trigger_time": f"{kw['timestamp']}s",
        "effect_type": "pop"
    } for kw in keywords]

四、pyJianYingDraft 的局限性与二次开发方向

4.1 当前版本的主要问题

4.2 二次开发路线图

Phase 1: MCP Server 封装层
├── 封装 pyJianYingDraft 核心 API 为 MCP Tools
├── 实现自然语言与JSON双向转换器
├── 添加素材资源库管理
└── 支持 fallback_loader 处理加密 JSON

Phase 2: Agent 决策层
├── 视频帧分析（人物检测、构图分析）
├── 语音识别 + 字幕时间戳对齐
├── 关键词检测和音效触发
├── 智能时间编排算法
└── 位置布局决策

Phase 3: 模板智能系统
├── 模板库管理和分类
├── 模板自然语言描述自动生成
├── 基于模板的智能替换和扩展
└── 多模板组合和混搭

Phase 4: 质量保障
├── 草稿 JSON 校验器
├── 版本兼容性处理
├── 自动化测试
└── 错误恢复机制

五、完整工作流示例：30秒产品宣传片

用户输入

"帮我制作一个30秒的产品宣传片，产品是一款智能手表。准备了3段产品视频、1段CEO讲解视频、1首科技感背景音乐。需要有人名条、产品特性字幕、转场效果。"

Agent 决策输出

{
  "title": "智能手表产品宣传片",
  "canvas": "16:9",
  "segments": [
    {"type": "video", "video_path": "/assets/close_up.mp4", "start_time": "0s", "duration": "5s"},
    {"type": "sound_effect", "effect_path": "/sfx/whoosh.wav", "trigger_time": "5s"},
    {"type": "video", "video_path": "/assets/ceo.mp4", "start_time": "5s", "duration": "8s"},
    {"type": "text", "text": "李明 - CEO", "start_time": "5.5s", "duration": "4s", "position": {"x": 0.15, "y": 0.85}, "style": "name_tag"},
    {"type": "video", "video_path": "/assets/features.mp4", "start_time": "13s", "duration": "8s"},
    {"type": "text", "text": "心率监测 | GPS定位 | 7天续航", "start_time": "14s", "duration": "6s", "position": {"x": 0.5, "y": 0.15}, "style": "subtitle"},
    {"type": "video", "video_path": "/assets/lifestyle.mp4", "start_time": "21s", "duration": "6s"},
    {"type": "text", "text": "智能生活 从此开始", "start_time": "23s", "duration": "4s", "position": {"x": 0.5, "y": 0.5}, "style": "title"},
    {"type": "audio", "audio_path": "/assets/bgm.mp3", "start_time": "0s", "duration": "30s", "volume": 0.25, "audio_type": "music"},
    {"type": "sticker", "sticker_resource_id": "brand_logo", "start_time": "27s", "duration": "3s", "position": {"x": 0.85, "y": 0.85}}
  ]
}

六、总结与展望

当前可实现的能力

• 通过 MCP Server 封装 pyJianYingDraft，AI Agent 通过自然语言工具调用来生成剪映草稿
• 模板导入后自动转换为自然语言描述，降低 AI 理解门槛
• Agent 层负责核心"剪辑师决策"：时间编排、位置布局、音频匹配
• 最终输出标准 draft_content.json，可直接在剪映中打开

需要持续投入的方向

1. pyJianYingDraft 二次开发：解决加密 JSON、轨道操作不完整等核心问题
2. 素材资源库：构建可被 AI 检索和选择的贴纸、音效、字体等资源库
3. 视觉分析集成：集成视频帧分析能力，让位置决策更智能
4. 版本兼容性：跟进剪映版本更新，保持 JSON 格式兼容
5. CapCut 国际化：pyJianYingDraft 的 CapCut 适配正在开发中

核心本质：把剪映的 JSON 草稿格式变成 AI 可以理解和操作的"画布"，通过 MCP 协议让 Agent 像人类剪辑师一样思考和创作。

作者：AI全栈-鹤哥 | 2026年8月18日 技术栈：Python + MCP + pyJianYingDraft + AI Agent