【开源剪映小助手】项目概述

项目概述

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 工具函数详解
7. 依赖关系分析
8. 性能考量
9. 故障排查指南
10. 结论
11. 附录

引言

capcut-mate 是一个面向剪映（CapCut）的完全开源免费 的自动化处理与云端渲染辅助系统，基于 FastAPI 构建，支持独立部署 。该项目的核心价值在于为大模型赋能基础视频编辑能力，提供开箱即用的视频编辑技能 ，并已完全自动化整个剪映核心功能工作流 。项目能够直接连接大模型，实现多样化的智能视频编辑，使普通用户能够快速创建专业和高级的视频作品。

• 核心价值与目标

  • 开源免费：完全开源免费，降低视频内容生产的门槛，提升批量与自动化能力
  • 大模型集成：专注于为大模型赋能视频编辑能力，提供智能视频编辑解决方案
  • 独立部署：支持独立部署，满足不同环境和安全要求
  • 智能视频编辑：提供开箱即用的视频编辑技能，实现智能化视频创作
  • 灵活协作：可与 Coze 或 n8n 结合构建自动化工作流，也可连接剪映实现云端渲染

• 主要功能特性

  • 草稿创建与保存、素材批量添加（视频/音频/图片/贴纸）、字幕与特效配置、关键帧与遮罩、富文本样式生成
  • 时间线与素材信息生成工具，辅助自动化编排
  • 云端渲染提交与状态查询，以及草稿下载与本地剪映自动化导出
  • ：完整的工具函数集合，包括 URL 提取、贴纸搜索、数据格式转换等实用工具
  • ：智能视频编辑能力，支持与大模型的无缝集成

• 应用场景

  • 内容创作者批量生产短视频、图文混排视频
  • 企业级营销团队自动化生成系列视频
  • 教育/培训领域批量生成教学视频
  • 需要跨平台、可扩展的视频生产流水线
  • 国际化团队协作，支持多语言环境下的视频制作工作流
  • 大模型驱动的智能视频创作工作流
  • AI 辅助的视频内容生成与编辑

• 技术选型与设计理念

  • 后端：Python + FastAPI，OpenAPI 描述清晰，便于对接与测试
  • 自动化：基于 Windows UI 自动化库与剪映窗口交互，实现草稿导出自动化
  • 云渲染：通过腾讯云对象存储与 API Key 认证，实现云端渲染与素材分发
  • 桌面客户端：Electron + React，提供草稿下载、历史记录与日志查看等能力
  • 部署：Docker 化运行，便于在服务器或容器环境中部署
  • 智能化：支持与大模型集成，实现智能视频编辑和内容生成

项目结构

项目采用"API 层---服务层---工具层---自动化层"的分层设计，配合模板与草稿缓存机制，形成可复用的草稿基座与渲染管线。项目结构体现了开源免费、独立部署和智能视频编辑的设计理念。
#mermaid-svg-DIFGKYrqHo3mjRte{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-DIFGKYrqHo3mjRte .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-DIFGKYrqHo3mjRte .error-icon{fill:#552222;}#mermaid-svg-DIFGKYrqHo3mjRte .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-DIFGKYrqHo3mjRte .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-DIFGKYrqHo3mjRte .marker{fill:#333333;stroke:#333333;}#mermaid-svg-DIFGKYrqHo3mjRte .marker.cross{stroke:#333333;}#mermaid-svg-DIFGKYrqHo3mjRte svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-DIFGKYrqHo3mjRte p{margin:0;}#mermaid-svg-DIFGKYrqHo3mjRte .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-DIFGKYrqHo3mjRte .cluster-label text{fill:#333;}#mermaid-svg-DIFGKYrqHo3mjRte .cluster-label span{color:#333;}#mermaid-svg-DIFGKYrqHo3mjRte .cluster-label span p{background-color:transparent;}#mermaid-svg-DIFGKYrqHo3mjRte .label text,#mermaid-svg-DIFGKYrqHo3mjRte span{fill:#333;color:#333;}#mermaid-svg-DIFGKYrqHo3mjRte .node rect,#mermaid-svg-DIFGKYrqHo3mjRte .node circle,#mermaid-svg-DIFGKYrqHo3mjRte .node ellipse,#mermaid-svg-DIFGKYrqHo3mjRte .node polygon,#mermaid-svg-DIFGKYrqHo3mjRte .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-DIFGKYrqHo3mjRte .rough-node .label text,#mermaid-svg-DIFGKYrqHo3mjRte .node .label text,#mermaid-svg-DIFGKYrqHo3mjRte .image-shape .label,#mermaid-svg-DIFGKYrqHo3mjRte .icon-shape .label{text-anchor:middle;}#mermaid-svg-DIFGKYrqHo3mjRte .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-DIFGKYrqHo3mjRte .rough-node .label,#mermaid-svg-DIFGKYrqHo3mjRte .node .label,#mermaid-svg-DIFGKYrqHo3mjRte .image-shape .label,#mermaid-svg-DIFGKYrqHo3mjRte .icon-shape .label{text-align:center;}#mermaid-svg-DIFGKYrqHo3mjRte .node.clickable{cursor:pointer;}#mermaid-svg-DIFGKYrqHo3mjRte .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-DIFGKYrqHo3mjRte .arrowheadPath{fill:#333333;}#mermaid-svg-DIFGKYrqHo3mjRte .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-DIFGKYrqHo3mjRte .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-DIFGKYrqHo3mjRte .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DIFGKYrqHo3mjRte .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-DIFGKYrqHo3mjRte .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DIFGKYrqHo3mjRte .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-DIFGKYrqHo3mjRte .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-DIFGKYrqHo3mjRte .cluster text{fill:#333;}#mermaid-svg-DIFGKYrqHo3mjRte .cluster span{color:#333;}#mermaid-svg-DIFGKYrqHo3mjRte div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-DIFGKYrqHo3mjRte .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-DIFGKYrqHo3mjRte rect.text{fill:none;stroke-width:0;}#mermaid-svg-DIFGKYrqHo3mjRte .icon-shape,#mermaid-svg-DIFGKYrqHo3mjRte .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DIFGKYrqHo3mjRte .icon-shape p,#mermaid-svg-DIFGKYrqHo3mjRte .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-DIFGKYrqHo3mjRte .icon-shape .label rect,#mermaid-svg-DIFGKYrqHo3mjRte .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DIFGKYrqHo3mjRte .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-DIFGKYrqHo3mjRte .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-DIFGKYrqHo3mjRte :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 桌面客户端
配置与模板
自动化层
工具层
服务层
API 层
开源免费架构
智能视频编辑架构
大模型集成

