minhdv-zz/tb-hoidz

Mapeamento Gradiente para Blender

Revisão de workflow 15. Responda no idioma do usuário. Use o Blender MCP conectado e o script mantido scripts/gm_core.py (versão 8+); preserve seu algoritmo de mapeamento.

Leia apenas o que esta fase precisa

Para mapeamento base, leia references/base-api.md e references/reference-quality.md uma vez por contexto disponível. Não carregue código auxiliar ou o workflow completo apenas para descobrir APIs. Inspecione uma assinatura/docstring direcionada para argumentos não documentados; leia apenas a função fonte relevante, se necessário.

references/workflow.md é a referência estendida para predefinições, chaves de plano opcionais, explicações de QA e exemplos históricos: leia seções relevantes sob demanda. SKILL_DIR é a pasta deste ponto de entrada. Leia references/detail.md apenas após aprovação da base. Reutilize documentos já no contexto, a menos que tenham sido alterados ou perdidos após compactação.

Escopo e salvaguardas

• /tb-hoidz autoriza preparação, planejamento, zonas, mapeamento base, comparação e QA. Combine um plano conciso e aviso de atribuição de paleta na breve atualização de abertura, depois continue sem confirmação intermediária; siga as regras de comunicação abaixo. Pare após a base concluída para aprovação do usuário antes do mapeamento de detalhes. Adições geométricas exigem a escolha do usuário sobre detalhe, método de corte e custo de triângulos; aprovações existentes persistem.
• Reutilize o conceito e alvo fornecidos; caso contrário, malhas selecionadas se não ambíguas. Pergunte apenas por entradas faltantes. Nunca invente um conceito, substitua o ativo ou importe duplicatas por padrão.
• Registre bpy.data.filepath no início da execução como alvo de salvamento de trabalho. Edite os objetos ativos. Um arquivo alterado inicia um novo contexto; um arquivo não salvo exige o primeiro local de salvamento do usuário.
• Cada face pertence a uma zona; uma strip por zona, U colapsada em seu centro, margens de pelo menos 2 px U/V. Combine normais de luz superior e altura, não apenas altura por padrão. Use normais hard/smooth apropriadas e resposta do material. Preserve geometria durante o mapeamento base.
• Armazene plano, associações/evidências privadas, triângulos de base, assinaturas, QA e exceções localmente na cena. JSON persistente, exportações de imagem e relatórios de benchmark são opcionais, não entregas padrão. save_plan assume como padrão a pasta da skill: use armazenamento gravável explícito.

Comunicação e pré-visualização

Padrão para narração mínima no chat: faça o trabalho autorizado e verificações internas, depois reporte o resultado concluído. Combine o plano, a atribuição de paleta pretendida e qualquer fallback conhecido em uma breve atualização de abertura. Durante o trabalho, evite mensagens de marco rotineiras, tabelas de cores, dumps de QA e explicações repetidas de pré-visualização. Forneça apenas breves atualizações de progresso exigidas por instruções de tempo de execução de maior prioridade, ou reporte um bloqueador, decisão necessária do usuário ou mudança de escopo do material prontamente.

Mantenha evidências completas, candidatos e relatórios localmente na cena; retorne sumários compactos de ferramentas para decisões. Prefira inspeção visual interna quando a ferramenta explicitamente a suportar. Se uma ferramenta exibir automaticamente imagens no chat, aceite essa limitação, use apenas capturas necessárias e não incorpore essas imagens novamente em comentários ou na resposta final. Nunca invente um modo de pré-visualização oculta ou pule QA visual necessária para manter o chat silencioso. Use uma visão geral mapeada por padrão; capturas adicionais devem resolver uma incerteza ou verificar uma correção significativa.

Termine com um relatório conciso cobrindo o arquivo salvo e estado sujo, resultado de QA, limitações de material e detalhes pendentes. Peça aprovação da base no checkpoint existente. Se salvar ou uma verificação necessária falhar, reporte o estado real incompleto. Narração mínima por si só não estabelece economia de velocidade ou tokens.

Mapeamento base

