bowen31337/image-para-ppt-editavel

Imagem para PPT Editável (porta Claude Code)

Use o runtime editppt incluso para decompor, reconstruir, validar e montar slides visuais como .pptx editável. As entradas podem ser uma ou mais imagens, um PDF ou um PPT/PPTX baseado em imagem. A saída é sempre um .pptx, um slide por página de entrada, na ordem de entrada.

<skill-root> abaixo significa o diretório que contém este SKILL.md.

Como esta skill está organizada

Este arquivo é lido por você, o orquestrador. O trabalho no nível da página é feito por reconstrutores de página (subagentes em segundo plano, ou você mesmo para uma única página) orientados por um prompt gerado. Cada regra tem uma casa autoritativa — siga o ponteiro em vez de adivinhar:

• prompts/page-worker.md — modelo do reconstrutor de página: limite de propriedade, rota de leitura, ordem de execução, saídas necessárias, formato de retorno. Preenchido por scripts/build-page-worker-prompt.py.
• references/cli-helper.md — verificação de instalação do editppt, árvore de comandos, sintaxe. Leia ao escolher um comando.
• references/manifest-schema.md — contratos JSON para cada artefato de execução/página. Leia ao escrever ou validar arquivos de execução/página.
• references/page-decision-tree.md — o que se torna fundo vs. ativo de imagem vs. texto/forma/tabela nativos, uso de dicas de texto, auto-verificação final, correção-vs-aviso. Os reconstrutores de página leem isso; você raramente precisa.

Mapeamento de tempo de execução do Claude Code

A skill original tem como alvo o Codex. Estas são as substituições que a fazem funcionar aqui; elas se aplicam onde quer que as referências mencionem os equivalentes do Codex.

Conceito upstream (Codex)	No Claude Code
image_gen.imagegen embutido + folhas de ativos de modelo de imagem	Substituído pelo backend claude-native. Claude pode ver, mas não gerar bitmaps, então ele traceja ícones/ilustrações como SVG, mantém fotos como regiões de origem retangulares e faz inpainting de bases limpas localmente (references/page-decision-tree.md seção 2.4). Sempre use prepare com --image-backend claude-native; nunca builtin-imagegen.
API de imagem CLI (editppt image generate/edit)	Atualização opcional apenas, usada quando editppt doctor --check-api relata um backend pronto e um objeto não se encaixa em nenhuma fonte nativa. Nunca necessário.
view_image	Leia o caminho do arquivo de imagem (source.png, text_hints.png, imagens de zoom e .compare.png, preview.png, split_assets_contact.png).
Criar um worker de página / subagente	Ferramenta Agent, subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>" (ex.: ppt-page_003).
ID do worker para --agent-id	O mesmo nome que você deu ao agente (ppt-page_003); main para modo local de página única.
Aguardar workers	Agentes em segundo plano notificam você quando terminam. Não faça polling em loop.
Enviar um reparo de volta para o worker	SendMessage para o nome do worker, para que ele mantenha seu contexto.
Sandbox / aprovação de rede	Prompts de permissão do Claude Code. Uma execução claude-native com dicas locais RapidOCR não faz chamadas externas. PaddleOCR é chamado apenas quando um token é configurado (editppt prepare / editppt run hints); editppt image generate/edit também faz chamadas se a atualização opcional for usada.

Contrato de Entrada

Estas regras de nível de orquestrador são declaradas uma vez aqui.

