自由视频生成工作室
从主题、脚本、提示或Python示例构建可复现的视频。Manim渲染是强制性的，用于确定性场景和代码或图表动画；可配置的云视频模型可以添加或生成其他素材。保持工作流可移植，能在Codex、Claude、Gemini、OpenClaw、Hermes、DeepSeek、Kimi、WorkBuddy或普通Python脚本中运行。
分离两个提供商层
- 智能体提供商仅用于编写教案、旁白、字幕、提示及Manim/Python源码。可对DeepSeek、Kimi或Hermes等提供商使用OpenAI兼容的聊天补全端点。
- 视频提供商仅用于生成或增强视频片段。切勿将视频任务发送到聊天补全端点。
- 将Agnes Video 2.5 Flash视为一个可选默认值，而非硬性依赖。
- 在配置或调用任何提供商之前，请阅读参考资料/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中文栈，在.vendor下保留所需的kokoro-tts-zh源码修订版本，在首次使用时下载所选模型/音色，并合成一个真实的烟雾测试WAV文件。如果任何步骤失败则停止。请阅读参考资料/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检索原作业。
使用台账
每次预检和提供商调用向<OUTPUT_PROJECT>/usage/video-usage.jsonl追加一条JSON记录。绝不存储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模板。