草稿管理系统
目录
简介
本项目为剪映草稿管理系统，提供草稿的创建、保存、查询与管理能力，并支持模板系统、画布配置、轨道设置与片段管理。系统通过 FastAPI 提供 REST API，服务层封装业务逻辑，底层基于草稿脚本文件模型实现对剪映草稿结构的读写与同步。
重要更新：系统已完成从 template/default 模板系统到 template/default2 的重大迁移，引入了新的 draft_content.json 文件结构，重构了草稿文件组织方式，并优化了模板系统的扩展机制。同时，新增了目录扫描集成功能，自动触发 Adobe Premiere Pro 的内部目录发现机制，显著提升用户体验。
项目结构
- API 层：路由定义与请求/响应模型
- 服务层：业务逻辑编排与异常处理
- 草稿模型层：草稿脚本文件、轨道、片段与素材抽象
- 配置与缓存：全局配置、草稿缓存与模板资源
- 桌面客户端：Electron 应用，提供图形界面和文件下载功能
- 目录扫描系统：自动触发文件系统变更通知，激活剪映目录发现机制
graph TB
subgraph "API 层"
R["路由(v1)"]
Schemas["请求/响应模型"]
end
subgraph "服务层"
SVC_Create["创建草稿服务"]
SVC_Save["保存草稿服务"]
SVC_Get["获取草稿服务"]
end
subgraph "草稿模型层"
SF["ScriptFile<br/>草稿脚本文件"]
DF["DraftFolder<br/>草稿文件夹管理"]
TR["Track<br/>轨道"]
end
subgraph "配置与资源"
CFG["配置(config.py)"]
TPL["模板(default2)"]
CACHE["草稿缓存(draft_cache.py)"]
end
subgraph "桌面客户端"
ELECTRON["Electron 应用"]
IPC["IPC 处理器"]
DOWNLOAD["下载模块"]
SCAN["目录扫描"]
end
R --> Schemas
R --> SVC_Create
R --> SVC_Save
R --> SVC_Get
SVC_Create --> SF
SVC_Save --> SF
SVC_Get --> SF
SF --> TR
DF --> SF
DF --> TPL
CFG --> SVC_Create
CFG --> SVC_Save
CFG --> SVC_Get
CACHE --> SVC_Create
CACHE --> SVC_Save
ELECTRON --> IPC
IPC --> DOWNLOAD
DOWNLOAD --> SCAN
核心组件
- 草稿脚本文件模型：负责草稿内容的加载、修改与导出，支持模板模式与双文件兼容模式。
- 草稿文件夹管理器：提供草稿的创建、复制、加载模板与素材检查等能力。
- 轨道系统：定义轨道类型、渲染顺序与片段添加规则，保证片段不重叠。
- 服务层：封装创建、保存、查询等业务逻辑，并与缓存与配置交互。
- API 路由：定义 REST 接口，绑定请求/响应模型与服务层方法。
- 目录扫描系统：自动触发文件系统变更通知，激活剪映目录发现机制，无需重启即可感知新草稿。
- 桌面客户端：提供图形界面，集成文件下载、日志管理和目录扫描功能。
架构总览
系统采用分层架构：
- 表现层：FastAPI 路由与 Pydantic 模型
- 业务层：服务函数编排与异常处理
- 数据访问层：草稿脚本文件与模板资源
- 配置与缓存：全局配置与 LRU 草稿缓存
- 桌面客户端层：Electron 应用，提供图形界面和文件下载功能
- 目录扫描层：自动触发文件系统变更通知，激活剪映目录发现机制
sequenceDiagram
participant C as "客户端"
participant API as "路由(v1)"
participant SVC as "服务层"
participant SF as "ScriptFile"
participant DF as "DraftFolder"
participant FS as "文件系统"
participant Electron as "桌面客户端"
participant Scan as "目录扫描"
C->>API : POST /v1/create_draft
API->>SVC : 调用创建草稿
SVC->>DF : 复制模板并创建草稿
DF->>FS : 写入draft_content.json与draft_info.json
SVC->>SF : 修改画布尺寸与轨道
SVC->>FS : 保存草稿
SVC-->>API : 返回草稿URL
API-->>C : 响应草稿URL
Note over Electron,Scan : 草稿下载完成后
Electron->>Scan : 触发目录扫描
Scan->>FS : 复制目录触发文件系统变更
FS-->>Scan : 发送ReadDirectoryChangesW通知
Scan-->>Electron : 目录扫描完成
Electron-->>C : 用户界面更新
详细组件分析
草稿脚本文件模型
- 负责加载模板、设置画布尺寸、添加轨道与片段、合并素材与轨道并导出。
- 支持双文件兼容模式，确保 draft_info.json 与 draft_content.json 同步。
- 提供导入轨道、替换素材与文本、解析 SRT 字幕等功能。
classDiagram
class ScriptFile {
+int width
+int height
+int fps
+int duration
+ScriptMaterial materials
+Dict tracks
+load_template(json_path) ScriptFile
+add_track(track_type, track_name, ...) ScriptFile
+add_segment(segment, track_name) ScriptFile
+add_effect(effect, t_range, ...) ScriptFile
+add_filter(filter_meta, t_range, ...) ScriptFile
+import_srt(srt_path, track_name, ...) ScriptFile
+dumps() str
+dump(file_path) void
}
class ScriptMaterial {
+List audios
+List videos
+List stickers
+List texts
+List audio_effects
+List audio_fades
+List animations
+List video_effects
+List speeds
+List masks
+List transitions
+List filters
+List canvases
+export_json() Dict
}
ScriptFile --> ScriptMaterial : "组合"
草稿文件夹管理器
- 提供草稿创建、复制模板为新草稿、加载模板、删除草稿与素材检查等能力。
- 通过资产模板与脚本文件配合，完成草稿的初始化与持久化。
flowchart TD
Start(["开始"]) --> CheckPath["检查草稿目录是否存在"]
CheckPath --> Exists{"是否已存在?"}
Exists --> |是| AllowReplace{"允许覆盖?"}
AllowReplace --> |否| Error["抛出已存在异常"]
AllowReplace --> |是| RemoveOld["删除旧草稿"]
Exists --> |否| MakeDir["创建草稿目录"]
RemoveOld --> MakeDir
MakeDir --> CopyMeta["复制草稿元信息模板"]
CopyMeta --> CreateScript["创建ScriptFile实例"]
CreateScript --> SetSavePath["设置保存路径与双文件兼容"]
SetSavePath --> Save["保存草稿"]
Save --> End(["结束"])
Error --> End
轨道系统
- 定义轨道类型与渲染顺序，确保片段按正确顺序渲染。
- 提供片段添加校验，防止片段重叠。
classDiagram
class TrackType {
+video
+audio
+effect
+filter
+sticker
+text
}
class Track {
+track_type
+name
+track_id
+render_index
+mute
+segments
+add_segment(segment) Track
+export_json() Dict
}
TrackType <.. Track : "使用"
服务层与 API 层
- 创建草稿：复制模板、设置画布尺寸、添加主轨道、启用双文件兼容并保存。
- 保存草稿：从 URL 解析草稿 ID，从缓存获取草稿并保存。
- 获取草稿：校验草稿 ID 与目录存在性，遍历文件并生成下载 URL。
sequenceDiagram
participant Client as "客户端"
participant Router as "路由(v1)"
participant Service as "服务层"
participant Cache as "草稿缓存"
participant FS as "文件系统"
Client->>Router : GET /v1/get_draft?draft_id=...
Router->>Service : 调用获取草稿
Service->>FS : 列出草稿目录文件
Service->>Service : 生成下载URL
Service-->>Router : 返回文件URL列表
Router-->>Client : 响应文件URL列表
草稿模板系统
- 模板迁移：从 template/default 迁移到 template/default2，引入了新的 draft_content.json 文件结构。
- 文件结构：default2 模板包含 draft_content.json、draft_info.json、draft_meta_info.json 等文件，提供更完整的草稿结构。
- 模板路径：创建草稿时使用 config.TEMPLATE_DIR + "/default2" 作为模板路径。
- 双文件兼容：支持 draft_info.json 和 draft_content.json 的同步保存，确保数据一致性。
目录扫描集成系统
新增功能：系统现已集成自动目录扫描功能，能够在草稿下载完成后自动触发 Adobe Premiere Pro 的内部目录发现机制。
工作原理
- 文件系统变更通知：通过复制草稿目录到临时目录的方式触发系统级文件变更通知
- 跨平台支持：Windows 使用 robocopy，macOS 使用 rsync，确保在不同操作系统上都能正常工作
- 无需重启：剪映无需重启即可感知到新草稿的存在
技术实现
- Windows 平台：使用 robocopy 工具执行目录复制，返回码 0-7 表示成功
- macOS 平台：使用 rsync 工具触发 FSEvents 变更通知
- 临时目录清理：扫描完成后自动清理临时目录，避免磁盘空间浪费
flowchart TD
Start(["草稿下载完成"]) --> CheckPlatform["检查操作系统平台"]
CheckPlatform --> Windows{"Windows?"}
CheckPlatform --> Mac{"macOS?"}
CheckPlatform --> Other{"其他平台?"}
Windows --> |是| Robocopy["使用robocopy复制目录"]
Mac --> |是| Rsync["使用rsync复制目录"]
Other --> |是| Skip["跳过目录扫描"]
Robocopy --> TriggerNotify["触发ReadDirectoryChangesW通知"]
Rsync --> TriggerNotify
TriggerNotify --> CleanTmp["清理临时目录"]
CleanTmp --> End(["完成"])
Skip --> End
草稿控制器工作原理
- 通过草稿脚本文件模型统一管理草稿内容，服务层负责业务编排与异常处理。
- 草稿缓存用于提升频繁保存/读取场景的性能，采用 LRU 策略限制最大容量。
- 桌面客户端：提供图形界面，集成文件下载、日志管理和目录扫描功能。
文件操作流程与错误处理
- 创建草稿：复制模板、设置画布、添加轨道、保存；异常统一捕获并返回自定义错误。
- 保存草稿：校验 URL 与缓存有效性；异常统一捕获并返回自定义错误。
- 获取草稿：校验草稿 ID 与目录存在性；异常统一捕获并返回自定义错误。
- 目录扫描：跨平台目录扫描，robocopy 返回码 0-7 视为成功，8+ 视为错误。
依赖关系分析
- 路由依赖服务层；服务层依赖草稿模型与配置；草稿模型依赖资产模板与工具模块。
- 草稿缓存与配置贯穿服务层，提升性能与可配置性。
- 桌面客户端：Electron 应用依赖 IPC 处理器和下载模块，实现文件下载与目录扫描功能。
graph LR
Router["路由(v1)"] --> Service["服务层"]
Service --> Script["ScriptFile"]
Service --> DraftFolder["DraftFolder"]
Service --> Cache["草稿缓存"]
Service --> Config["配置(config.py)"]
Script --> Track["Track"]
DraftFolder --> Script
Config --> Service
Electron["桌面客户端"] --> IPC["IPC处理器"]
IPC --> Download["下载模块"]
Download --> Scan["目录扫描"]
性能考虑
- 草稿缓存：采用 LRU 策略限制最大容量，减少重复读写磁盘的开销。
- 双文件兼容：在保存时同步更新两个文件，避免数据不一致带来的额外校验成本。
- 轨道与片段校验：在添加片段时进行重叠检测，避免后续渲染阶段出现异常。
- 目录扫描优化：使用静默模式执行 robocopy，避免影响用户界面响应性。
- 跨平台适配：针对不同操作系统选择最优的目录扫描方案，确保最佳性能。
故障排除指南
- 草稿创建失败：检查模板目录是否存在、目标草稿目录权限与磁盘空间。
- 无效草稿 URL：确认 URL 中包含有效的草稿 ID，且缓存中存在对应草稿。
- 获取草稿失败：确认草稿 ID 存在且草稿目录可访问，检查下载 URL 生成逻辑。
- 目录扫描失败：检查操作系统平台支持情况，Windows 系统需确保 robocopy 可用，macOS 系统需确保 rsync 可用。
- robocopy 返回码错误：根据返回码 8+ 的错误信息进行相应处理，如权限不足、磁盘空间不足等。
结论
本系统通过清晰的分层设计与完善的草稿模型抽象，实现了对剪映草稿的创建、保存、查询与管理。模板系统从 template/default 成功迁移到 template/default2，引入了新的 draft_content.json 文件结构，增强了草稿文件的完整性与一致性。双文件兼容模式确保了草稿结构的稳定性，服务层与缓存机制提升了性能与可靠性。API 层以简洁的接口对外提供能力，便于集成与扩展。
重要更新：新增的目录扫描集成功能显著提升了用户体验，通过自动触发 Adobe Premiere Pro 的内部目录发现机制，用户无需重启剪映即可感知到新下载的草稿，实现了无缝的草稿管理体验。桌面客户端的集成使得整个工作流程更加直观和高效。
附录
草稿管理 API 使用指南
创建草稿
- 方法与路径：POST /v1/create_draft
- 请求参数：
- width：画布宽度（整数，默认 1920）
- height：画布高度（整数，默认 1080）
- 返回参数：
- draft_url：草稿访问 URL
- tip_url：帮助文档 URL
- 实际应用示例：前端调用该接口后，得到草稿 URL，后续可在该草稿上添加视频、音频、图片、贴纸、字幕、特效等素材。
保存草稿
- 方法与路径：POST /v1/save_draft
- 请求参数：
- draft_url：草稿 URL
- 返回参数：
- draft_url：草稿 URL
获取草稿文件列表
- 方法与路径：GET /v1/get_draft?draft_id=...
- 请求参数：
- draft_id：草稿标识
- 返回参数：
- files：文件下载 URL 列表
草稿文件结构与模板
- 新文件结构：default2 模板包含 draft_content.json、draft_info.json、draft_meta_info.json 等文件，提供更完整的草稿结构。
- draft_content.json：包含完整的草稿内容，包括画布配置、素材集合、轨道列表与关键帧等字段。
- draft_info.json：包含草稿的基本信息和配置，支持多语言和系统字体列表。
- draft_meta_info.json：包含草稿的元信息，如云包信息、草稿类型等。
- 模板文件：提供初始结构，创建草稿时复制模板并修改画布尺寸与轨道。
画布配置与轨道设置
- 画布配置：宽度、高度、宽高比与帧率等。
- 轨道设置：轨道类型、渲染顺序、静音状态与片段列表。
草稿模板扩展与自定义配置
- 模板迁移：通过复制 template/default2 目录并在创建草稿时修改画布尺寸与轨道，实现模板扩展。
- 自定义配置：可在模板中预置素材与轨道，支持多语言配置和系统字体列表。
- 扩展机制：支持通过修改 draft_content.json 和 draft_info.json 来定制草稿模板。
目录扫描集成使用指南
新增功能：自动触发 Adobe Premiere Pro 的内部目录发现机制，提升用户体验。
功能特点
- 自动触发：草稿下载完成后自动执行目录扫描
- 跨平台支持：Windows 使用 robocopy，macOS 使用 rsync
- 无需重启：剪映无需重启即可感知新草稿
- 静默执行：不影响用户界面响应性
技术实现
- Windows 平台：使用 robocopy 工具复制目录，触发 ReadDirectoryChangesW 通知
- macOS 平台：使用 rsync 工具触发 FSEvents 变更通知
- 错误处理：robocopy 返回码 0-7 视为成功，8+ 视为错误
- 资源清理：扫描完成后自动清理临时目录
用户体验提升
- 即时感知：新下载的草稿立即出现在剪映项目面板中
- 无缝体验：无需手动刷新或重启应用程序
- 跨平台一致性：在不同操作系统上提供一致的用户体验
