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
- 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. Quandohooks/require_runner.pyestá 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. - 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.pyao lado deadapter_hex.py) com um docstring nomeando exatamente o que mudou e por quê. Todo script carrega uma linhaSTATUS:(Convenções de script), então "comprovado" está escrito, não memorizado. - Toda exportação passa por
cq_helpers.export_checked. ApenasisValid()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. - 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
- 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).
- 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.
- Execute-o:
Padrões: 300 s de tempo limite, limite de 4 GB, poll de 500 ms, interpretador& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(substitua com-Python <caminho>ou a variável de ambienteCADPARTS_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êMemoryErrorou 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 Nimprime apenas as últimas N linhas do stdout; o log completo está sempre em<script>.out.txtao 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-TimeoutSeca 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ã. - 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.txtexiste 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"). - Verifique antes de relatar. Leia o PNG
render6e 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, executeh.islandsna orientação em que a peça será impressa (não negociável 4) e relate o que ela sinaliza com a peça. - 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 comstl_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 emstl/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 emstl/, poisstl/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 paraarchived/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, eWHY-ARCHIVED.mdna 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-*.mdpara 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.jsonem 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, FROZENouSTATUS: 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 comprint("DONE", flush=True).- Exporte:
h.export_checked(solid, str(OUT / "nome_peca"), stl_dir="stl")eh.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.jsonnomeando o pai vivo. Escreva-o comh.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 seuexport_checked. A linha "o único a imprimir" do README ecurrent.jsondevem 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 semset_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.diffantes 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; requerisValid(); escreve.step/.stl(o STL em<dir de basepath>/<stl_dir>/quandostl_direstá 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 quandostep=False): bounding box dentro de max(0,05 mm, 0,5% do maior tamanho da peça) por lado, volume dentro deagree_tol. Retorna a malha trimesh. Toda verificação falha levantah.GateError(uma subclasse de AssertionError, levantada explicitamente para quepython -Onão possa ignorá-la), que interrompe a execução. Imprime uma linhaexport ok:por arquivo escrito, caminho completo com extensão, e uma linhaexport 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 commesh=(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): renderizashapenas 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)