• CLI primeiro. editppt é um runtime obrigatório. Se editppt --help falhar, instale-o de <skill-root>/cli usando a Verificação Pré-Execução em references/cli-helper.md (prefira uv tool install --force --editable <skill-root>/cli quando uv existir, depois pipx, depois pip --user), então execute editppt doctor.
• Estado apenas através da CLI. Comece com editppt prepare <input...>. Depois disso, avance cada transição de estado apenas através de comandos editppt; nunca escreva manualmente JSON de estado de execução/página. Isso mantém a execução determinística e retomável.
• Quem reconstrói páginas. Uma execução com exatamente uma página é reconstruída por você em modo local após editppt run dispatch --local reivindicá-la. Execuções com várias páginas são reconstruídas por workers de página em segundo plano — um por página. Não reconstrua artefatos de várias páginas você mesmo: cada página consome muito contexto (imagens, manifestos, loops de reparo), e mantê-los em workers separados é o que mantém seu contexto de orquestração utilizável e permite que as páginas sejam executadas em paralelo.
• Propriedade do artefato. Você não escreve manifest.json, page.pptx, preview.png, split_assets_contact.png, validation.json ou page_result.json exceto no modo local de página única após a reivindicação --local. O modo local segue o mesmo prompt de página, referências, saídas e validação run record que um worker.
• Backend de imagem. Veja "Backend de imagem no Claude Code" abaixo. Se nenhuma fonte permitida puder reproduzir um objeto, a página falha na validação em vez de substituir por formas aproximadas ou recortes de ícone (references/page-decision-tree.md seção 2).
• Chamadas externas autorizadas. Uma solicitação para converter slides em PPT editável autoriza as chamadas de OCR (e, se configurada, chamadas de API de imagem) necessárias para essa conversão, a menos que o usuário solicite processamento apenas local ou marque a entrada como confidencial. Envie apenas imagens de página locais à tarefa, prompts, máscaras e imagens de referência — nunca arquivos ou credenciais não relacionados. Pontos de extremidade de terceiros são permitidos apenas quando o usuário os configurou ou nomeou.
• Autonomia. Execute reconstrução de rotina, fallbacks configurados e reparos locais de página sem portões de confirmação. Pare para o usuário apenas para algo que só ele pode fornecer (uma decisão de token de OCR, uma entrada ausente). Relate bloqueadores concretos em vez de pedir ao usuário para depurar.
• Decisões de objeto seguem references/page-decision-tree.md; a validação determinística é um portão de estrutura e nunca renuncia a uma decisão de fonte de objeto.
• manifest.json é a fonte autoritativa de construção da página; run record valida page.pptx contra ele, e run finalize reconstrói o deck a partir dos manifestos registrados.

Higiene de credenciais

Segredos (token PaddleOCR, chave de API de imagem opcional) aparecem na transcrição se o usuário os colar no chat. Sugira que o usuário execute o comando de configuração com o prefixo ! para que o valor vá diretamente para a CLI, por exemplo:

! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1   # atualização opcional de API de imagem

Se eles colarem uma chave no chat de qualquer forma, armazene-a com editppt config e nunca a ecoe de volta; a CLI a mascara na saída. Nunca escreva chaves no projeto, no diretório de execução ou no diretório da skill.

Backend de imagem no Claude Code

Claude tem visão, mas não geração de imagem, então toda execução usa o backend claude-native: editppt prepare <input...> --image-backend claude-native. Os reconstrutores de página então escolhem a fonte de cada objeto de acordo com references/page-decision-tree.md seção 2.4:

• Ícones, logotipos, emblemas, marcas desenhadas à mão, ilustrações planas — Claude os traceja como SVG (editppt image zoom, depois editppt image svg). O PPTX incorpora o SVG real, então no PowerPoint o usuário pode recolorizá-lo ou usar Converter em Forma para editar seus caminhos individuais. Isso torna esses objetos mais editáveis do que os ativos de bitmap da skill upstream.
• Fotos, capturas de tela, blocos texturizados — mantidos como regiões de origem retangulares (editppt image photo-region). O tracejamento vetorial os transformaria em desenhos animados.
• Fundos complexos atrás de texto reconstruído — limpos por inpainting local (editppt image inpaint).

Não peça ao usuário uma API de imagem. Se editppt doctor --check-api mostrar um backend pronto (login Codex ou uma chave configurada), os workers podem usar editppt image generate/edit como uma atualização opcional para objetos que não se encaixam bem em nenhuma fonte nativa, como um recorte fotográfico em um fundo ocupado. Comandos de ativos dentro de uma página são executados em série.

Fluxo de trabalho

Fase 1: Preparar

Leia os exemplos de preparação em references/cli-helper.md e as descrições de arquivo de execução/página em references/manifest-schema.md.

editppt prepare <input...> --image-backend claude-native

Mantenha o padrão --out-root: ele cria o diretório de trabalho da execução output/image-to-editable-ppt/<job-id>/ sob o diretório atual. Não aponte para a pasta onde o usuário deseja o resultado; essa pasta deve receber apenas o deck final (Fase 4). Depois disso, deve haver deck_manifest.json, page_jobs.json, notes_manifest.json, e cada página deve ter source.png mais page_request.json.

Prepare também escreve dicas de texto por página (text_hints.json/text_hints.png). Sem token, elas vêm do RapidOCR local, que lê o texto no dispositivo sem upload, então não peça nada ao usuário. Apenas se prepare relatar o backend builtin-ink apenas geométrico (RapidOCR indisponível) você deve perguntar ao usuário uma vez antes de despachar qualquer página: um token gratuito de https://aistudio.baidu.com/account/accessToken, armazenado com editppt config --paddle-ocr-token <token>, torna as dicas cientes do conteúdo (lê o texto, não apenas mede onde ele está) e melhora notavelmente a fidelidade do texto; editppt run hints <run> então regenera as dicas da execução atual no local. A cota pessoal gratuita é mais do que suficiente para esta skill. Aguarde a escolha deles; se eles recusarem, continue com dicas offline e não pergunte novamente.

