zhanglt/document-illustrator

Skill Document Illustrator

Ferramenta de geração de ilustrações para documentos baseada em análise inteligente de IA. Não depende de formato específico, entende automaticamente o conteúdo e gera ilustrações profissionais.

🎯 Características Principais

• ✨ Resumo Inteligente por IA: Entende automaticamente o conteúdo do documento e extrai os tópicos centrais de forma inteligente
• 🎨 Independente de Formato: Suporta qualquer formato de documento (Markdown, texto puro, PDF, etc.)
• 📐 Proporções Flexíveis: Suporta 16:9 (paisagem) e 3:4 (retrato)
• 🖼️ Imagem de Capa Opcional: Pode gerar uma imagem de capa que resume todo o documento
• 🎭 Três Estilos: Cartão de vidro gradiente, estilo ticket, ilustração vetorial

🚀 Como Usar

Diga diretamente ao Codex

Gere ilustrações para este documento: /caminho/para/documento.md

Ou:

Quero gerar algumas ilustrações para este artigo

📝 Fluxo de Trabalho Completo

Passo 1: Codex lê e entende o documento

Quando você solicita a geração de ilustrações, o Codex irá:

1. Usar a ferramenta Read para ler o documento completo
2. A IA analisa e compreende o conteúdo e a estrutura do documento
3. Identifica os tópicos e pontos principais

Não se preocupe com o formato do documento:

