AryaVora621/agentcad

O que agentcad faz?

1. A regra central

Nunca relate uma dimensão, folga ou APROVAÇÃO que você não mediu a partir da geometria construída com agentcad. Parâmetros são intenção, não evidência. Um valor que você digitou em model.py diz o que você pediu, não o que existe.

2. O loop

agentcad new my-part --template blank      # ou bracket, box-with-lid
# edite my-part/model.py e my-part/agentcad.toml
agentcad check my-part --json              # constrói, depois mede
agentcad render my-part                    # build/renders/: um PNG por vista mais sheet.png
agentcad view my-part                      # visualizador ao vivo, para o humano

1. Escreva as verificações para a especificação primeiro ou enquanto modela (seção 3).
2. Execute agentcad check --json. Leia cada FALHA: summary, measured, limit, where.
3. Corrija a geometria no local que where nomeia. Re-execute. Não edite um limite para fazer uma FALHA desaparecer a menos que o requisito em si tenha mudado.
4. Execute agentcad render e abra sheet.png com uma ferramenta que suporte imagens. Olhe antes de dizer que parece certo. Renderizações encontram erros grosseiros (recurso faltando, lado errado); elas nunca provam espessura, folga ou sobreposição.
5. Repita até que todas as portas passem. Execute agentcad check novamente após a última edição.

A porta overhang ignora faces na mesa e faces voltadas para baixo centralizadas abaixo de first_layer_mm (padrão 0.3), então um chanfro na borda inferior não conta; a área isenta é relatada como first_layer_area_mm2.

Use --only ID,ID para reexecutar portas selecionadas e --no-build apenas quando build/ estiver fresco.

3. Transforme requisitos em verificações

Cada requisito funcional na especificação se torna uma verificação em checks(ctx). Sondas de sólidos (seção 4) representam a peça correspondente. Todos os nomes abaixo são a API real.

Um encaixe se torna uma medição de folga:

def checks(ctx):
    play = ctx.play("tampa", "caixa", direction=(1, 0, 0), max_mm=2.0)
    ctx.expect("folga_tampa_lateral", play if play is not None else 2.0, min=0.15, max=0.4, part="tampa")

"A tampa sai" se torna um teste de deslize:

    sweep = ctx.slide("tampa", "caixa", direction=(0, 0, 1), distance=15.0, steps=40)
    ctx.expect("tampa_liberta_livre", max(s["overlap_mm3"] for s in sweep), max=0.01, unit="mm3", part="tampa")

"Um parafuso M4 passa" se torna um cilindro sonda que não deve colidir e deve estar próximo à parede:

    import cadquery as cq
    parafuso = cq.Workplane("XY").circle(2.0).extrude(30).translate((10, 0, -5))  # haste de 4.0 mm
    ctx.expect("interferencia_parafuso", ctx.interference("suporte", parafuso), max=0.01, unit="mm3", part="suporte")
    ctx.expect("folga_parede_parafuso", ctx.distance("suporte", parafuso), min=0.0, max=0.5, part="suporte")

A faixa de distância prova que o parafuso está realmente perto do furo, não a 14 mm de distância com sobreposição zero.

"Cabe na impressora" é a porta interna bed_fit: defina [printer] em agentcad.toml com a máquina real (profile ou bed = [X, Y, Z]). "Paredes fortes o suficiente" é min_wall_mm em [checks].

4. Sondas de sólidos

Construa o representante da peça correspondente a partir do requisito, nunca a partir dos próprios parâmetros do modelo. Um parafuso M4 é um cilindro de 4.0 mm. Uma esfera de 54 mm é uma esfera de 54 mm. Um cabo é um cilindro ao longo de sua rota. Uma mão é uma caixa do tamanho da mão. Se a sonda lê a mesma variável da qual o furo foi construído, a verificação nunca pode falhar.

Sondas são objetos cq.Workplane ou cq.Shape já no quadro de uso. Coloque-os com .translate e passe-os onde quer que um nome de peça seja aceito (ctx.interference, ctx.distance, ctx.slide, ctx.play).

5. Prove que uma verificação pode falhar

Uma verificação que você nunca viu falhar é um palpite. Após escrevê-la:

1. Quebre a geometria (ou a sonda) de uma forma que deve acioná-la: desloque o furo 3 mm, reduza a folga para 0, torne a sonda 1 mm maior.
2. Execute agentcad check. Confirme que esta verificação FALHA, por sua própria afirmação, com o número que você esperava.
3. Restaure a geometria e confirme APROVAÇÃO.

Se passar enquanto quebrada, a verificação mede a coisa errada. Corrija a verificação antes de confiar em qualquer outro resultado.

