video-edit-cli

你就是编辑；video-edit-cli CLI 是你的工作台。它提供原子化、确定性的基础操作，并在 stdout 上输出一个 JSON 结果。编辑计划由你自行制定——没有任何命令会决定保留、删除或突出哪些内容。

运行 video-edit-cli --help（以及任何子命令的 --help）查看权威的命令列表；在此仓库中，请使用 uv run video-edit-cli … 运行。 如果 video-edit-cli 不在 PATH 中，请先使用 uv tool install video-edit-cli 安装（Apple Silicon 转录： uv tool install 'video-edit-cli[mlx]'）；必须另外预先安装 ffmpeg 和 ffprobe。

不变原则（适用于所有任务）

• 源媒体不可更改。绝不覆盖、原位重新编码或删除原文件。每个派生文件都必须是新文件，并保留其 *.provenance.json 旁车文件。
• 先获取证据，再编辑：不得处理尚未通过元数据、转录文本、帧、波形或预览检查过的区段。
• 渲染前先验证；进行重大编辑时，母版制作前先预览。
• 优先采用满足需求且成本最低的证据：对话内容先查看 probe 和转录文本；只有在决策需要时才进行有针对性的视觉／音频检查。

方法

1. 明确目标。 重述所需的交付内容和现有媒体。完成标准：能说出所需输出以及涉及的每个源文件。
2. 预检工作流。 运行 video-edit-cli doctor --workflow base；如果适用，可使用 transcription、vertical-captioned 或 audio-restoration。 在进行耗时操作前，先解决依赖检查失败的问题。
3. 设置工作区。 阅读 references/workspace.md，告知用户所选项目路径，然后复用匹配的项目，或运行 video-edit-cli workspace init。除非用户指定其他位置，否则默认使用 <project-root>/video-edit-projects/YYYY-MM-DD-<source-id-or-slug>/edit/。完成标准：workspace.json 列出每个源文件及其哈希值。
4. 检查媒体。 对每个源文件运行 probe；根据决策需要获取音频、代理文件、帧、胶片条、波形或区段预览。对于包含对话的媒体，阅读 references/transcription.md，并先进行转录。完成标准：了解每个源文件的时长、流和内容，足以为即将制定的计划提供依据。
5. 制定计划并渲染。 创建或修改计划前，阅读 references/edit-plan.md；自行编写计划、验证计划并渲染预览。完成标准：经验证的计划已成功渲染，且清单文件已生成。
6. 审核并修订。 阅读 references/cut-review.md；检查所生成渲染的每个边界。完成标准：每个剪辑都通过审核，或缺陷已修复或明确报告。
7. 完成交付。 完成标准：每项所需输出都通过技术验证以及必要的视觉／编辑审核。output validate 不会检查构图或编辑质量；请单独报告这些审核结果。

分支参考（符合条件时阅读）

• 用户要求清理／母带处理音频，或分析发现语音质量欠佳 → references/audio-restoration.md
• 打包交付内容（项目配置、字幕、资源、音乐、母版渲染） → references/subtitles-and-assets.md
• 多个已同步的视觉／音频源 → references/multicamera.md
• 竖屏或短视频交付内容 → references/vertical-video.md