激活条件
当用户想要一个卡通 / cel-shaded 风格的 3D 解说片段（纯色、黑色轮廓线、物体弹入、移动摄影机、大号字幕），想要复现“Stupy Doo”风格视频，或要求根据文字在 Blender 中为图表制作动画时加载此技能。
硬性规则
- 绝不允许使用图像/视频 AI 模型生成视觉效果。外观必须是 3D 几何体 + Blender 渲染的 Freestyle 轮廓线。
- Blender 可执行文件：
~/.local/bin/blender（5.1.x 版本，用户安装）。始终使用-b -P参数以无头模式运行。 - 故事板是唯一事实来源：
storyboard.json（模式定义见references/storyboard-schema.md）。编辑 JSON，重新渲染。严禁手动编辑.blend文件。 - 渲染完整视频前务必预览：使用
--stills参数渲染 3–5 帧，生成接触表并检查，修复重叠或超出画面的物体。 - 字幕和音频是后期处理（
mix.py、captions.py），绝不能使用 Blender 文字对象。 - 音效通过
audio部分中的action:引用锚定在动作时间上，当动作存在时绝不允许手动输入秒数。 - 旁白使用西班牙语并保持中性；UI/字幕文案遵循用户语言。
- 保持片段简短：每个故事板 8–30 秒。对于更长的视频，使用 ffmpeg concat 串联多个片段。
决策门
| 需求 | 操作 |
|---|---|
| 需旁白的视频 | 先录制旁白，然后根据旁白时间轴调整字幕，最后制作动画。通过 voice-video（tts.py）生成语音并放入 audio.narration。 |
| 音效 / 音乐 | audio 部分：narration、music、sfx 使用 action: 引用。占位符放在 assets/sfx/ 中，CC0 来源列在其 README 中。 |
| 提供了音乐 | 在静态帧渲染之前执行 beats.py snap storyboard.json --music track.mp3 --write。 |
| 快速检查 | --preview --stills t1,t2,t3（半分辨率，8 个采样）。 |
| 最终渲染 | 不使用 --preview；默认 1080x1920，30 fps。 |
| 物体不在预制件库中 | 预制件：box、plane、cylinder、sphere、panel、panel_row、cable、device、car、charger、transformer、cloud、tree、pole。否则使用基本几何体或 model（glb/obj）。 |
| 画面看起来很廉价 | 每个镜头一个主体，摄影机距离 8–13 米，使用 tree/pole/cloud 作为背景装饰，电缆先 draw 再 flow。参见 references/style-notes.md。 |
| 希望手动调整 | 添加 --blend 参数，在 Blender UI 中打开 out/scene.blend。 |
执行步骤
- 阅读
references/storyboard-schema.md和references/style-notes.md。 - 编写一个简短的
gen.py，生成<workdir>/storyboard.json：物体位于 z=0 的地面平面上，每个镜头一个主体、动作、字幕、post、audio。 - 静态帧：执行
~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5。使用 Pillow 构建接触表并阅读。 - 在 JSON 中修正构图和时间。重复步骤 3，直到每个镜头都清晰可读。
- 预览视频：使用相同的命令，仅附加
--preview。使用 ffprobe 检查out/raw.mp4（时长、fps）。 - 音频（如果存在
audio部分）：执行python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav。阅读提示表。 - 字幕 + 混流：执行
python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav（如果没有audio部分则使用--audio narration.wav）。 - 最终渲染：去掉
--preview，重新执行步骤 5–7。使用xdg-open打开out/final.mp4。
输出契约
返回：storyboard.json 的路径、out/final.mp4 的路径、时长、分辨率，以及每个镜头一行描述画面内容。报告渲染时间。列出尚未实现的功能（如口型同步、多片段串联）。
参考
references/storyboard-schema.md— JSON 模式、预制件、动作、摄影机约定。references/style-notes.md— 参考视觉效果、Blender 5 的注意事项、如何修正廉价画面、声音设计。references/external/— MIT 许可的副本：EL4CTEOblender-stylized-npr、arjun988camera-cinematography。assets/toonlib.py— bpy 库（材质、预制件、摄影机、动画）。assets/build.py— 故事板 → Blender 渲染。assets/mix.py— 将audio部分合并为一个 WAV 文件（带闪避的音乐、音效提示）。assets/beats.py— 节拍检测 + 调整动作时间。assets/sfx/— 占位音效及其 CC0 来源。assets/captions.py— ffmpeg 字幕 + 音频混流。assets/storyboard.example.json— 太阳能屋顶示例，9 秒。