火柴人故事短片生成器 是做什么的？
将一则故事前提转化为一条60-90秒的竖屏短片：一个为播放时长而优化的钩子脚本、用代码绘制的火柴人分镜、带有逐字时间戳的配音、音效设计，以及一个让观众评论并期待下集的二选一投票。基于 PlotVote 互动故事工作流构建。
整个流程是确定性的：你编写 episode.json（脚本、时间、动作）和 scenes.js（绘图），scripts/reel.py 负责剩下的工作（配音 → 音效 → 构建 → 检查 → 渲染）。不依赖图像模型、库存素材或除配音外的付费工具。
搭建（每台机器一次）
检查 python3 --version（需3.9以上）、ffmpeg -version 和 node --version（需18以上）。首次渲染时会通过 npx 下载 HyperFrames 和无头 Chrome；这是正常现象，大约需要一分钟。对于配音，用户需在项目目录的 .env 文件中设置 ELEVENLABS_API_KEY=...（或导出为环境变量）。切勿打印密钥。没有密钥时，所有内容仍可在 --draft 草稿模式下工作（静音，按实际速度计时）。
在每个终端会话中定义一次此 shell 函数（是函数，而非字符串变量，因此在 zsh 和 bash 中都能使用）。后续命令将使用它：
reel() { python3 "<此技能所在目录>/scripts/reel.py" "$@"; }
工作流程
1. 理解需求
- **“把这个故事做出来”**且给出明确前提 → 编写一个强力脚本并构建。
- “给我几个选项”或“脚本创意” → 提出3个完整选项（参见剧本库 §10），让对方选择，然后构建。
- “下一集”或“X胜出” → 继续系列：从上一集后果开始，解开上集埋下的线索，给出真实答案，升级冲突，新投票（剧本库 §9）。如有系列圣经，请先阅读。
- 仅需要脚本（或本地没有 Shell）→ 提供脚本表格，以及
episode.json和scenes.js（如果用户会自己渲染）。
2. 编写脚本
每次开始前先阅读 references/viral-script-playbook.md。 其中包含决定观众能否停留超过3秒的规则。当要发明一个前提、系列或季度时，也请阅读 references/story-engines.md。
将脚本写为一个表格（# · 配音 · 口白 · 屏幕内容），目标字数约210-230词（以普通语速约85秒）。运行剧本库的配音前检查清单。最容易出错的地方：第一帧必须有运动；5秒内交代时间、地点和人物；每个决定必须能通过12岁孩子的判断力测试；角色必须用第一人称说出自己的揭示；投票是两个物理性的单字动作且双方都有代价；投票后有一句低语线索暗示之前已埋下的伏笔。
如果用户要求了选项，或可能需要先批准再消耗积分，则先展示脚本表格并等待。否则继续。
3. 搭建短片骨架
reel new reels/<slug>-part1 --title "<标题> — 第1集"
这会从一个小型起始模板创建 episode.json 和 scenes.js。用你的故事内容替换这两个文件。
4. 绘制分镜（scenes.js）
阅读 references/drawing-kit.md，并打开 examples/sundown-part1/scenes.js 作为图案库（有探出身的生物、拉远地图、逐行展示的规则墙、定格动画生物、窗户擦肩而过、说话的收音机、树丛中的手电筒、选择分屏、封面）。
脚本表中的每个分镜对应一个函数。每个函数返回一个 1080×1920 的 SVG，由工具库中的辅助函数构建（defs()、sky()、forest()、cabin()、room()、water()、stick()、kid()、creature()、phone()、radio()、chip()、ring()、splitChoice()……）。如果遇到工具库未提供的设定（如水上乐园、火车、沙漠），这很正常：按照绘图工具库中“构建新场景”一节，使用矩形、路径和辅助函数绘制。为所有需要移动或随文字出现的内容赋予 id。避免将面部放在字幕区域（y 1180-1380）及右侧 140 像素范围内。为封面（主体位于标题下方）和投票卡片插图添加 mode。
5. 编排剧集（episode.json）
阅读 references/episode-format.md。 对每个场景：指定 draw、say 台词、kenburns 和 animate 条目（应落在台词对应的单词上，即 "at": "faster"）。然后：配置配音（对其他角色使用 fx 和字幕 tag），带时钟的 HUD 胶囊，手动放置在单词上的 sfx，bed 音乐提示，投票场景（两个选项、插图、线索行），封面和 post（含 {vote_line} 的文案、置顶评论、posts_at）。关于配音、音效和字幕，参见 references/sound-voice-posting.md。
6. 草稿预演（免费）
reel voice reels/<slug> --draft # 静音，按实际速度计时
reel sound reels/<slug>
reel build reels/<slug>
reel check reels/<slug>
reel snap reels/<slug> --at scenes # 每个分镜两张静帧（或 --at 0.5,12,30.5 秒）
查看 reels/<slug>/snaps/ 中的每一张静帧。修复绘图工具库可读性规则警告的内容：画面太暗难以阅读、面部被字幕遮挡、主体过小、揭示时机不对。check 必须显示“Check passed”（all 命令会在检查失败前停住）。以下警告是正常且无害的：“nested structure”、“track too dense”、“composition file too large”，以及插图“overflowing”其裁剪区域。
7. 配音与渲染
reel all reels/<slug> # 配音（ElevenLabs）→ 音效 → 构建 → 检查 → 渲染
reel frames reels/<slug> --every 2 # 全片联系单，用于审查
检查打印出的时长（60-90秒；若超时可删减开头铺垫）。查看 renders/review.png：主体可读、字幕清晰、对应单词上的物体有动作，投票卡片和线索插图正常出现。聆听第一行配音；如有单词可能被误听，则更换单词并重新配音（仅更改过的台词消耗积分）。
8. 交付
向用户提供 renders/<slug>.mp4、renders/cover.png 和 POST.md（文案、置顶评论、替代文本、投票关闭时间）。如果是系列故事，在短片文件夹旁编写或更新 bible.md：角色表、规则、正典、线索，以及每个投票选项对应的下一集开头一句话（故事引擎 §4）。
命令
| 命令 | 功能 |
|---|---|
reel new <目录> --title "…" | 创建短片文件夹骨架 |
reel voice <目录> [--draft] | 配音+单词时间戳 → timing.json、assets/audio/narration.wav |
reel sound <目录> | 合成19种音效+环境底噪 |
reel build <目录> | 编译 index.html、cover/、POST.md |
reel check <目录> | HyperFrames 代码检查、布局和对比度检查（失败时返回非零退出码） |
reel snap <目录> --at scenes | 从合成结果导出 PNG 静帧，每个分镜两张（或 --at 1,5.5,9 秒） |
reel render <目录> [--draft] | 生成 -14 LUFS 的 MP4 + cover.png + 联系单 |
reel all <目录> [--draft] | 配音 → 音效 → 构建 → 检查 → 渲染（检查失败则停止） |
reel frames <目录> --every 2 | 导出渲染后 MP4 全片的审查联系单 |
故障排除
"单词" isn't spoken there： 时间参考使用字幕拼写，且仅在该场景内搜索；错误信息会打印该场景的台词。对于同一单词的第二次出现使用word#1，其他场景使用sN:word，偏移量使用start+0.2，或绝对时间使用12.5s。- 配音未找到： 使用预设名称（Liam, Brian, George, Daniel, Callum, Bill, Roger, Chris, Eric, Will, Harry, Charlie, River, Adam, Sarah, Matilda, Jessica, Alice, Lily, Laura, Bella）或语音 id。
- 积分耗尽： 已配音的台词会被缓存；充值后重新运行
voice。 - 空画面或黑画面： 该分镜的 JavaScript 存在错误。
check会显示问题；修复后重新构建即可。 - 超过90秒： 删减铺垫台词和形容词；保留钩子、转折、投票和线索。
npx或node错误： 安装 Node 18+；首次运行时让npx下载 HyperFrames 和 Chrome。
此技能包含的内容
scripts/reel.py：命令行界面。scripts/synth.py：19种音效和底噪（无人机、风声、脉冲、嗡嗡声、水声），全部合成生成。assets/kit.js：绘图工具库。assets/runtime.js、assets/base.css：字幕、HUD 和投票卡片。references/：viral-script-playbook.md（必读）、story-engines.md（前提、系列、圣经）、episode-format.md（规格）、drawing-kit.md（绘图）、sound-voice-posting.md（配音、音效、字幕、发布、安全）。examples/sundown-part1/：一个完整的89秒第1集（episode.json+scenes.js）。examples/starter/：由new命令使用的4分镜初始模板。examples/script-pitches.md：另外五份完整的第1集脚本（THE WHEEL, LAST CAR, LOW TIDE, 3:33, ROW ONE）。