chulegexiaojiu/character-refs

Que fait character-refs ?

Saisissez une description de personnage, et le skill produit un ensemble d'images de référence. Peu importe d'où vient le personnage : adaptation de roman, histoire inventée, idée spontanée. Une image d'ancrage en pied (vue de face complète), et toutes les autres vues se réfèrent uniquement à cette image d'ancrage.

Utile comme référence pour les modèles vidéo (H3 / Wan / Seedance) et pour l'œil humain.

{baseDir} = répertoire de ce fichier. Le script {baseDir}/scripts/character-refs.mjs ne nécessite aucune dépendance, s'exécute directement avec node.

C'est le seul skill du dépôt qui génère réellement des images. Les autres skills ne fournissent que des prompts, car le choix du modèle et du style dépend du moment de la génération. Ce skill représente ce moment décisif : le modèle est choisi par l'utilisateur à l'étape 0, le style est défini lors de la création du personnage (par défaut anime, mais aussi réaliste ou personnalisé).

Règles fondamentales (à lire avant d'agir)

• Une seule racine par série d'images : l'ancrage en pied. Seule cette image est générée à partir d'un texte ; les autres sont toutes « ancrage + une instruction de modification ». Les cheveux, le visage et le col utilisent en plus un portrait confirmé comme référence dédiée. Les images ne se réfèrent pas entre elles. Ainsi, si une image est ratée, on la régénère seule, sans répercussion en chaîne.

• Palier par défaut : jusqu'au 2ᵉ palier.

  Palier	Contenu	Quand ?
  1	Pied complet, face (ancrage)	Toujours, en premier
  2 (défaut)	Portrait face, profil 90° (visage vers la droite du cadre), dos	Généré par défaut
  3	Détails (max 8) : éléments pointés par l'utilisateur ou les plus distinctifs du personnage ; sinon, défauts : cheveux/accessoires, col, poignets, chaussures	Si accessoires ou détails vestimentaires
  4 (pas par défaut)	Portrait 45° (visage vers la gauche du cadre)	Sur demande explicite

  Testé avec H3 : donner seulement le pied complet donne une tenue et un dos corrects, mais le visage dévie ; ajouter un portrait stabilise le visage. Donc le 2ᵉ palier est généré par défaut. Pour seulement l'ancrage (ex. pour voir la tête d'abord) : gen <asset.json> --tier 1.

• Modèle non figé : l'image principale et les dérivées peuvent utiliser des modèles différents ; la régénération d'une seule image peut aussi changer de modèle. La cohérence vient de « la même ancrage », pas du « même modèle » (testé : ancrage Qwen + dérivé GPT, ancrage GPT + dérivé Qwen, mélange fonctionne). Chaque image enregistre son modèle ; un mélange dans un même jeu est simplement signalé dans le rapport.

• Seuls trois éléments sont figés : le fichier d'ancrage (sha256), un instantané du style, et une empreinte de la description textuelle. Si l'un d'eux change, les images qui en dépendent sont marquées « obsolètes » – marquées seulement, pas supprimées, les anciennes versions restent toutes en place.

---

Étape 0 – Configuration initiale (une fois par machine)

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

Si la sortie se termine par « Il manque : … », demander ces trois choses en une fois :

1. Quel modèle pour l'image principale (ancrage) ?
   • qwen – Qwen Image 2.1 via son propre serveur ComfyUI. Rapide (25–45 s par image), dimensions précises, ne consomme pas de quota d'abonnement. Nécessite COMFY_URL (optionnellement COMFY_USER / COMFY_PASS) dans les variables d'environnement ou un fichier .env
   • codex – générateur d'images intégré de Codex (GPT). Pas de clé API, mais consomme le quota ChatGPT (Plus : environ 25 images avant plafond, rétablissement après quelques heures), 80–160 s par image
   • openai – API OpenAI Images, par défaut gpt-image-2. Facturation à l'usage, nécessite OPENAI_API_KEY ; peut pointer vers une interface compatible (--openai-base-url)
   • custom:<nom> – commande personnalisée de l'utilisateur, voir references/models.md
2. Quel modèle pour les images dérivées ? : Par défaut identique au modèle principal. Peut être différent (ex. ancrage GPT, dérivé Qwen)
3. Faut-il s'arrêter après l'ancrage pour confirmation ? : Recommandé yes – l'ancrage est la racine de tout le jeu ; si elle est fausse, tout le reste est à refaire. Si no, enchaînement automatique, avec mention « non confirmé par l'humain » dans le rapport ; l'ancrage qui échoue aux validations ne passe pas, il faut que l'humain voie et confirm ou régénère.

