AryaVora621/agentcad

Que fait agentcad ?

1. La règle fondamentale

Ne signalez jamais une dimension, un jeu ou une validation PASS que vous n'avez pas mesuré sur la géométrie construite avec agentcad. Les paramètres sont une intention, pas une preuve. Une valeur que vous avez tapée dans model.py vous indique ce que vous avez demandé, pas ce qui existe.

2. La boucle

agentcad new my-part --template blank      # ou bracket, box-with-lid
# éditer my-part/model.py et my-part/agentcad.toml
agentcad check my-part --json              # construit, puis mesure
agentcad render my-part                    # build/renders/ : un PNG par vue plus sheet.png
agentcad view my-part                      # visualisation en direct, pour l'humain

1. Écrivez d'abord les vérifications correspondant au cahier des charges ou pendant la modélisation (section 3).
2. Lancez agentcad check --json. Lisez chaque FAIL : summary, measured, limit, where.
3. Corrigez la géométrie à l'endroit nommé par where. Relancez. Ne modifiez pas une limite pour faire disparaître un FAIL à moins que l'exigence elle-même n'ait changé.
4. Lancez agentcad render et ouvrez sheet.png avec un outil capable d'afficher des images. Regardez-la avant de dire que ça a l'air correct. Les rendus trouvent les erreurs grossières (fonctionnalité manquante, mauvais côté) ; ils ne prouvent jamais l'épaisseur, le jeu ou le chevauchement.
5. Répétez jusqu'à ce que toutes les contraintes soient satisfaites. Relancez agentcad check après la dernière modification.

La contrainte overhang ignore les faces sur le plateau et les faces descendantes centrées en dessous de first_layer_mm (par défaut 0.3), donc un chanfrein de bord inférieur n'est pas compté ; la zone exemptée est signalée comme first_layer_area_mm2.

Utilisez --only ID,ID pour relancer des contraintes sélectionnées et --no-build seulement lorsque build/ est à jour.

3. Transformez les exigences en vérifications

Chaque exigence fonctionnelle du cahier des charges devient une vérification dans checks(ctx). Les sondes solides (section 4) représentent l'objet qui s'emboîte. Tous les noms ci-dessous correspondent à l'API réelle.

Un ajustement devient une mesure de jeu :

def checks(ctx):
    play = ctx.play("lid", "box", direction=(1, 0, 0), max_mm=2.0)
    ctx.expect("lid_side_play", play if play is not None else 2.0, min=0.15, max=0.4, part="lid")

« Le couvercle se retire » devient un test de glissement :

    sweep = ctx.slide("lid", "box", direction=(0, 0, 1), distance=15.0, steps=40)
    ctx.expect("lid_lifts_free", max(s["overlap_mm3"] for s in sweep), max=0.01, unit="mm3", part="lid")

« Une vis M4 traverse » devient un cylindre sonde qui ne doit pas entrer en collision et doit être proche de la paroi :

    import cadquery as cq
    screw = cq.Workplane("XY").circle(2.0).extrude(30).translate((10, 0, -5))  # corps de 4.0 mm
    ctx.expect("screw_interference", ctx.interference("bracket", screw), max=0.01, unit="mm3", part="bracket")
    ctx.expect("screw_wall_gap", ctx.distance("bracket", screw), min=0.0, max=0.5, part="bracket")

La bande de distance prouve que la vis est réellement près du trou, pas à 14 mm avec un chevauchement nul.

« Tient sur l'imprimante » est la contrainte intégrée bed_fit : définissez [printer] dans agentcad.toml avec la machine réelle (profile ou bed = [X, Y, Z]). « Parois assez solides » est min_wall_mm sous [checks].

4. Sondes solides

Construisez le substitut de l'objet qui s'emboîte à partir de l'exigence, jamais à partir des propres paramètres du modèle. Une vis M4 est un cylindre de 4.0 mm. Une bille de 54 mm est une sphère de 54 mm. Un câble est un cylindre le long de son tracé. Une main est une boîte à la taille de la main. Si la sonde lit la même variable que celle utilisée pour construire le trou, la vérification ne peut jamais échouer.

Les sondes sont des objets cq.Workplane ou cq.Shape déjà dans le repère d'utilisation. Placez-les avec .translate et passez-les partout où un nom de pièce est accepté (ctx.interference, ctx.distance, ctx.slide, ctx.play).

5. Prouvez qu'une vérification peut échouer

Une vérification que vous n'avez jamais vue échouer est une supposition. Après l'avoir écrite :

1. Cassez la géométrie (ou la sonde) d'une manière qui doit la déclencher : déplacez le trou de 3 mm, réduisez le jeu à 0, agrandissez la sonde de 1 mm.
2. Lancez agentcad check. Vérifiez que cette vérification échoue (FAIL), sur sa propre assertion, avec le nombre attendu.
3. Restaurez la géométrie et vérifiez le PASS.

Si elle passe alors qu'elle est cassée, la vérification mesure la mauvaise chose. Corrigez la vérification avant de faire confiance à tout autre résultat.

6. Repères

