chulegexiaojiu/character-refs

Was macht character-refs?

Gib eine Charakterbeschreibung ein, und erhalte eine Reihe von Referenzbildern – der Charakter kann aus jeder Quelle stammen: Romanadaption, eigene Geschichte, spontane Idee. Ein frontaler Ganzkörper-Ankerpunkt, und jedes weitere Bild bezieht sich ausschließlich auf diesen Anker. Verwende die Bilder als Referenz für Videomodelle (H3 / Wan / Seedance) oder zur Ansicht für Menschen.

{baseDir} = Verzeichnis dieser Datei. Skript {baseDir}/scripts/character-refs.mjs, keine Abhängigkeiten, direkt mit node ausführbar.

Dies ist das einzige Skill im Repository, das tatsächlich Bilder generiert. Alle anderen Skills liefern nur Prompts, denn erst beim Generieren entscheiden sich Modell und Stil; dieses Skill ist der „Moment“ – das Modell wird in Schritt 0 vom Benutzer gewählt, der Stil beim Erstellen des Charakters (Standard: Anime, mit Fotorealismus-Voreinstellung und benutzerdefinierten Stilen).

Kernregeln (erst lesen, dann loslegen)

• Ein Bildsatz hat nur eine Wurzel: den frontalen Ganzkörper-Anker. Nur dieser wird aus Text generiert, alle anderen sind „Anker + eine Umbau-Anweisung“. Für Haare, Gesicht und Kragen gibt es zusätzlich bestätigte frontale Porträts. Bilder referenzieren sich nicht gegenseitig – daher kann jedes einzeln neu generiert werden, ohne Kettenreaktion.

• Drei Stufen, standardmäßig bis Stufe 2:

  Stufe	Inhalt	Wann ausgeben
  1	Frontaler Ganzkörper (Anker)	Immer, als erstes
  2 (Standard)	Frontales Porträt, 90°-Seitenansicht (Gesicht nach rechts), Rückenansicht	Standardmäßig alle
  3	Detailaufnahmen (max. 8): vom Benutzer genannte, charakteristische Merkmale; sonst Standard: Haare/Kopfschmuck, Kragen, Manschetten, Schuhe	Bei Accessoires oder lokalen Kleidungsdetails
  4 (Standardmäßig deaktiviert)	45°-Porträt (Gesicht nach links)	Nur auf expliziten Wunsch

  H3-Erfahrung: Nur frontaler Ganzkörper – Kleidung und Rücken stimmen, aber das Gesicht driftet ab; ein Porträt dazu, das Gesicht bleibt am ähnlichsten. Daher standardmäßig Stufe 2. Nur den Anker (z.B. um zuerst das Aussehen zu prüfen): gen <asset.json> --tier 1.

• Modell nicht festgelegt: Haupt- und Nebenbilder können verschiedene Modelle verwenden, auch beim Neugenerieren kann das Modell gewechselt werden. Konsistenz kommt vom „gleichen Anker“, nicht vom „gleichen Modell“ (getestet: Qwen-Anker + GPT-Nebenbilder, GPT-Anker + Qwen-Nebenbilder, Mischung in einer Gruppe funktioniert). Jedes Bild speichert sein Modell; Mischung wird nur im Report vermerkt.

• Nur drei Dinge sind eingefroren: Anker-Datei (sha256), Stil-Snapshot, Textbeschreibungs-Fingerprint. Ändert sich eines, werden abhängige Bilder als „veraltet“ markiert – nur markiert, nicht gelöscht, alle alten Versionen bleiben erhalten.

---

Schritt 0 – Ersteinrichtung (einmal pro Maschine)

node {baseDir}/scripts/character-refs.mjs config --show

Am Ende der Ausgabe steht „Fehlt: …“ – dann den Benutzer nach diesen drei Dingen fragen, alle auf einmal:

