Humanize PPT

¿Qué hace Humanize PPT?

Usa esta habilidad cuando un usuario quiera convertir material bruto, notas, transcripciones de voz, documentos o enlaces en un esquema listo para presentación y decisiones de medios por página antes de delegar el renderizado a una habilidad descendente. Los archivos PPT/PPTX antiguos no se leen directamente: extrae su texto primero (consulta la salida dump/inspect de scripts/pptx_qa.py) y luego introduce ese texto como --source. Un mazo que Humanize PPT ya haya renderizado pasa por --qa-from <rendered.pptx> en su lugar, para la revisión de presentación, no el modo de informe.

Posicionamiento

Humanize PPT es un sistema de presentaciones, nacido para la charla: un Director de Esquema (AST de transferencia de estado de la audiencia — cada cambio de página mueve a la audiencia hacia adelante), un Director de Mejora Visual por Página (imagen real / diagrama SVG / video Remotion), un Orquestador de Informe de Producción, un Ejecutor de Revisión de Presentación (演讲体检; anteriormente el bucle de QA, el indicador CLI sigue siendo --qa-from), y una Transferencia al Modo Presentador. La motivación: las habilidades de plantillas HTML-PPT son excelentes para mostrar conceptos pero convierten una idea simple en una docena de páginas bonitas, mientras que una charla real de 90 minutos tiene ~30 — la cáscara bonita supera la densidad de contenido. Humanize cierra esa brecha: mantiene la belleza (renderizada de forma nativa por la habilidad de plantilla descendente) y la hace presentable — una línea que puedes defender de pie y presentar. Las habilidades de plantilla descendentes son dueñas de 'renderiza hermosamente'; Humanize es dueño de 'es una charla, y alguien la revisó'.

La revisión de presentación en una frase: no califica la belleza, califica el esquema. Compara cada página renderizada con su página de esquema, extrae las páginas que solo se pueden mirar pero no se pueden pronunciar, y continúa hasta que cada página sea una que el orador pueda defender de pie y presentar. Una página fallida, en palabras simples: una página que solo contiene unas pocas palabras y nunca termina su punto, o una página que no logra la transferencia de estado de la audiencia que prometió (el oyente sale de esa página en el mismo estado en que entró). Esa página no debería existir; la revisión la extrae y genera instrucciones de corrección.

Humanize es ampliamente compatible con renderizadores descendentes que pueden consumir markdown plano + JSON. Las rutas verificadas son: HTML chino → guizang-ppt-skill; HTML inglés → frontend-slides / beautiful-html-templates; PowerPoint nativo editable → ppt-master. Otros descendentes siguen siendo conectables en caliente; los niveles de soporte residen en registry/renderer_registry.json y se mueven solo con salida real.

Se ejecuta antes de las habilidades descendentes de diapositivas PPT / HTML y alrededor de la revisión de presentación posterior al renderizado. Es dueño del contrato AST, de la decisión de medios por página (¿esta página necesita una foto, un diagrama de sistema, un clip de proceso de 10 segundos, nada?), del informe de producción que consume el siguiente agente, y de la pasada de revisión sobre el HTML/PPTX renderizado. No es dueño del mazo renderizado en sí.

Hay dos puertas de revisión humana antes del renderizado: la vista previa del esquema y la puerta de estilo del renderizador. Las rutas HTML utilizan la --style-gallery de Humanize con ≥4 portadas reales. PPT Master ya posee una interfaz de Confirmación obligatoria de tres etapas con vistas previas visuales nativas, por lo que --renderer ppt-master --style-gallery delega en esa puerta y escribe style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md en lugar de duplicar el catálogo.

El usuario llama a Humanize PPT una vez para el informe, entrega el informe a una habilidad descendente para el renderizado nativo, luego llama a Humanize nuevamente con --qa-from <rendered.html|native.pptx> para ejecutar la revisión de presentación de 3 iteraciones. Cada iteración escribe qa_report.md, fix_prompt.md y qa_iteration.json. Después de 3 rondas con fallos restantes, el estado cambia a needs-human.

Humanize PPT nunca copia la plantilla de una habilidad descendente, nunca inyecta secciones personalizadas en ella, y nunca procesa posteriormente el HTML o PPTX renderizado. Las correcciones se devuelven a la fuente del autor descendente. Consulta references/guizang-production-brief-orchestrator.md y adapters/ppt-master-bridge-notes.md.

Para el posicionamiento público, describe Humanize PPT como un orquestador de informes que se empareja con renderizadores descendentes nativos. No lo enmarques como un renderizador en sí mismo, y no lo presentes como un 'enrutador' que elige el mejor estilo visual para el usuario — esa decisión reside en el informe, en las plantillas propias de la habilidad descendente y en la revisión humana. Cuando un usuario solo quiere una bonita página de plantilla, ese es un trabajo de habilidad de renderizado, no un trabajo de Humanize: expón la elección, no una prohibición.

Teoría AST

AST significa Audience-State-Transfer (Transferencia de Estado de la Audiencia).

