zhanglt/document-illustrator

Document Illustrator Skill

Ein KI-gestütztes Tool zur automatischen Generierung von Illustrationen für Dokumente. Unabhängig vom Format – es versteht den Inhalt und erstellt professionelle Bilder.

🎯 Kernfunktionen

• ✨ KI-basierte Zusammenfassung: Automatisches Verstehen des Dokuments und intelligente Extraktion der Kernthemen
• 🎨 Formatunabhängig: Unterstützt jedes Dokumentformat (Markdown, Text, PDF usw.)
• 📐 Flexibles Seitenverhältnis: 16:9 (Querformat) und 3:4 (Hochformat)
• 🖼️ Optional: Deckblatt: Kann ein zusammenfassendes Titelbild generieren
• 🎭 Drei Stile: Gradient Glass (Verlauf), Ticket (Ticketstil), Vector Illustration (Vektorgrafik)

🚀 Verwendung

Einfach Codex anweisen

Generiere mir Illustrationen für dieses Dokument: /path/to/document.md

Oder:

Ich möchte für diesen Artikel einige Illustrationen erstellen lassen

📝 Vollständiger Workflow

Schritt 1: Codex liest und versteht das Dokument

Wenn du die Generierung anforderst, wird Codex:

1. Das vollständige Dokument mit dem Read-Tool lesen
2. Den Inhalt und die Struktur per KI analysieren
3. Die Kernthemen und wichtigen Punkte identifizieren

Keine Sorge um das Dokumentformat:

