Que fait Reconnaissance de pièces LEGO et conception MOC ?
Deux étapes :
- Numérisation. L'utilisateur photographie des pièces détachées ; le serveur les reconnaît et tient à jour l'inventaire (par ID utilisateur).
- Conception et vérification. Vous concevez un modèle (MOC) à partir de cet inventaire et l'écrivez sous forme de fichier LDraw. Le serveur le vérifie physiquement : en cas d'échec, il nomme les lignes problématiques ; en cas de succès, il publie une page avec une vue 3D et des instructions de montage étape par étape. Le serveur ne conçoit rien : la conception vous appartient.
Il existe deux façons de travailler. Les outils MCP (section 2) ne nécessitent aucune commande shell ; utilisez-les quand ils sont disponibles. Le script scripts/lego.py (section 5) fait la même chose via des commandes shell et sert de solution de repli.
1. Les outils MCP sont-ils disponibles ?
Recherchez dans votre liste d'outils ces noms, généralement affichés sous un préfixe de serveur tel que lego-moc (par exemple mcp__lego-moc__scan_photos ou lego-moc.scan_photos) :
scan_photos, scan_status, inventory, edit_inventory, design_guide, connectors, submit_model, moc_status
- Tous présents : travaillez comme décrit dans la section 2.
- Tous sauf
scan_photos: l'hôte utilise le point de terminaison du serveur distant, qui ne peut pas lire les fichiers de cet ordinateur. Téléchargez les photos avec le script (scan), faites tout le reste avec les outils. - Aucun présent : utilisez le script (section 5) pour cette tâche ; tout fonctionne avec lui. Proposez ensuite à l'utilisateur la configuration unique ci-dessous, qui supprime les approbations par commande.
Configuration unique (l'utilisateur le fait)
- Exécutez
python3 <dossier de cette compétence>/scripts/lego.py mcp-config(Windows :python). Il affiche un bloc JSON et n'effectue aucun appel réseau. - Donnez ce JSON à l'utilisateur et demandez-lui d'ajouter l'entrée
lego-mocà la sectionmcpServersdes paramètres MCP de l'agent (page de paramètres ou fichier de configuration MCP), puis redémarrez l'agent ou rechargez ses serveurs MCP. Ne modifiez la configuration de l'hôte vous-même que si l'utilisateur vous le demande. - Après le redémarrage, l'agent démarre lui-même le pont (
lego.py mcp, un serveur MCP stdio local) et les outils apparaissent. Le même dossier~/.lego-parts/et le même ID utilisateur sont utilisés, donc rien de ce qui a été numérisé jusqu'à présent n'est perdu.
lego.py mcp-config --remote affiche le point de terminaison du serveur lui-même (type: http, une URL contenant l'ID utilisateur ; il crée un ID s'il n'en existe pas). Utilisez-le uniquement pour les hôtes qui ne peuvent pas exécuter de commandes locales. Il n'a pas de scan_photos, et son URL est un identifiant : ne le publiez jamais nulle part publiquement.
2. Flux MCP
Chaque résultat d'outil comporte une partie textuelle pour vous et un objet structuredContent avec les champs. Une erreur revient sous forme de résultat avec isError: true dont le texte indique ce qui s'est passé et la marche à suivre. Suivez-la ; ne la contournez pas avec vos propres appels HTTP.
Numérisation
scan_photos{"paths": [...]}: chemins absolus de fichiers photos, dossiers ou motifs glob sur cet ordinateur, 1 à 30 photos par appel (JPEG, PNG, WEBP, HEIC, 25 Mo chacune). Il renvoie immédiatement une tâche par photo ; il n'attend pas la reconnaissance. Dites à l'utilisateur chaque entréerejectedetnot_uploadedavec sa raison. Une entréeduplicate_photosignifie que ce fichier exact a déjà été téléchargé : il n'est pas reconnu à nouveau, etpreviousest le résultat du premier téléchargement (ses pièces sont déjà dans l'inventaire). Si l'hôte interrompt l'appel par timeout, le téléchargement continue : appelezscan_statusau lieu de télécharger à nouveau. Avec beaucoup de grandes photos, utilisez plusieurs appels d'environ 8 photos.scan_status{"wait_s": 50}: répétez jusqu'à ce quependingsoit 0 (la reconnaissance prend quelques minutes ; la première photo peut attendre le démarrage du GPU). Relayez chaque entrée denotices(pile_photo,no_pieces) textuellement à l'utilisateur et nommez les photos en échec avec leurerror. Si l'état reste en attente pendant longtemps, dites à l'utilisateur combien de photos sont encore en cours de traitement au lieu de boucler indéfiniment.
Afficher et corriger l'inventaire
inventory: affiche l'inventaire avec une image d'ensemble (une image dans le résultat) etinventory_url. Montrez l'image à l'utilisateur et donnez-lui le lien ; si vous avez un navigateur ou un panneau de prévisualisation, ouvrez le lien. Ne présentez jamais un tableau de simples numéros de pièces : la plupart des utilisateurs ne peuvent pas dire ce qu'est3020. Signalez les lignes à faible confiance (cadre orange et?dans l'image) et demandez à l'utilisateur de les vérifier sur la page. Les lignesdesignable: falsen'ont pas de géométrie 3D utilisable et ne peuvent jamais être utilisées dans une construction.pending_tasks > 0signifie que l'inventaire est incomplet : dites-le. Utilisezfilter: "usable"ou"low_confidence"etoffset/limitpour les inventaires longs.edit_inventory{"changes": [...]}, uniquement sur la parole de l'utilisateur (jamais pour faire correspondre un design) :{"op": "set_quantity", "key": "3001|4", "quantity": 3},{"op": "remove", "key": ...},{"op": "confirm", "key": ...}(l'utilisateur a vérifié une ligne à faible confiance et elle est correcte),{"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4}(il s'agit en fait d'une autre pièce ou couleur),{"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2},{"op": "undo", "key": ...},{"op": "undo_all"}. Chaque modification signaleok; dites à l'utilisateur lesquelles n'ont pas été appliquées et pourquoi. L'utilisateur peut effectuer les mêmes modifications sur la page d'inventaire.
Conception
- Comprendre la demande (section 3) : sujet, description, image de référence ou rien ; vérifiez que l'inventaire peut la supporter avant de concevoir.
design_guide: lisez l'intégralité du guide avant votre première conception dans une conversation. C'est le livre de règles actuel du serveur : format de fichier, coordonnées, quels connecteurs s'accouplent, règles du vérificateur, exemples travaillés et comment utiliser de nombreuses pièces. Il renvoie égalementusable_quantityettarget_percent.connectors{"parts": ["3001", "3023", ...]}(1 à 40 numéros de pièces LDraw par appel) : les limites et chaque connecteur de chaque pièce que vous prévoyez d'utiliser. Prenez l'origine et les positions des connecteurs de chaque pièce à partir d'ici ; ne les devinez jamais. Une pièce signalée commeunsupportedne peut pas être utilisée.- Écrivez le modèle : une ligne
0 <title>, puis une ligne1 <colour> x y z a b c d e f g h i <part>.datpar pièce, avec<colour>=ldraw_coloret<part>=ldraw_partde l'inventaire. Uniquement les lignes utilisables, et parkeyau plus saquantitydans l'ensemble du modèle ; comptez avant de soumettre. Pas de sous-modèles, pas de lignes0 STEP.
Vérifier et améliorer
submit_model{"ldr": "<tout le fichier>", "title": "...", "brief": "<la demande de l'utilisateur, ses mots>"}; ajoutez"moc_id"pour soumettre une nouvelle version du même modèle, et"design"uniquement pour les pièces mobiles déclarées (voir le guide). Il attend jusqu'àwait_s(par défaut 45) et renvoiestatus, lesissues(chaque échec nomme la règle, un indice et les pièces avec leur ligne de fichier et position),usage,resubmissions_leftet, en cas de succès,urlet deux images de prévisualisation. Sistatusn'est pas encore final (queued,checking,stepping), appelezmoc_status{"moc_id": ..., "wait_s": 50}. Le statuterrorest une erreur côté serveur, pas un problème de conception : soumettez le même modèle à nouveau avec sonmoc_id.- Échec : corrigez exactement les lignes nommées (recalculez les positions à partir de
connectors, ne modifiez pas les nombres au hasard) et soumettez à nouveau avec lemoc_id. - Réussi : regardez les deux aperçus et
usage, puis décidez si un autre cycle en vaut la peine (section 4). La page publique affiche toujours la dernière version qui a réussi, donc un cycle ultérieur échoué ne la supprime pas. - Rapport : donnez à l'utilisateur l'
urlde la page (dites qu'elle est publique), le nombre de pièces et d'étapes, chaque avertissement, ce que vous avez construit et ce que vous n'avez pas pu faire. La réussite signifie que le modèle est physiquement cohérent dans la simulation du vérificateur, pas que la construction réelle est garantie de tenir : dites-le.
3. Demandes de conception
L'utilisateur peut donner un sujet ("une voiture"), une description détaillée, une image de référence ou rien du tout.
- Vérifiez d'abord la faisabilité. Regardez l'inventaire (formes, couleurs, quantités) avant de promettre quoi que ce soit. Une voiture a besoin de roues et d'essieux ou de quelque chose qui peut les remplacer ; une maison a besoin d'assez de briques pour les murs et de pièces pour un toit. Dites clairement à l'utilisateur ce qui peut et ne peut pas être réalisé, et proposez des alternatives que les pièces permettent (une version plus petite, un autre sujet, une version stylisée) au lieu de forcer.
- Description : conservez les caractéristiques que l'utilisateur a nommées ; dites lesquelles vous avez dû abandonner ou modifier et pourquoi.
- Image de référence (uniquement si vous pouvez voir des images) : construisez un modèle dans son esprit (sa forme, ses proportions et ses couleurs principales) à partir des pièces que l'utilisateur possède. Ce ne sera pas une réplique ; dites-le.
- Rien de donné : choisissez un sujet qui correspond à l'inventaire (ses couleurs principales et les formes dont il a le plus) et dites ce que vous avez choisi.
- Transmettez le texte de la demande de l'utilisateur, dans ses mots, comme
brief. Mettez le sujet dans le titre. - Inventaire maigre. S'il y a moins d'environ 60 pièces utilisables, ou si l'inventaire est principalement composé de pièces uniques de nombreuses couleurs, dites-le à l'utilisateur avant de concevoir : seul un modèle petit ou abstrait est possible. Suggérez de confirmer les lignes à faible confiance (après les avoir vérifiées sur la page d'inventaire) et de photographier plus de pièces étalées. Une nouvelle photo de pièces déjà comptées les compte à nouveau : suggérez de photographier des pièces non encore numérisées, ou de corriger les quantités ensuite avec
set_quantity.
4. Utilisez beaucoup de pièces, puis affinez
- Objectif : utilisez au moins 60 % des pièces utilisables (
usage.target_percent) sauf si l'utilisateur a demandé quelque chose de petit. Utilisable = designable et non à faible confiance, ou confirmé.usage.percentdans chaque résultat de soumission montre où vous en êtes, etusage.unusedliste ce qui reste, du plus abondant au moins abondant. - Étalez le travail. Version 1 : la structure principale (base, corps, les grandes formes). Les versions ultérieures ajoutent des détails par grandes étapes : finition du toit, fenêtres et portes, rambardes, décoration, une plaque de base ou un sol. Il n'y a que 5 resoumissions par modèle, donc chaque cycle doit ajouter beaucoup de choses ; n'en gaspillez pas un pour une seule pièce.
- Chaque résultat : lisez
usageetunusedet demandez quelles pièces inutilisées amélioreraient le sujet. En cas de succès, regardez les deux aperçus et corrigez ce qui semble anormal : un mélange aléatoire de couleurs, des tenons nus sur le dessus, une forme asymétrique alors que le sujet est symétrique, une boîte plate. La section de conseils du guide explique comment. - Arrêtez-vous lorsque le modèle est bon et que l'objectif est atteint, lorsque l'inventaire ne peut rien ajouter de pertinent, ou lorsque les resoumissions sont épuisées. Dites à l'utilisateur l'utilisation finale.
5. Script de repli
Utilisez le script lorsque les outils MCP ne sont pas disponibles. Python 3.8+, uniquement la bibliothèque standard, rien à installer.
python3 <dossier de cette compétence>/scripts/lego.py <commande> [options] [arguments]
Sous Windows, utilisez python ou py -3. Placez les options avant la liste de photos.
Limitez les approbations de l'utilisateur. De nombreux agents demandent à l'utilisateur d'approuver chaque nouvelle commande shell, hôte réseau et écriture en dehors de l'espace de travail. Donc :
- Appelez toujours le script exactement sous cette forme, comme une commande simple : pas de
cd, pas de pipes, pas de&&, pas de préfixe d'environnement, pas de script wrapper. Ainsi, l'utilisateur peut approuver "toujours autoriser" une fois pourpython3 <chemin>/lego.py. Dites-le à l'utilisateur la première fois qu'une approbation apparaît, et mentionnez la configuration MCP (section 1), qui les évite. - Le script a besoin de trois choses, que l'utilisateur peut toutes autoriser une fois : exécuter
lego.py, atteindre l'hôte du serveur indiqué parlego.py whoami, et lire/écrire~/.lego-parts/. - N'exécutez pas la même étape deux fois, ne faites pas de sondage dans une boucle de commandes courtes (utilisez
--wait), et n'appelez pas le serveur avec curl ou votre propre code. - Écrivez
model.ldravec votre outil d'écriture de fichier en aussi peu d'étapes que possible ; évitez une série de scripts jetables.
| Commande | Ce qu'elle fait |
|---|---|
scan [--no-wait] [--wait SECONDS] [--images] PHOTO... | Télécharge 1 à 30 photos (fichiers, dossiers ou motifs glob), attend jusqu'à 480 s (par défaut) les résultats et les enregistre. --no-wait renvoie immédiatement après le téléchargement. |
status [--wait SECONDS] [--images] [TASK_ID...] | Vérifie une fois les tâches en attente (ou celles données), ou continue de sonder jusqu'à SECONDS. Enregistre les tâches terminées. |
parts [--images] | Enregistre les tâches en attente terminées, puis recharge tout l'inventaire (avec les modifications effectuées sur la page d'inventaire ou avec edit_inventory) dans parts.json. |
whoami | Affiche l'ID utilisateur, le serveur et le dossier local. Pas de réseau. |
moc guide [--parts-file PATH] | Enregistre le guide de conception moc/DESIGN_GUIDE.md et les fiches de connecteurs de vos pièces moc/connectors.txt. |
moc submit [--title NAME] [--brief TEXT] [--design design.json] [--moc MOC_ID] [--parts-file PATH] [--no-wait] [--wait SECONDS] MODEL.ldr | Envoie le modèle avec parts.json, attend jusqu'à 300 s (par défaut) la vérification et affiche le résultat, l'utilisation des pièces et, en cas de succès, les liens de prévisualisation. --moc soumet une nouvelle version d'un MOC existant ; --brief est la demande de l'utilisateur. |
moc status [--wait SECONDS] [MOC_ID] | Vérifie une fois les soumissions MOC en attente (ou celle donnée), ou continue de sonder jusqu'à SECONDS. |
mcp-config [--remote] | Affiche le JSON pour la configuration MCP (section 1). La sortie est uniquement ce JSON ; pas de ligne RESULT. |
mcp | Le pont MCP lui-même. L'hôte de l'agent l'exécute ; ne l'exécutez pas vous-même. |
--images télécharge également l'image LDraw de chaque ligne d'inventaire et le recadrage photo dans images/.
- Longues attentes.
scanpeut prendre jusqu'à 8 minutes,moc submitjusqu'à 5. Si votre outil shell expire plus tôt, augmentez son délai d'expiration ou passez un--waitplus petit (par exemple--wait 100) et continuez avecstatus --wait 100/moc status --wait 100. Être arrêté au milieu d'une attente est sans danger : les ID sont d'abord enregistrés danspending.json/moc/pending.json, et toute commande ultérieure, de n'importe quel agent, les collecte. - Adresse du serveur. Intégrée dans le script téléchargé. Si une commande dit qu'aucun serveur n'est configuré, l'utilisateur doit définir
LEGO_PARTS_SERVER(par exemplehttps://lego.groundrl.com, sans/skill/v1).LEGO_PARTS_HOMEchange le dossier local. - Réseau bloqué. Si une commande signale
HTTP 403 ... not from the LEGO serverou ne peut pas atteindre le serveur, un bac à sable, un proxy ou un pare-feu le bloque. Demandez à l'utilisateur d'autoriser l'hôte du serveur (montré parwhoami).
6. Comment les photos sont stockées et utilisées
Les photos sont téléchargées vers le serveur pour identification ; elles ne sont pas stockées sur votre ordinateur. Les pièces reconnues sont stockées dans le fichier local parts.json (dans ~/.lego-parts/). Les recadrages de photos des pièces reconnues peuvent être téléchargés avec --images dans le dossier images/. Le serveur peut stocker les photos temporairement pour la reconnaissance et les supprimer ensuite. Les photos originales sur votre ordinateur ne sont jamais modifiées ou supprimées par le script.
7. Modèle de licence et attribution
Cette compétence et son script associé sont fournis "en l'état" sans garantie. Les modèles MOC créés avec cette compétence sont la propriété intellectuelle de leur créateur (vous ou l'utilisateur). Le serveur de vérification ne revendique aucun droit sur les modèles. Les pièces LEGO sont des marques déposées du groupe LEGO. LDraw est un format de fichier ouvert et une communauté. Cette compétence n'est pas affiliée au groupe LEGO. Les utilisateurs doivent respecter les conditions d'utilisation du serveur de vérification et toutes les lois applicables en matière de droits d'auteur et de propriété intellectuelle.
8. Questions fréquentes
Q : Puis-je utiliser mes propres photos ? R : Oui, les photos de vos propres pièces LEGO détachées sont les meilleures.
Q : Combien de pièces puis-je photographier à la fois ? R : 1 à 30 photos par appel, chaque photo jusqu'à 25 Mo. Pour de meilleurs résultats, éparpillez les pièces et évitez les ombres.
Q : Que se passe-t-il si une pièce n'est pas reconnue ?
R : Elle apparaîtra comme no_pieces dans les notices. Vous pouvez l'ajouter manuellement via edit_inventory ou la page web.
Q : Puis-je modifier l'inventaire ?
R : Oui, via edit_inventory ou la page d'inventaire web.
Q : Combien de modèles puis-je soumettre ? R : Autant que vous le souhaitez, mais chaque modèle a 5 resoumissions. Une fois épuisées, vous ne pouvez plus modifier ce modèle ; vous devez en créer un nouveau.
Q : Puis-je utiliser des pièces non LEGO ? R : Non, seules les pièces LEGO authentiques sont prises en charge. Les pièces non LEGO peuvent ne pas être reconnues ou ne pas fonctionner avec le vérificateur.
Q : Puis-je partager la page publique ? R : Oui, la page est publique et peut être partagée avec n'importe qui.
Q : Le modèle est-il garanti pour tenir dans la vraie vie ? R : Non. La vérification est une simulation ; la construction réelle peut avoir des problèmes de stabilité. Utilisez votre jugement.
Q : Puis-je annuler des modifications ?
R : Oui, utilisez edit_inventory avec op: "undo" ou op: "undo_all".
Q : Que faire si l'outil scan_photos n'est pas disponible ?
R : Utilisez le script de repli (lego.py scan) et les outils MCP inventory, design_guide, etc. pour le reste.