chulegexiaojiu/character-refs

¿Qué hace character-refs?

Introduzca una descripción del personaje y obtenga un conjunto de imágenes de referencia del mismo (da igual de dónde venga el personaje: adaptación de novela, historia propia, alguien que se le acaba de ocurrir). Una imagen ancla de cuerpo completo de frente; el resto de imágenes solo toman esta ancla como referencia. Sirve como imagen de referencia para modelos de vídeo (H3 / Wan / Seedance) y para que las vean personas.

{baseDir} = directorio donde se encuentra este archivo. Script {baseDir}/scripts/character-refs.mjs, cero dependencias, ejecutable directamente con node.

Este es el único skill del repositorio que realmente genera imágenes. Los demás skills solo entregan prompts, porque el modelo y el estilo artístico se deciden en el momento de generar la imagen; este skill es «ese momento»: el modelo lo elige el usuario en el Paso 0, el estilo artístico se selecciona al crear el personaje (por defecto anime, con un preset realista y posibilidad de usar estilos personalizados).

Reglas principales (léalas antes de actuar)

• Un solo origen para todo el conjunto: la imagen ancla de cuerpo completo de frente. Solo ella se genera a partir de texto; el resto son «ancla + una instrucción de edición». Los detalles de pelo, cara y cuello llevan además una imagen de primer plano facial confirmada. Las imágenes no se referencian entre sí: si una sale mal, se puede regenerar individualmente sin efectos en cadena.

• Por niveles, por defecto hasta el nivel 2:

  Nivel	Contenido	Cuándo generarlo
  1	Cuerpo completo de frente (ancla)	Siempre, la primera
  2 (por defecto)	Primer plano facial, perfil 90° (mirando al lado derecho de la escena), espalda	Por defecto se generan todos
  3	Detalles (hasta 8): los que el usuario indique, las partes más distintivas del personaje; si no indica ninguno, usar los que vienen por defecto: pelo/adorno capilar, cuello, puños, zapatos	Cuando hay detalles de accesorios o partes de la ropa
  4 (no por defecto)	Primer plano 45° (mirando al lado izquierdo de la escena)	Solo si el usuario lo pide explícitamente

  Pruebas con H3: si solo se da la ancla de frente, la ropa y la espalda son correctas, pero la cara se distorsiona; con un primer plano facial adicional, la cara es la más parecida. Por eso se generan por defecto las del nivel 2. Si solo se quiere la ancla (por ejemplo, para ver primero el aspecto): gen <asset.json> --tier 1.

• El modelo no está fijado: la imagen principal y las derivadas pueden usar modelos distintos; al regenerar una imagen individual se puede cambiar de modelo. La coherencia viene de «la misma ancla», no de «el mismo modelo» (probado: ancla Qwen + derivada GPT, ancla GPT + derivada Qwen, mezcla en el mismo conjunto funcionan bien). Cada imagen registra su propio modelo; si se mezclan modelos dentro del mismo conjunto, solo se indica en el informe.

• Solo tres cosas están congeladas: el archivo ancla (sha256), la instantánea del estilo artístico, y la huella de la descripción textual. Si alguna cambia, las imágenes que dependen de ella se marcan como «obsoletas» — solo se marcan, no se eliminan; todas las versiones antiguas se conservan.

---

Paso 0 — Configuración inicial (una vez por máquina)

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

Si al final de la salida pone «Falta: …» hay que preguntar al usuario estas tres cosas, todas a la vez:

1. Qué modelo usar para la imagen principal (ancla):
   • qwen — Qwen Image 2.1, usando su propio servidor ComfyUI. Rápido (25–45 s por imagen), dimensiones precisas, no consume cuota de suscripción. Necesita COMFY_URL (opcional COMFY_USER / COMFY_PASS), en variables de entorno o un archivo .env
   • codex — generación de imágenes integrada en Codex (GPT). Sin API key, pero consume cuota de suscripción de ChatGPT (Plus se topa en unas 25 imágenes, se restablece en unas horas), 80–160 s por imagen
   • openai — OpenAI Images API, por defecto gpt-image-2. Facturación por uso, necesita OPENAI_API_KEY; también se puede apuntar a una API compatible (--openai-base-url)
   • custom:<nombre> — comando propio del usuario para generar imágenes, ver references/models.md
2. Qué modelo usar para las imágenes derivadas: por defecto el mismo que el principal. Se pueden separar (p.ej., ancla GPT, derivada Qwen)
3. Si se debe esperar confirmación tras la ancla: se recomienda yes — la ancla es la raíz de todo el conjunto; si no es correcta, el resto se genera en vano. Si se elige no, se pasa automáticamente; en el informe se marca «sin confirmación humana»; las anclas que no pasan el control de calidad no se liberan automáticamente; hay que revisarlas y usar confirm o regenerar.

