live2d-halfbody

Avatar de Meio Corpo: de uma Ilustração ao VTube Studio

Para quem não quer modelar manualmente ou ajustar malhas. A partir de uma ilustração ou descrição, o Agent cria, passo a passo, um avatar Live2D de meio corpo pronto para usar no VTS. O usuário só faz três coisas:

1. Confirma a ilustração (Passo 1);
2. Autoriza o envio para o See-through (Passo 3, Hugging Face, alternativamente ModelScope);
3. Verifica no VTS e responde Aprovado ou Reprovado: <descrição> (Passo 5).

O restante é feito pelo Agent, incluindo uma auto-verificação antes de entregar ao usuário.

Funcionalidades Obtidas em Uma Execução

Funcionalidade	Acionador
Virar cabeça para os lados, para cima/baixo (±30°), corpo inclina junto	Câmera
Acompanhamento corporal: rotação lateral, inclinação para frente/trás, respiração	Câmera, respiração automática do VTS
Piscada normal, piscada individual (troca para olho fechado desenhado ao fechar); pálpebra dupla desaparece ao semi-fechar	Câmera (olhos separados)
Movimento do globo ocular, sobrancelhas para cima/baixo	Câmera
Boca abrindo para falar, sorriso	Câmera
Cabelo segmentado: franja (opcional), laterais (três segmentos, da raiz às pontas, um seguindo o outro; pode ser preso atrás da orelha), cabelo traseiro ou coque; balanço vertical ao acenar com a cabeça. Rabo de cavalo balança independentemente a partir do elástico, também em três segmentos. Cabelo longo abaixo dos ombros segue o corpo	Física
Acessórios (pingente de colar, brincos) balançando	Física
Óculos acompanham o rosto	Câmera
Expressões: Olhos sorrindo N1, boca em "O" N2, olhos apertados N3, preocupado N4, limpar N0	Atalhos de teclado
Gestos: Acenar N5, Mostrar palmas N6, Apontar N7	Atalhos de teclado (gestos por câmera também configurados, veja "Problemas Conhecidos")
Rubor facial N8	Atalhos de teclado

Não é possível: virar a cabeça em ângulos grandes (requer material de perfil), corpo inteiro, braços acompanhando câmera continuamente (requer material de braço segmentado). A saída é um arquivo .moc3 diretamente utilizável no VTS, não um arquivo de projeto do Cubism Editor (.cmo3); o Editor não consegue abri-lo. Para efeitos de nível profissional (física mais refinada, mais expressões, malha comercial), é necessário importar as camadas de layers-st/ para o Cubism Editor e refazer a rigging.

Estrutura de Pastas

素材/角色名/                 Ilustração, prompts, variantes, resultado do See-through, camadas
  A0-base.png                Ilustração finalizada
  prompts/                   Copiado de references/提示词/标准/, preencher [[…]]
  check/                     Imagens de verificação de alinhamento para cada variante
  seethrough.psd             Resultado bruto do See-through
  seethrough/                Dividido em uma PNG por camada
  layers/                    Camadas auto-divididas: usadas apenas como base para a composição do See-through, não entregues separadamente
  layers-st/                 Camadas finais (composição do See-through, incluindo gestos e rubor)
  R0-rest.png                Composição estática das camadas finais, imagem base para gestos e rubor
角色/角色名/
  character.json             Posição, amplitude, mapeamento de camadas
  标注.png                   Posições do character.json desenhadas sobre a ilustração
  素材检查/  prepared/  build/runtime/  自查/  vts/

Passos

Os comandos são executados no diretório de trabalho do usuário (onde ficam 素材/ e 角色/). Adicione PYTHONPATH=<diretório da skill> (ex.: ~/.claude/skills/live2d-halfbody) antes do comando para que o Python encontre o módulo rigkit.

0. Verificar Ambiente

python -m rigkit.doctor

Se houver itens com ✗, resolva-os antes de gerar imagens, caso contrário o processo travará após gerar cerca de vinte imagens. Itens com ! afetam apenas partes do processo: sem token do See-through, a cota anônima pode não ser suficiente; sem ffmpeg, não será possível gerar o vídeo de auto-verificação; sem Codex, outras ferramentas de imagem serão usadas (veja Passo 2).

1. Ilustração — Confirmação do Usuário

