Copyright 2026 Colin Ezra Wilder. Licenciado bajo la Licencia Apache, Versión 2.0 (los archivos LICENSE y NOTICE que acompañan a esta habilidad).
Piezas CAD mediante subproceso de CadQuery
CAD local y programable: un script de Python construye el sólido, un subproceso monitorizado (watchdog) lo ejecuta, cq_helpers controla la exportación, y un PNG de 6 vistas prueba la forma. El usuario imprime los resultados en impresoras FDM, por lo que cada STL que salga de aquí debe poder rebanarse limpiamente.
Innegociables
- Solo subproceso único. El 14/07/2026, un proceso de servidor CAD de larga duración provocó un fallo de memoria (OOM) que estropeó toda la máquina a medida que los modelos importados se acumulaban entre llamadas (una repetición del 14/11/2026 aclaró que la escala no uniforme, inicialmente culpada, no era la causa; ver problemas conocidos). Un subproceso que falla pierde una ejecución; una operación en proceso que falla tumba el equipo. Ejecute cada construcción a través de
scripts/run_watchdogged.ps1, y también cualquier otro script del entorno virtual (sondas de dibujo, comprobaciones de malla), ya sea de CadQuery o no. Cuandohooks/require_runner.pyestá registrado como un hook de Claude Code (README), una llamada directa al Python del entorno virtual es rechazada mostrando el comando del ejecutor que se debe usar en su lugar: ese rechazo es la regla funcionando, no un error que deba evitarse. - Nunca editar un archivo de pieza probado. Un script cuya impresión ha sido probada y funciona está congelado. Las variantes obtienen un NUEVO archivo (p. ej.,
adapter_hex_trim.pyjunto aadapter_hex.py) con un docstring que nombra exactamente qué cambió y por qué. Cada script lleva una líneaSTATUS:(Convenciones de script) para que lo "probado" quede escrito, no en la memoria. - Cada exportación pasa por
cq_helpers.export_checked. SoloBRep.isValid()no garantiza una malla limpia; los rebanadores rechazan STLs no herméticos que pasan las comprobaciones de validez. Esta compuerta ya ha detectado una pieza defectuosa enviada. - Toda pieza que se vaya a imprimir recibe una comprobación de 'islas' en su orientación de IMPRESIÓN.
h.islands(solid, up="+z")(o el eje vertical previsto) encuentra material que comienza por encima de la cama y se une a las capas de la pieza más tarde, por lo que se apoya en soportes durante todo el recorrido. Una isla ALTA es un problema de diseño que debe corregirse o consultarse al usuario antes de cualquier plan de impresión, nunca "los soportes lo manejarán". El 09/10/2026, un pilar del hueco de la rueda de un chasis robótico era uno (36.8 mm de alto sobre soportes de árbol, 6.52 de grosor) y se rompió durante una impresión de 22 h en tres colores, después de que todas las comprobaciones de ajuste hubieran pasado. Las comprobaciones de ajuste preguntan "¿encaja?"; esta pregunta "¿se puede construir de abajo arriba?".
Flujo de trabajo
- Confirmar lo que la instrucción deja abierto. Una especificación completa ("12 mm de alto, 9 DE, 4.3 de agujero") no necesita compuerta. Cuando una elección importante está abierta (qué agujeros, desde dónde se mide "15 mm de saliente", qué se monta, qué herraje, qué carpeta), exprese su interpretación como una propuesta breve y pregunte al usuario antes de construir. Las imágenes de referencia siempre requieren esta compuerta (ver más abajo).
- Escribir el script. Piezas entregables: el script reside junto a sus salidas en la carpeta de la pieza (el script ES el registro de la pieza; ver "Dónde viven las piezas"). Sondas y experimentos: una carpeta de pruebas.
- Ejecutarlo:
Valores predeterminados: tiempo de espera 300 s, límite 4 GB, sondeo 500 ms, intérprete& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\ruta\a\parte.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(anular con-Python <ruta>o la variable de entornoCADPARTS_PYTHON). El límite se aplica a la memoria confirmada de todo el árbol de procesos, impuesto por el kernel a través de un objeto de trabajo de Windows: una asignación que lo supere es rechazada (el script veMemoryErroro un fallo de asignación de OCCT) y el ejecutor mata el árbol, código de salida 137. Importar solo CadQuery ya compromete unos 0.7 GB, por lo que nunca se debe limitar por debajo de ~1 GB. Aumente los límites solo deliberadamente para un trabajo pesado conocido, nunca como primera respuesta a una muerte; una muerte por watchdog suele indicar un error de geometría (ver problemas conocidos), no un límite pequeño.-Tail Nimprime solo las últimas N líneas de stdout; el registro completo está siempre en<script>.out.txtjunto al script. Úselo en scripts que registren mucho, para que el registro completo no ocupe espacio en el contexto. La línea de resumen informa del tiempo real: elija-TimeoutSecbasándose en eso, no por estimación. A través de una herramienta de PowerShell, establezca el tiempo de espera de la propia herramienta por encima de-TimeoutSec. Si la herramienta mata al ejecutor primero, el objeto de trabajo se lleva la construcción consigo: la ejecución se pierde, nunca queda huérfana. - Leer la salida. El ejecutor imprime el stdout del script, cualquier stderr, el tiempo real y el pico de memoria confirmada del árbol. Exija el centinela
DONE; una ejecución sin él no terminó. Salida 137 = muerte por watchdog (la última línea indica tiempo de espera o límite); 3 = el watchdog no pudo armarse (o falta el intérprete), por lo que el script nunca se ejecutó.<script>.out.txtes el registro de ejecución de la construcción (los README lo citan);<script>.err.txtexiste solo cuando stderr tenía contenido. Ante una muerte por límite, haga un triaje antes de tocar cualquier límite (problemas conocidos: "Triaje de una muerte por límite"). - Verificar antes de informar. Lea el PNG
render6y compruebe la silueta con respecto a la intención. Informe las dimensiones del bbox/volumen impreso por el script, no de memoria. Compruebe cada característica MIDIENDO el sólido construido (describe, bboxes de caras, una losa intersecada a través de la pared); una aserción que compara una constante de entrada consigo misma no prueba nada. Luego ejecuteh.islandsen la orientación en la que se imprimirá la pieza (innegociable 4) e informe de lo que marque junto con la pieza. - Registrar. Actualice el README de la carpeta (qué archivo imprimir), establezca la línea STATUS y anote cualquier cosa aprendida que la próxima sesión necesite (ver "Registro").
Dónde viven las piezas y qué contiene una carpeta de pieza
Raíz de piezas: PREGUNTAR (si todavía pone PREGUNTAR, pregunte al usuario dónde deben vivir las piezas, p. ej., C:\Users\<nombre>\Documents\cad-parts, y ofrezca escribirlo aquí). Cada pieza tiene su propia carpeta bajo esa raíz; agrupe piezas relacionadas en subcarpetas (las piezas del chasis de un robot juntas, las impresiones únicas juntas). Si no está claro el hogar de una pieza, pregunte; no adivine.
Una carpeta de pieza contiene:
- El/los script(s), STEPs y renders en el nivel superior; cada STL en una subcarpeta
stl/(exportar constl_dir="stl"). En una carpeta de cadena (ver "Ediciones en cadena") el nivel superior contiene UNA versión viva de la pieza: si hay un STL enstl/para la pieza del nivel superior, ese es el que se debe imprimir. Un STL roto que alguien entrega permanece en el nivel superior, nunca enstl/, ya questl/significa imprimible. README.md: qué es la pieza, el linaje ("en uso: v12, más reciente: prueba v16") y una línea explícita "el que se debe imprimir". Nada se mueve aarchived/sin la aprobación del usuario. Aún no hay README: escriba uno. Los tamaños hermanos en lugar de versiones (un separador de 11 mm y otro de 14 mm) tienen una línea de impresión cada uno.archived/: versiones superadas, una carpeta por versión o paso de cadena, cada una con su script, STEP, STL, renders y registro de ejecución juntos, yWHY-ARCHIVED.mden la raíz del archivo. Los pasos de cadena archivados no se vuelven a ejecutar en su lugar (sus rutas de origen asumen la disposición anterior); primero copie uno de vuelta al nivel superior.- Marcadores
DEAD-*.mdpara características que nunca deben volver (p. ej.,CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md: nervaduras de apriete que destruyeron dos motores). Lea cualquier archivo DEAD en la carpeta antes de tocar la pieza. - Un plan de impresión, si está escrito, vinculado a un nombre de STL; márquelo como obsoleto cuando la pieza avance.
<script>.out.txt, el registro de ejecución de la construcción.current.jsonen carpetas de cadena (siguientes secciones).
Convenciones de script
- Docstring del módulo: qué es la pieza, por qué existe, cómo ejecutarla y una línea
STATUS:(hágalo un docstring raw,r""", cuando contenga rutas de Windows: CPython 3.14 advierte sobre escapes\c,\s):STATUS: impreso 2026-09-08, ajustado, CONGELADOoSTATUS: prueba, sin imprimir. CONGELADO es lo que el innegociable 2 entiende por probado; actualice la línea cuando llegue un resultado de impresión. - El docstring contiene el delta de ESTA versión y su razonamiento. El linaje y qué archivo imprimir pertenecen al README. No pegue las notas de la versión anterior (un script que lo hizo alcanzó 50 KB).
- Los números de versión avanzan en décimas: cada nueva construcción de una línea de pieza versionada es +0.1,
v22->v22.1...v22.9->v23, nunca saltando hacia adelante a menos que el usuario lo indique. Los archivos escriben el punto como un guión bajo (chassis_v22_1.py,.step,stl/..._v22_1.stl) porque los scripts posteriores importan versiones anteriores como módulos (import chassis_v12 as V12) y un nombre de módulo con puntos no se puede importar; los docstrings y READMEs dicen "v22.1". Los archivos existentes mantienen sus números. Los pasos de cadena (step8,step11e) mantienen su propio esquema, y cualquier sello de versión grabado en una pieza sigue siendo el recuento del usuario. - TODAS las dimensiones como constantes con nombre en la parte superior, en mm, un solo lugar para editar.
import cq_helpers as h(instalado en site-packages del entorno virtual).- Decir QUÉ mano cada vez que escriba izquierda o derecha: la izquierda del robot o pieza (como si fueras tú, mirando hacia adelante) o la izquierda del espectador mirando su frente. Son opuestas; una "izquierda" a secas en un docstring, README o mensaje es un defecto. Escriba la convención de ejes (hacia dónde es el frente, +x, arriba) en la parte superior de cualquier proyecto de múltiples piezas y manténgala.
- Afirmar
solid.isValid()y afirmar que el cuadro delimitador coincide con las dimensiones previstas; también proteja las fórmulas con aserciones (p. ej., la profundidad del agujero debe superar la protuberancia del eje), para que una mala edición de parámetros falle de forma ruidosa en lugar de imprimir chatarra. - El herraje de acoplamiento se modela como sólidos y se comprueba con
h.interference. Tome las dimensiones de una hoja de datos o un calibre y marque el comentario de cada constante como "medido" o "asumido", con el origen del número. Valores predeterminados de fijación cuando no se sabe nada mejor: cabeza cilíndrica M3 5.5 x 3.0, holgura M3 D3.30, taladro piloto M2 para autorroscante en PLA D1.7 a 1.8. Otros sujetadores estándar: rosca ISO 261 y holgura ISO 273, marcados como asumidos. print(..., flush=True)para progreso; terminar conprint("DONE", flush=True).- Exportar:
h.export_checked(solid, str(OUT / "nombre_pieza"), stl_dir="stl")luegoh.render6(solid, str(OUT / "nombre_pieza.png")). - Una pieza por archivo exportado; las piezas se imprimen individualmente.
Ediciones en cadena sobre un STEP importado
Muchas piezas son un delta sobre un STEP padre importado (una placa base alcanzó el paso 10c a través de nueve deltas de este tipo). Reglas:
- Nombrar los pasos
step<N>, con una letra de sufijo para una rama (step7c) o un rebase (step5r); la línea SRC del docstring nombra el archivo padre. Un rebase tiene una nota WHY en la carpeta. - La carpeta de cadena lleva
current.jsonnombrando al padre vivo. Escríbalo conh.set_current(carpeta, "parte.step", note="2026-09-22: ...")cuando el usuario nombre la pieza a imprimir, o desde el script del paso justo después de suexport_checked. La línea "el que se debe imprimir" del README ycurrent.jsondeben coincidir. - Los dependientes importan al padre con
plate = h.import_current(PLATE_DIR, pin="base_plate_step10c"), nunca con un nombre de archivo codificado. Cuando la cadena se mueve, la construcción anclada FALLA nombrando ambas piezas; vuelva a ejecutar cada comprobación de ajuste contra el nuevo padre, luego mueva el anclaje. La comprobación de huella digital también falla si el STEP se reemplazó sinset_current. (Por qué: los dependientes dejaron de ejecutarse cuando su STEP padre desapareció, y uno pasó todas las comprobaciones anclado a un padre antiguo mientras uno más nuevo era la pieza a imprimir.) - Probar el delta:
h.diffantes y después, y afirmar que todo fuera del cuadro de edición no ha cambiado. - Una pieza dependiente NUEVA (un soporte atornillado a una placa) afirma al menos: asentado (sin espacio en la cara de acoplamiento, sin superposición), sus ejes de agujero en los de la pieza padre, holgura del vástago en ambos agujeros, acceso claro de cabeza y herramienta (una columna de llave hexagonal sobre cada cabeza), y cualquier característica del padre que no deba bloquear sigue libre. Lea los agujeros del padre desde su B-rep, filtrando las caras cilíndricas por dirección de eje, ya que un filete también es una cara cilíndrica.
- Variante de solo parámetros de un script (la copia de 14 mm de un separador de 11 mm): probar "nada más cambió" con un diff de texto de los dos scripts (solo el docstring, NOMBRE y el parámetro difieren) más
describe()contra el volumen analítico. No es necesaria una sonda de diff de geometría. - Una escala no uniforme convierte cada cara de un B-rep importado en una B-spline (problemas conocidos): los desplazamientos pueden fallar después de ella. Reconstruir, o escalar la malla.
API de cq_helpers (site-packages del entorno virtual)
export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015): acepta Workplane o Shape; requiereisValid(); escribe.step/.stl(el STL en<dir de basepath>/<stl_dir>/cuandostl_direstá configurado, aquí siempre"stl"); comprobación de trimesh hermético + orientación en el STL con reparación automática (merge_vertices dígitos 5 luego 4, fill_holes, fix_normals, aceptado solo si la deriva de volumen < 0.5%); luego el STL debe coincidir con el STEP leído del disco (o con shape cuandostep=False): cuadro delimitador dentro de max(0.05 mm, 0.5% del tamaño más grande de la pieza) por lado, volumen dentro deagree_tol. Devuelve la malla trimesh. Cada comprobación fallida lanzah.GateError(una subclase de AssertionError, lanzada explícitamente para quepython -Ono pueda omitirla), lo que detiene la ejecución. Imprime una líneaexport ok:por archivo escrito, ruta completa con extensión, y una líneaexport check:con los números de concordancia. La reparación automática cierra las grietas de teselación capilares en un B-rep válido; NO cerrará una cara faltante (ver "Reparación de una malla que el usuario entrega"). El STL se mallifica en una copia nueva (la forma permanece sin mallificar), por lo que una malla fijada en la forma primero se descarta: fíjela conmesh=(deflexión, angular)(mm absolutos, rad; las piezas de proveedor con caras estrechas necesitaron(0.05, 0.2), problemas conocidos).render6(shape, png_path, color="#b25563", tol=0.3): 6 vistas sombreadas canónicas (frente/atrás/izquierda/derecha/superior/frente-3/4) en un PNG. Un renderizado fuera de pantalla VTK con búfer de profundidad (la ordenación de pintor de matplotlib falsificaba la transparencia en ensamblajes, problemas conocidos), proyección paralela, cada vista encuadrada en la pieza; un Workplane renderiza cada Shape en su pila;toles la deflexión lineal de la teselación en mm (0.6 para ensamblajes grandes).- `render_compare(shape, ref_image_path, p