final-cut-pro-cli 0.1.0

Agent-friendly CLI for Apple Final Cut Pro on macOS

final-cut-pro-cli

Agent-friendly CLI for Apple Final Cut Pro on macOS.

为 Final Cut Pro 提供一个 可被 Agent / 脚本调用 的命令行接口，让 Cursor / Claude Code / 自研 Agent 能完成剪辑准备链路（Library / Event / Project / Media / Timeline），并把结果打开到 FCP 中继续人工或后续自动化处理。

定位

• 目标用户：专业剪辑师（脚本化批处理）、自动化 / AI 剪辑工程师
• 核心场景：辅助专业剪辑工作流。把 FCP 的能力 原子化、可组合、可调用
• 不做什么：不内置 AI 能力（AI 在调用方）；不替代 FCP UI

平台限制

项	要求
操作系统	macOS only
Final Cut Pro	10.7+
FCPXML schema	1.11+
Python	3.10+

启动时会自动检测，不满足条件直接 PLATFORM_UNSUPPORTED / FCP_NOT_INSTALLED / FCP_VERSION_TOO_OLD 退出。

安装

pip install final-cut-pro-cli

命令面（v0.1 MVP）

Library 层（FCP 专属，dr-cli 无对应）

fcp library new <name> [--path <dir>]      # 创建 .fcpbundle 并注册
fcp library list                            # 列出已注册 Library
fcp library open <name|path>                # 在 FCP 中打开

Event 层（FCP 专属）

fcp event new <name> --library <ref>
fcp event list --library <ref>

Project 层（与 dr-cli 对齐）

fcp project new <name> --library <ref> --event <ref> [--resolution 1920x1080] [--fps 30]
fcp project list --library <ref> [--event <ref>]
fcp project info <name> --library <ref> --event <ref>

Media

fcp media import <video>... --library <ref> --event <ref>

Clip 编辑

fcp clip add --library <ref> --event <ref> --project <name> --asset <asset-id> [--duration <dur>]
fcp clip cut --library <ref> --event <ref> --project <name> --at <timecode>
fcp clip move --library <ref> --event <ref> --project <name> --clip <index> --to <timecode>
fcp clip trim --library <ref> --event <ref> --project <name> --clip <index> --start <tc> --end <tc>
fcp clip delete --library <ref> --event <ref> --project <name> --clip <index>

Subtitle（预留命令面）

fcp subtitle add <text> --at <tc> --duration <dur>
fcp subtitle import <srt-file>

v0.1 仅保留 subtitle 命令组占位，暂不写入字幕 / 标题内容。完整 subtitle/title 能力进入后续版本。

Export

fcp export submit <project-name> --preset <name> --output <path>

v0.1 说明：FCP 11.1.1 的 scripting dictionary 没有 export / share / render 命令。fcp export submit 保留与 dr-cli 对齐的命令面，但会返回结构化 export_unavailable 错误，不使用 UI scripting 伪装导出。MP4 导出暂由 FCP UI 手动完成，或在后续版本研究 Compressor / 外部渲染链路。export status 是后续 异步导出能力的预留命令，v0.1 不实现。

MCP server 模式

fcp mcp serve            # 启动 stdio MCP server，供 Cursor / Claude Code 调用

示例配置：

• Cursor: examples/cursor-mcp.json
• Claude Desktop: examples/claude-desktop-mcp.json

MCP tool 命名使用点号分组，例如 library.new、event.list、project.info、 clip.cut、export.submit。工具内部复用同一套 CLI 命令路径，并默认使用 --json，因此 MCP 返回值与 shell 调用保持一致。

全局选项

• --json — 所有命令支持结构化输出（错误也是 JSON）
• --verbose — 打印 FCPXML 详细变更和 AppleScript 调用

--library / --event / --project 是具体命令的作用域参数，不是全局参数。v0.1 不会读取 FCP 当前 active library，Agent 调用时应显式传入目标 Library / Event / Project。

与 davinci-resolve-cli 的对齐策略

