Presentación en vídeo web

Convertir un artículo o un guion de locución, paso a paso, en una «página web camuflada como vídeo» que permita la grabación de pantalla, con la opción de añadir audio de locución. Resultado final = proyecto en Vite + React + TS + audio dividido por secciones.

Casos de uso

• «Tengo un guion de locución o un artículo, ayúdame a convertirlo en un vídeo» — Contenido impulsado por la locución
• Quiero crear una «presentación de PowerPoint dinámica»
• Grabación de pantalla en formato horizontal 16:9, con letras grandes, espacios en blanco y efectos de animación en cada pantalla
• Formación / Demostración de productos / Keynote: se busca un estilo cinematográfico
• Contenido para Bilibili / YouTube / Douyin

Esta Skill se centra en la metodología y el proceso de colaboración. Las plantillas de andamiaje proporcionan tokens y primitivas, pero cada decisión estética (paleta de colores, tipografía, estilo de los efectos de animación) debe rediseñarse en función de tu tema — no las copies tal cual.

Resumen del flujo de trabajo

Phase 1   内容编写
   1.1  识别用户输入
   1.2  一次产出 script.md + outline.md
        （口播稿 + 开发计划）
   ▼
[Checkpoint Plan]      ← 必须停。一次对齐 5 件事：
                         稿子 / outline / 主题 / 素材 / 开发模式
   ▼
Phase 2   网页开发
   2.1  脚手架（按选定主题）
   2.2  第 1 章 = 主线程 + 完整版本（强制 anchor）
        ▼
        [硬节点] 用户验收第 1 章 ← 不可跳过
        ▼
   2.3  第 2~N 章（按选定模式：A 逐章 / B 顺序 / C 并行）
   ▼
[Checkpoint Audio]     ← 必须停。是否合成音频
   ▼
Phase 3   音频合成（可选）
   ▼
Phase 4   录屏 + 后期

Convenciones del directorio de trabajo (el agente crea y edita en el directorio actual del usuario):

my-video/
├── article.md          # 用户给原文时必有 —— 不删！开发阶段画面信息源
├── script.md           # 必有：保持原文语言的平台化口播稿（决定节拍）
├── outline.md          # 必有：开发计划（章节切分 + 每步内容 + 信息池）
└── presentation/       # 脚手架产出的 Vite + React + TS 项目
    ├── src/chapters/-/
    │   ├── .tsx     # 视觉实现
    │   ├── .css
    │   └── narrations.ts     # ★ step 数 + 口播文本的唯一真相源
    ├── scripts/
    │   ├── extract-narrations.ts   # 扫所有 narrations.ts → audio-segments.json
    │   ├── synthesize-audio.sh     # provider-agnostic runner（循环 segments）
    │   └── tts-providers/          # 每 provider 一个 .sh（内置 2 个）
    │       ├── README.md           # 三函数契约 + 5 段现成代码片段（11labs / edge-tts / say / azure / gcloud）
    │       ├── minimax.sh          # 默认 provider，用 mmx-cli
    │       └── openai.sh           # 内置 OpenAI TTS（curl + OPENAI_API_KEY）
    ├── audio-segments.json         # extract 产出（合成前 review）
    └── public/audio//.mp3   # 可选：合成的音频

Clave:narrations.ts es la única fuente de verdad en cuanto al número de pasos y la síntesis de audio. Capítulo .tsx el if (step === N) debe ser igual a narrations.length. Esto garantiza que en cinco lugares (script / outline / código de capítulos / chapters.ts / archivos de audio) nunca haya discrepancias.

Protocolo de autocomprobación estricto (aplicable a toda la Skill)

Los tres resultados siguientes deben pasar, una vez completados, por el proceso de autocomprobación → corrección → nuevo informe / avance:

Métodos de ejecución (por orden de capacidad, dando prioridad a los métodos más aislados):

