AryaVora621/agentcad

agentcad 是做什麼的？

1. 核心規則

絕不報告未使用 agentcad 從已建構幾何量測到的尺寸、間隙或 PASS。參數是意圖，不是證據。你在 model.py 中輸入的值告訴你你要求的是什麼，而不是實際存在的東西。

2. 循環

agentcad new my-part --template blank      # 或 bracket、box-with-lid
# 編輯 my-part/model.py 和 my-part/agentcad.toml
agentcad check my-part --json              # 建構，然後量測
agentcad render my-part                    # build/renders/：每個視角一張 PNG 加上 sheet.png
agentcad view my-part                      # 即時檢視器，供人類使用

1. 先 (或邊建模邊) 為需求撰寫檢查（第 3 節）。
2. 執行 agentcad check --json。閱讀每個 FAIL：summary、measured、limit、where。
3. 在 where 指定的位置修正幾何。重新執行。除非需求本身改變，否則不要為了讓 FAIL 消失而編輯限制值。
4. 執行 agentcad render 並使用支援圖片的工具開啟 sheet.png。在說「看起來沒問題」之前先看過它。渲染圖能發現明顯的錯誤（遺失特徵、錯誤面）；它們永遠無法證明厚度、間隙或重疊。
5. 重複直到所有閘門通過。在最後一次編輯後再次執行 agentcad check。

overhang 閘門會忽略位於列印床上的面以及位於 first_layer_mm（預設 0.3）以下且朝下的面，因此底部邊緣的倒角不會被計入；豁免區域會回報為 first_layer_area_mm2。

使用 --only ID,ID 重新執行選定的閘門，並在 build/ 目錄為最新狀態時使用 --no-build。

3. 將需求轉換為檢查

需求中的每個功能要求都會變成 checks(ctx) 中的一個檢查。探針實體（第 4 節）代表配合的物體。以下所有名稱都是實際的 API。

配合變成間隙量測：

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

「蓋子可以取下」變成滑動測試：

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

「M4 螺絲可以穿過」變成一個探針圓柱體，必須不干涉且必須靠近牆壁：

    import cadquery as cq
    screw = cq.Workplane("XY").circle(2.0).extrude(30).translate((10, 0, -5))  # 4.0 mm 螺桿
    ctx.expect("screw_interference", ctx.interference("bracket", screw), max=0.01, unit="mm3", part="bracket")
    ctx.expect("screw_wall_gap", ctx.distance("bracket", screw), min=0.0, max=0.5, part="bracket")

距離區間驗證螺絲確實靠近孔洞，而不是在 14 mm 外且沒有重疊。

「適合列印機」是內建的 bed_fit 閘門：在 agentcad.toml 中設定 [printer] 為實際機器（profile 或 bed = [X, Y, Z]）。「牆壁夠堅固」是 [checks] 下的 min_wall_mm。

4. 探針實體

從需求建立配合物的替代實體，絕不從模型自身的參數建立。M4 螺絲是 4.0 mm 的圓柱體。54 mm 的球體是 54 mm 的球體。電纜是沿著其路徑的圓柱體。手是手部尺寸的盒子。如果探針讀取了與孔洞建構時相同的變數，則檢查永遠不會失敗。

探針是 cq.Workplane 或 cq.Shape 物件，且位於使用框架中。使用 .translate 放置它們，並將它們傳遞給任何接受零件名稱的地方（ctx.interference、ctx.distance、ctx.slide、ctx.play）。

5. 證明檢查可以失敗

你從未見過失敗的檢查就是一個猜測。在撰寫檢查後：

1. 以一定會觸發它的方式破壞幾何（或探針）：將孔洞偏移 3 mm、將間隙縮小為 0、將探針放大 1 mm。
2. 執行 agentcad check。確認此檢查根據其自身的斷言 FAIL，且數字符合預期。
3. 恢復幾何並確認 PASS。

如果檢查在模型異常時仍通過，則表示檢查量測了錯誤的東西。在信任任何其他結果之前先修正檢查。

6. 框架

