zhanglt/illustrateur-de-documents

Compétence Illustrateur de Documents

Outil de génération d'illustrations pour documents basé sur l'analyse intelligente par IA. Aucun format spécifique requis, compréhension automatique du contenu et génération d'illustrations professionnelles.

🎯 Caractéristiques principales

• ✨ Résumé intelligent par IA : comprend automatiquement le contenu du document et extrait les thèmes principaux
• 🎨 Indépendant du format : prend en charge tout format de document (Markdown, texte brut, PDF, etc.)
• 📐 Proportions flexibles : prend en charge 16:9 (paysage) et 3:4 (portrait)
• 🖼️ Image de couverture optionnelle : peut générer une image de couverture résumant l'ensemble du document
• 🎭 Trois styles : carte en verre dégradé, style ticket, illustration vectorielle

🚀 Utilisation

Dites simplement à Codex

Génère des illustrations pour ce document : /path/to/document.md

Ou :

Je veux générer des illustrations pour cet article

📝 Processus complet

Étape 1 : Codex lit et comprend le document

Lorsque vous demandez la génération d'illustrations, Codex :

1. Utilise l'outil Read pour lire le document complet
2. Analyse et comprend le contenu et la structure du document via l'IA
3. Identifie les thèmes principaux et les points clés

Ne vous souciez pas du format du document :