1. Agent Teams (óptimo) : abrir un agente revisor independiente, proporcionarle la «ruta del archivo de salida + la lista correspondiente + el contexto clave», y dejar que lo compruebe punto por punto e informe rigurosamente de sus conclusiones (qué elementos se han superado y cuáles han fallado, junto con las pruebas y las recomendaciones de corrección).
2. subAgent (segunda mejor opción): si no se dispone de la capacidad de Teams, pero se puede iniciar un subagent, utilícelo siguiendo el mismo proceso.
3. Autocomprobación (opción de último recurso) : si ningún agente dispone de las capacidades mencionadas, se debe realizar una comprobación rigurosa punto por punto por cuenta propia; no se permite dar el visto bueno tras un simple vistazo.

Regla de oro: una vez obtenidas las conclusiones, modifica primero el producto según los elementos «fallidos» y, a continuación, informa al usuario de «conclusión de la autoverificación

• conclusiones de la autoverificación + qué se ha corregido». Informar directamente de las conclusiones originales sin realizar las correcciones = incumplimiento.

Guía de lectura de documentos en cada fase

En cada fase hay que consultar los documentos correspondientes. En las sesiones largas, los agentes tienden a olvidar los principios, especialmente el «capítulo de implementación» de la Fase 2.4, que se repite N veces; hay que volver a consultar las restricciones fundamentales cada vez.

Al escribir los capítulos, consulta únicamente este documento: CHAPTER-CRAFT.md. Los diez principios, la autoestimulación al comenzar, el árbol de decisión, los patrones para evitar el «sabor a IA» y la autoevaluación al finalizar se incluyen todos en este único documento de referencia.EXAMPLES/ No es de lectura obligatoria : primero diseña libremente según el contenido y solo consulta este documento si te quedas atascado (utiliza los enlaces de anclaje para consultar la «estructura», no lo copies tal cual).

Fase 1 —— Redacción del contenido (elaboración única)

1.1 Identificar la entrada del usuario

1.2 Resultado en una sola sesión: script.md + outline.md

Ambos resultados se completan en una sola sesión de reflexión:

1. Generación de «script.md»: siguiendo references/SCRIPT-STYLE.md las reglas, se convierte el artículo en un guion de locución adaptado a la plataforma, conservando el idioma original. Se conserva el archivo «article.md» sin borrarlo, ya que es la fuente de detalles para el «outline» a la hora de crear el banco de información y las secuencias de imágenes correspondientes a cada sección (principio de las dos fuentes).
2. Generación de «outline.md»: siguiendo references/OUTLINE-FORMAT.md las reglas: dividir en capítulos + dividir en pasos + extraer el conjunto de información del primer párrafo de cada capítulo.

Límites de «outline» (fundamental):

Motivos para no incluir animaciones en el esquema: las animaciones fijas = el «agente de capítulo» se reduce a una mera máquina de traducción; el espacio en blanco permite que el «agente de capítulo» diseñe libremente, según CHAPTER-CRAFT.md el «árbol de decisión impulsado por el contenido», lo que le da una auténtica sensación de vídeo. Para más detalles, véase CHAPTER-CRAFT.md la Parte 0, principio 7.

Tras la ejecución, debe realizarse primero una autoverificación antes de pasar al Plan de puntos de control: según el «Protocolo de autoverificación obligatorio» mencionado anteriormente, se deben ejecutar por separado script.md / outline.md (priorizando: equipos de agentes → subagentes → autocomprobación), y solo tras completar las correcciones según las conclusiones se podrá acceder al Plan de puntos de control.

Plan de puntos de control — Alineación simultánea de 5 elementos (nodo rígido)

script.md + outline.md Una vez redactado, hay que detenerse. El usuario debe confirmar simultáneamente estas 5 cosas en este nodo.

El trabajo preparatorio que debe realizar el agente en este momento