框架	意義	使用於
model	零件在其自身座標系中	build/step/<part>.step
use	組裝後的姿態，Part.use	interference、探針、ctx.slide、ctx.play、build/assembly/
print	在列印床上，z = 0 在底部，XY 居中，Part.print 旋轉	bed_fit、bed_contact、overhang、min_wall、watertight、build/stl/

設定 Part.print = Pose(rx=180)（或任何旋轉），使每個零件無需支撐即可列印，且層紋沿受力方向。首先選擇與列印床接觸的面，然後在該框架中檢查 overhang。購買的零件設定為 printed=False。在方便的本機框架中建立模型，並使用 Part.use 放置它們。

7. 報告、退出碼、差異與獨立檔案

退出碼：0 全部通過（允許 WARN）、1 至少一個 FAIL、2 使用或配置錯誤（包括 agentcad.toml 中的未知鍵）、3 模型程式碼拋出例外或未產生有效的實體。將 2 和 3 視為「無結果」，而非通過。

agentcad check --json 會輸出一個文件，包含 "schema": "agentcad.report/1" 和一個 checks 清單。每個檢查都有 id、part、status（PASS、WARN、FAIL、SKIP、ERROR）、summary、measured、limit、where。專案檢查若拋出例外則變為 ERROR，且執行會繼續。

使用 agentcad diff OLD NEW（兩個 manifest.json 檔案或兩個建構資料夾；體積、邊界框、零件集合）來比較建構，以在編輯後發現非預期的變更。在進行有風險的變更前，先複製 build/manifest.json。

若要審閱非你撰寫的 CAD，可直接量測檔案：

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. 何時停止

僅在以下所有條件成立時停止：

• 在最新的 agentcad check 執行中（且該執行是在你最後一次編輯後進行的），所有閘門都通過；
• 需求中的每個要求都有一個對應的檢查，而且你已親眼看過每個檢查都失敗（第 5 節）；
• 你已看過渲染圖；
• 你的摘要中引用了包含單位的量測數值（間隙、壁厚 p1、懸空面積、列印床貼合度）；
• 你陳述了零件數量，以及任何留待工作台上確認的事項（卡扣力、實際列印機的公差、材料特性）。

9. 反模式與其導致的失敗

• 讀取參數而非已建構的形狀。一名工人報告滑動鳩尾槽間隙 PASS，但零件卻位於其溝槽外 14 mm 處，因為它的檢查讀取了參數。
• 跳過列印框架。一個平板模型被設計成面向下列印，產生了約 6100 mm2 的無支撐天花板，因為從未在列印方向檢查懸空。
• 跳過成對干涉。兩個零件在組裝中重疊了 50 cm3，因為沒有人在使用姿態下執行干涉檢查。
• 粗糙的匯出公差。一個旋轉體的粗糙 STL 匯出產生了一個小平面，將 2.0 mm 的壁切削至 1.5 mm。修正方法：匯出公差 0.02 mm，角公差 0.05 rad（[export] 中的預設值）。
• 未經量測的文字敘述。一份設計文件陳述外徑為 29 到 33.5 mm，而模型實際量測值為 19 mm。將你寫入文字敘述的每個數字都量測一遍。
• 僅以「它能建構」作為閘門。一次重建通過了唯一的閘門，但所有內部通道都被密封，且一個出口是實心的。追蹤功能路徑：沿著水、電纜或空氣路徑掃掠一個探針。
• 僅檢查整體。一個組件整體是穩定的，但其中一個鬆動的子堆疊在 6 度時便傾倒。檢查每個鬆動的子堆疊。
• 信任過時的報告。一份閘門報告是過時的，因為建構在舊報告寫入後崩潰了。agentcad 是原子性建構的，但仍需比較報告時間戳與你最後一次編輯時間，並在每次編輯後重新執行。
• 信任圖片。一張乾淨的渲染圖隱藏了以上所有問題。

10. 參考資料

• references/design-for-printing.md：在為 FDM 零件選擇方向、壁厚、配合、螺絲孔或卡扣特徵前閱讀。
• references/cadquery-patterns.md：當 CadQuery 操作失敗、回傳非預期形狀，或者你需要選擇器、殼體、圓角或探針實體時閱讀。
• references/verification-playbook.md：在為需求規劃檢查、測試運動或功能，或審閱其他代理的 CAD 時閱讀。