filmcraft

FilmCraft

使用用户指定的项目和序列，通过其结构化自动化接口操作 FilmCraft。

协议参考

构造调用前，请阅读 references/control-protocol.md 中的相关部分。这是未经修改的上游快照，于 2026-10-08 下载。

来源：FilmCraft 控制协议。上游 MIT 许可证包含在 references/LICENSE-MIT 中。

根据需要，在参考文档中搜索 Desktop control channel、Selection or explicit targets、Moving clips、Trim mode、Replace With Clip、Audio mixing、Essential Sound、Colour、Keyboard shortcuts 和 MCP。相对链接以 https://github.com/storytold/filmcraft/blob/main/docs/ 为基准解析。有关 MCP 参数架构、CLI 持久化以及导出进度/取消，请参阅上游 Agent 文档，第 1 部分。需要了解保存、恢复、重新链接和代理文件命令时，请参阅 project-files.md。如果已安装版本的行为有所不同，请检查已安装的命令注册表和工具架构，不要臆造参数。

选择会话

发现可用的 FilmCraft 工具和可执行文件，并复用合适的现有会话。用户打开的项目需要桌面桥接；无头会话是独立的进程内项目，无法编辑实时窗口。对于基于文件的无人值守操作，请使用无头 MCP 或 CLI。

桌面控制和桥接示例（请按需调整可执行文件路径和端口）：

filmcraft --control 9876
filmcraft-cli mcp --bridge 127.0.0.1:9876

无头 MCP：

filmcraft-cli mcp --project /absolute/path/project.fcproj

如果未指定 --project 或 --demo，无头 MCP 将以空项目启动。UI 工具需要桥接模式。创建或使用此技能不会安装 FilmCraft，也不会注册 MCP 服务；如果无法使用，请报告缺失的可执行文件或连接。

桌面 TCP 通道仅限环回连接，且未经身份验证；仅在使用期间启用。发送 UTF-8 JSON 对象，每行一个对象，其中包含字符串 method、可选的 params 和互不相同的请求 ID。读取回复并检查 ok。这是原始 TCP，不是 HTTP。无效请求、超过 4 MiB 的行或过多连接都可能导致连接关闭；发生错误后，请先重新连接再进行后续调用。不要仅因连接关闭就重放结果不确定的变更操作。

检查和编辑

使用 MCP doc_inspect 或 project_inspect，以及 sequence_inspect，识别项目项、当前活动序列、轨道、片段、播放头、所选内容和效果。在桌面端控制时，通过 engine.commands 查找检查命令；使用 ui.inspect 检查 UI 状态。

通过 MCP command_list 或桌面端 engine.commands 查找命令 ID、参数文档和当前启用状态。使用 MCP command_run {id, params} 或桌面端 engine.execute {command, params} 执行。若有明确的 clips / clip 或 items / item 目标，且能准确表达任务，请优先使用。命令注册表报告的是基于选择状态的启用情况：显示为禁用的命令仍可能接受显式目标，但其他前置条件仍然适用。

时间使用整数刻度：每秒 254,016,000,000 个刻度。如果有文档说明的 seconds、frame 或 timecode 替代字段，请使用这些字段；对于以刻度为单位的 time 字段，切勿用秒替代。解读帧数前，请先检查序列帧率。使用实际轨道 ID 或 V1、A2 等现有名称；不存在的轨道会导致错误。

移动片段前，请检查关联片段、锁定轨道和目标位置的重叠情况。timeline.move 可能覆盖目标位置的素材，也可能通过 insert 插入素材；默认情况下，关联片段会按相同偏移量移动。只有在确实要仅移动指定片段时，才使用 linked: false。检查返回的 moved ID 和移动后的时间信息，包括音频同步情况，以及素材是否从负序列时间偏移。

进行替换编辑时，请检查 short 和 sourceInClamped 结果：替换成功后，可能会在可用媒体范围之外保留最后一帧，也可能会截取保留的源入点。执行动态修剪操作时，请以秒为单位提供文档说明的时钟，并在继续之前完成或取消修剪手势。进行混音器自动化、闪避、LUT 或 HDR 操作时，请阅读音频或颜色章节；保留无关的序列设置。

对于对话框和手势，请检查 ui.elements，并优先使用返回的稳定元素 ID。对文档说明的对话框和视图字段使用 ui.set，并使用 ui.timeline.locate / ui.timeline.hit 定位时间线。布局更改后，请刷新检查结果。ui.type 的目标是当前聚焦的字段。只有 ui.focus 会明确占用用户的键盘焦点；仅在任务需要激活时调用它。

保存、导出和验证

打开、保存或导出之前，先发现已安装的文件命令及其参数。适用时，将可编辑项目保存为 .fcproj，并遵循指定的输出路径和格式。对于一次性 CLI 编辑，必须使用 --save 与 --project，或使用 --save-as <path> 才能持久保存；不要将仅存在于内存中的编辑报告为已保存的项目。

对于已知的命令序列，请使用批处理，并将 stop_on_error: true 设为默认值，除非有意在失败后继续。批处理失败后，先检查各步骤的结果和生成的项目，再决定后续操作。

对于 file.exportMedia，wait: true 会等待任务完成；若未设置，则保留返回的任务 ID，并轮询 jobs.list，直到任务完成或失败。需要时，使用 jobs.cancel 取消指定任务。通过 MCP 取消正在等待的导出会删除部分输出。依赖进度和取消功能之前，先确认已安装的相关支持。超时或未收到回复后，重试前先检查项目、任务状态和输出；若无法确认重试安全，则停止并报告结果不确定。

验证生成的序列状态，并检查有代表性的渲染帧或屏幕截图。MCP 的 render_frame / render_preview 可在无头模式下渲染，也可在桥接模式下捕获 Program 监视器画面，且不会更改播放头或所选内容。如果没有已呈现的帧，桌面截图可能在 10 秒后失败；请区分捕获失败与编辑失败。对于音频编辑，还应在可用时检查播放效果或导出的音频样本。报告已保存的路径、导出完成情况，以及重要警告，例如缺失媒体、源范围被截断或任务尚未完成。