node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <ruta al .env>
# Para separar modelos: --anchor-model codex --derive-model qwen

La configuración se guarda en {baseDir}/config.local.json (no entra en control de versiones, no se sobrescribe al reinstalar). A partir de entonces se usa por defecto; si el usuario dice «cambia a xx», se vuelve a ejecutar config. No imprima contraseñas ni claves del .env; config --show ya las ofusca.

Paso 1 — Entrada única

El usuario da un párrafo describiendo al personaje, no hace falta preguntar uno por uno. Usted (el modelo) lo desglosa:

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

Siguiendo la plantilla, desglosa la descripción en los campos y la escribe en <directorio de trabajo>/<nombre_del_personaje>-intake.json. Reglas (ver references/intake.md):

• lang: idioma en el que habla el usuario (chino zh, inglés en, japonés ja integrados). La tabla de confirmación y el informe usan este idioma; para otros idiomas, ejecute primero ui-template <lang>, traduzca uno por uno los textos en inglés que imprime, y ponga el resultado en el campo ui del intake
• Lo que el usuario ha dicho se marca stated, lo que usted deduce se marca inferred, lo que se completa por convención se marca default — márquelo fielmente; la tabla de confirmación se basa en esto para indicar al usuario qué debe revisar
• Si no puede deducir la edad, el sexo o la época, pregunte al usuario. Solo estos tres no puede inventarlos; del resto, complete todo sin preguntar
• en entra en el prompt: siempre en inglés, sin nombre del personaje, sin palabras de estilo; text es para que lo vea el humano, escrito en el idioma de lang (las entradas antiguas escritas en zh también se reconocen)
• La ropa se divide en top / bottom: para los primeros planos solo se usa la parte de arriba; si se incluye bottom, el modelo aleja el plano
• Los detalles se eligen según el personaje: primero los que el usuario indique; si no indica ninguno, elija las partes más distintivas del personaje; como respaldo hay cuatro ranuras por defecto; los rasgos faciales no van en detalles (ya se ven en el primer plano). Ver references/intake.md

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

Si hay errores, corríjalos según el mensaje hasta que pase. Si pasa, imprime la tabla de confirmación; muéstresela al usuario tal cual, con marcas en los campos inferidos y por defecto. No continúe hasta que el usuario confirme (o modifique y luego confirme).

Paso 2 — Crear el activo

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <directorio de salida> [--look estilo_artístico]

Crea <directorio de salida>/<nombre_del_personaje>/asset.json. En este punto se guarda una instantánea completa del estilo artístico; cambios posteriores en los presets no afectan a los personajes existentes.

Estilo artístico: si el usuario lo ha indicado, use ese; si no, anime. Los personajes de una misma serie usan todos el mismo estilo artístico.

Preset	Nombre que reconoce --look
Anime (por defecto)	动漫 卡通 anime cartoon 二次元 アニメ
Foto realista	写实 realistic photo 真人

looks lista todos los presets. Si el usuario quiere otro estilo (estilo chino, cómic americano…): look-template <el preset más parecido> > my-look.json, modifique style (medio, líneas), clean (fondo y luz, debe mantener fondo blanco), neg (prompt negativo — si cambia a un estilo dibujado, quite anime e illustration del prompt negativo), para un estilo dibujado ponga medium como drawn, luego --look my-look.json. Los estilos personalizados no están probados; primero genere la ancla para ver el resultado.

Para cambiar de estilo en un personaje ya creado:

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

Al cambiar, todas las imágenes existentes (incluida la ancla) se marcan como obsoletas; las imágenes antiguas se conservan y se regeneran desde la ancla.

Paso 3 — Generar por defecto el nivel 2

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

Sin especificar vistas ni nivel, completa las imágenes de los niveles 1 y 2 que falten o estén obsoletas.

Si está configurada la confirmación: este comando solo genera la ancla y se detiene. Muestre la imagen al usuario (informe o abra directamente el PNG). Si el usuario dice que vale:

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # mismo comando, continúa generando primer plano, perfil, espalda

Si no le gusta, ejecute de nuevo gen <asset.json> front-full (genera v2, puede usar --seed para cambiar la semilla, --model para cambiar el modelo), o vuelva al Paso 1 para modificar la descripción. Si la ancla no está confirmada, se rechazarán las imágenes derivadas. Si está configurado para no confirmar, genera las cuatro imágenes de una vez.

Paso 4 — Subir de nivel según necesidad

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 tiene detalles de adorno capilar y cuello"

--reason indica por qué se sube de nivel y se registra en el activo. También se pueden generar solo unas pocas: gen <asset.json> detail-hair detail-neck.

