cassieliang6709/tech-explainer-video

Video de Explicación Técnica

Tres barreras, cada una requiere que el usuario diga explícitamente "vale" para pasar a la siguiente. La configuración global del usuario "hacer sin confirmar" no se aplica a estas tres barreras; es un proceso de revisión que el usuario ha solicitado específicamente para esta skill. Si el usuario dice "no pongas voz aún / no hagas aún", se detiene en la fase actual.

Valores predeterminados (si el usuario no los especifica, se usan estos y se escriben en el front matter de script.md):

• Audiencia: estudiantes universitarios que saben Python y prácticamente han olvidado el curso relacionado. Redacción según references/kepu-style.md: primero lo concreto, luego lo abstracto; "si tuvieras que diseñarlo tú"; un diagrama físico que recorra todo el vídeo; máximo 6 términos nuevos por episodio; los detalles de registros y nivel de código fuente se colocan en el capítulo "Avanzado" al final de cada episodio.
• Objetivo: que al terminar, el espectador pueda escribir el código en PyTorch.
• Estructura: tres partes: principio matemático → herramientas de PyTorch a usar → codificación unificada.
• Dentro de cada episodio usar "general—específico—general": al principio, dar la pregunta que responde el episodio y un mapa de las secciones; en el cuerpo, desarrollar cada sección (mostrar un mapa de ruta en la esquina de la pantalla con la sección actual resaltada); al final, resumir cada sección en una frase y avanzar el siguiente episodio.
• Duración: 8–12 minutos por episodio (cambio del usuario el 2026-10-24: menos episodios, menos envíos, menos riesgo de chocar con límites de plataforma). Un tema suele tener 2 episodios, como máximo 3.
• Analogías: permitidas, pero solo para un punto: una frase y volver al tema; un concepto, como máximo una analogía (punto 5 de kepu-style.md).
• Voz: voice: volc (voz predefinida de Volcengine zh_female_vv_uranus_bigtts); si faltan credenciales en ~/.volc_tts.env, tts.py retrocede automáticamente a edge-tts con la voz Xiaoyi y muestra un aviso.

Fase 0: Recopilación de Materiales

Si el usuario menciona apuntes (por ejemplo, de Obsidian), primero encontrarlos y leerlos por completo. Basarse en la estructura, conclusiones y cifras de los apuntes.

Fase 1: Esquema (proporcionado en la conversación)

En la primera línea, escribir una frase de aprobación del proyecto: "Este episodio hará que las personas de X puedan Y después de verlo". Para cada episodio, proporcionar una línea con gancho de portada + visual derecha (ver references/cover-guide.md), y revisarlo junto con el esquema. Siguiendo references/outline-template.md, escribir una tabla breve: problema que resuelve cada capítulo, nuevos conceptos, código final, duración, así como plan de división en episodios y contenido que no se cubre. Leer primero references/kepu-style.md. Diseñar el inicio, ritmo, términos y final según la "fórmula de inicio", "ritmo", "términos y umbral" y "fórmula de final" de references/script-guide.md; en el esquema, marcar dónde se coloca cada punto culminante en qué capítulo. Al escribir la parte matemática, dar primero el objetivo del cálculo (por ejemplo, out_i = Σⱼ aᵢⱼ vⱼ), luego deducir cada componente, haciendo que el producto punto, softmax y escalado aparezcan "solo cuando sean necesarios".

Fase 2: Código → Guion → Revisión → Anotaciones → Versión Final

Principio de redacción: primero contar la motivación del diseño, luego el mecanismo, y finalmente el resultado. Priorizar explicar "qué problema había originalmente → qué quería resolver el diseñador → por qué eligió esta solución → cómo funciona". Se permite añadir pasos, ejemplos y la precisión necesaria, pero solo introducir los nuevos conceptos imprescindibles para entender el principio actual; cuando aparezca un nuevo término por primera vez, explicarlo usando conocimientos previos o ejemplos concretos. El capítulo avanzado se ajusta según los conocimientos previos presupuestos para ese capítulo.