• ✅ Standard Markdown (##, ###)
• ✅ Trennlinien-Format (======, ------)
• ✅ Reine Textabsätze
• ✅ Jedes andere Format

Schritt 2: Konfigurationsoptionen (3 Fragen)

Codex wird nach deinen Präferenzen fragen:

Frage 1: Bildverhältnis

Bitte wähle das Bildverhältnis:
1. 16:9 (Querformat) – geeignet für Präsentationen, Folien, horizontale Anzeige
2. 3:4 (Hochformat) – geeignet für soziale Medien, Smartphone-Ansicht, Poster

Bitte wähle (1/2):

Frage 2: Deckblatt

Soll ein Deckblatt generiert werden?
Das Deckblatt fasst alle Kerninformationen des Dokuments zusammen und dient als Einstieg in die Bilderserie.

1. Ja – Deckblatt + Inhaltsillustrationen generieren
2. Nein – Nur Inhaltsillustrationen generieren

Bitte wähle (1/2):

Frage 3: Anzahl der Inhaltsillustrationen

Wie viele Inhaltsillustrationen sollen generiert werden?
Empfohlener Bereich: 3–10 Stück
Basierend auf dem Dokumentinhalt werden 6 Stück empfohlen

Bitte gib eine Zahl ein:

Schritt 3: Codex fasst zusammen und zeigt an

Entsprechend der von dir angegebenen Anzahl wird Codex das Dokument intelligent zusammenfassen und dir zur Bestätigung anzeigen:

📋 Zusammenfassung abgeschlossen

📄 Deckblattinhalt: (falls Deckblatt ausgewählt)
„Konzeptentwicklung von KI-Programmierwerkzeugen: Von Regeln zu Skills“
- Kernkonzepte: statischer vs. dynamischer Kontext
- Entwicklungspfad: Rules → Commands → MCP → Modes → Skills
- Best Practices: Reduzierung auf zwei Kernwerkzeuge

📚 Inhaltsillustrationen (insgesamt 6):

1. Geburt und Entwicklung von Rules
   Enthält: frühe Halluzinationen, Rolle der Rules-Dateien, statischer Kontext

2. Commands und Workflow-Pakete
   Enthält: Entstehung fester Workflows, Slash-Befehle, Team-Sharing

3. MCP-Server bringen dynamische Fähigkeiten
   Enthält: Integration von Drittanbieter-Tools, OAuth, Kontextaufblähung

4. Auftritt von Modes und Subagents
   Enthält: Systemprompts, System-Prompt-Änderungen, Zuverlässigkeitsdesign, Hooks

5. Skills vereinen dynamischen Kontext
   Enthält: Skills-Konzept, dynamisches Laden, Optimierung von Programmierwerkzeugen

6. Best Practices und Zukunftsausblick
   Enthält: Rules-Empfehlungen, Skills-Erkundung, Zusammenfassung der Kernideen

✓ Alle Inhalte abgedeckt, keine Lücken

Soll die Generierung beginnen? (J/N)

Wichtige Garantien:

• ✅ Vollständige Inhalte: Alle wichtigen Informationen werden einem Bild zugeordnet
• ✅ Logische Klarheit: Aufteilung nach natürlicher Logik des Inhalts
• ✅ Benutzerkontrolle: Ergebnisse werden vor der Generierung angezeigt und bestätigt

Schritt 4: Bilder generieren

Nach Bestätigung ruft Codex das Python-Skript zur Generierung auf:

🖼️  Generierung gestartet…

Generiere Deckblatt…
  ✓ Gespeichert: /pfad/zum/dokument/images/cover.png

Generiere Bild 1/6…
  Titel: Geburt und Entwicklung von Rules
  ✓ Gespeichert: /pfad/zum/dokument/images/illustration-01.png

Generiere Bild 2/6…
  Titel: Commands und Workflow-Pakete
  ✓ Gespeichert: /pfad/zum/dokument/images/illustration-02.png

…

✨ Fertig! Insgesamt 7 Bilder generiert (1 Deckblatt + 6 Inhaltsillustrationen)

Schritt 5: Ergebnis ausgeben

Ausgabeort: Ordner images/ im Verzeichnis des Dokuments

/pfad/zum/deinem/dokument/
└── images/
    ├── cover.png              # Deckblatt (falls ausgewählt)
    ├── illustration-01.png    # 1. Inhaltsillustration
    ├── illustration-02.png    # 2. Inhaltsillustration
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 Stilbeschreibungen

1. Gradient-Glas-Stil (gradient-glass)

Merkmale:

• Minimalistisches Apple-Keynote-Design
• Glassmorphismus-Design
• Tiefschwarzer oder reinweißer Hintergrund
• Fließende Aurora-Verläufe
• 3D-Glaselemente und Leuchteffekte

Anwendungsbereiche:

• Technische Produktvorstellungen
• Datenanalyseberichte
• Zukunftsausblicke
• Produktfunktions-Demos

2. Ticket-Stil (ticket)

Merkmale:

• Digital-minimalistisches Ticket-Design
• Hoher Kontrast in Schwarz-Weiß
• Ähnlich wie Boarding-Pässe oder Eintrittskarten
• Präzise geometrische Aufteilung
• Gemischtsprachige Anordnung

Anwendungsbereiche:

• Infografiken
• Statistische Darstellungen
• Zeitlinien und Flussdiagramme
• Zusammenfassungen

3. Vektorillustrations-Stil (vector-illustration)

Merkmale:

• Flache Vektorgrafiken
• Einheitlich dicke schwarze Konturen
• Retro, sanfte Farben
• Geometrische Darstellung
• Horizontale Panorama-Komposition

Anwendungsbereiche:

• Geschichten erzählen
• Konzepte erklären
• Bildungsinhalte
• Markenwerbung

💡 Anwendungsbeispiele

Beispiel 1: Vollständiger Ablauf

Benutzer: Generiere mir Illustrationen für ~/blog/ai-tools.md im Ticket-Stil

Codex: Gerne, lies mich das Dokument lesen…
        [Dokument lesen, Inhalt analysieren]

        Dokumentlänge ca. 3000 Wörter, Thema: KI-Tool-Evolution.

        Bitte wähle das Seitenverhältnis:
        1. 16:9 (Querformat)
        2. 3:4 (Hochformat)

Benutzer: 1

Codex: Soll ein Deckblatt generiert werden?
        1. Ja
        2. Nein

Benutzer: Ja

Codex: Wie viele Inhaltsillustrationen?
        Empfohlener Bereich: 3–10
        Basierend auf Inhalt: 5 empfohlen

Benutzer: 5

Codex: [Zeigt die 5 zusammengefassten Themen]
        Soll die Generierung beginnen?

Benutzer: J

Codex: [Startet Python-Skript, generiert 6 Bilder]
        ✨ Fertig! Bilder gespeichert unter ~/blog/images/

Beispiel 2: Reines Textdokument

Benutzer: Erstelle Illustrationen für diese Textnotiz

Codex: [Liest Notiz, versteht auch ohne Überschriften]
        [Identifiziert intelligent 3 Kernthemen]
        [Fragt Konfiguration ab, zeigt Zusammenfassung, generiert]

Beispiel 3: Benutzerdefinierte Anzahl

Benutzer: Ich möchte 8 Bilder, Hochformat, kein Deckblatt

Codex: Ok, 16:9 Hochformat, kein Deckblatt, 8 Inhaltsillustrationen.
        [Fasst das Dokument in 8 Themen zusammen]
        [Zeigt Zusammenfassung, nach Bestätigung generieren]

🔧 Technische Details

Bildspezifikationen

Die folgenden Seitenverhältnisse und Auflösungen gelten für Gemini; Nebula image2-4k unterstützt nur 16:9, 3840x2160. Wählt der Benutzer Nebula, wird direkt 4K verwendet; bei Anfrage nach 2K oder Hochformat werden die Einschränkungen erklärt und eine unterstützte Lösung gefunden.

Verhältnis	Auflösung	Anwendungsbereich
16:9	2560x1440 (2K)	Präsentationen, horizontale Anzeige
3:4	1920x2560	Soziale Medien, Hochformat-Ansicht

Optional 4K-Auflösung:

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

API-Aufrufe

• Gemini-Modell: gemini-3-pro-image-preview (aktueller Standard im Skript)
• Nebula-Modell: gpt-image-2-4k, verwendet image2-4k-Gruppentoken
• Kosten: Jedes Bild = 1 API-Aufruf
• Geschwindigkeit: Abhängig von der Backend-Last; Nebula 4K-Request-Timeout: 1800 Sekunden

Backend-Auswahl und Nebula-Aufruf

nanobanana-Gruppe

Wenn der Benutzer nanobanana angibt, wird bei beiden Skripten --provider nanobanana übergeben. In der einheitlichen .env wird der dedizierte NEBULA_NANOBANANA_API_KEY (nanobanana-Gruppentoken) verwendet, nicht der image2-4k-Schlüssel. NEBULA_NANOBANANA_MODEL ist standardmäßig gemini-3.1-flash-image, kann aber auf ein anderes vom Token unterstütztes Modell gesetzt werden; ILLUSTRATOR_IMAGE_PROVIDER=nanobanana kann als Standard gesetzt werden. Sowohl Einzel- als auch Stapelbilder unterstützen 16:9, 3:4; 1K, 2K, 4K können angefordert werden, Standard 2K; die tatsächlich unterstützten Werte und Pixel hängen vom gewählten Modell ab, nicht von der image2-4k-4K-Beschränkung.

Die einheitliche .env verwendet ILLUSTRATOR_SINGLE_RATIO für das Standard-Seitenverhältnis eines Einzelbildes, ILLUSTRATOR_BATCH_RATIO für das Standard-Seitenverhältnis einer Stapelgenerierung und ILLUSTRATOR_RESOLUTION für die Standard-Auflösung. Beide Einstiegspunkte unterstützen --ratio und --resolution, um die Konfiguration zu überschreiben. Wenn diese nicht konfiguriert oder leer sind, ist das Seitenverhältnis 16:9 und die Auflösung der Backend-Standard (Gemini/nanobanana: 2K, image2-4k: 4K). Diese Einstellungen gelten für alle Backends; wenn sie mit Backend-Einschränkungen kollidieren, wird vor der Anfrage ein Fehler ausgegeben; dann muss die Konfiguration angepasst oder explizit überschrieben werden.

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "Thema" --content "Bildinhalt" --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

Ruft Gemini nativ POST /v1beta/models/{model}:generateContent auf, dekodiert und validiert das Bild aus inlineData, speichert keine vollständige Base64-Antwort. Kein Google SDK erforderlich. Der aktuelle Anschluss unterstützt nur Text-zu-Bild; bei Timeout werden kostenpflichtige Tasks nicht automatisch wiederholt. Siehe README.md und offizielle API-Beschreibung.

Ursprüngliche image2-4k-Gruppe

Beide Skripte unterstützen --provider gemini|nebula. Ohne Angabe wird ILLUSTRATOR_IMAGE_PROVIDER gelesen, bei Nichtkonfiguration wird Gemini verwendet. Wenn der Benutzer explizit Nebula angibt, wird --provider nebula übergeben; kein Wechsel zu einem anderen Dienst. Konfiguriere NEBULA_API_KEY im einheitlichen Pfad ~/.agents/skills/document-illustrator/.env oder verwende eine gleichnamige Umgebungsvariable; das Token muss zur image2-4k-Gruppe gehören. Nebula benötigt keinen Gemini-Schlüssel oder Google SDK, benötigt aber Pillow und python-dotenv.

python -X utf8 scripts/generate_single_image.py --provider nebula --title "Thema" --content "Bestätigter Bildinhalt" --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

Das Skript ruft POST https://img-api.apinebula.ai/v1/images/generations auf und verwendet fest gpt-image-2-4k, 3840x2160, quality=high, response_format=url. Bevorzugt liest es die URL, ist aber auch für Base64 kompatibel; vor dem Speichern wird die tatsächliche Pixelzahl überprüft und das Server-JPEG in das zur lokalen Dateierweiterung passende Format umgewandelt. Die API-Antwort wird als <Bildname>.response.json gespeichert; bei fehlgeschlagenem Download wird zuerst der darin enthaltene temporäre Link für einen erneuten Download verwendet. Nach POST-Timeout ist der Task-Status möglicherweise unbekannt; es erfolgt kein automatischer Neustart; zuerst den Serverstatus prüfen, um Doppelabrechnung zu vermeiden. Bei HTTP 403 oder wenn die Verbindung noch nicht hergestellt wurde, wird ein Proxy unter http://127.0.0.1:81 versucht. Derzeit ist nur Text-zu-Bild angebunden; Referenzbildbearbeitung ist nicht implementiert.

Vollständige Konfiguration und Offline-Testbefehle siehe README.md, die API-Parameter basieren auf der offiziellen Dokumentation.

Umgebungsvoraussetzungen

Erforderlich:

pip install google-genai pillow python-dotenv

API-Schlüssel:

• Alle Agenten (Codex, Claude usw.) lesen einheitlich aus ~/.agents/skills/document-illustrator/.env
• Windows: %USERPROFILE%\.agents\skills\document-illustrator\.env
• Nur diese Datei wird geladen; ihre Werte überschreiben gleichnamige Umgebungsvariablen; existiert die Datei nicht, werden nur vorhandene Umgebungsvariablen verwendet, es wird nicht an anderen Orten gesucht
• Gemini verwendet GEMINI_API_KEY, Nebula verwendet NEBULA_API_KEY
• Die nanobanana-Gruppe verwendet NEBULA_NANOBANANA_API_KEY; die Modellkonfiguration siehe oben

📊 Zusammenfassungsprinzipien

Claude folgt bei der Zusammenfassung den folgenden Prinzipien:

1. Vollständigkeit zuerst

• ✅ Alle wichtigen Informationen werden eingeschlossen
• ✅ Keine Kernkonzepte werden übersehen
• ✅ Die Kernaussagen des Originals bleiben erhalten

2. Logische Klarheit

• Aufteilung nach natürlicher Logik des Inhalts
• Zusammengehörige Inhalte werden zusammengefasst
• Erzählfluss bleibt erhalten

3. Ausgewogene Verteilung

• Jedes Bild enthält eine ähnliche Informationsmenge
• Vermeidung überladener oder leerer Bilder
• Anpassung nach Wichtigkeit des Inhalts

4. Benutzerkontrolle

• Zusammenfassung wird dem Benutzer zur Bestätigung angezeigt
• Benutzer kann Anpassungen anfordern
• Generierung beginnt erst nach Bestätigung

🐛 Fehlerbehebung

Problem 1: API-Schlüsselfehler

Fehlermeldung:

Error: Invalid API key

Lösung:

1. Überprüfe im .env den GEMINI_API_KEY oder NEBULA_API_KEY für das entsprechende Backend; bei Nebula zusätzlich die Tokengruppe prüfen
2. Stelle sicher, dass der API-Schlüssel gültig und nicht abgelaufen ist
3. Neuen Schlüssel unter https://makersuite.google.com/app/apikey abrufen

Problem 2: Unbefriedigende Zusammenfassung

Problem: Die zusammengefassten Themen entsprechen nicht den Erwartungen

Lösung:

1. Teile Codex in der Zusammenfassungsphase deine Wünsche mit
2. Codex wird die Zusammenfassung überarbeiten und anpassen
3. Bestätige erst, wenn du zufrieden bist

Problem 3: Bildgenerierung fehlgeschlagen

Mögliche Ursachen:

• Netzwerkverbindungsprobleme
• API-Kontingent ausgeschöpft
• Inhalt zu lang, überschreitet Limit

Lösung:

1. Netzwerkverbindung prüfen
2. API-Kontingent prüfen
3. Versuche, die Anzahl der Bilder zu erhöhen (um den Inhalt zu verteilen)

💰 Kostenschätzung

Bilderanzahl	API-Aufrufe	Geschätzte Kosten
Ohne Deckblatt + 3 Bilder	3 Aufrufe	Niedrig
Mit Deckblatt + 5 Bilder	6 Aufrufe	Mittel
Mit Deckblatt + 10 Bilder	11 Aufrufe	Höher

Empfehlung:

• Kurze Dokumente (<1000 Wörter): 3–5 Bilder
• Mittlere Dokumente (1000–3000 Wörter): 5–7 Bilder
• Lange Dokumente (>3000 Wörter): 8–10 Bilder

📚 Best Practices

1. Angemessene Anzahl von Bildern wählen

Zu wenige:

• Jedes Bild enthält zu viele Informationen
• Schwer verständlich und einprägsam

Zu viele:

• Inhalte werden auseinandergerissen
• Erhöht Kosten und Generierungszeit

Empfohlen:

• Nach Dokumentlänge wählen
• Jedes Bild sollte 1–2 Kernpunkte abdecken

2. Seitenverhältnis nach Verwendungszweck wählen

16:9 geeignet für:

• PPT-Präsentationen
• Website-Banner
• Videocover
• Blog-Illustrationen (Desktop)

3:4 geeignet für:

• Soziale Medien (Instagram, Xiaohongshu)
• Mobile Artikel
• Posterdesign
• Hochformat-Videos

3. Verwendung von Deckblättern

Situationen, in denen ein Deckblatt empfohlen wird:

• Serienartikel (als einheitlicher Einstieg)
• Social-Media-Sharing (als Vorschaubild)
• Dokument-Startseite (Zusammenfassung des gesamten Inhalts)

Situationen, in denen darauf verzichtet werden kann:

• Nur für den internen Gebrauch
• Genügend Bilder vorhanden
• Kosten reduzieren

4. Stilempfehlungen

Technische Dokumentation → Gradient-Glas-Stil Datenberichte → Ticket-Stil Tutorials/Geschichten → Vektorillustrations-Stil Produktvorstellungen → Gradient-Glas-Stil

🔄 Funktionsweise

Traditioneller Ansatz (veraltet)

[Code] Dokument lesen → ## ### Überschriften erkennen → Mechanisches Aufteilen
       ↓
     Abhängig von bestimmtem Format
     Inhalt leicht übersehen
     Nicht intelligent

Neuer Ansatz (aktuelle Implementierung)

[Claude] Dokument lesen → KI versteht Inhalt → Intelligente Themenzusammenfassung
         ↓
       Formatunabhängig
       Vollständiger Inhalt
       Benutzerkontrolle

Kernunterschied:

• ❌ Alter Ansatz: Abhängig von Code-Analyse, kann nur Standardformate verarbeiten
• ✅ Neuer Ansatz: KI versteht Inhalt, jedes Format ist möglich

🎯 Vergleich mit anderen Tools

Funktion	Document Illustrator	Traditionelle PPT-Tools	KI-Bildgeneratoren
Dokumentinhalt verstehen	✅ KI-Intelligenz	❌ Manuell nötig	❌ Manuelle Eingabe nötig
Formatabhängigkeit	✅ Formatunabhängig	❌ Abhängig von bestimmtem Format	✅ Keine Abhängigkeit
Inhaltsvollständigkeit	✅ Automatische Prüfung	⚠️ Manuelle Sicherstellung	❌ Nicht garantierbar
Stapelgenerierung	✅ Mehrere auf einmal	❌ Bild für Bild	⚠️ Mehrere Eingaben nötig
Stilkonsistenz	✅ Automatisch	⚠️ Manuelle Anpassung	⚠️ Wiederholte Prompts nötig

📞 Hilfe erhalten

Bei Fragen oder Vorschlägen:

1. Frage direkt in Codex
2. Skill-Verzeichnis prüfen: ~/.agents/skills/document-illustrator

---

Lass die KI deine Inhalte verstehen und zusammenfassen – und professionelle Bilder dazu generieren! ✨