剪映改草稿(jianying-draft-edit)
一句话定位:在副本上改剪映草稿(加素材/加音轨/移动裁剪/调音量/加文字/加轨道/撤销重做), 落盘后用落盘草稿的逐段字段差确认改动真的生效 —— 真草稿零改动。
调什么(动词)
| 动词 | 作用 |
|---|---|
draft_open |
打开草稿(默认开副本;allowReal 与 copy 冲突会被拒) |
draft_read |
读草稿语义结构(时间线/片段/素材)—— 拿 segmentId 等 id 用 |
draft_patch |
官方行为操作全集(18 域 / 199 个,桥全部放行;常用见下表,全量见 references/official-ops.md) |
draft_commit |
落盘(自动素材路径重定位 + 真草稿 sha 前后断言) |
render_frames |
用官方渲染器出帧(改前/改后各一次) |
verify_diff |
逐帧像素差(取全帧最大)判定"看得见" |
★ 官方行为操作(带命名空间,不是裸名)
★ 全集是 18 域 / 199 个 op,我们这道桥实测全部放行(0 个被拒) —— 以前"只有 27 个"是我们只试了 27 个。 全量清单 + 已知参数契约 + 三个坑:
references/official-ops.md。
| 组 | 操作 |
|---|---|
draft |
setCanvasSize · setDraftId |
track |
add · delete · mute |
segment |
move · scale · translate · rotate · updateLayout · split · delete · setTimeRange · innerReplace · setDescription |
video |
add · muteOn · muteOff · setVolume |
audio |
add · setVolume |
text |
add |
undoRedo |
undo · redo · canUndo · canRedo |
| 批量 | invokeBatch |
★ 已知必填项(缺了会被本地先拦下,不白跑一次官方调用):
video.add→path · audio.add→audioPath · text.add→content+startTime/duration · track.mute/track.delete→trackId ·
segment.move/setDescription→segmentId · segment.split→splitTime ·
segment.updateLayout→layout · segment.innerReplace→replacement
主工作流
# ① 开副本(拿 sessionId)
node ${PLUGIN_ROOT}/scripts/run-verb.mjs draft_open '{"draft":"<草稿库>\\<草稿名>","copy":true}'
# ② 读结构(拿 segmentId)
node ${PLUGIN_ROOT}/scripts/run-verb.mjs draft_read '{"path":"<草稿目录>/draft_content.json","root":"<草稿目录>"}'
# ★ 不要传 scope:后端不支持(分段读取未实现,传了会被 schema 拒)
# ③ 改(可多次;每次 baseRevision 会递增)
node ${PLUGIN_ROOT}/scripts/run-verb.mjs draft_patch '{"op":"video.setVolume","sessionId":"ve-session-N","params":{"segmentId":"<uuid>","volume":0.25}}'
# ④ 落盘(会做路径重定位 + 真草稿 sha 断言)
node ${PLUGIN_ROOT}/scripts/run-verb.mjs draft_commit '{"sessionId":"ve-session-N","realDraft":"<草稿库>\\<草稿名>"}' # ★ sessionId 必填(draft_open 给的)
# ⑤ 验收(★ 主判据 = 语义:落盘草稿的逐段字段差)
# 改前/改后各读一次明文草稿,再让 verify_diff 比"哪个字段变了"
# ★ 两份草稿必须是【裸草稿】——顶层就有 tracks/segments;
# draft_read 的响应外面还包了一层 draft ⇒ 直接把响应存成文件会读出 tracks:0(判据失效)
# ★ 两份草稿必须是【裸草稿】——顶层就有 tracks/segments;
# draft_read 的响应外面还包了一层 draft ⇒ 直接把响应存成文件会读出 tracks:0(判据失效)
node ${PLUGIN_ROOT}/scripts/run-verb.mjs draft_read '{"path":"<copy>/draft_content.json"}'
node ${PLUGIN_ROOT}/scripts/run-verb.mjs verify_diff '{
"checks": ["timeline"],
"beforeDraft": "<改前的明文草稿.json>", "afterDraft": "<改后的明文草稿.json>",
"expect": { "segmentFieldChanged": "volume" }
}'
★ 四条纪律(别破)
- 永远开副本 ——
draft_open的copy默认 true;allowReal=true必须同时copy=false(否则被拒)。 - 落盘后必须验证 ——
draft_commit会断言真草稿 sha 未变;"没报错"不等于"生效", 要用verify_diff看语义(哪个字段变了)。 - 判据用全帧最大 + 先量噪声底 —— 不用单帧抽样(单帧会假 FAIL/假 PASS);
★ 官方渲染器同态重渲染就有 MAD 48~123 的噪声 ⇒ 像素结论必须带
noiseDir校准,否则只当参考。 - ★ 优先用语义判据 —— "改动生效"最硬的证据是落盘草稿里那个字段真的变了
(如
volume0.99→0.2),它完全确定,而像素差不是。
常见诉求 → op
★ 机器可读版:
references/intent-map.json(21 条"人话 → 参数"映射) ★ 里面的参数名由机械审计按 schema 校验 ⇒ 拼错会被当场抓出来(不会静默失效)。
| 用户说 | op + params |
|---|---|
| 把这轨静音 | track.mute {trackId} |
| 把这轨删了 | track.delete {trackId} |
| 加一条视频 | video.add {path}(★ 参数名是 path,不是 source/filePath) |
| 加一条音频 | audio.add {audioPath}(★ 不是 source) |
| 加一段文字 | text.add {content}(★ 不是 text) |
| 加字幕(带时码) | text.add {content, startTime, duration}(★ 时码直接吃这两个键,官方按 fps 帧对齐) |
| 这段音量调到 25% | video.setVolume {segmentId, volume} |
| 这段静音 | video.muteOn {segmentId} |
| 把这段剪成两半 | segment.split {segmentId, splitTime}(★ 不是 splitTimeUs) |
| 删掉这段 | segment.delete {segmentId} |
| 挪到别的位置 | segment.move {segmentId, ...}(★ 需要先有 snapshot) |
| 改这段的时间范围 | segment.setTimeRange {segmentId, …} ⚠️ 参数名尚未确证:传 startUs/durationUs 官方回 accepted 但回读时码被清零 ⇒ 判据必须是"回读后字段真的变了" |
| 撤销上一步 | undoRedo.undo {} |
| 一次做多步 | ★ 官方没有批量 op(实测 199 个里没有 invokeBatch)⇒ 连着调多次 draft_patch(每次 baseRevision 会递增) |
★ 官方行为操作是带命名空间的(
segment.move不是move)—— 历史上"白名单 0/150"就是命名错造成的。 ★ 剪"中间一段"的正确链:split(t1)→split(前半, t0)→delete(中段); split 会让后面的段整体后移 ⇒ 多个区间必须从后往前处理。
失败处理
| 症状 | 原因 | 处理 |
|---|---|---|
缺少必填参数:path |
op 的必填项没给 | 查上表;参数放 params 里 |
edit/xxx 失败:segment_id_required |
官方原样错误 | 你的 segmentId 不存在/已被删 ⇒ 先 draft_read 重新拿 |
edit/xxx 失败:draft_snapshot_required |
这个 op 需要先有快照 | 先做一次别的 op,或用 draft.setDraftId |
管道连不上 |
剪映没在跑 | 启动剪映;edit 域必须连到活着的 VE 服务 |
真草稿被改动了 |
★ 危险信号 | 立刻停;查是不是误开了真草稿 |
verify_diff 的 timeline 判 FAIL |
语义判据没看到预期字段变化 | ① 确认 expect 的字段名对不对(如 volume)② 确认 beforeDraft/afterDraft 是改前/改后两份,不是同一份 |
verify_diff 的 visibility 判"不可见" |
可能是渲染噪声盖住了,也可能是真没生效 | 先加 noiseDir 校准;再用 timeline 维度的语义判据交叉验证 |
draft_read 返回 chars=0 |
读指定草稿时 root 没解析出来 | 传 root(或用 path 的上级目录);插件已自动补,但自定义路径时仍要核 |
★ 边界(不做什么)
| 不做 | 为什么 | 替代 |
|---|---|---|
| 改真草稿 | 官方零文件监听 ⇒ 写盘不保证 GUI 立刻可见;且我们的红线是"官方库只读" | 人工在 GUI 里导入/替换 |
| 写结构化调色(曲线/HSL/色轮) | 草稿侧字段名尚未确证,且官方预览渲染器本身也不认这些 | jianying-cut / make_film --grade 走我们自己的链出片 |
| 官方导出器出片 | 官方 CLI 被 −100007 / −100015 挡死,不绕 | jianying-cut |
| 画布节点操作(连线/卡片) | 画布是生成线,与"编辑已有草稿时间线"不同轴 | 不做 |
| 从零生成(AIGC 资产/单集成片) | processor 走沙箱 agent,取不到 | 不做 |
参考
- 官方 op 全集的实测清单:
references/official-ops.md(18 域 199 个、逐个打桥的结果、已确证参数契约、三个"accepted 但没生效"的坑) - 判据纪律:
references/verify-discipline.md - 踩坑清单:
references/pitfalls.md