解说短片（创意 → 完整视频）
您每次请求仅生成一个完整视频，请按以下 7 个步骤依次执行一次。 每个步骤都有一个命令、一个输出和一个停止条件。不要自行增加额外步骤。
路径：SKILL = 包含此文件的文件夹。STUDIO = 视频工作区
（默认：当前项目中的 ./explainer-studio；如已存在则复用）。SLUG = 视频的 kebab-case id，
例如 how-https-works。
硬性限制（保持运行快捷且成本低廉）
- 最多向用户提问一次，且仅当完全没有主题时。否则请自行决定（长度、格式、品牌），使用下面的默认值，并在最终回复中说明您的选择。
check.sh→ 修复 →check.sh最多2 次修复循环。然后进行渲染，并在回复中列出所有遗留问题。- 最多重新生成语音 2 次（仅针对长度或发音错误的单词）。
- 不要编辑
src/kit/（添加图标除外）。不要安装其他包或工具。 - 阅读
template/src/videos/example/一次（它是参考实现）。不要阅读 kit 源码；references/kit-api.md是它的文档。
“短片”、“短视频”、“解说短片” = 竖版 FORMAT（格式），而非长度模式。仅当用户要求快速/非常短/一分钟以内的视频或提供秒数时，才使用“short”长度模式。
默认值：长度 95–120 秒（300–370 词；“short” = 55–70 秒，“full” = 参考长度 160–175 秒 — 参见 references/script-guide.md），语音 am_michael 语速 1.18，品牌 = 用户的名字/频道（如果已知），否则为 "YourBrand"。
样式规则源自对 23 个参考视频的测量；证据放在 references/style-evidence/ 中（仅限人类阅读 — 您无需查看）。
步骤 1 — 设置（每台机器一次，首次约 3 分钟，之后约 2 秒）
bash SKILL/scripts/setup.sh STUDIO
停止条件：最后一行输出 READY: …。如果输出 MISSING TOOLS，请告知用户需要安装什么并停止。
（如果语音模型文件已存在于某处，可先设置 KOKORO_MODELS=<dir>，以跳过 340 MB 的下载。）
步骤 2 — 规划（尚未编写代码）
阅读 references/script-guide.md。然后编写 STUDIO/src/videos/SLUG/plan.md（≤ 25 行，在步骤 3 创建文件夹后进行）：
- 标题：采用以下格式之一（“How X works” · “X vs Y” · “Interview: …” · “System design: how <产品> does X”）。
- 贯穿示例：一个命名的人名 + 一个从头用到尾的具体产品/输入/值。
- 节拍（章节）：包含 id，6–9 个，每个 = 一个想法。
- 舞台：阅读
references/visual-guide.md，然后为每个章节写一行：section → added / moved / focus (spotlight ids) / leaves（参见其中的“Planning stages”）。选择 3–4 种强调色，每种绑定到一个东西。
步骤 3 — 脚本
bash SKILL/scripts/new_video.sh STUDIO SLUG
编写 STUDIO/src/videos/SLUG/script.json（格式：参见示例的 script.json）。必须遵守的规则：
sections[].id唯一、简单（hook、scenario、mechanism、…）。最后一个章节是行动召唤（CTA）。- 按您希望它们显示的方式编写数字/符号，并在
pronounce中映射它们读作什么 （"429": "four twenty nine"、"API": "A P I"、"SQL": "sequel"、"k8s": "kubernetes"）。 - 句子 ≤ 18 个单词。仅使用
. ! ?结束句子（每个句子独立合成）。 在继续之前，对照script-guide.md末尾的规则列表进行自我检查。
步骤 4 — 语音
bash SKILL/scripts/voice.sh STUDIO SLUG
打印每个章节的起止时间和 Done: <秒>s, <词> words, <词/分钟> wpm。停止条件：时长在目标值的 ±15% 以内。
太长 → 裁剪句子（而非加速），并重新运行一次。
步骤 5 — 视觉效果
阅读 references/kit-api.md 和示例（STUDIO/src/videos/example/Video.tsx + stages/*.tsx）。
编写 STUDIO/src/videos/SLUG/Video.tsx + 每个阶段一个文件放在 stages/ 中。不可协商：
- 每个元素的
at必须来自cue(section, word)或sec(section).from— 永远不能使用硬编码的秒数。 - 一个连续的画布：元素持续存在、移动、变暗并被重用。除阶段之间外，不允许全屏清除。
- 在叙述过程中，大约每 3 秒必须至少有一个可见变化（新元素、高亮、状态变化、移动）。
- 聚焦 = 在
<Canvas focus>上使用 Spotlight 方案（其余部分变暗） — 这是该样式的主要手法。 - 无字幕。标题（
Takeaway）≤ 7 个单词，每个视频 2–6 条。 - 内容保持在安全区域内（x 60–1020，y 280–1480；标题 ≈150；说明文字紧贴图表下方）。
- 填满宽度：主面板宽 960（或 2 × 465）。不得小于 26 px。
步骤 6 — 检查（最多 2 次修复循环）
check.sh 和 render.sh 会启动一个本地服务器和 headless Chrome。在沙盒化的代理中，请在沙盒外运行这两个命令。
如果您的环境完全无法执行此操作（No available ports found、Chrome 无法启动、拒绝非沙盒调用）：在步骤 5 后停止，并告知用户自己运行 check.sh 和 render.sh（给出完整的两个命令）。不要尝试变通方法。
bash SKILL/scripts/check.sh STUDIO SLUG # 可选的第三个参数："12.5,30,41" = 需要检查的额外秒数
它会即时检查每个 cue() 与语音时序的匹配情况、进行类型检查、每个章节渲染约 3 帧 + 结束卡，并输出 out/SLUG/check/sheet.jpg（+ 单帧 NN.jpg）。查看检查表图像（以及 2–3 个全尺寸的单帧）。仅修复失败的问题：
| 检查项 | 失败条件 |
|---|---|
| overlap | 文本/盒状元素重叠或被屏幕边缘裁剪 |
| scale | 图表未使用 < 80% 的宽度，或在繁忙的章节中留下 y 900–1400 的空白；在 540 px 宽的帧中需要眯眼看文字 |
| readability | 任何标签小于约 28 px，或文字位于繁忙区域之上 |
| sync | 元素在其对应词之前出现，或某帧显示空白/过时画布而叙述正在谈论其他内容 |
| continuity | 当故事继续时，某个阶段与上一阶段看起来无关（所有元素都被替换） |
| focus | 正在谈论的内容未被高亮（聚焦 / 琥珀色 / 其他部分变暗） |
| density | 某帧包含超过 9 个可见元素，或超过 2 行说明文字 |
类型错误 / cue not found 错误会打印修复信息（有效词列表）。修复后重新运行。
步骤 7 — 渲染 + 交付
bash SKILL/scripts/render.sh STUDIO SLUG
（如果 headless Chrome 被沙盒阻止，请在沙盒外重新运行此命令。）
然后编写 STUDIO/out/SLUG/upload.md：标题（= 视频标题，≤ 60 个字符，末尾允许 1 个 emoji）、
2 句话的描述、5 个话题标签，以及一个“需要核实的事实”列表（您凭记忆陈述的每个数字/声明）。
最终回复（简短）：MP4 文件路径、时长、SRT/封面/upload.md 路径、您做出的选择 （格式、长度、贯穿示例）以及任何遗留的已知问题。然后停止。
故障排除
| 症状 | 修复方法 |
|---|---|
cue not found: "x" #1 in section "y". Words: … | 使用打印列表中的某个词，或使用正确的章节 |
| 某个词发音错误 | 将其添加到 pronounce 并重新运行步骤 4 |
Cannot find module './timing.json' | 此 SLUG 尚未运行步骤 4 |
找不到 composition SLUG | 运行 voice.sh（它会注册视频） |
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found | 沙盒阻止了浏览器/端口：在非沙盒环境下运行命令（参见步骤 6） |
failed to canonicalize path …/voice/.venv/bin/python3 或其他 uv/venv 错误 | 删除 STUDIO/voice/.venv 并重新运行 setup.sh |
| 某帧显示文本溢出面板 | 为 <El> 设置更大的 h、更少的行数或更小的字体（≥ 26 px） |
| 视频太长/太短 | 编辑脚本（语速 1.18 时大约每秒 3.1 个词），重新运行步骤 4 |