timeline-master

SKILL.md

---
name: timeline-master
description: 检查和修复 FCPXML/FCPXMLD 的版本、媒体路径及时间码，为 DaVinci Resolve 准备时间线，处理 Resolve 调色交付回套 FCP 的媒体冲突和导入警告，并进行实际导入验收。按 XML 特性路由处理变速、多机位、调整片段、淡化/叠变与嵌套结构。
metadata:
  version: 0.1.3
---

# Timeline Master

以原始 XML 和真实媒体为基线，按用户请求修改新副本。先扫描，读取命中特性知识，再执行并验证。不要把“已生成”或 DTD 通过称作完美还原。

## 入口

运行环境：Python 3.10+、lxml、ffprobe。检查已安装依赖；缺少时使用用户环境的包管理方式安装。所有示例从本 Skill 根目录执行。

```sh
python3 scripts/timeline.py inspect '<source.fcpxmld>' --out '<analysis.json>' --probe
```

读取 analysis 中的 `features[].read`，只加载本任务相关的 reference。基本路径检查必读 media；timecode 改写必读 retime；Resolve 实机验收必读 `references/resolve-validation.md`。有多个 project 时报告全部，修改目标必须明确。

## FCPXML 修改

版本和路径修改使用 `prepare`，省略 `--timecode` 时不改源时间。`--version` 选择有 DTD 与目标证据的版本。无请求不得删除媒体或效果。

```sh
python3 scripts/timeline.py prepare '<source>' --out '<new-run-dir>' --version 1.12
```

当前 `--media-root` 负责找出候选；候选尚未核实身份时会阻止输出。核实后使用 `scripts/relink.py` 的显式 ID→路径映射生成新副本，再 prepare。

## Resolve 准备

确认真实文件与内嵌 timecode 后，必要时执行：

```sh
python3 scripts/timeline.py prepare '<source>' --out '<new-run-dir>' --version 1.12 --timecode --explicit-start --name '<new-timeline>'
python3 scripts/timeline.py validate '<new-run-dir>/output.fcpxml'
```

默认保留多机位、调整层、效果和嵌套结构，先进行目标应用基线测试。仅在确认原生结构不能导入且任务允许展开已选机位时，读取 multicam 模块并使用 `--multicam flatten`。展开会保留原结构在 sidecar，但不再具有原生切换机位能力。

用户明确允许忽略调整层时使用 `--adjustments ignore`，保存被移除节点。用户要求去掉已有调色以便重新调色时，读取 `references/color.md` 并用 `--color remove-known`，交付时必须通知调色效果已移除，同时说明已烘焙源媒体不受影响。以上都是可选策略，不能从“导入 Resolve”自动推断用户授权丢弃效果。

用户允许忽略音频淡化、音频滤镜、FCP 文本、Placeholder、交叉叠变/其他转场时，必读 `references/loss-policy.md`。使用可重复的 `--allow-omit` 记录许可并保存回套证据；该参数不强制删除节点，不改变素材位置。实际差异、许可差异和未验证项必须分开通知。

普通 XML 修复不要求打开 NLE；用户要求实机验收时，建立独立测试时间线。先检查脚本 API，不能连接时使用 Computer Use。App Store 版可能需要文件选择器授予媒体根目录访问；脚本返回 true 也必须核实输出文件真实存在。

开始 Resolve 实机操作前读 `references/troubleshooting.md`；它包含版本拒绝、离线、静帧/丢镜头、禁用多机位截短、隐藏日志窗口及回导假成功等已遇到问题的排查顺序。不要重复采用其中已验证失败的方案。

出现源帧整数接口差一帧，或 `s_In : trimmed` 断言时，读 `references/resolve-residuals.md`。对已定位的直接素材变速原点问题，可用 `--rebase-retime-origin`；禁止凭整数 getter 自动给素材加一帧。

## Resolve 调色交付 → FCP 回套

收到 Resolve 交付渲染的视频目录与 FCPXML/FCPXMLD，必读 `references/fcp-return.md`。先区分仅 XML 回导与绑定新渲染媒体的交付；两者不能混用证据。运行 `python3 scripts/delivery_audit.py '<delivery.fcpxmld>' --render-root '<render-directory>' --out '<new-audit.json>'` 检查同名输出冲突和实际媒体范围。该命令只做预检，不是回套转换器。

以原始 FCPXML、Resolve 入站候选、交付 XML 和真实渲染文件建立对应链。不能把不同渲染区间强行统一为同一文件时间码，不以旧原素材冒充调色结果。缺少完整调色采访时可依明确授权保留手工回套缺口；已渲染的采访片段可作为普通视频回套，但不能宣称可切换原生多机位。

预检通过后使用 `scripts/prepare_fcp_return.py` 生成新副本；具体参数与适用边界见回套路由。默认只修正实测渲染资源格式/时长；包裹展开、恢复未渲染原件时间域、恢复未烘焙变速都需显式参数及证据。不对所有时间字段按项目帧率取整。实机使用 FCP 新项目，观察警告并实际导出 XML，再用 `scripts/check_fcp_return.py` 核对直接视频引用及源映射。该检查不证明合成、效果或全片像素一致。

## 必须保持的语义

- 分离源时间、父容器局部时间、时间线时间；保持连接子片段的有效位置。
- 坐标换域同步处理相关 timeMap 和动画键；未支持的组合应标明，不能以猜测替换。
- 多机位分别读取 video/audio 的 angleID；不能以第一条角度代替当前选择。
- 调整片段影响其覆盖区间的下层合成画面，不能无条件复制到每个底层片段。
- 未授权不移除叠变；获准忽略也不得按转场 duration 移动后续素材或改变源入出点。复杂转场没有可靠坐标模型时保留原节点并报告，禁止盲删。
- 未解决媒体、错误引用或 DTD 失败阻止正式 XML 输出。效果未验收则明确标记 NOT_TESTED。

## 交付

正向准备提供 output.fcpxml、原件 source.fcpxml、analysis.json、sidecar.json、handoff.json、validation.json 和 report.md。回套提供 source.fcpxml、output.fcpxml、return-report.json、交付预检、实际 FCP 回导与 picture-roundtrip-check.json、用户可读差异报告。handoff 保存许可、原效果节点、转场父容器和前后事件清单；它不是通用自动回填器。实际验收另存导入日志、回导文件、关键画面和效果结果。核对原件→候选与候选→回导两段链路。`compare` 是保守事件检查器，复杂嵌套/变速会明确留下未解决项。

本版实际能力与限制见 `references/acceptance.md`。首版不声明通用三软件无损互转，也不把跨软件保留的未知参数当作已经正确渲染。

规范来源和 DTD 快照 provenance 见 `references/sources.md`。交付报告必须分别列出用户允许的损失与尚未验证的项目；单个案例的豁免不能成为默认行为。