CommunityImagengithub.com

cad-parts

Crea piezas físicas 3D como archivos .stl/.step locales con CadQuery, ejecutándose como subprocesos únicos con watchdog de RAM contra C:\cadquery-venv.

¿Qué es cad-parts?

Esta habilidad permite a un agente de IA (como Claude Code) actuar como un diseñador CAD paramétrico y programático directamente en el sistema local del usuario. Utiliza la biblioteca CadQuery de Python para generar modelos 3D sólidos a partir de scripts, exportándolos a formatos STL (para impresión 3D FDM) y STEP (para intercambio CAD). El punto clave es su robustez: cada script se ejecuta como un subproceso aislado y monitorizado (watchdog) que impide que un fallo de memoria o un bucle infinito derribe toda la máquina, un problema crítico que ocurrió con servidores CAD persistentes. Además, incorpora un estricto control de calidad: verifica que la malla STL sea hermética y tenga una buena orientación para la impresión, y realiza análisis de 'islas' (material que comienza sobre la base de impresión) para evitar fallos de impresión. Está diseñado para sistemas Windows con un entorno virtual de Python dedicado. La habilidad también gestiona un flujo de trabajo de diseño iterativo donde los scripts son el registro autorizado de la pieza, con convenciones para versionado, ediciones en cadena sobre archivos STEP importados, y pruebas de ajuste para hardware de acoplamiento, todo ello documentado en un README por carpeta de pieza.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ColinE0/cad-parts/tree/HEAD/cad-parts

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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. Cuando hooks/require_runner.py está 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.
  2. 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.py junto a adapter_hex.py) con un docstring que nombra exactamente qué cambió y por qué. Cada script lleva una línea STATUS: (Convenciones de script) para que lo "probado" quede escrito, no en la memoria.
  3. Cada exportación pasa por cq_helpers.export_checked. Solo BRep.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.
  4. 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

  1. 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).
  2. 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.
  3. Ejecutarlo:
    & "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\ruta\a\parte.py" -Tail 40
    
    Valores predeterminados: tiempo de espera 300 s, límite 4 GB, sondeo 500 ms, intérprete C:\cadquery-venv\Scripts\python.exe (anular con -Python <ruta> o la variable de entorno CADPARTS_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 ve MemoryError o 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 N imprime solo las últimas N líneas de stdout; el registro completo está siempre en <script>.out.txt junto 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 -TimeoutSec basá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.
  4. 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.txt es el registro de ejecución de la construcción (los README lo citan); <script>.err.txt existe 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").
  5. Verificar antes de informar. Lea el PNG render6 y 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 ejecute h.islands en la orientación en la que se imprimirá la pieza (innegociable 4) e informe de lo que marque junto con la pieza.
  6. 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 con stl_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 en stl/ 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 en stl/, ya que stl/ 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 a archived/ 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, y WHY-ARCHIVED.md en 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-*.md para 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.json en 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, CONGELADO o STATUS: 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 con print("DONE", flush=True).
  • Exportar: h.export_checked(solid, str(OUT / "nombre_pieza"), stl_dir="stl") luego h.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.json nombrando al padre vivo. Escríbalo con h.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 su export_checked. La línea "el que se debe imprimir" del README y current.json deben 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ó sin set_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.diff antes 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; requiere isValid(); escribe .step/.stl (el STL en <dir de basepath>/<stl_dir>/ cuando stl_dir está 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 cuando step=False): cuadro delimitador dentro de max(0.05 mm, 0.5% del tamaño más grande de la pieza) por lado, volumen dentro de agree_tol. Devuelve la malla trimesh. Cada comprobación fallida lanza h.GateError (una subclase de AssertionError, lanzada explícitamente para que python -O no pueda omitirla), lo que detiene la ejecución. Imprime una línea export ok: por archivo escrito, ruta completa con extensión, y una línea export 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 con mesh=(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; tol es la deflexión lineal de la teselación en mm (0.6 para ensamblajes grandes).
  • `render_compare(shape, ref_image_path, p

Skills relacionados