Bildvariationen (Skill 01)
Einziger Einstiegspunkt. Die Orchestrierung ist hier beschrieben; der vollständige Text, Prompt-Vorlagen, Provider-Kompatibilitätsmatrix, Fehlercodes und Schwellwerte in 12 Richtungen sind nicht hier, sondern bei Bedarf immer aus der eingefrorenen Basislinie zu lesen, um zwei voneinander abweichende Wahrheiten zu vermeiden.
- Geschäftsregeln:
Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md - Richtungsregister:
.../references/directions/registry.json - Prompt-Vorlagen:
.../references/grid-prompt.md,.../references/sequence-prompt.md - Provider-Kompatibilität und Sicherheit:
.../references/provider-compat.md - Fehlercodes:
.../references/error-registry.json - Verpackungsregeln:
.../references/packaging.md - Verträge:
.../contracts/{image-artifact,job-state,delivery-package}.schema.json
Die Basislinie ist schreibgeschützt: Die Hash-Liste befindet sich in shared/baseline.manifest.json, shared/check_baseline.py muss immer grün sein. Wenn die Spezifikation geändert werden muss, bitte zuerst die Begründung darlegen und eine Bestätigung einholen, die Basislinie nicht stillschweigend in der Implementierung „korrigieren".
1. Fünf unverletzliche Regeln
- Keine stillschweigende Herabstufung. Bei unzureichenden Fähigkeiten, unzureichendem Budget oder fehlgeschlagener Validierung wird immer explizit ein Fehlercode aus
references/error-registry.jsonzurückgegeben; es ist nicht erlaubt, „leise auf eine kleinere Größe/geringere Qualität/weniger Bilder umzuschalten" und weiterzumachen, noch ist es erlaubt, einen Fehler als Erfolg zu melden. - Schwellwerte werden nur aus der Konfiguration gelesen.
config/iv.config.jsonist die einzige Quelle (warn/hard für Kachelkanten, pass/risk für Nähte, Vergrößerungsfaktor, Wiederholungen und Budget). Diese sind noch nicht mit echten Modellen kalibriert; vor einer Änderung zuerst Daten liefern. Im Code dürfen keine magischen Zahlen vorkommen. - Einzige Quelle der Wahrheit. Richtungen, Prompts, Fehlercodes und Verträge werden zur Laufzeit aus der Basislinie gelesen und nicht in diesen Skill kopiert.
- Schlüssel nur als Referenz. Es werden nur
secret://...oderenv:...akzeptiert; Schlüssel, Originalbilder und Benutzertexte dürfen nicht in Logs, Manifest, Fehlermeldungen oder ZIPs gelangen. - Artefakte müssen überprüfbar sein. Jede Lieferung enthält
manifest.json(image-artifact1.1) unddelivery-package.json; jeder Eintrag im Manifest muss tatsächlich existieren und der Hash muss übereinstimmen.
2. Verwendung
# 1) Vorabprüfung: Nur Plan berechnen, kein Modell aufrufen, nichts auf Platte schreiben
python scripts/run_task.py --input task.json --preflight-only
# 2) Ausführung (bei fehlenden Schlüsseln mit mock_synthetic die gesamte Kette durchspielen)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty
# 3) Wenn nur einige Frames fehlgeschlagen sind, nachträglich mit den ursprünglichen Indizes generieren (erzeugt rev2, parent zeigt auf rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1
Aufgabenbeschreibung (ein JSON, Felder konsistent mit den Produktparametern aus references/provider-compat.md):
{
"task_id": "cup_light_001",
"output_mode": "grid", // grid | sequence
"grid_size": 3, // grid Pflichtfeld: 2 | 3 | 4
"direction": "light", // Eine von 12 Richtungen, siehe registry.json
"input_type": "text_only", // text_only | image_only | image_plus_text
"subject": "eine hellgraue Keramiktasse", // Subjektbeschreibung, geht in den Subjektanker
"reference_path": "img/ref.png", // Pflichtfeld bei Bildeingabe, relativ zum workspace
"aspect_ratio": "3:4",
"resolution_tier": "1K", // 1K | 2K | 4K; default wir vom minimalen Kacheldurchmesser abgeleitet
"provider": {"type": "mock_synthetic"},
"pack_zip": true
}
sequence benötigt zusätzlich branch (einer der 3 von der Richtung unterstützten Zweige) und image_count (4–16).
Echter Provider:
"provider": {
"type": "openai_image_compatible", // oder gemini_image_compatible
"base_url": "https://api.example.com/v1",
"model_id": "gpt-image-1",
"api_key_secret_ref": "secret://IMAGE_API_KEY",
"capability": { "...": "siehe provider-compat.md §1 Fähigkeitserklärung" }
}
Fehlt capability, gilt die Fähigkeit als nicht erfüllt und es wird MODEL_CAPABILITY_UNSUPPORTED gemeldet – es ist die „Mindestanforderungsliste" und wird nicht durch Standardwerte stillschweigend ergänzt. Wenn der eingebaute Adapter nicht injiziert wird, wird BUILTIN_UNAVAILABLE gemeldet; es wird nicht automatisch auf einen externen Dienst umgeschaltet.
3. Ablauf (Zweigregeln)
Eingabe parsen → Vorabprüfung (Fähigkeit/Seitenverhältnis/Stufe/Anzahl/Budget)
├─ nicht bestanden → Fehlercode melden, Ende (kein Modell aufrufen, nichts auf Platte schreiben)
└─ bestanden ─┬─ Grid: Einmalige Tafel erstellen → Validierung (N×N / nahtlos / schneidbar / Seitenverhältnis) → Begrenzte gesamte Tafelwiederholungen
│ → Normalisieren → Zeilenweise schneiden → Jede Kachelkante bewerten (ok / risk / too_low)
└─ Sequence: Zuerst N Frame-Pläne erstellen (Framenummer, Änderungspunkte pro Frame, gleichbleibende Elemente, Prompt)
→ Frame für Frame generieren (Bild 1 als Basis, Bilder 2–N beziehen sich immer auf Bild 1; falls Originalbild vorhanden, jedes Frame mit Originalbild)
→ Bei fehlgeschlagenem Frame wird der Slot beibehalten und fortgefahren; Fehler bei Bild 1 sofort SEQUENCE_ANCHOR_FAILED
→ Nahe-Duplizierungserkennung (nach Erschöpfung der Wiederholungen Slot beibehalten und kennzeichnen)
→ Auf Platte schreiben (manifest + delivery-package + optional ZIP) → JSON-Ergebnis zurückgeben
Wichtige Entscheidungen:
| Situation | Behandlung |
|---|---|
grid_size nicht 2/3/4, Sequenz nicht 4–16 | INVALID_MODE_OR_COUNT |
| Kacheldurchmesser unter hartem Schwellwert | TILE_RESOLUTION_TOO_LOW, kein Lieferpaket |
| Kacheldurchmesser unter warn-Schwellwert | Ausliefern, aber TILE_RESOLUTION_RISK Warnung (mit tile_edge_ok=false) |
| Naht < risk-Schwellwert | GRID_VALIDATION_FAILED, gesamte Tafel wiederholen; keine Schnittbilder ausliefern |
| Naht zwischen risk und pass | Ausliefern mit GRID_SEAM_RISK |
| Tafelstruktur/-verhältnis N×N nicht erfüllt | GRID_VALIDATION_FAILED |
| Bild 1 fehlgeschlagen | SEQUENCE_ANCHOR_FAILED, Budget nicht weiter verbrauchen |
| Frame i fehlgeschlagen | Ursprünglichen Indexslot beibehalten, mit restlichen Frames fortfahren, endgültig partial_failed |
| Budget wird überschritten? | BUDGET_EXCEEDED (kann Aufteilungsvorschlag beifügen, aber nicht automatisch splitten) |
4. Artefakte
workspace/iv_<task_id>_<revision>/
├── manifest.json # image-artifact 1.1 (Stil/Größe/Naht/Ausführung/Warnungen/Fehler)
├── delivery-package.json # Paketliste (sha256 pro Datei)
├── board.png # Nur Grid: kind=board, index=0
└── images/NN.png # Grid=Schnittbilder tile (zeilenweise); Sequence=frame (Index nicht hochgezählt? Der Index wird nicht vorgezogen)
Im selben Verzeichnis befindet sich optional iv_<task_id>_<revision>.zip als verpacktes Artefakt. Das ZIP enthält delivery-package.json nicht selbst; der archive-Hash wird in delivery-package.json zurückgeschrieben.
Bei teilweisem Fehlschlag: Es werden nur die tatsächlich existierenden Bilder registriert (fehlgeschlagene Frames kommen nicht in images[]), die Fehlerinformationen stehen in errors[].asset_id + validation.failed_indices, status=partial_failed. Bei erneuter Ausführung wird eine neue Revision erstellt (parent_artifact_revision zeigt auf die vorherige Version), erfolgreich abgeschlossene Frames bleiben bytegenau unverändert.
5. Grenzen
- Es werden nur Bildvarianten erstellt. Texterstellung, Veröffentlichung auf Plattformen, Cover-Layout gehören zu Skill 02 (
image-content-publishing); dieser Skill überschreitet diese Grenzen nicht. - Wenn der Benutzer explizit mehrere Richtungen anfordert, wird nur eine ausgewählt und begründet, oder es wird
MULTIPLE_DIRECTIONSgemeldet; es wird nicht gemischt. - Es werden keine Grenzfälle wie „Stiltransfer zu Werken anderer" bearbeitet; bei realen Personen/Marken wird nach den Sicherheitsanforderungen in
provider-compat.md §4verfahren. - Die für Selbsttests verwendeten
mock_synthetic-Artefakte werden fest mitprovider_type=mock_syntheticgekennzeichnet und dürfen nicht ausgeliefert werden.
6. Entwicklung und Validierung
.venv/bin/python skills/image-variations/tests/run_all.py # 9 Suiten (inkl. Basislinie 24/24 und Verträge 48/48)
.venv/bin/python shared/check_baseline.py # Schreibgeschützte Basislinienvalidierung
Nachweise und bekannte Abweichungen sind in docs/PHASE_EVIDENCE.md dokumentiert.