1. Conecte e prepare. Chame get_addon_status uma vez e obtenha fatos compactos da cena: caminho de trabalho, malhas, limites do mundo, contagens de face/triângulo e materiais. Agrupe leituras independentes. Importe auxiliares do diretório absoluto de scripts desta skill em cada chamada ao Blender que os utilize. Na primeira importação, coloque esse diretório primeiro em sys.path, remova módulos gm de outros caminhos, recarregue gm_core e imprima seu caminho/versão verificados uma vez (base-api.md). Chamadas posteriores importam sem recarregar. Execute ensure_palette; inclua fallback, religação ou criação de material no relatório final, a menos que exija uma decisão do usuário agora. Pergunte antes de atualizar uma cópia diferente da paleta da equipe na skill. A atualização de abertura cobre a atribuição de paleta antes de prepare_model(..., assign_material=True); evite um anúncio de rotina separado.
2. Identifique materiais antes do mapeamento. Em um lote de descoberta inicial, quando prático, reúna partes, limites, grupos UV originais e sumários de normais no espaço do mundo para os objetos alvo. Armazene associações e evidências privadamente; resuma apenas partes relevantes para decisão. Foque verificações mais profundas de PCA/profundidade/adjacência em partes ambíguas ou mistas e famílias representativas, depois reutilize evidências verificadas. Descoberta adicional é permitida para limites não resolvidos. Combine pistas geométricas com posição do conceito; descoberta precede atribuição semântica. Audite partes dominantes incertas antes de atribuí-las. Uma caixa delimitadora fina pode descrever uma chapa larga ou uma corda diagonal: inspecione dimensões principais e extensão de superfície mais posição semântica. Dicas de formato são evidências, nunca rótulos de material. Capture surface_groups(..., uv_seams=True) antes de sobrescrever UVs em shells mistos. Verifique um representante e estrutura correspondente antes de reutilizar uma regra para repetições. Resolva limites de painel/aro, cavidade/superfície e envoltório/mastro durante a base. Complete a verificação de material de partes pequenas em reference-quality.md para cada parte ou família estruturalmente verificada; tamanho pequeno não isenta uma parte. Atribuições incertas exigem descoberta focada antes do mapeamento.
3. Planeje e atribua. Use reference-quality.md para cores de conceito medidas ou explicitamente estimadas, hierarquia de material e valor. Agrupe buscas completas de V seguro com suggest_zone_colors; retenha 2–3 candidatos e cores escolhidas privadamente; emita apenas um sumário compacto de ferramenta e problemas que exigem decisão. Atribua zonas a partir da auditoria de material verificada e verifique faces não atribuídas e limites incertos antes do mapeamento. Não use um material padrão genérico para fazer a cobertura passar; atribuições temporárias permanecem explicitamente incertas até serem verificadas. Preserve associações verificadas. Liste emblemas/tábuas faltantes como detalhes futuros.
4. Mapeie e compare. Aplique o plano, depois show_texture(light="FLAT"). Valide paleta e material de pré-visualização antes de inspecionar cor; evite uma captura de tela inicial toda rosa. Uma imagem pré-mapeamento deve responder a uma pergunta específica de geometria: use cores sólidas planas verificadas ou cores de zona temporárias. Inspecione uma visão geral comparável de 512–640 px após o mapeamento. Complete uma revisão de limites semânticos das famílias auditadas, incluindo pequenos acessórios e interfaces ocultas ou ilegíveis na visão geral. Use vistas direcionadas apenas onde necessário. Corrija objetos/zonas afetados apenas e verifique vizinhos. Ajuste de luz real opcional é para uma incompatibilidade concreta não resolvida, não uma passagem de ativo inteiro padrão. Outra captura deve resolver um problema ou verificar uma correção significativa.
5. QA final e salvamento. Conclua correções planejadas de cor e limite antes do QA final. Durante o mapeamento, use verificações compactas de cobertura, limite e zona afetada em vez de QA final de ativo inteiro. Após a última alteração, execute qa e qa_faces em cada alvo uma vez. Um reparo solicitado pelo QA invalida resultados afetados: execute novamente os auxiliares de objeto inteiro nos alvos afetados e expanda para todos os usuários para mudanças de dependência compartilhada; nunca salve usando QA desatualizado. Corrija falhas; inspecione e documente avisos/exceções intencionais. Verifique cobertura, margens, UV ativo/render, links reais de shader de paleta, normais/luz e topologia base inalterada. Registre comparação de referência e resultado da verificação de material separadamente: dados de QA não provam atribuição correta de material ou similaridade visual. Não marque uma base como totalmente verificada enquanto houver atribuições incertas; registre qualquer limitação genuína de referência/topologia explicitamente. Finalize pré-visualizações temporárias, empacote a paleta, deixe textura visível e execute o salvamento protegido em base-api.md. Reporte caminho salvo/estado sujo, detalhes pendentes e peça aprovação da base.

