Pedrovbm1/explicador

Explicador animado (motion graphics 3D por código)

一切都是程式碼：影片的每個部分都是一個 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。

基本規則

• 零虛構資料： 每個數字在建構之前都必須在 CONTRATO 中附上來源。
• 禁止寵物或帶有眼睛的物體，以及任何可能被解讀為眼睛的形狀（參閱「典型錯誤」）。
• 預設風格：一個乾淨的物體放在深色背景上，帶有溫暖的光暈，微距鏡頭始終平穩移動，關鍵字為金色，整段旁白都帶有卡拉 OK 字幕，循環到第一幀。
• 節奏：每個畫面的變化約 3.0-3.2 字/秒，每個畫面變化約 3 秒，沒有任何東西靜止超過 5 秒，鉤子在 4.5 秒之前出現。
• 持續時間：如果是獨立影片，為 15-30 秒；只有當它是帶有名稱和編號的系列的一部分時，才超過 60 秒。

流程

1. python SKILL_DIR/nuevo.py <tema>-AAAA-MM（在目前目錄中建立資料夾）。開啟並測試是否能正常顯示： npx http-server escena -p 8080（或在 escena/ 內執行 python -m http.server）並連線到 localhost:8080。
2. 使用 guion 技能撰寫腳本：含來源的研究、大綱、第 0 輪（A ≥ 9，C ≥ 9，最多 2 輪）並停止在**腳本就緒**。 在獲得使用者同意之前，不要繼續。
3. 配音（會消耗額度或 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）。
4. 完整的 CONTRATO（escena/CONTRATO.md）：包含帶有時間段 B.* 的部分、每個關鍵字顯示的內容、確切的標題、 帶有來源的資料、安全區域、節奏。這是建構者唯一閱讀的內容：不在其中的東西他們會猜測。 在 motor.js 中更改 PLAN（部分的順序和轉場）和 CLAVE（卡拉 OK 的金色單字）。
5. 3D 模型：在開始建模之前，先在資料庫中搜尋（biblioteca 技能，HOME3D/biblioteca/CATALOGO.md），並 複製任何適用的模型到 escena/modelos/。缺少的模型由一個代理（共享模型，medium 努力等級，上限 150k）製作，並透過 modelos/LISTO_<objeto>.txt 通知完成。
6. 建構者，使用 ENCARGO_CONSTRUCTOR.md：
   • 每個代理負責一個部分（一個 ≤ 15 秒的場景），在背景執行，最多同時 3 個；
   • 簡短委任：僅包含其時間段、其模型（API 在一行內）和規則；建構者不閱讀引擎或完整的 CONTRATO；
   • 附上「典型錯誤」區塊和「建構者上限」，保持原樣；
   • 每輪修正都使用新的建構者，永遠不要繼續與一個已經超過 40 個回合的建構者交談；
   • 永遠不要讓他們「等待」另一個代理：先完成共享模型，然後才是各部分。
7. 渲染前的審查表： node render.mjs --hoja（每個節拍一張圖：視覺腳本）並 python SKILL_DIR/revisar_hoja.py .。紅色 = 在繼續之前，使用一個新的 low 努力等級的代理進行修正。然後 審查員 A、B 和 D 根據審查表進行審查（ENCARGO_REVISORES.md，第 1 輪），並將 revisar_hoja.py 的輸出貼到 D 的委任中。
8. python scripts/audio.py → audio/mezcla.wav 調整為 -14 LUFS（音樂和效果為合成；編輯檔案頂部的 EFECTOS 和 CAMBIOS）。
9. 用於疊代的渲染： 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 輪）。
10. 最終渲染，僅一次： node render.mjs --sub 6。絕對不要同時進行兩次渲染。
11. python SKILL_DIR/entregar.py . NOMBRE --ronda N --escritorio 並交付手機版本。
12. 貢獻到資料庫（預設啟用）： 遵循 biblioteca 技能的「貢獻新模型」部分 （nuevos.py → 準備 → 要將它們上傳到資料庫嗎？(S/n)）。如果使用者在此專案中已說過不，則不要詢問。

每個角色的努力等級與模型

請參閱儲存庫中 AGENTS.md 的完整表格（依 harness 分類）。摘要（Claude Code 名稱；其他 harness 使用等效的「快速/中等/深度」）：

角色	模型	努力等級
協調影片的會話	你正在使用的模型	medium
資料研究員與審查員 B	中等（Sonnet）	high
共享 3D 模型	中等	medium，上限 150k
場景建構者	中等	medium，上限 40 回合 / 120k
審查員 A、C、D	中等	medium（像 Haiku 這樣的小模型會違反規則：不允許）
場景的小型修正	中等	low
max	永不	花費太多時間且過度思考