node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <chemin vers .env>
# Séparé : --anchor-model codex --derive-model qwen

La configuration est écrite dans {baseDir}/config.local.json (hors version, pas écrasée par réinstallation). Elle sera utilisée par défaut ; si l'utilisateur dit « passe à xx », relancer config. Ne jamais afficher de mots de passe ou clés du .env ; config --show les masque déjà.

Étape 1 – Saisie unique

L'utilisateur donne un paragraphe pour décrire le personnage, pas question par question. C'est vous (le modèle) qui décomposez :

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

Suivez le modèle pour décomposer la description dans chaque champ et écrire le fichier <répertoire de travail>/<nom_personnage>-intake.json. Règles (voir references/intake.md) :

• lang : langue de l'utilisateur (zh pour chinois, en pour anglais, ja pour japonais – intégrés). Le formulaire de confirmation et le rapport utiliseront cette langue. Pour d'autres langues, exécutez d'abord ui-template <lang>, puis traduisez manuellement les textes anglais imprimés et placez le bloc dans le champ ui du fichier intake.
• Ce que l'utilisateur a dit est marqué stated, ce que vous déduisez est marqué inferred, ce qui est ajouté par convention est marqué default – indiquez-le clairement ; le formulaire de confirmation l'utilise pour signaler à l'utilisateur ce qui doit être vérifié.
• Âge, sexe, époque : ne les inventez jamais, demandez toujours. Seuls ces trois champs ne doivent pas être déduits ; pour tout le reste, complétez-vous sans demander.
• en : entre dans le prompt – toujours en anglais, sans le nom du personnage ni de mots de style ; text : pour l'humain, écrit dans la langue de lang (les anciennes saisies en zh sont reconnues).
• Vêtements divisés en top / bottom – le portrait n'utilise que le haut ; inclure le bas forcerait le modèle à éloigner le cadre.
• Détails : choisissez selon le personnage : priorité à ce que l'utilisateur a mentionné ; sinon, ce qui le rend le plus reconnaissable ; à défaut, les quatre emplacements par défaut ; les traits du visage ne sont pas mis en détails (le portrait les montre déjà). Voir references/intake.md.

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

Si des erreurs, corrigez jusqu'à validation. Ensuite, il imprime un formulaire de confirmation à montrer à l'utilisateur, avec les marques pour les champs déduits ou par défaut. Ne continuez qu'après confirmation (ou modification puis confirmation) de l'utilisateur.

Étape 2 – Création des assets

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <répertoire de sortie> [--look style]

Crée <répertoire de sortie>/<nom_personnage>/asset.json. Le style est instantané et intégré à l'asset ; les modifications futures du style n'affectent pas les personnages existants.

Style : si l'utilisateur en a parlé, utilisez-le ; sinon, anime par défaut. Tous les personnages d'une même œuvre utilisent le même style.

Préréglage	Nom reconnu par --look
Anime (défaut)	动漫 卡通 anime cartoon 二次元 アニメ
Photo réaliste	写实 realistic photo 真人

looks liste tous les préréglages. Si l'utilisateur veut un autre style (style chinois, comics américain…) : look-template <préréglage le plus proche> > my-look.json, modifiez style (médium, traits), clean (arrière-plan et lumière, doit garder un fond blanc), neg (prompts négatifs – pour un style dessiné, retirez anime, illustration des négatifs), et pour un style dessiné, écrivez medium : drawn, puis --look my-look.json. Les styles personnalisés ne sont pas testés ; générez d'abord l'ancrage pour évaluer.

Pour changer le style d'un personnage déjà créé :

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

