nature-image2ppt

Nature Image2PPT

Use este diretório como o runtime completo. Execute ações determinísticas apenas através de:

python <image2ppt-root>/cli/image2ppt/cli.py <comando> ...

Use Python 3.10 ou posterior com requirements.txt instalado. Quando existir um ambiente dedicado, substitua <image2ppt-root>/.venv/bin/python no macOS/Linux ou <image2ppt-root>/.venv/Scripts/python.exe no Windows para cada comando python abaixo. Não continue após um doctor com falha; instale apenas a dependência ausente reportada e execute-o novamente.

Não descubra nem invoque outra Skill, CLI, Prompt, Schema, módulo ou máquina de estado.

Leia os contratos locais progressivamente

Sempre leia references/workflow.md. Leia references/runtime-dependencies.md apenas para configuração ou falhas do doctor, e leia references/ocr-text-hints-contract.md apenas ao escolher ou solucionar problemas de OCR.

Antes de escrever um manifesto de página, leia references/page-decision-tree.md e references/manifest-schema.md. Adicione apenas as referências necessárias para aquela página:

• página estruturada ou composta: references/region-decomposition.md e references/object-routing.md;
• setas: references/manifest-arrow-extension.md;
• ativos rasterizados ou trabalho com backend de imagem: references/assets-provenance-contract.md.

Antes de aceitar ou entregar a saída, leia references/qa-contract.md.

Preserve a fonte única de verdade

• Trate page_jobs.json como a única fonte de estado da página.
• Trate cada pages/page_NNN/manifest.json como a única fonte de conteúdo da página.
• Trate deck_manifest.json como a fonte da montagem final.
• Use apenas prepare, run next/dispatch/record/reset/hints/finalize e os comandos de página na CLI local para operações de ciclo de vida com estado.
• Mantenha evidências de região semântica em manifest.json.image2ppt_region_decomposition.
• Nunca crie um segundo arquivo de tarefa, plano de reconstrução, normalizador de OCR, controlador de página, empacotador ou caminho de finalização.
• Deixe que o QA suplementar reporte falhas; nunca permita que ele mude o estado do ciclo de vida.

Mantenha cada escrita dentro de seu diretório proprietário

• A construção, validação, dicas e QA da página podem ler e escrever apenas dentro daquele diretório de página. Caminhos de manifesto, ativos gravados, fórmulas, relatórios, prévias e substituições --out não devem usar .., links simbólicos ou caminhos absolutos para escapar dele. A única exceção de entrada externa é um resultado explícito de ferramenta de imagem fornecido para image import ou como process-sheet --asset-sheet-source; ele é copiado para a página antes de se tornar uma dependência de construção.
• Manifestos de execução e saídas finais devem permanecer dentro do diretório de execução preparado. A finalização reconstrói em um arquivo temporário no mesmo diretório e o publica atomicamente apenas após uma construção bem-sucedida.
• Trate qualquer rejeição de limite como uma falha grave; não copie o arquivo rejeitado de volta ao escopo e apresente-o como saída do runtime.

Preserve o comportamento pré-migração

• Trate a autocontenção como uma migração de caminho/importação/ponto de entrada, não como um redesenho do comportamento de reconstrução.
• Gere cada Prompt de worker a partir da camada base local completa mais a camada de perfil Image2PPT preservada. Não condense, reinterprete ou substitua nenhuma das camadas.
• Prefira a estratégia visual previamente validada quando várias rotas satisfizerem os contratos. Mantenha objetos nativos mensuráveis simples e retenha ativos complexos limitados sempre que um redesenho nativo reduzisse a fidelidade.
• Nunca reescreva uma página de base aceita meramente para provar independência de runtime.

Execute o workflow

Seleção de backend de imagem

Use builtin-imagegen quando o runtime do agente expuser image_gen.imagegen; é o backend preferido porque o worker pode inspecionar entradas de edição e importar o resultado local explícito. Use o contrato de imagem da CLI apenas quando a ferramenta embutida não estiver disponível, retornar erro, não conseguir ler uma entrada ou não retornar saída local válida. A ausência de um argumento opcional como modelo, máscara, tamanho, qualidade ou caminho de saída nunca autoriza fallback. Registre o produtor real e o motivo de fallback permitido em imagegen-jobs.json.

O contrato de imagem da CLI é neutro em relação ao provedor no limite de transporte. Selecione codex-oauth apenas para IDs de modelo GPT Image. Selecione openai-compatible-api para qualquer modelo específico de provedor cujo endpoint implemente o esquema /images/generations e/ou /images/edits compatível com OpenAI Images. Não infira o backend de imagem a partir do modelo de linguagem da tarefa. Use um backend explícito quando a proveniência for importante; auto usa Codex OAuth apenas para IDs de GPT Image compatíveis e, caso contrário, seleciona a API configurada sem enviar credenciais Codex OAuth a terceiros.

1. Pré-voo e escolha de OCR

python <image2ppt-root>/cli/image2ppt/cli.py doctor --json