1. Modell für Hauptbild (Anker):
   • qwen – Qwen Image 2.1 über eigenen ComfyUI-Server. Schnell (25–45 s pro Bild), genaue Maße, kein Abo-Kontingent. Benötigt COMFY_URL (optional COMFY_USER / COMFY_PASS) in Umgebungsvariablen oder .env-Datei
   • codex – integrierte Bildgenerierung von Codex (GPT). Kein API-Key, aber verbraucht ChatGPT-Abo-Kontingent (Plus ca. 25 Bilder, Obergrenze; nach Stunden wieder verfügbar), 80–160 s pro Bild
   • openai – OpenAI Images API, Standard gpt-image-2. Nutzungsbasiert, benötigt OPENAI_API_KEY; kann auf kompatible Schnittstellen umgeleitet werden (--openai-base-url)
   • custom:<Name> – eigener Befehl des Benutzers, siehe references/models.md
2. Modell für Nebenbilder: Standardmäßig gleich wie Hauptbild. Kann getrennt werden (z.B. Anker GPT, Nebenbilder Qwen)
3. Nach dem Anker anhalten und bestätigen lassen? Empfohlen yes – der Anker ist die Wurzel der gesamten Gruppe; ist er falsch, sind alle folgenden Bilder umsonst. Bei no automatisch fortfahren, mit Vermerk „nicht manuell bestätigt“ im Report; Anker, die die Prüfungen nicht bestehen, werden nicht automatisch freigegeben – menschliche Prüfung und confirm oder Neugenerierung erforderlich.

node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <.env-Pfad>
# Getrennte Einstellung: --anchor-model codex --derive-model qwen

Konfiguration in {baseDir}/config.local.json (nicht versioniert, wird bei Neuinstallation nicht überschrieben). Danach immer standardmäßig verwendet; bei „Ändere zu xx“ einfach config erneut ausführen. Keine Passwörter oder Keys aus .env ausgeben – config --show maskiert sie bereits.

Schritt 1 – Einmalige Eingabe

Der Benutzer beschreibt den Charakter in einem Absatz – keine Einzelfeldabfrage. Du (das Modell) zerlegst:

node {baseDir}/scripts/character-refs.mjs intake-template

Gemäß der Vorlage die Beschreibung in Felder aufteilen und in <Arbeitsverzeichnis>/<Charaktername>-intake.json schreiben. Regeln (Details in references/intake.md):

• lang: Sprache des Benutzers (Chinesisch zh, Englisch en, Japanisch ja sind integriert). Bestätigungstabelle und Report in dieser Sprache; bei anderen Sprachen zuerst ui-template <lang> ausführen, den englischen Text Zeile für Zeile übersetzen und vollständig in das ui-Feld des Intake einfügen
• stated für vom Benutzer Genanntes, inferred für von dir Erschlossenes, default für Konventionsergänzungen – wahrheitsgemäß markieren; die Bestätigungstabelle macht den Benutzer darauf aufmerksam, welche Punkte zu prüfen sind
• Alter, Geschlecht, Epoche: wenn nicht erschließbar, den Benutzer fragen – nur diese drei dürfen nicht selbst erfunden werden; alles andere selbst ergänzen, nicht nachfragen
• en für Prompt: immer Englisch, keinen Charakternamen, keine Stilbegriffe; text für Menschen, in der Sprache von lang (auch alte Eingaben in zh werden erkannt)
• Kleidung in top / bottom aufteilen – Porträts verwenden nur Oberteil; mit Ober- und Unterteil rückt das Modell die Kamera weiter weg
• Detailaufnahmen nach Charakter wählen: Vom Benutzer genannte priorisieren; sonst die charakteristischsten Merkmale wählen; Standard vier Slots als Rückfall; Gesichtsmerkmale nicht als Detailaufnahme (Porträt zeigt sie bereits). Siehe references/intake.md

node {baseDir}/scripts/character-refs.mjs intake-check <intake.json>

Bei Fehlern korrigieren, bis alles durchgeht. Danach wird die Bestätigungstabelle ausgegeben – dem Benutzer unverändert zeigen, mit Markierungen für erschlossene und Standardfelder. Erst nach Bestätigung (oder Änderung + Bestätigung) durch den Benutzer weitermachen.

