技术栈概览

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排除指南
9. 结论

简介

本项目为 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 前端<br/>Vite 构建"]
Main["Electron 主进程<br/>main.js"]
Preload["预加载脚本<br/>preload.js"]
IPC["IPC 处理器<br/>ipcHandlers.js"]
end
subgraph "后端服务(Python)"
FastAPI["FastAPI 应用<br/>main.py"]
Router["路由(v1)<br/>src/router/v1.py"]
Middleware["中间件<br/>src/middlewares/prepare.py"]
Utils["工具类<br/>src/utils/draft_downloader.py"]
Auto["自动化控制<br/>src/pyJianYingDraft/jianying_controller.py"]
Cfg["配置<br/>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["桌面客户端<br/>Electron + React"] --> API["后端 API<br/>FastAPI"]
API --> Service["业务服务<br/>service 层"]
API --> Utils["工具类<br/>draft_downloader"]
API --> Auto["自动化控制<br/>JianyingController"]
Auto --> CapCut["剪映应用<br/>Windows UIAutomation"]
API --> Config["配置中心<br/>config.py"]
Docker["容器化运行<br/>Dockerfile"] --> API
Compose["编排<br/>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()
+save_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_SAVE_PATH
+COS_SECRET_ID
+COS_SECRET_KEY
+COS_BUCKET_NAME
+COS_REGION
+ENABLE_APIKEY
}
FastAPIApp --> V1Router : "注册路由"
FastAPIApp --> PrepareMiddleware : "注册中间件"
V1Router --> Config : "读取配置"

自动化控制组件分析

• 控制器职责
  • 查找剪映窗口、切换状态（主页/编辑页/导出页）、设置导出分辨率与帧率、点击导出按钮、等待导出完成、移动导出文件。
• 状态机设计
  • 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 {
<<enumeration>>
+RES_8K
+RES_4K
+RES_2K
+RES_1080P
+RES_720P
+RES_480P
}
class ExportFramerate {
<<enumeration>>
+FR_24
+FR_25
+FR_30
+FR_50
+FR_60
}
JianyingController --> ControlFinder : "使用"
JianyingController --> ExportResolution : "设置"
JianyingController --> ExportFramerate : "设置"

桌面客户端组件分析

• 主进程
  • 创建 BrowserWindow、加载开发/生产资源、设置安全策略、处理未捕获异常、窗口生命周期管理。
• 预加载脚本
  • 通过 contextBridge 暴露受控 API，如保存文件、获取 URL JSON 数据、读取/清空下载日志、打开外部 URL、读取配置与历史记录等。
• IPC 处理器
  • 注册 ipcMain.handle，实现文件保存、日志读取、URL 访问检测、历史记录读取、消息框弹窗等功能。

sequenceDiagram
participant UI as "React 前端"
participant Preload as "预加载脚本"
participant Main as "Electron 主进程"
participant IPC as "IPC 处理器"
participant FS as "文件系统"
UI->>Preload : 调用 window.electronAPI.saveFile(config)
Preload->>Main : ipcRenderer.invoke('save-file', config)
Main->>IPC : ipcMain.handle('save-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<br/>提取draft_id"]
ParseURL --> GetList["获取文件列表"]
GetList --> LoopFiles{"遍历文件"}
LoopFiles --> |下载失败| Retry["重试/记录错误"]
LoopFiles --> |下载成功| WriteFile["写入文件<br/>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、日志与 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 提升用户体验与系统集成能力；容器化部署简化运维。建议在实际部署中关注版本兼容性、权限配置与资源限制，以获得最佳稳定性与性能表现。