• Audiencia: quién escucha, qué sabe, qué resiste y por qué seguiría escuchando.
• Estado: el estado de la audiencia antes y después del mazo, más la tensión central que bloquea la transición.
• Transferencia: el camino diapositiva por diapositiva que mueve a la audiencia del estado inicial al estado deseado.

Frase clave:

PPT no es un contenedor de información. PPT es un artefacto de transferencia de estado de la audiencia.

Contrato de salida requerido

Para cada ejecución de Humanize PPT, produce:

1. deck_brief.md — audiencia, objetivo, tensión, criterios de éxito.
2. ast_outline.md — mapa AST y arco narrativo.
3. slide_plan.json — plan diapositiva por diapositiva, con decisión de media: {image, diagram, video} por página y layout_hint.
4. speaker_intent.md — lo que el orador debe hacer en cada diapositiva. Las habilidades descendentes consumen esto como la fuente para sus notas de orador nativas y su carcasa de presentador.
5. asset_manifest.md — decisiones de material por página de Humanize: qué página necesita qué tipo de recurso (imagen / diagrama / video) y con qué propósito.
6. video_slots.json — plan opcional de inserción de video Remotion / HyperFrames / nativo.
7. style_brief.md — principio visual para la producción descendente.
8. renderer_registry.json — instantánea de la capacidad del renderizador para esta ejecución.
9. router_plan.json — renderizador primario seleccionado y plan de ruta escalonado.
10. commands/*.md — instrucciones acotadas para cada agente especialista descendente.
11. run_manifest.json — inventario final de archivos, estado de la ruta y estado de QA.
12. <renderer>-production-prompt.md — el punto de entrada descendente. Además de las rutas HTML, ppt-master emite ppt-master-production-prompt.md + ppt-master-source.md autocontenido y copias desechables en outputs/ppt-master-handoff/.
13. outputs/qa/qa_report.md — puerta de QA de primera pasada (modo informe) o hallazgos de QA por iteración (modo QA).

El modo QA (post-renderizado) produce adicionalmente por iteración:

14. outputs/qa/fix_prompt.md — instrucciones de corrección accionables por la habilidad descendente.
15. outputs/qa/qa_iteration.json — número de ronda, estado (iterate / pass / needs-human), hallazgos no resueltos, historial.

El modo Galería de Estilos (--style-gallery, puerta previa al esquema) produce y se detiene:

16. Rutas HTML: style_gallery.html más ≥4 entradas de portada. PPT Master: sin HTML de galería falso; la selección de estilo permanece en su interfaz de Confirmación nativa.
17. style_gallery_plan.json — candidatos a portada para HTML o mode: downstream-confirm-ui para PPT Master.
18. commands/style-gallery/<id>.md — comando de portada para HTML, o ppt-master-confirm-ui.md para la puerta nativa.

Flujo de trabajo OPC recomendado (v0.6.4)

O — Esquema + Dirección de Medios por Página
  Humanize PPT: material bruto → esquema AST + decisión de medios por página
  (deck_brief.md, ast_outline.md, slide_plan.json, speaker_intent.md,
   asset_manifest.md, video_slots.json, style_brief.md)

P — Invocación del Renderizador Nativo (100% descendente)
  zh  → guizang-ppt-skill        (Estilo A o B, nativo; recomendado)
  en  → frontend-slides / beautiful-html-templates (nativo; recomendado)
  pptx → ppt-master (DrawingML nativo; --renderer ppt-master explícito)
  otras habilidades HTML-PPT → conectables en caliente, mismo contrato de informe
  Humanize emite el prompt de producción y se detiene. La habilidad
  descendente renderiza el mazo. Humanize NO copia plantillas, NO
  inyecta reemplazos SLIDES_HERE / [必填], NO añade puentes
  postMessage al HTML renderizado.

Q — Revisión de Presentación (演讲体检) sobre el artefacto renderizado
  Humanize --qa-from <rendered.html|native.pptx> lee la salida de P,
  compara páginas con el esquema, escanea modos de fallo
  (references/qa-failure-modes.md), escribe qa_report.md y
  fix_prompt.md, rastrea la iteración en qa_iteration.json.
  Límite: 3 rondas. Después del límite con hallazgos restantes, el estado
  cambia a needs-human.

C — Completar / Control
  Notas de orador nativas de la habilidad descendente + carcasa de presentador + despliegue
  (Humanize no es dueño de estos en v0.6.4 — el informe le dice al
  siguiente agente que los produzca en el formato propio de la habilidad descendente)

Reglas

Invariantes v0.6.4 (estas son las reglas duras; si incumples alguna, estás fuera del límite v0.6.4)

1. Humanize es solo informe. Escribe el contrato de producción del renderizador y se detiene. No abre, copia ni procesa posteriormente plantillas descendentes o HTML/PPTX final.
2. Los renderizadores descendentes son 100% nativos. El siguiente agente sigue el SKILL.md propio de la habilidad descendente. El informe le dice al siguiente agente qué habilidad cargar, qué Estilo (A/B) usar, qué diseños seleccionar y qué puertas de QA deben pasar, pero no lleva internos de la plantilla.
3. La revisión de presentación tiene un límite de 3 iteraciones. La ronda 4 con hallazgos de fallo restantes es needs-human. El bucle no gira para siempre; devuelve la decisión a un humano.
4. Notas de orador y carcasa de presentador — Humanize produce una presenter-shell.html de referencia; el descendente es dueño del escenario completo. Humanize es dueño de la fuente semántica (speaker_intent.md) y ahora también escribe outputs/presenter/presenter-shell.html directamente desde slide_plan.json + speaker_intent.md (usable de forma independiente, incluso antes de que exista el mazo descendente). La habilidad descendente produce las notas de orador nativas y la consola de presentador más completa. Humanize no inyecta puentes postMessage ni parámetros de URL ?slide= en el HTML renderizado.
5. El prompt de producción es el punto de entrada descendente. Nombra cada artefacto de soporte que el renderizador debe leer. PPT Master además lee ppt-master-source.md, que congela la historia de la página de Humanize y la intención de las notas sin duplicar los contratos visuales de PPT Master.

Reglas de trabajo

6. No permitas que los renderizadores de diapositivas consuman material bruto directamente cuando Humanize PPT puede primero producir el contrato AST.
7. Mantén la habilidad descendente como la dueña de la vista completa del escenario; el presenter-shell.html de Humanize es una referencia funcional, no un reemplazo para las consolas nativas.
8. Absorbe principios de limpieza de escritura AI de herramientas humanizadoras, pero no reduzcas Humanize PPT a un pulido de texto.
9. Prefiere un flujo de trabajo pequeño y verificado sobre una promesa amplia y no verificada.
10. Para versiones públicas de Skills, crea/envía el repositorio, instálalo desde GitHub localmente, ejecuta una muestra completa segura, verifica el informe + la revisión de presentación en el punto de control conocido-bueno verificado (examples/03-codex-guizang-native-ink-classic/), y solo entonces pule los detalles del README.
11. Para el desarrollo de Equipos de Agentes, emite router_plan.json, run_manifest.json, commands/*.md acotados, y el prompt de producción por renderizador antes de conectar las Skills descendentes reales.
12. Para paquetes de carga de WorkBuddy/CodeBuddy Team, no empaques salidas de demostración o HTML renderizado como el zip del equipo. El zip de carga debe reflejar una estructura de plugin de equipo como trading-team: .codebuddy-plugin/plugin.json en la raíz, agents/, skills/, rules/ y setting.json (más avatars/, .workbuddy-plugin/, README.md, settings.json opcionales). El directorio rules/ debe incluir un archivo de reglas de escenario como rules/<nombre-plugin>_rules.md con metadatos (description, alwaysApply, enabled, updatedAt, provider) y un bloque <system_reminder> que describa los agentes, skills, SOP y requisitos de uso disponibles. Verifica con unzip -l que la raíz no sea index.html/assets/screenshots/source y que no esté envuelta en una carpeta a menos que el cargador de destino requiera explícitamente un directorio contenedor.
13. No trates los videos HyperFrames/Remotion como un único reproductor incrustado que reemplaza el contenido PPT. Para los entregables de Humanize PPT, las herramientas de video son productores de material: transiciones, clips explicativos, comparaciones antes/después, inserciones de material para hablar, vistas previas sociales e imágenes fijas de respaldo que llenan necesidades específicas de diapositivas. La decisión media.video por página (consulta el esquema slide_plan.json) le dice a la habilidad descendente qué páginas quieren un clip de Remotion, con qué propósito y a qué duración.

Referencias operativas

• references/guizang-production-brief-orchestrator.md — especificación canónica del informe: qué debe y no debe contener <renderer>-production-prompt.md.
• references/qa-failure-modes.md (+ espejo en inglés references/qa-failure-modes.en.md) — catálogo de modos de fallo para la revisión de presentación; la fuente de verdad del lado del código es FAILURE_MODES en scripts/humanize_ppt_v2.py.
• references/style-gallery-spec.md — la puerta de estilos de portada --style-gallery.
• references/renderer-guidance.md — rutas recomendadas por renderizador y reglas de puntos de control conocidos-buenos.
• references/renderer-verification.md — evidencia de verificación por renderizador detrás de las frases de metadatos.
• adapters/ppt-master-bridge-notes.md — límite de la ruta PPTX nativa y contrato de revisión OOXML.
• SPEC.md — especificación técnica del motor: superficie CLI, flujo de datos, contrato de salida, galería de estilos, revisión, modelo de medios, registro de renderizadores.
• Índice completo anotado de todas las referencias, adaptadores, notas de versión y scripts auxiliares: docs/index.md.

Demostración local

El punto de entrada estable recomendado es scripts/humanize_ppt.py (los scripts versionados permanecen como shims de compatibilidad). Los ejemplos completos de CLI — modo informe, revisión de presentación, PPTX nativo, vista previa del esquema, puntos de entrada heredados — residen en docs/local-demo.md.

Advertencia --out: apunta --out a un directorio de ejecución dedicado. El modo informe lo reconstruye desde cero en cada ejecución, pero solo lo borra automáticamente cuando falta, está vacío o ya es una ejecución anterior de Humanize PPT (run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json en su raíz); de lo contrario, se niega y pide --force.