Schritt 2 – Asset erstellen

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <Ausgabeverzeichnis> [--look Stil]

Erzeugt <Ausgabeverzeichnis>/<Charaktername>/asset.json. Der Stil wird zu diesem Zeitpunkt vollständig gesnapshotet; spätere Änderungen an Voreinstellungen beeinflussen bestehende Charaktere nicht.

Stil: Wenn vom Benutzer genannt, diesen verwenden; sonst Anime. Charaktere derselben Serie verwenden durchgängig denselben Stil.

Voreinstellung	Name für --look
Anime (Standard)	动漫 卡通 anime cartoon 二次元 アニメ
Fotorealismus	写实 realistic photo 真人

looks listet alle Voreinstellungen auf. Für andere Stile (Chinoiserie, amerikanischer Comic …): look-template <nächste Voreinstellung> > my-look.json, dann style (Medium, Linien), clean (Hintergrund und Licht, weißer Hintergrund zwingend), neg (Negativ-Prompt – bei gezeichnetem Stil anime illustration aus Negativ-Prompt entfernen) anpassen, bei gezeichnetem Stil medium auf drawn setzen, dann --look my-look.json. Für benutzerdefinierte Stile gibt es keine Tests; zuerst den Anker generieren und prüfen.

Stilwechsel bei bereits erstelltem Charakter:

node {baseDir}/scripts/character-refs.mjs restyle <asset.json> --look Anime

Danach werden alle vorhandenen Bilder (auch der Anker) als veraltet markiert – alte Bilder bleiben erhalten, Neugenerierung ab Anker.

Schritt 3 – Standardmäßig Stufe 2 ausgeben

node {baseDir}/scripts/character-refs.mjs gen <asset.json>

Ohne Ansichts- oder Stufenangabe werden alle noch nicht generierten oder veralteten Bilder der Stufen 1 und 2 ergänzt.

Bei konfigurierter Bestätigung: Der Befehl stoppt nach dem Anker. Dem Benutzer das Bild zeigen (Report oder direkt PNG öffnen). Wenn der Benutzer zustimmt:

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # Gleicher Befehl, fährt mit Porträt, Profil, Rücken fort

Bei Unzufriedenheit: erneut gen <asset.json> front-full (erzeugt v2, optional --seed oder --model), oder zurück zu Schritt 1 für Textänderung. Ohne bestätigten Anker werden Nebenbilder abgelehnt. Bei konfigurierter Nicht-Bestätigung werden alle vier Bilder in einem Befehl generiert.

Schritt 4 – Bei Bedarf höhere Stufen

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 hat Kopfschmuck und Kragen-Detail"

--reason für den Grund der Höherstufung, wird im Asset vermerkt. Auch Einzelbilder möglich: gen <asset.json> detail-hair detail-neck.

Schritt 5 – Prüfen und neugenerieren

node {baseDir}/scripts/character-refs.mjs check <asset.json>

Jedes Bild durchläuft Qualitätsprüfungen (Maße 300–5760, Seitenverhältnis 0.4–2.5, proportionale Übereinstimmung, ≤20 MB, ausreichend weißer Hintergrund) und Veralterungsprüfung. Bei Fehlern exit 1. Für fehlgeschlagene oder veraltete Bilder einzeln neugenerieren:

node {baseDir}/scripts/character-refs.mjs gen <asset.json> detail-neck --model codex

„Ausreichend weißer Hintergrund“: Bei Ganzkörperbildern alle vier Seiten prüfen, bei Porträts nur obere Seite und obere Hälfte der Seiten (Körper reicht bis unten), bei Detailaufnahmen überspringen und explizit vermerken. Die Prüfung kann nicht Aussehen, Winkel oder Bildausschnitt bewerten – Bilder immer ansehen, diese Punkte erfordern menschliche Kontrolle.

Schritt 6 – Report

node {baseDir}/scripts/character-refs.mjs render <asset.json>... --out <Ausgabeverzeichnis>/character-refs.html