Copie toda a pasta references/提示词/标准/ para 素材/角色名/prompts/. Primeiro, preencha os [[…]] no arquivo A0-base.txt (aparência, franja, cabelo lateral, comprimento do cabelo, óculos, brincos).

• Apenas descrição: Preencha conforme a descrição e gere a ilustração.
• Com ilustração: Salve como 素材/角色名/参考.png e anexe como imagem de referência durante a geração, obtendo uma versão que atenda aos requisitos de rigging (pescoço visível; franja termina acima das sobrancelhas; cabelo lateral cobre da orelha ao queixo, ou preso atrás da orelha; iluminação plana, fundo branco, espaço entre braço e corpo). Se a imagem original não atender a esses requisitos, a divisão direta causará problemas durante a animação.

python -m rigkit.variants 素材/角色名 A0-base

Se não houver Codex, use outras ferramentas de imagem para gerar A0 (conforme Passo 2). Mostre ao usuário; prossiga somente após a confirmação.

Se já existirem arquivos de camadas separados conforme a Lista de Camadas, pule para o Passo 4.

2. Geração de Imagens

Substitua os demais [[…]] em prompts/ pela descrição do personagem; remova os prompts correspondentes a partes que o personagem não possui: chapéu ou adereço V1, cabelo lateral na frente da orelha V2, franja V3, pingente V9 (remova também a linha correspondente em S1, veja Geração de Imagens). Em seguida:

python -m rigkit.variants 素材/角色名

Gere de 13 a 17 variantes, cada uma com uma única alteração em relação à imagem base. Para cada variante, gere uma imagem de verificação de alinhamento. Variações de até 4 px e alterações restritas às áreas pretendidas são consideradas aceitáveis; caso contrário, delete e regere, no máximo três tentativas por imagem. Detalhes em Geração de Imagens.

Usando outras ferramentas de imagem para gerar (sem Codex, ou se o Agent puder gerar imagens): O comando variants apenas verifica imagens já existentes, sem regerá-las. Você pode gerar as imagens com outra ferramenta e colocá-las na pasta.

python -m rigkit.variants 素材/角色名 --list

Uma imagem por linha: imagem a ser anexada, arquivo de prompt, indicação se já foi gerada. Gere uma de cada vez. Quando a imagem anexada estiver marcada como "ainda não", aguarde até que seja gerada:

• Use o conteúdo completo do arquivo prompts/<nome>.txt como prompt, sem reescrever. Anexe apenas a imagem listada, e a ferramenta deve modificá-la.
• A ferramenta deve ser capaz de modificar imagens: dada uma imagem e um prompt, retorne a mesma imagem modificada. Ferramentas que só geram novas imagens a partir de texto só podem gerar A0.
• Salve como 素材/角色名/<nome>.png, mantendo a mesma proporção da imagem anexada. Não corte, não adicione bordas, não recorte o fundo, não faça reparos.
• A0 deve ser quadrada; se não for 1254×1254, redimensione para esse tamanho (personagens já criados usam esse tamanho).

Após gerar um lote, execute python -m rigkit.variants 素材/角色名 para gerar as imagens de verificação. O critério de aprovação é o mesmo acima. O mesmo se aplica aos gestos e rubor do Passo 3: --list F1-blush P1-wave P2-explain P3-point. Ainda não foi criado um personagem completo usando ferramentas diferentes do Codex.

3. Separação de Camadas — Autorização do Usuário para Upload

Primeiro, faça a auto-divisão das variantes para servir como base da composição:

python -m rigkit.split 素材/角色名 素材/角色名/layers --pad-top 90

Em seguida, pergunte ao usuário se autoriza o envio da ilustração para o See-through. Após a autorização:

python -m rigkit.seethrough fetch 素材/角色名/A0-base.png 素材/角色名/seethrough
python -m rigkit.seethrough split 素材/角色名 素材/角色名/layers 素材/角色名/layers-st --pad-top 90

O comando fetch tenta primeiro o Hugging Face; se falhar, usa o ModelScope (use --site hf ou --site modelscope para forçar um específico). Cada site usa a resolução mais alta disponível. Você também pode fornecer um PSD gerado pela versão web, ComfyUI ou sua própria placa de vídeo: fetch esse.psd 素材/角色名/seethrough. Se o See-through estiver instalado localmente, use --site local: não envia imagens, não consome cota (veja "Ambiente").

