剪映自动化 Skill 复盘——让 Agent 剪视频，怎么做到「不误删、不伪装、失败可解释」

仓库：ydflow/jianying-editor-skill-reliable · Python
一句话：剪映自动化 Agent Skill 的可靠增强版。

一、背景：一个「能剪」但「不可靠」的上游项目

上游 luoluoluo22/jianying-editor-skill 已经做得很好了：用自然语言指挥 Agent 完成从写文案、配音、加字幕、选音乐、上特效到导出的整套流程。

但我在实际使用里发现几个「能用但不敢放心用」的问题：

• 默认会覆盖已有草稿——一个误操作就毁了辛苦做的工程；
• 录屏得到的 WebM 输出为 .mp4 时只改扩展名、没真转码——格式是「伪装」的；
• 剪映版本变了，Agent 却判断不了，可能误触新版本弹窗；
• Windows 终端遇到 Emoji 会 UnicodeEncodeError，失败没有解释。

于是有了这个二次开源版本，聚焦一句话：不误删、不伪装格式、版本可判断、失败可解释。

二、可靠增强：五个具体的改动

1. 安全覆盖——默认不覆盖草稿

JyProject 默认不再覆盖已有草稿；显式覆盖前，自动先把旧草稿移入时间戳备份。这是「误删」的第一道防线。

2. 只读 Doctor——先体检，再动手

新增 scripts/doctor.py，检查 Python、FFmpeg、依赖、Playwright、剪映版本、草稿路径，默认不写入任何草稿。把「环境对不对」和「要不要动手」分开。

3. 导出预检——版本不对就拦住

检测到未验证的新版剪映时，阻止 UI 自动导出，避免误操作。版本判断从不透明变成了显式的门禁。

4. 媒体保真——别伪装

• 视频标准化默认保留原始方向、尺寸和帧率；
• 缓存不再写到 Skill 或素材目录；
• WebM 输出为 .mp4 时，用 FFmpeg 真正转码，不再只改扩展名。

5. Windows UTF-8——让失败可见

统一处理 Agent 终端的 Unicode 输出，避免 Emoji 导致 GBK UnicodeEncodeError。失败不再是一堆乱码，而是能读懂的错误。

三、二次开源的正确姿势

这个项目有个我很在意的细节——怎么对待上游：

• 保留原项目完整的 Git 历史；
• 保留 MIT 许可证，内嵌 pyJianYingDraft 的 Apache-2.0 归属明确标注；
• 清楚声明「与剪映官方无关联」。

二次开源不是「拿来改改」，而是要诚实交代来源和边界。这是对上游、对用户、对自己的三重负责。

四、诚实的边界：明确「做不到什么」

README 里专门有一节「做不到什么」，比「能做什么」更值得读：

• 不是剪映的替代品：最终渲染还是靠剪映本身，工具负责「搭好时间轴 + 点击导出」；
• 不能用剪映的实时特效：智能抠图、美颜、语音识别字幕这类 GPU 实时功能，代码调不了；
• 自动导出依赖 Windows UI 自动化：剪映 5.9 及以下最稳，新版本可能受弹窗影响；
• Mac 需手动导出、不支持手机端/国际版。

把边界写清楚，用户才不会在错误场景里浪费时间，也避免「看起来全能、用起来翻车」。

五、几点复盘

1. 可靠是自动化工具的第一价值。一个会误删草稿的剪视频工具，再聪明也不敢用。先「不犯错」，再谈「更高效」。
2. 「不伪装」是工程底线。改个扩展名让文件看起来是 MP4，本质是埋雷。真转码、真保真，才对得起「可靠」二字。
3. 失败要可解释。一个 UnicodeEncodeError 背后是「没处理 Windows 编码」，修好它，Agent 的每一次失败才值得被复盘。
4. 二次开源要讲清楚归属。保留历史、保留许可证、声明无关，这三件事一个都不能少。

这个项目让我重新理解了「Agent 工具」的含义：工具的价值不在功能列表有多长，而在于你可以放心地把真实的活交给它。