FCPX插件目录层级关系文档
============================

一、根目录结构
--------------

用户插件根目录：
~/Movies/Motion Templates.localized/

系统插件根目录：
/Library/Application Support/Final Cut Pro/Templates.localized/

内置插件根目录：
/Applications/Final Cut Pro.app/Contents/PlugIns/MediaProviders/MotionEffect.fxp/Contents/Resources/Templates/

FxPlug插件目录：
/Library/Plug-Ins/FxPlug/


二、插件类型目录（第一层）
------------------------

Effects.localized/          - 效果插件
Generators.localized/       - 发生器插件
Titles.localized/           - 字幕插件
Transitions.localized/      - 转场插件

注意：内置插件目录无.localized后缀


三、类别目录（第二层）- 重要层级
------------------------------

示例路径：Motion Templates.localized/Effects.localized/_dayumedia/

这一层是：
- 用户可见的插件分类
- 拖拽操作的目标层级
- 重命名和合并操作的单位
- 插件管理的核心层级

普通类别目录结构：
Effects.localized/
├── _dayumedia/             ← 类别目录
├── 视频特效/               ← 类别目录
└── 其他分类/               ← 类别目录

FxFactory类别目录结构：
Effects.localized/
├── 12345678-1234-1234-1234-123456789ABC.localized/  ← UUID命名的类别目录
│   ├── .localized/
│   │   └── en.strings      ← 存储真实显示名称
│   └── .fxfactory.plist    ← FxFactory配置文件
└── 其他普通类别/


四、主题目录（第三层）- 可选层级
------------------------------

示例路径：Motion Templates.localized/Effects.localized/_dayumedia/摄影特效/

特点：
- 可选的分组层级
- 不是所有类别都有主题目录
- 纯粹的组织结构
- 可能直接包含插件目录

结构示例：
_dayumedia/                 ← 类别目录
├── 摄影特效/               ← 主题目录
│   ├── 光效插件/           ← 插件目录
│   └── 色彩插件/           ← 插件目录
├── 转场动画/               ← 主题目录
│   └── 淡入淡出/           ← 插件目录
└── 直接插件/               ← 插件目录（无主题分组）


五、插件目录（最终层级）
----------------------

示例路径：Motion Templates.localized/Effects.localized/_dayumedia/光效插件/

必需内容：
- Motion模板文件（.motn, .moef, .moti, .motr）
- 缩略图文件（.jpg, .png）
- Media目录（包含素材文件）

典型插件目录结构：
光效插件/
├── 光效插件.motn           ← Motion模板文件
├── 光效插件.jpg            ← 缩略图
└── Media/                  ← 媒体资源目录
    ├── 素材1.mov
    ├── 素材2.png
    └── ...


六、完整路径示例
--------------

用户插件完整路径：
~/Movies/Motion Templates.localized/Effects.localized/_dayumedia/摄影特效/光效插件/光效插件.motn

系统插件完整路径：
/Library/Application Support/Final Cut Pro/Templates.localized/Effects.localized/Apple效果/基础效果/模糊.motn

FxFactory插件完整路径：
~/Movies/Motion Templates.localized/Effects.localized/12345678-1234-1234-1234-123456789ABC.localized/特效包/粒子效果/粒子效果.motn


七、层级关系总结
--------------

层级1：插件源类型
- user（用户插件）
- system（系统插件）
- fxplug（FxPlug插件）

层级2：插件类型目录
- Effects.localized（效果）
- Generators.localized（发生器）
- Titles.localized（字幕）
- Transitions.localized（转场）

层级3：类别目录 ★重要层级★
- 用户自定义分类名称
- FxFactory使用UUID命名
- 拖拽和合并操作的目标

层级4：主题目录（可选）
- 进一步的分组组织
- 不是必需层级

层级5：插件目录
- 包含实际插件文件
- 拖拽时需要完整复制

层级6：插件文件
- .motn等模板文件
- 缩略图和Media目录


八、特殊情况说明
--------------

1. FxFactory插件特殊处理：
   - 目录名为UUID格式
   - 显示名称存储在.localized/en.strings
   - 删除时需要处理.fxfactory.plist

2. 系统插件限制：
   - 只读权限，不能修改
   - 扫描逻辑与用户插件相同

3. 内置插件特点：
   - 深层嵌套路径
   - 目录名无.localized后缀
   - 完全只读

4. 目录识别规则：
   - 包含.motn等文件 = 插件目录
   - 包含Media目录 = 插件目录
   - 其他情况 = 主题目录，需递归扫描


九、开发注意事项
--------------

1. 拖拽操作：
   - 插件拖拽：复制整个插件目录
   - 类别拖拽：复制整个类别目录及所有内容

2. 合并限制：
   - 只能合并相同插件类型（Effects不能与Titles合并）
   - 需要验证类型一致性

3. 路径处理：
   - 注意.localized后缀的处理
   - FxFactory插件的特殊命名规则
   - 权限检查和错误处理

4. 性能考虑：
   - 大目录扫描使用异步处理
   - 缓存扫描结果
   - 避免重复扫描


十、目录操作映射
--------------

用户界面操作 → 实际目录操作：

重命名类别 → 重命名类别目录
删除类别 → 移动类别目录到回收站
合并类别 → 移动插件目录到目标类别
拖拽插件 → 复制插件目录到目标位置
拖拽类别 → 复制类别目录到目标位置

注意：所有操作都在类别目录层级进行，确保插件的完整性和FCPX的正确识别。
