Humanize PPT

O que Humanize PPT faz?

Use esta habilidade quando o usuário quiser transformar material bruto, notas, transcrições de voz, documentos ou links em um esboço de apresentação e decisões de mídia por página antes de delegar a renderização a uma habilidade downstream. Arquivos PPT/PPTX antigos não são lidos diretamente: extraia seu texto primeiro (veja a saída dump/inspect de scripts/pptx_qa.py) e alimente esse texto como --source. Uma apresentação que o Humanize PPT já renderizou passa por --qa-from <rendered.pptx> — é a verificação de apresentação, não o modo de briefing.

Posicionamento

O Humanize PPT é um sistema de apresentações, nascido para o discurso: um Diretor de Roteiro (AST — transferência de estado do público — cada virada de página move o público para frente), um Diretor de Aprimoramento Visual por Página (imagem real / diagrama SVG / vídeo Remotion), um Orquestrador de Briefing de Produção, um Executor de Verificação de Apresentação (演讲体检; anteriormente o loop de QA, o flag da CLI ainda é --qa-from), e uma entrega para o Modo Apresentador. A motivação: habilidades de template HTML-PPT são ótimas para exibição de conceitos, mas transformam uma ideia simples em uma dúzia de páginas bonitas, enquanto uma palestra real de 90 minutos tem cerca de 30 — a casca bonita supera a densidade do conteúdo. O Humanize fecha essa lacuna: mantém a beleza (renderizada nativamente pela habilidade de template downstream) e a torna apresentável — uma linha que você pode defender em pé. As habilidades de template downstream são donas de "renderiza lindamente"; o Humanize é dono de "é uma palestra, e alguém a verificou".

A verificação de apresentação em uma frase: ela não avalia a beleza, ela avalia o roteiro. Ela compara cada página renderizada com sua página de roteiro, extrai as páginas que podem ser apenas olhadas, mas não faladas, e continua até que cada página seja uma que o apresentador possa defender em pé. Uma página reprovada, em palavras simples: uma página que contém apenas algumas palavras e nunca completa seu ponto, ou uma página que falha na transferência de estado do público prometida (o ouvinte sai daquela página no mesmo estado em que entrou). Tal página não deveria existir; a verificação a extrai e gera instruções de correção.

O Humanize é amplamente compatível com renderizadores downstream que podem consumir markdown simples + JSON. As rotas verificadas são: HTML Chinês → guizang-ppt-skill; HTML Inglês → frontend-slides / beautiful-html-templates; PowerPoint editável nativo → ppt-master. Outros downstreams permanecem conectáveis; os níveis de suporte estão em registry/renderer_registry.json e só se movem com saída real.

Ele é executado antes das habilidades downstream de slides PPT / HTML e em torno da verificação de apresentação pós-renderização. Ele é dono do contrato AST, da decisão de mídia por página (esta página precisa de uma foto, um diagrama de sistema, um clipe de processo de 10 segundos, nada?), do briefing de produção que o próximo agente consome, e da passagem de verificação no HTML/PPTX renderizado. Ele não é dono da apresentação renderizada em si.

Existem duas portas de revisão humana antes da renderização: a pré-visualização do roteiro e a porta de estilo do renderizador. As rotas HTML usam a galeria de estilos do Humanize com ≥4 capas reais (--style-gallery). O PPT Master já possui uma UI de Confirmação obrigatória em três estágios com pré-visualizações visuais nativas, então --renderer ppt-master --style-gallery delega para essa porta e escreve style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md em vez de duplicar o catálogo.

O usuário chama o Humanize PPT uma vez para o briefing, entrega o briefing a uma habilidade downstream para renderização nativa, depois chama o Humanize novamente com --qa-from <rendered.html|native.pptx> para executar a verificação de apresentação de 3 iterações. Cada iteração escreve qa_report.md, fix_prompt.md e qa_iteration.json. Após 3 rodadas com falhas restantes, o status muda para needs-human.

O Humanize PPT nunca copia o template de uma habilidade downstream, nunca injeta seções personalizadas nele e nunca pós-processa HTML ou PPTX renderizado. As correções retornam ao código-fonte da habilidade downstream. Veja references/guizang-production-brief-orchestrator.md e adapters/ppt-master-bridge-notes.md.

Para posicionamento público, descreva o Humanize PPT como um orquestrador de briefing que se emparelha com renderizadores downstream nativos. Não o enquadre como um renderizador em si, e não o apresente como um "roteador" que escolhe o melhor estilo visual para o usuário — essa decisão vive no briefing, nos templates próprios da habilidade downstream e na revisão humana. Quando um usuário quiser apenas uma página de template bonita, isso é trabalho de uma habilidade de renderização, não do Humanize: declare a escolha, não uma proibição.

Teoria AST

AST significa Audience-State-Transfer (Transferência de Estado do Público).

• Público: quem está ouvindo, o que sabem, o que resistem e por que continuariam ouvindo.
• Estado: o estado do público antes e depois da apresentação, mais a tensão central que bloqueia a transição.
• Transferência: o caminho slide por slide que move o público do estado inicial ao estado desejado.

