Agent Harness把 GUI 应用改造成 Agent 可用有状态 CLI 的通用 SOP以 Shotcut/MLT 为例【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文基于 CLI-Anything 仓库中 HARNESS.md 这套标准操作规程SOP系统讲解如何把面向人类操作、依赖显示器和鼠标的开源 GUI 软件改造成可供编码智能体Claude Code、Codex 等直接调用的有状态 CLI。文章以 Shotcut 视频编辑器的完整落地实现SHOTCUT.md、shotcut_cli.py为佐证深入剖析渲染断层Rendering Gap、滤镜翻译、非整数帧率时间码精度、程序化输出验证等关键工程问题。读完本文你将掌握一套可复用的四阶段改造方法论以及一套改完必须验证的质量红线能够独立把任意 GUI 应用接入 Agent 工作流。一、Harness 的目标与适用对象HARNESS.md 开宗明义这是一套面向编码智能体的标准操作规程与工具包目的是让 AI Agent 能够操作为人类设计的软件而无需显示器与鼠标。其核心断言是大多数 GUI 应用都把呈现层与逻辑层分离这为 CLI 化改造提供了天然切口——找到底层引擎与原生数据格式就能绕开界面直接驱动软件。该 SOP 已在本仓库中落地为多个真实实现其中 Shotcut 一例最为完整CLI 直接读写.mltMLT XML工程文件驱动melt完成渲染并配套 110 项测试见 TEST.md。二、通用 SOP四阶段把任意 GUI 变成 Agent 可用 CLIPhase 1代码库分析Codebase Analysis改造前必须先摸清软件的内在结构五个步骤缺一不可识别后端引擎——多数 GUI 将表现与逻辑分离找到核心库/框架例如 Shotcut 的 MLT、GIMP 的 GEGL。引擎是 CLI 最终要驱动的对象。把 GUI 动作映射为 API 调用——每一个按钮点击、拖拽、菜单项背后都是一个函数调用需要系统化登记这些映射关系。Shotcut 的完整映射表见 SHOTCUT.md 的Command Map: GUI Action → CLI Command。识别数据模型——软件使用什么文件格式工程状态如何表示XML、JSON、二进制还是数据库Shotcut 的答案是.mltMLT XML这是整个 CLI 的支点。寻找现成 CLI 工具——很多后端自带命令行melt、ffmpeg、convert这些是现成的积木不必重复造轮子。盘点命令/撤销系统——如果应用有 undo/redo它大概率采用了命令模式Command Pattern这些命令本身就是你的 CLI 操作集。Phase 2CLI 架构设计选择交互模型有状态 REPL适合需要保持上下文的交互式会话子命令 CLI适合一次性脚本与管道操作两者兼有推荐同一套命令体系同时支撑两种模式。Shotcut CLI 即采用Click 子命令 REPL双模式python3 -m cli.shotcut_cli不带子命令时直接进入交互式 REPL见 shotcut_cli.py 中click.group(invoke_without_commandTrue)与ctx.invoke(repl)的实现。按应用逻辑域定义命令组工程管理new/open/save/close、核心操作应用的主业、导入导出文件 I/O 与格式转换、配置设置/偏好/配置文件、会话与状态管理undo/redo/history/status。Shotcut CLI 的命令组为project / timeline / filter / media / export / transition / composite / session / preview一一对应。设计状态模型哪些状态需要在命令间持久化打开的工程、光标位置、选区状态存于何处REPL 用内存、CLI 用文件如何序列化JSON 会话文件仓库中Session类session.py通过_snapshot()对工程根节点做快照入栈从而在任意时刻支持undo()/redo()并将会话状态持久化为 JSONsave_session_state/load_session_state/list_sessions。规划输出格式交互使用人类可读格式表格、颜色Agent 消费使用机器可读 JSON二者由--json开关控制。CLI 的全局output()函数shotcut_cli.py即实现JSON 模式输出json.dumps否则打印字典/列表的双通道--json --project p.mlt timeline clips 1即为典型调用。Phase 3实现顺序HARNESS.md 给出了明确的落地次序本仓库实现完全遵循先做数据层——XML/JSON 工程文件的解析与改写对应utils/mlt_xml.py加探测/信息命令——让 Agent 在修改前先能观察media probe、project info、timeline show、timeline tracks、filter list等加变更命令——每个逻辑操作一个命令add-clip、trim、split、add-filter、set-filter等加渲染/导出——输出管线见下文渲染断层加会话管理——状态持久化、undo/redo加 REPL——用交互模式包装全部子命令。Phase 4验证策略SOP 要求六层验证由轻到重单元测试合成数据、无外部依赖→ 真实文件 E2E捕捉单元测试漏掉的格式假设→ 多步工作流测试如剪 3 段、加效果、调色、导出的组合缺陷→输出验证见后文→ 往返测试CLI 建工程 → GUI 打开核对→Agent 测试让 AI Agent 仅用 CLI 完成真实任务。三、最关键的坑渲染断层The Rendering GapHARNESS.md 将渲染断层列为头号陷阱#1 pitfall。绝大多数 GUI 应用的效果滤镜/转场都是在渲染时由引擎实时计算的。当你直接操作工程文件时必须同时接管渲染——而朴素的渲染方案会静默丢弃所有效果。问题复现路径CLI 往工程文件里添加了滤镜/效果 → 渲染时如果图省事用简单工具如 ffmpeg concat demuxer→ 它直接读取原始媒体文件 →工程级效果全部被忽略→ 输出与输入几乎一样用户看不出任何改动发生。解决方案——滤镜翻译层filter translation layer按优先级三选一最佳方案调用应用原生渲染器。如 MLT 工程就用melt它直接读.mlt并应用全部效果零翻译成本备选方案构建翻译层把工程格式的效果转成渲染工具的原生语法如 MLT 滤镜 → ffmpeg-filter_complex兜底方案生成渲染脚本交给用户手动运行。渲染优先级恒为原生引擎 → 翻译后的滤镜图 → 脚本。从当前仓库源码看Shotcut CLI 的render()export.py采用了最优路线将当前工程写入临时.mlt以melt temp.mlt -consumer avformat:output直接渲染注释明确写道 No ffmpeg fallback — melt is the only render path because it natively reads MLT XML and handles all project featuresexport.py而 SHOTCUT.md 中则完整记录了 ffmpeg 翻译层的设计MLT→ffmpeg 滤镜映射表作为 melt 不可用时的降级路线并在 workflow_demo.py 中演示了手工构造-filter_complex的完整流程。四、滤镜翻译的四个经典陷阱当在两种格式间翻译效果MLT → ffmpeg时HARNESS.md 与 SHOTCUT.md 共同总结出以下易错点重复滤镜类型Duplicate filter typesffmpeg 不允许同一链中出现两个相同滤镜。若工程同时有brightness与saturation而二者都映射到 ffmpeg 的eq就必须合并为单个eqbrightnessX:saturationY。SHOTCUT.md 明确警告eqbrightness0.06,eqsaturation1.3会被拒绝必须写成eqbrightness0.06:saturation1.3。排序约束Ordering constraintsffmpeg 的concat滤镜要求交错流顺序[v0][a0][v1][a1][v2][a2]而非分组的[v0][v1][v2][a0][a1][a2]。若顺序写错报错信息 media type mismatch between filter output pad 极具迷惑性。workflow_demo.py 中的 concat 即严格采用[v0][v1][v2]concatn3:v1:a0与[a0][a1][a2]concatn3:v0:a1的分流写法。参数空间差异Parameter space differences效果参数常使用不同量纲。MLT 的 brightness1.15表示 15%而 ffmpegeqbrightness0.06基于 -1..1 刻度。每一组映射都必须显式记录换算公式。SHOTCUT.md 给出了已核验的映射表节选MLT Serviceffmpeg Filter参数翻译brightnesseqbrightnessXlevel: 1.0中性(level-1)×0.4frei0r.saturat0reqsaturationX同刻度1.0中性frei0r.hueshift0rhuehXshift×360 换算为角度sepiacolorchannelmixer...固定矩阵 rr0.393 rg0.769 rb0.189 等charcoaledgedetect,negate无参数frei0r.IIRblurboxblurXamount×10 得像素半径fadein-video/fadeout-videofadetin/out解析关键帧串得时长volumevolumeX同刻度1.0中性不可映射效果Unmappable effects部分效果在渲染工具中没有等价物应当优雅处理警告并跳过而不是崩溃。此外还要注意读取滤镜的作用层级滤镜可挂在producer剪辑级、playlist轨道级、tractor全局/总线上三个层级翻译时若只读一层效果必然缺失SHOTCUT.md 明确Track-level vs clip-level filters: Read filters from both... Missing one level missing effects.。五、非整数帧率下的时间码精度29.97fps即 30000/1001这类非整数帧率会导致累积舍入误差。HARNESS.md 给出三条铁律time.py 逐条落实浮点转帧必须用round()而非int()int(9000 * 29.97)截断会丢帧round()才得到正确结果。timecode_to_frames()time.py对HH:MM:SS.mmm、SS.mmm、HH:MM:SS:FF、纯帧号等全部输入统一走round(total_seconds * fps_num / fps_den)。时间码显示用整数算术帧 → 总毫秒用round(frames * fps_den * 1000 / fps_num)再以整数除法分解出时/分/秒/毫秒避免长时间跨度下中间浮点漂移。frames_to_timecode()time.py正是如此实现注释明确说明Use integer arithmetic to avoid floating-point drift。非整数帧率的往返测试接受 ±1 帧容差时间码→帧→时间码严格相等在数学上不可能测试断言应写成abs(a - b) 1。六、输出验证方法论不能只看退出码为 0HARNESS.md 反复强调一条纪律进程正常退出 ≠ 导出正确。必须用程序化手段验证输出详见 HARNESS.mdOutput Verification Methodology视频用 ffmpeg 逐帧探测——第 0 帧应近黑淡入起点、中间帧与源对比亮度/饱和度以确认调色生效、最后一帧应近黑淡出终点黑边letterbox/pillarbox处理跨分辨率对比像素时必须排除黑边像素——竖屏视频放进横屏画框约有 40% 黑像素会严重拉低均值。SHOTCUT.md 记录了实测案例834×1112 的竖屏源缩入 1920×1080验证时只取中间约 810px 进行分析音频检查首尾 RMS 电平验证淡入淡出并与源做频谱对比。该方法论在仓库中已被可复现地落地workflow_demo.py 的 8 步高光集锦流程产出了实测数据——亮度 15% 时内容像素均值由 70.8 → 85.514.7 确认、饱和度 30% 时色差 58.3 → 71.813.5 确认、淡入首帧均值 3.3近黑、淡出末帧 0.0纯黑、Sepia 呈现 RGB242217通道序见 SHOTCUT.md Verified Workflow。E2E 测试还专门包含test_render_imported_media_is_not_black、test_melt_can_load_subclip_project、test_melt_multiple_subclips_no_loop等输出正确性测试test_full_e2e.py。七、测试策略两套互补的测试套件SOP 规定双套测试体系本仓库完全照此执行总 144 项其中 TEST.md 记录了 110 项单元测试 100% 通过单元测试test_core.py合成数据、零外部依赖、每个函数隔离测试、快速确定性、适合 CI。覆盖 Timecode9、MLT XML4、Session7、Project6、Timeline17、Filters10、Media5、Export5、Integration2、Transitions16、Compositing16、Expanded Filters13。E2E 测试test_full_e2e.py真实媒体文件、跑通全管线格式解析、编解码、实际渲染捕捉单元测试覆盖不到的现实问题。SOP 特别列举了真实世界工作流测试场景清单多段剪辑YouTube 式裁剪、蒙太奇拼装大量短片段、画中画合成、调色流水线、音频混音播客式、高强度 undo/redo 压力、复杂工程保存/加载往返、迭代精修增、改、删、再加——E2E 套件中的 10 个真实工作流测试逐一对应YouTube edit、montage、multicam、podcast、picture-in-picture、color grading、undo-heavy、save/load complex、iterative refinement、timeline visualization。八、关键原则与硬性规则Key PrinciplesHARNESS.md直接操作原生格式——不要去重实现引擎解析并修改应用的原生工程文件MLT XML、PSD 等善用既有 CLI 工具——melt、ffmpeg、ffprobe作为子进程调用不要重新发明渲染但必须验证渲染确实应用了你的编辑——见渲染断层这是最常见也最静默的失败模式失败要响亮而清晰——Agent 需要无歧义的错误信息才能自我纠正尽可能幂等——同一命令执行两次应当安全提供内省能力——info、list、status命令对 Agent 理解当前状态至关重要JSON 输出模式——每个命令都应支持--json。Rules硬性规则每个cli/目录必须包含README.md说明依赖安装、如何运行、如何测试、基础用法示例——这是用户或 Agent 读到的第一份文档没有它 CLI 不可用每个导出/渲染函数必须经过程序化输出分析验证后才能标记为可用没有报错不充分注册表中的每个滤镜/效果必须有对应的渲染映射或明确标注仅工程内不渲染测试套件必须包含真实文件 E2E 测试——现实媒体的格式假设总是在破坏。九、落地实例Shotcut CLI 的目录结构与使用HARNESS.md 描绘了通用结构本仓库 Shotcut 的实际实现位于 shotcut/agent-harnessshotcut/agent-harness/ ├── HARNESS.md # 本文档——通用 SOP ├── SHOTCUT.md # Shotcut 专项分析与 SOP ├── TEST.md # 测试结果记录 ├── setup.py # 包安装脚本 ├── workflow_demo.py # 完整演示3 段高光集锦 ├── examples/ │ └── workflow_basic.sh # 基础工作流脚本 └── cli_anything/shotcut/ # 实际 CLI 实现 ├── README.md # HOW TO RUN——必备 ├── shotcut_cli.py # 主入口Click REPL1630 行 ├── core/ # 按域拆分project/timeline/filters/media/export/session/transitions/compositing/preview ├── utils/ # mlt_xml.py、time.py、melt_backend.py、preview_bundle.py、repl_skin.py ├── skills/SKILL.md # Agent 技能说明 └── tests/ # test_core.py test_full_e2e.py安装与运行详见 cli_anything/shotcut/README.md依赖 Python 3.10、click、melt渲染必需、ffmpeg/ffprobe探测与导出REPL 可选prompt_toolkit。系统工具可按发行版安装pacman -S melt ffmpeg/apt install melt ffmpeg/brew install mlt ffmpeg。典型调用一次性命令与 REPL 两种形态# 新建工程默认 profile: hd1080p30 python3 -m cli.shotcut_cli project new --profile hd1080p30 -o my_project.mlt # 打开工程并查看信息Agent 友好--json python3 -m cli.shotcut_cli --json --project my_project.mlt project info # 进入交互式 REPL python3 -m cli.shotcut_cli repl --project my_project.mltREPL 内示例会话README.md new hd1080p30 add-track video Main media import intro.mp4 → Imported intro.mp4 as clip0 add-clip clip0 1 00:00:00.000 00:00:05.000 add-filter brightness --track 1 --clip 0 level1.3 show save render output.mp4 --preset h264-high可用 profilehd1080p30、hd1080p60、hd1080p24、hd720p30、4k30、4k60、sd480p。可用转场dissolve、wipe-left/right/down/up、bar-horizontal/vertical、diagonal、clock、iris-circle、crossfade。可用混合模式 17 种normal、add、multiply、screen、overlay等。CLI 还提供--dry-run不落盘试运行、--session id会话恢复、命令后自动保存_auto_save_callback见 shotcut_cli.py等增强能力。导出预设定义于 export.py共 10 个源码实际参数值defaultH.264 CRF 21 AAC 384kMP4、h264-highCRF 15 preset slow、h264-fastCRF 23 ultrafast、h265libx265 CRF 23、webm-vp9libvpx-vp9 CRF 30WebM、proresprores_ks profile 2MOV、gif、audio-mp3320k、audio-wavpcm_s16le、png-sequence。渲染命令支持--width/--height覆盖与--overwrite。滤镜注册表定义于 filters.pyCLI 名 → MLT service → 参数规格类型/默认值/取值范围一一登记例如brightnesslevel0.0–2.01.0正常、volumelevel0.0–5.0另含 gain dB、blurfrei0r.IIRbluramount 0.0–1.0、cropleft/right/top/bottom 像素、saturationfrei0r.saturat0r0.0–3.0、huefrei0r.hueshift0rshift 0.0–1.0整圆、sepiau/v 色度值、textdynamictextargument/size/fgcolour/family/halign/valign、以及用关键帧串timeval;timeval实现的淡入淡出系列。十、把同一套 SOP 推广到其他软件HARNESS.md 用一张对照表证明该 SOP 的普适性——模式永远是找到数据格式、找到引擎、写一个操作前者并驱动后者的 CLI最后验证输出。软件后端原生格式现有 CLI渲染断层风险ShotcutMLT.mlt (XML)melt, ffmpeg高——必须翻译滤镜GIMPGEGL.xcfgimp -i (script-fu)中——GEGL 有 CLIBlenderbpy.blendblender --python低——bpy 原生渲染Inkscapelibrsvg.svg (XML)inkscape --actions低——SVG 即格式AudacityPortAudio.aup3 (SQLite)—高——无 CLI 渲染器LibreOfficeUNO.odt (XMLZIP)soffice --macro低——UNO API 可用OBS Studiolibobsscene.jsonobs-websocket中——仅实时KdenliveMLT.kdenlive (XML)melt高——同 Shotcut渲染断层风险列标识朴素导出方案静默丢效果的概率高风险意味着几乎必然需要滤镜翻译层。本仓库中 Shotcut、Kdenlive、GIMP 等目录正是这一 SOP 的规模化实证。结语HARNESS.md 提供的方法论可以浓缩为一句话不重实现引擎直接操作原生数据格式用现成引擎渲染然后用程序化分析验证输出。四阶段 SOP分析→设计→实现→验证解决了如何把 GUI 变 CLI的架构问题渲染断层与滤镜翻译解决了改完能否真的生效的正确性问题时间码精度与双套测试解决了长期可靠性与 Agent 自纠错的质量问题。任何想要让开源软件Agent-Native的开发者都可以把这份 SOP 作为起点并对照 SHOTCUT.md 与 export.py 等真实实现逐项核对让 Agent 真正无屏操作你的软件。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Harness：把 GUI 应用改造成 Agent 可用有状态 CLI 的通用 SOP（以 Shotcut/MLT 为例）
Agent Harness把 GUI 应用改造成 Agent 可用有状态 CLI 的通用 SOP以 Shotcut/MLT 为例【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文基于 CLI-Anything 仓库中 HARNESS.md 这套标准操作规程SOP系统讲解如何把面向人类操作、依赖显示器和鼠标的开源 GUI 软件改造成可供编码智能体Claude Code、Codex 等直接调用的有状态 CLI。文章以 Shotcut 视频编辑器的完整落地实现SHOTCUT.md、shotcut_cli.py为佐证深入剖析渲染断层Rendering Gap、滤镜翻译、非整数帧率时间码精度、程序化输出验证等关键工程问题。读完本文你将掌握一套可复用的四阶段改造方法论以及一套改完必须验证的质量红线能够独立把任意 GUI 应用接入 Agent 工作流。一、Harness 的目标与适用对象HARNESS.md 开宗明义这是一套面向编码智能体的标准操作规程与工具包目的是让 AI Agent 能够操作为人类设计的软件而无需显示器与鼠标。其核心断言是大多数 GUI 应用都把呈现层与逻辑层分离这为 CLI 化改造提供了天然切口——找到底层引擎与原生数据格式就能绕开界面直接驱动软件。该 SOP 已在本仓库中落地为多个真实实现其中 Shotcut 一例最为完整CLI 直接读写.mltMLT XML工程文件驱动melt完成渲染并配套 110 项测试见 TEST.md。二、通用 SOP四阶段把任意 GUI 变成 Agent 可用 CLIPhase 1代码库分析Codebase Analysis改造前必须先摸清软件的内在结构五个步骤缺一不可识别后端引擎——多数 GUI 将表现与逻辑分离找到核心库/框架例如 Shotcut 的 MLT、GIMP 的 GEGL。引擎是 CLI 最终要驱动的对象。把 GUI 动作映射为 API 调用——每一个按钮点击、拖拽、菜单项背后都是一个函数调用需要系统化登记这些映射关系。Shotcut 的完整映射表见 SHOTCUT.md 的Command Map: GUI Action → CLI Command。识别数据模型——软件使用什么文件格式工程状态如何表示XML、JSON、二进制还是数据库Shotcut 的答案是.mltMLT XML这是整个 CLI 的支点。寻找现成 CLI 工具——很多后端自带命令行melt、ffmpeg、convert这些是现成的积木不必重复造轮子。盘点命令/撤销系统——如果应用有 undo/redo它大概率采用了命令模式Command Pattern这些命令本身就是你的 CLI 操作集。Phase 2CLI 架构设计选择交互模型有状态 REPL适合需要保持上下文的交互式会话子命令 CLI适合一次性脚本与管道操作两者兼有推荐同一套命令体系同时支撑两种模式。Shotcut CLI 即采用Click 子命令 REPL双模式python3 -m cli.shotcut_cli不带子命令时直接进入交互式 REPL见 shotcut_cli.py 中click.group(invoke_without_commandTrue)与ctx.invoke(repl)的实现。按应用逻辑域定义命令组工程管理new/open/save/close、核心操作应用的主业、导入导出文件 I/O 与格式转换、配置设置/偏好/配置文件、会话与状态管理undo/redo/history/status。Shotcut CLI 的命令组为project / timeline / filter / media / export / transition / composite / session / preview一一对应。设计状态模型哪些状态需要在命令间持久化打开的工程、光标位置、选区状态存于何处REPL 用内存、CLI 用文件如何序列化JSON 会话文件仓库中Session类session.py通过_snapshot()对工程根节点做快照入栈从而在任意时刻支持undo()/redo()并将会话状态持久化为 JSONsave_session_state/load_session_state/list_sessions。规划输出格式交互使用人类可读格式表格、颜色Agent 消费使用机器可读 JSON二者由--json开关控制。CLI 的全局output()函数shotcut_cli.py即实现JSON 模式输出json.dumps否则打印字典/列表的双通道--json --project p.mlt timeline clips 1即为典型调用。Phase 3实现顺序HARNESS.md 给出了明确的落地次序本仓库实现完全遵循先做数据层——XML/JSON 工程文件的解析与改写对应utils/mlt_xml.py加探测/信息命令——让 Agent 在修改前先能观察media probe、project info、timeline show、timeline tracks、filter list等加变更命令——每个逻辑操作一个命令add-clip、trim、split、add-filter、set-filter等加渲染/导出——输出管线见下文渲染断层加会话管理——状态持久化、undo/redo加 REPL——用交互模式包装全部子命令。Phase 4验证策略SOP 要求六层验证由轻到重单元测试合成数据、无外部依赖→ 真实文件 E2E捕捉单元测试漏掉的格式假设→ 多步工作流测试如剪 3 段、加效果、调色、导出的组合缺陷→输出验证见后文→ 往返测试CLI 建工程 → GUI 打开核对→Agent 测试让 AI Agent 仅用 CLI 完成真实任务。三、最关键的坑渲染断层The Rendering GapHARNESS.md 将渲染断层列为头号陷阱#1 pitfall。绝大多数 GUI 应用的效果滤镜/转场都是在渲染时由引擎实时计算的。当你直接操作工程文件时必须同时接管渲染——而朴素的渲染方案会静默丢弃所有效果。问题复现路径CLI 往工程文件里添加了滤镜/效果 → 渲染时如果图省事用简单工具如 ffmpeg concat demuxer→ 它直接读取原始媒体文件 →工程级效果全部被忽略→ 输出与输入几乎一样用户看不出任何改动发生。解决方案——滤镜翻译层filter translation layer按优先级三选一最佳方案调用应用原生渲染器。如 MLT 工程就用melt它直接读.mlt并应用全部效果零翻译成本备选方案构建翻译层把工程格式的效果转成渲染工具的原生语法如 MLT 滤镜 → ffmpeg-filter_complex兜底方案生成渲染脚本交给用户手动运行。渲染优先级恒为原生引擎 → 翻译后的滤镜图 → 脚本。从当前仓库源码看Shotcut CLI 的render()export.py采用了最优路线将当前工程写入临时.mlt以melt temp.mlt -consumer avformat:output直接渲染注释明确写道 No ffmpeg fallback — melt is the only render path because it natively reads MLT XML and handles all project featuresexport.py而 SHOTCUT.md 中则完整记录了 ffmpeg 翻译层的设计MLT→ffmpeg 滤镜映射表作为 melt 不可用时的降级路线并在 workflow_demo.py 中演示了手工构造-filter_complex的完整流程。四、滤镜翻译的四个经典陷阱当在两种格式间翻译效果MLT → ffmpeg时HARNESS.md 与 SHOTCUT.md 共同总结出以下易错点重复滤镜类型Duplicate filter typesffmpeg 不允许同一链中出现两个相同滤镜。若工程同时有brightness与saturation而二者都映射到 ffmpeg 的eq就必须合并为单个eqbrightnessX:saturationY。SHOTCUT.md 明确警告eqbrightness0.06,eqsaturation1.3会被拒绝必须写成eqbrightness0.06:saturation1.3。排序约束Ordering constraintsffmpeg 的concat滤镜要求交错流顺序[v0][a0][v1][a1][v2][a2]而非分组的[v0][v1][v2][a0][a1][a2]。若顺序写错报错信息 media type mismatch between filter output pad 极具迷惑性。workflow_demo.py 中的 concat 即严格采用[v0][v1][v2]concatn3:v1:a0与[a0][a1][a2]concatn3:v0:a1的分流写法。参数空间差异Parameter space differences效果参数常使用不同量纲。MLT 的 brightness1.15表示 15%而 ffmpegeqbrightness0.06基于 -1..1 刻度。每一组映射都必须显式记录换算公式。SHOTCUT.md 给出了已核验的映射表节选MLT Serviceffmpeg Filter参数翻译brightnesseqbrightnessXlevel: 1.0中性(level-1)×0.4frei0r.saturat0reqsaturationX同刻度1.0中性frei0r.hueshift0rhuehXshift×360 换算为角度sepiacolorchannelmixer...固定矩阵 rr0.393 rg0.769 rb0.189 等charcoaledgedetect,negate无参数frei0r.IIRblurboxblurXamount×10 得像素半径fadein-video/fadeout-videofadetin/out解析关键帧串得时长volumevolumeX同刻度1.0中性不可映射效果Unmappable effects部分效果在渲染工具中没有等价物应当优雅处理警告并跳过而不是崩溃。此外还要注意读取滤镜的作用层级滤镜可挂在producer剪辑级、playlist轨道级、tractor全局/总线上三个层级翻译时若只读一层效果必然缺失SHOTCUT.md 明确Track-level vs clip-level filters: Read filters from both... Missing one level missing effects.。五、非整数帧率下的时间码精度29.97fps即 30000/1001这类非整数帧率会导致累积舍入误差。HARNESS.md 给出三条铁律time.py 逐条落实浮点转帧必须用round()而非int()int(9000 * 29.97)截断会丢帧round()才得到正确结果。timecode_to_frames()time.py对HH:MM:SS.mmm、SS.mmm、HH:MM:SS:FF、纯帧号等全部输入统一走round(total_seconds * fps_num / fps_den)。时间码显示用整数算术帧 → 总毫秒用round(frames * fps_den * 1000 / fps_num)再以整数除法分解出时/分/秒/毫秒避免长时间跨度下中间浮点漂移。frames_to_timecode()time.py正是如此实现注释明确说明Use integer arithmetic to avoid floating-point drift。非整数帧率的往返测试接受 ±1 帧容差时间码→帧→时间码严格相等在数学上不可能测试断言应写成abs(a - b) 1。六、输出验证方法论不能只看退出码为 0HARNESS.md 反复强调一条纪律进程正常退出 ≠ 导出正确。必须用程序化手段验证输出详见 HARNESS.mdOutput Verification Methodology视频用 ffmpeg 逐帧探测——第 0 帧应近黑淡入起点、中间帧与源对比亮度/饱和度以确认调色生效、最后一帧应近黑淡出终点黑边letterbox/pillarbox处理跨分辨率对比像素时必须排除黑边像素——竖屏视频放进横屏画框约有 40% 黑像素会严重拉低均值。SHOTCUT.md 记录了实测案例834×1112 的竖屏源缩入 1920×1080验证时只取中间约 810px 进行分析音频检查首尾 RMS 电平验证淡入淡出并与源做频谱对比。该方法论在仓库中已被可复现地落地workflow_demo.py 的 8 步高光集锦流程产出了实测数据——亮度 15% 时内容像素均值由 70.8 → 85.514.7 确认、饱和度 30% 时色差 58.3 → 71.813.5 确认、淡入首帧均值 3.3近黑、淡出末帧 0.0纯黑、Sepia 呈现 RGB242217通道序见 SHOTCUT.md Verified Workflow。E2E 测试还专门包含test_render_imported_media_is_not_black、test_melt_can_load_subclip_project、test_melt_multiple_subclips_no_loop等输出正确性测试test_full_e2e.py。七、测试策略两套互补的测试套件SOP 规定双套测试体系本仓库完全照此执行总 144 项其中 TEST.md 记录了 110 项单元测试 100% 通过单元测试test_core.py合成数据、零外部依赖、每个函数隔离测试、快速确定性、适合 CI。覆盖 Timecode9、MLT XML4、Session7、Project6、Timeline17、Filters10、Media5、Export5、Integration2、Transitions16、Compositing16、Expanded Filters13。E2E 测试test_full_e2e.py真实媒体文件、跑通全管线格式解析、编解码、实际渲染捕捉单元测试覆盖不到的现实问题。SOP 特别列举了真实世界工作流测试场景清单多段剪辑YouTube 式裁剪、蒙太奇拼装大量短片段、画中画合成、调色流水线、音频混音播客式、高强度 undo/redo 压力、复杂工程保存/加载往返、迭代精修增、改、删、再加——E2E 套件中的 10 个真实工作流测试逐一对应YouTube edit、montage、multicam、podcast、picture-in-picture、color grading、undo-heavy、save/load complex、iterative refinement、timeline visualization。八、关键原则与硬性规则Key PrinciplesHARNESS.md直接操作原生格式——不要去重实现引擎解析并修改应用的原生工程文件MLT XML、PSD 等善用既有 CLI 工具——melt、ffmpeg、ffprobe作为子进程调用不要重新发明渲染但必须验证渲染确实应用了你的编辑——见渲染断层这是最常见也最静默的失败模式失败要响亮而清晰——Agent 需要无歧义的错误信息才能自我纠正尽可能幂等——同一命令执行两次应当安全提供内省能力——info、list、status命令对 Agent 理解当前状态至关重要JSON 输出模式——每个命令都应支持--json。Rules硬性规则每个cli/目录必须包含README.md说明依赖安装、如何运行、如何测试、基础用法示例——这是用户或 Agent 读到的第一份文档没有它 CLI 不可用每个导出/渲染函数必须经过程序化输出分析验证后才能标记为可用没有报错不充分注册表中的每个滤镜/效果必须有对应的渲染映射或明确标注仅工程内不渲染测试套件必须包含真实文件 E2E 测试——现实媒体的格式假设总是在破坏。九、落地实例Shotcut CLI 的目录结构与使用HARNESS.md 描绘了通用结构本仓库 Shotcut 的实际实现位于 shotcut/agent-harnessshotcut/agent-harness/ ├── HARNESS.md # 本文档——通用 SOP ├── SHOTCUT.md # Shotcut 专项分析与 SOP ├── TEST.md # 测试结果记录 ├── setup.py # 包安装脚本 ├── workflow_demo.py # 完整演示3 段高光集锦 ├── examples/ │ └── workflow_basic.sh # 基础工作流脚本 └── cli_anything/shotcut/ # 实际 CLI 实现 ├── README.md # HOW TO RUN——必备 ├── shotcut_cli.py # 主入口Click REPL1630 行 ├── core/ # 按域拆分project/timeline/filters/media/export/session/transitions/compositing/preview ├── utils/ # mlt_xml.py、time.py、melt_backend.py、preview_bundle.py、repl_skin.py ├── skills/SKILL.md # Agent 技能说明 └── tests/ # test_core.py test_full_e2e.py安装与运行详见 cli_anything/shotcut/README.md依赖 Python 3.10、click、melt渲染必需、ffmpeg/ffprobe探测与导出REPL 可选prompt_toolkit。系统工具可按发行版安装pacman -S melt ffmpeg/apt install melt ffmpeg/brew install mlt ffmpeg。典型调用一次性命令与 REPL 两种形态# 新建工程默认 profile: hd1080p30 python3 -m cli.shotcut_cli project new --profile hd1080p30 -o my_project.mlt # 打开工程并查看信息Agent 友好--json python3 -m cli.shotcut_cli --json --project my_project.mlt project info # 进入交互式 REPL python3 -m cli.shotcut_cli repl --project my_project.mltREPL 内示例会话README.md new hd1080p30 add-track video Main media import intro.mp4 → Imported intro.mp4 as clip0 add-clip clip0 1 00:00:00.000 00:00:05.000 add-filter brightness --track 1 --clip 0 level1.3 show save render output.mp4 --preset h264-high可用 profilehd1080p30、hd1080p60、hd1080p24、hd720p30、4k30、4k60、sd480p。可用转场dissolve、wipe-left/right/down/up、bar-horizontal/vertical、diagonal、clock、iris-circle、crossfade。可用混合模式 17 种normal、add、multiply、screen、overlay等。CLI 还提供--dry-run不落盘试运行、--session id会话恢复、命令后自动保存_auto_save_callback见 shotcut_cli.py等增强能力。导出预设定义于 export.py共 10 个源码实际参数值defaultH.264 CRF 21 AAC 384kMP4、h264-highCRF 15 preset slow、h264-fastCRF 23 ultrafast、h265libx265 CRF 23、webm-vp9libvpx-vp9 CRF 30WebM、proresprores_ks profile 2MOV、gif、audio-mp3320k、audio-wavpcm_s16le、png-sequence。渲染命令支持--width/--height覆盖与--overwrite。滤镜注册表定义于 filters.pyCLI 名 → MLT service → 参数规格类型/默认值/取值范围一一登记例如brightnesslevel0.0–2.01.0正常、volumelevel0.0–5.0另含 gain dB、blurfrei0r.IIRbluramount 0.0–1.0、cropleft/right/top/bottom 像素、saturationfrei0r.saturat0r0.0–3.0、huefrei0r.hueshift0rshift 0.0–1.0整圆、sepiau/v 色度值、textdynamictextargument/size/fgcolour/family/halign/valign、以及用关键帧串timeval;timeval实现的淡入淡出系列。十、把同一套 SOP 推广到其他软件HARNESS.md 用一张对照表证明该 SOP 的普适性——模式永远是找到数据格式、找到引擎、写一个操作前者并驱动后者的 CLI最后验证输出。软件后端原生格式现有 CLI渲染断层风险ShotcutMLT.mlt (XML)melt, ffmpeg高——必须翻译滤镜GIMPGEGL.xcfgimp -i (script-fu)中——GEGL 有 CLIBlenderbpy.blendblender --python低——bpy 原生渲染Inkscapelibrsvg.svg (XML)inkscape --actions低——SVG 即格式AudacityPortAudio.aup3 (SQLite)—高——无 CLI 渲染器LibreOfficeUNO.odt (XMLZIP)soffice --macro低——UNO API 可用OBS Studiolibobsscene.jsonobs-websocket中——仅实时KdenliveMLT.kdenlive (XML)melt高——同 Shotcut渲染断层风险列标识朴素导出方案静默丢效果的概率高风险意味着几乎必然需要滤镜翻译层。本仓库中 Shotcut、Kdenlive、GIMP 等目录正是这一 SOP 的规模化实证。结语HARNESS.md 提供的方法论可以浓缩为一句话不重实现引擎直接操作原生数据格式用现成引擎渲染然后用程序化分析验证输出。四阶段 SOP分析→设计→实现→验证解决了如何把 GUI 变 CLI的架构问题渲染断层与滤镜翻译解决了改完能否真的生效的正确性问题时间码精度与双套测试解决了长期可靠性与 Agent 自纠错的质量问题。任何想要让开源软件Agent-Native的开发者都可以把这份 SOP 作为起点并对照 SHOTCUT.md 与 export.py 等真实实现逐项核对让 Agent 真正无屏操作你的软件。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考