Se o usuário pedir Indra OCR (ou para OCR local mais rápido/alternativo), execute editppt config --text-hints-backend indra e reinstale a CLI com o extra [indra] (references/cli-helper.md). Mencione uma vez que os pesos do modelo Indra carregam uma licença OpenRAIL-M modificada que restringe alguns usos comerciais. Não mude para ele por conta própria: RapidOCR leu o texto do slide mais completamente nos testes.

Se um token estiver configurado, mas o OCR recuou devido a um prompt de permissão ou falha de rede, esse não é o caminho de qualidade preferido: obtenha a chamada permitida e execute novamente editppt run hints <run> antes da reconstrução da página. Continue offline apenas após o usuário recusar OCR, após uma tentativa de OCR permitida falhar por um motivo real de serviço, ou quando o usuário solicitou manipulação apenas local.

Fase 2: Reconstruir ou despachar páginas

Chame repetidamente e aja conforme o stage retornado:

editppt run next <run> --json

stage=rebuild_page_locally (exatamente uma página). Reivindique-a e reconstrua-a você mesmo:

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.md
2. editppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --local
3. Leia o prompt gerado e siga-o dentro desse diretório de página, produzindo as mesmas saídas que um worker produziria.

stage=dispatch_pages. Para cada página sugerida, nesta ordem:

1. Construa o prompt com o script, como acima.
2. Crie o worker com a ferramenta Agent — subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>", description: "Reconstruir <page_id> como PPT editável", e prompt definido como:

   Você é um reconstrutor de página para a skill image-to-editable-ppt (porta Claude Code).
   Leia <abs-run-dir>/pages/<page_id>/worker-prompt.md e siga-o exatamente.
   Notas do Claude Code: veja imagens com a ferramenta Read; você não pode gerar
   bitmaps, então visuais não-textuais vêm de page-decision-tree.md seção 2.4
   (traços SVG, regiões de foto, inpainting local); execute comandos shell com Bash.
   Não toque em arquivos fora do diretório da sua página.
   

3. Apenas após o spawn bem-sucedido: editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md

Crie todas as páginas sugeridas de um lote em uma única mensagem para que elas sejam executadas simultaneamente. --out e --prompt-file devem ser absolutos para que o diretório da página não seja prefixado duas vezes. Os slots de simultaneidade vêm de page_jobs.json.max_concurrent_pages (padrão 6).

stage=wait. Páginas despachadas são leases ativos, não slots ociosos. Aguarde notificações de conclusão. Não pare, redefina ou substitua um worker porque ele está lento ou silencioso — páginas complexas legitimamente levam 10+ minutos.

stage=configure_backend. Execute editppt run backend <run> --mode claude-native em vez do builtin-imagegen/contrato CLI sugerido.

Fase 3: Registrar

Quando a notificação de conclusão de um worker chegar (ou você terminar a página local):

editppt run record <run> --page <page_id> --agent-id <id>

Isso valida page.pptx contra manifest.json e rejeita a página se objetos posicionados faltarem coordenadas de pixel de origem, o manifesto não puder reconstruir a página independentemente, ou validation.json não tiver passed: true no nível superior. Em seguida, volte para editppt run next.

Reparos. Se o registro falhar, leia a evidência de falha e peça ao proprietário da página para reparar apenas os artefatos afetados, revalide (editppt page validate, veja references/cli-helper.md) e registre novamente. No modo de várias páginas, SendMessage a evidência para o worker existente (ppt-<page_id>) em vez de criar um novo — ele já contém o contexto da página e seus ativos verificados. Não regenerar ativos em conformidade para corrigir um erro de manifesto ou tabela não relacionado.

Redefinir apenas quando uma página precisar de uma execução nova: o worker terminou em um estado de falha terminal, o usuário cancelou ou tentativas repetidas de acessibilidade não mostram progresso local da página. Lento não é perdido. Depois de corrigir o que o bloqueou:

editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost

Reset retorna a página para pending; retome a Fase 2 com um novo prompt e worker. Artefatos existentes permanecem para proveniência e reutilização seletiva.

Tente novamente apenas após alterar uma entrada ou condição — nunca repita uma chamada com falha idêntica. Se um pré-requisito real estiver faltando, preserve o progresso e relate o bloqueador concreto. Uma vez que as saídas passem em suas verificações, siga em frente; não repita a garantia de qualidade visual inalterada.

Fase 4: Finalizar

Quando run next retornar o estágio de finalização:

editppt run finalize <run>

Finalizar reconstrói o deck a partir de cada pages/page_NNN/manifest.json registrado na ordem das páginas, copia as notas do apresentador .pptx inalteradas e valida o resultado: pacote válido, contagem de slides = contagem de páginas de entrada, paginação PDF/PPTX correta.

...