cli-anything-kdenlive：用命令行与 JSON 项目模型驱动的 Kdenlive 状态化视频编辑

cli-anything-kdenlive 是 CLI-Anything 生态中面向视频剪辑的工具链，它把 Kdenlive/melt 的完整编辑能力封装成一套有状态（stateful）命令行接口：所有剪辑操作统一作用于一份 JSON 项目文件，最终通过 MLT XML 生成器输出可被 Kdenlive 直接打开、可被 melt 命令行工具处理的工程文件。读完本文，你将掌握从安装、命令分组、REPL 交互，到 JSON 项目结构、MLT XML 生成原理，再到面向 AI Agent 的自动化调用规范的完整实战方案。

概述：为什么需要一个"有状态"的 Kdenlive CLI

传统上，Kdenlive 的编辑能力集中在图形界面，而 melt 等命令行工具又偏向底层渲染。cli-anything-kdenlive 遵循与 Blender CLI harness 相同的设计模式，在二者之间架起一座桥：

• JSON 项目即真相：项目、媒体箱（bin）、轨道、时间线、滤镜、转场、标记（guide）全部以结构化 JSON 保存，天然适合脚本与 Agent 读写；
• MLT XML 作为输出契约：生成符合 Kdenlive Gen 5（doc version 1.1）规范的 MLT XML，既能交付给 Kdenlive 打开，也能交给 melt 做无头渲染（headless render）；
• 状态会话贯穿全程：CLI 进程内维护 Session 对象，支持最多 50 级 undo/redo 历史，让"批量修改再回滚"成为可能。

安装与环境要求

pip install cli-anything-kdenlive

安装前提：

• Python 3.10+；
• 系统中需安装 kdenlive（用于打开生成的 .kdenlive XML 文件）。

需要注意：根据 agent-harness 的 README，项目编辑本身并不需要 Kdenlive 或 melt 运行时——只有打开/渲染 XML 才需要它们。这意味着一套纯脚本环境也可以完成项目的创建、剪辑编排与 JSON 序列化。

快速上手：基本命令与 REPL 模式

基本命令

# 显示帮助
cli-anything-kdenlive --help

# 启动交互式 REPL
cli-anything-kdenlive

# 创建新项目
cli-anything-kdenlive project new -o project.json

# 以 JSON 输出（供 Agent 消费）
cli-anything-kdenlive --json project info -p project.json

REPL 模式

不带子命令直接调用即进入交互式 REPL 会话，支持 tab 补全与命令历史：

cli-anything-kdenlive
# 交互输入命令，输入 help 查看可用命令，quit/exit/q 退出

REPL 内部会把每一行输入用 shlex.split 拆分后重新调度到同一套 Click 命令组上（见 kdenlive_cli.py），因此REPL 与一次性命令拥有完全一致的语义。REPL 还集成了 ReplSkin 皮肤：显示横幅（banner）、项目名与"已修改"状态、彩色错误提示。

一条完整的一次性工作流（来源：agent-harness README Quick Start）

# 1. 创建项目
python3 -m cli.kdenlive_cli project new --name "MyVideo" --profile hd1080p30 -o project.json

# 2. 向媒体箱导入素材
python3 -m cli.kdenlive_cli --project project.json bin import /path/to/video.mp4 --name "Interview" -d 120.5
python3 -m cli.kdenlive_cli --project project.json bin import /path/to/music.mp3 --name "BGM" -d 180.0 --type audio

# 3. 添加轨道
python3 -m cli.kdenlive_cli --project project.json timeline add-track --type video
python3 -m cli.kdenlive_cli --project project.json timeline add-track --type audio

# 4. 在时间线上放置片段
python3 -m cli.kdenlive_cli --project project.json timeline add-clip 0 clip0 --position 0 --out 30.0
python3 -m cli.kdenlive_cli --project project.json timeline add-clip 1 clip1 --position 0 --out 60.0

# 5. 添加滤镜
python3 -m cli.kdenlive_cli --project project.json filter add 0 0 brightness -p level=1.3

