开源剪映小助手技术栈概览

技术栈概览

在深入细节之前，先明确一下这个项目的定位。CapCut Mate（即剪映小助手）要解决的核心问题非常务实：它通过代码自动化实现视频草稿的下载、素材管理、自动生成以及导出整个流程。技术选型方面，后端采用 Python 的 FastAPI 搭配 Uvicorn，前端使用 React 配合 Vite 和 Electron，自动化控制依赖 uiautomation。整套方案还支持容器化部署，便于运维。

项目结构

项目的组织方式非常清晰，采用分层设计，一目了然：

• 后端服务：Python 与 FastAPI 的经典组合，提供 REST API，路由集中在 v1 版本，业务逻辑放在 service 层，工具类归入 utils。
• 自动化控制：基于 uiautomation 操控剪映窗口，专门负责草稿导出的流程。
• 桌面客户端：Electron 加上 React，提供用户界面以及与系统的集成能力，通过 IPC 与主进程通信。
• 配置与环境：配置集中在 config.py 文件中，Dockerfile 和 docker-compose.yaml 负责容器化部署。

graph TB
subgraph "桌面客户端(Electron)"
UI["React 前端
Vite 构建"]
Main["Electron 主进程
main.js"]
Preload["预加载脚本
preload.js"]
IPC["IPC 处理器
ipcHandlers.js"]
end

subgraph "后端服务(Python)"
FastAPI["FastAPI 应用
main.py"]
Router["路由(v1)
src/router/v1.py"]
Middleware["中间件
src/middlewares/prepare.py"]
Utils["工具类
src/utils/draft_downloader.py"]
Auto["自动化控制
src/pyJianYingDraft/jianying_controller.py"]
Cfg["配置
config.py"]
end

subgraph "运行时"
Docker["Docker 容器"]
Compose["Docker Compose"]
end

UI --> Main
Main --> Preload
Preload --> IPC
Main --> FastAPI
FastAPI --> Router
FastAPI --> Middleware
Router --> Utils
Router --> Auto
FastAPI --> Cfg
Docker --> FastAPI
Compose --> Docker

核心组件

Python 后端（FastAPI + Uvicorn）

应用入口位于 main.py 中，路由注册、中间件配置、日志记录以及启动参数都在此处完成。v1 路由集中定义了草稿的创建、保存、素材添加、导出、查询等一整套接口。中间件负责在请求到达前创建必要的目录，避免后续操作因路径问题失败。

自动化控制（uiautomation）

JianyingController 封装了剪映窗口的查找、草稿选择、导出流程控制、分辨率与帧率设置、导出完成检测等一系列操作。本质上就是模拟人工手动操作剪映的过程，实现自动化导出。

工具类（下载与路径处理）

draft_downloader 提供草稿下载、文件写入、路径修复以及 robocopy 触发等功能。这些看似琐碎的工作，实际上是保证整个自动化流程数据一致性的关键环节。

桌面客户端（Electron + React）

主进程负责窗口创建、开发/生产模式加载、安全策略设置以及权限错误处理。预加载脚本通过 contextBridge 向渲染进程暴露受控 API。IPC 处理器则集中管理文件保存、日志读取、URL 访问检测、历史记录等任务。

架构总览

整体架构可分为三层：

• 表现层：桌面客户端（Electron + React），负责用户交互和系统集成。
• 服务层：Python 后端（FastAPI），提供 REST API 以及核心业务逻辑。
• 自动化层：uiautomation 控制剪映窗口，实现草稿导出的自动化。

graph TB
Client["桌面客户端
Electron + React"] --> API["后端 API
FastAPI"]
API --> Service["业务服务
service 层"]
API --> Utils["工具类
draft_downloader"]
API --> Auto["自动化控制
JianyingController"]
Auto --> CapCut["剪映应用
Windows UIAutomation"]
API --> Config["配置中心
config.py"]
Docker["容器化运行
Dockerfile"] --> API
Compose["编排
docker-compose.yaml"] --> Docker

详细组件分析

Python 后端组件分析

应用入口与生命周期

创建 FastAPI 应用、注册路由和中间件、打印路由表、启动 Uvicorn 服务器，这几个步骤串联起整个后端的生命周期。

路由与服务层

v1 路由覆盖了草稿管理、素材添加、导出与状态查询、时间线计算、URL 提取、序列化转换等接口。服务层通过依赖注入调用具体业务逻辑，最终返回 Pydantic 模型，保证数据结构的规范性。

中间件

PrepareMiddleware 会在每个请求到达前，确保草稿目录和临时目录已经存在。不要小看这一步——如果目录缺失，后续所有操作都会直接报错。

配置

config.py 提供了项目根目录、草稿保存路径、下载 URL、模板目录、腾讯云 COS 配置、API Key 开关等关键参数。配置集中管理的设计，让后期维护和调试都更加方便。

classDiagram
class FastAPIApp {
    include_router()
    add_middleware()
    run()
}

class V1Router {
    create_draft()
    sa ve_draft()
    add_videos()
    add_audios()
    add_images()
    add_sticker()
    add_keyframes()
    add_captions()
    add_effects()
    add_masks()
    add_text_style()
    easy_create_material()
    get_text_animations()
    get_image_animations()
    get_draft()
    gen_video()
    gen_video_status()
    get_audio_duration()
    timelines()
    audio_timelines()
    audio_infos()
    imgs_infos()
    caption_infos()
    effect_infos()
    keyframes_infos()
    video_infos()
    search_sticker()
    get_url()
    str_list_to_objs()
    str_to_list()
    objs_to_str_list()
}

class PrepareMiddleware {
    dispatch()
}

class Config {
    PROJECT_ROOT
    DRAFT_DIR
    TEMP_DIR
    DRAFT_URL
    DOWNLOAD_URL
    TIP_URL
    STICKER_CONFIG_PATH
    TEMPLATE_DIR
    DRAFT_SA VE_PATH
    COS_SECRET_ID
    COS_SECRET_KEY
    COS_BUCKET_NAME
    COS_REGION
    ENABLE_APIKEY
}

FastAPIApp --> V1Router : "注册路由"
FastAPIApp --> PrepareMiddleware : "注册中间件"
V1Router --> Config : "读取配置"

自动化控制组件分析

控制器职责

JianyingController 的核心职责包括：查找剪映窗口、切换状态（主页/编辑页/导出页）、设置导出分辨率和帧率、点击导出按钮、等待导出完成、最后移动导出文件。

状态机设计

通过 app_status 和 app_sub_status 描述当前窗口状态和导出子状态，确保整个过程可控，不会出现“不知道现在跑到哪一步了”的情况。

错误处理

针对控件缺失、超时等常见问题，抛出自定义异常，方便上层逻辑捕获并给出提示。毕竟自动化最怕的就是“卡死”。

classDiagram
class JianyingController {
    get_window()
    switch_to_home()
    find_and_click_draft()
    click_export_button()
    set_export_resolution()
    set_export_framerate()
    click_final_export_button()
    wait_for_export_completion()
    move_exported_file()
    export_draft()
    -__ensure_window_focus()
    -init_export_sub_status()
    -__jianying_window_cmp()
}

class ControlFinder {
    desc_matcher()
    class_name_matcher()
}

class ExportResolution {
    <>
    RES_8K
    RES_4K
    RES_2K
    RES_1080P
    RES_720P
    RES_480P
}

class ExportFramerate {
    <>
    FR_24
    FR_25
    FR_30
    FR_50
    FR_60
}

JianyingController --> ControlFinder : "使用"
JianyingController --> ExportResolution : "设置"
JianyingController --> ExportFramerate : "设置"

桌面客户端组件分析

主进程

负责创建 BrowserWindow、加载开发/生产资源、设置安全策略、处理未捕获异常，以及管理窗口生命周期。这些都是 Electron 开发中的常规操作，但细节处理得当与否，直接影响用户体验。

预加载脚本

通过 contextBridge 向渲染进程暴露受控 API，比如保存文件、获取 URL JSON 数据、读取/清空下载日志、打开外部 URL、读取配置和历史记录等。这个设计兼顾了安全性和功能性。

IPC 处理器

注册 ipcMain.handle，实现文件保存、日志读取、URL 访问检测、历史记录读取、消息框弹窗等功能。IPC 是 Electron 中前后端通信的桥梁，这里的实现中规中矩，但足够实用。

sequenceDiagram
participant UI as "React 前端"
participant Preload as "预加载脚本"
participant Main as "Electron 主进程"
participant IPC as "IPC 处理器"
participant FS as "文件系统"

UI->>Preload : 调用 window.electronAPI.sa veFile(config)
Preload->>Main : ipcRenderer.invoke('sa ve-file', config)
Main->>IPC : ipcMain.handle('sa ve-file')
IPC->>FS : 写入文件/目录
FS-->>IPC : 返回结果
IPC-->>Main : Promise 结果
Main-->>Preload : Promise 结果
Preload-->>UI : Promise 结果

工具类组件分析

草稿下载流程

先从 URL 中提取 draft_id，然后获取文件列表，逐个下载并保持目录结构，接着更新 JSON 中的路径，最后通过 robocopy 触发剪映目录的扫描。整个流程环环相扣，每一步的失败都有对应的处理逻辑。

文件写入与路径修复

使用 O_EXCL 原子创建文件，写入后调用 fsync 确保数据落盘。对于 draft_info.json 和 draft_content.json 中的路径，会进行替换，适配本地路径。数据一致性在这里被放在了很高的优先级。

批量下载与统计

支持批量处理 URL，最后返回成功和失败的统计结果。这对于需要大量处理草稿的场景来说，是一个很实用的功能。

flowchart TD
Start(["开始"]) --> ParseURL["解析草稿URL
提取draft_id"]
ParseURL --> GetList["获取文件列表"]
GetList --> LoopFiles{"遍历文件"}
LoopFiles --> |下载失败| Retry["重试/记录错误"]
LoopFiles --> |下载成功| WriteFile["写入文件
safe_write_file"]
WriteFile --> UpdateJSON{"是否为草稿JSON?"}
UpdateJSON --> |是| FixPath["修复JSON内路径"]
UpdateJSON --> |否| Next["继续"]
FixPath --> Next
Next --> LoopFiles
Retry --> LoopFiles
LoopFiles --> |结束| TriggerScan["robocopy触发扫描"]
TriggerScan --> End(["结束"])

依赖分析

Python 后端的依赖包括 FastAPI、Uvicorn、Requests、uiautomation、PyMediaInfo、pywin32、email-validator、cos-python-sdk-v5。桌面客户端则依赖 Electron、Vite、React、React Router、Axios、Bootstrap、log4js 和 uuid 等。容器化运行时，使用 uv 安装依赖，设置非 root 用户和缓存目录，暴露 30000 端口，并挂载输出目录和时区配置。

graph TB
P["pyproject.toml 依赖"] --> F["FastAPI"]
P --> U["Uvicorn"]
P --> R["Requests"]
P --> A["uiautomation"]
P --> M["PyMediaInfo"]
P --> W["pywin32"]
P --> E["email-validator"]
P --> C["cos-python-sdk-v5"]

D["desktop-client/package.json 依赖"] --> EL["Electron"]
D --> RE["React"]
D --> AX["Axios"]
D --> BO["Bootstrap"]
D --> LO["log4js"]
D --> UU["uuid"]

DF["Dockerfile"] --> UV["uv 安装依赖"]
DF --> EX["暴露端口 30000"]
DC["docker-compose.yaml"] --> VOL["挂载输出目录"]

性能考虑

并发与工作者

Dockerfile 中通过多工作者启动，提升并发处理能力。在需要批量处理任务时，这一点很关键。

I/O 优化

文件写入采用原子创建和 fsync，保证数据的一致性。批量下载时按需重试，尽量降低失败率。

自动化稳定性

uiautomation 的控件查找采用了深度匹配与匹配器，减少了误触的可能。导出流程设置了超时和状态轮询，避免进入死循环。

容器资源限制

docker-compose 中限制了内存和 CPU，防止资源滥用，同时调整了 OOM 优先级，提升系统稳定性。

故障排除指南

权限与路径问题

桌面客户端在 macOS 沙箱环境下会捕获权限错误，引导用户在系统偏好设置中授权文件夹访问。这种“引导式”的错误处理，比直接抛出一个看不懂的异常要友好得多。

网络与下载失败

草稿下载对网络请求和文件写入都做了异常捕获和重试。robocopy 的返回码也会被处理，用来定位失败原因。

自动化控件缺失

uiautomation 在找不到控件时会抛出异常，这时候建议检查剪映的版本和窗口状态。如果导出经常超时，可以适当延长 timeout 值。

容器运行问题

需要确认端口映射和卷挂载路径是否正确。检查 UV_CACHE_DIR 和 PATH 环境变量，查看日志定位依赖安装的问题。

结论

这套方案的核心思路，是通过 Python 后端（FastAPI + uiautomation）与桌面客户端（Electron + React）的协同，打通从草稿下载、素材管理到自动化导出的完整链路。技术选型上兼顾了易用性和可维护性：FastAPI 提供了简洁的 API 和良好的类型支持；uiautomation 保障了自动化流程的稳定；Electron 提升了用户体验和系统集成能力；容器化部署则让运维变得简单。实际部署时，建议重点关注版本兼容性、权限配置和资源限制，这样才能获得最佳的稳定性和性能表现。