cut

技能：剪辑

此技能可根据素材库构建时间线。

1. 确认素材库并检查准备情况

开始剪辑前必须先有素材库。如果当前对话中已有素材库信息，就使用它；否则显示最近使用的素材库（ruby lib/buttercut/library.rb recent 5），让用户选择。

确认素材库名称后，检查素材库是否已就绪（所有素材都已处理）。

ruby lib/buttercut/library.rb <name> ready

退出代码 0 表示素材库已准备好进行剪辑（Library.ready? 是判断标准——不要在此重新推导判断条件）。如果退出代码非零，就停止。运行 ruby lib/buttercut/library.rb <name> summary，找出尚未处理完的片段，并告知用户素材库需要完成处理（引导他们使用 process-library 技能）。不要尝试绕过缺失的片段进行剪辑。

2. 确定任务类型

如果可以使用 AskUserQuestion 工具，就用它询问用户；否则按以下顺序以文本提问。

直接提问。用户开场请求中的“roughcut”是已训练过的词汇，并不代表用户已经确认选择——请列出选项，让他们选择。不要向用户解释为什么要问，也不要为重复提问道歉；问题本身就足够明确。

你可能会想直接继续，假定用户确实想要一个有故事结构的 roughcut，但他们只是在宽泛地使用这个词。你必须先向他们说明以下内容并提问，然后才能继续：

如果素材库已处理完毕，告知用户素材库已就绪，以及已处理的片段数量。然后询问他们想要哪种剪辑。同样，他们可能说过“roughcut”，但我们刚刚才教会他们这个词。必须提问。

示例说法：“素材库已就绪。所有素材均已处理。你想构建哪种剪辑？”

选项：

1. 场景 — 一个故事节拍，通常为 30–90 秒。
2. 精选片段 / 查找片段 — 按条件筛选的片段合集（最佳镜头、提及某个主题的片段、某个主题的 B-roll）。
3. 脚本剪辑 — 提供书面脚本，ButterCut 会让 Agent 查找素材并按脚本剪辑。
4. 自定义任务 — 其他任何需求。
5. Agent Roughcut — 完整的故事型剪辑。与 Agent 一起规划，然后让子 Agent 做出大部分决策。（实验性功能，可能消耗大量令牌）

Roughcut 流程更深入，因为 Agent 需要广泛探索素材库、阅读许多摘要、生成新的联系表，并在多个片段中塑造叙事。其他四种路径则由主线程直接与用户处理。

3. 构建剪辑（生成 YAML）

两种路径都会在 libraries/[library-name]/cuts/[slug]_[YYYYMMDD_HHMMSS].yaml 生成 YAML 文件。

剪辑可包含的内容

以下是与用户一起设计剪辑的快速选项菜单。完整字段列表和格式见 skills/cut/cut_yaml_schema.md。

• 裁剪后的视频 — 裁剪到入点和出点的片段。
• 静帧 — 持续指定时长的图像（无时间变化且无声音）。
• 静音 — 静音片段自身的音频（例如，使用配乐，或素材原声无法使用）。
• 时间线格式 — 覆盖输出帧率和分辨率；默认沿用第一个视频片段的格式。

单轨：片段按顺序播放，每个片段都保留自身音频。

Roughcut 路径

阅读 skills/cut/roughcut_path.md 并按其说明操作。

场景 / 精选片段 / 自定义 / 脚本路径

阅读 skills/cut/direct_path.md 并按其说明操作。

4. 确认素材可访问

导出时会读取剪辑引用的每个源文件，因此导出前请确认素材确实可用——自创建媒体库以来，硬盘可能已被拔出或重命名：

ruby lib/buttercut/library.rb <name> verify_media

每个片段都是 ok 吗？如果是，继续。如果有任何片段显示为 missing 或 phantom，请勿导出——阅读 skills/cut/missing_footage.md 并按其中说明重新连接素材。

规划和制作剪辑无需插入硬盘——只有导出时才需要。因此，此检查放在这里，就在导出之前，而非流程开始时：用户可以在硬盘未连接时调整剪辑，等准备好将时间线交给剪辑师时再重新连接。

5. 确定剪辑应用

现在剪辑 YAML 已创建，请为导出确定一个剪辑软件值：

1. 如果 library.yaml 中已设置 editor，则使用该值。
2. 否则，使用 libraries/settings.yaml 中的 editor，并将该值写回 library.yaml。
3. 如果两者都未设置，请询问用户（Final Cut Pro X / Adobe Premiere Pro / DaVinci Resolve），然后将选择保存到 library.yaml 和 libraries/settings.yaml。在 Windows 上，只提供 Premiere 和 Resolve——Final Cut 仅适用于 macOS。

6. 导出剪辑

使用第 5 步确定的剪辑软件和第 3 步生成的 YAML 运行导出：

# Final Cut Pro X
ruby lib/buttercut/export.rb --editor fcpx libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp].fcpxml

# Premiere Pro
ruby lib/buttercut/export.rb --editor premiere libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp].xml

# DaVinci Resolve
ruby lib/buttercut/export.rb --editor resolve libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp]_resolve.fcpxml

