动画解说器（代码化3D动态图形）
一切都是代码：视频的每个部分都是一个3D世界（escena/partes/<parte>.js），它是时间纯函数，motor.js决定显示哪个并绘制卡拉OK字幕，render.mjs请求无头Chrome渲染每一帧。
无需手动编辑：如果出现问题，只需修正代码并重新渲染。
所有文件位置： HOME3D = $EXPLICADORES_3D，如果未设置，则为 ~/.explicadores-3d（由安装程序创建）。
其中包含 biblioteca/（3D模型，vendor/包含three.js、字体）以及此技能的副本。SKILL_DIR 是此 SKILL.md 所在的文件夹。
| 文件 | 用途 |
|---|---|
nuevo.py <carpeta> | 使用模板创建项目（包括引擎、样式、lib2d、three.js、Fredoka字体、语音/时间/音频脚本、示例部分、空白CONTRATO.md和DECISIONES.md） |
render.mjs | --hoja, --probe a,b,c, --rango a,b, --mitad, --sub N, --rapido, --sin-gpu |
entregar.py <proyecto> <NOMBRE> --ronda N [--escritorio] | 视频+音频，手机版小于29 MB，每0.5秒的审查表以及datos.txt（时长，LUFS，峰值） |
revisar_hoja.py <proyecto> [--tramo a,b | --ronda N | --cuadros …] | 约5秒自动审查，无需令牌：检测渐隐中的双文字、光晕、成对物体（像眼睛）、过曝白色、污点、超出安全区域、亮度跳跃 |
ENCARGO_CONSTRUCTOR.md | 构建者简短任务模板（每个代理负责一部分） |
ENCARGO_REVISORES.md | 审查者A（保留）、B（数据）、D（图像）负责审查表和视频 |
要求：Node 18+、项目中 npm install playwright-core、Chrome（或设置 CHROME_PATH，或运行 npx playwright install chromium）、Python 3.10+（安装numpy和faster-whisper），以及ffmpeg。
内务规则
- 零编造数据： 在构建之前，合同中的每个数字都必须注明来源。
- 禁止宠物或带有眼睛的物体，以及任何可能被解读为眼睛的形状（参见“典型错误”）。
- 默认样式：在深色背景上放置一个干净物体，带有温暖光晕，摄影机始终缓慢运动，关键词为金色，完整叙述的卡拉OK字幕，循环至第一帧。
- 节奏：3.0-3.2词/秒，约每3秒改变一次构图，没有物体静止超过5秒，在4.5秒内设置悬念。
- 时长：独立视频15-30秒；超过60秒仅适用于带有名称和编号的系列视频。
流程
python SKILL_DIR/nuevo.py <tema>-AAAA-MM（在当前目录创建文件夹）。打开并测试显示：npx http-server escena -p 8080（或在escena/内运行python -m http.server），然后访问localhost:8080。- 使用
guion技能编写脚本：包含来源调研、映射图、第0轮（A≥9，C≥9，最多2轮），并以脚本就绪结束。在获得用户确认前不要继续。 - 语音（消耗积分或CPU时间，因此在确认后进行）：
- ElevenLabs：
export ELEVENLABS_API_KEY=...（由用户设置；你绝不能将其写入文件），然后python scripts/voz_eleven.py [--voz <id>]→voz/tomas_eleven/。免费计划禁止商业用途且有积分限制。 - 免费本地：
pip install kokoro soundfile（+系统espeak-ng），然后python scripts/voz_local.py [--voz em_alex]→voz/tomas_local/。 python scripts/verificar_voz.py（Whisper large-v3，仅运行一次且在后台）标记发音不佳的单词。python scripts/tiempos.py --tomas tomas_eleven（或tomas_local）→voz/voz_completa.wav、escena/beats.js（每个关键词的时间点，根据voz/claves.json）和escena/palabras.js（卡拉OK）。
- ElevenLabs：
- 完整合同（
escena/CONTRATO.md）：包含各部分及其B.*时间段落、每个关键词对应的视觉内容、精确的文字标记、带有来源的数据、安全区域、节奏。这是构建者唯一读取的内容：未在合同中的内容将被他们猜测。修改motor.js中的PLAN（部分顺序和过渡）和CLAVE（卡拉OK的金色词语）。 - 3D模型：在建模之前，先搜索资源库（
biblioteca技能，HOME3D/biblioteca/CATALOGO.md），并将适用的模型复制到escena/modelos/。缺失的模型由单个代理制作（共享模型，努力程度medium，上限150k），并通过modelos/LISTO_<objeto>.txt通知。 - 构建者，使用
ENCARGO_CONSTRUCTOR.md：- 每个代理负责一个部分（一个不超过15秒的场景），在后台运行，最多同时3个；
- 简短任务：仅包含其时间段、其模型（API一行）和规则；构建者不读取引擎或完整合同；
- 包含“典型错误”和“构建者上限”模块，保持原样；
- 每轮修复使用全新的构建者，绝不在一个已超过40轮的代理上继续对话；
- 绝不让他们“等待”其他代理：先制作共享模型，再制作各个部分。
- 渲染前的审查表：
node render.mjs --hoja（每个关键帧一个画面：可视化脚本），然后python SKILL_DIR/revisar_hoja.py .。红色警告表示在继续前必须使用全新的low努力程度代理进行修复。随后，审查者A、B和D对审查表进行检查（ENCARGO_REVISORES.md，第1轮），并将revisar_hoja.py的输出粘贴到D的任务中。 python scripts/audio.py→audio/mezcla.wav，标准化至 -14 LUFS（音乐和效果为合成；编辑文件顶部的EFECTOS和CAMBIOS）。- 迭代渲染：
node render.mjs --rapido --sub 1。然后python SKILL_DIR/entregar.py . NOMBRE --ronda 1和python SKILL_DIR/revisar_hoja.py . --ronda 1，再发送给A和D（对视频进行1轮审查）。 - 最终渲染，仅一次：
node render.mjs --sub 6。绝不同时进行两次渲染。 python SKILL_DIR/entregar.py . NOMBRE --ronda N --escritorio，交付手机版。- 贡献至资源库（默认启用）： 遵循
biblioteca技能的“贡献新模型”流程（nuevos.py→ 准备 →¿Los subo a la biblioteca? (S/n)）。如果用户在此项目中已拒绝，则不再询问。
按角色分配的努力程度和模型
有关各框架的完整表格，请参见仓库中的 AGENTS.md。摘要（Claude Code名称；其他框架使用等效的“快速/中等/深度”）：
| 角色 | 模型 | 努力程度 |
|---|---|---|
| 协调视频的会话 | 你正在使用的 | medium |
| 数据调研与审查者B | 中等（Sonnet） | high |
| 共享3D模型 | 中等 | medium，上限150k |
| 场景构建者 | 中等 | medium，上限40轮/120k |
| 审查者A、C、D | 中等 | medium（像Haiku这样的小模型会违反规则：不行） |
| 场景小修复 | 中等 | low |
max | 从不使用 | 速度极慢且过度思考 |
令牌和会话预算
成本是轮数 × 对话长度，而非书写的内容。规则：
- 每个视频使用一个全新会话。 在上下文达到150k时进行接力：留下
AVANCE.md（记录已完成、待办、决策），并在读取该文件的新会话中继续。 - 仅在里程碑时通知：
脚本就绪、快速视频就绪、完成，或当你受阻时。其他内容记入TIEMPOS.md而不通知。 - 主会话中不包含截图或图片：这些由返回文本的子代理查看。
- 审查者预算：第0轮（映射图）最多2轮；第1轮（审查表）1轮；视频仅1轮，仅由A和D参与。第二轮仅针对评分低于8.5的区域。
构建者上限（每个任务的末尾必须原样粘贴；对于共享模型，上限为150k）：
预算：最多40轮和120k令牌上下文。当达到任一限制时，在你的工作目录中写入
AVANCE.md（记录已完成、待办、测试过但失败的内容），并以5行摘要结束；另一个代理将从那里继续。不要读取引擎、完整合同或其他部分：此任务中已包含你所需的信息。绝不要读取超过300行的完整文件：使用范围或grep。截图仅在node render.mjs --probe <seg> --mitad时进行，且每5轮最多做1张。在请求截图之前，先运行revisar_hoja.py（不消耗令牌）。不要等待任何人：如果缺少什么，在AVANCE.md中注明并结束。
典型错误（每个构建者任务必须原样粘贴；(auto) 表示revisar_hoja.py可以捕获）：
- 渐隐中的双文字 (auto)：在新文字进入前完全移除旧文字（退出 < 0.15秒）或使用硬切；同一区域绝不同时显示两个文字。
- 光晕和辉光 (auto)：带有柔和光辉的球体、圆盘或焦点会被视为眼睛或太阳。使用平面发光体，无径向精灵；如果某物发光，应为长条状且无环。
- 成对物体 (auto)：两个大小和亮度相同的窗户、焦点或球体放在一起会被视为眼睛。使用不同大小、不同高度，或仅用一个。
- 过曝白色 (auto，警告)：禁止纯白色带有泛光；使用调色板颜色，哑光。
- 污点和散点 (auto，警告)：单独的粒子、文字后方的阴影、残留的边缘。
- 超出安全区域 (auto)：禁止任何物体位于 y < 215 或 y > 1450（卡拉OK区域）；禁止任何物体跨越文字。
- 亮度跳跃 (auto 配合
--ronda)：平均亮度在60-90之间，镜头之间跳跃不超过25。- 重复：同一文字同时出现在题板和卡拉OK中；一个想法只用一个题板。
- 脸和手：人物应背对或3/4背面；手应从侧面或手背进入。
- 小文字：所有文字大小 >= 42px（题板 >= 52px）。
渲染：时间花在哪里（在4核集成GPU笔记本上测量）
| 步骤 | 每帧 |
|---|---|
| 从Chrome获取帧（JPEG，GPU通过ANGLE） | ~0.07秒 |
x264 slow CRF 16（交付） | +0.11秒 |
--rapido（Windows/Intel上的Quick Sync；其他平台上的x264 veryfast；可通过 CODEC_RAPIDO 选择） | +0.02-0.05秒 |
模糊 --sub 6 | +0.09秒 |
无GPU（--sin-gpu）速度慢约40%。材质中禁止transmission，每个部分每帧不超过80毫秒。
忘记就会浪费迭代的教训
update(t)是 t 的纯函数：渲染器会请求独立帧和子帧。禁止使用Math.random（使用E.azar(semilla)）或帧间状态。保护 t < 0。- 相机运动持续时间 >= 0.6秒，使用 inOutCubic 缓动：配合
--sub 6，快速运动会产生鬼影。 - 如果测试结果出现其他帧的碎片，说明另一个进程正在同时渲染：重新执行。
- 渲染结束时出现“Failed to load resource”的404错误是正常的；真正的错误是
pageerror。 - 使用
scene.environment时，three.js r186 使用scene.environmentIntensity，而非材质的envMapIntensity。 - 资源库中的粒子（three.quarks）是时间确定性的：不要移动群组，使用其
pos属性。 - 鼠标调整面板：在URL中添加
?ajustes=1（参见biblioteca/base/LEEME.md）；渲染时永远不会加载它。 - 真实材质（照片、档案素材）：Wikimedia Commons 和 Internet Archive 提供公有领域和 CC BY 许可素材；在描述中注明出处。