一、它是啥：把「结构化剪辑计划」变成可继续修改的多轨草稿
这条 brief 的核心一句话：把结构化的剪辑计划（一份 JSON）变成可继续修改的剪映多轨草稿，支持画中画、字幕、标题和本机导出，适合批量内容、Agent 辅助剪辑和工程交接。它不是让你再打开剪映 GUI 手拖轨道，而是把「剪辑意图」写成一份带微秒时间轴的 plan.json，工具链替你把它变成草稿/成品——这是它跟「手动剪辑」的本质区别。
先按数据红线实查主仓（mcncarl/jianying-headless，2026-10-04 查）：★2959 / fork 1950 / 约 10MB / Python 实现 / 09-27 还在推。fork 数（1950）相对星数偏高，说明有一批衍生/移植版——其中就有「根据逸尘大佬的 mac 版改的」Windows 移植仓，正对应 brief 里「苹果芯片 Mac 与剪映版本匹配」这句话。注意 license 是 NOASSERTION（非标准）、描述写「Private source preview」：brief 打了 #公开项目，但严格说它不是标准 OSS 协议，商用/二次分发前要自己看条款（见第六节边界）。
二、全链路机制：JSON 计划 → build 快照 → filter_complex → FFmpeg 渲染
它真正的「结构化」藏在这条链路上，不是营销词。我 clone 下来读了 engine/，跑通后产物能反推整个数据流：
① 计划（plan.json）：用微秒（start_us/duration_us/source_start_us）描述每条轨道每段从哪个源素材、取哪一段、放主轴什么时刻、什么速度/音量。画布写死宽高帧率。我实跑用的最小计划（双视频轨、各 2s 串接）长这样：
{
"schema": "jy14-headless-plan/v1",
"canvas": {"width": 1280, "height": 720, "fps": 30},
"tracks": [ {"type": "video", "name": "主视频", "segments": [
{"source": ".../src1.mp4", "start_us": 0, "duration_us": 2000000,
"source_start_us": 0, "source_duration_us": 2000000, "speed": 1, "volume": 0},
{"source": ".../src2.mp4", "start_us": 2000000, "duration_us": 2000000,
"source_start_us": 0, "source_duration_us": 2000000, "speed": 1, "volume": 0} ]} ]
}② build（build.json）：把计划「快照」成可校验的构建产物。每个源素材按 SHA256 指纹固化（files 字段，我那次两个源 489559/117356 字节各一条 sha256），再记 plan_sha256/timeline_sha256，并标 native_editable_draft:false（FFmpeg 路径不走剪映草稿）。这套指纹 + 校验（verify-build）就是它「可交接」的底气：计划改了没、源素材动了没，一眼能验，不用信「我记得改过」。
③ filter_complex：build 把微秒时间轴编译成一张 FFmpeg 滤镜图。我实跑那份（压缩成一行方便看结构）：
color=c=black:s=1280x720:r=30:d=4.0 # 黑底画布打底
[0:v]trim=start=0:duration=2,setpts=...,scale=1280:720,pad=...,setsar=1,setpts=+0/TB
[vcanvas][vr0_0]overlay=eof_action=pass:enable='between(t,0,2)' # 第 1 段：t∈[0,2)
[1:v]trim=start=0:duration=2,...setpts=+2/TB
[vp0_0][vr0_1]overlay=eof_action=pass:enable='between(t,2,4)' # 第 2 段：t∈[2,4)
...[vout]trim=duration=4,setpts=PTS-STARTPTS读这张图就懂了它的「精确到帧」在哪：每段先 trim 切源素材、setpts 把起点平移到主轴时刻、scale+pad 归一到画布，再用 overlay 的 enable='between(t,起,止)' 精确圈定「这一段只在 t∈[0,2) 显示」。这就是为什么画中画/叠字能做——本质都是 overlay 一个图层 + 用 enable 控时段，字幕/标题只是把叠加层换成 drawtext/ass 文本层而已。
④ 渲染：FFmpeg 按滤镜图渲出 render.mp4，并把完整命令行写进 result.json（ffmpeg_command 字段），可复现、可审计。
三、双后端：macOS 出「可编辑剪映草稿」，Windows 出「纯 FFmpeg 成品」
这是它最有取舍的一层，也是 brief「本机导出 / 苹果芯片 Mac」的出处。它其实有两条渲染路：
| 后端 | 产物 | 依赖 | 关键标志 |
|---|---|---|---|
| macOS native | 剪映原生可编辑草稿——能回到剪映里继续拖 | Apple Silicon Mac + 剪映 11.5.0（版本硬绑） | native_editable_draft:true |
| windows-ffmpeg（跨平台） | 直接 FFmpeg 渲出 MP4 成品 | 任意平台有 ffmpeg，不需要装剪映 | native_editable_draft:false |
取舍很清楚：要「出完还能回剪映精修」就 macOS native；要「批量/无人值守/CI 里直接出片」就 windows-ffmpeg。这条跨平台路正是 brief 说的「本机导出」的落地方式，也是我一节实跑押的点。
四、我把整条链路克隆下来真跑了一遍（ECS 宿主机）
它的卖点太依赖「跑起来」了，光读 README 验证不了。我在 2 核 ECS（Linux + ffmpeg）上绕开 macOS 那条，走 windows-ffmpeg 跨平台路径真跑：造两个真实源视频（testsrc2 彩色 + smptebars 色条，不同画面好看出切换）→ 写纯 video 双轨 plan → build → verify-build → export。结果全链路跑通：
build 成功：两个源按 SHA256 快照进 build 目录，native_editable_draft:false 确认走 FFmpeg 而非剪映草稿。verify-build 全绿。export 生成滤镜图后，我把项目产出的 filter_complex.txt 喂给带 libx264 的 FFmpeg，真渲出 render.mp4：1280×720 / 30fps / 120 帧 / 4.000s / 557KB / h264。抽 4 帧验真——前 2 帧是 testsrc2（彩色条纹）、后 2 帧是 smptebars（色条），画面在第 2 秒肉眼可见地从彩色切到色条，证明轨道串接是真渲染出来的、不是占位：
这次实跑还顺带挖出两个「只有真跑才撞得上」的环境坑（不影响项目正确性，是运行环境问题）：① ECS 发行版 ffmpeg 7.0.2 是 RPM 剥离了 GPL 编码器的版本，没有 libx264（只带 libopenh264/VA-API）→ 用 BtbN 静态 GPL 版补齐；② 该静态版已移除 -filter_complex_script，把项目生成的滤镜图 inline 到 -filter_complex 就能出片。项目源码本身用 resolve_tool 暴露了 JIANYING_FFMPEG/JIANYING_FFPROBE 环境变量覆盖点，正是为这种环境差异留的口子。截图跑完即销毁（删 /tmp 源 + 静态 ffmpeg 缓存），服务器不留垃圾。
五、跟同类比：什么时候用它，什么时候别用
| 方案 | 强 | 弱 / 何时别用 |
|---|---|---|
| 剪映 / CapCut（GUI） | 上手快、草稿可继续精修、字幕/模板生态全 | 手工拖轨，没法结构化批量、Agent 驱动、CI 无人出片 |
| MoviePy（Python） | 纯代码拼接渲染，Python 生态友好 | 没有「可继续修改的原生草稿」概念，也没有 plan/build/verify 的校验闭环，交接时说不清「到底改了什么」 |
| 裸 FFmpeg filter_complex | 零依赖、极限灵活 | 每段滤镜图手写，无微秒时间轴抽象、无 SHA 快照/verify，量大易错难维护 |
| Remotion（React 出片） | 声明式组件、可预览、代码即视频 | 产出的是 React 组件不是「剪映草稿」，要接剪映精修就断了 |
| Jianying Headless（本项） | 「结构化计划→可校验草稿/成品」是一等公民：微秒时间轴 + SHA 快照 + verify + 可继续改；macOS 出剪映草稿、跨平台出 MP4 两条路 | 核心可编辑草稿路绑 macOS 剪映 11.5.0；license 非标准；FFmpeg 路出的是成品不是可回剪映草稿 |
一句话定位：它卡的是「结构化剪辑计划 ↔ 可编辑剪映草稿」这个中间态。谁要「把一批结构化意图（批量选题/Agent 生成的剪辑指令）翻成可交接、可继续精修的草稿/成品」，它正对口；谁只是「快速剪一条」，直接用剪映 GUI 更快。
六、坑与边界（红线，别照搬旧文案）
① License 是 NOASSERTION、描述写「Private source preview」——brief 标 #公开项目，但严格讲它没挂标准 OSS 协议，商用/二次分发先读条款，别默认「公开=随便用」。
② 「可继续修改的剪映草稿」只有 macOS native 路径才有（native_editable_draft:true），且要 Apple Silicon + 剪映 11.5.0 版本匹配；我实跑的 windows-ffmpeg 路径出的是 MP4 成品，回剪映就不能再拖了。想「出完还能精修」就得上 Mac 那套。
③ FFmpeg 环境差异：发行版 ffmpeg 常缺 libx264，新版静态 ffmpeg 又去掉了 -filter_complex_script——得用 JIANYING_FFMPEG/JIANYING_FFPROBE 覆盖一个带 libx264 的构建，滤镜图必要时 inline。
④ build 强制绝对路径（我一开始传相对路径直接被拒「Plan path must be absolute」）——这是防目录穿越的设计，写 plan 时源素材路径务必给全。
⑤ 我实跑只验证了「纯 video 双轨串接」这条骨架（enable=between(t,…) 控时段的机制跑通了）；字幕/画中画的完整效果我没真跑（要真跑得配中文字体），它们的实现就是 overlay 换文本层，机制同构，但「效果」这条我如实不代证。
七、我的判断
适合：批量内容生产、Agent 辅助剪辑、工程交接这三类——共同点是「剪辑意图来自代码/上游、需要可校验可追溯、可能要回剪映精修」。把一段段「第几秒放什么、叠什么」写成 plan，build 出 SHA 快照草稿，交接时对方 verify 一遍就知道「计划没被动过、源素材没被换过」，这是它比「发个 mp4 过去」强一个身位的地方。
不适合：一次性手工精剪（用剪映 GUI 更快）；跑不了 macOS（就只能拿到 MP4 成品而非可编辑草稿）。license 非标准这点，商用前务必自己过一遍条款，别拿「公开」当「无约束」。