As camadas finais devem obrigatoriamente passar pelo See-through: as camadas auto-divididas apresentam bordas irregulares durante a animação e regiões de cabelo ocultas não são preenchidas corretamente; por isso, não são entregues separadamente. Se não houver cota no dia, tente o outro site, aguarde o dia seguinte ou use um PSD.

O comando split exibirá uma lista das correções aplicadas às camadas do See-through (recortar partes que vazaram para fora da área, reposicionar acessórios deslocados, preencher partes faltantes). As regras estão em Regras, seção "Composição do See-through". Verifique layers-st/拆层总览.png: cada camada deve conter apenas seus próprios elementos; a composição estática deve diferir da ilustração apenas no estilo de arte.

Os olhos fechados e olhos sorrindo são auto-divididos. Se eles trouxerem linhas adjacentes ou bordas irregulares, e a correção falhar duas vezes, envie essas duas variantes para o See-through e execute novamente o comando split acima. Ele usará as camadas de cílios do See-through (Regra 103):

python -m rigkit.seethrough fetch 素材/角色名/D5-eyes-closed.png 素材/角色名/seethrough-D5-eyes-closed
python -m rigkit.seethrough fetch 素材/角色名/D6-eyes-smile.png 素材/角色名/seethrough-D6-eyes-smile

Pergunte ao usuário antes de enviar ao site; cada envio consome uma cota. Ao executar localmente, use --site local --head-from 素材/角色名/seethrough para processar apenas a cabeça.

Em seguida, gere os gestos e o rubor:

python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # Gera R0-rest.png
python -m rigkit.variants 素材/角色名 F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # Adiciona as camadas

Verifique layers-st/手势和脸红.png: cada linha mostra o estado estático, a variante e a aparência no modelo. Prossiga somente se os braços se conectarem ao corpo e as bordas das mãos estiverem limpas.

4. Geração e Auto-verificação

python -m rigkit.estimate 素材/角色名/layers-st 角色/角色名 --name Nome
python -m rigkit.check_art 角色/角色名/character.json
python -m rigkit.prepare 角色/角色名/character.json
python -m rigkit.build 角色/角色名/character.json             # Leva alguns minutos

• estimate não sobrescreve character.json existente; ele cria character.draft.json. Se as camadas forem alteradas e for necessário reestimar, compare e substitua manualmente.
• 标注.png: Se a elipse do rosto, sobrancelhas, nariz, boca, eixos de inclinação, base do pescoço, ombros, cintura ou linha da raiz do cabelo não estiverem nas posições corretas, ajuste os números correspondentes em character.json e execute prepare e build novamente.
• 素材检查/: Se houver pixels magenta em 露底 ou linhas vermelhas em 原画对照, volte ao Passo 3. Se 透出背景 listar áreas não cobertas no estado estático ou áreas que se tornam transparentes durante os gestos, verifique 青底.png (estática e gestos sobre fundo ciano): áreas de roupas brancas ou pele clara podem não ser visíveis no fundo branco. É normal que áreas onde o braço se move fiquem transparentes; caso contrário, volte ao Passo 3.

Auto-verificação:

python -m rigkit.preview flips 角色/角色名/build/runtime
python -m rigkit.preview sheet 角色/角色名/character.json 角色/角色名/自查 新版=角色/角色名/build/runtime
python -m rigkit.preview clip 角色/角色名/character.json 角色/角色名/自查/动作.mp4 新版=角色/角色名/build/runtime

Triângulos invertidos devem ser 0. Verifique as áreas de verificação fixas nas imagens ampliadas e no vídeo (sobrancelhas e franja, contorno do rosto, queixo e pescoço, têmpora e orelha, canto do olho e cílios, canto da boca). Corrija problemas antes de entregar ao usuário. Se houver uma versão anterior, coloque-a lado a lado para comparação.

Em seguida, renderize no fundo do VTS: olhos fechados, semi-fechados, sorrindo, boca bem aberta, semi-aberta, três gestos e balançar a cabeça para os lados. Amplie 3 a 4 vezes a área dos olhos, boca e transições do cabelo: são essas as primeiras coisas que o usuário verá no VTS.

5. Instalação no VTS — Validação do Usuário

python -m rigkit.vts 角色/角色名/character.json --install

