草稿管理系统

目录

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

简介

本项目为剪映草稿管理系统，提供草稿的创建、保存、查询与管理能力，并支持模板系统、画布配置、轨道设置与片段管理。系统通过 FastAPI 提供 REST API，服务层封装业务逻辑，底层基于草稿脚本文件模型实现对剪映草稿结构的读写与同步。

重要更新：系统已完成从 template/default 模板系统到 template/default2 的重大迁移，引入了新的 draft_content.json 文件结构，重构了草稿文件组织方式，并优化了模板系统的扩展机制。同时，新增了目录扫描集成功能，自动触发 Adobe Premiere Pro 的内部目录发现机制，显著提升用户体验。

项目结构

• API 层：路由定义与请求/响应模型
• 服务层：业务逻辑编排与异常处理
• 草稿模型层：草稿脚本文件、轨道、片段与素材抽象
• 配置与缓存：全局配置、草稿缓存与模板资源
• 桌面客户端：Electron 应用，提供图形界面和文件下载功能
• 目录扫描系统：自动触发文件系统变更通知，激活剪映目录发现机制

核心组件

• 草稿脚本文件模型：负责草稿内容的加载、修改与导出，支持模板模式与双文件兼容模式。
• 草稿文件夹管理器：提供草稿的创建、复制、加载模板与素材检查等能力。
• 轨道系统：定义轨道类型、渲染顺序与片段添加规则，保证片段不重叠。
• 服务层：封装创建、保存、查询等业务逻辑，并与缓存与配置交互。
• API 路由：定义 REST 接口，绑定请求/响应模型与服务层方法。
• 目录扫描系统：自动触发文件系统变更通知，激活剪映目录发现机制，无需重启即可感知新草稿。
• 桌面客户端：提供图形界面，集成文件下载、日志管理和目录扫描功能。

架构总览

系统采用分层架构：

• 表现层：FastAPI 路由与 Pydantic 模型
• 业务层：服务函数编排与异常处理
• 数据访问层：草稿脚本文件与模板资源
• 配置与缓存：全局配置与 LRU 草稿缓存
• 桌面客户端层：Electron 应用，提供图形界面和文件下载功能
• 目录扫描层：自动触发文件系统变更通知，激活剪映目录发现机制

详细组件分析

草稿脚本文件模型

• 负责加载模板、设置画布尺寸、添加轨道与片段、合并素材与轨道并导出。
• 支持双文件兼容模式，确保 draft_info.json 与 draft_content.json 同步。
• 提供导入轨道、替换素材与文本、解析 SRT 字幕等功能。

草稿文件夹管理器

• 提供草稿创建、复制模板为新草稿、加载模板、删除草稿与素材检查等能力。
• 通过资产模板与脚本文件配合，完成草稿的初始化与持久化。

轨道系统

• 定义轨道类型与渲染顺序，确保片段按正确顺序渲染。
• 提供片段添加校验，防止片段重叠。

服务层与 API 层

• 创建草稿：复制模板、设置画布尺寸、添加主轨道、启用双文件兼容并保存。
• 保存草稿：从 URL 解析草稿 ID，从缓存获取草稿并保存。
• 获取草稿：校验草稿 ID 与目录存在性，遍历文件并生成下载 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 变更通知
• 临时目录清理：扫描完成后自动清理临时目录，避免磁盘空间浪费

草稿控制器工作原理

• 通过草稿脚本文件模型统一管理草稿内容，服务层负责业务编排与异常处理。
• 草稿缓存用于提升频繁保存/读取场景的性能，采用 LRU 策略限制最大容量。
• 桌面客户端：提供图形界面，集成文件下载、日志管理和目录扫描功能。

文件操作流程与错误处理

• 创建草稿：复制模板、设置画布、添加轨道、保存；异常统一捕获并返回自定义错误。
• 保存草稿：校验 URL 与缓存有效性；异常统一捕获并返回自定义错误。
• 获取草稿：校验草稿 ID 与目录存在性；异常统一捕获并返回自定义错误。
• 目录扫描：跨平台目录扫描，robocopy 返回码 0-7 视为成功，8+ 视为错误。

依赖关系分析

• 路由依赖服务层；服务层依赖草稿模型与配置；草稿模型依赖资产模板与工具模块。
• 草稿缓存与配置贯穿服务层，提升性能与可配置性。
• 桌面客户端：Electron 应用依赖 IPC 处理器和下载模块，实现文件下载与目录扫描功能。

性能考虑

• 草稿缓存：采用 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+ 视为错误
• 资源清理：扫描完成后自动清理临时目录

用户体验提升

• 即时感知：新下载的草稿立即出现在剪映项目面板中
• 无缝体验：无需手动刷新或重启应用程序
• 跨平台一致性：在不同操作系统上提供一致的用户体验

附录

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