1. Escribir el código del tutorial py/tutorial.py y ejecutarlo realmente, usando show(key, value) para exportar py/values.json. Todos los valores numéricos, formas, True/False en pantalla provienen de aquí.
   • Si un ejemplo pequeño necesita tener un significado interpretable, establecer los pesos manualmente y explicar tanto en los comentarios del código como en la narración: "establecido manualmente, en un modelo real se aprende por entrenamiento".
   • Para demostrar "por qué", usar comparaciones reales: por ejemplo, allclose de la propiedad asociativa con y sin softmax, norma de Jacobi de softmax antes y después del escalado.
2. Según references/kepu-style.md y references/script-guide.md, escribir script/script.md (formato más abajo) y revisar ambas listas de verificación. Cada línea "Dibujar:" debe describir claramente qué cambio ve el espectador y qué ayuda a entender esta imagen; determinar primero el objetivo expresivo, sin fijar la herramienta de producción. Las imágenes pueden realizarse con lienzo web, Remotion, Manim, Blender u otra herramienta más adecuada, eligiendo según el plano una vez finalizada la versión definitiva. Las imágenes que necesiten valores numéricos, código o formas deben ser coherentes con py/values.json y py/tutorial.py. Verificar duración por episodio: número de caracteres del número de línea ÷ 4.5 ÷ 60, más aproximadamente 0.5 minutos para tarjetas de capítulo y pausas. Si supera los 12 minutos, ajustar la división en episodios en este paso (no esperar a tener la voz grabada para descubrir que es demasiado largo).
3. Tras completar el borrador inicial, realizar en orden: verificación de umbral para principiantes, comprobación de hechos y pulido del lenguaje: 3b. Verificación de umbral para principiantes (obligatorio): iniciar otro agente, darle solo script.md y una frase de configuración: "Sabes Python, pero prácticamente has olvidado el curso de este tema". No darle código ni apuntes. Que el agente marque frase por frase: ① términos que no entiende o saltos en el razonamiento; ② lugares donde se introducen demasiadas cosas nuevas en una frase y hay que volver atrás; ③ puntos donde la descripción visual y la narración no coinciden. Exigir que señale qué paso de explicación falta concretamente, especialmente comprobando si se puede seguir la secuencia "problema → motivación de diseño → mecanismo → resultado". Puede sugerir añadir pasos, ejemplos o la precisión necesaria, pero sin introducir conceptos nuevos no relacionados con la línea principal para añadir detalles. Modificar punto por punto y volver a comprobar con las mismas condiciones hasta que no queden marcas de tipo ① o ②; las de tipo ③ también deben corregirse. Registrar la lista de modificaciones y entregarla al usuario junto con el envío. El capítulo avanzado se verifica según los conocimientos previos presupuestos para ese capítulo. 3c. Comprobación de hechos (obligatorio): iniciar otro agente, darle script.md y los apuntes. Que marque solo errores factuales o afirmaciones que puedan llevar a una comprensión errónea, indicando la base; no se requiere complementar puntos de conocimiento, condiciones de contorno o detalles adicionales. Se permiten simplificaciones didácticas; si el público podría tomar la expresión simplificada como una definición estricta, añadir una breve aclaración en la narración: "esto es una simplificación". Al corregir, priorizar expresiones igual de simples pero precisas, sin acumular calificativos. En caso de conflicto con el punto 3b, buscar una expresión que sea a la vez precisa y fácil de entender; no mantener errores factuales, pero tampoco dejar que la precisión opaque la línea principal de la explicación. Si la corrección de hechos afecta la comprensión o las imágenes, repetir la verificación 3b correspondiente. 3d. Usar la skill humanizer-zh para pulir frase por frase las líneas numeradas y las líneas "Leer:" (eliminar el estilo AI). Mantener el significado de los valores numéricos, términos, código y líneas "Dibujar:". No añadir ni eliminar puntos de conocimiento por cuenta propia. Tras el pulido, volver a verificar que los resultados del código, las descripciones de las imágenes y la narración sean coherentes, y recalcular la duración de cada episodio.
4. Enviar el archivo al usuario (SendUserFile) y pedirle que escriba anotaciones debajo de las frases comenzando con > (también vale > [!批注] de Obsidian). Si quiere anotar en Obsidian, que copie el archivo a su vault, lo modifique y luego lo lea de vuelta.
5. Procesar las anotaciones: modificar una por una → eliminar las líneas de anotación ya procesadas → listar en la conversación cómo se ha modificado cada una → volver a pedir al usuario que las revise, hasta que diga que es la versión definitiva.
6. Antes de la versión definitiva, no grabar voz ni crear imágenes formales. Para verificar si un plano complejo es realizable, se puede hacer un breve prototipo; el prototipo no sustituye la revisión del guion.

