AryaVora621/agentcad

¿Qué hace agentcad?

1. La regla fundamental

Nunca informes una dimensión, holgura o resultado de PASO que no hayas medido de la geometría construida con agentcad. Los parámetros son la intención, no la evidencia. Un valor que escribiste en model.py te dice lo que pediste, no lo que existe.

2. El bucle

agentcad new my-part --template blank      # o bracket, box-with-lid
# editar my-part/model.py y my-part/agentcad.toml
agentcad check my-part --json              # construye, luego mide
agentcad render my-part                    # build/renders/: un PNG por vista más sheet.png
agentcad view my-part                      # visor en vivo, para el humano

1. Escribe primero las comprobaciones (sección 3) para el objetivo o mientras modelas.
2. Ejecuta agentcad check --json. Lee cada FALLO: summary, measured, limit, where.
3. Corrige la geometría en la ubicación que nombra where. Vuelve a ejecutar. No modifiques un límite para eliminar un FALLO a menos que el requisito en sí haya cambiado.
4. Ejecuta agentcad render y abre sheet.png con una herramienta que permita ver imágenes. Míralo antes de decir que se ve bien. Los renders detectan errores graves (característica faltante, lado equivocado); nunca prueban espesor, holgura o superposición.
5. Repite hasta que todas las comprobaciones pasen. Vuelve a ejecutar agentcad check después de la última edición.

La comprobación overhang ignora las caras sobre la cama y las caras hacia abajo centradas por debajo de first_layer_mm (por defecto 0.3), por lo que un chaflán en el borde inferior no cuenta; el área exenta se informa como first_layer_area_mm2.

Usa --only ID,ID para volver a ejecutar comprobaciones seleccionadas y --no-build solo cuando build/ esté actualizado.

3. Convierte requisitos en comprobaciones

Cada requisito funcional del objetivo se convierte en una comprobación en checks(ctx). Los sólidos de sonda (sección 4) representan la pieza complementaria. Todos los nombres siguientes son la API real.

Un ajuste se convierte en una medición de juego:

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")

"La tapa se desprende" se convierte en una prueba de deslizamiento:

    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")

"Un tornillo M4 pasa" se convierte en un cilindro de sonda que no debe colisionar y debe estar cerca de la pared:

    import cadquery as cq
    screw = cq.Workplane("XY").circle(2.0).extrude(30).translate((10, 0, -5))  # vástago 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 banda de distancia demuestra que el tornillo está realmente cerca del agujero, no a 14 mm de distancia con superposición cero.

"Cabe en la impresora" es la comprobación incorporada bed_fit: configura [printer] en agentcad.toml con la máquina real (profile o bed = [X, Y, Z]). "Paredes suficientemente resistentes" es min_wall_mm bajo [checks].

4. Sólidos de sonda

Construye el sustituto de la pieza complementaria a partir del requisito, nunca a partir de los parámetros propios del modelo. Un tornillo M4 es un cilindro de 4.0 mm. Una bola de 54 mm es una esfera de 54 mm. Un cable es un cilindro a lo largo de su recorrido. Una mano es una caja del tamaño de la mano. Si la sonda lee la misma variable que se usó para construir el agujero, la comprobación nunca puede fallar.

Las sondas son objetos cq.Workplane o cq.Shape ya en el marco de uso. Colócalas con .translate y pásalas donde sea que se acepte un nombre de pieza (ctx.interference, ctx.distance, ctx.slide, ctx.play).

5. Demuestra que una comprobación puede fallar

Una comprobación que nunca has visto fallar es una suposición. Después de escribirla:

1. Rompe la geometría (o la sonda) de manera que deba activarla: desplaza el agujero 3 mm, reduce la holgura a 0, agranda la sonda 1 mm.
2. Ejecuta agentcad check. Confirma que esta comprobación FALLA, con su propia aserción, con el número que esperabas.
3. Restaura la geometría y confirma que PASA.

Si pasa mientras está rota, la comprobación mide lo incorrecto. Corrige la comprobación antes de confiar en cualquier otro resultado.

6. Marcos de referencia

Marco	Significado	Usado por
modelo	la pieza en sus propias coordenadas	build/step/<part>.step
uso	la pose ensamblada, Part.use	interference, sondas, ctx.slide, ctx.play, build/assembly/
impresión	sobre la cama, z = 0 en la parte inferior, XY centrado, rotación Part.print	bed_fit, bed_contact, overhang, min_wall, watertight, build/stl/