Repère	Signification	Utilisé par
model	la pièce dans ses propres coordonnées	build/step/<part>.step
use	la pose assemblée, Part.use	interference, sondes, ctx.slide, ctx.play, build/assembly/
print	sur le plateau, z = 0 en bas, XY centré, rotation Part.print	bed_fit, bed_contact, overhang, min_wall, watertight, build/stl/

Définissez Part.print = Pose(rx=180) (ou toute autre rotation) pour que chaque pièce s'imprime sans support et avec les couches dans l'axe de la charge. Choisissez d'abord la face sur le plateau, puis vérifiez overhang dans ce repère. Les pièces achetées reçoivent printed=False. Modélisez les pièces dans un repère local pratique et placez-les avec Part.use.

7. Rapports, codes de sortie, diff et fichiers isolés

Codes de sortie : 0 tout passe (WARN autorisé), 1 au moins un FAIL, 2 erreur d'utilisation ou de configuration (y compris les clés inconnues dans agentcad.toml), 3 le code du modèle a levé une exception ou n'a produit aucun solide valide. Traitez 2 et 3 comme « aucun résultat », pas comme un succès.

agentcad check --json imprime un document avec "schema": "agentcad.report/1" et une liste checks. Chaque vérification a id, part, status (PASS, WARN, FAIL, SKIP, ERROR), summary, measured, limit, where. Une vérification de projet qui lève une exception devient ERROR et l'exécution continue.

Comparez les constructions avec agentcad diff OLD NEW (deux fichiers manifest.json ou deux dossiers de construction ; volume, boîte englobante, ensemble de pièces) pour détecter les modifications involontaires après une modification. Copiez build/manifest.json de côté avant un changement risqué.

Pour réviser un CAO que vous n'avez pas écrit, mesurez les fichiers directement :

agentcad measure part.step --json
agentcad interfere a.stl b.stl --json
agentcad overhang part.stl --max-deg 45 --json
agentcad wall part.stl --thin 1.2 --json
agentcad fit part.stl --printer generic-220 --json

8. Quand s'arrêter

Arrêtez-vous uniquement lorsque toutes ces conditions sont remplies :

• toutes les contraintes passent dans la dernière exécution de agentcad check, effectuée après votre dernière modification ;
• chaque exigence du cahier des charges a une vérification, et vous avez vu chacune échouer (section 5) ;
• vous avez regardé les rendus ;
• votre résumé cite les nombres mesurés avec leurs unités (jeu, épaisseur de paroi p1, zone de porte-à-faux, adaptation au plateau) ;
• vous indiquez le nombre de pièces et tout ce qui reste à vérifier sur banc (force d'encliquetage, tolérance sur l'imprimante réelle, comportement du matériau).

9. Anti-patrons et les échecs qu'ils ont causés

• Lire les paramètres au lieu de la forme construite. Un ouvrier a rapporté un PASS sur un jeu de queue d'aronde coulissante alors que la pièce se trouvait à 14 mm en dehors de sa rainure, car sa vérification lisait les paramètres.
• Ignorer le repère d'impression. Une plaque a été modélisée pour s'imprimer face vers le bas avec environ 6100 mm2 de plafond non supporté, car le porte-à-faux n'a jamais été vérifié dans l'orientation d'impression.
• Ignorer les interférences par paires. Deux pièces se chevauchaient de 50 cm3 dans l'assemblage, car personne n'avait exécuté d'interférence dans la pose d'utilisation.
• Tolérance d'exportation grossière. Une exportation STL grossière d'une pièce de révolution a produit une facette qui a découpé une paroi de 2.0 mm à 1.5 mm. Correction : tolérance d'exportation 0.02 mm, tolérance angulaire 0.05 rad (les valeurs par défaut dans [export]).
• Texte non mesuré. Un document de conception indiquait un diamètre extérieur de 29 à 33.5 mm alors que le modèle mesurait 19 mm. Mesurez chaque nombre que vous écrivez dans le texte.
• Validation uniquement sur « ça se construit ». Une reconstruction a passé sa seule contrainte alors que tous les canaux internes étaient scellés et qu'un bec était plein. Tracez le chemin fonctionnel : balayez une sonde le long de l'eau, du câble ou de l'air.
• Vérifier uniquement l'ensemble. Un assemblage était stable dans son ensemble tandis qu'un seul étage desserré basculait à 6 degrés. Vérifiez chaque sous-empilement desserré.
• Faire confiance à un rapport obsolète. Un rapport de contrainte était obsolète car la construction a échoué après l'écriture de l'ancien rapport. agentcad construit de manière atomique, mais comparez quand même les horodatages du rapport avec votre dernière modification et relancez après chaque modification.
• Faire confiance à l'image. Un rendu propre cachait tout ce qui précède.

10. Références

• references/design-for-printing.md : lisez avant de choisir l'orientation, l'épaisseur de paroi, les ajustements, les trous de vis ou les clips pour une pièce FDM.
• references/cadquery-patterns.md : lisez lorsqu'une opération CadQuery échoue, retourne une forme inattendue, ou si vous avez besoin de sélecteurs, de coques, de congés ou de sondes solides.
• references/verification-playbook.md : lisez lorsque vous planifiez des vérifications pour un cahier des charges, testez un mouvement ou une fonction, ou révisez le CAO d'un autre agent.