Mehrere Charaktere möglich. Sprache standardmäßig aus dem Asset lang; temporär mit --lang en ändern; bei nicht integrierten Sprachen ohne ui mit --ui <Datei> eigene Übersetzung übergeben. Wenn Übersetzung fehlt, Fehlermeldung – kein gemischtsprachiger Report. Oberflächentexte wechseln die Sprache, Charakterbeschreibung bleibt im Original. Stufe 1: nur eine Karte; ab Stufe 2: Design-Blatt-Layout (links Porträt, oben rechts Vorder-/Seiten-/Rückansicht, unten rechts Detailleiste). Detailbilder standardmäßig ausgeblendet, auf der Seite mit einem Klick einblendbar. Veraltete Bilder mit rotem Rahmen; Seitenkopf mit Legende; beim Überfahren des roten Rahmens Grund. Bei Modellmischung Warnhinweis.

Schritt 7 – Bericht

Ein Satz: Welche Bilder generiert? Welches Modell verwendet? Pfad zum Report. Bei fehlgeschlagenen oder veralteten Bildern diese benennen. „Sieht toll aus“ nur sagen, wenn du die Bilder gesehen hast.

---

Verzeichnisstruktur

<Ausgabeverzeichnis>/
├── character-refs.html          ← von render erzeugt
└── <Charaktername>/
    ├── asset.json               ← Charakterbeschreibung + alle Versionen jedes Bildes
    └── default/                 ← Look (v1 nur default-Set)
        ├── front-full.v1.png    ← Anker
        ├── face-front.v1.png
        ├── face-front.v2.png    ← Neugenerierung überschreibt nicht
        └── detail-hair.v1.png …

Jede PNG enthält Markierungen (Charakter/Look/Ansicht/Version), Modell, Referenzen; auch bei separatem Kopieren ist die Herkunft nachvollziehbar. Struktur von asset.json in references/schema.md.

Grenzen

• Getestete Stile: nur Fotorealismus und Anime (beide mit Qwen über vier Stufen); benutzerdefinierte Stile hängen von der Umsetzung ab – zuerst Anker generieren und prüfen
• Detailaufnahmen nur für am Körper getragene Merkmale (Kopfschmuck, Kragen, Manschetten, Schuhe); Requisiten gehören zu novel-art
• Bekannte Schwächen: kleine Narben werden leicht als frische Wunden dargestellt; große Details wie Doppelknopfleisten werden zu weit entfernt aufgenommen; Qwen-Kragendetail kann grobes Tuch wie Samt aussehen lassen (dann mit Codex neugenerieren); in Qwen-Detailbildern kann freiliegende Haut älter wirken (Altersangabe im Prompt ist bei 16-jährigem Beispiel wirksam, aber nicht massengetestet)
• openai-Adapter nur mit lokalem Testserver auf Anfrageformat geprüft, nie mit echtem Key getestet; zuerst einen Anker generieren und prüfen
• Gleicher Prompt wurde sowohl auf Qwen als auch auf GPT getestet; Effekt bei benutzerdefinierten Modellen hängt vom Modell ab

Selbsttest

node {baseDir}/scripts/selftest.mjs

230 Assertions, kein Modellaufruf, kein Kontingentverbrauch: PNG-Markierungen lesen/schreiben, Prüfungen, Eingabevalidierung, mehrsprachige Bestätigungstabelle und Report, Stilvoreinstellungen und -wechsel, Prompts, Veralterungsweitergabe, Anfrageformat der Bildadapter (Qwen und GPT Image mit lokalem Testserver) sowie vollständiger Ablauf mit benutzerdefiniertem Befehl. Vor Änderungen am Skript zuerst ausführen.

Mitgeliefertes Beispiel

{baseDir}/examples/阿禾-描述.txt ist eine benutzertypische Ein-Satz-Beschreibung (Tee-Pflückerin aus Jiangnan, 1920er Jahre), 阿禾-intake.json ist die zerlegte Eingabe mit Markierungen für erschlossene und Standardfelder. Beispielbilder nicht versioniert: mit eigenem Modell ausführen, um sie zu sehen.