Variaciones de Imagen (Skill 01)
Entrada única. La orquestación está escrita aquí; el texto completo de las 12 direcciones, las plantillas de Prompt, la matriz de compatibilidad de Proveedores, los códigos de error y los umbrales no están aquí, deben leerse según sea necesario desde la línea base congelada para evitar dos verdades que se desvíen mutuamente.
- Reglas de negocio:
Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md - Registro de direcciones:
.../references/directions/registry.json - Plantillas de Prompt:
.../references/grid-prompt.md,.../references/sequence-prompt.md - Compatibilidad de Proveedores y seguridad:
.../references/provider-compat.md - Códigos de error:
.../references/error-registry.json - Reglas de empaquetado:
.../references/packaging.md - Contratos:
.../contracts/{image-artifact,job-state,delivery-package}.schema.json
La línea base es de solo lectura: la lista hash está en shared/baseline.manifest.json, shared/check_baseline.py debe mantenerse siempre en verde.
Para cambiar la especificación, primero justifique y obtenga confirmación; no "corrija" la línea base silenciosamente en la implementación.
I. Cinco reglas inquebrantables
- Sin degradación silenciosa. Capacidad insuficiente, presupuesto insuficiente, validación fallida: siempre devuelva explícitamente un código de error de
references/error-registry.json; no está permitido "cambiar silenciosamente a un tamaño más pequeño/una calidad más baja/menos imágenes" y continuar, ni tampoco informar una falla como exitosa. - Los umbrales solo se leen de la configuración.
config/iv.config.jsones la única fuente (límite suave/fuerte para el lado del mosaico, riesgo/paso para la costura, factor de ampliación, reintentos y presupuesto). Aún no han sido calibrados con modelos reales; proporcione datos antes de cambiarlos. No deben aparecer números mágicos en el código. - Fuente única de verdad. Las direcciones, prompts, códigos de error y contratos se leen desde la línea base en tiempo de ejecución, no se copian en este Skill.
- Las claves solo por referencia. Solo se aceptan
secret://…oenv:…; las claves, la imagen original y el texto del usuario no deben aparecer en registros, manifiestos, mensajes de error o ZIP. - Los artefactos deben ser verificables. Cada entrega incluye
manifest.json(image-artifact1.1) ydelivery-package.json; cada entrada en el manifiesto debe existir realmente y tener un hash consistente.
II. Cómo usar
# 1) Verificación previa: solo calcula el plan, no llama al modelo, no escribe en disco
python scripts/run_task.py --input task.json --preflight-only
# 2) Ejecución real (sin claves, use mock_synthetic para probar el flujo completo)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty
# 3) Si solo fallan algunos fotogramas, regenerarlos según el índice original (produce rev2, parent apunta a rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1
Descripción de la tarea (un JSON, los campos coinciden con los parámetros del producto en references/provider-compat.md):
{
"task_id": "cup_light_001",
"output_mode": "grid", // grid | sequence
"grid_size": 3, // grid obligatorio: 2 | 3 | 4
"direction": "light", // una de las 12 direcciones, ver registry.json
"input_type": "text_only", // text_only | image_only | image_plus_text
"subject": "una taza de cerámica gris claro", // descripción del sujeto, entra al ancla de sujeto
"reference_path": "img/ref.png", // obligatorio si hay entrada de imagen, relativo a workspace
"aspect_ratio": "3:4",
"resolution_tier": "1K", // 1K | 2K | 4K; por defecto se deduce del lado mínimo de un mosaico
"provider": {"type": "mock_synthetic"},
"pack_zip": true
}
sequence requiere adicionalmente branch (una de las 3 ramas que admite la dirección) e image_count (4–16).
Proveedor real:
"provider": {
"type": "openai_image_compatible", // o gemini_image_compatible
"base_url": "https://api.example.com/v1",
"model_id": "gpt-image-1",
"api_key_secret_ref": "secret://IMAGE_API_KEY",
"capability": { "...": "ver declaración de capacidades en provider-compat.md §1" }
}
Si capability falta, se considera que no cumple y se reporta MODEL_CAPABILITY_UNSUPPORTED — es una "lista mínima" que no se completa silenciosamente con valores predeterminados. Si el adaptador incorporado no se inyecta, reporta BUILTIN_UNAVAILABLE y no cambia automáticamente a una red externa.
III. Flujo (reglas de bifurcación)
Analizar entrada → Verificación previa (capacidad/proporción/nivel/cantidad/presupuesto)
├─ No pasa → Reportar código de error, finalizar (no llama al modelo, no escribe en disco)
└─ Pasa ─┬─ Grid: Una sola generación de panel → Validación (N×N / sin costuras / cortable / proporción) → Reintento limitado del panel completo
│ → Normalizar → Cortar en mosaicos por filas → Evaluar cada lado del mosaico (ok / risk / too_low)
└─ Sequence: Primero generar N planes de fotogramas (número de fotogramas, puntos de cambio por fotograma, elementos que permanecen, Prompt)
→ Generar fotograma por fotograma (fotograma 1 como base, fotogramas 2–N siempre referencian al fotograma 1; si hay imagen original, cada fotograma la incluye)
→ Si un fotograma falla, mantener su ranura y continuar; si el fotograma 1 falla, inmediatamente SEQUENCE_ANCHOR_FAILED
→ Detección de casi duplicados (después de agotar los reintentos, mantener la ranura y marcar)
→ Escribir en disco (manifest + delivery-package + ZIP opcional) → Devolver resultado JSON
Decisiones clave:
| Situación | Manejo |
|---|---|
grid_size no es 2/3/4, secuencia no está en 4–16 | INVALID_MODE_OR_COUNT |
| Lado del mosaico por debajo del umbral fuerte | TILE_RESOLUTION_TOO_LOW, no se genera paquete de entrega |
| Lado del mosaico por debajo del umbral suave | Entregar pero registrar advertencia TILE_RESOLUTION_RISK (tile_edge_ok=false) |
| Costura < umbral de riesgo | GRID_VALIDATION_FAILED, reintentar panel completo; no enviar cortes |
| Costura entre riesgo y paso | Entregar y registrar GRID_SEAM_RISK |
| Estructura/proporción N×N del panel no cumple | GRID_VALIDATION_FAILED |
| Fotograma 1 falla | SEQUENCE_ANCHOR_FAILED, no continuar quemando presupuesto |
| Fotograma i-ésimo falla | Mantener ranura del índice original, continuar con los siguientes fotogramas, finalmente partial_failed |
| Presupuesto a punto de excederse | BUDGET_EXCEEDED (puede adjuntar sugerencia de división, pero no dividir automáticamente) |
IV. Artefactos
workspace/iv_<task_id>_<revision>/
├── manifest.json # image-artifact 1.1 (estilo/tamaño/costura/ejecución/advertencias/errores)
├── delivery-package.json # Lista de este paquete (sha256 por archivo)
├── board.png # Solo Grid: kind=board, index=0
└── images/NN.png # Grid=cortes tile (orden por filas); Sequence=frame (índice sin adelantar)
En el mismo directorio, iv_<task_id>_<revision>.zip es el artefacto empaquetado opcional. El ZIP no contiene delivery-package.json; el hash del archive se escribe de vuelta en delivery-package.json.
Fallo parcial: solo se registran las imágenes que realmente existen (los fotogramas fallidos no entran en images[]); la información de fallo está en errors[].asset_id + validation.failed_indices, con status=partial_failed. La re-ejecución produce una nueva revisión (parent_artifact_revision apunta a la versión anterior), y los fotogramas ya exitosos permanecen byte a byte sin cambios.
V. Límites
- Solo generar variantes de imagen. Redacción de texto, publicación en plataformas, maquetación de portadas pertenecen al Skill 02 (
image-content-publishing); este Skill no se extralimita. - Si el usuario solicita explícitamente múltiples direcciones, solo elegir una y justificar la razón, o reportar
MULTIPLE_DIRECTIONS; no mezclar. - No realizar solicitudes dudosas como "transferencia de estilo a obras de otros"; cuando involucren personas reales/marcas, manejarlas según los requisitos de seguridad de
provider-compat.md §4. - Los artefactos de
mock_syntheticpara autocomprobación tienen la etiqueta fijaprovider_type=mock_syntheticy no deben entregarse externamente.
VI. Desarrollo y verificación
.venv/bin/python skills/image-variations/tests/run_all.py # 9 suites (incluye línea base 24/24 y contratos 48/48)
.venv/bin/python shared/check_baseline.py # Validación de solo lectura de la línea base
Las evidencias y desviaciones conocidas se registran en docs/PHASE_EVIDENCE.md.