Modelos novos podem ser instalados com o VTS aberto; para substituir um modelo já instalado, feche o VTS primeiro. Nesse caso, as configurações ajustadas pelo usuário no VTS são preservadas; apenas os atalhos e mapeamentos faltantes são adicionados. Se o VTS estiver aberto e for necessário substituir o modelo, altere vts.name e vts.folder para instalar em uma nova pasta.

Apresente ao usuário as imagens lado a lado, o vídeo e a lista abaixo. O usuário deve responder Aprovado ou Reprovado: <descrição>:

O que verificar	Como
Virar e inclinar a cabeça	Virar para os lados, cima/baixo, inclinar: rosto, cabelo, chapéu, orelhas acompanham; sem rachaduras, fragmentos ou partes paradas
Olhos	Piscada normal, piscada individual, semi-fechar; ao virar a cabeça, cílios não atravessam o cabelo
Boca	Falar, sorrir; ao virar a cabeça com a boca fechada, ela não entorta
Cabelo	Balançar a cabeça: franja, cabelo lateral, cabelo traseiro balançam em segmentos, cada segmento atrasado em relação ao anterior; ao acenar com a cabeça, balanço vertical. Cabelo longo abaixo dos ombros segue o corpo
Acessórios	Pingentes balançam quando o corpo se move; a roupa por baixo permanece intacta
Corpo	Acompanhamento corporal: rotação lateral, inclinação para frente/trás, respiração
Expressões	Alternar N1 a N4, limpar com N0
Gestos	N5 a N7: estilo de arte do corpo não muda; bordas das mãos limpas; ao virar a cabeça durante o gesto, os braços acompanham o corpo
Rubor facial	N8: bordas suaves; ao balançar a cabeça, o rubor não aparece abaixo do cabelo

Ajuste de Amplitude

As amplitudes de movimento estão em character.json:

O que ajustar	Campo
Ângulo de inclinação da cabeça	head.tilt_deg (graus na amplitude máxima)
Distância que o rosto percorre ao virar	head.yaw_px, head.pitch_px
Inclinação do corpo	body.tilt_deg (graus por unidade de parâmetro; amplitude máxima ×10)
Respiração	body.breath.head, body.breath.shoulder (pixels)
Acompanhamento corporal	body.turn, body.shift, body.lean_y
Amplitude do balanço do cabelo	hair.locks.<camada>.swing; segmentos intermediários e pontas hair.locks.<camada>.bend; balanço vertical hair.locks.<camada>.pitch
Sensação física	hair.locks.<camada>.chain (três segmentos) ou physics: delay (menor = mais arrastado), length (maior = mais lento)
Amplitude do balanço de acessórios	dangles.<camada>.deg (graus na amplitude máxima)
Semi-fechar dos olhos	eyes.crease_fade (intervalo de desaparecimento da pálpebra dupla), eyes.lower_from (posição onde a pálpebra inferior começa a fechar)
Posição onde a boca começa a abrir	mouth.open_from: a boca permanece fechada quando a leitura da câmera for inferior a este valor

As amplitudes são determinadas com base no enquadramento de meio corpo do VTS e no movimento humano real: uma inclinação normal da cabeça é de aproximadamente 15°; se o modelo inclinar apenas 3°, é praticamente imperceptível. Após ajustar, execute build novamente. Os demais campos estão documentados em Configuração.

Regras

Todas as regras e suas justificativas estão em Regras. As regras mais frequentemente violadas são:

• Antes de agir, consulte as práticas padrão do Live2D e explique claramente a abordagem.
• Use o See-through para cortar imagens; o modelo de imagem deve preencher apenas detalhes que o See-through não consegue (expressões, partes ocultas, gestos).
• Trabalhe apenas com partes que você domina: use as camadas do See-through de forma integral; o código deve apenas selecionar, reposicionar ou separar blocos não conectados, sem recortar pixel a pixel por cor dentro de uma camada (o resultado seria irregular). Para modificar uma região, compare lado a lado em ampliação com o original do See-through; só modifique se a melhoria for claramente superior.
• Novas regras devem primeiro ser quantificadas em todos os personagens existentes para determinar o escopo. Após a definição, execute o código antigo e o novo em cada camada para comparação, garantindo que não haja regressão para personagens já aprovados. Cada regra deve especificar seu escopo: geral ou específico a determinadas situações (condições de ativação, exceções).
• Sempre apresente ao usuário imagens lado a lado e vídeos para julgamento humano. Use contagem de triângulos invertidos e diferenças de pixels apenas para depuração de artefatos.
• Se um mesmo sintoma persistir após três tentativas de correção, pare de modificar o código e resolva com alterações nos materiais.
• O modelo de imagem deve receber apenas instruções para "modificar um aspecto em toda a imagem", nunca "deixar apenas uma parte"; a parte desejada deve ser extraída por código usando métodos de diferença.
• Antes de enviar imagens a serviços externos, pergunte ao usuário. Contas e tokens devem ser registrados e configurados pelo usuário; o token não deve ser reescrito na conversa.
• Ao instalar, não sobrescreva o vtube.json do usuário. Ao substituir um modelo já instalado, o VTS deve ser fechado.

