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
- 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. - 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. - 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.
- Chaves apenas por referência. Apenas
secret://…ouenv:…são aceitos; chaves, imagens originais e texto do usuário não devem entrar em logs, manifesto, mensagens de erro ou ZIP. - Artefatos devem ser verificáveis. Cada entrega vem com
manifest.json(image-artifact1.1) edelivery-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ção | Tratamento |
|---|---|
grid_size diferente de 2/3/4, sequência fora de 4–16 | INVALID_MODE_OR_COUNT |
| Borda de célula abaixo do limite rígido | TILE_RESOLUTION_TOO_LOW, sem pacote de entrega |
| Borda de célula abaixo do limite de advertência | Entrega mas registra aviso TILE_RESOLUTION_RISK (tile_edge_ok=false) |
| Costura < limite de risco | GRID_VALIDATION_FAILED, tentar placa inteira novamente; não enviar tiles cortados |
| Costura entre risco e passagem | Entrega e registra GRID_SEAM_RISK |
| Estrutura/proporção N×N da placa não atende | GRID_VALIDATION_FAILED |
| Figura 1 falha | SEQUENCE_ANCHOR_FAILED, não continuar queimando orçamento |
| Quadro i falha | Manter slot do índice original, continuar quadros seguintes, eventualmente partial_failed |
| Orçamento será excedido | BUDGET_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_syntheticpara autoverificação são fixamente marcados comoprovider_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.