# 6. 添加转场
python3 -m cli.kdenlive_cli --project project.json transition add dissolve 0 1 -d 2.0

# 7. 添加标记
python3 -m cli.kdenlive_cli --project project.json guide add 30.0 --label "Scene 2"

# 8. 导出为 Kdenlive XML
python3 -m cli.kdenlive_cli --project project.json export xml -o output.kdenlive

# 9. 保存项目
python3 -m cli.kdenlive_cli --project project.json project save

提示：SKILL 文档与 README 中分别演示了 cli-anything-kdenlive 与 python3 -m cli.kdenlive_cli 两种调用方式，前者面向已安装的包入口，后者面向源码目录直接运行，二者命令语义一致。

命令分组详解

SKILL 文档将全部命令划分为 8 个分组，下面结合源码逐组说明参数与底层行为。

Project：项目管理

命令	说明
new	创建新项目
open	打开既有项目文件
save	保存当前项目
info	显示项目信息
profiles	列出可用视频制式
json	打印原始项目 JSON

project new 的关键参数（源码见 project.py）：

• --name/-n：项目名，默认 untitled；
• --profile/-p：预定义制式名，例如 hd1080p30；
• --width/--height：自定义分辨率，默认 1920×1080；
• --fps-num/--fps-den：帧率分子/分母，默认 30/1；
• --output/-o：保存路径。

若同时传入制式名，制式表中的宽高、帧率、宽高比会覆盖手动参数；传入未知制式会直接抛出 ValueError。分辨率、帧率、宽高比均有正数校验。

内置视频制式（共 11 个）：hd1080p30、hd1080p25、hd1080p24、hd1080p60、hd720p30、hd720p25、hd720p60、4k30、4k60、sd_ntsc、sd_pal。其中 sd_ntsc 使用 30000/1001 的 NTSC 帧率、逐行扫描为假，sd_pal 为 720×576/25fps，其余均为 16:9 逐行制式。

project info 会汇总返回制式（分辨率、FPS、宽高比）与数量统计（媒体箱片段数、轨道数、时间线上片段数、转场数、标记数），并以 counts 字段结构化呈现。

Bin：媒体箱管理

命令	说明
import	导入素材片段到媒体箱
remove	从媒体箱移除片段
list	列出媒体箱全部片段
get	获取片段详细信息

bin import 参数：

• source：素材路径（位置参数）；
• --name/-n：片段名，缺省时从源文件名推导（去掉扩展名）；
• --duration/-d：时长（秒），默认 0.0；
• --type：video|audio|image|color|title，默认 video。

从 bin.py 可以看到两个自动化友好的细节：

1. 自动 ID 分配：新片段 ID 按 clip0、clip1……递增，保证唯一；
2. 同名去重：若同名片段已存在，自动追加序号后缀（Name.001、Name.002……），避免覆盖。

Timeline：时间线管理

命令	说明
add-track	添加轨道
remove-track	移除轨道
add-clip	向轨道放置片段
remove-clip	从轨道移除片段
trim	裁剪片段入/出点
split	在时间偏移处拆分片段
move	移动片段到新位置
list	列出全部轨道

核心参数与行为：

• timeline add-track：--name、--type video|audio、--mute、--hide、--locked。未命名时自动生成 V1/A1 之类名称；locked 轨道会拒绝后续所有修改操作（RuntimeError）；
• timeline add-clip <track_id> <clip_id>：--position（时间线位置，秒）、--in（素材入点）、--out（素材出点，缺省取媒体箱中的时长）；要求 out > in、位置非负；片段会按 position 自动排序；
• timeline split <track_id> <clip_index> <split_at>：拆分点必须严格落在 (0, 片段时长) 之间，返回两段（timeline.py），且原片段上的滤镜会深拷贝到两段结果中；
• timeline move：修改 position 后重新按 position 排序。

Filter：滤镜/效果管理

命令	说明
add	向片段添加滤镜
remove	移除滤镜
set	设置滤镜参数
list	列出片段上的滤镜
available	列出全部可用滤镜