Toutes les images existantes (même l'ancrage) sont marquées obsolètes, les anciennes sont conservées, on reprend de l'ancrage.

Étape 3 – Génération du 2ᵉ palier par défaut

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

Sans préciser de vue ou de palier, complète les images manquantes ou obsolètes des paliers 1 et 2.

Si la confirmation est activée : cette commande s'arrête après l'ancrage. Montrez l'image à l'utilisateur (rapport ou ouverture du PNG). Si OK :

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # même commande, continue avec portrait, profil, dos

Sinon, relancez gen <asset.json> front-full (version v2, avec --seed pour changer la graine, --model pour changer de modèle), ou revenez à l'étape 1 pour modifier la description. Tant que l'ancrage n'est pas confirmée, les dérivées sont refusées.

Si configuré sans confirmation, la commande génère les quatre images d'un coup.

Étape 4 – Palier supérieur sur demande

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 : détails coiffure et col"

--reason indique pourquoi on monte en palier, enregistré dans l'asset. On peut aussi ne générer que certaines vues : gen <asset.json> detail-hair detail-neck.

Étape 5 – Vérification et régénération

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

Chaque image passe des vérifications automatisées (dimensions 300–5760, ratio 0.4–2.5, proportions cohérentes, ≤20 Mo, fond assez blanc), puis vérifie l'obsolescence. En cas d'échec, exit 1. Pour une image qui échoue ou est obsolète, régénérez-la seule :

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

« Fond assez blanc » : pour les plans pied, vérifie les quatre bords ; pour le portrait, seulement le bord supérieur et les parties supérieures des côtés (le corps touche naturellement le bas) ; pour les détails, la vérification est ignorée et mentionnée explicitement. Les vérifications ne portent pas sur l'apparence, l'angle ou le cadrage – il faut regarder les images ; ces aspects sont évalués visuellement.

Étape 6 – Rapport

node {baseDir}/scripts/character-refs.mjs render <asset.json>... --out <répertoire de sortie>/character-refs.html

Plusieurs personnages peuvent être réunis. La langue par défaut est celle de l'asset lang ; pour changer temporairement, ajoutez --lang en ; pour une langue non intégrée sans champ ui, utilisez --ui <fichier> pour fournir vos propres textes traduits. Si des textes manquent, une erreur est levée – pas de rapport mi-une langue mi-une autre. Les textes de l'interface changent de langue, la description du personnage reste originale.

Le premier palier a une seule carte ; à partir du deuxième, le rapport adopte une mise en page de fiche technique (portrait à gauche, face/profil/dos en haut à droite, détails en bas à droite), les détails sont cachés par défaut, avec un bouton pour les afficher en un clic. Les images obsolètes ont un cadre rouge ; un légende en haut de page explique les indicateurs ; en survolant une image avec cadre rouge, la raison s'affiche ; un avertissement s'affiche si les modèles sont mélangés.

Étape 7 – Résumé

En une phrase : quelles images ont été générées, avec quel modèle, chemin du rapport. Citer explicitement les échecs aux vérifications ou les obsolescences. Ne dites pas « ça rend bien » sans avoir vu les images.

---

Structure des fichiers

<répertoire de sortie>/
├── character-refs.html          ← sortie de render
└── <nom_personnage>/
    ├── asset.json               ← description du personnage + toutes les versions de chaque image
    └── default/                 ← version du look (v1 n'a que default)
        ├── front-full.v1.png    ← ancrage
        ├── face-front.v1.png
        ├── face-front.v2.png    ← régénération : pas d'écrasement
        └── detail-hair.v1.png …

Chaque PNG contient un identifiant (personnage/look/vue/version), le modèle utilisé, et les références ; même extrait seul, on peut retracer son origine. La structure de asset.json est décrite dans references/schema.md.

Limites connues

• Les styles testés sont seulement réaliste et anime (tous deux avec Qwen sur les quatre paliers) ; l'effet des styles personnalisés dépend de leur écriture ; générez d'abord l'ancrage pour évaluer.
• Les détails concernent uniquement les éléments portés par le personnage (coiffure, col, poignets, chaussures) ; les accessoires sont gérés par novel-art.
• Limitations connues : les petites cicatrices sont souvent rendues comme des blessures fraîches ; les détails étendus comme les doubles rangées de boutons sont cadrés trop large ; le rendu des cols par Qwen peut transformer un tissu grossier en velours (régénérez cette image avec codex) ; dans les détails Qwen, la peau exposée paraît plus âgée (le prompt inclut déjà une phrase d'âge ; fonctionne sur l'échantillon 16 ans, pas massivement vérifié).
• L'adaptateur openai n'a été testé qu'avec un faux serveur local pour la validation du format de requête, pas avec une vraie clé ; pour la première utilisation, générez d'abord une ancrage.
• Les mêmes prompts ont été testés sur Qwen et GPT ; l'effet d'un modèle personnalisé dépend de ce modèle.

Auto-test

node {baseDir}/scripts/selftest.mjs

230 assertions, sans invoquer de modèle, sans coût : lecture/écriture des identifiants PNG, vérifications automatisées, validation des entrées, formulaire multilingue et rapport, préréglages de style et changement de style, prompts, propagation d'obsolescence, format des requêtes des adaptateurs (Qwen et GPT Image avec serveur local factice), et un flux complet utilisant une commande personnalisée. Lancez ce test après toute modification des scripts.

Exemple intégré

{baseDir}/examples/阿禾-描述.txt est un paragraphe de description (une cueilleuse de thé du Jiangnan des années 1920). 阿禾-intake.json est l'entrée décomposée, avec les champs déduits et par défaut marqués. Les exemples d'images ne sont pas inclus dans le contrôle de version ; pour les voir, générez-les avec votre propre modèle.