CommunityImagemgithub.com

Peças CAD via subprocesso CadQuery

Autor de peças físicas 3D como arquivos .stl/.step locais com CadQuery, executado como subprocessos únicos com watchdog de RAM em C:\cadquery-venv. Use quando o usuário quiser projetar, modelar, criar, redimensionar, aparar ou remixar uma peça imprimível (adaptadores, espaçadores, suportes, montagens, invólucros, teclas, robô ou peças de chassi), pedir um arquivo STL ou STEP, quiser alterar uma dimensão em um script de peça existente, renderizar, medir ou verificar uma peça, reparar um STL quebrado ou verificar novamente uma peça em relação a uma peça pai que mudou, mesmo que o usuário nunca diga "CadQuery" ou "CAD". NÃO para projeto de PCB ou configurações de fatiamento/impressão.

O que é Peças CAD via subprocesso CadQuery?

Este skill cria peças físicas 3D paramétricas no formato STL/STEP usando o CadQuery, executado em subprocessos segregados com monitoramento de memória RAM via watchdog. Ele é projetado para o fluxo de trabalho de engenharia reversa e design de peças para impressão 3D FDM, garantindo que cada STL exportado seja estanque e imprimível. O skill suporta plataformas como Claude Code e similares que executam scripts Python no Windows, usando um ambiente virtual dedicado em `C:\cadquery-venv`. Ele implementa regras rigorosas: execução única por subprocesso (evitando vazamentos de memória que derrubariam todo o sistema), verificação de ilhas em orientação de impressão, e validação combinada de malha (watertight + baixa deriva de volume). Além disso, gerencia edições encadeadas em arquivos STEP importados, rastreando versões e garantindo que peças dependentes sejam atualizadas quando o pai muda. O skill também inclui uma ferramenta de renderização de 6 vistas para inspeção visual e uma API de helpers (cq_helpers) para exportação, diferença geométrica e comparação de malhas.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Peças CAD via subprocesso CadQuery faz?

CAD local e programável: um script Python constrói o sólido, um subprocesso monitorado o executa, cq_helpers bloqueia a exportação, e um PNG de 6 vistas prova a forma. O usuário imprime os resultados em impressoras FDM, então todo STL que sai daqui deve fatiar limpo.

Não negociáveis

  1. Subprocesso único apenas. Em 2026-07-14 um servidor CAD de longa duração causou OOM e crash em toda a máquina, pois modelos importados acumulavam entre chamadas (uma reprodução em 2026-11-14 limpou a escala não uniforme antes culpada; veja pegadinhas). Um subprocesso quebrado perde uma execução; um processo integrado quebrado derruba a máquina. Execute toda construção através de scripts/run_watchdogged.ps1, e todos os outros scripts do venv também (sondas de desenho, verificações de malha), CadQuery ou não. Quando hooks/require_runner.py está registrado como hook do Claude Code (README), uma chamada direta ao Python do venv é recusada com o comando runner a ser usado: essa recusa é a regra funcionando, não um erro a ser contornado.
  2. Nunca edite um arquivo de peça comprovado. Um script cuja impressão foi testada e funciona está congelado. Variantes ganham um NOVO arquivo (ex. adapter_hex_trim.py ao lado de adapter_hex.py) com um docstring nomeando exatamente o que mudou e por quê. Todo script carrega uma linha STATUS: (Convenções de script), então "comprovado" está escrito, não memorizado.
  3. Toda exportação passa por cq_helpers.export_checked. Apenas isValid() do BRep não garante uma malha limpa; fatiadores rejeitam STLs não estanques que passam nas verificações de validade. Essa barreira já pegou uma peça ruim enviada.
  4. Toda peça que será impressa recebe uma verificação de ilhas na sua orientação de IMPRESSÃO. h.islands(solid, up="+z") (ou o eixo para cima planejado) encontra material que começa acima da mesa e só se junta às camadas da peça depois, ficando apoiado do início ao fim. Uma ilha ALTA é um problema de projeto a corrigir ou apresentar ao usuário antes de qualquer plano de impressão, nunca "suportes vão lidar com isso". Em 2026-10-09 o pilar do vão da roda de um invólucro de robô era um (36,8 mm de altura em suportes de árvore, 6,52 de espessura) e quebrou no meio de uma impressão de 22 h em três cores, depois que todas as verificações de encaixe haviam passado. Verificações de encaixe perguntam "encaixa?"; esta pergunta "pode ser construído de baixo para cima?".