DaVinci Resolve 回退方案（临时）。 上面的 resolve 是默认选项，所有新剪辑都应使用它。以下两种情况会转而使用回退方案 --editor resolve_legacy——Resolve 在 FCPXML 之前使用的旧版 FCP7 XML 格式：

1. 导出本身发出警告。 当剪辑混用不同帧率时（例如，在 24p 时间线上使用 23.976 素材），resolve 导出会打印警告并列出帧率不匹配的片段：Resolve 无法从 FCPXML 关联这些片段，导入后会显示为离线。不要把该文件交给剪辑师。请立即使用 resolve_legacy 重新导出，并将 .xml 文件交给对方，同时用一句话说明原因。（包含多机位片段的剪辑不能使用回退方案——警告中会说明可选方案，请转告用户。）
2. 剪辑师反馈导入问题，且使用的是 Resolve FCPXML 导出文件——提出使用 resolve_legacy 重新导出。

ruby lib/buttercut/export.rb --editor resolve_legacy libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp]_resolve.xml

除此之外，请保持原样：不要主动提出，也不要默认使用此方案。

7. 将文件复制到桌面（如果已启用）

检查 libraries/settings.yaml 中的 save_to_desktop_after_export：

1. 如果该键的值为 true，将导出的 XML 复制到 ~/Desktop/，方便用户获取并导入剪辑软件。
2. 如果该键的值为 false，跳过此步骤。
3. 如果缺少该键，请询问用户是否希望将每次导出的副本放到桌面上，将其回答（true/false）保存到 libraries/settings.yaml，然后按设置执行。

cp [library xml path] ~/Desktop/

媒体库中的副本仍是规范文件；桌面副本只是为了方便而额外放置的文件。

（该命令在 Windows 的 Git Bash 中也能运行。如果 ~/Desktop 不存在——OneDrive 有时会重定位它——请使用 powershell -NoProfile -Command "[Environment]::GetFolderPath('Desktop')" 查找实际桌面路径，并将文件复制到那里。）

8. 备份媒体库

运行 backup-library 技能。此操作会为整个媒体库目录创建快照，以便在需要时恢复进度。

9. 报告结果

提供 XML 文件的路径——如果启用了桌面复制，则提供媒体库路径或桌面路径。对于 roughcuts，还要简要列出子 Agent 返回的编辑备注；小幅调整可以直接在 YAML 中完成，然后重新导出，无需再次调用子 Agent。不要提供 YAML 路径——它是内部构建产物，不是供用户打开的文件。

附上对应剪辑软件的一行导入说明：

• Final Cut Pro X： 在 Final Cut Pro 中选择“文件”→“导入”→“XML”打开剪辑
• Adobe Premiere Pro： 在 Premiere 中选择“文件”→“导入”，然后选择 XML 文件打开剪辑
• DaVinci Resolve： 在 Resolve 中选择“文件”→“导入”→“时间线”，然后选择导出的 .fcpxml 文件（如果使用了 resolve_legacy 回退方案，则选择 .xml 文件）

10. 在编辑器中打开（如果已启用）

检查 libraries/settings.yaml 中的 open_in_editor_after_export：

1. 如果该键的值为 true，直接在用户的编辑器中打开导出的文件。
2. 如果该键的值为 false，跳过此步骤。
3. 如果该键不存在，询问用户是否要自动打开导出的文件，将他们的回答（true/false）保存到 libraries/settings.yaml，然后据此操作。

在 macOS 上，使用 open -a 和正确的应用名称，以免 macOS 改用文本编辑器或 Xcode 打开：

# Final Cut Pro X
open -a "Final Cut Pro" [xml path]

# Adobe Premiere Pro
open -a "Adobe Premiere Pro" [xml path]

# DaVinci Resolve
open -a "DaVinci Resolve" [xml path]

如果已启用，请告知用户：“我已在 application_name 中为你打开文件。如果还需要其他帮助，请告诉我。”

在 Windows 上，不要尝试用 XML 启动编辑器。Premiere 和 Resolve 会导入这些文件，而不是打开它们；.xml 文件关联可能会让文件在浏览器或文本编辑器中打开。请改为在资源管理器中显示文件，并重复步骤 9 中的导入说明：

explorer /select,"$(cygpath -w "[xml path]")"

（资源管理器即使成功完成操作，也经常会以代码 1 退出，因此不要将其视为失败。）然后告知用户：“我已在资源管理器中选中导出的文件。请在 application_name 中使用上面的导入菜单将其导入。”

如果步骤 7 已将文件放在桌面副本路径中，请使用该路径；否则使用库路径。

指南

重要 请像与视频剪辑师交流那样与用户交谈，而不是像与程序员交流。隐藏技术细节。完全不要提 YAML。不要使用 em dash 或 en dash。

错误：“明白了，只要 3 秒的领奖台片段。我现在来编写 YAML。” 正确：“明白了。只要 3 秒的领奖台片段。我开始剪辑。”

错误：“我已经清楚掌握了全部 48 个片段。现在来编写 YAML。” 正确：“我已经了解了这场活动的整体情况。现在开始剪辑。”

注意：如果用户要求你执行 ButterCut 不原生支持其视频编辑器的操作，请阅读 misc-task 技能以获取指导。