Variations d'Image (Skill 01)
Point d'entrée unique. L'orchestration est écrite ici ; les textes complets des 12 directions, les modèles de prompts, la matrice de compatibilité des fournisseurs, les codes d'erreur et les seuils ne sont pas ici, ils sont toujours lus dans la base de référence gelée selon les besoins, afin d'éviter deux sources de vérité divergentes.
- Règles métier :
Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md - Registre des directions :
.../references/directions/registry.json - Modèles de prompts :
.../references/grid-prompt.md,.../references/sequence-prompt.md - Compatibilité et sécurité des fournisseurs :
.../references/provider-compat.md - Codes d'erreur :
.../references/error-registry.json - Règles de conditionnement :
.../references/packaging.md - Contrats :
.../contracts/{image-artifact,job-state,delivery-package}.schema.json
La base de référence est en lecture seule : la liste de hachages se trouve dans shared/baseline.manifest.json, et shared/check_baseline.py doit toujours être vert.
Si vous devez modifier la spécification, veuillez d'abord en expliquer la raison et obtenir une confirmation : ne "corrigez" pas subrepticement la base de référence dans l'implémentation.
I. Cinq règles inviolables
- Pas de dégradation silencieuse. En cas de capacité insuffisante, de budget insuffisant ou d'échec de validation, retournez explicitement un code d'erreur de
references/error-registry.json; il est interdit de "passer silencieusement à une taille/qualité/nombre d'images inférieur" pour continuer l'exécution, ou de faire passer un échec pour une réussite. - Les seuils sont lus uniquement depuis la configuration.
config/iv.config.jsonest la seule source (seuils warn/hard pour le côté de la tuile, seuils pass/risk pour les joints, facteur d'agrandissement, tentatives et budget). Ils n'ont pas encore été calibrés avec un modèle réel ; fournissez des données avant de les modifier. Aucun nombre magique dans le code. - Source unique de vérité. Les directions, les prompts, les codes d'erreur et les contrats sont lus depuis la base de référence au moment de l'exécution, ne les copiez pas dans cette Skill.
- Les clés ne sont utilisées que par référence. Acceptez uniquement
secret://…ouenv:…; les clés, les images originales et le texte de l'utilisateur ne doivent pas apparaître dans les logs, le manifeste, les messages d'erreur ou le ZIP. - Les artefacts doivent être vérifiables. Chaque livraison doit inclure
manifest.json(image-artifact1.1) etdelivery-package.json; chaque entrée du manifeste doit exister réellement et avoir un hachage cohérent.
II. Comment utiliser
# 1) Pré-vérification : ne calcule que le plan, n'appelle pas de modèle, n'écrit pas sur le disque
python scripts/run_task.py --input task.json --preflight-only
# 2) Exécution réelle (utilise mock_synthetic pour parcourir toute la chaîne si pas de clé)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty
# 3) En cas d'échec partiel de certaines frames, les regénère en utilisant les indices d'origine (produit rev2, parent pointant vers rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1
Description de la tâche (un fichier JSON, dont les champs correspondent aux paramètres produit dans references/provider-compat.md) :
{
"task_id": "cup_light_001",
"output_mode": "grid", // grid | sequence
"grid_size": 3, // grid obligatoire : 2 | 3 | 4
"direction": "light", // une des 12 directions, voir registry.json
"input_type": "text_only", // text_only | image_only | image_plus_text
"subject": "une tasse en céramique gris clair", // description du sujet, entre dans l'ancre du sujet
"reference_path": "img/ref.png", // obligatoire si entrée image, relatif au workspace
"aspect_ratio": "3:4",
"resolution_tier": "1K", // 1K | 2K | 4K ; par défaut déduit de la taille minimale du côté de la tuile
"provider": {"type": "mock_synthetic"},
"pack_zip": true
}
sequence nécessite en plus branch (un des 3 embranchements de la direction) et image_count (4–16).
Fournisseur réel :
"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": { "...": "voir §1 Déclarations de capacité dans provider-compat.md" }
}
Par défaut, capability est considérée comme non conforme et renvoie MODEL_CAPABILITY_UNSUPPORTED — c'est une "liste minimale" qui ne sera pas comblée silencieusement par des valeurs par défaut. Si l'adaptateur intégré n'est pas injecté, renvoie BUILTIN_UNAVAILABLE et ne passe pas automatiquement par un réseau externe.
III. Flux (règle d'embranchement)
Analyser l'entrée → Pré-vérification (capacité / ratio / niveau / nombre d'images / budget)
├─ Échec → Retourner le code d'erreur, terminer (n'appelle pas de modèle, n'écrit pas)
└─ Succès ─┬─ Grid : Générer la planche en une fois → Valider (N×N / sans jointure / découpable / ratio) → Tentatives limitées sur la planche entière
│ → Normaliser → Découper en tuiles (ordre des lignes) → Vérifier le côté de chaque tuile (ok / risk / too_low)
└─ Sequence : D'abord planifier N frames (nombre de frames, points de changement par frame, éléments conservés, Prompt)
→ Générer frame par frame (image 1 comme base, images 2–N référencent toujours l'image 1 ; si image originale disponible, chaque frame l'inclut)
→ En cas d'échec d'une frame, garder l'emplacement et continuer ; si l'image 1 échoue, retourner immédiatement SEQUENCE_ANCHOR_FAILED
→ Détection de quasi-redondance (après épuisement des tentatives, garder l'emplacement et le marquer)
→ Écrire sur le disque (manifest + delivery-package + ZIP optionnel) → Retourner le résultat JSON
Décisions clés :
| Situation | Traitement |
|---|---|
grid_size n'est pas 2/3/4, ou la séquence n'est pas entre 4–16 | INVALID_MODE_OR_COUNT |
| Le côté de la tuile est inférieur au seuil hard | TILE_RESOLUTION_TOO_LOW, aucun paquet de livraison |
| Le côté de la tuile est inférieur au seuil warn | Livrer mais enregistrer un avertissement TILE_RESOLUTION_RISK (tile_edge_ok=false) |
| Jointure < seuil risk | GRID_VALIDATION_FAILED, réessayer la planche entière ; ne pas sortir les tuiles |
| Jointure entre risk et pass | Livrer et enregistrer GRID_SEAM_RISK |
| Structure/ratio de la planche N×N non conforme | GRID_VALIDATION_FAILED |
| Échec de l'image 1 | SEQUENCE_ANCHOR_FAILED, ne pas continuer à brûler le budget |
| Échec de la i-ème frame | Garder l'emplacement d'indice d'origine, continuer avec les frames suivantes, finalement partial_failed |
| Budget dépassé | BUDGET_EXCEEDED (peut inclure une suggestion de fractionnement, mais ne le fait pas automatiquement) |
IV. Artefacts
workspace/iv_<task_id>_<revision>/
├── manifest.json # image-artifact 1.1 (style/taille/jointure/exécution/avertissements/erreurs)
├── delivery-package.json # Liste des fichiers du paquet (sha256 par fichier)
├── board.png # Seulement pour Grid : kind=board, index=0
└── images/NN.png # Grid=tuiles découpées (ordre des lignes) ; Sequence=frames (les indices ne reculent pas)
iv_<task_id>_<revision>.zip dans le même répertoire est un artefact de conditionnement optionnel. Le ZIP ne contient pas delivery-package.json lui-même ; le hachage de archive est réécrit dans delivery-package.json.
En cas d'échec partiel : n'enregistrer que les images qui existent réellement (les frames en échec n'entrent pas dans images[]), les informations d'échec sont dans errors[].asset_id + validation.failed_indices, status=partial_failed.
La relance produit une nouvelle révision (parent_artifact_revision pointe vers la version précédente), les frames déjà réussies sont inchangées octet par octet.
V. Limites
- Ne fait que des variations d'image. La rédaction de contenu, la publication sur des plateformes et la mise en page de couvertures relèvent de la Skill 02 (
image-content-publishing) ; cette Skill ne franchit pas ces limites. - Si l'utilisateur demande explicitement plusieurs directions, n'en choisir qu'une et expliquer la raison, ou renvoyer
MULTIPLE_DIRECTIONS, sans mélanger. - Ne pas traiter les requêtes limites comme "transférer le style d'une œuvre d'autrui" ; pour les personnes réelles/les marques, traiter selon les exigences de sécurité de
provider-compat.md §4. - Les artefacts
mock_syntheticpour l'auto-test sont marquésprovider_type=mock_syntheticet ne doivent pas être livrés à l'extérieur.
VI. Développement et validation
.venv/bin/python skills/image-variations/tests/run_all.py # 9 suites de tests (dont 24/24 pour la base de référence et 48/48 pour les contrats)
.venv/bin/python shared/check_baseline.py # Validation de la base de référence en lecture seule
Les preuves et les écarts connus sont enregistrés dans docs/PHASE_EVIDENCE.md.