Fluxo de trabalho

  1. Confirme o que a solicitação deixa em aberto. Uma especificação completa ("12 mm de altura, 9 DE, 4,3 furo") não precisa de verificação. Quando uma escolha crítica está em aberto (quais furos, de onde "15 mm saliente" é medido, o que monta nela, qual hardware, qual pasta), apresente sua interpretação como uma proposta curta e pergunte ao usuário antes de construir. Imagens de referência sempre passam por esta verificação (veja abaixo).
  2. Escreva o script. Peças entregáveis: o script vive ao lado de suas saídas na pasta da peça (o script É o registro da peça; veja "Onde as peças vivem"). Sondas e experimentos: uma pasta de rascunho.
  3. Execute-o:
    & "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40
    
    Padrões: 300 s de tempo limite, limite de 4 GB, poll de 500 ms, interpretador C:\cadquery-venv\Scripts\python.exe (substitua com -Python <caminho> ou a variável de ambiente CADPARTS_PYTHON). O limite é na memória confirmada de toda a árvore de processos, imposta pelo kernel através de um objeto de job do Windows: uma alocação acima é recusada (o script vê MemoryError ou falha de alocação do OCCT) e o runner mata a árvore, saída 137. Importar apenas o cadquery confirma cerca de 0,7 GB, então nunca limite abaixo de ~1 GB. Aumente limites apenas deliberadamente para um trabalho sabidamente pesado, nunca como primeira resposta a uma morte; uma morte por watchdog geralmente significa um erro de geometria (veja pegadinhas), não um limite pequeno. -Tail N imprime apenas as últimas N linhas do stdout; o log completo está sempre em <script>.out.txt ao lado do script. Use-o em scripts que registram muito para que o log inteiro não caia no contexto. A linha de resumo informa o tempo real: escolha -TimeoutSec a partir disso, não por adivinhação. Através de uma ferramenta PowerShell, defina o tempo limite da própria ferramenta acima de -TimeoutSec. Se a ferramenta matar o runner primeiro, o objeto de job derruba a construção junto: a execução é perdida, nunca órfã.
  4. Leia a saída. O runner imprime o stdout do script, qualquer stderr, tempo real e o pico de memória confirmada da árvore. Exija o sentinela DONE; uma execução sem ele não terminou. Saída 137 = morte por watchdog (a última linha diz tempo limite ou limite); 3 = o watchdog não pôde armar (ou o interpretador está faltando), então o script nunca rodou. <script>.out.txt é o log de execução da construção (READMEs citam-no); <script>.err.txt existe apenas quando stderr teve conteúdo. Em uma morte por limite, faça triagem antes de tocar em qualquer limite (pegadinhas: "Triagem de morte por limite").
  5. Verifique antes de relatar. Leia o PNG render6 e confira a silhueta contra a intenção. Relate as dimensões a partir do bbox/volume impresso pelo script, não de memória. Verifique cada recurso MEDINDO o sólido construído (describe, bboxes de faces, uma placa intersectada através da parede); uma asserção que compara uma constante de entrada contra si mesma não prova nada. Em seguida, execute h.islands na orientação em que a peça será impressa (não negociável 4) e relate o que ela sinaliza com a peça.
  6. Registre. Atualize o README da pasta (qual arquivo imprimir), defina a linha STATUS e anote tudo o que for aprendido e que a próxima sessão precisar (veja "Registro").

Onde as peças vivem e o que uma pasta de peça contém

Raiz das peças: PERGUNTAR (se ainda disser PERGUNTAR, pergunte ao usuário onde as peças devem viver, ex. C:\Users\<nome>\Documents\cad-parts, e ofereça-se para escrever aqui). Cada peça ganha sua própria pasta sob essa raiz; agrupe peças relacionadas em subpastas (partes do chassi de um robô juntas, impressões avulsas juntas). Se o lar de uma peça não estiver claro, pergunte; não adivinhe.