Configura Part.print = Pose(rx=180) (o cualquier rotación) para que cada pieza se imprima sin soportes y con las capas a lo largo de la carga. Elige primero la cara sobre la cama, luego verifica overhang en ese marco. Las piezas compradas reciben printed=False. Modela las piezas en un marco local conveniente y colócalas con Part.use.

7. Informes, códigos de salida, diferencias y archivos sueltos

Códigos de salida: 0 todo pasa (ADVERTENCIA permitido), 1 al menos un FALLO, 2 error de uso o configuración (incluyendo claves desconocidas en agentcad.toml), 3 el código del modelo generó una excepción o no produjo un sólido válido. Trata 2 y 3 como "sin resultado", no como un pase.

agentcad check --json imprime un documento con "schema": "agentcad.report/1" y una lista checks. Cada comprobación tiene id, part, status (PASA, ADVERTENCIA, FALLA, OMITIDO, ERROR), summary, measured, limit, where. Una comprobación de proyecto que genera una excepción se convierte en ERROR y la ejecución continúa.

Compara construcciones con agentcad diff OLD NEW (dos archivos manifest.json o dos carpetas de construcción; volumen, caja delimitadora, conjunto de piezas) para detectar cambios no deseados después de una edición. Copia build/manifest.json antes de un cambio arriesgado.

Para revisar CAD que no escribiste, mide los archivos directamente:

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. Cuándo detenerse

Detente solo cuando se cumplan todas estas condiciones:

• todas las comprobaciones pasan en la última ejecución de agentcad check, ejecutada después de tu última edición;
• cada requisito del objetivo tiene una comprobación, y has visto fallar cada una (sección 5);
• has mirado los renders;
• tu resumen cita los números medidos con unidades (holgura, pared p1, área de voladizo, ajuste a la cama);
• indicas el número de piezas y cualquier cosa que quede como verificación manual (fuerza de encaje, tolerancia de la impresora real, comportamiento del material).

9. Antipatrones y los fallos que causaron

• Leer parámetros en lugar de la forma construida. Un trabajador informó PASA en una holgura de cola de milano deslizante mientras la pieza estaba 14 mm fuera de su ranura, porque su comprobación leía los parámetros.
• Saltarse el marco de impresión. Una placa se modeló para imprimirse boca abajo con aproximadamente 6100 mm2 de techo sin soporte, porque nunca se verificó el voladizo en la orientación de impresión.
• Saltarse la interferencia por pares. Dos piezas se superponían en 50 cm3 en el ensamblaje, porque nadie ejecutó interferencia en la pose de uso.
• Tolerancia de exportación gruesa. Una exportación STL gruesa de una pieza revuelta produjo una faceta que cortó una pared de 2.0 mm a 1.5 mm. Solución: tolerancia de exportación 0.02 mm, tolerancia angular 0.05 rad (los valores predeterminados en [export]).
• Texto sin medir. Un documento de diseño declaró un diámetro exterior de 29 a 33.5 mm mientras que el modelo medía 19 mm. Mide cada número que escribas en el texto.
• Comprobar solo con "se construye". Una reconstrucción pasó su única comprobación mientras todos los canales internos estaban sellados y un pico era sólido. Traza la ruta funcional: barre una sonda a lo largo de la ruta del agua, cable o aire.
• Comprobar solo el conjunto completo. Un ensamblaje era estable en general mientras que una sola etapa suelta se inclinaba a 6 grados. Verifica cada sub-pila suelta.
• Confiar en un informe desactualizado. Un informe de comprobación estaba desactualizado porque la construcción falló después de que se escribiera el informe anterior. agentcad construye atómicamente, pero aún así compara las marcas de tiempo del informe con tu última edición y vuelve a ejecutar después de cada edición.
• Confiar en la imagen. Un render limpio ocultó todo lo anterior.

10. Referencias

• references/design-for-printing.md: léelo antes de elegir orientación, espesor de pared, ajustes, agujeros para tornillos o características de encaje para una pieza FDM.
• references/cadquery-patterns.md: léelo cuando una operación de CadQuery falle, devuelva una forma inesperada, o necesites selectores, cáscaras, redondeos o sólidos de sonda.
• references/verification-playbook.md: léelo al planificar comprobaciones para un objetivo, probar movimiento o función, o revisar el CAD de otro agente.