滤镜由 FILTER_REGISTRY 统一注册，共 13 个，按类别划分：

滤镜名	mlt_service	类别	参数（类型/默认/范围）
brightness	brightness	color	level (float, 1.0, 0–5)
contrast	brightness	color	level (float, 1.0, 0–5)
saturation	avfilter.eq	color	saturation (float, 1.0, 0–3)
blur	boxblur	effect	hblur/vblur (int, 2, 0–100)
fade_in_video	brightness	transition	duration (float, 1.0, 0.01–60)
fade_out_video	brightness	transition	duration (float, 1.0, 0.01–60)
fade_in_audio	volume	transition	duration (float, 1.0, 0.01–60)
fade_out_audio	volume	transition	duration (float, 1.0, 0.01–60)
volume	volume	audio	gain (float, 1.0, 0–10)
crop	crop	effect	left/right/top/bottom (int, 0, 0–9999)
rotate	affine	effect	angle (float, 0.0, -360–360)
speed	timewarp	effect	speed (float, 1.0, 0.01–100)
chroma_key	frei0r.select0r	keying	color (str, "#00ff00")、variance (float, 0.15, 0–1)

使用方式：

# 添加滤镜，-p 可多次传入 key=value
cli-anything-kdenlive filter add 0 0 brightness -p level=1.3
cli-anything-kdenlive filter add 0 0 blur -p hblur=4 -p vblur=4

# 查看某片段上的滤镜
cli-anything-kdenlive filter list 0 0

# 查看可用滤镜（可按类别过滤）
cli-anything-kdenlive filter available --category color

# 修改第 0 个滤镜的第 1 个参数
cli-anything-kdenlive filter set 0 0 0 level 1.5

add 与 set 都会进行参数类型与范围校验（未知参数名、越界值直接报错），并把缺省参数自动补齐默认值——这保证了 JSON 项目始终处于合法状态（filters.py）。

Transition：转场管理

命令	说明
add	在轨道间添加转场
remove	移除转场
set	设置转场参数
list	列出全部转场

可用转场类型与参数（transitions.py）：

类型	mlt_service	参数
dissolve	luma	duration (0.01–60)、softness (0–1)
wipe	luma	duration、resource (str)、softness
slide	affine	duration、direction (str, 默认 left)
composite	composite	fill (0/1)、aligned (0/1)
affine	affine	distort (0/1)

transition add <type> <track_a> <track_b> 要求两个轨道均存在且不同，--position 默认 0.0、--duration 默认 1.0。set 额外允许直接修改 position 与 duration 这两个顶层字段。

Guide：标记管理

命令	说明
add	在指定秒数位置添加标记
remove	移除标记
list	列出全部标记

guide add <position> 支持 --label、--type default|chapter|segment、--comment。在 MLT XML 导出时，标记会转换成 kdenlive:sequenceproperties.guides 属性中的 JSON 数组（每项含 pos（帧）、comment、type）。

Export：导出与渲染

命令	说明
xml	生成 Kdenlive/MLT XML
presets	列出可用渲染预设

export xml -o output.kdenlive 将 JSON 项目渲染为 XML 字符串并写入文件；不带 -o 时直接打印到 stdout。

渲染预设（8 个）（export.py）：

预设名	说明	视频编码	音频编码	扩展名
h264_hq	H.264 高质量	libx264 (8000k)	aac (192k)	mp4
h264_fast	H.264 快速/草稿	libx264 (4000k)	aac (128k)	mp4
h265_hq	H.265/HEVC 高质量	libx265 (6000k)	aac (192k)	mp4
webm_vp9	WebM VP9	libvpx-vp9 (5000k)	libvorbis (192k)	webm
prores	Apple ProRes 422	prores_ks	pcm_s16le	mov
lossless	FFV1 无损	ffv1	flac	mkv
gif	动画 GIF	gif	无	gif
audio_only	纯音频 WAV	无	pcm_s16le	wav

