O que 3d-builder faz?
Não adivinhe um modelo 3D. Escreva o que será construído, esclareça o que está ambíguo com o usuário, registre cada suposição e só então modele. Um modelo construído com dimensões adivinhadas é corrigido repetidamente; uma especificação captura os palpites antes que se tornem geometria.
O fluxo de trabalho tem estas fases, sempre nesta ordem: especificação → perguntas → plantas baixas (apenas construções) → modelo. Não abra o Blender ou FreeCAD, e não escreva código de modelagem, antes que a especificação exista e as perguntas sejam concluídas. Para uma construção, o usuário também deve ter aprovado as plantas baixas primeiro.
Estrutura do projeto
Um projeto pode conter vários modelos, portanto tudo que pertence a um modelo vive em sua própria pasta:
models/
<nome>/
specs/
<aaaa-mm-dd-hhmmss>-<solicitacao>.md # uma especificação por solicitação
plans/ # apenas construções
layout.json
floor-<id>.svg
<nome>.blend | <nome>.FCStd # o modelo
<nome>.py # apenas fallback de script
<nome>.glb | <nome>.fbx # apenas exportações para jogos/web
.3d-builder.json # escolha da ferramenta lembrada, para todo o projeto
<nome> é um nome curto em kebab-case para o objeto (phone-holder, router-wall-mount). Ele nomeia a pasta e os arquivos do modelo. Todos os caminhos abaixo são relativos a models/<nome>/, a menos que indicado o contrário.
Projetos antigos podem ainda usar a estrutura plana anterior (specs/ e plans/ na raiz do projeto, models/<nome>.blend). Se você encontrar um, trabalhe com ele como está e ofereça uma vez para mover os arquivos para esta estrutura. Não mova nada sem perguntar.
Fase 1: Escrever a especificação
- Escolha o
<nome>do modelo. Para um novo modelo, verifique semodels/<nome>/não existe ainda, então crie-o e sua pastaspecs/. - Obtenha o timestamp do relógio do sistema (ex.:
date +%Y-%m-%d-%H%M%S) em vez de inventar um. - Crie
specs/<aaaa-mm-dd-hhmmss>-<solicitacao>.mdusando o template em references/spec-template.md.<solicitacao>é um rótulo curto em kebab-case para esta solicitação:initialpara um novo modelo, ou a alteração para uma edição (thicker-hook,move-kitchen-wall).
Preencha o que a solicitação já declarou, então liste os pontos em aberto: tudo que afeta a geometria mas não foi especificado. Pontos em aberto típicos:
- Dimensões gerais e unidades, e quais dimensões são fixas vs. livres
- Ajuste e folga em relação a objetos reais (um telefone de 60 mm precisa de um encaixe ligeiramente maior que 60 mm; quanto?)
- Espessura da parede, filetes/chanfros, tamanhos de furos, tipos de parafusos
- Método de montagem, orientação, carga
- Propósito e fabricação (impressão 3D → saliências, paredes mínimas, base plana; CNC; apenas render; ativo para jogo/web)
- Para ativos de jogo/web: engine alvo, orçamento de polígonos, escala em unidades da engine, posição do pivô, UVs e texturas vs. cores sólidas, LODs, malha de colisão
- Nível de detalhe, materiais (Blender), necessidades paramétricas (FreeCAD)
- Para construções: andares, pegada, cômodos e seus tamanhos, escadas, portas e janelas. Estes serão resolvidos na Fase 3 com as plantas baixas, então liste-os lá e não aqui
Editando um modelo existente: encontre primeiro a pasta do objeto em models/. Escreva uma nova especificação para a alteração (cada solicitação tem seu próprio arquivo, para que o histórico permaneça legível), vincule-a à especificação anterior e declare o que muda e o que deve permanecer igual. Leia o modelo existente (via MCP, ou o script que o construiu) antes de editar, para que a edição comece a partir do que realmente está lá. Para uma construção com uma pasta plans/, uma alteração de layout passa primeiro pelas plantas (Fase 3, "Editando uma construção").
Fase 2: Perguntas esclarecedoras
Se a solicitação deixar pontos em aberto, pergunte sobre eles antes de modelar. O usuário sabe coisas que você não pode inferir (a largura real do telefone, onde os parafusos de parede vão), e uma pergunta agora evita uma reconstrução depois.
Regras:
- Uma pergunta de cada vez. Espere a resposta antes de fazer a próxima. Ordene as perguntas por quanto elas afetam a geometria: tamanho geral e propósito primeiro, detalhes cosméticos por último.
- Sim/não quando possível. "O slot do cabo deve ser centralizado?" é melhor que "Onde o slot do cabo deve ficar?".
- Caso contrário, múltipla escolha: a opção recomendada primeiro e marcada como "(recomendado)", depois as alternativas e, por último, uma resposta de texto livre. Use a ferramenta de perguntas do agente (ex.: AskUserQuestion) se houver uma; ela geralmente adiciona a opção de texto livre para você.
- Lotes de 5. Após cada 5 perguntas, pergunte se deseja continuar com mais até 5, dizendo aproximadamente quantos pontos em aberto restam. Se o usuário disser não, pare de perguntar.
- Não pergunte sobre coisas que não importam para este modelo, e não pergunte o que o usuário já disse.
- Registre cada resposta na seção Decisões da especificação imediatamente, para que a especificação esteja sempre atualizada.
Pare quando nada importante permanecer incerto, ou quando o usuário parar de responder. Para cada ponto em aberto que restar, decida por si mesmo, escolhendo o padrão sensato para o propósito declarado, e escreva-o em Suposições com uma razão de uma linha. O usuário deve ser capaz de ler a especificação e ver cada escolha feita em seu nome.
Se a solicitação já estiver totalmente especificada, pule as perguntas e diga isso em uma linha.
Fase 3: Plantas baixas (apenas construções)
Se o modelo é uma construção ou tem cômodos, resolva o layout no papel antes de modelar. Leia references/floorplans.md e siga-o:
- Discuta a planta baixa com o usuário, usando as regras de perguntas acima: andares, pegada, cômodos, adjacência, escadas, portas e janelas.
- Desenhe uma planta vetorial para cada andar. Escreva
plans/layout.jsone gereplans/floor-<id>.svgcom o script incluído scripts/draw_plans.py. - Revise as plantas com o usuário e revise-as até que o usuário aprove. Registre a aprovação em Decisões.
O layout.json aprovado é a fonte da verdade para as paredes, aberturas, cômodos e escadas do modelo. Pule esta fase para qualquer coisa que não seja uma construção.
Fase 4: Modelo
Salve o resultado em <nome>.blend (Blender) ou <nome>.FCStd (FreeCAD) na pasta do modelo. Para um ativo de jogo ou web, também exporte-o ao lado do arquivo fonte (veja Exportar para engines).
Escolher a ferramenta
Verifique quais servidores MCP estão configurados: olhe suas ferramentas disponíveis para ferramentas MCP do Blender ou FreeCAD (nomes geralmente contêm blender ou freecad).
- Escolha lembrada: se
.3d-builder.jsonexistir na raiz do projeto, use seu"tool"("blender"ou"freecad") a menos que o usuário peça outra coisa. - Exatamente um servidor MCP configurado: use essa ferramenta.
- Ambos ou nenhum configurado: pergunte ao usuário qual ferramenta usar (uma pergunta de múltipla escolha). Recomende FreeCAD para peças funcionais com dimensões precisas (suportes, invólucros, qualquer coisa impressa ou usinada), e Blender para formas orgânicas, objetos esculpidos ou decorativos, qualquer coisa destinada a renderização e ativos para jogos ou web (as malhas tesseladas do FreeCAD são pouco adequadas para uso em tempo real).
- Lembre a escolha escrevendo
{"tool": "blender"}ou{"tool": "freecad"}em.3d-builder.json. Registre a ferramenta na especificação também.
Construir via MCP (preferencial)
- Faça uma chamada barata primeiro (ex.: obter informações da cena/documento). Se der erro ou não responder em 10 segundos, trate o servidor como indisponível e mude para o fallback de script. Diga ao usuário o motivo em uma linha.
- Construa o modelo passo a passo a partir da especificação. Verifique as dimensões enquanto avança (consultando bounding boxes ou propriedades de objetos) em vez de confiar que o código fez o que você pretendia.
- Salve no caminho acima.
Fallback de script
Quando nenhum servidor MCP estiver utilizável, escreva um script Python autônomo, <nome>.py na pasta do modelo, que construa o modelo do zero e salve <nome>.blend ou <nome>.FCStd ao lado de si mesmo. Coloque as dimensões-chave como constantes nomeadas no topo para que o usuário possa ajustá-las. Para uma construção, o script lê plans/layout.json e não copia as coordenadas para o código (veja references/floorplans.md, "Construir o modelo a partir do layout").
Em seguida, tente executá-lo sem interface gráfica, se a ferramenta estiver instalada:
- Blender:
blender --background --python models/<nome>/<nome>.py - FreeCAD:
freecadcmd models/<nome>/<nome>.py(em alguns sistemasFreeCADCmdoufreecad.cmd)
Se funcionar, verifique a saída (arquivo existe, bounding box impressa corresponde à especificação). Se falhar, corrija o script e execute novamente. Se a ferramenta não estiver no PATH, diga ao usuário o comando exato para executar.
Armadilhas específicas da ferramenta e esqueletos de script: references/blender.md, references/freecad.md. Leia o da ferramenta escolhida antes de escrever código.
Exportar para engines
Apenas para ativos de jogo ou web. Mantenha o .blend como fonte editável e exporte ao lado dele:
| Alvo | Formato | Arquivo |
|---|---|---|
| Web (three.js, Babylon.js), Godot, uso geral | glTF binário | <nome>.glb |
| Unity, Unreal | FBX (ou .glb se o pipeline do usuário importar glTF) | <nome>.fbx |
As engines são em tempo real, então o ativo deve respeitar o orçamento da especificação: verifique a contagem de triângulos, aplique transformações, coloque o pivô onde a especificação diz e corresponda à escala e eixos da engine. Configurações de exportação e armadilhas: a seção "Ativos para jogos e web" em references/blender.md.
Esta skill entrega o arquivo do ativo. Carregá-lo em uma cena, escrever scripts de engine ou construir uma página three.js está fora do seu escopo; se o usuário também quiser isso, faça como uma etapa separada após este fluxo de trabalho estar concluído.
Finalizar
- Verifique o modelo contra a especificação: dimensões gerais, cada recurso listado presente e quaisquer requisitos de ajuste ou folga. Para ativos de jogo/web, também a contagem de triângulos contra o orçamento e o bounding box do arquivo exportado em unidades da engine. Para construções, também verifique contra as plantas aprovadas: dimensões gerais, posições das paredes, cada porta e janela e níveis dos andares.
- Atualize a especificação: defina Status como
done, preencha Saída (caminhos de arquivo incluindo exportações e plantas, ferramenta, MCP ou script) e anote qualquer coisa que tenha ficado diferente do planejado. - Relate ao usuário brevemente: o que foi construído, onde estão os arquivos e as principais suposições que ele pode querer revisitar (aponte para a especificação para o resto).
Se o usuário pedir alterações depois disso, trate-as como uma nova solicitação de edição (Fase 1, "Editando um modelo existente"). Pequenos acompanhamentos na mesma conversa ("um pouco mais grosso") podem ir na mesma especificação sob Revisões.