Use Baidu AI Studio PADDLE_OCR_TOKEN quando configurado. Se estiver ausente, informe ao usuário uma vez que o fallback local builtin-ink mede a geometria do texto, mas não reconhece caracteres; ofereça o caminho de configuração em references/ocr-text-hints-contract.md. Respeite uma escolha offline.

2. Preparar uma execução

python <image2ppt-root>/cli/image2ppt/cli.py prepare <entrada...> \
  --out-root output/image2ppt --image-backend builtin-imagegen

Para fixar um provedor/modelo terceiro configurado para proveniência auditável, prepare com --image-backend openai-compatible-api. O contrato de execução registra o IMAGE2PPT_IMAGE_MODEL exato do projeto ativo ou ambiente; ele não substitui um padrão GPT Image apenas porque nenhuma flag --model foi passada.

Use --no-text-hints apenas quando o processamento de OCR estiver intencionalmente desabilitado. Regere dicas sem criar uma nova execução quando necessário:

python <image2ppt-root>/cli/image2ppt/cli.py run hints <run-dir>

3. Avançar e reivindicar páginas

python <image2ppt-root>/cli/image2ppt/cli.py run next <run-dir> --json
python <image2ppt-root>/scripts/build_page_worker_prompt.py \
  <run-dir> --page <page-id> --out <absolute-page-dir>/worker-prompt.md
python <image2ppt-root>/cli/image2ppt/cli.py run dispatch \
  <run-dir> --page <page-id> --agent-id <id> --prompt-file <absolute-prompt>

Para exatamente uma página, reivindique-a com --local e reconstrua-a no agente atual. Para múltiplas páginas, despache workers de página independentes até a capacidade em page_jobs.json. Não reinicie um worker ativo apenas porque está lento.

4. Reconstruir e controlar cada página

Planeje uma página estruturada como 3–5 regiões semânticas e roteie cada região independentemente. Use diagramas compostos medidos: meça cada nó, relação e âncora protegida. Mantenha círculos mensuráveis, cartões, relações retas/tracejadas e conectores simples nativos. Use ativos transparentes limitados apenas para subpartes locais complexas.

Represente uma seta fina como um conector com sua ponta de seta no mesmo objeto. Represente uma seta preenchida como um AutoForma de Seta, com texto de rótulo centralizado dentro do mesmo objeto. Nunca construa uma seta comum a partir de uma linha mais triângulo e nunca achate um grafo de conhecimento inteiro em uma imagem.

Escreva novos manifestos de página com schema_version: 2. Use itens visual_inventory estruturados com valores explícitos de kind e representation, e escreva uma observação concreta quality_evidence para cada verificação de qualidade exigida. A renderização de fórmulas é uma barreira rígida: um mecanismo ausente, conversor ou falha de compilação deve manter a página como falha, a menos que o usuário aprove explicitamente essa exceção de fórmula exata e o manifesto registre tanto user_approved_exception: true quanto um approval_note concreto.

O Prompt do worker executa a sequência determinística. Suas barreiras finais são:

python <image2ppt-root>/cli/image2ppt/cli.py page build <page-dir>
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir>
# A primeira execução escreve visual-review-evidence.template.json e permanece pendente.
# Inspecione source.png contra render/rendered.png, copie e complete o template
# como visual-review-evidence.json, repare se necessário, então:
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <page-dir>/visual-review-evidence.json
python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <page-dir>

O arquivo de evidência deve cobrir os hashes atuais source/render e cada verificação exigida com uma observação específica. --visual-review-notes é contexto opcional e não pode substituir o arquivo de evidência.

Grave apenas após a validação padrão e as barreiras de região, seta e renderização do Image2PPT passarem:

python <image2ppt-root>/cli/image2ppt/cli.py run record \
  <run-dir> --page <page-id> --agent-id <id>

Use o mesmo ciclo run reset → dispatch → record para reparar páginas rejeitadas.

5. Finalizar e revalidar o deck reconstruído

Quando run next reportar finalize, execute:

python <image2ppt-root>/cli/image2ppt/cli.py run finalize <run-dir>
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir>
# A primeira execução escreve final/visual-review-evidence.template.json e permanece pendente.
# Inspecione cada slide renderizado, complete final/visual-review-evidence.json, então:
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <run-dir>/final/visual-review-evidence.json

A finalização reconstrói a partir dos manifestos de página, preserva as notas do orador originais, valida o pacote e escreve a saída registrada por deck_manifest.json. O QA final reaplica as setas do manifesto, verifica a atomicidade das setas e a estrutura composta, renderiza cada slide, verifica a integridade das notas do orador e escreve final/image2ppt_qa.json.

Entregue

Retorne o caminho final do PPTX, a validação final padrão e final/image2ppt_qa.json. Reporte quais visuais complexos permanecem como ativos bitmap substituíveis. Não considere o deck completo enquanto qualquer barreira de página/final estiver pendente ou com falha.