24-剪映skills-说明文档

剪映自动化底层 Skill 使用说明

本文档详细介绍了 jianying-editor-skill 的工作模式、运行逻辑、调用方式和经过实测确认可控制的参数。请你收到该文档之后，按照文档说明找到底层skills的位置，仔细研究其具体的代码和文件。研究好之后，用户再让你生成具体的上层业务封装 Skill。

1. 底层 Skill 位置

本地底层剪映自动化 skill 根目录：

以下称它为 ``。

2. 工作模式与运行逻辑

jianying-editor-skill 是底层能力 skill，提供的是剪映自动化 API、脚本入口、规则文档、素材索引和运行约束。它不是直接成片逻辑，也不应该承载具体业务规则。

标准运行逻辑：

1. 在任务脚本中定位 ``。
2. 将 \scripts 加入 sys.path。
3. 导入 JyProject 和底层 pyJianYingDraft 对象。
4. 创建 JyProject(...)。
5. 调用 project.add_media_safe(...)、project.add_text_simple(...)、project.add_audio_safe(...) 等 API 组装时间线。
6. 任务脚本最后必须调用 project.save()。
7. 生成的结果是剪映草稿，而不是直接生成 MP4 成片。
8. 如需导出 MP4，需要额外调用导出脚本，且自动导出依赖 Windows 和剪映版本。

3. 底层 Skill 与上层业务封装 Skill 的关系

底层 jianying-editor-skill 只负责提供剪映草稿生成能力。

上层业务封装 skill 负责决定素材目录结构、素材选择规则、时间线组合逻辑、标题和字幕样式、批量生成数量、草稿命名规则等。

重要约束：

• 不要把业务剪辑脚本写进底层 jianying-editor-skill-main 目录。
• 新业务逻辑应该放在新的业务封装 skill 或当前项目工作区中。
• 新业务封装 skill 不是为了替代底层 skill，而是在底层能力之上做业务编排。
• 最终生成剪映草稿仍然必须通过 JyProject 和相关 API。
• 所有任务脚本最后必须调用 project.save()。

4. 通用规则

所谓通用规则，是指不同类型素材都要遵守的全局规则。比如时间、颜色、位置、坐标、透明度等参数，普通文本、字幕、图片、视频素材都可能用到；后续能力小节没有单独说明时，应优先按照本章规则设置。

4.1 时间

高层 API 通常支持字符串时间：

底层关键帧等 API 可能需要微秒：

4.2 颜色

文本颜色、描边颜色、阴影颜色通常使用 RGB 浮点元组，范围是 0-1。

例如十六进制 73f74e：

背景颜色使用字符串：

4.3 位置与坐标

经过实测，剪映 UI 中普通文本的位置 X/Y 与 ClipSettings.transform_x/y 的对应方式如下：

在 1920x1080 横屏项目中：

例如 UI 位置 X=500、Y=600：

5. 能力范围及代码示例

5.1 草稿创建

已验证可控参数：

• 基础参数：草稿名称、草稿宽度、草稿高度、是否覆盖同名草稿、自定义草稿根目录
• 批量创建：草稿名称列表、循环创建数量、命名规则、横屏/竖屏分辨率

注意事项：

• 每个草稿都必须添加至少一个元素并调用 project.save()，否则空草稿不利于剪映识别、检查和后续测试。
• overwrite=True 会覆盖同名草稿，批量生产时必须设计好草稿命名规则，避免误覆盖。
• 横屏常用 `width=1920, he