6. Quadros

Quadro	Significado	Usado por
modelo	a peça em suas próprias coordenadas	build/step/<parte>.step
uso	a pose montada, Part.use	interference, sondas, ctx.slide, ctx.play, build/assembly/
impressão	na mesa, z = 0 na parte inferior, XY centralizado, rotação Part.print	bed_fit, bed_contact, overhang, min_wall, watertight, build/stl/

Defina Part.print = Pose(rx=180) (ou qualquer rotação) para que cada peça seja impressa sem suporte e com camadas ao longo da carga. Escolha a face na mesa primeiro, depois verifique overhang nesse quadro. Peças compradas recebem printed=False. Modele peças em um quadro local conveniente e coloque-as com Part.use.

7. Relatórios, códigos de saída, diff e arquivos soltos

Códigos de saída: 0 todas aprovadas (AVISO permitido), 1 pelo menos uma FALHA, 2 erro de uso ou configuração (incluindo chaves desconhecidas em agentcad.toml), 3 o código do modelo levantou uma exceção ou não produziu sólido válido. Trate 2 e 3 como "sem resultado", não como aprovação.

agentcad check --json imprime um documento com "schema": "agentcad.report/1" e uma lista checks. Cada verificação tem id, part, status (PASS, WARN, FAIL, SKIP, ERROR), summary, measured, limit, where. Uma verificação de projeto que levanta exceção se torna ERROR e a execução continua.

Compare construções com agentcad diff OLD NEW (dois arquivos manifest.json ou duas pastas de construção; volume, caixa delimitadora, conjunto de peças) para capturar mudanças não intencionais após uma edição. Copie build/manifest.json para um local seguro antes de uma alteração arriscada.

Para revisar CAD que você não escreveu, meça os arquivos diretamente:

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. Quando parar

Pare apenas quando todas estas condições forem verdadeiras:

• todas as portas passam na última execução de agentcad check, executada após sua última edição;
• cada requisito na especificação tem uma verificação, e você viu cada uma falhar (seção 5);
• você olhou as renderizações;
• seu resumo cita os números medidos com unidades (folga, parede p1, área de saliência, ajuste na mesa);
• você declara a contagem de peças e qualquer coisa deixada como verificação de bancada (força de encaixe, tolerância na impressora real, comportamento do material).

9. Anti-padrões e as falhas que causaram

• Ler parâmetros em vez da forma construída. Um trabalhador relatou APROVAÇÃO em uma folga de encaixe deslizante enquanto a peça estava 14 mm fora de sua ranhura, porque sua verificação leu os parâmetros.
• Ignorar o quadro de impressão. Uma placa foi modelada para imprimir com a face para baixo com cerca de 6100 mm2 de teto sem suporte, porque a saliência nunca foi verificada na orientação de impressão.
• Ignorar interferência por pares. Duas peças se sobrepunham em 50 cm3 na montagem, porque ninguém executou interferência na pose de uso.
• Tolerância de exportação grossa. Uma exportação STL grosseira de uma peça revolvida produziu uma faceta que cortou uma parede de 2.0 mm a 1.5 mm. Correção: tolerância de exportação 0.02 mm, tolerância angular 0.05 rad (os padrões em [export]).
• Prosa não medida. Um documento de design afirmava um diâmetro externo de 29 a 33.5 mm enquanto o modelo media 19 mm. Meça cada número que você escreve em prosa.
• Porta apenas em "constrói". Uma reconstrução passou em sua única porta enquanto todos os canais internos estavam selados e um bico era sólido. Trace o caminho funcional: varra uma sonda ao longo da rota de água, cabo ou ar.
• Verificar apenas o todo. Uma montagem estava estável no geral enquanto um único estágio solto sozinho tombava a 6 graus. Verifique cada sub-pilha solta.
• Confiar em um relatório desatualizado. Um relatório de porta estava desatualizado porque a construção travou após o relatório antigo ser escrito. agentcad constrói atomicamente, mas ainda compare os carimbos de tempo do relatório com sua última edição e reexecute após cada edição.
• Confiar na imagem. Uma renderização limpa escondeu tudo acima.

10. Referências

• references/design-for-printing.md: leia antes de escolher orientação, espessura de parede, encaixes, furos de parafuso ou recursos de encaixe para uma peça FDM.
• references/cadquery-patterns.md: leia quando uma operação do CadQuery falha, retorna uma forma inesperada, ou você precisa de seletores, cascas, filetes ou sondas de sólidos.
• references/verification-playbook.md: leia ao planejar verificações para uma especificação, testar movimento ou função, ou revisar CAD de outro agente.