Session：会话管理

命令	说明
status	显示会话状态
undo	撤销最近一次操作
redo	重做最近撤销的操作
history	显示撤销历史

状态管理：Session 与 50 级 Undo/Redo

SKILL 文档明确约定会话状态的三项能力，其底层实现在 session.py：

• Undo/Redo（最多 50 级）：Session.MAX_UNDO = 50。每次变更操作前调用 snapshot()，将当前项目深拷贝压入撤销栈并附带描述与时间戳；超过 50 条时弹出最旧条目。undo 会把当前状态压入重做栈再回退；任何新变更会清空重做栈；
• 项目持久化：save_session 以 _locked_save_json 落盘——写入时使用 fcntl.flock 独占锁并先截断再写，避免多进程并发写坏文件；保存成功后将 _modified 置回 False；
• 会话跟踪：status 返回 has_project、project_path、modified、undo_count、redo_count 与项目名。

SKILL 文档中"一次性命令结束自动保存"的行为由 kdenlive_cli.py 的 result_callback 实现：非 REPL、非 --dry-run 模式下，若会话存在项目且已被修改，命令返回后自动 save_session()。这意味着长链条的批量命令也可以逐条自动落盘，即使中途失败，已提交的修改不会丢失。

输出格式：人读与机读双通道

所有命令都支持两种输出：

• 人读模式（默认）：结构化表格、颜色、缩进文本（_print_dict/_print_list 递归打印）；
• 机读模式（--json）：输出带缩进的 JSON（json.dumps(indent=2, default=str)），供 Agent 直接解析。

# 人读输出
cli-anything-kdenlive project info -p project.json

# Agent 消费的 JSON 输出
cli-anything-kdenlive --json project info -p project.json

错误处理同样是双通道的（handle_error 装饰器，见 kdenlive_cli.py）：JSON 模式下错误以 {"error": ..., "type": ...} 输出，人读模式下写入 stderr；一次性命令出错时以非零退出码结束（REPL 内则不退出、仅报错）。

JSON 项目格式：一份"可编程"的工程文件

项目文件是 CLI 的数据中枢，结构如下（完整示例见 agent-harness README）：

{
  "version": "1.0",
  "name": "my_video",
  "profile": {
    "name": "hd1080p30", "width": 1920, "height": 1080,
    "fps_num": 30, "fps_den": 1, "progressive": true,
    "dar_num": 16, "dar_den": 9
  },
  "bin": [
    {"id": "clip0", "name": "Interview", "source": "/path/to/video.mp4",
     "duration": 120.5, "type": "video"}
  ],
  "tracks": [
    {"id": 0, "name": "V1", "type": "video", "mute": false, "hide": false,
     "locked": false, "clips": [
      {"clip_id": "clip0", "in": 0.0, "out": 30.0, "position": 0.0, "filters": []}
    ]}
  ],
  "transitions": [],
  "guides": [],
  "metadata": {}
}

要点解读：

• bin 中的片段是素材引用（source 路径 + 元数据），时间线 tracks[].clips[] 中的条目则是引用 + 编辑决策（clip_id 指回媒体箱、in/out 为素材入出点、position 为时间线位置、filters 为滤镜链）；
• metadata 由 project new 自动填充 created/modified 时间戳与 software: kdenlive-cli 1.0；
• open 会校验 version 与 profile 字段，不符合即判定为无效项目文件。

MLT XML 生成原理：从 JSON 到 Kdenlive/melt 可消费文档

导出链路为：export xml → export.generate_kdenlive_xml → build_mlt_xml（mlt_xml.py）。这份 XML 是 Kdenlive Gen 5（doc version 1.1）兼容的 MLT 文档，melt 可直接播放，Kdenlive 可直接打开。生成要点：