• ✅ Markdown padrão (##, ###)
• ✅ Formato com linhas divisórias (======, ------)
• ✅ Parágrafos de texto puro
• ✅ Qualquer outro formato

Passo 2: Opções de Configuração (3 perguntas)

O Codex perguntará suas preferências:

Pergunta 1: Proporção da Imagem

Escolha a proporção da imagem:
1. 16:9 (paisagem) - Adequado para apresentações, slides, exibição em tela larga
2. 3:4 (retrato) - Adequado para redes sociais, visualização em dispositivos móveis, pôsteres

Escolha (1/2):

Pergunta 2: Imagem de Capa

Deseja gerar uma imagem de capa?
A imagem de capa resumirá todas as informações principais do documento, servindo como guia para a série de ilustrações.

1. Sim - Gerar imagem de capa + ilustrações de conteúdo
2. Não - Apenas gerar ilustrações de conteúdo

Escolha (1/2):

Pergunta 3: Número de Ilustrações de Conteúdo

Quantas ilustrações de conteúdo deseja gerar?
Faixa sugerida: 3-10
Com base no conteúdo do documento, recomendo gerar 6

Digite um número:

Passo 3: Codex resume o conteúdo e exibe

Com base no número que você especificou, o Codex irá resumir o documento de forma inteligente e exibir para sua confirmação:

📋 Resumo do conteúdo concluído

📄 Conteúdo da imagem de capa: (se selecionado)
"Evolução do Conceito de Ferramentas de IA: de Regras para Skills"
- Conceito central: Contexto estático vs Contexto dinâmico
- Caminho de evolução: Regras → Comandos → MCP → Modos → Skills
- Melhores práticas: Simplificar para duas ferramentas principais

📚 Ilustrações de conteúdo (total de 6):

1. O Nascimento e a Evolução das Regras
   Inclui: Problemas de alucinação em modelos iniciais, função dos arquivos de regras, conceito de contexto estático

2. Comandos e Empacotamento de Fluxos de Trabalho
   Inclui: Surgimento de fluxos de trabalho fixos, slash commands, compartilhamento em equipe

3. Servidores MCP Trazem Capacidades Dinâmicas
   Inclui: Integração com ferramentas de terceiros, autenticação OAuth, problema de inchaço do contexto

4. Modos e Subagentes Entram em Cena
   Inclui: Prompts de persona, modificação de prompts de sistema, design de confiabilidade, determinismo de Hooks

5. Skills Unificam o Contexto Dinâmico
   Inclui: Conceito de Skills, carregamento dinâmico, otimização de ferramentas de programação

6. Melhores Práticas e Perspectivas Futuras
   Inclui: Recomendações de uso de Regras, exploração de Skills, resumo de conceitos principais

✓ Todo o conteúdo foi coberto, sem omissões

Confirmar início da geração de ilustrações? (S/N)

Garantias principais:

• ✅ Conteúdo completo: Todas as informações importantes serão incluídas em alguma imagem
• ✅ Lógica clara: Segmentação de acordo com a lógica natural do conteúdo
• ✅ Controlável pelo usuário: Exibe o resultado do resumo e aguarda confirmação do usuário

Passo 4: Gerar Ilustrações

Após a confirmação, o Codex chama o script Python para gerar as imagens:

🖼️  Iniciando geração de ilustrações...

Gerando imagem de capa...
  ✓ Salva em: /caminho/para/documento/imagens/capa.png

Gerando imagem 1/6...
  Título: O Nascimento e a Evolução das Regras
  ✓ Salva em: /caminho/para/documento/imagens/ilustracao-01.png

Gerando imagem 2/6...
  Título: Comandos e Empacotamento de Fluxos de Trabalho
  ✓ Salva em: /caminho/para/documento/imagens/ilustracao-02.png

...

✨ Concluído! Total de 7 ilustrações geradas (1 capa + 6 de conteúdo)

Passo 5: Resultado da Saída

Local de saída: Pasta imagens/ no diretório do documento

/caminho/para/seu/documento/
└── imagens/
    ├── capa.png                    # Imagem de capa (se selecionada)
    ├── ilustracao-01.png           # 1ª ilustração de conteúdo
    ├── ilustracao-02.png           # 2ª ilustração de conteúdo
    ├── ilustracao-03.png
    ├── ilustracao-04.png
    ├── ilustracao-05.png
    └── ilustracao-06.png

🎨 Descrição dos Três Estilos

1. Estilo Cartão de Vidro Gradiente (gradient-glass)

Características:

• Minimalismo estilo Apple Keynote
• Design Glassmorphism
• Base em preto espaço profundo ou branco cerâmica puro
• Cores gradientes aurora fluídas
• Objetos de vidro 3D e efeitos brilhantes

Cenários de uso:

• Introdução de produtos de tecnologia
• Relatórios de análise de dados
• Perspectivas de tendências futuras
• Demonstração de funcionalidades de produtos

2. Estilo Ticket (ticket)

Características:

• Design digital minimalista de bilhetes
• Esquema de cores preto e branco de alto contraste
• Estrutura semelhante a cartões de embarque e ingressos
• Zoneamento geométrico preciso
• Layout de texto misto chinês-inglês, orientação multidirecional

Cenários de uso:

• Infográficos
• Exibição de dados estatísticos
• Linhas do tempo e fluxogramas
• Resumo de pontos principais

3. Estilo Ilustração Vetorial (vector-illustration)

Características:

• Ilustração vetorial plana
• Contorno preto de espessura uniforme
• Paleta de cores suaves e retrô
• Tratamento geométrico
• Composição panorâmica horizontal

Cenários de uso:

• Narrativas visuais
• Explicação de conceitos
• Conteúdo educacional
• Promoção de marca

💡 Exemplos de Uso

Exemplo 1: Fluxo Completo

Usuário: Gere ilustrações para ~/blog/ferramentas-ia.md, no estilo ticket

Codex: Claro, deixe-me ler o documento primeiro...
        [Lê o documento, analisa o conteúdo]

        Detectado documento com aproximadamente 3000 palavras, conteúdo sobre evolução de ferramentas de IA.

        Escolha a proporção da imagem:
        1. 16:9 (paisagem)
        2. 3:4 (retrato)

Usuário: 1

Codex: Deseja gerar uma imagem de capa?
        1. Sim
        2. Não

Usuário: Sim

Codex: Quantas ilustrações de conteúdo deseja gerar?
        Faixa sugerida: 3-10
        Com base no conteúdo do documento, recomendo gerar 5

Usuário: 5

Codex: [Exibe os 5 tópicos resumidos]
        Confirmar início da geração de ilustrações?

Usuário: S

Codex: [Chama o script Python para gerar 6 imagens]
        ✨ Concluído! Ilustrações salvas em ~/blog/imagens/

Exemplo 2: Documento de Texto Puro

Usuário: Gere ilustrações para esta anotação de texto puro

Codex: [Lê a anotação, mesmo sem títulos, entende o conteúdo]
        [Identifica inteligentemente 3 tópicos principais]
        [Pergunta configurações, exibe resumo, gera ilustrações]

Exemplo 3: Quantidade Personalizada

Usuário: Quero 8 imagens, no formato retrato, sem capa

Codex: Ok, 16:9 retrato, sem capa, 8 ilustrações de conteúdo.
        [Resume o documento em 8 tópicos]
        [Exibe o resultado do resumo, aguarda confirmação do usuário e gera]

🔧 Detalhes Técnicos

Especificações da Imagem

As seguintes proporções e resoluções se aplicam ao Gemini; Nebula image2-4k suporta apenas 16:9, 3840x2160. Quando o usuário escolhe Nebula, usa diretamente 4K; se o usuário solicitar 2K ou imagem retrato, primeiro explica as limitações e determina uma solução compatível.

Proporção	Resolução	Cenário de uso
16:9	2560x1440 (2K)	Apresentações, exibição paisagem
3:4	1920x2560	Redes sociais, exibição retrato

Resoluções 4K opcionais:

• 16:9 → 3840x2160
• 3:4 → 2880x3840

Chamada de API

• Modelo Gemini: gemini-3-pro-image-preview (valor padrão atual do script)
• Modelo Nebula: gpt-image-2-4k, usa tokens do grupo image2-4k
• Custo: Cada imagem = 1 chamada de API
• Velocidade: Depende da carga do backend; timeout de solicitação 4K Nebula é de 1800 segundos

Seleção de Backend e Chamada Nebula

Grupo nanobanana

Quando o usuário especifica nanobanana, ambos os scripts passam --provider nanobanana. O .env unificado usa NEBULA_NANOBANANA_API_KEY dedicada (token do grupo nanobanana), não reutiliza a chave do image2-4k. NEBULA_NANOBANANA_MODEL padrão é gemini-3.1-flash-image, pode especificar outros modelos suportados pelo token; ILLUSTRATOR_IMAGE_PROVIDER=nanobanana pode ser definido como padrão. Imagem única e lote suportam 16:9, 3:4; pode solicitar 1K, 2K, 4K, padrão 2K, os valores suportados específicos e pixels reais são determinados pelo modelo escolhido, não se aplica a limitação de imagem 4K paisagem do image2-4k.

O .env unificado usa ILLUSTRATOR_SINGLE_RATIO para definir a proporção padrão de imagem única, ILLUSTRATOR_BATCH_RATIO para definir a proporção padrão de lote, ILLUSTRATOR_RESOLUTION para definir a resolução padrão da solicitação. Ambas as entradas suportam --ratio, --resolution para substituir a configuração. Quando não configurado ou o valor está vazio, a proporção é 16:9, a resolução usa o valor padrão do backend (Gemini/nanobanana é 2K, image2-4k é 4K). Essas configurações se aplicam a todos os backends; em caso de conflito com as limitações do backend, um erro é exibido antes da solicitação, sendo necessário ajustar a configuração ou substituir explicitamente.

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "Tópico" --content "Conteúdo da ilustração" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py artigo.md --provider nanobanana --style ticket --level h2 --resolution 2K

Chama o Gemini nativo POST /v1beta/models/{model}:generateContent, decodifica e verifica a imagem a partir de inlineData, não persiste a resposta Base64 completa. Não requer Google SDK. A integração atual suporta apenas geração de texto para imagem; após timeout, não reenvia tarefas cobradas automaticamente. Consulte README.md e documentação oficial da interface.

Grupo image2-4k Original

Ambos os scripts suportam --provider gemini|nebula. Quando não especificado, lê ILLUSTRATOR_IMAGE_PROVIDER, se não configurado, usa Gemini. Quando o usuário especifica explicitamente Nebula, passa --provider nebula; não mude para outro serviço. Configure NEBULA_API_KEY no caminho unificado ~/.agents/skills/document-illustrator/.env, ou use a variável de ambiente de mesmo nome; o token deve pertencer ao grupo image2-4k. Nebula não requer chave Gemini ou Google SDK, ainda requer Pillow e python-dotenv.

python -X utf8 scripts/generate_single_image.py --provider nebula --title "Tópico" --content "Conteúdo da ilustração confirmado" --style-file styles/ticket.md --output output/imagem-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py artigo.md --provider nebula --style ticket --level h2 --resolution 4K

O script chama POST https://img-api.apinebula.ai/v1/images/generations, usando fixamente gpt-image-2-4k, 3840x2160, quality=high, response_format=url. Prioriza a leitura da URL, compatível com Base64; antes de salvar, verifica os pixels reais, converte o JPEG do servidor para o formato correspondente à extensão local. A resposta da interface é salva como <nome_do_arquivo_de_imagem>.response.json, em caso de falha de download, reutiliza o link temporário contido para retomar o download. Após timeout do POST, o status da tarefa pode ser desconhecido; não reenvia automaticamente; primeiro confirma o status do servidor para evitar cobrança duplicada. HTTP 403 ou conexão não estabelecida tenta o proxy http://127.0.0.1:81. Atualmente, apenas a geração de texto para imagem está integrada; edição de imagem de referência não foi implementada.

Configuração completa e comandos de teste offline estão em README.md, os parâmetros da interface baseiam-se na documentação oficial.

Requisitos de Ambiente

Obrigatório:

pip install google-genai pillow python-dotenv

Chaves de API:

• Todos os agentes (Codex, Claude, etc.) leem unificadamente ~/.agents/skills/document-illustrator/.env
• No Windows, o caminho correspondente é %USERPROFILE%\.agents\skills\document-illustrator\.env
• Apenas este arquivo é carregado; seus valores substituem variáveis de ambiente de mesmo nome; se o arquivo não existir, apenas as variáveis de ambiente existentes são usadas, sem procurar em outros locais
• Gemini usa GEMINI_API_KEY, Nebula usa NEBULA_API_KEY
• O grupo nanobanana usa NEBULA_NANOBANANA_API_KEY; a configuração do modelo está na descrição do grupo acima

📊 Princípios de Resumo de Conteúdo

Ao resumir o conteúdo, o Claude segue os seguintes princípios:

1. Prioridade à Integridade

• ✅ Todas as informações importantes são incluídas
• ✅ Não omite conceitos-chave
• ✅ Mantém os argumentos centrais do texto original

2. Lógica Clara

• Segmentação de acordo com a lógica natural do conteúdo
• Agrupamento de conteúdo relacionado
• Manutenção da coerência narrativa

3. Distribuição Equilibrada

• Cada imagem contém uma quantidade similar de informação
• Evita que uma imagem fique muito carregada ou vazia
• Ajusta de acordo com a importância do conteúdo

4. Controlável pelo Usuário

• Exibe o resultado do resumo para confirmação do usuário
• O usuário pode solicitar ajustes
• Só começa a gerar após confirmação

🐛 Solução de Problemas

Problema 1: Erro de Chave de API

Mensagem de erro:

Error: Invalid API key

Solução:

1. Verifique GEMINI_API_KEY ou NEBULA_API_KEY correspondente ao backend no .env; para Nebula, verifique também o grupo do token
2. Certifique-se de que a chave de API é válida e não expirou
3. Obtenha uma nova chave: https://makersuite.google.com/app/apikey

Problema 2: Resumo do Conteúdo Insatisfatório

Problema: Os tópicos resumidos não correspondem às expectativas

Solução:

1. Durante a fase de exibição do resumo, informe ao codex suas expectativas
2. O codex irá resumir novamente e ajustar
3. Confirme que está satisfeito antes de iniciar a geração

Problema 3: Falha na Geração da Imagem

Possíveis causas:

• Problema de conexão de rede
• Cota da API esgotada
• Conteúdo muito longo excede o limite

Solução:

1. Verifique a conexão de rede
2. Verifique a cota da API
3. Tente aumentar o número de imagens (distribuir o conteúdo)

💰 Estimativa de Custos

Número de Imagens	Chamadas de API	Custo Estimado
Sem capa + 3 imagens	3 vezes	Baixo
Com capa + 5 imagens	6 vezes	Médio
Com capa + 10 imagens	11 vezes	Alto

Recomendação:

• Documento curto (<1000 palavras): 3-5 imagens
• Documento médio (1000-3000 palavras): 5-7 imagens
• Documento longo (>3000 palavras): 8-10 imagens

📚 Melhores Práticas

1. Escolha Razoável do Número de Imagens

Muito poucas:

• Cada imagem contém muita informação
• Dificulta compreensão e memorização

Muitas:

• Conteúdo disperso
• Aumenta custo e tempo de geração

Recomendação:

• Escolha com base no comprimento do documento
• Cada imagem cobre 1-2 pontos principais

2. Escolha a Proporção de Acordo com o Uso

16:9 adequado para:

• Apresentações PPT
• Banners de sites
• Capas de vídeo
• Ilustrações de blog (desktop)

3:4 adequado para:

• Redes sociais (Instagram, Xiaohongshu)
• Artigos para dispositivos móveis
• Design de pôsteres
• Vídeos verticais

3. Uso da Imagem de Capa

Cenários em que se recomenda gerar capa:

• Artigos em série (como guia unificado)
• Compartilhamento em redes sociais (como imagem de pré-visualização)
• Página inicial do documento (resumindo todo o texto)

Cenários em que pode não gerar:

• Uso exclusivamente interno
• Número de imagens já suficiente
• Deseja reduzir custos

4. Recomendação de Estilo

Documentação técnica → Estilo cartão de vidro gradiente Relatório de dados → Estilo ticket Tutorial/narrativa → Estilo ilustração vetorial Apresentação de produto → Estilo cartão de vidro gradiente

🔄 Princípio de Funcionamento

Método Tradicional (Obsoleto)

[Código] Lê documento → Identifica títulos ## ### → Segmenta mecanicamente
       ↓
     Dependente de formato específico
     Pode omitir conteúdo
     Pouco inteligente

Novo Método (Implementação Atual)

[Claude] Lê documento → IA entende conteúdo → Resume tópicos de forma inteligente
         ↓
       Independente de formato
       Conteúdo completo
       Controlável pelo usuário

Diferença principal:

• ❌ Método antigo: Depende de análise por código, só processa formatos padrão
• ✅ Novo método: IA entende o conteúdo, qualquer formato é processável

🎯 Comparação com Outras Ferramentas

Funcionalidade	Document Illustrator	Ferramentas PPT Tradicionais	Geradores de Imagem AI
Entender conteúdo do documento	✅ Compreensão inteligente por IA	❌ Requer entrada manual	❌ Requer entrada manual
Dependência de formato	✅ Independente de formato	❌ Dependente de formato específico	✅ Sem dependência
Integridade do conteúdo	✅ Verificação automática	⚠️ Garantia manual	❌ Não pode garantir
Geração em lote	✅ Gera várias de uma vez	❌ Criada uma a uma	⚠️ Requer entradas múltiplas
Consistência de estilo	✅ Mantida automaticamente	⚠️ Ajustada manualmente	⚠️ Requer prompt repetido

📞 Obter Ajuda

Em caso de dúvidas ou sugestões:

1. Pergunte diretamente no codex
2. Verifique o diretório da Skill: ~/.agents/skills/document-illustrator

---

Deixe a IA entender e resumir seu conteúdo, gerando ilustrações profissionais! ✨