1. Leer todos los themes/*/theme.json Coger nameZh / descriptionZh / bestFor / mood — No codificar la lista de forma rígida
2. Según script.md el tipo de contenido / las palabras clave / el tono, selecciona de forma proactiva del tema entre 2 y 3 conjuntos de recomendaciones que mejor se ajusten (campos de bestFor )
3. Echa un vistazo outline.md la sección «Lista de materiales» al final

Resumir la plantilla (esquema; el agente la completará según el caso)

内容计划写完，产出文件：
  📄 article.md     {若用户给原文则保留}
  📄 script.md      {X} 字 / ~{T} 分钟
  📄 outline.md     {N} 章 / {M} 步 + 每章信息池 + 末尾素材清单

章节速览：
  1.      <章节标题>     步 ~s
  2. ...

接下来一次对齐 5 件事：

  1. 稿子 (script.md) 要不要改？
     可以直接编辑文件，或口头告诉我修改方向。

  2. 开发计划 (outline.md) 要不要改？重点看：
     - 章节切分 / step 数 / 估时是否合理（合理判断：每章 30~60s）
     - 每步屏幕内容是否清晰
     - 每章首段「信息池」是否有足够的 article 细节供画面挂
     - 末尾素材清单是否完整

  3. 选哪个主题？我的推荐：
     ★ <推荐 1：nameZh (id)> — 因为 ；
     ★ <推荐 2 / 推荐 3>
     其它可选：<剩余主题，nameZh + 一句话>
     也可以让我帮你做新主题（详见 references/THEMES.md）。

  4. 真素材怎么准备？粗看本视频要的图：<列粗略清单>
     a) 我从 <现有素材路径> 帮你挑   b) 你自己提供   c) 全部 placeholder

  5. 开发模式选哪个？

     **第 1 章无论哪种模式都必须主线程做完 + 用户验收**（强制 anchor）。
     差异在第 2 章及之后：

     A) 默认 · 逐章确认（推荐）
        每章做完都暂停验收 → 风险可控 / 节奏最稳
     B) 第 1 章后顺序开发（不并行）
        第 2~N 章主线程顺序做完后统一验收 → 速度中 / 适合 agent 不支持并行
     C) 第 1 章后并行开发（subagent）
        第 2~N 章用 subagent 并行 → 最快 / 用户控并行数（一次几章）
        ⚠️ 风格各章会有差异（这是预期，主题禁区兜底）

Tras recibir los comentarios:

• Si hay que modificar el borrador o el esquema: edita directamente el archivo y, una vez terminado, avisa (o describe verbalmente al agente para que lo modifique)
• El tema debe estar claro para pasar a la Fase 2. Si el usuario dice «Elige tú el tema por mí» → elige la primera de tus recomendaciones, comunícale al usuario qué has elegido y por qué, y dale la oportunidad de cambiar de opinión
• Una vez elegido el modelo → pasar a la Fase 2

Fase 2: desarrollo web

2.1 Estructura básica

bash /scripts/scaffold.sh \
  ./presentation \
  --theme=<用户选的主题 id>

bash /scripts/scaffold.sh --list-themes

Tema personalizado → Primero sigue references/THEMES.md el proceso de «Crear un nuevo tema» themes//y, a continuación, --theme=。

el generador de código incluirá una 01-example demostración. Antes de escribir el contenido real del primer capítulo, elimina:

rm -rf presentation/src/chapters/01-example

y cambia presentation/src/registry/chapters.ts el EXAMPLE_CHAPTER .

2.2 Capítulo 1: hilo principal + aceptación obligatoria

Esencia: el capítulo 1 = una versión completa desde el primer momento (con ritmo, elementos visuales y material real). No existe el concepto de «versión básica»: el primer capítulo debe ser una maqueta que el usuario pueda validar directamente.

¿Por qué el capítulo 1 debe ejecutarse en el hilo principal?

• Es CHAPTER-CRAFT.md la primera aplicación práctica de esta guía bajo el tema y la temática actuales
• Si la guía tiene lagunas o no hay suficientes tokens de colores o tipografías para el tema, el Capítulo 1 lo pondrá de manifiesto — En ese momento, con la retroalimentación de los usuarios, se podrá modificar la guía o ajustar el tema; cuanto antes se corrija, menor será el coste
• Los capítulos posteriores (ya sean secuenciales o paralelos) deben basarse en el patrón de código del primer capítulo, por lo que este equivale a el «punto de referencia estilístico» del proyecto en cuestión (no se exige coherencia entre capítulos, pero cada capítulo debe ser convincente por sí mismo).

Una vez terminado el capítulo 1, hay que detenerse y esperar a la aprobación de los usuarios:

第 1 章  做完了，dev server 在 localhost:5173 运行。

验收重点：
  □ 视觉气质对不对？符合  的预期吗？
  □ 节奏对不对？某些步太快 / 太慢 / 信息太薄？
  □ 内容驱动动画是否到位？还是有几步是无脑入场动画？
  □ 双源原则：屏幕画面有没有"口播没念但 article 能挂"的细节？
  □ 反 AI 味检查：紫粉渐变 / 圆角彩色边框 / 假插画 / emoji 是否有？

问题告诉我，我针对性改。OK 了告诉我"继续"，我按选定模式做第 2 章及之后。

2.3 Capítulos 2 a N —— Siguiendo el patrón seleccionado

Regla común para todos los patrones: cada capítulo se desarrolla de forma independiente CHAPTER-CRAFT.md . No se exige que el estilo sea totalmente uniforme entre capítulos : los colores temáticos y los tokens de tipografía garantizan la uniformidad visual, mientras que se espera que cada capítulo tenga libertad para desarrollar sus propias animaciones, ritmo y presentación visual.

Modelo A · Predeterminado · Confirmación capítulo a capítulo

Finalización del capítulo 2 → Pausa para la aceptación → OK → Capítulo 3 → Pausa → ... → Capítulo N. Cada capítulo se somete a aceptación de forma independiente; los problemas se corrigen en cualquier momento, lo que minimiza los riesgos y garantiza un ritmo más estable. Cuando el usuario no especifique un modo, se seguirá este por defecto.

Modo B · Desarrollo secuencial tras el capítulo 1

Capítulo 2 → Capítulo 3 → ... → Capítulo N. El hilo principal se completa de forma secuencial y, al final, se realiza una aceptación unificada. Velocidad media, adecuada para entornos en los que el agente no admite tareas en paralelo.

Modo C · Desarrollo paralelo tras el capítulo 1 (subagente)

Se utilizan subagentes para completar en paralelo los capítulos 2 a N; el usuario controla el número máximo de tareas en paralelo («4 capítulos a la vez» / «2 capítulos a la vez»). Es el más rápido, pero el estilo variará de un capítulo a otro —lo cual es de esperar, ya que:

1. cada subagente no puede ver los resultados de los demás subagentes, por lo que no es posible una alineación mecánica
2. El código de los capítulos está físicamente separado (una carpeta por capítulo / prefijo CSS propio), por lo que no se interferirán entre sí
3. Los tokens del tema garantizan la coherencia visual (colores / tipografías / números destacados / tarjetas / líneas divisorias / personalidad / elementos decorativos), por lo que el estilo no se desvía
4. La falta de uniformidad en el estilo aporta la sensación de naturalidad propia de un vídeo realizado a mano (múltiples voces / múltiples perspectivas)

Las indicaciones de los subagentes en paralelo deben incluir:

• Párrafos del esquema del capítulo actual (incluido el conjunto de datos)
• references/CHAPTER-CRAFT.md (lectura obligatoria: requisitos de presentación visual + revelación gradual + principio de doble fuente + evitar el «sabor a IA» + líneas rojas del código + autocomprobación al finalizar; todo en este único documento)
• el tema actual theme.json , descriptionZh / mood / bestFor(basta con seguir el estilo de referencia; la animación, la duración, el tamaño de letra y los emojis los decide libremente el agente del capítulo)
• Capítulo 1: el código sirve como referencia de «estilo de código» (no como «objeto de plagio visual»)
• Regla estricta: prefijo CSS independiente para cada capítulo (.cd- / .mg- / .pm- / ...); No modificar chapters.ts; una vez terminado, se ejecuta npx tsc --noEmit

Importante: independientemente del modo elegido, el usuario puede cambiar de modo en cualquier momento. Capítulo 2: una vez aprobado, el usuario puede elegir entre «el resto en paralelo» o «el resto capítulo por capítulo».

2.4 Implementación de un solo capítulo (se debe completar cada capítulo)

Para obtener instrucciones detalladas, consulta references/CHAPTER-CRAFT.md —— Punto de entrada único obligatorio, que abarca: requisitos de presentación visual / revelación gradual / selección de contenidos / principio de doble fuente / estética básica de la demostración en vídeo / evitar el estilo «anti-IA» / límites del código / autocomprobación al finalizar.

Puntos clave (detallados en CHAPTER-CRAFT.md):

• Cada capítulo debe incluir una demostración visual con CSS / SVG / Canvas / JS; se prohíben los capítulos de solo texto
• Revelación gradual: las listas deben seguir el principio de 1 elemento = 1 paso; no se permite mostrar todo de una vez
• Principio de las dos fuentes: el ritmo debe seguir el del guion de voz (el orden no puede alterarse); los detalles deben extraerse del artículo original (base de datos + párrafos del artículo de este capítulo)
• La autoevaluación de finalización debe revisarse punto por punto; si no cumple los requisitos, hay que volver a modificarla — se aplicará el «Protocolo de autoevaluación obligatorio» mencionado anteriormente (prioridad: equipos de agentes → subagentes → autoevaluación); una vez corregido, informar al usuario de la entrega de este capítulo

2.5 Tras una modificación importante, actualizar STORAGE_KEY

Modificaciones chapters.ts(si se añaden, eliminan o reordenan capítulos, o si cambia narrations.ts ) se debe actualizar presentation/src/hooks/useStepper.ts el STORAGE_KEY(por ejemplo v4 → v5), para evitar que el cursor permanente se sitúe en un paso que ya no existe.

Checkpoint Audio —— ¿Se sintetiza el audio? (nodo fijo)

Una vez finalizada la Fase 2, hay que detenerse y preguntar al usuario:

网页做完，{N} 章 {M} 步，dev server 在 localhost:5173 跑着。

要不要合成音频做"自动播放录屏"？
  ✓ 合成 → 扫所有章节的 narrations.ts 出 audio-segments.json，
           调 TTS provider 合成每步一个 mp3 到 public/audio/。
           合成完后用 ?auto=1 模式可以一镜到底录屏（音视频天然同步）。
           内置两个 provider：
             • minimax (mmx-cli)    —— 默认，中文音色稳
             • openai  (OPENAI_API_KEY) —— curl-based，多数已有 key
           其它后端 (ElevenLabs / edge-tts 免费 / macOS say 离线 /
           Azure / Google) 见 scripts/tts-providers/README.md 的现成片段。
  ✗ 不合成 → 跳过 Phase 3，直接 Phase 4 用手动录屏 + 后期配音。

¿Desea sintetizar? → Fase 3. ¿No desea sintetizar? → Directamente a la Fase 4.

Fase 3 —— Síntesis de audio (opcional)

Para ver el proceso detallado, véase references/AUDIO.md. Versión resumida:

cd presentation
npm run extract-narrations   # 扫所有 narrations.ts → audio-segments.json
# 让用户扫一眼 audio-segments.json 确认文本对
npm run synthesize-audio                       # 默认 minimax provider，增量
# 或用内置 openai (要 OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# 或自定义：写一个 scripts/tts-providers/.sh，见该目录的 README.md

Una vez finalizada la síntesis, informar al usuario: ubicación de la salida / número total de segmentos / qué segmentos tienen una duración anómala (demasiado largo = hay que dividir ese paso; demasiado corto = el texto es demasiado escaso) — dar una última oportunidad para ajustar el ritmo. A continuación, pasar a la Fase 4.

Fase 4 —— Grabación de pantalla + posproducción

Para más detalles, véase references/RECORDING.md. Hay dos opciones:

El agente indica de forma proactiva al usuario la ruta de grabación más adecuada tras la Fase 3 / Checkpoint Audio.

Diez principios (lista concisa)

Para ver la versión completa, consulta references/CHAPTER-CRAFT.md Parte 0 —— Consúltala al redactar los capítulos; lo que sigue es solo un índice.

Resumen de comentarios habituales de los usuarios

Véase la tabla simplificada references/CHAPTER-CRAFT.md Parte 8: «Guía rápida de comentarios habituales». Clave : primero identificar en qué nivel se encuentra el problema (ritmo / aspecto visual / contenido / código) y, a continuación, modificar la parte más pequeña posible, sin rehacer todo el capítulo .

Recursos relacionados

Etiquétalos según «cuándo leerlos» para evitar leerlo todo de una vez: