CommunityImagemgithub.com

Variações de imagem consistentes

Transforma um pedido ou uma imagem de referência num conjunto que mantém o mesmo sujeito. O modo grelha pinta uma folha 2×2, 3×3 ou 4×4 e corta-a. O modo sequência faz 4 a 16 fotogramas de luz, ângulo, lugar ou narrativa. Ambos entregam um pacote verificável com manifesto.

O que é Variações de imagem consistentes?

Skill de imagens fixas para séries coerentes. Escolhe uma folha de contacto ou uma sequência curta, mantém o sujeito e entrega um zip com manifesto em vez de uma pilha de ficheiros impossíveis de rever.

Funciona com~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/Chans-gh/AI-Image-Variation/tree/HEAD/skills/image-variations

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Variações de Imagem (Skill 01)

Ponto de entrada único. A orquestração está aqui; o texto completo das 12 direções, modelos de Prompt, matriz de compatibilidade com provedores, códigos de erro e limites não estão aqui, devem ser lidos conforme necessário a partir da linha de base congelada, evitando duas verdades divergentes.

  • Regras de negócio: Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md
  • Registro de direções: .../references/directions/registry.json
  • Modelos de Prompt: .../references/grid-prompt.md, .../references/sequence-prompt.md
  • Compatibilidade e segurança do provedor: .../references/provider-compat.md
  • Códigos de erro: .../references/error-registry.json
  • Regras de empacotamento: .../references/packaging.md
  • Contratos: .../contracts/{image-artifact,job-state,delivery-package}.schema.json

Linha de base é somente leitura: o manifesto hash está em shared/baseline.manifest.json, shared/check_baseline.py deve estar sempre verde. Para alterar a especificação, primeiro apresente a justificativa e obtenha confirmação; não "corrija" a linha de base silenciosamente na implementação.

1. Cinco regras invioláveis

  1. Sem degradação silenciosa. Em caso de capacidade insuficiente, orçamento insuficiente ou validação falha, retorne explicitamente o código de erro de references/error-registry.json; não é permitido "trocar silenciosamente para um tamanho/nível/quantidade menor" para continuar, nem transformar uma falha em sucesso.
  2. Limites lidos apenas da configuração. config/iv.config.json é a única fonte (limite de advertência/rígido para borda de célula, costura passagem/risco, fator de ampliação, tentativas e orçamento). Eles ainda não foram calibrados com modelos reais; forneça dados antes de alterá-los. Números mágicos não são permitidos no código.
  3. Fonte única da verdade. Direções, Prompts, códigos de erro e contratos são lidos da linha de base em tempo de execução, não copiados para dentro desta Skill.
  4. Chaves apenas por referência. Apenas secret://… ou env:… são aceitos; chaves, imagens originais e texto do usuário não devem entrar em logs, manifesto, mensagens de erro ou ZIP.
  5. Artefatos devem ser verificáveis. Cada entrega vem com manifest.json (image-artifact 1.1) e delivery-package.json; cada entrada no manifesto deve existir fisicamente e ter hash consistente.

2. Como usar

# 1) Pré-verificação: calcula apenas o plano, não chama modelo, não persiste
python scripts/run_task.py --input task.json --preflight-only

# 2) Execução real (usa mock_synthetic para percorrer o pipeline completo quando não há chave)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty

# 3) Se apenas alguns quadros falharem, gere novamente pelos índices originais (produz rev2, parent aponta para rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1

Descrição da tarefa (um JSON, campos consistentes com os parâmetros do produto em references/provider-compat.md):

{
  "task_id": "cup_light_001",
  "output_mode": "grid",            // grid | sequence
  "grid_size": 3,                   // grid obrigatório: 2 | 3 | 4
  "direction": "light",             // Uma das 12 direções, veja registry.json
  "input_type": "text_only",        // text_only | image_only | image_plus_text
  "subject": "uma caneca de cerâmica cinza clara", // Descrição do sujeito, entra no âncora do sujeito
  "reference_path": "img/ref.png",  // Obrigatório quando há entrada de imagem, relativo ao workspace
  "aspect_ratio": "3:4",
  "resolution_tier": "1K",          // 1K | 2K | 4K; padrão é inferido pelo tamanho mínimo da borda da célula
  "provider": {"type": "mock_synthetic"},
  "pack_zip": true
}

sequence exige adicionalmente branch (um dos 3 ramos suportados pela direção) e image_count (4–16).

Provedor real:

"provider": {
  "type": "openai_image_compatible",     // ou gemini_image_compatible
  "base_url": "https://api.example.com/v1",
  "model_id": "gpt-image-1",
  "api_key_secret_ref": "secret://IMAGE_API_KEY",
  "capability": { "...": "veja §1 declaração de capacidade em provider-compat.md" }
}