Uma pasta de peça contém:

  • O(s) script(s), STEPs e renders no nível superior; todo STL em uma subpasta stl/ (exporte com stl_dir="stl"). Em uma pasta de cadeia (veja "Edições em cadeia") o nível superior contém UMA versão viva da peça: se houver um STL em stl/ para a peça do nível superior, é aquele a ser impresso. Um STL quebrado que alguém entrega fica no nível superior, nunca em stl/, pois stl/ significa imprimível.
  • README.md: o que a peça é, a linhagem ("em uso: v12, mais novo: v16 teste") e uma linha explícita "o único a imprimir". Nada vai para archived/ sem o OK do usuário. Ainda não há README: escreva um. Tamanhos irmãos em vez de versões (um espaçador de 11 mm e um de 14 mm) recebem uma linha de impressão cada.
  • archived/: versões substituídas, uma pasta por versão ou etapa de cadeia, cada uma com seu script, STEP, STL, renders e log de execução juntos, e WHY-ARCHIVED.md na raiz do arquivo. Etapas de cadeia arquivadas não são reexecutadas no local (seus caminhos de origem assumem o layout antigo); copie uma de volta ao nível superior primeiro.
  • Marcadores DEAD-*.md para recursos que nunca devem voltar (ex. CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md: nervuras de aperto que destruíram dois motores). Leia qualquer arquivo DEAD na pasta antes de tocar na peça.
  • Um plano de impressão, se escrito, vinculado a um nome de STL; marque-o como desatualizado quando a peça avançar.
  • <script>.out.txt, o log de execução da construção.
  • current.json em pastas de cadeia (próximas seções).

