makunrui80-oss/freedom-video-skill

Estudio de Generación de Video Freedom

Construye videos reproducibles a partir de un tema, guión, prompt o ejemplo en Python. El renderizado con Manim es obligatorio para escenas deterministas y animación de código o diagramas; un modelo de video en la nube configurado puede agregar o generar otro metraje. Mantén el flujo de trabajo portable entre Codex, Claude, Gemini, OpenClaw, Hermes, DeepSeek, Kimi, WorkBuddy o un script Python normal.

Separa las Dos Capas de Proveedores

• Usa un proveedor de agente solo para escribir el plan de lección, la narración, los subtítulos, los prompts y el código fuente de Manim/Python. Se pueden usar endpoints de chat compatibles con OpenAI para proveedores como DeepSeek, Kimi o Hermes.
• Usa un proveedor de video solo para generar o mejorar clips de video. Nunca envíes un trabajo de video a un endpoint de chat-completions.
• Trata a Agnes Video 2.5 Flash como un valor predeterminado opcional, no como una dependencia estricta.
• Lee references/provider-config.md antes de configurar o llamar a cualquier proveedor.

Flujo de Trabajo Obligatorio

1. Crea un directorio de proyecto de salida. Mantén dentro de él el código fuente, el audio, los subtítulos, los renders y los registros.

2. Antes de escribir o renderizar la lección, ejecuta:

   python3 scripts/ensure_manim.py --project-root <PROYECTO_SALIDA>
   

   Este paso es obligatorio. Encuentra o instala Manim en <PROYECTO_SALIDA>/.venv-manim, verifica la versión y realiza un render de prueba real. Detente si falla. Usa la ruta del ejecutable de Manim que imprime el script para renders posteriores.

3. Cuando se requiera narración, ejecuta esta configuración obligatoria antes de generarla:

   python3 scripts/ensure_kokoro.py --project-root <PROYECTO_SALIDA>
   

   Instala el stack fijo de Kokoro Chinese en <PROYECTO_SALIDA>/.venv-kokoro, conserva la revisión solicitada de la fuente kokoro-tts-zh en .vendor, descarga el modelo/voz seleccionado en el primer uso y sintetiza un WAV de prueba real. Detente si falla algún paso. Lee references/audio-config.md para obtener información sobre voces y comandos de narración.

4. Produce un plan de lección temporizado. Para cada escena especifica narración, código en pantalla, animación, texto de subtítulo y duración. Usa Manim para conceptos de ejecución de código, cambios de estado, punteros, trazas, diagramas y gráficos educativos deterministas.

5. Genera la narración completa antes de fijar la temporización de la escena. Usa scripts/kokoro_narrate.py, usa por defecto la voz didáctica cálida zf_032 a velocidad 0.96, mantén una sola voz y una velocidad moderada constante dentro de una lección, y temporiza los visuales/subtítulos según el WAV medido y su manifiesto.

6. Renderiza un borrador de Manim y verifica que su duración medida, tamaño del fotograma, límites del texto, resaltado de código y transiciones coincidan con el plan de narración.

7. Solo llama a un proveedor de video en la nube cuando mejore materialmente la lección. Ejecuta la verificación de seguridad de facturación a continuación antes de cada trabajo facturable.

8. Ensambla el video final, luego verifica el audio, la temporización de los subtítulos, la legibilidad del código, la duración y la salida reproducible.

Política de Fuente de Narración

• Para cada video narrado, usa una voz china proporcionada por la familia de modelos kokoro-tts-zh integrada.
• Nunca uses say de macOS, SAPI de Windows, síntesis de voz del navegador u otra voz del sistema operativo como respaldo automático.
• Si la instalación de Kokoro, la descarga del modelo, la carga de la voz o la síntesis falla, detente e informa del fallo. No sustituyas silenciosamente una voz mecánica.
• Kokoro proporciona voces predefinidas; no clona un orador cargado arbitrariamente. La ruta de clonación del repositorio vinculado depende de un submódulo StableTTS separado y de pesos de modelo que no son autónomos ni están verificados por este Skill. Para una solicitud de clonación, requiere un backend de clonación configurado y validado por separado, además de la confirmación de que el usuario tiene permiso para usar la voz.

Verificación de Facturación Obligatoria

Antes de cada solicitud de video en la nube:

1. Consulta el endpoint de precios actual del proveedor o la fuente oficial de precios actual.
2. Consulta la cuota/créditos de la cuenta a través del endpoint de cuota configurado.
3. Calcula el costo máximo esperado usando la duración solicitada, la resolución, el modelo y el precio del proveedor.
4. Compáralo con VIDEO_MAX_COST_PER_TASK y los créditos disponibles.
5. Registra el resultado de la verificación en <PROYECTO_SALIDA>/usage/video-usage.jsonl.

No envíes el trabajo si el precio o la cuota son desconocidos, el endpoint no puede verificarse, los créditos son insuficientes o se superaría el costo máximo. Que un proveedor anuncie un nivel gratuito no demuestra que la solicitud actual sea gratuita.

Reglas de Reintento y Sondeo

• Nunca reintentes indefinidamente.
• Usa VIDEO_MAX_POLLS y VIDEO_POLL_INTERVAL_SECONDS para trabajos asíncronos.
• Reintenta fallos de red transitorios o errores HTTP 429/5xx como máximo VIDEO_MAX_RETRIES veces con retroceso exponencial con tope.
• Para errores de cola llena, capacidad completa, crédito insuficiente, autenticación, validación o política de precios, detente inmediatamente a menos que el proveedor proporcione explícitamente un Retry-After corto y el presupuesto de reintentos configurado permita un reintento.
• Nunca crees un trabajo de reemplazo solo porque falló el sondeo de estado; primero recupera el trabajo original por ID.

Libro de Contabilidad de Uso

Adjunta un objeto JSON por cada verificación y llamada al proveedor en <PROYECTO_SALIDA>/usage/video-usage.jsonl. Nunca almacenes claves de API ni encabezados de autorización. Incluye:

{"timestamp":"ISO-8601","provider":"nombre","model":"id","job_id":"id-o-nulo","requested_seconds":10,"actual_seconds":10,"call_count":1,"status":"exitoso","price_source":"endpoint-o-url","estimated_cost":0,"actual_cost":0,"currency":"USD","cost_known":true,"error":null}

Si el proveedor no devuelve el costo real, establece actual_cost como null y cost_known como false; no registres silenciosamente cero. Resume el total de llamadas, la duración generada, el costo conocido y las llamadas con costo desconocido al final.

Contrato de Salida

Entrega el video final junto con el código fuente editable de Manim, el WAV de narración de Kokoro y su manifiesto, archivos de subtítulos, una plantilla de configuración segura para el proveedor, el comando de renderizado y el libro de contabilidad de uso. Indica la voz/modelo/velocidad de Kokoro utilizados, y declara claramente cuando no se llamó a ninguna API de video en la nube o cuando no se pudo verificar el costo.

No expongas secretos en el código fuente, registros, prompts, historial del shell, capturas de pantalla o archivos .env confirmados. Usa variables de entorno y proporciona solo plantillas .env.example.