Plextrang/story-shorts

故事短片：输入创意，输出完整的动画短片

该技能是一个电影引擎加工作流。引擎（engine/）在无头 Chrome 中逐帧渲染 three.js： 2D 画布木偶角色位于卡通着色、墨线轮廓的 3D 世界中，包含摄像机运镜与溶解、用于解说图形的 2D 叠加层、内嵌字幕以及事件驱动的声音混音。每部影片只写入其故事层： 角色、地点、镜头、图形和声音方案。新影片从空白模板（starter/：两个占位角色、两个地点、四个镜头）开始。examples/floating-scale/ 是一部完成的参考影片。切勿重复使用其角色或故事。

按需阅读以下内容：

• reference/rules.md：故事与画面规则。首先阅读它。
• reference/story-templates.md：六种故事模板。每部影片选择一个。
• reference/engine-api.md：如何在引擎上编写影片（角色、姿势、世界、道具、镜头、图形、提示）。
• reference/transitions.md：规则 11 的实际应用（摄像机运镜、连续性剧幕编排、保留的切镜）。
• reference/sound.md：配音、音乐和音效，使用 Epidemic Sound 或免费工具。
• reference/lessons.md：已遇到的错误及其修复。在调试任何内容之前先检查它。

开始之前：问两个问题

1. 创意。 一句话就够了：“一个怕黑的灯塔管理员”“1904 年奥运会马拉松”“如果重力减半一天”。如果用户没有提供，请询问。只有在用户在意时才询问时长（默认为约 60 秒）。
2. 声音工具。 询问：“你有 Epidemic Sound（带其 Claude 连接器）吗，还是我应该使用免费工具？”
   • Epidemic Sound（推荐）： 使用 Epidemic 的画外音为叙述者和角色配音，将一首 Epidemic 音乐曲目剪裁到故事中，以及 Epidemic 的音效和环境音。它需要 Claude Code 中的 Epidemic Sound MCP 连接器。
   • 免费： 使用 Kokoro TTS 生成配音（scripts/kokoro_voice.py），以及代码合成的配乐和音效。
   • 除非在影片的 README 中说明，否则不要在一部影片中混用两者。

然后运行 python scripts/check_setup.py 并修复所有标记为 MISSING 的内容，然后再编写任何影片代码。

工作流（除非用户要求，否则无需批准）

1. 新项目。 python scripts/new_film.py <文件夹> "标题" 复制引擎和空白模板，写入占位时间线并安装 film/node_modules。仅在该文件夹内工作。
2. 故事（docs/STORY.md，script/lines.json）。
   • 选择与创意匹配的故事模板（reference/story-templates.md），并说明你选择了哪个及其原因。
   • 编写剧本：每个口语台词一条记录（id、说话者、开始时间、文本）。叙述加上几条角色台词；每分钟影片约 150 个单词。
   • 编写分镜表，每个镜头进行无声阅读：静音观看者仅从画面中能理解什么。
   • 命名地点。地点变化是唯一需要溶解的原因；在一个地点内部使用摄像机运镜。
   • 事实必须真实，有实际数字。角色、故事和世界均为原创。
3. 选角（film/src/story/cast.js）。
   • 每个角色一个键（与其说话者 ID 相同）。从预设开始，覆盖颜色、比例和特征，直到成为本影片独有的（reference/engine-api.md，“Characters”）。当故事需要时，在 character.js 中添加新的外观，并放在新的 feat 标志下。
   • 在构建任何镜头之前，运行 node film/tools/charsheet.mjs 并查看每张角色表。
4. 世界和道具（story/world.js，story/set.js，可选 story/props.js）。
   • 使用 worldkit.js 加上其自己的地标构建每个地点。将每个标记放在 SET 中。为主角道具提供故事所需的状态。
5. 画面分镜（story/shots.js，story/overlay.js）。
   • 用影片的镜头替换模板的四个镜头。从时间线获取时间点（K.wordAt，K.lineAt），绝不能使用硬编码的秒数。在配音存在之前，运行 python tools/build_timeline.py --placeholder。
   • 从一开始就为连续性做剧幕编排（规则 11）：每个地点每个角色一种表演，道具位于其标记位置。
   • 使用 2D 图解进行说明（规则 4）。在 CUES 中列出每个可见动作。
6. 配音。
   • 将每个台词生成为独立的音频片段到 audio/vo/raw/<id>.mp3|wav（Epidemic，或 scripts/kokoro_voice.py）。
   • 运行 python <仓库>/scripts/prepare_voice.py（对于 Kokoro 添加 --atempo-off）修剪静音结尾并设置节奏。
   • 运行 python tools/build_timeline.py，python tools/captions.py，然后 cd film && node tools/cues.mjs。
   • 绝不要在耳语单词时间处剪切片段。重新检查构图：时间点随真实配音而移动。
7. 在完整渲染前审核画面：
   • node framecheck.mjs --step 4 必须输出 "framing OK"。
   • node tools/poptest.mjs --out ../render/pop 检查所有边界的跳帧；bash tools/movesheet.sh 检查运动。
   • bash tools/sheet.sh <名称> "<时间>" 制作接触印相表。查看它们，并将每个镜头与其无声阅读进行对照。至少进行两轮完整检查。
8. 声音（audio/sound_plan.json，reference/sound.md）。
   • Epidemic：将音轨和音效下载到 audio/epidemic/，填写 music、effects 和 ambience，然后 cd audio/epidemic_mix && python mix_film.py && python autolevel.py && python qc.py && python sync_check.py。
   • 免费：填写 synth，然后 cd audio/synth && python music.py && python build_fx.py && python mix.py && python cue_presence.py。
   • 目标：−14 LUFS，真实峰值 ≤ −1.3 dBTP，配音在所有台词上至少清晰 6 dB，无静音间隙，每个音效在一帧内。
9. 渲染、合成、交付。
   • cd film && node render.mjs --from 0 --to <帧数-1> --scale 1.5 --workers 2 --jpg --out ../render/frames。
   • bash tools/assemble.sh 写入 out/<标题>.mp4 和 out/contact_sheet.jpg，并测量结果。如果崩溃的工作进程留下了空帧，它会拒绝运行。
   • 如果安装了 earshot：运行 bash audio/tools/es.sh critique out/<标题>.mp4，目标是“可发布级别”。
   • 编写影片的 README.md：一句话摘要、测量结果、每个保留切镜及其原因、使用的音效，以及诚实的薄弱环节。绝不要声称影片是好的： 你无法以全速观看或收听它。列出用户需要通过眼睛和耳朵检查的内容，然后停止并等待他们的审查。

不可妥协项（详情见 reference/rules.md）

• 关闭声音也能看懂。在显示解决方案之前先展示问题。在每句台词被说出的同时将其显示在屏幕上。
• 没有字面比喻；使用清晰的 2D 图解进行解释。
• 道具一目了然。使用包含完整人物的中景和远景镜头，保持字幕区域（画面高度的 62–78%）清晰，且没有人被切断在画面边缘。
• 同一地点意味着摄像机运镜，新地点意味着溶解，切镜只有在说明理由时才保留。
• 每个可见动作都有对应的可听声音，叙述全程保持清晰。
• 仅使用原创角色、故事和世界。切勿复制现有节目的角色或外观，也切勿重复使用示例影片中的内容。
• 仅在该影片自己的文件夹内工作。在那里全新安装所有内容；切勿链接到其他项目。