capability padrão é considerado não conforme e reporta MODEL_CAPABILITY_UNSUPPORTED — é uma "lista de requisitos mínimos", não sendo preenchida silenciosamente por valores padrão. Quando o adaptador embutido não é injetado, reporta BUILTIN_UNAVAILABLE, não muda automaticamente para rede externa.

3. Fluxo (Regras de ramificação)

Analisar entrada → Pré-verificação (capacidade/proporção/nível/quantidade/orçamento)
  ├─ Falha → reportar código de erro, fim (sem chamar modelo, sem persistir)
  └─ Sucesso ─┬─ Grid: montar placa de uma vez → Validar (N×N / sem emendas / cortável / proporção) → Tentativas limitadas de placa inteira
              │        → Normalizar → Cortar em tiles (linha principal) → Avaliar borda de cada tile (ok / risco / muito_baixo)
              └─ Sequence: Primeiro, criar plano de N quadros (número de quadros, pontos de variação por quadro, itens mantidos, Prompt)
                       → Gerar quadro por quadro (Figura 1 como base, Figuras 2–N sempre referenciam Figura 1; se houver imagem original, cada quadro a inclui)
                       → Em caso de falha de quadro individual, manter slot e continuar; falha da Figura 1 resulta imediatamente em SEQUENCE_ANCHOR_FAILED
                       → Detecção de quase-duplicatas (após esgotar tentativas, manter slot e marcar)
 → Persistir (manifest + delivery-package + ZIP opcional) → Retornar resultado JSON

Decisões principais:

SituaçãoTratamento
grid_size diferente de 2/3/4, sequência fora de 4–16INVALID_MODE_OR_COUNT
Borda de célula abaixo do limite rígidoTILE_RESOLUTION_TOO_LOW, sem pacote de entrega
Borda de célula abaixo do limite de advertênciaEntrega mas registra aviso TILE_RESOLUTION_RISK (tile_edge_ok=false)
Costura < limite de riscoGRID_VALIDATION_FAILED, tentar placa inteira novamente; não enviar tiles cortados
Costura entre risco e passagemEntrega e registra GRID_SEAM_RISK
Estrutura/proporção N×N da placa não atendeGRID_VALIDATION_FAILED
Figura 1 falhaSEQUENCE_ANCHOR_FAILED, não continuar queimando orçamento
Quadro i falhaManter slot do índice original, continuar quadros seguintes, eventualmente partial_failed
Orçamento será excedidoBUDGET_EXCEEDED (pode anexar sugestão de divisão, mas não divide automaticamente)

4. Artefatos

workspace/iv_<task_id>_<revision>/
├── manifest.json            # image-artifact 1.1 (estilo/tamanho/costura/execução/avisos/erros)
├── delivery-package.json    # Lista deste pacote (sha256 por arquivo)
├── board.png                # Apenas Grid: kind=board, index=0
└── images/NN.png            # Grid=tile cortado (linha principal); Sequence=frame (índice não avança)

No mesmo diretório, iv_<task_id>_<revision>.zip é o artefato de empacotamento opcional. O ZIP não contém delivery-package.json em si; o hash archive é escrito de volta em delivery-package.json.

Falha parcial: apenas imagens que realmente existem são registradas (quadros com falha não entram em images[]), informações de falha em errors[].asset_id + validation.failed_indices, status=partial_failed. Re-execução produz uma nova revisão (parent_artifact_revision aponta para a versão anterior), os quadros bem-sucedidos permanecem byte a byte inalterados.

5. Limites

  • Apenas variações de imagem de saída. Redação de texto, publicação em plataformas, layout de capa pertencem à Skill 02 (image-content-publishing), esta Skill não ultrapassa seu escopo.
  • Se o usuário solicitar explicitamente múltiplas direções, escolha apenas uma e justifique, ou reporte MULTIPLE_DIRECTIONS, não misture.
  • Não atender a solicitações limítrofes como "transferência de estilo para obras de outros"; ao envolver pessoas reais/marcas, siga os requisitos de segurança em provider-compat.md §4.
  • Os artefatos mock_synthetic para autoverificação são fixamente marcados como provider_type=mock_synthetic, não devem ser entregues externamente.

6. Desenvolvimento e Validação

.venv/bin/python skills/image-variations/tests/run_all.py     # 9 suites (incluindo baseline 24/24 e contratos 48/48)
.venv/bin/python shared/check_baseline.py                     # Verificação de linha de base somente leitura

Evidências e desvios conhecidos são registrados em docs/PHASE_EVIDENCE.md.

Habilidades Relacionadas