Paso 5 — Comprobación y regeneración

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

Cada imagen pasa por un control de calidad (dimensiones 300–5760, relación de aspecto 0.4–2.5, proporciones correctas, ≤20 MB, fondo suficientemente blanco) y se comprueba si está obsoleta. Si hay problemas, sale con exit 1. Las que no pasan el control o están obsoletas, se regeneran individualmente:

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

En el control, «fondo suficientemente blanco» para imágenes de cuerpo completo comprueba los cuatro bordes; para primeros planos solo el borde superior y los lados en la mitad superior (el cuerpo ya llega al borde inferior); en detalles se omite y se indica explícitamente. El control no puede verificar el aspecto, el ángulo ni el encuadre — después de generar, hay que mirar las imágenes; estas cosas dependen del ojo humano.

Paso 6 — Informe

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

Se pueden incluir varios personajes a la vez. El idioma se toma por defecto del lang del activo; para cambiar temporalmente añada --lang en; para idiomas no integrados sin campo ui, pase las traducciones con --ui <archivo>; si faltan textos, dará error y no generará un informe medio en chino medio en inglés. Los textos de la interfaz cambian de idioma, pero la descripción del personaje se mantiene en el original. El nivel 1 solo tiene una tarjeta; a partir del nivel 2 es un diseño de hoja de datos (izquierda: primer plano facial; arriba a la derecha: frente/perfil/espalda; abajo a la derecha: tira de detalles), por defecto no se muestran los detalles; en la página se puede cambiar con un solo clic. Las imágenes obsoletas se marcan con un borde rojo; en la parte superior de la página hay una leyenda; al pasar el ratón sobre una imagen con borde rojo se ve el motivo; si se mezclan modelos, se muestra un aviso.

Paso 7 — Informe de resultados

En una frase: qué imágenes se han generado, con qué modelo, y la ruta del informe. Si alguna no ha pasado el control o está obsoleta, menciónela. No diga «tiene buena pinta» sin haber visto las imágenes.

---

Estructura en disco

<directorio de salida>/
├── character-refs.html          ← generado por render
└── <nombre_del_personaje>/
    ├── asset.json               ← descripción del personaje + todas las versiones de cada imagen
    └── default/                 ← apariencia (v1 solo tiene una serie llamada default)
        ├── front-full.v1.png    ← ancla
        ├── face-front.v1.png
        ├── face-front.v2.png    ← regenerar no sobrescribe
        └── detail-hair.v1.png …

Cada PNG contiene su identificador (personaje/apariencia/vista/versión), el modelo y a qué imágenes referencia; incluso si se copia por separado se puede rastrear su origen. La estructura de asset.json se describe en references/schema.md.

Limitaciones

• Los únicos estilos probados son realista y anime (ambos con Qwen en cuatro niveles); el resultado de estilos personalizados depende de cómo se escriba; primero genere la ancla para ver
• Las imágenes de detalles solo recogen elementos que van sobre el personaje (adornos capilares, cuello, puños, zapatos); los objetos aparte van en novel-art
• Fallos conocidos: las cicatrices pequeñas pueden parecer heridas recientes; los detalles extensos como doble botonadura salen con el encuadre demasiado alejado; los detalles de cuello de Qwen pueden hacer que la tela gruesa parezca terciopelo (regenerar esa imagen con codex); la piel que se ve en los detalles de Qwen puede parecer más vieja (el prompt ya incluye una frase de edad, efectiva en el ejemplo de 16 años, no probada en masa)
• El adaptador de openai solo se ha probado con un servidor local falso para verificar el formato de las peticiones, no se ha ejecutado con una clave real; la primera vez genere una ancla para probar
• El mismo prompt se ha probado tanto en Qwen como en GPT; el resultado con modelos personalizados depende del modelo

Autocomprobación

node {baseDir}/scripts/selftest.mjs

230 aserciones, sin invocar modelos ni gastar crédito: lectura/escritura de identificadores en PNG, controles de calidad, validación de entrada, tabla de confirmación e informe multilingüe, presets de estilo y cambio de estilo, prompts, propagación de obsolescencia, formato de peticiones de los adaptadores de generación (Qwen y GPT Image con servidor local falso), y flujo completo con comandos personalizados. Ejecútelo después de modificar los scripts.

Ejemplos incluidos

{baseDir}/examples/阿禾-描述.txt es una descripción en una frase al estilo usuario (una recolectora de té en Jiangnan en la década de 1920), 阿禾-intake.json es la entrada ya desglosada, con los campos inferidos y por defecto marcados. Las imágenes de ejemplo no están bajo control de versiones; para verlas, use sus propios modelos.