VideoHero
僅透過 VideoHero 支援的 videohero CLI 來使用它。請勿自動化 SwiftUI 介面、編輯 VideoHero 的 SwiftData 儲存庫、呼叫其私有的輔助執行檔、或在其專案目錄內建構檔案。
從使用者或測試工具提供的絕對路徑解析 CLI 執行檔，然後從絕對路徑 VIDEOHERO_CLI 解析，最後才從 PATH 上的 videohero 命令解析。在整個工作流程中持續使用該確切解析的執行檔。從以下指令開始：
CLI="/absolute/path/supplied/by/the/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和任何警告。
當 capabilities.presentation.persistsProject 為 true 時，簡報渲染會在預設情況下建立並持續儲存一個可編輯的 VideoHero 專案。請勿新增或發明 --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，並傳遞其路徑，而不是拼湊出脆弱的命令列。