Formato de script.md

---
title: Attention → MHA → GQA
subtitle: De los principios matemáticos a la implementación en PyTorch
audience: Estudiantes universitarios con cierta base informática
voice: volc
volc_speaker: zh_female_vv_uranus_bigtts
volc_resource: seed-tts-2.0
episodes: ch0,ch1,ch2,ep1_end | ep2_start,ch3,ch4,ep2_end | ep3_start,ch5,ch6
episode_titles: Título del primer episodio | Título del segundo episodio | Título del tercer episodio
---

## ch0 | Apertura
1. Texto original del subtítulo, un compás de imagen por frase.
   - Leer: pronunciación TTS (solo si difiere del subtítulo; los símbolos se escriben como se pronuncian, el carácter polifónico "行" (háng) se escribe como "航")
   - Dibujar: qué aparece en pantalla en esta frase (obligatorio, el agente de imagen lo implementa según esto)
> Anotación: el usuario escribe aquí

## ep1_end | Avance del próximo episodio
1. El próximo episodio tratará…
   - Dibujar: tarjeta de final del EP1

• ID de capítulo: ch0, ch1, …; el inicio/final de episodio se marca con epK_start / epK_end, las imágenes las genera automáticamente la tarjeta de episodio genérica. Las nuevas frases también deben ser revisadas por el usuario.
• General—específico—general: epK_start escribe 2–3 frases: ① la pregunta que responde este episodio ② "Este episodio trata N cosas: …" (correspondiendo una a una con los capítulos del episodio); epK_end escribe 2–3 frases: una conclusión por capítulo + avance del próximo episodio. El capítulo de apertura (ch0) del primer episodio también debe incluir el mapa del episodio. El front matter episodes determina qué secciones aparecen en el mapa; los nombres de las secciones son los títulos de los capítulos.
• No es necesario dividir manualmente los subtítulos en fragmentos cortos; tts.py los divide automáticamente en fragmentos de ≤22 caracteres de ancho según los signos de puntuación.

Fase 3: Generación del Video

Seleccionar por plano el método de producción que mejor explique el principio: las relaciones bidimensionales, el código y los datos se pueden realizar con lienzo web, Remotion o Manim; las estructuras espaciales y los movimientos de cámara se pueden realizar con herramientas 3D como Blender. También se pueden usar nuevas herramientas más adecuadas, sin añadir complejidad a la explicación por usar una herramienta concreta. El template/ existente es la canalización de composición y entrega con Remotion; los planos realizados con otras herramientas primero se exportan como video o imágenes, se verifica que se puedan integrar en esa canalización manteniendo la sincronización de subtítulos, voz y ritmo, y luego se usan en los capítulos formales. Los componentes, rutas y comandos de references/visual-guide.md y references/agent-brief.md solo se aplican a los capítulos de Remotion; otras herramientas siguen sus propios principios de formato, combinación de colores, datos reales y autoinspección de imágenes.

