editonny CLI命令全参考:doctor、catalog、inspect、scene等核心命令详解
editonny CLI命令全参考:doctor、catalog、inspect、scene等核心命令详解
editonny 是一个免费的开源本地视频剪辑工具,你可以在自己的电脑上通过对话完成剪辑:切除停顿、添加字幕、应用动效场景并导出 MP4。它的 editonny CLI 命令(doctor、catalog、inspect、scene、media 等)既是新手了解工具能力的窗口,也是 AI Agent 自动执行剪辑流程的底层接口。本文用通俗的方式带你逐个认识这些核心命令,无需任何编程基础也能看懂。
快速上手:一条命令认识所有子命令
editonny 的所有 CLI 能力都由一个入口脚本提供。在仓库根目录运行:
python3 editonny.py --help
即可看到全部子命令清单。入口文件是根目录的 editonny.py,它会把调用转发到真正干活的 skills/editonny/scripts/editonny.py。
| 子命令 | 一句话作用 |
|---|---|
doctor |
体检环境:检查 Python、uv、FFmpeg、Node.js 等依赖 |
inspect |
检查素材视频并给出剪辑建议(不开始剪辑) |
catalog |
搜索内置的 145 个动效场景 |
scene |
把场景、转场、特效、文字样式应用到项目 |
media |
校验/恢复内置媒体素材完整性 |
new |
从剪辑成果创建新项目 |
workspace |
管理项目版本:确认、修改、导出等 |
helper |
直接调用引擎里的单个处理脚本 |
guide |
启动本地网页版指南 |
doctor 命令:剪辑前的环境体检
python3 editonny.py doctor
doctor 是最常用的"体检"命令,它会依次检查:
- Launcher Python:启动器需要 Python 3.9+;
- uv / ffmpeg / ffprobe / node / npx:这些系统工具是否在 PATH 上可用;
- Python engine:剪辑引擎的虚拟环境与依赖是否齐全;
- Visual catalog:145 个场景文件是否完整。
输出中每行以 OK 或 MISSING 开头,一目了然。两个常用增强参数:
python3 editonny.py doctor --json # 输出 JSON 格式报告,便于程序读取
python3 editonny.py doctor --probe-media # 额外做本地媒体兼容性探测(不会安装任何东西)
💡 提示:
doctor是只读诊断,不会修改你的文件。完整的安装与恢复流程见 docs/installation.md 和 skills/editonny/references/setup.md。
catalog 命令:像搜索相册一样找动效场景
editonny 内置了 145 个动效场景(数字计数器、前后对比、三步骤列表、转场、指针等),数据存放在 skills/editonny/visuals/catalog.json 中。catalog 命令帮你按名称、类别或用途搜索:
python3 editonny.py catalog "three steps"
python3 editonny.py catalog counter
python3 editonny.py catalog "before after" --json
普通模式每行输出 场景ID · 类别 · 名称;加 --json 则输出完整信息,包括每个场景的 whenToUse(适用时机)、时长和画幅比例,方便你在对话中精准描述想要哪个场景。
inspect 命令:先看看素材,再决定怎么剪
python3 editonny.py inspect /path/to/video.mp4 --json
inspect 会分析你指定的一个或多个素材文件(可传多个路径),报告分辨率、时长、帧率、音频信息等,并给出剪辑设置建议,但不会真的开始剪辑。可选参数:
--requested 文件.json:提供你已明确选择的偏好,让建议更贴合;--json:输出完整 JSON 报告。
这一步对应的是 editonny 的"提案—确认"工作流:所有剪辑设置(裁切、字幕、音频处理等)都是建议,必须经你确认后才执行,默认设置不会自动改变画面比例或色彩。详见 skills/editonny/engine/WORKFLOW.md。
scene 命令:给视频加动效的核心工具
scene 命令负责把 catalog 里搜到的场景真正"贴"到项目上,实现位于 skills/editonny/visuals/apply.py。最常用的形态:
# 在 5 秒处开始、9 秒结束放置"三步骤"场景
python3 editonny.py scene --project ./myproject --use three-steps --start 5 --end 9
它还支持更多子动作(同一时间只能选一个):
| 参数 | 作用 |
|---|---|
--use 场景ID |
应用一个动效场景(需配合 --start 或 --cut) |
--transition 名称 |
在多个剪辑点插入转场(需配合 --cuts 0.5,3.2,...) |
--pointer / --effect / --text 名称 |
添加指针、视频特效或文字样式,--count N 控制数量 |
--sounds |
为已放置的场景写入配套音效事件 |
--captions |
按场景重新整理字幕层 |
--voice 效果 |
语音处理(含 list、inspect、remove 等模式) |
⚠️ 注意:
scene只会把某个场景用到的片段复制到项目中,项目里已有的视频不会被覆盖。
media 命令:内置素材的校验与恢复
editonny 自带 79 个原创视频素材(城市夜景、人物、产品等),用于场景演示与背景。media 命令管理它们:
python3 editonny.py media status # 校验 79 个视频是否齐全(按 SHA-256 哈希核对)
python3 editonny.py media status --json # 输出含缺失/损坏文件路径的 JSON 报告
python3 editonny.py media import /path/to/backup/visuals # 从完整备份恢复缺失文件
media status 会报告 X/79 valid videos; Y missing; Z invalid。如果有文件损坏或缺失,用 media import 指向一个完整的 visuals 备份文件夹即可安全恢复——它会先校验输入再复制,不会动你的源文件。实现位于 skills/editonny/visuals/media.py,素材清单在 skills/editonny/visuals/media.json。
new、workspace 与 guide:项目生命周期
创建项目 —— 剪辑完成后,用 new 把成果固化为一个可继续编辑的项目:
python3 editonny.py new ./myproject --edit /path/to/cut --style paper
# --style 可选 amber / paper / night
管理版本 —— workspace 子命令对应 skills/editonny/engine/helpers/workspace.py,覆盖整个项目生命周期:
init:用确认过的设置创建项目工作区;status:查看项目当前状态;revise:按 JSON 变更文件修改设置(--scope限定改动范围,如captions、audio);confirm/review:记录你的确认与评审;variant:派生一个变体版本;export:校验候选文件并发布最终导出。
打开网页指南 —— 在完整仓库中运行 python3 editonny.py guide,会在 http://localhost:4173 启动本地网站,可浏览全部场景目录、生成剪辑请求文案;--port 换端口,--no-open 不自动打开浏览器。
小结:一条命令链走完全流程
把上面的命令串起来,就是 editonny 的标准工作流:
doctor—— 体检环境,确保依赖齐全;catalog—— 搜到想要的动效场景;inspect—— 检查素材、查看剪辑建议并确认;scene—— 在确认的时间点应用场景与转场;media status—— 随时抽查内置素材完整性;new+workspace—— 创建项目、修订设置、导出成品。
更多架构细节可阅读 docs/architecture.md,场景库说明见 skills/editonny/visuals/README.md。掌握这些 CLI 命令后,无论是对话式让 AI 剪辑,还是亲自在终端操作,你都能对 editonny 的每一步了如指掌。


