character-refs

O que character-refs faz?

Insira uma descrição de personagem e obtenha um conjunto de imagens de referência — não importa de onde o personagem vem: adaptação de romance, história própria, alguém que veio à mente. Uma âncora de corpo inteiro frontal, e cada imagem subsequente referencia apenas esta âncora. Use como referência para modelos de vídeo (H3 / Wan / Seedance) e para visualização humana.

{baseDir} = diretório deste arquivo. Script {baseDir}/scripts/character-refs.mjs, zero dependências, execute com node.

Este é o único skill neste repositório que realmente gera imagens. Os outros skills apenas fornecem prompts, porque o modelo e o estilo só podem ser decididos no momento da geração; este skill é esse "momento" — o modelo é escolhido pelo usuário no Passo 0, e o estilo é selecionado ao construir o personagem (padrão anime, com predefinição realista, e suporte para estilos personalizados).

Regras Principais (Leia antes de agir)

• Um grupo de imagens tem apenas uma raiz: a âncora de corpo inteiro frontal. Somente ela é gerada por texto; todas as outras são "âncora + uma instrução de modificação". Detalhes de cabelo, rosto e gola têm um close-up frontal confirmado adicional. As imagens não se referenciam entre si — portanto, se uma imagem sair ruim, regenere apenas essa imagem, sem efeito cascata.

• Camadas, padrão até a segunda camada:

  Camada	Conteúdo	Quando gerar
  1	Corpo inteiro frontal (âncora)	Sempre, a primeira
  2 (padrão)	Close-up frontal, perfil 90° (virado para a direita da tela), costas	Gerado por padrão
  3	Detalhes (máx. 8): itens solicitados pelo usuário, as partes mais reconhecíveis do personagem; se não especificado, usar cabelo/ornamento de cabelo, gola, punho, sapato	Quando houver acessórios ou close-ups de partes da roupa
  4 (não padrão)	Close-up 45° (virado para a esquerda da tela)	Quando o usuário solicitar explicitamente

  Testes com H3: fornecer apenas corpo inteiro frontal mantém roupas e costas corretas, mas o rosto pode distorcer; adicionar um close-up frontal deixa o rosto mais próximo. Portanto, a segunda camada é gerada por padrão. Apenas âncora (por exemplo, para ver a aparência primeiro): gen <asset.json> --tier 1.

• Modelo não fixo: a imagem principal e as derivadas podem usar modelos diferentes, e a regeneração individual também pode trocar de modelo. A consistência vem da "mesma âncora", não do "mesmo modelo" (testes mostram que âncora Qwen + derivada GPT, âncora GPT + derivada Qwen, ou mixagem no mesmo grupo funcionam). Cada imagem registra seu próprio modelo; a mixagem em um grupo é apenas sinalizada no relatório.

• Apenas três coisas são congeladas: o arquivo âncora (sha256), o snapshot do estilo, e a impressão digital da descrição textual. Se qualquer uma mudar, as imagens que dependem dela são marcadas como "desatualizadas" — apenas marcadas, não excluídas, todas as versões antigas são mantidas.

---

Passo 0 — Configuração Inicial (uma vez por máquina)

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

Se a saída terminar com "Falta: ...", pergunte ao usuário estas três coisas, todas de uma vez:

1. Qual modelo usar para a imagem principal (âncora):
   • qwen — Qwen Image 2.1, através do próprio servidor ComfyUI. Rápido (25–45s por imagem), dimensões precisas, não consome créditos de assinatura. Requer COMFY_URL (opcional COMFY_USER / COMFY_PASS), definidos como variáveis de ambiente ou em um arquivo .env
   • codex — Geração de imagem integrada ao Codex (GPT). Sem necessidade de chave de API, mas consome créditos do ChatGPT (Plus atinge o limite em cerca de 25 imagens, recupera após algumas horas), 80–160s por imagem
   • openai — OpenAI Images API, padrão gpt-image-2. Cobrança por uso, requer OPENAI_API_KEY; também pode apontar para uma interface compatível (--openai-base-url)
   • custom:<nome> — Comando de geração de imagem do usuário, veja references/models.md
2. Qual modelo usar para as imagens derivadas: Padrão igual ao da imagem principal. Pode ser diferente (por exemplo, âncora GPT, derivadas Qwen)
3. Parar após gerar a âncora para aguardar confirmação do usuário?: Recomendado yes — a âncora é a raiz do grupo; se estiver errada, todo o resto é em vão. Escolher no permite continuar automaticamente, mas o relatório marca "não confirmada pelo humano"; âncoras que não passam na verificação não são automaticamente liberadas, exigindo revisão e confirm ou regeneração

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