Convenções de script

  • Docstring do módulo: o que a peça é, por que existe, como executá-la e uma linha STATUS: (faça dela uma docstring bruta, r""", quando contiver caminhos do Windows: CPython 3.14 adverte sobre escapes \c, \s): STATUS: printed 2026-09-08, fitted, FROZEN ou STATUS: trial, unprinted. FROZEN é o que o não negociável 2 significa por comprovado; atualize a linha quando o resultado de uma impressão chegar.
  • O docstring contém o delta DESTA versão e sua justificativa. Linhagem e qual arquivo imprimir pertencem ao README. Não cole as notas da versão anterior adiante (um script que fez isso chegou a 50 KB).
  • Números de versão em passos de décimos: cada nova construção de uma linha de peça versionada é +0,1, v22 -> v22.1 ... v22.9 -> v23, nunca pulando adiante a menos que o usuário diga. Os arquivos escrevem o ponto como sublinhado (chassis_v22_1.py, .step, stl/..._v22_1.stl) porque scripts posteriores importam versões anteriores como módulos (import chassis_v12 as V12) e um nome de módulo com ponto não pode ser importado; docstrings e READMEs dizem "v22.1". Arquivos existentes mantêm seus números. Etapas de cadeia (step8, step11e) mantêm seu próprio esquema, e qualquer selo de versão gravado em uma peça permanece a contagem do próprio usuário.
  • TODAS as dimensões como constantes nomeadas no topo, em mm, um lugar para editar.
  • import cq_helpers as h (instalado nos site-packages do venv).
  • Diga QUAL lado sempre que escrever esquerda ou direita: o esquerdo do robô ou da peça (como se você fosse ele, de frente) ou o esquerdo do observador olhando para sua frente. São opostos; um "esquerdo" solto em um docstring, README ou mensagem é um defeito. Escreva a convenção de eixos (qual direção é a frente, +x, para cima) no topo de qualquer projeto multiparte e mantenha-a.
  • Afirme solid.isValid() e afirme que o bounding box corresponde às dimensões pretendidas; proteja fórmulas também como asserções (ex. profundidade do furo deve exceder a protrusão do eixo), para que uma má edição de parâmetro falhe ruidosamente em vez de imprimir sucata.
  • Hardware de acoplamento é modelado como sólidos e verificado com h.interference. Tire as dimensões de uma folha de dados ou de um paquímetro e marque em cada constante o comentário "medido" ou "assumido", com de onde veio o número. Valores padrão de fixadores quando nada melhor é conhecido: cabeça cilíndrica M3 5,5 x 3,0, folga M3 D3,30, piloto auto-roscante M2 em PLA D1,7 a 1,8. Outros fixadores padrão: rosca ISO 261 e folga ISO 273, marcado como assumido.
  • print(..., flush=True) para progresso; termine com print("DONE", flush=True).
  • Exporte: h.export_checked(solid, str(OUT / "nome_peca"), stl_dir="stl") e h.render6(solid, str(OUT / "nome_peca.png")).
  • Uma peça por arquivo exportado; as peças são impressas individualmente.

Edições em cadeia em um STEP importado

Muitas peças são um delta em um STEP pai importado (uma placa base chegou ao passo 10c através de nove desses deltas). Regras:

  • Nomeie passos step<N>, com uma letra de sufixo para um ramo (step7c) ou uma rebase (step5r); a linha SRC do docstring nomeia o arquivo pai. Uma rebase recebe uma nota WHY na pasta.
  • A pasta da cadeia carrega current.json nomeando o pai vivo. Escreva-o com h.set_current(pasta, "part.step", note="2026-09-22: ...") quando o usuário nomear a peça a ser impressa, ou a partir do script do passo logo após seu export_checked. A linha "o único a imprimir" do README e current.json devem concordar.
  • Dependentes importam o pai com plate = h.import_current(PLATE_DIR, pin="base_plate_step10c"), nunca por um nome de arquivo codificado. Quando a cadeia se move, a CONSTRUÇÃO fixada FALHA nomeando ambas as peças; reexecute toda verificação de encaixe contra o novo pai, depois mova o pino. A verificação de impressão digital também falha se o STEP foi substituído sem set_current. (Por quê: dependentes uma vez pararam de funcionar quando seu STEP pai desapareceu, e um passou em todas as verificações fixado a um pai antigo enquanto um mais novo era a peça a ser impressa.)
  • Prove o delta: h.diff antes e depois, e afirme que tudo fora da caixa de edição permanece inalterado.
  • Uma NOVA peça dependente (um suporte aparafusado a uma placa) afirma pelo menos: assentado (zero folga na face de acoplamento, sem sobreposição), seus eixos de furo nos do pai, folga da haste em ambos os furos, cabeça e acesso de ferramenta livres (uma coluna de chave sextavada sobre cada cabeça), e qualquer recurso do pai que não deve bloquear ainda livre. Leia os furos do pai de seu B-rep, filtrando faces de cilindro pela direção do eixo, já que um arredondamento também é uma face cilíndrica.
  • Variante apenas de parâmetro de um script (a cópia de 14 mm de um espaçador de 11 mm): prove "nada mais mudou" com um diff de texto dos dois scripts (apenas o docstring, NOME e o parâmetro diferem) mais describe() contra o volume analítico. Nenhuma sonda de diff de geometria necessária.
  • Uma escala não uniforme transforma toda face de um B-rep importado em uma B-spline (pegadinhas): deslocamentos podem falhar depois dela. Reconstrua, ou escale a malha.

API do cq_helpers (site-packages do venv)

  • export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015): aceita Workplane ou Shape; requer isValid(); escreve .step/.stl (o STL em <dir de basepath>/<stl_dir>/ quando stl_dir está definido, sempre "stl" aqui); trimesh estanque + verificação de enrolamento no STL com autoreparo (merge_vertices dígitos 5 então 4, fill_holes, fix_normals, aceito apenas se deriva de volume < 0,5%); então o STL deve concordar com o STEP lido do disco (ou com a forma quando step=False): bounding box dentro de max(0,05 mm, 0,5% do maior tamanho da peça) por lado, volume dentro de agree_tol. Retorna a malha trimesh. Toda verificação falha levanta h.GateError (uma subclasse de AssertionError, levantada explicitamente para que python -O não possa ignorá-la), que interrompe a execução. Imprime uma linha export ok: por arquivo escrito, caminho completo com extensão, e uma linha export check: com os números de concordância. O autoreparo fecha rachaduras de tesselação capilares em um B-rep válido; NÃO fechará uma face faltante (veja "Reparando uma malha que o usuário entrega"). O STL é malhado em uma cópia nova (a forma permanece não malhada), então uma malha fixada na forma primeiro é descartada: fixe-a com mesh=(deflection, angular) (mm absolutos, rad; peças de fornecedor com faces finas precisaram de (0,05, 0,2), pegadinhas).

  • render6(shape, png_path, color="#b25563", tol=0.3): 6 vistas canônicas sombreadas (frente/trás/esquerda/direita/topo/frente-3/4) em um PNG. Um render offscreen VTK com buffer de profundidade (a ordenação de pintor do matplotlib falsificava transparência em conjuntos, pegadinhas), projeção paralela, cada vista emoldurada na peça; um Workplane renderiza cada Shape em sua pilha; tol é a deflexão linear da tesselação em mm (0,6 para grandes conjuntos).

  • render_compare(shape, ref_image_path, png_path, color="#b25563", tol=0.3): renderiza shape nas mesmas 6 vistas, compondo cada par de imagem de referência e render atual lado a lado (esquerda: referência, direita: atual) no PNG de saída. Útil para inspecionar visualmente se mudanças em uma peça pai alteraram regiões não intencionais de uma filha.

    (nota do tradutor: o texto da API foi truncado no original; o skill foi localizado com base no conteúdo disponível)

Habilidades Relacionadas