Disciplina de cache e saída

• Execute state_signature + compare_state uma vez por lote dependente antes de reutilizar cache. Assinaturas faltantes são não verificadas. Mudanças de geometria invalidam associações; mudanças de UV invalidam evidências de UV original. Mudanças compartilhadas de normal/paleta/material/transform/luz expandem escopo. Atualize assinaturas após edições aceitas. Não repita assinaturas entre leituras independentes em um lote inalterado.
• Mantenha partes completas, associações de face, dados de paleta, candidatos e QA na cena. Retorne contagens agregadas mais no máximo 12 linhas de partes relevantes para decisão por padrão; expanda apenas para uma região nomeada não resolvida ou solicitação do usuário. Nunca imprima o mapa de paleta/catálogo de strips completo, lista de candidatos, catálogo de faces/vértices ou cache de cena. Filtre zonas vazias de apply_plan; retorne totais de faces mapeadas e strips alteradas, não relatórios brutos de auxiliares. A saída final de QA cobre cada alvo com contagens de falhas/problemas e avisos acionáveis; mantenha relatórios detalhados de aprovação privadamente.
• Emita uma representação de resultado MCP: structuredContent quando disponível, caso contrário conteúdo de texto. Encaminhe blocos de imagem separadamente. Não transforme em string ambas representações duplicadas ou dados de imagem.
• Agrupe leituras independentes e operações de objeto compatíveis; mantenha verificações/edições dependentes sequenciais. Evite capturas de tela inalteradas, dumps de cena e polling de conexão. Sem alegações de economia de token/tempo sem medições comparáveis.

Eficiência de execução

• Carregue o mapa de paleta uma vez por lote de execução. Armazene em cache part_evidence por associação de face verificada; não recalcule PCA separadamente para centro e tamanho. Agrupe leituras e correções compatíveis enquanto mantém decisões revisáveis. Preserve o algoritmo de mapeamento mantido.
• Antes da captura, estabeleça validade de imagem/shader, sombreamento, luz e enquadramento juntos. Colete incompatibilidades concretas da visão geral e agrupe correções independentes antes da verificação. Para edições locais, preserve e verifique dados UV/zona fora do escopo e verifique limites vizinhos; expanda escopo para dependências compartilhadas.
• Armazene métricas leves de execução localmente na cena: identidade alvo/base, segundos por etapa, contagens reais de chamadas de ferramenta/captura e status final de QA. Use time.perf_counter() ao redor do trabalho existente de descoberta, mapeamento/correções e QA/salvamento; conte chamadas reais de ferramenta na orquestração. Não adicione chamadas apenas para medir. Marque métricas indisponíveis e distinga tempo de execução do Blender de tempo decorrido ponta a ponta. Faça benchmark apenas quando solicitado no mesmo conceito/modelo/estado inicial, comparando qualidade e tempo. Não equacione bytes de saída com economia de tokens.

Salvamento e recuperação

Para edições de cor/UV, use Undo de sessão e política de backup existente do Blender; nenhum arquivo de recuperação separado. Atualizar o arquivo de trabalho é autorizado, mas limites de filesystem ainda se aplicam. Resolva a rota de salvamento permitida uma vez e reutilize-a. Prefira a ferramenta do Blender conectada quando permitido. Se elevação for necessária, solicite-a apenas para o salvamento protegido concreto após QA. Não redescubra fonte do servidor ou implemente TCP bruto por execução. Um fallback aprovado deve usar host/porta configurados ativos, nunca uma porta adivinhada ou uma rota que burle a negação.

Antes de edições geométricas, salve uma cópia de recuperação no diretório irmão _backup/<working_stem>_gm_recovery.blend com copy=True; reutilize apenas este slot de propriedade da skill. Para esse salvamento de recuperação apenas, registre preferences.filepaths.save_version, defina-o temporariamente para 0 e restaure em finally. Não persista preferências, mude a política de salvamento de trabalho ou remova backups do usuário. Verifique autorização e salvamento de recuperação bem-sucedido antes de cortar; pare o trabalho geométrico se falhar.

Edições bpy diretas podem deixar is_dirty=False: exija um operador de salvamento explícito bem-sucedido, caminho de arquivo resultante correspondente e verificação suja pós-salvamento. Preserve estado de rollback em caso de falha. Se captura visual não estiver disponível, complete QA de dados, marque fidelidade visual como não verificada e identifique a região para revisão ao vivo.