cli-anything-shotcut 是一个有状态的视频编辑命令行界面，构建在 MLT XML 格式之上，面向需要在不使用图形界面的情况下创建和编辑 Shotcut 项目的 AI 智能体与高级用户。
用途 该工具用于通过命令行完成 Shotcut 视频项目的创建、编辑与渲染，适合自动化编辑流程、由 AI 智能体驱动的视频处理，以及需要脚本化重建时间线的场景。
安装与前置条件 该 CLI 作为 cli-anything-shotcut 包的一部分安装：
pip install cli-anything-shotcut
前置条件：
- Python 3.10+
- melt（MLT CLI）——渲染和播放所需
- ffmpeg / ffprobe——媒体探测所需
- 系统中必须已安装 shotcut
使用方式 基本命令：
显示帮助
cli-anything-shotcut --help
启动交互式 REPL 模式
cli-anything-shotcut
创建新项目
cli-anything-shotcut project new -o project.json
以 JSON 输出运行（供智能体使用）
cli-anything-shotcut --json project info -p project.json
REPL 模式：不带子命令调用时，CLI 进入支持撤销/重做的交互式 REPL 会话：
cli-anything-shotcut
或带项目：
cli-anything-shotcut --project my_project.mlt
工作流提示：始终先导入媒体以获取 clip_id，然后使用 add-clip 将其放置到时间线上。
主要能力 命令组覆盖以下方面：
项目与会话：new、open、save、info、xml、status、undo/redo。
媒体（两步模型）：media import <file> [--caption name] 导入文件到项目素材箱并返回 clip_id（如 clip0）；media 列出所有已导入媒体；probe <file> 分析媒体文件。
时间线：add-track、tracks、show、add-clip、clips、remove-clip、trim、split 等，支持绝对定位（--at）、修剪、分割、添加空白间隙、设置轨道名称、静音、隐藏等。
滤镜：list-filters、filter-info、add-filter、filters、remove-filter、set-filter、volume-envelope（关键帧音量）、duck（闪避包络）。
导出：presets 列出导出预设，render <output> [--preset name] 渲染为视频文件。
转场：list-available、info、add、remove、set、list。
合成：blend-modes、set-blend、get-blend、set-opacity、pip（画中画）。
会话：status、undo、redo、save、list。
预览：preview recipes、preview capture、preview latest、preview live start/push/status/stop，用于迭代编辑审阅。快速预览包通常包含 preview.mp4、若干采样帧、中点 hero.png 以及包含项目事实的 summary.json。支持轮询模式。查看器命令包括 cli-hub previews inspect/html/watch/open。
输出格式 所有命令支持双输出模式：
- 人类可读（默认）：表格、颜色、格式化文本
- 机器可读（--json 标志）：结构化 JSON，供智能体消费
会话状态 CLI 维护会话状态，包括：撤销/重做（最多 50 级历史）、项目持久化（以 JSON 保存/加载项目状态）、会话跟踪（跟踪修改与变更）。
适用场景
- 由 AI 智能体程序化创建和编辑 Shotcut 项目
- 脚本化、确定性地重建时间线（推荐使用绝对定位 --at 而非仅追加插入）
- 音频自动化，如关键帧音量包络与闪避
- 通过预览包或实时预览会话验证节奏、剪辑与滤镜效果
限制与注意事项
- 需要预先安装 shotcut、melt、ffmpeg/ffprobe 及 Python 3.10+。
- 时间线 add-clip 使用 --at 时，若目标时间落在空白区域会自动插入空白；CLI 会拒绝与现有剪辑重叠。
- 建议显式指定 --in 和 --out 值，以便后续绝对定位保持明确。
- 程序化使用时建议始终使用 --json 标志、检查返回码（0 成功，非零错误）、从 stderr 解析错误信息、使用绝对路径，并在导出后验证输出存在。
- 关键帧音量或闪避更改后应审阅最终渲染。
- 使用 preview live status --json 可在读取完整 trajectory.json 前了解最新发布情况。
- cli-hub previews ... 仅用于检查/打开现有预览包或实时会话。
更多信息 完整文档见包内 README.md；测试覆盖见 TEST.md；方法论见 cli-anything-plugin 中的 HARNESS.md。版本 1.0.0。