面向剪映专业版 macOS 的本地自动化工具。通过结构化剪辑计划生成可编辑草稿， 在独立副本中修改多轨工程，并调用本机剪映引擎导出 MP4。

主要适配版本：11.5.0 · 兼容版本：11.4.2

首次使用请从 从零生成第一个剪映草稿 开始。 教程包含安装前提、环境检查、拖入自己的视频、首页登记、保存重开和常见报错处理。 11.5.0 仍需匹配具体安装身份与工具链，尚不保证任意电脑安装即用。

项目适用于 AI 视频工作流的工程交接、批量草稿生成和 Agent 辅助剪辑。 提供 Python 命令行入口及配套 Agent Skill。它不是剪映官方 SDK，运行时需要安装匹配版本的剪映。

核心流程为：素材与剪辑计划 → 可编辑剪映草稿 → 原生引擎导出。 剪映中后续手工修改的内容不会自动同步回原计划或旧导出快照。

Windows 另提供独立的 FFmpeg 路径：从剪辑计划生成已校验的渲染快照， 再输出 MP4。它不需要安装剪映，也不生成可在剪映中编辑的草稿； 只支持已说明的视频、音频和基础文字能力，不等同于上方的 macOS 原生流程。 Windows 云端使用本仓库公开 IG 案例验证了完整解码、帧数与音量； 使用方法和限制见 Windows FFmpeg 导出。

该独立导出后端由 @instantgoing 在 PR #1 中贡献。

一个约 50.23 秒的 IG 滚动动画教程展示了从 Hypit 到剪映的工程交接。 转换使用原工程的独立画面、配音、图片和文字时间安排，而不是仅导入一条最终成片。

该案例已在剪映 11.5.0 完成构建、打开播放、保存、完全退出、冷重开和结构回读， 并通过原生导出的 1507 / 1507 帧检查与完整解码检查。

Hypit 原成片	剪映工程原生导出

两组图片均取自真实案例的 1、8、17、28、37、48 秒。展示的是可编辑工程交接， 不是视觉无损转换：特殊字体、逐词颜色动画、部分裁切与阴影未原样保留， 第 37 秒的补充画面也存在差异。完整主观视听验收尚未完成。

详见 Hypit 协作案例 和 媒体说明。 当前转换是单向、按项目实现；不提供任意 Hypit 工程的一键无损转换或双向同步。

• Apple Silicon Mac，macOS 26.0+；已验证环境为 macOS 26.5.1。
• 剪映专业版 11.5.0，或兼容配置对应的 11.4.2。
• Python 3.9+、FFmpeg / ffprobe、Xcode Command Line Tools。
• 已验证桥接工具链：Apple clang 21.0.0 / macOS SDK 26.5。

应用版本、build、官方库哈希、签名与开发者身份均有检查。 未知版本或不匹配组件会被拒绝，不通过放宽校验强行运行。干净机器安装验收尚未完成。 官方引擎、账号数据、原始工程素材库和效果资源不随源码分发。

构建工具选择、安装诊断、登记恢复及字体支持的进展和待验限制见 Issue 修复进展。环境检查通过不等于任意电脑兼容。

git clone https://github.com/mcncarl/jianying-headless.git
cd jianying-headless
python3 tools/build_native_codec.py
python3 skills/yichen-jianying-edit/scripts/headless_draft.py doctor

doctor 是环境检查命令：检查剪映版本、组件身份和必要工具。 检查通过表示环境符合运行条件，不代表任意草稿都已通过画面、声音或导出验收。

桥接构建只编译项目源码并链接本机已安装程序库，不下载剪映、不修改官方库或账号权益。 编译结果必须匹配固定哈希，否则停止。

按 计划格式 准备 JSON， 或参考 基础计划 和 Hypit 交接格式示例。 示例中的素材路径须替换为有权使用的本地文件。

python3 skills/yichen-jianying-edit/scripts/headless_draft.py build \
  --plan /absolute/path/to/plan.json --out "$PWD/work/new-build"
python3 skills/yichen-jianying-edit/scripts/headless_draft.py verify-build \
  --build "$PWD/work/new-build"

保存当前工作并完全退出剪映后，将新草稿登记到本机首页：

python3 skills/yichen-jianying-edit/scripts/headless_draft.py publish \
  --build "$PWD/work/new-build" --audit "$PWD/work/new-publish-audit"

publish 在此仅指本机首页登记，不是互联网发布。生成的草稿仍需实际打开、播放和保存检查。 需要成片时，可独立导出已验证快照：

python3 skills/yichen-jianying-edit/scripts/headless_draft.py export \
  --build "$PWD/work/new-build" --out "$PWD/work/new-export"

输出目录须不存在，成片为该目录下的 render.mp4。 导出在隔离进程中运行，默认不联网、不读取账号数据。

skills/yichen-jianying-edit/ 提供 Agent 调用入口、口播计划辅助脚本与操作参考。 Skill 不包含剪映引擎；独立安装后仍需检出核心项目，并指定其路径：

export JIANYING_HEADLESS_ROOT="/absolute/path/to/jianying-headless"

安装说明见 独立 Skill。 Skill 另收录于 yichen-skills。

• 复合片段仅支持实验性的离线修改与冻结快照导出，尚不能交付为保存可靠的可编辑嵌套草稿。
• 图片/GIF 样本曾出现间歇少一帧；严格帧数检查会拒绝缺帧输出，根因尚未解决。
• 不支持任意剪映版本、任意效果组合、在线模板、资源下载、云端工程或账号权益获取。
• 高清黑白滤镜与橙色描边花字已退出支持范围；含这些效果的计划或旧快照会明确报错。
• 工程结构检查、原生播放、视觉一致性、主观听感与素材许可是不同的验收项目。

详细结果及已知问题见 验证状态。

python3 tools/check_package.py
python3 -m unittest discover -s tests -v

专项原生测试的本机素材与证据不随仓库分发；源码检查不能替代实际工程验收。

原创部分采用 个人学习和非商业使用许可；商业使用需取得作者书面授权。 第三方内容继续适用原许可证，详见 第三方声明。 本项目不是 MIT / Apache-2.0 整包授权，代码许可也不包含剪映集成授权、账号权益或素材许可。 分发边界见 分发范围。