oma-video

视频路由器

调度

适用场景

适用于短视频/短片、README 或代码讲解，以及演示操作流程。

请求	模式	默认纵横比	必需来源
短视频、短片、社交媒体片段	shorts	9:16	主题或简述
README、代码、数据讲解	explainer	16:9	主题或来源路径
演示或操作流程讲解	demo	16:9	使用 --capture 提供人工录制的视频

不适用场景

静态图片请使用 oma-image，幻灯片请使用 oma-slide，纯音频请使用 oma-voice，交互式 HTML 讲解请使用 oma-explanation。编辑现有成片和直播不在适用范围内。

结构流程

输入包括简述，以及可选的模式、纵横比、地区设置、字幕、视觉素材、语音、音乐、时长、合成器、录制路径和种子。输出保存在 .agents/results/videos/<timestamp>-<shortid>-<mode>/ 中：

• script.json、timing.json 和 render-spec.json 构成确定性素材总线。
• 字幕和获取的音频/视觉素材会记录在 manifest.json 中，并附带哈希、提供方、费用、警告和退出代码。
• 成功完成的实际渲染包含 <mode>-<slug>.mp4、编码后的视频流，以及大于零的 ffprobe 时长。

OMA_VIDEO_MOCK=1 仅用于测试。它可以创建带有 .mp4 名称的确定性文本占位文件；这些文件绝不是交付给用户的成品。缺少 HyperFrames/MPT 工具链、合成内容未编写、渲染出错或视频无效时，都会导致失败并提供诊断信息，同时保留脚本/渲染规格以便恢复。

判断并确认

如果意图明确，则推断模式：短视频/短片 -> shorts；README/代码/数据/讲解 -> explainer；演示/操作流程/录制 -> demo。对于一句话请求，在调用前说明推断出的模式、纵横比、时长、视觉策略、字幕、地区设置，以及语音/音乐。默认值明确时，不要要求用户填写问卷。

仅在会影响结果时询问：模式/来源不明确、需要演示录制，或需要确认费用。明确指定的模式、纵横比、时长、字幕或语音必须原样遵循。

对于演示，由人工录制屏幕并控制登录。--source web --url 仅用于提供上下文；它不会自动执行登录，也不会启动录制器。若未提供 --capture，则返回引导式录制说明并停止。

逻辑操作

防护措施

1. 除非明确允许外部输出，否则输出和录制路径必须位于 $PWD 内。验证录制格式，并将外部素材复制到运行目录。对日志和清单中的 URL 查询参数/哈希令牌进行遮蔽。
2. 提供方配置不要求密钥：使用已配置的链。付费提供方需要其环境密钥，并且必须遵守费用防护措施。本地回退方案可以替代语音、视觉素材、字幕或音乐；在警告中记录覆盖情况。合成器故障绝不能回退为视频。
3. 在执行付费提供方操作或重新运行之前，将规划估算与 cost.guardrail_usd 或 --max-usd 进行比较，并复用现有的费用授权。在进行中的 OMA 视频工作流中，执行前须记录实际的付费、限额、回退或拒绝选择（执行协议第 2 步）。仅当付费操作已获授权时，才传入 --yes 或 OMA_VIDEO_YES=1；该事件本身不构成授权。
4. 遵守 limits.max_duration_sec（180）和 limits.max_scenes（40）。在收到 SIGINT/SIGTERM 时取消子进程工作。
5. 保留运行目录。绝不自动清理用户的视频素材。
6. --dry-run 只写入规划素材，不执行提供方渲染。它不能证明 MP4 文件存在。

标准命令路径

# Plan or create the asset bus. Supply --script whenever an agent authored it.
oma video generate "Jeju coffee" --mode shorts --aspect 9:16 \
  --captions tiktok --script ./script.json --output json

# Deterministic planning only; no real render or provider work.
oma video generate "explain this project" --mode explainer --seed 42 --dry-run

# Human-recorded demo input.
oma video generate "feature walkthrough" --mode demo --capture <absolute-path>.mp4

# Scaffold the per-run HyperFrames project, author index.html as instructed,
# then render and validate the encoded output.
oma video compose <runDir> --output json
oma video render <runDir> --output json

# Diagnose required toolchains without changing a run.
oma video doctor
oma video provider list

oma video generate --output json 会返回 {exitCode, runDir, manifestPath, scriptPath, renderSpecPath, warnings, error}。 从清单中读取视频和素材路径；JSON 信封没有 outputs 字段。

失败与恢复

• 缺少 HyperFrames 合成内容：oma video compose <runDir> 会准备项目和创作规范。根据生成的 AUTHORING.md 编写 <runDir>/hyperframes/index.html，然后调用 oma video render <runDir>。该命令会检查、渲染并使用 ffprobe 检查输出。修复报告中指出的合成内容或工具链故障，然后重新运行；无法渲染时，请返回失败报告。

• 缺少 MPT 工具链：--compositor mpt 需要已安装的代码检出版本、其虚拟环境和 ffmpeg。获得授权且条件允许时，请使用 oma video doctor --install-mpt。MPT 设置失败、驱动程序故障以及非视频输出都会导致失败并附带诊断信息；不会写入占位 MP4。

成功意味着所有素材架构和清单哈希均通过验证，并且真实 MP4 通过视频流和时长验证。部分成功可以使用不需要密钥的视觉、时序、字幕或音乐备用方案，但仍必须通过真实视频验证。

参考资料

条件性资源

仅加载任务所需的资源：

• resources/execution-protocol.md：完整的有序处理流水线、故障映射和 JSON 报告规则。
• resources/vendor-matrix.md：更改提供商、密钥、成本或备用顺序前必读。
• resources/script-schema.md：编写或验证 --script 输入时使用。
• resources/prompt-tips.md：将概要转化为场景提示词时使用。
• resources/hyperframes-authoring/README.md 和所选模式指南：编写 index.html 前必读。
• resources/checklist.md：将真实视频交付给用户前必读。

验证

对于 CLI/运行时更改，请针对受影响的成功和失败路径添加回归测试。至少运行相关的 Vitest 文件，例如：

cd cli
bunx vitest run commands/video/providers/compositor.test.ts \
  commands/video/orchestrator.test.ts
bunx biome check commands/video/providers/compositor.ts \
  commands/video/providers/compositor.test.ts

不要仅为测试文档或仅使用模拟的代码分支而运行实时渲染。