Freedom Video Generation Studio
從主題、腳本、提示或 Python 範例建立可重製的影片。強制使用 Manim 渲染確定性場景及程式碼或圖表動畫；設定好的雲端影片模型可以加入或生成其他片段。保持工作流程可在 Codex、Claude、Gemini、OpenClaw、Hermes、DeepSeek、Kimi、WorkBuddy 或一般 Python 腳本之間移植。
區分兩個供應商層
- 僅使用代理供應商來撰寫教案、旁白、字幕、提示詞以及 Manim/Python 原始碼。對於 DeepSeek、Kimi 或 Hermes 等供應商，可使用 OpenAI 相容的聊天端點。
- 僅使用影片供應商來生成或增強影片片段。絕不要將影片任務傳送給聊天完成端點。
- 將 Agnes Video 2.5 Flash 視為可選的預設值，而非強制依賴。
- 在設定或呼叫任何供應商之前，請先閱讀 references/provider-config.md。
必要工作流程
-
建立輸出專案目錄。將原始碼、音訊、字幕、渲染結果和日誌都保留在該目錄內。
-
在撰寫或渲染課程之前，先執行：
python3 scripts/ensure_manim.py --project-root <OUTPUT_PROJECT>此步驟為強制性。它會在
<OUTPUT_PROJECT>/.venv-manim中尋找或安裝 Manim，驗證版本，並執行一次實際的煙霧測試渲染。若失敗則停止。後續渲染請使用此腳本列印出的 Manim 可執行檔路徑。 -
需要旁白時，請在生成旁白前執行此強制設定：
python3 scripts/ensure_kokoro.py --project-root <OUTPUT_PROJECT>它會在
<OUTPUT_PROJECT>/.venv-kokoro安裝鎖定的 Kokoro 中文堆疊，將要求的kokoro-tts-zh原始碼修訂版保留在.vendor下，首次使用時下載選擇的模型/語音，並合成一個實際的煙霧測試 WAV 檔案。任何步驟失敗則停止。請閱讀 references/audio-config.md 以了解語音和旁白指令。 -
產出有時間標記的教案。為每個場景指定旁白、螢幕上程式碼、動畫、字幕文字和持續時間。使用 Manim 來呈現程式碼執行概念、狀態變化、指標、軌跡、圖表和確定性的教育視覺效果。
-
在鎖定場景時間之前，先生成完整的旁白。使用
scripts/kokoro_narrate.py，預設使用溫暖教學語音zf_032，速度為0.96，在一個課程內保持單一語音和穩定的適中速度，並根據測量到的 WAV 及其清單來設定視覺效果/字幕的時間。 -
渲染一個 Manim 草稿，並驗證其測量持續時間、畫面大小、文字邊界、程式碼高亮和轉場是否與旁白計畫相符。
-
僅在雲端影片模型能實質改善課程時才呼叫它。在每次付費任務前執行下面的安全預檢。
-
組裝最終影片，然後驗證音訊、字幕時間、程式碼可讀性、持續時間和可播放的輸出。
旁白來源政策
- 對於每個有旁白的影片，使用由整合的
kokoro-tts-zh模型系列提供的國語語音。 - 絕不要使用 macOS
say、Windows SAPI、瀏覽器語音合成或其他作業系統語音作為自動備用方案。 - 如果 Kokoro 安裝、模型下載、語音載入或合成失敗，請停止並報告失敗。不要靜默地替換為機械語音。
- Kokoro 提供預設語音；它不會複製任意上傳的說話者。連結的儲存庫的語音複製路徑依賴於一個單獨的 StableTTS 子模組和模型權重，這些並非此技能自含或驗證過的。對於語音複製請求，需要一個單獨設定並驗證過的複製後端，以及使用者有權使用該語音的確認。
強制性計費預檢
在每次雲端影片請求之前：
- 查詢供應商的當前價格端點或當前官方定價來源。
- 透過設定的配額端點查詢帳戶配額/點數。
- 使用請求的持續時間、解析度、模型和供應商定價來計算最大預期成本。
- 將其與
VIDEO_MAX_COST_PER_TASK和可用點數進行比較。 - 將預檢結果記錄到
<OUTPUT_PROJECT>/usage/video-usage.jsonl。
如果價格或配額未知、無法驗證端點、點數不足或可能超過最大成本，請不要提交任務。供應商宣傳免費層級並不能證明當前請求是免費的。
重試與輪詢規則
- 絕不無限重試。
- 對於非同步任務，使用
VIDEO_MAX_POLLS和VIDEO_POLL_INTERVAL_SECONDS。 - 針對暫時性網路或 HTTP 429/5xx 錯誤，最多重試
VIDEO_MAX_RETRIES次，並使用有上限的指數退避。 - 對於佇列滿、容量滿、點數不足、身份驗證、驗證或價格政策錯誤，請立即停止，除非供應商明確提供一個較短的
Retry-After並且已設定的重試預算允許一次重試。 - 絕不要僅僅因為狀態輪詢失敗就建立替代任務；應先透過 ID 檢索原始任務。
用量帳本
將每個預檢和供應商呼叫的 JSON 物件附加到 <OUTPUT_PROJECT>/usage/video-usage.jsonl。絕不儲存 API 金鑰或授權標頭。包含：
{"timestamp":"ISO-8601","provider":"name","model":"id","job_id":"id-or-null","requested_seconds":10,"actual_seconds":10,"call_count":1,"status":"succeeded","price_source":"endpoint-or-url","estimated_cost":0,"actual_cost":0,"currency":"USD","cost_known":true,"error":null}
如果供應商未回傳實際成本，請將 actual_cost 設為 null，並將 cost_known 設為 false；不要靜默記錄為零。最後，總結總呼叫次數、生成的持續時間、已知成本以及成本未知的呼叫次數。
輸出合約
交付最終影片以及可編輯的 Manim 原始碼、Kokoro 旁白 WAV 和清單、字幕檔案、供應商安全的設定範本、渲染指令和用量帳本。說明所使用的 Kokoro 語音/模型/速度，並在未呼叫任何雲端影片 API 或無法驗證成本時明確說明。
不要在原始碼、日誌、提示詞、shell 歷史記錄、螢幕截圖或已提交的 .env 檔案中暴露機密。請使用環境變數，並僅提供 .env.example 範本。