A configuração é salva em {baseDir}/config.local.json (não versionado, a reinstalação não sobrescreve). Será usada por padrão. Se o usuário disser "mude para xx", execute config novamente. Não imprima senhas ou chaves do .env; config --show já as mascara.

Passo 1 — Entrada Única

O usuário fornece um parágrafo descrevendo o personagem. Não pergunte item por item. Você (o modelo) extrai:

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

Siga o template para dividir a descrição nos campos e salve em <diretório_de_trabalho>/<nome_do_personagem>-intake.json. Regras (veja references/intake.md):

• lang define o idioma da descrição do usuário (chinês zh, inglês en, japonês ja pré-carregados). A tabela de confirmação e o relatório usam esse idioma; Para outros idiomas, execute ui-template <lang>, traduza o texto em inglês impresso item por item e coloque o bloco inteiro no campo ui do intake
• O que o usuário disse é marcado como stated, o que você inferiu é inferred, o que foi completado por convenção é default — marque honestamente; a tabela de confirmação usa isso para destacar quais itens o usuário deve revisar
• Idade, sexo e época se não puderem ser inferidos, pergunte ao usuário: apenas essas três coisas não podem ser inventadas; todo o resto pode ser completado sem perguntar
• en vai para o prompt: sempre em inglês, sem nome do personagem, sem palavras de estilo; text para humanos, no idioma de lang (entradas antigas em zh ainda são reconhecidas)
• Roupas divididas em top / bottom — close-ups frontais usam apenas a parte de cima; incluir a parte de baixo faz o modelo aproximar o enquadramento
• Detalhes escolhidos para o personagem: os solicitados pelo usuário primeiro; se não solicitados, escolha os mais distintivos do personagem; quatro slots padrão como fallback; características faciais não vão para imagens de detalhes (o close-up frontal já as mostra claramente). Veja references/intake.md

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

Corrija quaisquer problemas apontados até passar. Após passar, o comando imprime a tabela de confirmação, mostrada ao usuário; itens inferidos e padrão têm marcadores. Somente após a confirmação do usuário (ou modificação e confirmação) continue.

Passo 2 — Criar o Ativo

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <diretório_de_saída> [--look estilo]

Cria <diretório_de_saída>/<nome_do_personagem>/asset.json. O estilo é copiado como snapshot neste ponto; alterações futuras na predefinição não afetam personagens existentes.

Estilo: use o que o usuário especificou; se não especificado, padrão anime. Personagens da mesma obra devem usar o mesmo estilo.

Predefinição	Nome reconhecido por --look
Anime (padrão)	动漫 卡通 anime cartoon 二次元 アニメ
Foto realista	写实 realistic photo 真人

looks lista todas as predefinições. Para outros estilos (arte chinesa, quadrinhos americanos...): look-template <predefinição_mais_próxima> > my-look.json, edite style (meio, linhas), clean (fundo e luz, o fundo branco deve ser mantido), neg (termos negativos — para estilo desenhado, remova anime illustration dos termos negativos), para estilo desenhado, defina medium como drawn, então --look my-look.json. Estilos personalizados não são testados; gere a âncora primeiro para ver o resultado.

Para trocar o estilo de um personagem já criado:

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

Após a troca, todas as imagens existentes (incluindo a âncora) são marcadas como desatualizadas; as imagens antigas são mantidas, e a regeneração começa pela âncora.

Passo 3 — Gerar a Segunda Camada Padrão

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

Sem especificar visões ou camadas, completa as imagens da primeira e segunda camadas que ainda não foram geradas ou estão desatualizadas.

Se a confirmação estiver configurada: este comando para após gerar a âncora. Mostre a imagem ao usuário (relatório ou abra o PNG diretamente). Se o usuário aprovar, então:

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # Mesmo comando, continua gerando close-up frontal, perfil, costas

Se não aprovar, execute gen <asset.json> front-full novamente (gera v2, pode usar --seed para trocar semente, --model para trocar modelo), ou volte ao Passo 1 para modificar a descrição. Âncora não confirmada impede a geração de derivadas. Se a confirmação automática estiver desativada, o comando gera todas as quatro imagens de uma vez.

Passo 4 — Subir de Camada Sob Demanda

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 tem close-up de ornamento de cabelo e gola"

--reason explica por que a camada foi elevada, registrado no ativo. Também é possível gerar apenas algumas imagens: gen <asset.json> detail-hair detail-neck.

