Pedrovbm1/explicador

Explicador animado（コードベース3Dモーショングラフィックス）

すべてはコードです。動画の各部分は 3D ワールド（escena/partes/<parte>.js）であり、それは時間の純粋関数です。motor.js がどのパートを表示するかを決定し、カラオケ字幕を描画します。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	コンストラクターへの短い依頼テンプレート（1エージェントあたり1パート）
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 にソースとともに記載すること。
• ペットや目のあるオブジェクトは禁止。 目として認識される形状も禁止（「典型的なエラー」参照）。
• デフォルトスタイル：暗い背景に暖かいハローを伴うクリーンなオブジェクト1つ、マクロカメラは常に滑らかに動き、キーワードは金色、ナレーション全体のカラオケ字幕、最初のフレームでループ。
• リズム：3.0〜3.2語/秒、約3秒ごとにフレームチェンジ、5秒以上静止なし、4.5秒以内にフック。
• 再生時間：単体の場合は15〜30秒。連続シリーズ（名前と番号あり）の一部の場合のみ60秒以上。

フロー

1. python SKILL_DIR/nuevo.py <テーマ>-YYYY-MM（カレントディレクトリにフォルダ作成）。開いて表示確認： npx http-server escena -p 8080（または escena/ 内で python -m http.server）を実行し、localhost:8080 にアクセス。
2. guion スキルでスクリプト作成：ソース付き調査、MAPA、ラウンド0（A ≥ 9、C ≥ 9、最大2ラウンド）、停止条件は GUION LISTO。ユーザーのOKなしに次に進まないこと。
3. 音声（クレジットまたはCPU時間を消費するため、OKの後に実施）：
   • 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（カラオケ用）。
4. CONTRATO 完成（escena/CONTRATO.md）：各パートのセクション B.*、各キーで何を表示するか、正確なテキスト表示、ソース付きデータ、セーフゾーン、リズム。これがコンストラクターが読む唯一の文書です。ここにないものは推測されます。motor.js の PLAN（パートの順序とトランジション）と CLAVE（カラオケの金色の単語）を変更します。
5. 3Dモデル：モデリングの前に、ライブラリを検索（biblioteca スキル、HOME3D/biblioteca/CATALOGO.md）、該当するものを コピー して escena/modelos/ に配置。不足分は1つのエージェントが作成（共有モデル、努力 medium、上限150k）、modelos/LISTO_<object>.txt で完了を通知。
6. コンストラクター、ENCARGO_CONSTRUCTOR.md を使用：
   • 1エージェントあたり1パート（1シーン ≤ 15秒）、バックグラウンドで実行、最大3つ同時；
   • 短い依頼：自分のセクション、モデル（1行でAPI使用）、ルールのみ；コンストラクターはモーターや完全な CONTRATO を読まない；
   • 「典型的なエラー」ブロックと「コンストラクターの上限」をそのまま貼り付ける；
   • 修正ラウンドごとに新しいコンストラクター、40ターンを超えたエージェントとの継続的な会話は禁止；
   • 他のエージェントを「待たせる」ことは禁止：最初に共有モデル、次にパート。
7. レンダリング前のレビューシート: node render.mjs --hoja（ビートごとに1フレーム：ビジュアルスクリプト）および 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。同時に2つのレンダリングを実行しないこと。
11. python SKILL_DIR/entregar.py . NOMBRE --ronda N --escritorio を実行し、モバイル版を納品。
12. ライブラリへの貢献（デフォルトで有効）: biblioteca スキルの「Aportar modelos nuevos」に従う（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（完了した内容、次に行うべきこと、決定事項）を残し、それを読む新しいセッションで続行。
• マイルストーンのみ通知： GUION LISTO、VIDEO RÁPIDO LISTO、TERMINADO、またはブロックされた場合。それ以外は TIEMPOS.md に記録し、通知しない。
• メインセッションではスクリーンショットや画像は使用しない：それらはテキストで応答するサブエージェントが確認する。
• レビュー担当者の予算：MAPA のラウンド0は最大2ラウンド。レビューシートのラウンド1は1回。動画のレビューはAとDのみで1ラウンド。2ラウンド目は8.5未満のエリアのみ。

コンストラクターの上限（各依頼の最後にそのまま貼り付ける。共有モデルの場合は150k）：

予算：最大40ターン、コンテキストトークン120k。いずれかに達したら、自分の作業フォルダにAVANCE.md（完了した内容、不足しているもの、試したが失敗したもの）を書き、5行の要約で終了。別のエージェントがそこから続行します。モーター、完全なCONTRATO、または他のパートを読まないこと：必要なものはこの依頼に含まれています。300行を超えるファイルを完全に読まないこと：範囲指定または grep を使用。スクリーンショットは node render.mjs --probe <seg> --mitad のみ、最大で5ターンに1回。スクリーンショットを要求する前に revisar_hoja.py を実行すること（トークンを消費しません）。誰かを待たせないこと：不足しているものがあれば AVANCE.md に記録して終了。

典型的なエラー（各コンストラクターの依頼にそのまま貼り付ける。（自動）は revisar_hoja.py が捕捉）：

1. フェード中の二重テキスト（自動）：新しいパネルが入る前に古いパネルを完全に除去（経過時間 < 0.15秒）するか、カットで切り替え。同じ領域に2つの看板を同時に表示しないこと。
2. ハローとオーラ（自動）：球体、ディスク、またはスポットライトに柔らかな輝きがあると、目や太陽のように見える。フラットなエミッシブ、放射状スプライトなし。何かが光る場合は、細長く、リング状にしないこと。
3. 双子（自動）：同じサイズと明るさの2つのウィンドウ、スポットライト、または球体が近接していると、目のように見える。サイズを変える、高さを変える、または1つだけにする。
4. 白飛び（自動、警告）：ピュアホワイトにブルームを使用しない。パレットの色、マット。
5. シミと孤立した点（自動、警告）：孤立したパーティクル、パネルの背後にある影、残ったエッジ。
6. 領域外（自動）：y < 215 または y > 1450（カラオケ）に何も配置しない。何もパネルを横切らないこと。
7. 輝度ジャンプ（自動、--ronda 使用時）：平均輝度 60〜90。ショット間で 25 を超えるジャンプなし。
8. 重複：同じテキストが看板とカラオケに同時に表示されること。1つのアイデアにつき1つの看板。
9. 顔と手：人物は後ろ向きまたは3/4後方。手は横または甲側から入る。
10. 小さな看板：すべて 42px 以上（パネルは 52px 以上）。

レンダリング：時間の内訳（統合GPU搭載4コアノートPCで測定）

ステップ	1フレームあたり
Chromeからフレームを取得（JPEG、ANGLE経由GPU）	~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 は使用禁止。各パートは1フレームあたり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素材があります。クレジットは説明に記入すること。