1. Copiar template/ al directorio especificado por el usuario (por defecto ~/Videos/<tema>, preguntar primero) y colocar dentro py/, script/. Instalar dependencias una sola vez: para una serie (varios proyectos en el mismo directorio padre, por ejemplo ~/Videos/nudgecode-算法/<capítulo>/), instalar una vez node_modules en el directorio padre (copiar el package.json de template y hacer npm install), y cada proyecto hace ln -s ../node_modules node_modules; para un proyecto individual, instalar dentro del proyecto. npm install solo se ejecuta uno a la vez; la ejecución concurrente puede dañar los paquetes. Tras la instalación, verificar que existe node_modules/react-dom/index.js (este paquete se ha dañado en la caché de npm; si faltan archivos, copiar la misma versión desde otro proyecto).
2. python3 tools/md2json.py (si hay anotaciones sin procesar, lo rechazará) → python3 tools/scaffold.py → python3 tools/tts.py Genera public/audio/*, src/timeline.json. La voz se almacena en caché, solo se resintetizan las frases modificadas.
3. Hacer primero la apertura y el capítulo 1 para establecer el estilo visual (hacer primero el plano más difícil; el ritmo y las transiciones se basan en references/plotome-lessons.md). Los planos de Remotion se revisan con node tools/stills.mjs ch1 && tools/sheet.sh ch1; los planos realizados con herramientas externas se revisan a partir del material original y los fotogramas compuestos tras la integración. Enviar la vista previa al usuario. Si el estilo visual de la serie ya ha sido confirmado por el usuario (por ejemplo, el primer proyecto de la misma serie), no es necesario volver a mostrarlo al usuario; continuar directamente. stills.mjs reutiliza out/bundle (tools/bundle.mjs, que solo reempaqueta si los archivos fuente han cambiado), sin crear un nuevo directorio de empaquetado de ~90 MB en $TMPDIR cada vez.
4. Tras la aprobación del usuario, distribuir el resto de capítulos a varios agentes simultáneamente en un solo mensaje (cada uno de 1 a 2 capítulos):
   • Capítulos de Remotion: completar references/agent-brief.md y escribirlo como AGENT_BRIEF.md en la raíz del proyecto, copiar references/visual-guide.md como VISUAL_GUIDE.md. Para los planos de herramientas externas, escribir una breve descripción de la tarea, acordar el formato del material, la duración, la ubicación del archivo y la responsabilidad de la integración con Remotion, sin aplicar la restricción de solo poder modificar ChN.tsx.
   • Si se cambia la narración, enviar un SendMessage al agente correspondiente indicando qué frases han cambiado y que la línea de tiempo se ha actualizado.
5. Una vez que todos los capítulos hayan vuelto, la sesión principal revisa los fotogramas compuestos capítulo por capítulo: superposiciones, subtítulos aplastados, coherencia entre la imagen y "Dibujar:", si los valores numéricos provienen de values.json; para material externo, verificar también la duración y el ritmo tras la importación.
6. Tras pasar npx tsc, ejecutar en segundo plano tools/render.sh: genera por episodio out/epK.mp4 + out/epK.srt + out/covers/epK.jpg, y normaliza a -16 LUFS. Aproximadamente 1 minuto de renderizado por minuto de video. Durante el renderizado, no mover archivos de audio ni código: la mezcla de audio solo lee el audio en el último paso; sobrescribir a mitad de camino mezclaría audio nuevo y viejo. render.sh usa un bloqueo a nivel de máquina (lockf /tmp/remotion-render.lock) para asegurar que solo se renderiza un episodio a la vez: renderizar varios proyectos simultáneamente no es más rápido (la CPU ya está al máximo), solo consume más memoria y disco. Varios proyectos pueden iniciar render.sh simultáneamente; se pondrán en cola automáticamente.
7. Portada: según references/cover-guide.md, escribir por episodio src/covers/CoverEpK.tsx y registrarlo en src/covers/index.ts (fondo negro, gancho en letra grande + resaltado en fondo amarillo, gran visual a la derecha); render.sh generará automáticamente out/covers/epK.jpg. Los episodios no registrados usarán una versión genérica. Mostrar al usuario todas las portadas juntas en una imagen. Para regenerar una sola: npx remotion still out/bundle cover-epK out/covers/epK.jpg.
8. Entrega: usar SendUserFile para enviar los mp4, srt, portadas y py/tutorial.py de cada episodio. Pedir al usuario que lea los srt por sí mismo; a menudo se encuentran problemas.
9. Cuando sea necesario publicar, pasar a la skill video-publish. Antes de publicar, revisar la lista de cumplimiento de references/plotome-lessons.md (marcado de IA, licencias de música, atribuciones).

Producción en serie (múltiples proyectos en paralelo)

• Mantener entre 3 y 4 sesiones abiertas simultáneamente: abrir demasiadas pronto alcanzará el límite de uso, y la TTS de Volcengine también reportará superación del límite de concurrencia (tts.py ya incluye retroceso con reintentos, concurrencia 2).
• La paralelización se aplica solo a la redacción y creación de imágenes; el renderizado se deja en la cola con el bloqueo a nivel de máquina de render.sh.
• Disco: cada capítulo out/bundle ocupa ~90 MB, las capturas out/check decenas de MB, el video final unos pocos MB por episodio. Antes de iniciar un nuevo lote, mirar df -h. Los directorios $TMPDIR/remotion-webpack-bundle-* son empaquetados temporales dejados por scripts antiguos; se pueden limpiar.
• Cuando el usuario acepte "renderizar un lote → subir directamente → eliminar videos finales", ver la "cadena de producción en lote" de video-publish.

Cadena de producción de la sesión principal (probada con la base de conocimiento del 30-10 al 03-11, dos artículos por lote)

1. Agentes de fase de escritura (uno por artículo, dos simultáneos): esquema → ejecutar tutorial real exportando values.json → guion → verificación de umbral para principiantes (iniciar otro agente, máximo 8 rondas, luego modificar todo según la última ronda) → comprobación de hechos (iniciar otro agente comparando con los apuntes) → humanizer → verificar duración por episodio → copiar template, enlazar node_modules → md2json / scaffold / tts → escribir AGENT_BRIEF.md, VISUAL_GUIDE.md, componentes compartidos del diagrama físico src/lib/<nombre>.tsx (primero definir constantes de diseño) → hacer ch0, ch1. En el informe, listar "discrepancias entre apuntes y pruebas reales".
2. La sesión principal mira el mosaico ch0/ch1. Si el estilo visual está bien, continuar, sin esperar al usuario.
3. Distribución de imágenes (fan-out): completar references/agent-brief.md como un brief compartido y escribirlo en /tmp/claude-501/brief_<artículo>.txt (para el segundo artículo, usar sed para cambiar rutas/nombres de componentes/nombres de bloqueo y luego añadir "Complementos de este proyecto"). Cada agente recibe un prompt de una sola frase: "Primero lee el brief completo con Read y síguelo estrictamente. Te encargas de chX, chY". Cada uno de 2 a 3 capítulos; la portada se la queda el último agente. Iniciar todos simultáneamente en un solo mensaje.
4. Recopilar problemas conocidos: cuando cada agente de imagen vuelva, anotar los "problemas conocidos / valores no en values.json / modificaciones sin revisar" que reporte.
5. Agente de revisión completa del video (uno por artículo, plantilla references/review-brief.md): escribir los problemas resumidos en el paso 4 uno por uno en "Pendiente de corregir".
6. Renderizado: cada artículo inicia tools/render.sh en segundo plano; el bloqueo a nivel de máquina los pone en cola automáticamente. Usar un bucle until en segundo plano esperando a que aparezca out/ep3.mp4.
7. Inspección aleatoria (la sesión principal la hace, sin fiarse de informes): por cada episodio ffmpeg -af volumedetect (normal media ~ −19 dB, max ≤ −1.2 dB); de cada artículo tomar un episodio y hacer -vf "fps=1/60,scale=480:-1,tile=4x3" para componer una cuadrícula y leerla con Read; confirmar que los tres archivos en out/covers/ están presentes.
8. Subida: out/parts/P<k> <gancho>：<tema>.mp4 enlace duro + out/upload_meta.md (incluyendo un párrafo adicional de descripción), luego ponerlo en cola según "Añadir a envíos existentes" de video-publish. Tras la subida, actualizar PROGRESS.md y el tablero, y enviar el párrafo de descripción al usuario.

Límite de uso / Interrupción

• El límite de uso matará a todos los agentes en ejecución. Tras la recuperación, usar SendMessage para enviar "continúa" a cada agente; retomará con el contexto. No abrir nuevos agentes (duplicarían trabajo y se sobrescribirían entre sí).
• Mantener el número de agentes ejecutándose simultáneamente en ~12 o menos (2 artículos × 5-6 agentes de imagen).

Discrepancias entre apuntes y pruebas reales

• Los apuntes de la base de conocimiento (vault) son de solo lectura. Cuando las pruebas reales y los apuntes no coincidan, el video se basa en las pruebas reales. Listar las discrepancias una por una en el informe para que el usuario decida si modificar los apuntes.

Modificaciones tras la versión definitiva

• Modificar la narración: cambiar script.md → md2json → tts (solo resintetiza las frases modificadas) → revisar las imágenes de los capítulos afectados.
• Cambiar el número de frases puede desalinear las imágenes: en los capítulos cuyas imágenes ya están hechas, modificar solo la redacción, sin añadir ni eliminar frases; si hay que añadir contenido, hacerlo como una nueva frase de capítulo (por ejemplo, epK_start).
• El agente de imagen solo implementa según visual; si tiene dudas, informa a la sesión principal, no modifica la narración por su cuenta.

Voces

• Voz predefinida de Volcengine (por defecto, voice: volc): zh_female_vv_uranus_bigtts, recurso seed-tts-2.0. Fue la elegida por el usuario para el proyecto GQA, con resultados claramente mejores que edge-tts. Si el front matter no especifica volc_speaker, se usa esta. Las credenciales están en ~/.volc_tts.env (ya configurado); solo se necesita VOLC_APPID / VOLC_TOKEN; opcionalmente VOLC_SPEED para la velocidad (1.0 normal).
• Cambiar de voz: en el front matter, escribir volc_speaker: <ID de voz>. Las voces predefinidas usan automáticamente seed-tts-2.0; las voces clonadas que comienzan con S_ usan automáticamente seed-icl-2.0 (o VOLC_RESOURCE del entorno). También se puede especificar explícitamente con volc_resource; escribir v1 usa la interfaz antigua, y entonces se puede configurar VOLC_CLUSTER (por defecto volcano_icl).
• La voz clonada del usuario (VOLC_SPEAKER_ID del entorno, comenzando con S_) actualmente da error resource ID is mismatched with speaker. Primero confirmar la versión de la voz, el estado de entrenamiento y el appid en la consola de Volcengine; no usarla hasta que funcione.
• No imprimir el contenido del archivo de entorno. Para proyectos nuevos, primero sintetizar con --only unas pocas frases de un episodio para probar, luego generar todo el video.
• edge-tts (alternativa): voice: zh-CN-XiaoyiNeural, otras opciones: YunxiNeural, YunyangNeural, XiaoxiaoNeural. Cuando faltan las credenciales de Volcengine, tts.py usa automáticamente Xiaoyi.
• Cambiar de voz solo requiere volver a ejecutar tts.py; las imágenes se alinean automáticamente al ritmo; basta con una inspección aleatoria del mosaico.

Voz en inglés (2026-11-03)

• edge-tts en-US-AndrewMultilingualNeural: el usuario la seleccionó tras probar 9 voces. Gratuita, sin clave, pero usa una interfaz no oficial de Edge: puede limitar la tasa o desconectarse (tts debe reintentar), su uso comercial no está claro, y la interfaz podría cambiar en cualquier momento. En el front matter: voice: en-US-AndrewMultilingualNeural.
• De Volcengine seed-tts-2.0: en_male_tim_uranus_bigtts, en_female_dacey_uranus_bigtts disponibles (alternativas); las voces en inglés de seed-tts-1.0 (*_mars_bigtts) dan error 403 en esta cuenta (no activadas). La voz china vv también puede leer inglés, pero con acento notable.
• Prueba: un mismo fragmento de ~20 segundos de introducción en inglés, generar un mp3 por cada voz, luego concatenar con ffmpeg (añadiendo apad de 1.2 segundos entre cada una) y enviar al usuario como una compilación.

Bilingüe chino-inglés (en prueba)

• Proyecto piloto ~/Videos/知识库/llm-13-rag-agent-en: narración oral en inglés recién escrita (no traducida del chino), cada frase con traducción al chino, dos líneas de subtítulos en la parte inferior (inglés arriba, chino un poco más pequeño abajo), etiquetas de imagen en inglés.
• Los cambios concretos en el componente de subtítulos y en md2json se escribirán aquí y en template una vez finalizado el piloto.
• La versión en inglés no se añade a las compilaciones en chino; el lugar de publicación (nuevo envío en Bilibili / YouTube) lo decide el usuario.

Resumen de archivos (template/)

Archivo	Función
tools/md2json.py	script.md → script.json (revisa anotaciones, divide episodios)
tools/scaffold.py	Genera componentes placeholder de capítulos y src/chapters/index.ts
tools/tts.py	Sintetiza voz frase por frase, divide subtítulos cortos, escribe timeline.json; soporta edge-tts / Volcengine
tools/stills.mjs + sheet.sh	Captura al 80% de cada frase y compone en mosaico 3×3 (SCALE=1 para tamaño completo)
tools/render.sh	Renderiza por episodio + fusiona subtítulos + normaliza sonoridad
src/lib/beat.tsx	Sincronización de ritmo (useBeat), tarjetas de título de capítulo, subtítulos
src/lib/ui.tsx	CodePanel / Matrix / Fade / Tag / H / Tex (fórmulas KaTeX)
src/lib/EpCard.tsx	Tarjetas de inicio y final de episodio
src/lib/Cover.tsx + src/covers/	Componentes de portada (CoverFrame / Hl / CodeVisual / BigNumber) + registro de portada personalizada por episodio
src/lib/algo.tsx	Componentes de tipo algoritmo: cuadrícula de array, dict, tabla de trace, tarjeta de enunciado
tools/bundle.mjs	Empaqueta una vez y reutiliza out/bundle
src/lib/library.tsx	Opcional: componente de metáfora de "biblioteca" de tensores (Building / Corridor)

Documentos de referencia

• references/script-guide.md: Cómo escribir el guion; outline-template.md: tabla de esquema
• references/visual-guide.md / agent-brief.md: Especificaciones de imagen, instrucciones para el agente de imagen
• references/cover-guide.md: Especificaciones de portada
• references/plotome-lessons.md: Ritmo, transiciones, música, cumplimiento (inspirado en plotome)
• references/production-retro-2026-10.md: Retrospectiva de la producción en lote de los 13 capítulos de nudgecode, problemas y soluciones
• references/production-retro-2026-11.md: Retrospectiva de la cadena de producción de dos artículos por lote de la base de conocimiento
• references/review-brief.md: Plantilla para el agente de revisión completa del video
• rethinkfun-style.md / cishoon-style.md: Análisis de los creadores favoritos del usuario

Errores cometidos

• say de macOS es demasiado robótico; usar edge-tts.
• El código y los símbolos deben escribirse como se pronuncian en las líneas "Leer:"; el carácter polifónico "行" (háng) se escribe como "航".
• Antes de hablar de las cifras de un modelo real, verificar su estructura (por ejemplo, Llama-2-70B ya es GQA; si se calcula con 64 cabezas y 10 GB, hay que decir "suponiendo que se usara MHA").
• La atención inicializada aleatoriamente es demasiado uniforme y no tiene sentido: o establecer los pesos manualmente, o cambiar la semilla aleatoria para elegir una con contraste más evidente.
• Las capturas con tools/stills.mjs (solo empaqueta una vez) son mucho más rápidas que remotion still; la primera renderización descargará headless Chrome.
• En Bash, no usar cat > file sin entrada; se quedará esperando stdin indefinidamente.
• Las capturas se hacen al 80% de cada frase: las animaciones que aparecen después del 80% (aspa roja, letras grandes tardías) no se capturan; hay que capturarlas por separado o adelantar el momento de aparición.
• Cuando los agentes de imagen trabajan en paralelo, un error de sintaxis en el capítulo de otro puede hacer que el bundle falle: esperar uno o dos minutos y reintentar; no modificar los archivos de otros.
• Un agente de revisión "limpió" capturas antiguas: en el brief hay que escribir "no eliminar ningún archivo (sobrescribir capturas está bien)".
• Disco: cada proyecto de artículo ocupa ~0.5 GB, el video final unos pocos MB por episodio; llenar el disco durante el renderizado dará error No space left on device. Antes de iniciar un nuevo lote, hacer df -h; si está por debajo de ~15 GB, listar los grupos que se pueden limpiar (cachés de herramientas, conda clean, etc.) para que el usuario elija; la eliminación requiere su aprobación.
• Las tarjetas de título de capítulo y las de inicio/final de episodio añaden ~10 segundos por episodio; estimar la duración final como duración real de la TTS + 10 segundos.
• Los agentes de imagen pueden registrar src/covers/index.ts por su cuenta: esto es necesario para las portadas, se permite.
• No usar pgrep -f render.sh para esperar la renderización en segundo plano: la línea de comandos del comando de espera también contiene esa cadena, pgrep siempre coincidirá consigo mismo, causando un bucle vacío durante horas. Esperar solo a que aparezca out/epK.mp4 (o un error en el registro).