1. 制式映射：<profile> 元素写入分辨率、帧率、逐行标记、display/sample aspect ratio（SAR 由 DAR 与分辨率推导）以及 colorspace=709；
2. 时间码换算：秒与 HH:MM:SS.mmm 双向转换（seconds_to_timecode/timecode_to_seconds），帧数换算按 fps_num/fps_den 计算（mlt_xml.py）；
3. 轨道排序：音频轨在前、视频轨在后，使视频轨在 Kdenlive 中显示在上层；每个轨道由"chain（每素材一个）+ 双 playlist + 包裹 tractor"构成，音频轨自动附加禁用的 volume/panner/audiolevel 滤镜；
4. 自动转场：序列级 tractor 为每条音频轨生成 mix 转场、每条视频轨生成 qtblend 转场（internal_added=237 标记为内部元素）；用户自定义转场再按 a_track/b_track 追加；
5. 空档处理：playlist 中两个片段间的空隙自动生成 <blank length="帧数"/>，位置计算以 position 为准；
6. 媒体箱：main_bin playlist 收纳序列与全部素材 chain，最后以 tractor_project 作为 melt 播放的最终出口。

生成的 XML 适合三类下游消费：直接在 Kdenlive 中打开、用 melt 命令行处理、纳入更上层的自动化渲染流水线。

面向 AI Agent 的调用规范

SKILL 文档为程序化/Agent 调用给出了 5 条硬性规范，结合源码可进一步确认其依据：

1. 始终使用 --json：output() 在 _json_output 为真时输出结构化 JSON（kdenlive_cli.py）；
2. 检查返回码：0 为成功，非零为失败；错误路径由 handle_error 统一 sys.exit(1)；
3. 失败时解析 stderr：人读模式错误写入 stderr；JSON 模式错误带 type 字段（如 file_not_found、file_exists）；
4. 文件操作使用绝对路径：open_project/save_project 直接以传入路径读写（save_project 会自动创建父目录）；
5. 导出后校验产物存在：export xml -o 返回 {"path": ..., "size": ...}，Agent 应据此确认文件已写入。

此外可组合 --dry-run 做只读演练：全局选项会在命令返回时跳过自动保存（kdenlive_cli.py），适合在正式修改前验证命令链的正确性。

工程架构与测试覆盖

CLI 采用 Click + 模块化 core 的分层结构（架构图见 agent-harness README）：

kdenlive/agent-harness/cli_anything/kdenlive/
├── kdenlive_cli.py          # 主入口（Click + REPL）
├── core/
│   ├── project.py           # 项目 create/open/save/info/profiles
│   ├── bin.py               # 媒体箱管理
│   ├── timeline.py          # 轨道与片段放置
│   ├── filters.py           # 滤镜注册表与管理
│   ├── transitions.py       # 转场管理
│   ├── guides.py            # 标记管理
│   ├── export.py            # XML 生成与渲染预设
│   └── session.py           # 带 undo/redo 的会话
├── utils/
│   ├── mlt_xml.py           # MLT XML 生成、时间码换算
│   └── repl_skin.py         # REPL 界面皮肤
└── tests/
    ├── test_core.py         # 单元测试（60+）
    └── test_full_e2e.py     # 端到端测试（40+）

测试运行方式（在 agent-harness 目录下）：

python3 -m pytest cli/tests/ -v
python3 -m pytest cli/tests/test_core.py -v     # 仅单元测试
python3 -m pytest cli/tests/test_full_e2e.py -v # 仅端到端测试

从源码结构看，core/ 各模块保持"纯数据操作 + 校验"的单职责设计：CLI 层只负责参数解析、错误处理与输出格式化，所有业务逻辑都可在不启动命令行的情况下被测试直接调用，这也是 60+ 单元测试与 40+ E2E 测试得以覆盖完整编辑流程的结构基础。

进一步阅读

• 完整命令与快速开始：agent-harness README
• 本 SKILL 文档本体：skills/cli-anything-kdenlive/SKILL.md
• harness 方法论（cli-anything-plugin 插件）：cli-anything-plugin/HARNESS.md
• 测试覆盖说明：kdenlive/agent-harness/cli_anything/kdenlive/tests/TEST.md

当前版本：1.0.0