Passo 5 — Verificação e Regeneração

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

Cada imagem passa por verificações de código (dimensões 300–5760, proporção 0.4–2.5, proporção correta, ≤20MB, fundo suficientemente branco), e verificação de desatualização. Se houver problemas, exit 1. Para imagens que falharam na verificação ou estão desatualizadas, regenere apenas aquela:

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

Na verificação, "fundo suficientemente branco" verifica as quatro bordas para corpo inteiro, apenas a borda superior e os dois terços superiores das laterais para close-ups (o corpo toca a borda inferior), e é ignorado para detalhes com aviso explícito. A verificação não confere aparência, ângulo ou enquadramento — é necessário olhar as imagens após a geração; esses itens dependem do olho humano.

Passo 6 — Relatório

node {baseDir}/scripts/character-refs.mjs render <asset.json>... --out <diretório_de_saída>/character-refs.html

Vários personagens podem ser combinados. O idioma padrão é o lang do ativo; para trocar temporariamente, adicione --lang en; para idiomas não pré-carregados sem campo ui, use --ui <arquivo> para passar traduções personalizadas; se faltar o texto da interface, o comando falhará com erro, sem gerar relatório bilíngue. O texto da interface muda de idioma, mas a descrição do personagem permanece no original. A primeira camada tem apenas um cartão; a partir da segunda camada, o layout é de folha de design (close-up frontal à esquerda, frente/perfil/costas à direita, barra de detalhes embaixo a direita), detalhes não são mostrados por padrão, mas podem ser alternados com um clique na página. Imagens desatualizadas têm moldura vermelha; um guia de ícones está no topo da página; ao passar o mouse sobre uma moldura vermelha, o motivo aparece; modelos misturados são sinalizados.

Passo 7 — Relatar

Uma frase: quais imagens foram geradas, qual modelo usado, caminho do relatório. Mencione se alguma falhou na verificação ou está desatualizada. Não diga "efeito muito bom" sem ter visto as imagens.

---

Estrutura do Projeto

<diretório_de_saída>/
├── character-refs.html          ← gerado por render
└── <nome_do_personagem>/
    ├── asset.json               ← Descrição do personagem + todas as versões de cada imagem
    └── default/                 ← Aparência (v1 tem apenas a aparência default)
        ├── front-full.v1.png    ← Âncora
        ├── face-front.v1.png
        ├── face-front.v2.png    ← Regenerações não sobrescrevem
        └── detail-hair.v1.png …

Cada PNG contém identificadores (personagem/aparência/visão/versão), modelo e referências; mesmo se copiado separadamente, sua origem pode ser rastreada. A estrutura de asset.json está em references/schema.md.

Limitações

• Apenas dois estilos foram testados: realista e anime (ambos com Qwen nas quatro camadas); o resultado de estilos personalizados depende da implementação; gere a âncora primeiro
• Detalhes incluem apenas itens que fazem parte do personagem (ornamentos de cabelo, gola, punhos, sapatos); adereços pertencem a novel-art
• Limitações conhecidas: cicatrizes pequenas podem parecer feridas recentes; detalhes extensos como botões duplos podem ter enquadramento muito distante; Qwen pode transformar tecido grosso em veludo em detalhes de gola (regenerar essa imagem com codex); a pele exposta em detalhes do Qwen pode parecer mais velha (o prompt inclui instrução de idade; eficaz no exemplo de 16 anos, mas não amplamente verificado)
• O adaptador openai foi testado apenas com um servidor local falso para verificar o formato da requisição; nunca foi executado com uma chave real; gere uma âncora primeiro ao usar
• Os mesmos prompts foram testados tanto no Qwen quanto no GPT; o resultado com modelos personalizados depende do modelo

Autoteste

node {baseDir}/scripts/selftest.mjs

230 asserções, sem invocar modelos, sem gastar créditos: leitura/escrita de identificadores em PNG, verificação, validação de entrada, tabelas de confirmação e relatórios multilíngues, predefinições de estilo e troca de estilo, prompts, propagação de desatualização, formato de requisição dos adaptadores de geração (Qwen e GPT Image com servidor local falso), e um fluxo completo usando comandos personalizados. Execute este teste após modificar o script.

Exemplos Inclusos

{baseDir}/examples/描述-阿禾.txt é uma descrição de personagem de um parágrafo (uma colhedora de chá dos anos 1920 no sul do Rio Yangtzé), 阿禾-intake.json é a entrada extraída, com campos inferidos e padrão marcados. As imagens de exemplo não estão no controle de versão; para vê-las, execute com seu próprio modelo.