AI Video Editing
机器学习模型

Video Generation
智能协作

Coze/n8n Workflows
开源免费

完全开源免费
独立部署

支持独立部署
工具函数

Utility Functions
FastAPI 路由

src/router/v1.py
中间件

PrepareMiddleware / ResponseMiddleware
业务服务

src/service/*
草稿下载器

src/utils/draft_downloader.py
日志/下载/媒体工具

src/utils/*
工具函数

src/utils/*
剪映控制器

src/pyJianYingDraft/jianying_controller.py
配置中心

config.py
模板目录

template/*
Electron 主进程

desktop-client/main.js
前端页面与组件

desktop-client/web/src/*

核心组件

• API 服务（FastAPI）

  • 路由集中于 v1 版本，覆盖草稿创建/保存、素材添加、特效/字幕/贴纸、关键帧/遮罩、富文本样式、时间线与素材信息生成、云端渲染提交与状态查询、URL 提取与序列转换等
  • 统一响应中间件与准备中间件保证请求与响应的一致性与可观测性
  • ：支持与大模型的智能视频编辑接口

• 服务层（service/*）

  • 将路由层的请求参数转化为具体业务动作，如创建草稿、下载草稿、生成素材信息、提交渲染任务等
  • 与工具层、自动化层协作，完成跨模块的编排
  • ：智能视频编辑服务，支持大模型驱动的内容生成

• 工具层（utils/*）

  • 草稿下载器负责从 API 获取草稿文件清单并下载至本地；提供安全写入、目录扫描触发等能力
  • 日志、媒体处理、草稿缓存等工具支撑业务稳定运行
  • ：工具函数模块，提供数据格式转换、URL 处理、贴纸搜索等实用工具

• 自动化层（pyJianYingDraft）

  • 剪映控制器通过 UI 自动化定位窗口、切换状态、设置导出分辨率/帧率、点击导出按钮、等待导出完成并移动文件
  • 适用于本地 Windows 环境下的剪映自动化导出
  • ：智能视频编辑自动化，支持大模型生成内容的自动渲染

• 配置中心（config.py）

  • 定义草稿目录、临时目录、下载/提示/草稿 URL、模板目录、草稿保存路径、云存储配置、API Key 开关等
  • 云渲染相关配置（COS、API Key）为云端渲染提供基础
  • ：智能视频编辑配置选项

• 桌面客户端（Electron + React）

  • Electron 主进程负责窗口创建、权限处理与 IPC 初始化
  • 前端页面提供草稿下载、历史记录、日志查看与基础配置入口
  • ：智能视频编辑界面，支持大模型内容生成和编辑

架构总览

capcut-mate 的整体架构分为三层：API 层、服务层与自动化/工具层。API 层接收外部请求，服务层组织业务逻辑，工具层与自动化层负责文件下载、草稿缓存与剪映自动化导出。架构设计体现了开源免费、独立部署和智能视频编辑的理念。
#mermaid-svg-bti7vte7yiihlpsi{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bti7vte7yiihlpsi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bti7vte7yiihlpsi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bti7vte7yiihlpsi .error-icon{fill:#552222;}#mermaid-svg-bti7vte7yiihlpsi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bti7vte7yiihlpsi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bti7vte7yiihlpsi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bti7vte7yiihlpsi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bti7vte7yiihlpsi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bti7vte7yiihlpsi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bti7vte7yiihlpsi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bti7vte7yiihlpsi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bti7vte7yiihlpsi .marker.cross{stroke:#333333;}#mermaid-svg-bti7vte7yiihlpsi svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bti7vte7yiihlpsi p{margin:0;}#mermaid-svg-bti7vte7yiihlpsi .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bti7vte7yiihlpsi .cluster-label text{fill:#333;}#mermaid-svg-bti7vte7yiihlpsi .cluster-label span{color:#333;}#mermaid-svg-bti7vte7yiihlpsi .cluster-label span p{background-color:transparent;}#mermaid-svg-bti7vte7yiihlpsi .label text,#mermaid-svg-bti7vte7yiihlpsi span{fill:#333;color:#333;}#mermaid-svg-bti7vte7yiihlpsi .node rect,#mermaid-svg-bti7vte7yiihlpsi .node circle,#mermaid-svg-bti7vte7yiihlpsi .node ellipse,#mermaid-svg-bti7vte7yiihlpsi .node polygon,#mermaid-svg-bti7vte7yiihlpsi .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bti7vte7yiihlpsi .rough-node .label text,#mermaid-svg-bti7vte7yiihlpsi .node .label text,#mermaid-svg-bti7vte7yiihlpsi .image-shape .label,#mermaid-svg-bti7vte7yiihlpsi .icon-shape .label{text-anchor:middle;}#mermaid-svg-bti7vte7yiihlpsi .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bti7vte7yiihlpsi .rough-node .label,#mermaid-svg-bti7vte7yiihlpsi .node .label,#mermaid-svg-bti7vte7yiihlpsi .image-shape .label,#mermaid-svg-bti7vte7yiihlpsi .icon-shape .label{text-align:center;}#mermaid-svg-bti7vte7yiihlpsi .node.clickable{cursor:pointer;}#mermaid-svg-bti7vte7yiihlpsi .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bti7vte7yiihlpsi .arrowheadPath{fill:#333333;}#mermaid-svg-bti7vte7yiihlpsi .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bti7vte7yiihlpsi .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bti7vte7yiihlpsi .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bti7vte7yiihlpsi .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bti7vte7yiihlpsi .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bti7vte7yiihlpsi .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bti7vte7yiihlpsi .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bti7vte7yiihlpsi .cluster text{fill:#333;}#mermaid-svg-bti7vte7yiihlpsi .cluster span{color:#333;}#mermaid-svg-bti7vte7yiihlpsi div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-bti7vte7yiihlpsi .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bti7vte7yiihlpsi rect.text{fill:none;stroke-width:0;}#mermaid-svg-bti7vte7yiihlpsi .icon-shape,#mermaid-svg-bti7vte7yiihlpsi .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bti7vte7yiihlpsi .icon-shape p,#mermaid-svg-bti7vte7yiihlpsi .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bti7vte7yiihlpsi .icon-shape .label rect,#mermaid-svg-bti7vte7yiihlpsi .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bti7vte7yiihlpsi .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bti7vte7yiihlpsi .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bti7vte7yiihlpsi :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 客户端/调用方
FastAPI 应用

main.py
路由 v1

src/router/v1.py
服务层

src/service/*
草稿下载器

src/utils/draft_downloader.py
配置中心

config.py
模板目录

template/*
剪映控制器

src/pyJianYingDraft/jianying_controller.py
工具函数

src/utils/*
智能视频编辑

AI Integration
桌面客户端

desktop-client/main.js
开源免费
独立部署

详细组件分析

组件 A：草稿创建与保存（create_draft）

• 功能要点

  • 基于模板目录复制并修改画布尺寸，生成唯一草稿 ID，并启用双文件兼容模式以确保草稿内容一致性
  • 自动添加空主轨道，便于后续素材落位
  • 更新草稿缓存并返回草稿 URL，供后续编辑与渲染使用
  • ：支持智能视频编辑的草稿创建，为大模型生成内容提供基础

• 关键流程

  • 生成草稿 ID → 复制模板 → 修改画布尺寸 → 保存草稿 → 添加主轨道 → 更新缓存 → 返回草稿 URL

#mermaid-svg-m9GBUg925iOKTxlF{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-m9GBUg925iOKTxlF .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-m9GBUg925iOKTxlF .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-m9GBUg925iOKTxlF .error-icon{fill:#552222;}#mermaid-svg-m9GBUg925iOKTxlF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-m9GBUg925iOKTxlF .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-m9GBUg925iOKTxlF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-m9GBUg925iOKTxlF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-m9GBUg925iOKTxlF .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-m9GBUg925iOKTxlF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-m9GBUg925iOKTxlF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-m9GBUg925iOKTxlF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-m9GBUg925iOKTxlF .marker.cross{stroke:#333333;}#mermaid-svg-m9GBUg925iOKTxlF svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-m9GBUg925iOKTxlF p{margin:0;}#mermaid-svg-m9GBUg925iOKTxlF .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-m9GBUg925iOKTxlF .cluster-label text{fill:#333;}#mermaid-svg-m9GBUg925iOKTxlF .cluster-label span{color:#333;}#mermaid-svg-m9GBUg925iOKTxlF .cluster-label span p{background-color:transparent;}#mermaid-svg-m9GBUg925iOKTxlF .label text,#mermaid-svg-m9GBUg925iOKTxlF span{fill:#333;color:#333;}#mermaid-svg-m9GBUg925iOKTxlF .node rect,#mermaid-svg-m9GBUg925iOKTxlF .node circle,#mermaid-svg-m9GBUg925iOKTxlF .node ellipse,#mermaid-svg-m9GBUg925iOKTxlF .node polygon,#mermaid-svg-m9GBUg925iOKTxlF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-m9GBUg925iOKTxlF .rough-node .label text,#mermaid-svg-m9GBUg925iOKTxlF .node .label text,#mermaid-svg-m9GBUg925iOKTxlF .image-shape .label,#mermaid-svg-m9GBUg925iOKTxlF .icon-shape .label{text-anchor:middle;}#mermaid-svg-m9GBUg925iOKTxlF .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-m9GBUg925iOKTxlF .rough-node .label,#mermaid-svg-m9GBUg925iOKTxlF .node .label,#mermaid-svg-m9GBUg925iOKTxlF .image-shape .label,#mermaid-svg-m9GBUg925iOKTxlF .icon-shape .label{text-align:center;}#mermaid-svg-m9GBUg925iOKTxlF .node.clickable{cursor:pointer;}#mermaid-svg-m9GBUg925iOKTxlF .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-m9GBUg925iOKTxlF .arrowheadPath{fill:#333333;}#mermaid-svg-m9GBUg925iOKTxlF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-m9GBUg925iOKTxlF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-m9GBUg925iOKTxlF .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-m9GBUg925iOKTxlF .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-m9GBUg925iOKTxlF .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-m9GBUg925iOKTxlF .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-m9GBUg925iOKTxlF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-m9GBUg925iOKTxlF .cluster text{fill:#333;}#mermaid-svg-m9GBUg925iOKTxlF .cluster span{color:#333;}#mermaid-svg-m9GBUg925iOKTxlF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-m9GBUg925iOKTxlF .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-m9GBUg925iOKTxlF rect.text{fill:none;stroke-width:0;}#mermaid-svg-m9GBUg925iOKTxlF .icon-shape,#mermaid-svg-m9GBUg925iOKTxlF .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-m9GBUg925iOKTxlF .icon-shape p,#mermaid-svg-m9GBUg925iOKTxlF .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-m9GBUg925iOKTxlF .icon-shape .label rect,#mermaid-svg-m9GBUg925iOKTxlF .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-m9GBUg925iOKTxlF .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-m9GBUg925iOKTxlF .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-m9GBUg925iOKTxlF :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 入口：create_draft
生成草稿ID
复制模板到草稿目录
加载草稿脚本并启用双文件兼容
设置画布宽高
保存草稿内容
添加空主轨道
更新草稿缓存
返回草稿URL
智能视频编辑增强
结束

组件 B：草稿下载与本地渲染（draft_downloader）

• 功能要点

  • 从草稿 URL 提取草稿 ID，获取文件清单并逐个下载，确保原子写入与磁盘同步
  • 下载完成后触发目录扫描，保证剪映能识别新增文件
  • 支持自定义保存路径（默认使用配置中的草稿保存路径）
  • ：支持智能视频编辑内容的下载和渲染

• 关键流程

  • 解析 URL → 提取 draft_id → 获取文件列表 → 逐个下载并写入 → 触发扫描 → 返回结果

#mermaid-svg-xI4FL216tO2bCpjg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-xI4FL216tO2bCpjg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-xI4FL216tO2bCpjg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-xI4FL216tO2bCpjg .error-icon{fill:#552222;}#mermaid-svg-xI4FL216tO2bCpjg .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-xI4FL216tO2bCpjg .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-xI4FL216tO2bCpjg .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-xI4FL216tO2bCpjg .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-xI4FL216tO2bCpjg .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-xI4FL216tO2bCpjg .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-xI4FL216tO2bCpjg .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-xI4FL216tO2bCpjg .marker{fill:#333333;stroke:#333333;}#mermaid-svg-xI4FL216tO2bCpjg .marker.cross{stroke:#333333;}#mermaid-svg-xI4FL216tO2bCpjg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-xI4FL216tO2bCpjg p{margin:0;}#mermaid-svg-xI4FL216tO2bCpjg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-xI4FL216tO2bCpjg .cluster-label text{fill:#333;}#mermaid-svg-xI4FL216tO2bCpjg .cluster-label span{color:#333;}#mermaid-svg-xI4FL216tO2bCpjg .cluster-label span p{background-color:transparent;}#mermaid-svg-xI4FL216tO2bCpjg .label text,#mermaid-svg-xI4FL216tO2bCpjg span{fill:#333;color:#333;}#mermaid-svg-xI4FL216tO2bCpjg .node rect,#mermaid-svg-xI4FL216tO2bCpjg .node circle,#mermaid-svg-xI4FL216tO2bCpjg .node ellipse,#mermaid-svg-xI4FL216tO2bCpjg .node polygon,#mermaid-svg-xI4FL216tO2bCpjg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-xI4FL216tO2bCpjg .rough-node .label text,#mermaid-svg-xI4FL216tO2bCpjg .node .label text,#mermaid-svg-xI4FL216tO2bCpjg .image-shape .label,#mermaid-svg-xI4FL216tO2bCpjg .icon-shape .label{text-anchor:middle;}#mermaid-svg-xI4FL216tO2bCpjg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-xI4FL216tO2bCpjg .rough-node .label,#mermaid-svg-xI4FL216tO2bCpjg .node .label,#mermaid-svg-xI4FL216tO2bCpjg .image-shape .label,#mermaid-svg-xI4FL216tO2bCpjg .icon-shape .label{text-align:center;}#mermaid-svg-xI4FL216tO2bCpjg .node.clickable{cursor:pointer;}#mermaid-svg-xI4FL216tO2bCpjg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-xI4FL216tO2bCpjg .arrowheadPath{fill:#333333;}#mermaid-svg-xI4FL216tO2bCpjg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-xI4FL216tO2bCpjg .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-xI4FL216tO2bCpjg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xI4FL216tO2bCpjg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-xI4FL216tO2bCpjg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xI4FL216tO2bCpjg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-xI4FL216tO2bCpjg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-xI4FL216tO2bCpjg .cluster text{fill:#333;}#mermaid-svg-xI4FL216tO2bCpjg .cluster span{color:#333;}#mermaid-svg-xI4FL216tO2bCpjg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-xI4FL216tO2bCpjg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-xI4FL216tO2bCpjg rect.text{fill:none;stroke-width:0;}#mermaid-svg-xI4FL216tO2bCpjg .icon-shape,#mermaid-svg-xI4FL216tO2bCpjg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xI4FL216tO2bCpjg .icon-shape p,#mermaid-svg-xI4FL216tO2bCpjg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-xI4FL216tO2bCpjg .icon-shape .label rect,#mermaid-svg-xI4FL216tO2bCpjg .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xI4FL216tO2bCpjg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-xI4FL216tO2bCpjg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-xI4FL216tO2bCpjg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 入口：download_draft
解析草稿URL并提取draft_id
准备目标目录
获取草稿文件清单
遍历文件并下载
触发目录扫描
智能视频编辑处理
返回下载结果

组件 C：剪映自动化导出（JianyingController）

• 功能要点

  • 通过 UI 自动化定位剪映窗口，支持首页、编辑页、导出前置页的状态切换
  • 设置导出分辨率与帧率，点击最终导出按钮，并等待导出完成或成功提示
  • 导出完成后可将文件移动到指定位置，便于后续上传或归档
  • ：支持智能视频编辑内容的自动化导出

• 关键流程

  • 初始化窗口 → 切换到首页 → 定位草稿 → 进入编辑页 → 点击导出 → 设置分辨率/帧率 → 点击最终导出 → 等待完成 → 返回首页

"剪映窗口" "智能视频编辑" "JianyingController" "调用方" "剪映窗口" "智能视频编辑" "JianyingController" "调用方" #mermaid-svg-4PliQEBrIUdnxoE0{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-4PliQEBrIUdnxoE0 .error-icon{fill:#552222;}#mermaid-svg-4PliQEBrIUdnxoE0 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-4PliQEBrIUdnxoE0 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-4PliQEBrIUdnxoE0 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-4PliQEBrIUdnxoE0 .marker.cross{stroke:#333333;}#mermaid-svg-4PliQEBrIUdnxoE0 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-4PliQEBrIUdnxoE0 p{margin:0;}#mermaid-svg-4PliQEBrIUdnxoE0 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-4PliQEBrIUdnxoE0 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-4PliQEBrIUdnxoE0 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-4PliQEBrIUdnxoE0 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-4PliQEBrIUdnxoE0 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-4PliQEBrIUdnxoE0 .sequenceNumber{fill:white;}#mermaid-svg-4PliQEBrIUdnxoE0 #sequencenumber{fill:#333;}#mermaid-svg-4PliQEBrIUdnxoE0 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-4PliQEBrIUdnxoE0 .messageText{fill:#333;stroke:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-4PliQEBrIUdnxoE0 .labelText,#mermaid-svg-4PliQEBrIUdnxoE0 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .loopText,#mermaid-svg-4PliQEBrIUdnxoE0 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-4PliQEBrIUdnxoE0 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-4PliQEBrIUdnxoE0 .noteText,#mermaid-svg-4PliQEBrIUdnxoE0 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-4PliQEBrIUdnxoE0 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-4PliQEBrIUdnxoE0 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-4PliQEBrIUdnxoE0 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-4PliQEBrIUdnxoE0 .actorPopupMenu{position:absolute;}#mermaid-svg-4PliQEBrIUdnxoE0 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-4PliQEBrIUdnxoE0 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-4PliQEBrIUdnxoE0 .actor-man circle,#mermaid-svg-4PliQEBrIUdnxoE0 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-4PliQEBrIUdnxoE0 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} export_draft(draft_name, output_path, ...) 获取智能编辑内容 返回编辑后的内容 定位窗口并置顶 切换到首页 查找并点击草稿 点击导出按钮 设置分辨率/帧率 点击最终导出 等待导出完成/成功 移动导出文件 返回完成状态

组件 D：桌面客户端（Electron）

• 功能要点

  • Electron 主进程负责窗口创建、图标适配、开发/生产模式加载、IPC 初始化与异常处理
  • 前端页面提供下载、历史记录、日志模块与基础配置入口，便于本地用户操作与调试
  • ：智能视频编辑界面，支持大模型内容生成和编辑

• 关键流程

  • 应用启动 → 创建窗口 → 加载页面（开发/生产）→ 初始化 IPC → 监听事件 → 异常捕获与提示

"React 页面" "IPC处理器" "BrowserWindow" "智能视频编辑" "Electron 应用" "React 页面" "IPC处理器" "BrowserWindow" "智能视频编辑" "Electron 应用" #mermaid-svg-0MMH4frqrJgJEZDw{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-0MMH4frqrJgJEZDw .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-0MMH4frqrJgJEZDw .error-icon{fill:#552222;}#mermaid-svg-0MMH4frqrJgJEZDw .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-0MMH4frqrJgJEZDw .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-0MMH4frqrJgJEZDw .marker{fill:#333333;stroke:#333333;}#mermaid-svg-0MMH4frqrJgJEZDw .marker.cross{stroke:#333333;}#mermaid-svg-0MMH4frqrJgJEZDw svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-0MMH4frqrJgJEZDw p{margin:0;}#mermaid-svg-0MMH4frqrJgJEZDw .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-0MMH4frqrJgJEZDw text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-0MMH4frqrJgJEZDw .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-0MMH4frqrJgJEZDw .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-0MMH4frqrJgJEZDw .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-0MMH4frqrJgJEZDw .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-0MMH4frqrJgJEZDw #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-0MMH4frqrJgJEZDw .sequenceNumber{fill:white;}#mermaid-svg-0MMH4frqrJgJEZDw #sequencenumber{fill:#333;}#mermaid-svg-0MMH4frqrJgJEZDw #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-0MMH4frqrJgJEZDw .messageText{fill:#333;stroke:none;}#mermaid-svg-0MMH4frqrJgJEZDw .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-0MMH4frqrJgJEZDw .labelText,#mermaid-svg-0MMH4frqrJgJEZDw .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-0MMH4frqrJgJEZDw .loopText,#mermaid-svg-0MMH4frqrJgJEZDw .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-0MMH4frqrJgJEZDw .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-0MMH4frqrJgJEZDw .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-0MMH4frqrJgJEZDw .noteText,#mermaid-svg-0MMH4frqrJgJEZDw .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-0MMH4frqrJgJEZDw .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-0MMH4frqrJgJEZDw .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-0MMH4frqrJgJEZDw .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-0MMH4frqrJgJEZDw .actorPopupMenu{position:absolute;}#mermaid-svg-0MMH4frqrJgJEZDw .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-0MMH4frqrJgJEZDw .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-0MMH4frqrJgJEZDw .actor-man circle,#mermaid-svg-0MMH4frqrJgJEZDw line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-0MMH4frqrJgJEZDw :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} createWindow() 加载页面(开发/生产) setupIpcHandlers() 用户操作(下载/历史/日志/智能编辑) 返回结果/状态 提供智能视频编辑功能

组件 E：API 与 OpenAPI 描述

• 功能要点

  • API 路由集中在 v1，覆盖草稿、素材、特效、字幕、渲染、时间线与工具类接口
  • OpenAPI 描述文件提供接口规范、请求/响应示例与错误码说明，便于联调与自动化测试
  • ：支持智能视频编辑的 API 接口

• 关键流程

  • 客户端发起请求 → FastAPI 路由解析 → 服务层处理 → 工具/自动化层执行 → 返回统一响应

"智能视频编辑" "工具/自动化" "服务层" "路由 v1" "FastAPI" "客户端" "智能视频编辑" "工具/自动化" "服务层" "路由 v1" "FastAPI" "客户端" #mermaid-svg-vkBcqV809Zafr6f1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-vkBcqV809Zafr6f1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-vkBcqV809Zafr6f1 .error-icon{fill:#552222;}#mermaid-svg-vkBcqV809Zafr6f1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-vkBcqV809Zafr6f1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-vkBcqV809Zafr6f1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-vkBcqV809Zafr6f1 .marker.cross{stroke:#333333;}#mermaid-svg-vkBcqV809Zafr6f1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-vkBcqV809Zafr6f1 p{margin:0;}#mermaid-svg-vkBcqV809Zafr6f1 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vkBcqV809Zafr6f1 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-vkBcqV809Zafr6f1 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-vkBcqV809Zafr6f1 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-vkBcqV809Zafr6f1 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-vkBcqV809Zafr6f1 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-vkBcqV809Zafr6f1 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-vkBcqV809Zafr6f1 .sequenceNumber{fill:white;}#mermaid-svg-vkBcqV809Zafr6f1 #sequencenumber{fill:#333;}#mermaid-svg-vkBcqV809Zafr6f1 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-vkBcqV809Zafr6f1 .messageText{fill:#333;stroke:none;}#mermaid-svg-vkBcqV809Zafr6f1 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vkBcqV809Zafr6f1 .labelText,#mermaid-svg-vkBcqV809Zafr6f1 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-vkBcqV809Zafr6f1 .loopText,#mermaid-svg-vkBcqV809Zafr6f1 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-vkBcqV809Zafr6f1 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-vkBcqV809Zafr6f1 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-vkBcqV809Zafr6f1 .noteText,#mermaid-svg-vkBcqV809Zafr6f1 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-vkBcqV809Zafr6f1 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vkBcqV809Zafr6f1 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vkBcqV809Zafr6f1 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vkBcqV809Zafr6f1 .actorPopupMenu{position:absolute;}#mermaid-svg-vkBcqV809Zafr6f1 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-vkBcqV809Zafr6f1 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vkBcqV809Zafr6f1 .actor-man circle,#mermaid-svg-vkBcqV809Zafr6f1 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-vkBcqV809Zafr6f1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} HTTP 请求 路由分发 参数校验与业务处理 智能视频编辑处理 返回编辑结果 下载/渲染/导出等 执行结果 统一响应模型 JSON 响应

工具函数详解

工具函数概览

capcut-mate 提供了一套完整的工具函数集合，专门用于处理常见的数据格式转换和内容提取需求。这些工具函数通过统一的 API 接口暴露，方便开发者在视频制作流程中进行数据处理和格式转换。新增：支持智能视频编辑的工具函数。

get_url 工具函数

用于从输入内容中提取 URL 信息，支持从复杂的字符串格式中解析出有效的链接地址。

• 接口信息

  • 请求方法：POST
  • 请求路径：/openapi/capcut-mate/v1/get_url
  • 功能描述：提取链接，用于多值返回变成单值返回

• 请求参数

  • output (string, 必填)：需要提取链接的内容
  • 示例："[魂牵梦萦https://sf.com；中国人https://jcaigc.cn],\"[]\""

• 响应格式

  • 成功响应：返回包含提取结果的 JSON 对象
  • 错误响应：返回标准错误信息

search_sticker 工具函数

根据关键词搜索贴纸素材，返回匹配的贴纸列表，包括贴纸的详细信息如图片 URL、尺寸、类型等。

• 接口信息

  • 请求方法：POST
  • 请求路径：/openapi/capcut-mate/v1/search_sticker
  • 功能描述：根据关键词搜索贴纸

• 请求参数

  • keyword (string, 必填)：搜索贴纸的关键词
  • 示例："人"、"花"、"动物"

• 响应格式

  • 成功响应：返回包含贴纸数据列表的 JSON 对象
  • 响应字段：包含贴纸详细信息、贴纸 ID、标题等

objs_to_str_list 工具函数

将对象列表转换为字符串列表格式，主要用于处理包含 URL 地址的数据结构。

• 接口信息

  • 请求方法：POST
  • 请求路径：/openapi/capcut-mate/v1/objs_to_str_list
  • 功能描述：对象列表转化成字符串列表

• 请求参数

  • outputs (arrayobject, 必填)：数据对象列表
  • 示例：[{"output": "https://assets.jcaigc.cn/min.mp4"}, {"output": "https://assets.jcaigc.cn/max.mp4"}]

• 响应格式

  • 成功响应：返回包含字符串列表的 JSON 对象
  • 返回值：将输入的对象列表中的 output 字段提取出来组成字符串列表

str_list_to_objs 工具函数

将字符串列表转换为对象列表格式，与 objs_to_str_list 功能相反，用于数据格式的逆向转换。

• 接口信息

  • 请求方法：POST
  • 请求路径：/openapi/capcut-mate/v1/str_list_to_objs
  • 功能描述：字符串列表转化成对象列表

• 请求参数

  • infos (arraystring, 必填)：字符串列表
  • 示例：["https://assets.jcaigc.cn/min.mp4", "https://assets.jcaigc.cn/max.mp4"]

• 响应格式

  • 成功响应：返回包含对象列表的 JSON 对象
  • 返回值：将输入的字符串列表转换为包含 output 字段的对象列表

str_to_list 工具函数

将输入的字符串转换为列表格式，主要用于处理单个字符串内容的包装。

• 接口信息

  • 请求方法：POST
  • 请求路径：/openapi/capcut-mate/v1/str_to_list
  • 功能描述：字符转列表

• 请求参数

  • obj (string, 必填)：对象内容
  • 示例："{ \"infos\": [ \"https://assets.jcaigc.cn/min.mp4\", \"https://assets.jcaigc.cn/max.mp4\" ] }"

• 响应格式

  • 成功响应：返回包含字符串列表的 JSON 对象
  • 返回值：将输入的字符串作为单个元素放入列表中返回

依赖关系分析

• 组件耦合与内聚

  • API 层与服务层通过统一的 Pydantic 模型解耦，便于扩展与测试
  • 服务层与工具层/自动化层通过函数调用解耦，职责清晰
  • 配置中心集中管理路径与云存储参数，避免散落的硬编码
  • ：工具函数模块独立于核心业务逻辑，提供可重用的数据处理能力
  • ：智能视频编辑模块与核心业务逻辑松耦合，支持插件式集成

• 外部依赖

  • Python 生态：FastAPI、uiautomation（剪映自动化）、requests（HTTP）、腾讯云 COS SDK（云渲染）
  • 前端生态：Electron、React、Vite（开发/打包）
  • ：大模型集成依赖，支持与各种 AI 平台的对接
  • ：智能视频编辑框架，支持多种视频生成和编辑算法

#mermaid-svg-pTPvKVL43QW3nxcA{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-pTPvKVL43QW3nxcA .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-pTPvKVL43QW3nxcA .error-icon{fill:#552222;}#mermaid-svg-pTPvKVL43QW3nxcA .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-pTPvKVL43QW3nxcA .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-pTPvKVL43QW3nxcA .marker{fill:#333333;stroke:#333333;}#mermaid-svg-pTPvKVL43QW3nxcA .marker.cross{stroke:#333333;}#mermaid-svg-pTPvKVL43QW3nxcA svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-pTPvKVL43QW3nxcA p{margin:0;}#mermaid-svg-pTPvKVL43QW3nxcA .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-pTPvKVL43QW3nxcA .cluster-label text{fill:#333;}#mermaid-svg-pTPvKVL43QW3nxcA .cluster-label span{color:#333;}#mermaid-svg-pTPvKVL43QW3nxcA .cluster-label span p{background-color:transparent;}#mermaid-svg-pTPvKVL43QW3nxcA .label text,#mermaid-svg-pTPvKVL43QW3nxcA span{fill:#333;color:#333;}#mermaid-svg-pTPvKVL43QW3nxcA .node rect,#mermaid-svg-pTPvKVL43QW3nxcA .node circle,#mermaid-svg-pTPvKVL43QW3nxcA .node ellipse,#mermaid-svg-pTPvKVL43QW3nxcA .node polygon,#mermaid-svg-pTPvKVL43QW3nxcA .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-pTPvKVL43QW3nxcA .rough-node .label text,#mermaid-svg-pTPvKVL43QW3nxcA .node .label text,#mermaid-svg-pTPvKVL43QW3nxcA .image-shape .label,#mermaid-svg-pTPvKVL43QW3nxcA .icon-shape .label{text-anchor:middle;}#mermaid-svg-pTPvKVL43QW3nxcA .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-pTPvKVL43QW3nxcA .rough-node .label,#mermaid-svg-pTPvKVL43QW3nxcA .node .label,#mermaid-svg-pTPvKVL43QW3nxcA .image-shape .label,#mermaid-svg-pTPvKVL43QW3nxcA .icon-shape .label{text-align:center;}#mermaid-svg-pTPvKVL43QW3nxcA .node.clickable{cursor:pointer;}#mermaid-svg-pTPvKVL43QW3nxcA .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-pTPvKVL43QW3nxcA .arrowheadPath{fill:#333333;}#mermaid-svg-pTPvKVL43QW3nxcA .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-pTPvKVL43QW3nxcA .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-pTPvKVL43QW3nxcA .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pTPvKVL43QW3nxcA .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-pTPvKVL43QW3nxcA .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pTPvKVL43QW3nxcA .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-pTPvKVL43QW3nxcA .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-pTPvKVL43QW3nxcA .cluster text{fill:#333;}#mermaid-svg-pTPvKVL43QW3nxcA .cluster span{color:#333;}#mermaid-svg-pTPvKVL43QW3nxcA div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-pTPvKVL43QW3nxcA .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-pTPvKVL43QW3nxcA rect.text{fill:none;stroke-width:0;}#mermaid-svg-pTPvKVL43QW3nxcA .icon-shape,#mermaid-svg-pTPvKVL43QW3nxcA .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pTPvKVL43QW3nxcA .icon-shape p,#mermaid-svg-pTPvKVL43QW3nxcA .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-pTPvKVL43QW3nxcA .icon-shape .label rect,#mermaid-svg-pTPvKVL43QW3nxcA .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pTPvKVL43QW3nxcA .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-pTPvKVL43QW3nxcA .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-pTPvKVL43QW3nxcA :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} API 层

main.py + v1.py
服务层

service/*
工具层

utils/*
自动化层

pyJianYingDraft
配置中心

config.py
工具函数

get_url/search_sticker/*
智能视频编辑

AI Integration
桌面客户端

desktop-client
开源免费
独立部署

性能考量

• 草稿创建

  • 模板复制与双文件保存需注意 I/O 性能，建议在 SSD 上运行并合理设置草稿目录
  • ：智能视频编辑内容的创建需要额外的计算资源，建议预留充足的 CPU 和内存

• 草稿下载

  • 并行下载与断点续传可进一步优化，当前实现采用逐个下载与原子写入，保证可靠性
  • ：大模型生成内容的下载需要考虑网络带宽和存储空间

• 云端渲染

  • 素材 URL 稳定性与带宽直接影响渲染时长；建议使用 CDN 与高质量素材
  • ：智能视频编辑内容的渲染需要更强的 GPU 性能支持

• 剪映自动化导出

  • 导出超时与分辨率/帧率设置需结合硬件性能与素材复杂度进行权衡
  • ：大模型生成内容的导出需要考虑文件大小和导出质量

• 桌面客户端

  • 开发模式下启用调试工具会增加内存占用，生产打包后性能更佳
  • ：智能视频编辑界面需要更多的内存和 CPU 资源

• 工具函数性能

  • 数据格式转换操作通常为 O(n) 复杂度，其中 n 为数据项数量
  • URL 提取和贴纸搜索操作受数据规模影响，建议对大量数据进行分批处理
  • ：智能视频编辑工具函数的性能取决于具体的算法复杂度

故障排查指南

• 常见问题与定位

  • 草稿创建失败：检查模板目录是否存在、权限是否足够、画布尺寸是否合法
  • 草稿下载失败：确认草稿 URL 有效、网络可达、目标目录可写
  • 剪映自动化导出失败：确认剪映窗口可见、分辨率/帧率设置正确、导出超时阈值合理
  • 云端渲染失败：检查 API Key 与 COS 配置、素材 URL 可达性、渲染服务器负载
  • 桌面客户端权限错误：在系统偏好设置中授予应用所需文件夹访问权限
  • ：智能视频编辑失败：检查大模型连接、模型可用性和计算资源
  • ：工具函数调用失败：检查参数验证、数据格式和编码问题

• 日志与监控

  • API 层与服务层均使用统一日志模块，便于追踪请求与异常
  • 剪映控制器与下载器提供详细的步骤日志，有助于定位自动化环节的问题
  • ：智能视频编辑模块的日志，记录 AI 处理过程和异常情况
  • ：工具函数调用日志，记录数据转换过程和异常情况

结论

capcut-mate 通过清晰的分层架构与完善的 API 描述，实现了从草稿创建、素材编排到云端渲染与本地导出的全链路自动化。其设计理念强调"可扩展、可运维、易接入"，既满足初学者快速上手，也具备足够的灵活性供高级用户定制。新增：完善的开源免费、独立部署和智能视频编辑支持进一步提升了项目的实用性，结合桌面客户端与容器化部署，项目可在多种场景下高效落地，支持多语言环境下的视频制作工作流，特别适合大模型驱动的智能视频创作应用。

附录

• 实际使用案例（概念性演示）

  • 批量短视频生成：先调用创建草稿接口生成草稿，再批量添加视频/音频/图片与字幕，最后提交云端渲染并轮询状态，完成后下载成品
  • 本地自动化导出：在本地通过桌面客户端下载草稿，使用剪映控制器一键导出到指定目录，便于离线处理与归档
  • 模板化生产：基于模板目录快速生成标准规格的草稿，统一画布尺寸与轨道结构，减少重复配置成本
  • ：智能视频编辑工作流：通过大模型生成创意内容，自动创建草稿并进行智能编辑，最后导出成品
  • ：国际化协作：多语言团队可以通过统一的 API 接口和工具函数进行视频内容的创建和处理，支持不同语言环境下的协作

• 参考文档

  • 草稿创建接口文档：docs/create_draft.md(file://docs/create_draft.md#L1-L165)
  • 云端渲染接口文档：docs/gen_video.md(file://docs/gen_video.md#L1-L141)
  • ：智能视频编辑文档
  • ：大模型集成指南
  • ：工具函数文档
    • URL 提取工具：docs/get_url.md(file://docs/get_url.md#L1-L107)
    • 贴纸搜索工具：docs/search_sticker.md(file://docs/search_sticker.md#L1-L148)
    • 数据格式转换工具：docs/objs_to_str_list.md(file://docs/objs_to_str_list.md#L1-L124)、docs/str_list_to_objs.md(file://docs/str_list_to_objs.md#L1-L121)、docs/str_to_list.md(file://docs/str_to_list.md#L1-L109)

文档信息

• 接口文档： docs.jcaigc.cn
• 效果案例： www.jcaigc.cn/workflow
• 开源仓库： capcut-mate