# 时间线交接与局部修订

已有上游工具的持久化响应文件时，用 `edit_apply.operationsRef: { path, sha256 }` 读取整条时间线。支持包含 `mediaOperation` 的响应、单个 timeline/trim、或仅含一个 operation 的数组。路径和哈希必须来自真实文件引用；工具不会猜测 `$speclipRef`，不接受只有 `previewMediaOperation` 的交付。文件哈希改变立即失败；所有素材与分析仍走原有校验。上游没有持久化工件时，原有 `operations` 输入继续可用。

给已有时间线附加字幕，无需重传 A-roll、B-roll 或 BGM：

```js
edit_apply {
  projectId: "demo", expectedRevision: 2, compact: true,
  timelinePatch: {
    subtitleTrack: { sourcePath: "out/reviewed.ass", format: "ass", mode: "burn-in", exportReceiptPath: ".subtitles/projects/demo/exports/<actual-id>.json" }
  },
  requiredTracks: { music: true, subtitles: true, overlayCount: 10 }
}
```

`timelinePatch` 只更新 musicTrack/subtitleTrack，省略的轨道保持不变，`null` 明确删除。必须是已有 timeline，并核验旧素材/分析/字幕哈希；不绕过并发版本锁。`operations`、`operationsRef`、`timelinePatch` 三选一。

`requiredTracks` 是当前交付明确需要的轨道，不由通用工具猜测。true 要求存在，false 要求不存在，overlayCount 要求准确数量；未提供的字段不限制。期望写入不可变修订，后续修订继承；显式传 `{}` 清除。故意无配乐的项目仍合法。

```js
edit_preflight { projectId: "demo", revision: 3 }
```

渲染前检查素材、分析、字幕回执的哈希及所需轨道，返回与 renderer 相同规划器的 `timelineTiming`、主时间线指纹和实际轨道摘要。检查通过只表示结构与文件一致；不表示字体、画面、听校或最终编码已通过。该 timing 是规划结果，不是 render receipt；pi-subtitles 的回执模式仍需真实渲染回执。临时传给 preflight 的 requiredTracks 只检查本次；要持续约束 render，应在 edit_apply 中保存。render 始终核验快照已保存的期望。

`edit_apply compact:true` 返回版本、轨道摘要，完整快照仍可由 `project_get` 获取。旧默认响应与完整 operations 保持兼容。

# 指定时刻补帧

```js
media_contact_sheet {
  path: "source.mp4", outputDir: "analysis/cut-evidence", precision: "high",
  timestampsSeconds: [10.2, 10.7, 10.9]
}
```

最多 300 个严格递增、唯一、毫秒精度的时刻，与 sampling 互斥。生成现有带源/图片哈希的 schemaVersion 2 清单；sampling.mode 为 timestamps，无额外自动抽帧。时刻须落在源和分析范围内；不会静默夹到视频尾部或补入其他时刻。时间戳表示请求的 seek 时刻，实际帧由解码器按视频帧时间解析，不宣称任意毫秒都有独立帧。查看切点两侧时选择相应帧间隔的两个时刻。补帧结果必须真实查看后才能用作视觉证据。