命令层	是否对齐 dr-cli	说明
Library	❌ 不对齐	dr-cli 无 Library 概念，fcp-cli 独有
Event	❌ 不对齐	dr-cli 无 Event 概念，fcp-cli 独有
Project / Media / Clip / Export	✅ 尽量对齐	在 FCP 需要额外补充 Library / Event 作用域
Subtitle	🚧 预留	v0.1 仅保留命令组，占位对齐后续版本

详见 docs/dr-cli-alignment.md。

错误码

退出码分段：

范围	含义
0	成功
1-19	用户输入错误（参数非法、文件不存在）
20-39	FCP 状态错误（FCP 未运行、Library 未打开）
40-59	长时操作错误（AppleScript timeout、后续导出/渲染失败）
60+	内部错误（fcpxml 解析失败、AppleScript 异常）

详见 docs/error-codes.md。

架构

src-layout，与 davinci-resolve-cli 在目录布局、模块命名、命令组织上一一对应：

src/fcp/
├── cli.py              ← 入口 main_entry()，Typer
├── bootstrap.py        ← 平台/FCP 版本预检（macOS + 10.7+）
├── errors.py           ← 错误码段位 + FcpCliError
├── output.py           ← --json / rich 双输出
├── timecode.py         ← 时间码解析（与 dr-cli 同语义）
├── fcp_app.py          ← AppleScript 桥接（对应 dr-cli/resolve.py）
├── fcpxml/             ← FCPXML 读写（fcp 独有，主路径）
├── commands/
│   ├── library.py      ★ fcp 独有
│   ├── event.py        ★ fcp 独有
│   ├── project.py      ↔ dr-cli/project.py
│   ├── media.py        ↔ dr-cli/media.py
│   ├── timeline.py     ↔ dr-cli/timeline.py
│   ├── subtitle.py     ↔ (dr-cli v0.3 计划)
│   ├── export.py       ↔ dr-cli/render.py（FCP 叫 Export，参数 1:1）
│   ├── doctor.py       ↔ dr-cli/doctor.py
│   ├── completion.py   ↔ dr-cli/completion.py
│   └── mcp_cmd.py      ↔ dr-cli/mcp_cmd.py
├── jobs/               ← async 任务（预留给后续 export / MCP 长任务）
├── mcp/                ← MCP server 实现
└── schemas/            ← *.json，与 dr-cli/schemas/ 字段命名一致（camelCase）

设计约束

• FCPXML 主路径 — 所有内容编辑（library/event/project/media/clip/subtitle）走 FCPXML 文件操作，不依赖 FCP 运行
• AppleScript 仅做运行时触发 — v0.1 只实现 library open（标准 application open 命令）与 FCP library inspection；FCP scripting dictionary 当前没有 export/share 自动化能力
• 禁止 UI scripting — 不使用 System Events、坐标点击、key code、keystroke、AXUIElement；测试会扫描并拒绝这些片段

开发

# 安装开发依赖
pip install -e ".[dev]"

# 单元测试
pytest tests/fcpxml tests/cli

# 端到端测试（需要 macOS + FCP 10.7+）
FCP_E2E_OPEN_REAL_FCP=1 \
PYTHONPATH=/private/tmp/fcp-cli-pytest-stubs:src \
pytest tests/e2e/test_real_fcp_open.py -m integration -q

测试用例清单见 test-cases.md。 E2E 排障见 docs/e2e-troubleshooting.md。

路线图

• v0.1（M1，当前）— 剪辑准备闭环 MVP：library/event/project/media import/clip add/cut/library open + export_unavailable 明确降级 + MCP server
• v0.2 — 对齐 dr-cli v0.2：跨平台（FCPXML 操作部分）、recipe 模式、批量素材 glob/import 辅助
• v0.3 — 对齐 dr-cli v0.3：razor-cut 增强、MCP HTTP、subtitle 完整支持、config 文件

姊妹项目

• davinci-resolve-cli — 同团队，DaVinci Resolve 的 CLI（Project 层及以下命令面对齐）

License

MIT