VideoHero
仅通过受支持的 videohero CLI 使用 VideoHero。请勿自动化 SwiftUI 界面、编辑 VideoHero 的 SwiftData 存储、调用其私有辅助可执行文件或在项目目录中构造文件。
首先根据用户或测试工具提供的绝对路径解析 CLI 可执行文件，然后根据绝对路径 VIDEOHERO_CLI，最后才根据 PATH 中的 videohero 命令。在整个工作流中持续使用该已解析的可执行文件。从以下命令开始：
CLI="/user/提供的/绝对/路径/bin/videohero"
"$CLI" version --format json
"$CLI" capabilities --format json
如果未提供绝对路径，则通过 command -v videohero 解析并使用其返回的绝对路径作为 CLI。
如果可执行文件缺失、自动化被禁用或报告协议不兼容，则停止并解释用户需要在 VideoHero 中启用或安装什么。不要替换为猜测的命令。预期的第一个稳定协议版本是 1。
工作流
- 读取当前能力，而不是依赖记忆中的引擎、声音、格式或默认值。
- 在进行昂贵的生成之前，运行
videohero doctor --workflow <workflow> --format json。对于具体请求，当安装的 CLI 支持时，请包含其输入和输出参数。 - 从
videohero voices list --format json中解析请求的声音。使用其稳定的id，而不是本地化标题。如果用户的描述匹配多个声音，则提供有意义的候选列表，而不是默默地选择。 - 使用绝对路径和
--format json（不带--wait）提交操作，然后解析返回的作业 ID。对于长文本或敏感文本，优先使用--text-file。 - 对于返回的作业 ID，当用户希望当前轮次等待时使用
videohero jobs wait <job-id> --format ndjson；否则报告作业 ID，稍后使用jobs status。在演示作业期间，传达有意义的阶段/进度变化和存在的estimate。estimate缺失意味着 VideoHero 没有足够的兼容历史记录；切勿发明完成时间。仅当用户请求取消或当前任务明确授权取消时，才使用jobs cancel。 - 仅当最终状态为
succeeded、delivery.state为delivered且 CLI 退出代码为 0 时，才确认成功。返回收据的实际destinationPath以及任何警告。
演示渲染默认会创建并持续保存一个可编辑的 VideoHero 项目，当 capabilities.presentation.persistsProject 为 true 时。请勿添加或发明 --save-project 选项。文本转语音仍然是临时音频作业，不得创建 VideoHero 项目。在两种情况下，都不要自行写入 VideoHero 的 SwiftData 存储或项目目录；应用拥有持久化权。
除非用户已授权，否则不要下载模型、接受许可、启用代理控制、授权个人语音、覆盖现有输出，或使用实质上不同的设置重试失败的生成。超时并不表示提交失败：请查询作业或使用相同的幂等键重试。
路线
- 对于文本转语音，阅读 references/cli-protocol.md。
- 对于 PPTX/PDF 转视频，阅读 references/cli-protocol.md。
- 对于作业状态、结构化错误、恢复或取消，阅读 references/cli-protocol.md。
- 当用户要求安装、配置或测试本地集成时，阅读 references/setup-and-testing.md。
将路径保留为单独的命令参数。不要将用户文本插入到 shell 语法中。当请求复杂时，编写 capabilities 支持的版本化请求 JSON 并传递其路径，而不是组装脆弱的命令行。