代幣預算與會話

成本在於回合數 × 對話長度，而非你寫了什麼。規則：

• 每個影片使用一個全新的會話。 在150k上下文時進行交接：留下 AVANCE.md（記錄了什麼、下一步是什麼、 決定）並在一個讀取它的新會話中繼續。
• 僅在里程碑時通知： GUION LISTO、VIDEO RÁPIDO LISTO、TERMINADO 或當你卡住時。其他所有內容都記錄在 TIEMPOS.md 中，不通知。
• 主要會話中不要有螢幕擷取或圖片：這些由一個以文字回覆的子代理查看。
• 審查員預算：關於大綱的第 0 輪最多 2 輪；關於審查表的第 1 輪為 1 輪；關於影片的審查僅 1 輪，僅限 A 和 D。只有當某個區域評分低於 8.5 時，才進行第二輪。

建構者上限（保持原樣，貼在每個委任的結尾；對於共享模型，為 150k）：

預算：最多 40 個回合和 120k 上下文代幣。當達到任一上限時，在你的工作目錄中寫下 AVANCE.md（記錄了什麼、缺少什麼、你測試了什麼以及失敗了什麼）並以一行摘要結束；另一個代理將從那裡繼續。 不要閱讀引擎、完整的 CONTRATO 或其他部分：你需要的一切都在此委任中。永遠不要完整讀取超過 300 行的檔案：使用範圍或 grep。螢幕擷取僅能透過 node render.mjs --probe <seg> --mitad，且每 5 個回合最多 1 張。在請求螢幕擷取之前，執行 revisar_hoja.py（不消耗代幣）。不要等待任何人：如果缺少某些東西，請在 AVANCE.md 中記錄並結束。

典型錯誤（保持原樣，貼在每個建構者委任中；（自動）= revisar_hoja.py 會捕捉）：

1. 淡入中的雙重文字（自動）：在新文字完全進入之前（進入時間 < 0.15 秒）完全移除舊文字，或使用硬切；同一區域永遠不要同時有兩個標題。
2. 光暈和輝光（自動）：周圍發光的球體、圓盤或聚光燈會被解讀為眼睛或太陽。使用平面發光，不要使用徑向精靈；如果某些東西會發光，它應該是拉長的，且沒有環。
3. 雙胞胎（自動）：兩個大小和亮度相同的窗戶、聚光燈或球體放在一起會被解讀為眼睛。使用不同的大小、不同的高度，或只使用一個。
4. 白色色塊（自動，警告）：不要使用帶有 blooms 效果的純白色；使用調色板顏色，霧面。
5. 污點和雜散點（自動，警告）：孤立的粒子、標題後方的陰影、殘留的邊緣。
6. 超出安全區域（自動）：沒有任何東西在 y < 215 或 y > 1450（卡拉 OK 區域）；沒有東西穿過標題。
7. 亮度跳躍（使用 --ronda 時自動）：平均亮度 60-90，鏡頭之間跳躍不超過 25。
8. 重複：標題和卡拉 OK 中同時出現相同的文字；每個創意只使用一個標題。
9. 臉部和手部：人物應背對鏡頭或顯示 3/4 背面；手應從側面或手背進入。
10. 文字太小：所有文字 >= 42px（標題 >= 52px）。

渲染：時間花在哪裡（在配備整合 GPU 的 4 核心筆記型電腦上測量）

步驟	每幀
從 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(seed)）或跨幀的狀態。保護 t < 0 的情況。
• 攝影機運動應 ≥ 0.6 秒，並使用 inOutCubic：使用 --sub 6 時，快速運動會產生鬼影。
• 如果測試結果出現其他幀的片段，表示另一個程序正在同時渲染：重新執行一次。
• 渲染結束時的 "Failed to load resource" 404 錯誤是正常的；真正的錯誤是 pageerror。
• 使用 scene.environment 時，three r186 使用 scene.environmentIntensity，而非材質的 envMapIntensity。
• 來自資料庫的粒子（three.quarks）是基於時間的確定性系統：不要移動群組，使用其 pos 屬性。
• 用於滑鼠調整的面板：在 URL 中加入 ?ajustes=1（參閱 biblioteca/base/LEEME.md）；渲染器永遠不會載入它。
• 真實材質（照片、檔案片段）：Wikimedia Commons 和 Internet Archive 包含公有領域和 CC BY 授權的內容；在描述中標註出處。