JianYing Editor Skill

剪映专业版的一个工程就是磁盘上的一个文件夹：draft_info.json 装时间轴，draft_meta_info.json 装工程信息，而它导入的每个素材都会被复制进这个目录。这个仓库是套在那层目录外面的 Python 封装，按 skill 的形式给 agent 加载。JyProject 新建或打开草稿，往命名轨道上追加片段，用同义词表把特效、滤镜、转场、动画的名字解析成枚举，把一段文案逐句变成配音、再按每句音频的实际时长压上一条字幕，并写入缩放运镜用的关键帧。data/ 下十二份 CSV 把剪映自己的云端音乐、音效、视频素材、滤镜和转场按 id 编成索引，于是 agent 能按中文名从剪映的库里挑东西。录屏走 ffmpeg 加一个记录点击的 Tk 窗口；网页动画由 Playwright 录成片段。只有导出这一步离开了文件系统，也是唯一分平台的一步。

谁做的一个 2016 年注册的 GitHub 账号，148 个公开仓库、60 个关注者。仓库 3,858 星、492 个 fork、16 个 watcher。贡献者表上除作者外还有三个人：@twodogegg 做 macOS 适配，@shaozheliu 修 5.9 的素材丢失，@Maxinsomnia 支持 macOS 上的草稿。main 上 117 次提交里有 114 次是作者本人的。

1. 01

   仓库是一个给 agent 读的文件夹，而且大半是数据

   这个 skill 一共 184 个文件，其中 47 个在 assets/ 下：三组剪映自己的特效素材，里面有 effect.prefab、main.scene、材质、贴图和 GLSL 着色器，外加一套 8 个文件的演示素材，打头的是 3 MB 的测试视频。剩下 137 个文件合起来约 2.6 MB，其中体积最大的一份根本不是脚本，而是 262 KB 的 data/cloud_music_library.csv，一份剪映云端已有音乐的 id 索引。SKILL.md 有 10 KB，是 agent 最先读的东西；rules/ 另有十一份文件。GitHub 把仓库的语言统计成 Python 第一、HTML 第二、GLSL 第三，而 GLSL 全在特效素材里。仓库创建于 2026-01-24，main 上 117 次提交，时间从 2026-01-27 到 2026-09-11，其中 114 次来自作者本人的账号。VERSION 写的是 1.7.0，CHANGELOG.md 最新一条的日期是 2026-09-11。仓库从来没发过 release，也没打过 tag。

2. 02

   整个接口就是一个 JSON 文件，而映射是别人写的

   改工程的方式，是在剪映打开它之前把 draft_info.json 拼出来。从这份 JSON 到 Python 对象的那层映射不是这里写的：scripts/vendor/pyJianYingDraft/ 是管奕轩的 pyJianYingDraft 的副本，Apache-2.0，Copyright 2024，自带一份 LICENSE，scripts/vendor/README.md 按这条许可的要求列出了本地改动。这些改动正是它被内嵌而不是当依赖装的原因：草稿格式换成了 5.9 与 6.x 用的 draft_info.json，local_material_id 由文件名生成，素材不再动不动丢失，pymediainfo 缺失时改用 ffprobe 探测。requirements.txt 里没有它的条目，所以从一份 clone 就能跑。在这层库之上，scripts/jy_wrapper.py 只有 70 行，用四个 mixin 拼出 JyProject。它的 save() 不只是写文件，还会给草稿引用到的云端素材补上 material id，并强制激活调节节点——一份引用了云端素材却没有这些字段的草稿，打开时那个素材是缺的。

3. 03

   剪映会锁住自己的草稿，于是封装去请它松手

   分辨率在第一次调用 JyProject(...) 时就定下来，默认 1920x1080，而规则文档两次提醒：用默认值建竖屏工程会出黑边。在 Windows 上，只要那份草稿还开在剪辑页，剪映就占着工程目录，创建会抛 PermissionError。封装会重试三次，两次之间通过 uiautomation 伸手进正在运行的剪映，读它停在首页还是剪辑页，如果停在剪辑页就先把它切回首页再试。草稿目录里少了 JSON 会被当成损坏，overwrite=True 时直接删掉重建。工程名会被清洗，每一条路径在删除之前都要和草稿根目录比对一次——v1.5.0 的日志里说的「阻止路径穿越」指的就是这一步。

4. 04

   配音用的是剪映自己的服务，密钥从这台机器上读出来

   scripts/universal_tts.py 不用自己的云端账号。它从剪映本地的 TTNet 配置里读出一个 device id，从用户目录下最新的几个日志文件里读出一个 iid，然后带着源码里写死的 app_id 3704 和应用密钥，用自称 JianyingPro/5.9.0.11632 的 User-Agent，连上 sami.bytedance.com 的 WebSocket。有个环境变量可以关掉 TLS 校验，关掉时脚本会打印警告；默认是校验的，v1.5.0 的日志把这一条列为修复。这条链路失败时，退路是 edge-tts 和微软的音色。add_narrated_subtitles 按中文标点把一段话切开，逐句生成一个音频文件，再在它上面压一条时长等于该音频时长的文字片段，字幕因此不可能和声音走散。第一个应答成功的后端会被锁定给整段话用：后半段若失败，它会直接报错，而不是把视频用第二个音色配完。

5. 05

   凡是不靠写文件完成的部分，不是点击就是浏览器

   tools/recording/recorder.py 是一个 Tk 窗口，在 Windows 上驱动 ffmpeg 的 gdigrab 与 dshow，在 macOS 上用 avfoundation，同时用 pynput 把鼠标和键盘事件写进录像旁边的 JSON 文件。scripts/smart_zoomer.py 再把那些点击读成关键帧：推近、停留、还原。碰到剪映本身没有的特效，scripts/web_recorder.py 起一个 Playwright 浏览器，把网页录成视频，等动画把 window.animationFinished 置位，上限 30 秒。导出这一步，工具彻底离开了文件系统：scripts/auto_exporter.py 用 Windows 的 UI Automation 去点剪映的导出对话框。在 macOS 上调用它，返回的是退出码 2，以及一句「请在剪映里手动导出」。

• 自动导出只支持 Windows，README 点名说剪映 5.9 或更低版本最稳。在 macOS 上调 scripts/auto_exporter.py，它返回退出码 2，并告诉调用者手动导出。
• README 在安装之前就先划掉三件事：CapCut 国际版完全不支持，手机端也不支持，而跑在剪映 GPU 上的功能——智能抠图、美颜、语音识别字幕——都无法从代码调用。
• 剪映会自动更新，而且阻止不了，这就是开着的第 24 号 issue。新版本会挪动导出自动化所点的那些控件，所以一次剪映更新就能弄坏最后一步，而这个仓库里什么都没改。
• 六个 issue 开着。其中 2026-09-16 提的那个列了七处「失败之后照样产出一支成片，只是成片是错的」；2026-09-22 提的那个要求：缺 ffprobe 时素材探测应当降级，而不是中断导入。
• 录制器的「自动生成智能草稿」按钮执行的是 scripts/jy_wrapper.py apply-zoom，后面跟着 --name、--video、--json。jy_wrapper.py 根本没有参数解析，它的 __main__ 只会建一个叫 Refactor_Test_Project 的工程，那几个参数从头到尾没人读。真正会应用缩放关键帧的 apply_smart_zoom 在 scripts/smart_zoomer.py 里，没有任何文件 import 它，而它开头是一句相对导入，单独运行这个文件必然失败。scripts/smart_rough_cut.py 则 import 了属于另一个 skill 的 api_client，失败被一个 warning 吞掉，模块里两个名字从此都是 None。