Frase central:

PPT não é um recipiente de informação. PPT é um artefato de transferência de estado do público.

Contrato de saída obrigatório

Para cada execução do Humanize PPT, produza:

1. deck_brief.md — público, objetivo, tensão, critérios de sucesso.
2. ast_outline.md — mapa AST e arco narrativo.
3. slide_plan.json — plano slide por slide, com decisão media: {image, diagram, video} por página e layout_hint.
4. speaker_intent.md — o que o apresentador deve fazer em cada slide. Habilidades downstream consomem isso como fonte para suas notas de apresentador nativas e modo apresentador.
5. asset_manifest.md — decisões de material por página do Humanize: qual página precisa de qual tipo de ativo (imagem / diagrama / vídeo) e para qual propósito.
6. video_slots.json — plano opcional de inserção de vídeo Remotion / HyperFrames / nativo.
7. style_brief.md — princípio visual para a produção downstream.
8. renderer_registry.json — instantâneo da capacidade do renderizador para esta execução.
9. router_plan.json — renderizador primário selecionado e plano de rota em estágios.
10. commands/*.md — instruções delimitadas para cada agente especialista downstream.
11. run_manifest.json — inventário final de arquivos, status da rota e status de QA.
12. <renderer>-production-prompt.md — o ponto de entrada downstream. Além das rotas HTML, o ppt-master emite ppt-master-production-prompt.md + ppt-master-source.md autocontido e cópias descartáveis em outputs/ppt-master-handoff/.
13. outputs/qa/qa_report.md — portão de QA de primeira passagem (modo briefing) ou descobertas de QA por iteração (modo QA).

O modo QA (pós-renderização) adicionalmente produz por iteração:

14. outputs/qa/fix_prompt.md — instruções de correção acionáveis pela habilidade downstream.
15. outputs/qa/qa_iteration.json — número da rodada, status (iterate / pass / needs-human), descobertas não resolvidas, histórico.

O modo Galeria de Estilos (--style-gallery, portão pré-roteiro) em vez disso produz e para:

16. Rotas HTML: style_gallery.html mais ≥4 entradas de capa. PPT Master: nenhum HTML de galeria falso; a seleção de estilo permanece em sua UI de Confirmação nativa.
17. style_gallery_plan.json — candidatos a capa para HTML ou mode: downstream-confirm-ui para PPT Master.
18. commands/style-gallery/<id>.md — comando de capa para HTML, ou ppt-master-confirm-ui.md para o portão nativo.

Fluxo de trabalho OPC recomendado (v0.6.4)

O — Roteiro + Direção de Mídia por Página
  Humanize PPT: material bruto → roteiro AST + decisão de mídia 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 — Invocação do Renderizador Nativo (100% downstream)
  zh  → guizang-ppt-skill        (Estilo A ou B, nativo; recomendado)
  en  → frontend-slides / beautiful-html-templates (nativo; recomendado)
  pptx → ppt-master (DrawingML nativo; --renderer ppt-master explícito)
  outras habilidades HTML-PPT → conectáveis, mesmo contrato de briefing
  Humanize emite o prompt de produção e para. A habilidade
  downstream renderiza a apresentação. Humanize NÃO copia templates, NÃO
  injeta substituições SLIDES_HERE / [必填], NÃO adiciona pontes
  postMessage ao HTML renderizado.

Q — Verificação de Apresentação (演讲体检) no artefato renderizado
  Humanize --qa-from <rendered.html|native.pptx> lê a saída de P,
  compara páginas com o roteiro, escaneia modos de falha
  (references/qa-failure-modes.md), escreve qa_report.md e
  fix_prompt.md, rastreia iteração em qa_iteration.json.
  Limite: 3 rodadas. Após o limite com descobertas restantes, status
  muda para needs-human.

C — Completo / Controle
  Notas de apresentador nativas da habilidade downstream + modo apresentador + deploy
  (Humanize não é dono destes na v0.6.4 — o briefing diz ao
  próximo agente para produzi-los no formato próprio da habilidade downstream)

Regras

Invariantes da v0.6.4 (estas são as regras rígidas; se você quebrar alguma, está fora do limite da v0.6.4)

1. Humanize é apenas briefing. Ele escreve o contrato de produção do renderizador e para. Ele não abre, copia ou pós-processa templates downstream ou HTML/PPTX final.
2. Os renderizadores downstream são 100% nativos. O próximo agente segue o SKILL.md da habilidade downstream. O briefing diz ao próximo agente qual habilidade carregar, qual Estilo (A/B) usar, quais layouts selecionar e quais portões de QA devem passar — mas não carrega detalhes internos do template.
3. A verificação de apresentação tem limite de 3 iterações. A rodada 4 com descobertas de falha restantes é needs-human. O loop não gira para sempre; ele devolve a decisão a um humano.
4. Notas de apresentador e modo apresentador — Humanize produz um presenter-shell.html básico; o downstream é dono do palco completo. Humanize é dono da fonte semântica (speaker_intent.md) e agora também escreve outputs/presenter/presenter-shell.html diretamente de slide_plan.json + speaker_intent.md (utilizável de forma independente, mesmo antes da apresentação downstream existir). A habilidade downstream produz as notas de apresentador nativas e o console do apresentador mais completo. Humanize não injeta pontes postMessage ou parâmetros de URL ?slide= no HTML renderizado.
5. O prompt de produção é o ponto de entrada downstream. Ele nomeia todos os artefatos de suporte que o renderizador deve ler. O PPT Master adicionalmente lê ppt-master-source.md, que congela a história da página do Humanize e a intenção das notas sem duplicar os contratos visuais do PPT Master.

Regras de trabalho

6. Não deixe que renderizadores de slide consumam material bruto diretamente quando o Humanize PPT pode primeiro produzir o contrato AST.
7. Mantenha a habilidade downstream como dona da visão completa do palco; o presenter-shell.html do Humanize é uma base funcional, não um substituto para consoles nativos.
8. Absorva princípios de limpeza de escrita de IA de ferramentas humanizadoras, mas não reduza o Humanize PPT ao polimento de texto.
9. Prefira um fluxo de trabalho pequeno e verificado a uma promessa ampla e não verificada.
10. Para lançamentos públicos de Habilidades, crie/envie o repositório, instale a partir do GitHub localmente, execute uma amostra completa segura, verifique o briefing + verificação de apresentação no checkpoint conhecido-bom verificado (examples/03-codex-guizang-native-ink-classic/), e só então refine os detalhes do README.
11. Para desenvolvimento de Equipes de Agentes, emita router_plan.json, run_manifest.json, commands/*.md delimitados e o prompt de produção por renderizador antes de conectar Habilidades downstream reais.
12. Para pacotes de upload de equipe WorkBuddy/CodeBuddy, não empacote saídas de demonstração ou HTML renderizado como o zip da equipe. O zip de upload deve espelhar uma estrutura de plugin de equipe como trading-team: .codebuddy-plugin/plugin.json na raiz, agents/, skills/, rules/ e setting.json (mais avatars/ opcional, .workbuddy-plugin/, README.md, settings.json). O diretório rules/ deve incluir um arquivo de regra de cenário como rules/<nome-do-plugin>_rules.md com frontmatter (description, alwaysApply, enabled, updatedAt, provider) e um bloco <system_reminder> descrevendo agentes, habilidades, SOP e requisitos de uso disponíveis. Verifique com unzip -l que a raiz não é index.html/assets/screenshots/source e não está encapsulada em pasta, a menos que o uploader de destino exija explicitamente um diretório wrapper.
13. Não trate vídeos HyperFrames/Remotion como um único player incorporado que substitui o conteúdo do PPT. Para entregáveis do Humanize PPT, as ferramentas de vídeo são produtoras de material: transições, clipes explicativos, comparações antes/depois, inserções de material de fala, prévias sociais e imagens estáticas de fallback que preenchem necessidades específicas de slide. A decisão media.video por página (veja o esquema de slide_plan.json) diz à habilidade downstream quais páginas querem um clipe Remotion, para qual propósito e em qual duração.

Referências operacionais

• references/guizang-production-brief-orchestrator.md — especificação canônica do briefing: o que <renderer>-production-prompt.md deve e não deve conter.
• references/qa-failure-modes.md (+ espelho em inglês references/qa-failure-modes.en.md) — catálogo de modos de falha para a verificação de apresentação; a fonte da verdade do lado do código é FAILURE_MODES em scripts/humanize_ppt_v2.py.
• references/style-gallery-spec.md — o portão de estilo de capa --style-gallery.
• references/renderer-guidance.md — caminhos recomendados por renderizador e as regras do checkpoint conhecido-bom.
• references/renderer-verification.md — evidência de verificação por renderizador por trás das linhas únicas do frontmatter.
• adapters/ppt-master-bridge-notes.md — limite da rota PPTX nativa e contrato de verificação OOXML.
• SPEC.md — especificação técnica do mecanismo: superfície da CLI, fluxo de dados, contrato de saída, galeria de estilos, verificação, modelo de mídia, registro do renderizador.
• Índice completo anotado de todas as referências, adaptadores, notas de versão e scripts auxiliares: docs/index.md.

Demonstração local

O ponto de entrada estável recomendado é scripts/humanize_ppt.py (scripts versionados permanecem como shims de compatibilidade). Exemplos completos de CLI — modo briefing, verificação de apresentação, PPTX nativo, pré-visualização do roteiro, pontos de entrada legados — estão em docs/local-demo.md.

Aviso sobre --out: aponte --out para um diretório de execução dedicado. O modo briefing o reconstrói do zero a cada execução, mas só o limpa automaticamente quando ele está faltando, vazio ou já é uma execução anterior do Humanize PPT (run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json em sua raiz) — caso contrário, recusa e pede --force.