• ✅ Markdown standard (##, ###)
• ✅ Format avec séparateurs (======, ------)
• ✅ Paragraphes en texte brut
• ✅ Tout autre format

Étape 2 : Options de configuration (3 questions)

Codex vous demande vos préférences :

Question 1 : Proportion de l'image

Veuillez choisir la proportion de l'image :
1. 16:9 (paysage) - idéal pour présentations, diaporamas, affichage paysage
2. 3:4 (portrait) - idéal pour réseaux sociaux, visualisation mobile, affiches

Votre choix (1/2) :

Question 2 : Image de couverture

Souhaitez-vous générer une image de couverture ?
L'image de couverture résumera toutes les informations clés du document, servant d'introduction à la série d'illustrations.

1. Oui - générer une image de couverture + illustrations de contenu
2. Non - générer uniquement les illustrations de contenu

Votre choix (1/2) :

Question 3 : Nombre d'illustrations de contenu

Combien d'illustrations de contenu souhaitez-vous générer ?
Plage recommandée : 3-10
D'après le contenu du document, 6 illustrations sont recommandées

Veuillez entrer un nombre :

Étape 3 : Codex résume le contenu et affiche

En fonction du nombre spécifié, Codex résume intelligemment le document, puis vous montre le résultat pour confirmation :

📋 Résumé du contenu terminé

📄 Contenu de l'image de couverture : (si choisie)
"Évolution du concept des outils de programmation IA : des Rules aux Skills"
- Concept clé : contexte statique vs contexte dynamique
- Chemin d'évolution : Rules → Commands → MCP → Modes → Skills
- Meilleure pratique : simplifier en deux outils principaux

📚 Illustrations de contenu (6 au total) :

1. Naissance et évolution des Rules
   Contient : problèmes d'hallucination des premiers modèles, rôle du fichier rules, concept de contexte statique

2. Commands et packaging des workflows
   Contient : apparition des workflows fixes, slash command, partage en équipe

3. MCP Servers apportent des capacités dynamiques
   Contient : intégration d'outils tiers, authentification OAuth, problème d'expansion du contexte

4. Arrivée des Modes et Subagents
   Contient : prompts de personnalité, modification des prompts système, conception de fiabilité, déterminisme des Hooks

5. Skills unifient le contexte dynamique
   Contient : concept de Skills, chargement dynamique, optimisation des outils de programmation

6. Meilleures pratiques et perspectives futures
   Contient : recommandations d'utilisation des Rules, exploration des Skills, résumé des concepts clés

✓ Tout le contenu est couvert, sans omission

Confirmez-vous le début de la génération des illustrations ? (O/N)

Garanties clés :

• ✅ Contenu complet : toutes les informations importantes seront incluses dans une image
• ✅ Logique claire : segmentation selon la logique naturelle du contenu
• ✅ Contrôle utilisateur : affichage du résultat du résumé, attente de confirmation

Étape 4 : Génération des illustrations

Après confirmation, Codex appelle le script Python pour générer les images :

🖼️  Début de la génération des illustrations...

Génération de l'image de couverture...
  ✓ Enregistrée : /path/to/document/images/cover.png

Génération de la 1/6...
  Titre : Naissance et évolution des Rules
  ✓ Enregistrée : /path/to/document/images/illustration-01.png

Génération de la 2/6...
  Titre : Commands et packaging des workflows
  ✓ Enregistrée : /path/to/document/images/illustration-02.png

...

✨ Terminé ! 7 illustrations générées (1 couverture + 6 de contenu)

Étape 5 : Résultat final

Emplacement de sortie : dossier images/ dans le répertoire du document

/path/to/your/document/
└── images/
    ├── cover.png              # Image de couverture (si choisie)
    ├── illustration-01.png    # 1ère illustration de contenu
    ├── illustration-02.png    # 2ème illustration de contenu
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 Description des trois styles

1. Style carte en verre dégradé (gradient-glass)

Caractéristiques :

• Minimalisme style Apple Keynote
• Design Glassmorphism
• Fond noir profond ou blanc pur
• Dégradé d'aurore boréale
• Objets 3D en verre et effets lumineux

Cas d'utilisation :

• Présentation de produits tech
• Rapports d'analyse de données
• Perspectives futures
• Démonstration de fonctionnalités

2. Style ticket (ticket)

Caractéristiques :

• Design de billet numérique minimaliste
• Contraste noir et blanc élevé
• Structure type carte d'embarquement ou billet
• Divisions géométriques précises
• Mélange chinois/anglais, disposition multi-directionnelle

Cas d'utilisation :

• Infographies
• Présentation de données statistiques
• Chronologies et diagrammes de flux
• Résumé de points clés

3. Style illustration vectorielle (vector-illustration)

Caractéristiques :

• Illustration vectorielle plate
• Contours noirs d'épaisseur uniforme
• Palettes rétro et douces
• Traitement géométrique
• Composition panoramique horizontale

Cas d'utilisation :

• Narration
• Explication de concepts
• Contenu éducatif
• Promotion de marque

💡 Exemples d'utilisation

Exemple 1 : Processus complet

Utilisateur : Génére des illustrations pour ~/blog/ai-tools.md, style ticket

Codex : D'accord, laisse-moi d'abord lire ce document...
        [Lecture du document, analyse du contenu]

        Longueur détectée : environ 3000 mots, contenu sur l'évolution des outils IA.

        Veuillez choisir la proportion de l'image :
        1. 16:9 (paysage)
        2. 3:4 (portrait)

Utilisateur : 1

Codex : Souhaitez-vous générer une image de couverture ?
        1. Oui
        2. Non

Utilisateur : Oui

Codex : Combien d'illustrations de contenu souhaitez-vous générer ?
        Plage recommandée : 3-10
        D'après le contenu, 5 illustrations sont recommandées

Utilisateur : 5

Codex : [Affichage des 5 thèmes résumés]
        Confirmez-vous le début de la génération ?

Utilisateur : O

Codex : [Appel du script Python pour générer 6 images]
        ✨ Terminé ! Illustrations enregistrées dans ~/blog/images/

Exemple 2 : Document texte brut

Utilisateur : Génére des illustrations pour cette note en texte brut

Codex : [Lecture de la note, compréhension même sans titres]
        [Identification intelligente de 3 thèmes principaux]
        [Demande de configuration, affichage du résumé, génération]

Exemple 3 : Nombre personnalisé

Utilisateur : Je veux 8 images, format portrait, sans couverture

Codex : D'accord, 16:9 portrait, pas de couverture, 8 illustrations de contenu.
        [Résumé du document en 8 thèmes]
        [Affichage du résumé, génération après confirmation]

🔧 Détails techniques

Spécifications des images

Les proportions et résolutions suivantes s'appliquent à Gemini ; Nebula image2-4k ne supporte que 16:9, 3840x2160. Lorsque l'utilisateur choisit Nebula, utilisez directement la 4K ; si l'utilisateur demande 2K ou un format vertical, expliquez d'abord les limitations et déterminez une solution prise en charge.

Proportion	Résolution	Cas d'utilisation
16:9	2560x1440 (2K)	Présentations, affichage paysage
3:4	1920x2560	Réseaux sociaux, visualisation portrait

Résolutions 4K optionnelles :

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

Appels API

• Modèle Gemini : gemini-3-pro-image-preview (valeur par défaut actuelle du script)
• Modèle Nebula : gpt-image-2-4k, utilise les tokens du groupe image2-4k
• Coût : chaque image = 1 appel API
• Vitesse : dépend de la charge du backend ; délai d'attente des requêtes Nebula 4K : 1800 secondes

Choix du backend et appel Nebula

Groupe nanobanana

Lorsque l'utilisateur spécifie nanobanana, les deux scripts passent --provider nanobanana. Le .env unifié utilise la clé dédiée NEBULA_NANOBANANA_API_KEY (token du groupe nanobanana), sans réutiliser la clé image2-4k. Le modèle par défaut de NEBULA_NANOBANANA_MODEL est gemini-3.1-flash-image, peut être modifié pour tout modèle supporté par le token ; ILLUSTRATOR_IMAGE_PROVIDER=nanobanana peut être défini comme valeur par défaut. Les images uniques et par lot prennent en charge 16:9 et 3:4 ; peuvent demander 1K, 2K, 4K, par défaut 2K, les valeurs supportées et les pixels réels dépendent du modèle choisi, sans appliquer la limite 4K paysage de image2-4k.

Le .env unifié utilise ILLUSTRATOR_SINGLE_RATIO pour définir la proportion par défaut des images uniques, ILLUSTRATOR_BATCH_RATIO pour les lots, ILLUSTRATOR_RESOLUTION pour la résolution par défaut. Les deux points d'entrée supportent --ratio et --resolution pour remplacer la configuration. Si non configuré ou vide, la proportion est 16:9, la résolution utilise la valeur par défaut du backend (Gemini/nanobanana : 2K, image2-4k : 4K). Ces paramètres s'appliquent à tous les backends ; en cas de conflit avec les limites du backend, une erreur est signalée avant la requête, il faut ajuster la configuration ou remplacer explicitement.

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "Sujet" --content "Contenu de l'illustration" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py article.md --provider nanobanana --style ticket --level h2 --resolution 2K

Appel natif Gemini POST /v1beta/models/{model}:generateContent, décode et valide l'image depuis inlineData, sans persister la réponse Base64 complète. Aucun SDK Google requis. L'intégration actuelle ne supporte que la génération à partir de texte ; pas de renvoi automatique après timeout pour les tâches payantes. Voir README.md et documentation officielle.

Groupe image2-4k existant

Les deux scripts supportent --provider gemini|nebula. Par défaut, ils lisent ILLUSTRATOR_IMAGE_PROVIDER, si non configuré, utilisent Gemini. Lorsque l'utilisateur spécifie explicitement Nebula, passer --provider nebula ; ne pas utiliser un autre service. Configurer NEBULA_API_KEY dans le chemin unifié ~/.agents/skills/document-illustrator/.env, ou utiliser une variable d'environnement du même nom ; le token doit appartenir au groupe image2-4k. Nebula ne nécessite pas de clé Gemini ni SDK Google, mais nécessite Pillow et python-dotenv.

python -X utf8 scripts/generate_single_image.py --provider nebula --title "Sujet" --content "Contenu confirmé de l'illustration" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py article.md --provider nebula --style ticket --level h2 --resolution 4K

Le script appelle POST https://img-api.apinebula.ai/v1/images/generations, utilise obligatoirement gpt-image-2-4k, 3840x2160, quality=high, response_format=url. Priorité à la lecture de l'URL, compatible Base64 ; vérifie les pixels réels avant sauvegarde, convertit le JPEG serveur au format correspondant à l'extension locale. La réponse de l'interface est sauvegardée sous <nom_fichier_image>.response.json, en cas d'échec de téléchargement, réutilise d'abord le lien temporaire pour relancer le téléchargement. L'état des tâches après timeout POST peut être inconnu, pas de renvoi automatique ; vérifier d'abord l'état côté serveur pour éviter les doublons de facturation. En cas d'HTTP 403 ou de connexion non établie, essaye le proxy http://127.0.0.1:81. Actuellement, seule la génération à partir de texte est intégrée ; l'édition avec image de référence n'est pas implémentée.

Configuration complète et commandes de test hors ligne dans README.md, les paramètres de l'interface sont basés sur la documentation officielle.

Environnement requis

Obligatoire :

pip install google-genai pillow python-dotenv

Clés API :

• Tous les agents (Codex, Claude, etc.) lisent unifiés ~/.agents/skills/document-illustrator/.env
• Sous Windows, le chemin correspondant est %USERPROFILE%\.agents\skills\document-illustrator\.env
• Seul ce fichier est chargé, ses valeurs remplacent les variables d'environnement du même nom ; si le fichier n'existe pas, seules les variables d'environnement existantes sont utilisées, aucune autre recherche n'est effectuée
• Gemini utilise GEMINI_API_KEY, Nebula utilise NEBULA_API_KEY
• Le groupe nanobanana utilise NEBULA_NANOBANANA_API_KEY ; la configuration du modèle est décrite ci-dessus dans la section du groupe

📊 Principes de résumé du contenu

Claude suit les principes suivants lors du résumé :

1. Priorité à l'exhaustivité

• ✅ Toutes les informations importantes sont incluses
• ✅ Aucun concept clé n'est omis
• ✅ Les idées principales du texte original sont conservées

2. Logique claire

• Segmentation selon la logique naturelle du contenu
• Regroupement des contenus connexes
• Maintien de la cohérence narrative

3. Répartition équilibrée

• Chaque image contient une quantité d'informations similaire
• Éviter qu'une image soit trop chargée ou vide
• Ajustement en fonction de l'importance du contenu

4. Contrôle utilisateur

• Affichage du résumé pour confirmation utilisateur
• L'utilisateur peut demander des ajustements
• Génération uniquement après confirmation

🐛 Dépannage

Problème 1 : Erreur de clé API

Message d'erreur :

Error: Invalid API key

Solution :

1. Vérifier GEMINI_API_KEY ou NEBULA_API_KEY dans le .env correspondant au backend ; pour Nebula, vérifier également le groupe de tokens
2. S'assurer que la clé API est valide et non expirée
3. Obtenir une nouvelle clé : https://makersuite.google.com/app/apikey

Problème 2 : Résumé insatisfaisant

Problème : les thèmes résumés ne correspondent pas aux attentes

Solution :

1. Lors de l'étape d'affichage du résumé, indiquer vos attentes à codex
2. codex refera le résumé et l'ajustera
3. Confirmer une fois satisfait avant de lancer la génération

Problème 3 : Échec de génération d'image

Causes possibles :

• Problème de connexion réseau
• Quota API épuisé
• Contenu trop long dépassant la limite

Solution :

1. Vérifier la connexion réseau
2. Vérifier le quota API
3. Essayer d'augmenter le nombre d'images (pour répartir le contenu)

💰 Estimation des coûts

Nombre d'images	Appels API	Coût estimé
Sans couverture + 3	3 appels	Faible
Avec couverture + 5	6 appels	Moyen
Avec couverture + 10	11 appels	Élevé

Recommandations :

• Document court (< 1000 mots) : 3 à 5 images
• Document moyen (1000-3000 mots) : 5 à 7 images
• Document long (> 3000 mots) : 8 à 10 images

📚 Meilleures pratiques

1. Choisir le bon nombre d'images

Trop peu :

• Chaque image contient trop d'informations
• Difficile à comprendre et mémoriser

Trop :

• Contenu dispersé
• Augmente les coûts et le temps de génération

Recommandé :

• Choisir en fonction de la longueur du document
• Chaque image couvre 1 à 2 idées principales

2. Choisir la proportion en fonction de l'usage

16:9 convient :

• Présentations PPT
• Bannières de sites web
• Couvertures de vidéos
• Illustrations de blog (bureau)

3:4 convient :

• Réseaux sociaux (Instagram, Xiaohongshu)
• Articles mobiles
• Conception d'affiches
• Vidéos verticales

3. Utilisation de l'image de couverture

Cas recommandés pour générer une couverture :

• Séries d'articles (comme guide unifié)
• Partage social (comme image de prévisualisation)
• Page d'accueil du document (résumé complet)

Cas où on peut s'en passer :

• Usage interne uniquement
• Nombre d'images déjà suffisant
• Souhait de réduire les coûts

4. Suggestions de style

Documentation technique → Style carte en verre dégradé Rapport de données → Style ticket Tutoriel / histoire → Style illustration vectorielle Présentation produit → Style carte en verre dégradé

🔄 Fonctionnement

Méthode traditionnelle (obsolète)

[Code] Lit le document → Identifie les titres ## ### → Découpage mécanique
       ↓
     Dépend d'un format spécifique
     Risque d'omettre du contenu
     Peu intelligent

Nouvelle méthode (implémentation actuelle)

[Claude] Lit le document → Compréhension IA → Résumé intelligent en thèmes
         ↓
       Indépendant du format
       Contenu complet
       Contrôle utilisateur

Différence clé :

• ❌ Ancienne méthode : dépend de l'analyse du code, ne traite que les formats standard
• ✅ Nouvelle méthode : compréhension IA du contenu, tout format est traité

🎯 Comparaison avec d'autres outils

Fonctionnalité	Illustrateur de Documents	Outils PPT traditionnels	Générateur d'images IA
Compréhension du contenu	✅ Compréhension IA intelligente	❌ Manuel	❌ Saisie manuelle requise
Dépendance au format	✅ Indépendant du format	❌ Dépend d'un format spécifique	✅ Aucune dépendance
Exhaustivité du contenu	✅ Vérification automatique	⚠️ Manuel	❌ Impossible à garantir
Génération par lot	✅ Génération multiple en une fois	❌ Une par une	⚠️ Saisies multiples requises
Cohérence de style	✅ Maintien automatique	⚠️ Ajustement manuel	⚠️ Prompts répétitifs requis

📞 Obtenir de l'aide

Pour toute question ou suggestion :

1. Demandez directement à codex
2. Vérifiez le répertoire Skill : ~/.agents/skills/document-illustrator

---

Laissez l'IA comprendre et résumer votre contenu, et générer des illustrations professionnelles ! ✨