Ambiente

• Python 3.10+: pip install -r <diretório da skill>/requirements.txt (se o Python do sistema não permitir instalação, crie um ambiente virtual). Para gerar o vídeo, é necessário ffmpeg.
• Codex CLI (geração de imagens): Incluso no ChatGPT Desktop ou instalado separadamente como codex (no PATH); faça login na conta ChatGPT. Caso contrário, defina a variável de ambiente CODEX apontando para ele. Se não houver Codex, use outras ferramentas de imagem que possam modificar imagens, conforme Passo 2.
• See-through (separação de camadas): Os dois sites executam o mesmo modelo. Prepare pelo menos um:
  • Hugging Face (preferencial, alguns minutos por execução, resolução máxima 1280): O tempo de GPU gratuito diário (sem login) pode não ser suficiente para uma execução completa. O usuário deve criar uma conta gratuita, gerar um Read token e defini-lo na variável de ambiente HF_TOKEN ou em ~/.cache/huggingface/token (local onde hf auth login salva). Cerca de 1 a 2 execuções por dia.
  • ModelScope (alternativa, gratuita, resolução máxima 1536): O usuário deve criar uma conta, gerar um token de acesso e defini-lo na variável de ambiente MODELSCOPE_API_TOKEN ou em ~/.cache/modelscope/token. Pode haver fila; uma execução pode levar até meia hora. A resolução 1536 produz contornos de cabelo e olhos mais próximos da ilustração original.
  • Local (opcional, sem envio de imagens, sem limite de uso): Verificado em Apple Silicon com 24 GB de RAM; uma execução completa em 1280 leva cerca de 21 minutos, processando apenas a cabeça leva cerca de 9 minutos. Na primeira execução, baixa ~13 GB de modelos. Após a instalação, defina a variável de ambiente SEETHROUGH_DIR apontando para ele. Instruções de instalação em Geração de Imagens (seção "Executar See-through Localmente").
• VTube Studio (versão Steam).
• Live2D Cubism Core (necessário para pré-visualização, auto-verificação e ícones): Se o Cubism Editor estiver instalado, é encontrado automaticamente. Caso contrário, baixe o Cubism SDK for Native e defina a variável de ambiente CUBISM_CORE apontando para a biblioteca dinâmica Core. O Core é usado sob a licença da Live2D e não é distribuído com esta skill.

Verificado no macOS; não verificado no Windows.

Problemas Conhecidos

• Gestos por câmera (mão aberta = acenar, ambas as mãos abertas = mostrar palmas, indicador levantado = apontar): O primeiro personagem os aciona, mas o segundo personagem, com a mesma configuração campo a campo, não os aciona. A causa não foi identificada. Os atalhos N5 a N7 não são afetados.
• Estilo de arte estático: O estado estático tem a aparência gerada pelo See-through, que é ligeiramente mais suave que a ilustração original, com menos detalhes nos cílios e contornos das pontas do cabelo.
• Óculos próximos à pálpebra dupla: Quando a armação do óculos está muito próxima da pálpebra dupla, o See-through pode perder a linha da pálpebra dupla e desenhar uma faixa cinza clara na borda dos cílios. Isso é mantido como está.
• Canto do olho próximo ao contorno entre bochecha e orelha (gorro): As camadas auto-divididas de olhos fechados e olhos sorrindo podem incluir um pequeno segmento desse contorno, que aparece no lado do rosto ao virar a cabeça. Enviar essas duas variantes para o See-through resolve (Passo 3).