Reconhecimento de peças LEGO e design de MOC
Duas etapas:
- Digitalizar. O usuário fotografa peças soltas; o servidor as reconhece e mantém o inventário (por ID de usuário).
- Projetar e verificar. Você projeta um modelo (MOC) a partir desse inventário e o escreve como um arquivo LDraw. O servidor verifica fisicamente: em caso de falha, nomeia as linhas problemáticas; em caso de aprovação, publica uma página com visualização 3D e instruções de montagem passo a passo. O servidor não projeta nada: o design é seu.
Existem duas formas de trabalhar. Ferramentas MCP (seção 2) não precisam de comandos shell; use-as sempre que estiverem disponíveis. O script scripts/lego.py (seção 5) faz o mesmo por meio de comandos shell e é a alternativa.
1. As ferramentas MCP estão disponíveis?
Verifique em sua lista de ferramentas por estes nomes, geralmente mostrados sob um prefixo de servidor como lego-moc (por exemplo, mcp__lego-moc__scan_photos ou lego-moc.scan_photos):
scan_photos, scan_status, inventory, edit_inventory, design_guide, connectors, submit_model, moc_status
- Todas presentes: trabalhe conforme a seção 2.
- Todas exceto
scan_photos: o host usa o endpoint do servidor remoto, que não pode ler arquivos neste computador. Faça upload das fotos com o script (scan), faça todo o resto com as ferramentas. - Nenhuma presente: use o script (seção 5) para esta tarefa; tudo funciona com ele. Em seguida, ofereça ao usuário a configuração única abaixo, que remove as aprovações por comando.
Configuração única (o usuário faz)
- Execute
python3 <pasta desta skill>/scripts/lego.py mcp-config(Windows:python). Isso imprime um bloco JSON e não faz nenhuma chamada de rede. - Dê esse JSON ao usuário e peça que adicione a entrada
lego-mocà seçãomcpServersdas configurações MCP do agente (página de configurações ou arquivo de configuração MCP) e, em seguida, reinicie o agente ou recarregue seus servidores MCP. Edite a configuração do host você mesmo apenas se o usuário solicitar. - Após a reinicialização, o agente inicia a ponte por conta própria (
lego.py mcp, um servidor MCP stdio local) e as ferramentas aparecem. A mesma pasta~/.lego-parts/e ID de usuário são usados, então nada digitalizado até agora é perdido.
lego.py mcp-config --remote imprime o endpoint do próprio servidor (type: http, uma URL que contém o ID de usuário; ele cria um ID se nenhum existir). Use-o apenas para hosts que não podem executar comandos locais. Ele não tem scan_photos, e sua URL é uma credencial: nunca a publique em lugar público.
2. Fluxo MCP
Todo resultado de ferramenta tem uma parte de texto para você ler e um objeto structuredContent com os campos. Um erro retorna como um resultado com isError: true cujo texto informa o que aconteceu e o que fazer a seguir. Siga as instruções; não contorne com suas próprias chamadas HTTP.
Digitalizar
scan_photos{"paths": [...]}: caminhos absolutos de arquivos de foto, pastas ou padrões glob neste computador, de 1 a 30 fotos por chamada (JPEG, PNG, WEBP, HEIC, 25 MB cada). Retorna imediatamente com uma tarefa por foto; não espera pelo reconhecimento. Informe ao usuário cada entrada derejectedenot_uploadedcom seu motivo. Uma entradaduplicate_photosignifica que o arquivo exato foi enviado antes: não é reconhecido novamente, epreviousé o resultado do primeiro upload (suas peças já estão no inventário). Se o host exceder o tempo limite da chamada, o upload continua: chamescan_statusem vez de fazer upload novamente. Com muitas fotos grandes, use várias chamadas de cerca de 8 fotos.scan_status{"wait_s": 50}: repita até quependingseja 0 (o reconhecimento leva minutos; a primeira foto pode esperar a GPU iniciar). Transmita cada entrada denotices(pile_photo,no_pieces) ao usuário literalmente e nomeie as fotos com falha com seuerror. Se permanecer pendente por muito tempo, informe ao usuário quantas fotos ainda estão sendo processadas, em vez de repetir indefinidamente.
Exibir e corrigir o inventário
inventory: mostra o inventário com uma imagem de visão geral (uma imagem no resultado) einventory_url. Mostre a imagem ao usuário e forneça o link; se você tiver um navegador ou painel de visualização, abra o link lá. Nunca apresente uma tabela de números de peça simples: a maioria dos usuários não sabe o que é3020. Aponte as linhas de baixa confiança (moldura laranja e?na imagem) e peça ao usuário para verificá-las na página. As linhasdesignable: falsenão têm geometria 3D utilizável e nunca podem ser usadas na construção.pending_tasks > 0significa que o inventário está incompleto: diga isso. Usefilter: "usable"ou"low_confidence"eoffset/limitpara inventários longos.edit_inventory{"changes": [...]}, apenas sob orientação do usuário (nunca para fazer um design se ajustar):{"op": "set_quantity", "key": "3001|4", "quantity": 3},{"op": "remove", "key": ...},{"op": "confirm", "key": ...}(o usuário verificou uma linha de baixa confiança e está correta),{"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4}(é realmente outra peça ou cor),{"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2},{"op": "undo", "key": ...},{"op": "undo_all"}. Cada alteração relataok; informe ao usuário quais não se aplicaram e por quê. O usuário pode fazer as mesmas edições na página de inventário.
Projetar
- Entenda a solicitação (seção 3): assunto, descrição, imagem de referência ou nada; verifique se o inventário pode suportá-la antes de projetar.
design_guide: leia o guia completo antes do seu primeiro design em uma conversa. É o livro de regras atual do servidor: formato de arquivo, coordenadas, quais conectores se encaixam, regras do verificador, exemplos práticos e como usar muitas peças. Também retornausable_quantityetarget_percent.connectors{"parts": ["3001", "3023", ...]}(1–40 números de peça LDraw por chamada): os limites e cada conector de cada peça que você planeja usar. Obtenha a origem e as posições dos conectores de cada peça daqui; nunca as adivinhe. Uma peça relatada comounsupportednão pode ser usada.- Escreva o modelo: uma linha
0 <título>, em seguida, uma linha1 <cor> x y z a b c d e f g h i <peça>.datpor peça, com<cor>=ldraw_colore<peça>=ldraw_partdo inventário. Apenas linhas utilizáveis, e porkeyno máximo suaquantityem todo o modelo; conte antes de enviar. Sem submodelos, sem linhas0 STEP.
Verificar e melhorar
submit_model{"ldr": "<arquivo inteiro>", "title": "...", "brief": "<solicitação do usuário, palavras dele>"}; adicione"moc_id"para enviar uma nova versão do mesmo modelo e"design"apenas para peças móveis declaradas (veja o guia). Aguarda atéwait_s(padrão 45) e retornastatus, osissues(cada falha nomeia a regra, uma dica e as peças com sua linha de arquivo e posição),usage,resubmissions_lefte, em caso de aprovação,urle duas imagens de visualização. Sestatusainda não for final (queued,checking,stepping), chamemoc_status{"moc_id": ..., "wait_s": 50}. O statuserroré uma falha do lado do servidor, não um problema de design: envie o mesmo modelo novamente com seumoc_id.- Falhou: corrija exatamente as linhas nomeadas (recalcule posições a partir de
connectors, não ajuste números) e envie novamente com omoc_id. - Aprovado: veja ambas as visualizações e o
usage, e decida se outra rodada vale a pena (seção 4). A página pública sempre mostra a versão mais recente que foi aprovada, então uma rodada posterior com falha não a derruba. - Relatório: forneça ao usuário a
urlda página (diga que é pública), a contagem de peças e etapas, todos os avisos, o que você construiu e o que não conseguiu fazer. A aprovação significa que o modelo é fisicamente consistente na simulação do verificador, não que a construção real seja garantida de segurar: diga isso.
3. Solicitações de design
O usuário pode dar um assunto ("um carro"), uma descrição detalhada, uma imagem de referência ou nada.
- Verifique a viabilidade primeiro. Olhe o inventário (formas, cores, quantidades) antes de prometer algo. Um carro precisa de rodas e eixos ou algo que possa substituí-los; uma casa precisa de tijolos suficientes para paredes e peças para um telhado. Diga claramente ao usuário o que pode e o que não pode ser atendido e proponha alternativas que as peças permitam (uma versão menor, outro assunto, um estilizado) em vez de forçar.
- Descrição: mantenha as características que o usuário nomeou; diga quais você teve que descartar ou alterar e por quê.
- Imagem de referência (apenas se você puder ver imagens): construa um modelo no espírito dela (sua forma, proporções e cores principais) a partir das peças que o usuário possui. Não será uma réplica; diga isso.
- Nada fornecido: escolha um assunto que se adapte ao inventário (suas cores principais e as formas que mais tem) e diga o que escolheu.
- Passe o texto da solicitação do usuário, nas palavras dele, como
brief. Coloque o assunto no título. - Inventário enxuto. Se houver menos de cerca de 60 peças utilizáveis, ou o inventário for principalmente peças únicas em muitas cores, avise o usuário antes de projetar: apenas um modelo pequeno ou abstrato é possível. Sugira confirmar as linhas de baixa confiança (após verificá-las na página de inventário) e fotografar mais peças espalhadas. Uma nova foto de peças que já foram contadas as conta novamente: sugira fotografar peças ainda não digitalizadas ou corrigir as quantidades depois com
set_quantity.
4. Use muitas peças e refine
- Meta: use pelo menos 60% das peças utilizáveis (
usage.target_percent) a menos que o usuário tenha solicitado algo pequeno. Utilizável = projetável e não de baixa confiança, ou confirmado.usage.percentem cada resultado de envio mostra onde você está, eusage.unusedlista o que sobrou, do mais abundante primeiro. - Divida o trabalho. Versão 1: a estrutura principal (base, corpo, as grandes formas). Versões posteriores adicionam detalhes em grandes etapas: acabamento do telhado, janelas e portas, grades, decoração, uma placa de base ou chão. Existem apenas 5 reenvios por modelo, então cada rodada deve adicionar muito; não gaste uma em uma única peça.
- Cada resultado: leia
usageeunusede pergunte quais peças não utilizadas melhorariam o assunto. Em uma aprovação, veja ambas as visualizações e corrija o que parecer errado: uma mistura aleatória de cores, pinos descobertos no topo, uma forma desequilibrada onde o assunto é simétrico, uma caixa chata. A seção de conselhos do guia diz como. - Pare quando o modelo estiver bom e a meta for atingida, quando o inventário não puder adicionar nada sensato ou quando os reenvios se esgotarem. Informe ao usuário o uso final.
5. Script alternativo
Use o script quando as ferramentas MCP não estiverem disponíveis. Python 3.8+, apenas biblioteca padrão, nada para instalar.
python3 <pasta desta skill>/scripts/lego.py <comando> [opções] [argumentos]
No Windows use python ou py -3. Coloque as opções antes da lista de fotos.
Mantenha as aprovações do usuário em poucas. Muitos agentes pedem que o usuário aprove cada novo comando shell, host de rede e gravação fora do espaço de trabalho. Então:
- Sempre chame o script exatamente desta forma, como um único comando simples: sem
cd, sem pipes, sem&&, sem prefixo de ambiente, sem script wrapper. Assim, o usuário pode aprovar "sempre permitir" uma vez parapython3 <caminho>/lego.py. Informe o usuário sobre isso na primeira vez que uma aprovação aparecer e mencione a configuração MCP (seção 1), que as evita. - O script precisa de três coisas, todas as quais o usuário pode permitir uma vez: executar
lego.py, alcançar o host do servidor mostrado porlego.py whoamie ler/gravar~/.lego-parts/. - Não execute a mesma etapa duas vezes, não faça polling em um loop de comandos curtos (use
--wait) e não chame o servidor com curl ou código próprio. - Escreva
model.ldrcom sua ferramenta de escrita de arquivos no menor número de etapas possível; evite uma série de scripts descartáveis.
| Comando | O que faz |
|---|---|
scan [--no-wait] [--wait SEGUNDOS] [--images] FOTO... | Envia de 1 a 30 fotos (arquivos, pastas ou padrões glob), aguarda até 480 s (padrão) pelos resultados e os salva. --no-wait retorna imediatamente após o upload. |
status [--wait SEGUNDOS] [--images] [ID_TAREFA...] | Verifica as tarefas pendentes (ou as fornecidas) uma vez ou continua fazendo polling por até SEGUNDOS. Salva as concluídas. |
parts [--images] | Salva as tarefas pendentes concluídas e recarrega todo o inventário (com as edições feitas na página de inventário ou com edit_inventory) em parts.json. |
whoami | Mostra o ID de usuário, servidor e pasta local. Sem rede. |
moc guide [--parts-file CAMINHO] | Salva o guia de design moc/DESIGN_GUIDE.md e as folhas de conectores de suas peças moc/connectors.txt. |
moc submit [--title NOME] [--brief TEXTO] [--design design.json] [--moc MOC_ID] [--parts-file CAMINHO] [--no-wait] [--wait SEGUNDOS] MODELO.ldr | Envia o modelo com parts.json, aguarda até 300 s (padrão) pela verificação e imprime o resultado, o uso de peças e, em caso de aprovação, os links de visualização. --moc envia uma nova versão de um MOC existente; --brief é a solicitação do usuário. |
moc status [--wait SEGUNDOS] [MOC_ID] | Verifica os envios de MOC pendentes (ou o fornecido) uma vez ou continua fazendo polling por até SEGUNDOS. |
mcp-config [--remote] | Imprime o JSON para a configuração MCP (seção 1). A saída é apenas esse JSON; nenhuma linha RESULT. |
mcp | A própria ponte MCP. O host do agente o executa; não execute você mesmo. |
--images também baixa a imagem LDraw de cada linha de inventário e o recorte da foto para images/.
- Esperas longas.
scanpode levar 8 minutos,moc submit5. Se sua ferramenta shell expirar mais cedo, aumente o tempo limite ou passe um--waitmenor (ex.:--wait 100) e continue comstatus --wait 100/moc status --wait 100. Ser interrompido durante a espera é seguro: os IDs são salvos empending.json/moc/pending.jsonprimeiro, e qualquer comando posterior, de qualquer agente, os coleta. - Endereço do servidor. Incorporado no script baixado. Se um comando disser que nenhum servidor está configurado, o usuário deve definir
LEGO_PARTS_SERVER(ex.:https://lego.groundrl.com, sem/skill/v1).LEGO_PARTS_HOMEaltera a pasta local. - Rede bloqueada. Se um comando relatar
HTTP 403 ... não do servidor LEGOou não conseguir alcançar o servidor, um sandbox, proxy ou firewall está bloqueando. Pergunte ao usuário se pode acessar a URL do servidor em um navegador.