Copyright 2026 Colin Ezra Wilder. Licensed under the Apache License, Version 2.0 (隨此技能附帶的 LICENSE 和 NOTICE 檔案)。
透過 CadQuery 子程序進行 CAD 零件設計
本機、可腳本化的 CAD:Python 腳本建構實體,一個受監控的一次性子程序執行它,cq_helpers 負責管制匯出,一張 6 視角 PNG 圖證明其形狀。使用者將結果在 FDM 印表機上列印,因此從這裡出去的每一個 STL 都必須能良好切片。
不可協商的條件
- 僅限一次性子程序。 在 2026-07-14,一個長期運行的 CAD 伺服器程序因匯入的模型在多次呼叫中累積而導致整個機器因記憶體耗盡(OOM)崩潰(2026-11-14 的一次重播排除了最初被歸咎的非均勻縮放問題;請參閱常見陷阱)。一個崩潰的子程序只損失一次運行;而一個在主進程內崩潰的操作則會拖垮整個系統。每個建置都必須透過
scripts/run_watchdogged.ps1執行,其他虛擬環境腳本(如繪圖探針、網格檢查)也同樣,不論是否為 CadQuery。當hooks/require_runner.py被註冊為 Claude Code 的鉤子(請參閱 README)時,直接呼叫虛擬環境的 Python 會被拒絕,並提示應使用的執行器命令:此拒絕是規則在正常運作,而非需要繞過的錯誤。 - 絕不編輯一個已驗證的零件檔案。 一個經過列印測試且運作正常的腳本即被凍結。變體必須建立一個「新」檔案(例如,
adapter_hex_trim.py放在adapter_hex.py旁邊),並在其文件字串中明確說明變更內容與原因。每個腳本都帶有一個STATUS:行(請參閱腳本慣例),以便「已驗證」的狀態被記錄下來,而非僅憑記憶。 - 所有匯出都需經過
cq_helpers.export_checked。 僅 BRepisValid()無法保證網格的乾淨度;切片器會拒絕那些通過有效性檢查但非水密的 STL。此關卡已經成功攔截過一個有缺陷的零件。 - 每個將被列印的零件都必須在其「列印」方向進行孤島檢查。
h.islands(solid, up="+z")(或預期的向上軸向)會找出那些從列印平台開始,但只在後續層與主體連接的材料,這意味著它從頭到尾都需要支撐材料。一個「高」孤島是一個需要修復的設計問題,或在任何列印計畫之前就應提交給使用者,絕不能認為「支撐可以處理」。在 2026-10-09,一個機器人外殼的輪轂間隙支柱就是這樣的孤島(在樹狀支撐上高 36.8 毫米,細部 6.52),在一個 22 小時三色列印過程中,在所有配合檢查都通過後,它中途斷裂了。配合檢查問的是「它適合嗎?」;此檢查問的是「它能從下往上被建構出來嗎?」
工作流程
- 確認提示中未明確的部分。 一個完整的規格(如「12 毫米高,外徑 9,孔徑 4.3」)無需關卡。當一個影響重大的選擇是開放的(哪些孔、從何處測量「突出 15 毫米」、上面安裝什麼、哪種硬體、哪個資料夾),請將你的解讀作為一個簡短提案陳述,並在建構前詢問使用者。參考圖片總是會經過這個關卡(見下文)。
- 撰寫腳本。 可交付的零件:腳本與其輸出檔案一起存放在零件資料夾中(腳本就是零件的記錄;請參閱「零件存放位置」)。探針與實驗:則放在草稿資料夾。
- 執行腳本:
預設值:300 秒超時,4 GB 上限,500 毫秒輪詢間隔,直譯器& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(可使用-Python <path>或CADPARTS_PYTHON環境變數覆寫)。此上限適用於整個進程樹的已提交記憶體,透過 Windows 作業物件由核心強制執行:超過此上限的記憶體分配將被拒絕(腳本會看到MemoryError或 OCCT 分配失敗),並且執行器會終止整個進程樹,退出碼為 137。僅匯入 cadquery 就會提交約 0.7 GB,因此切勿將上限設低於約 1 GB。只有在確認是繁重任務時才刻意提高限制,絕不能將其作為首次回應;監控終止通常意味著幾何形狀錯誤(請參閱常見陷阱),而非上限過小。-Tail N僅列印最後 N 行標準輸出;完整日誌始終保留在腳本旁邊的<script>.out.txt中。對於會產生大量日誌的腳本,使用此選項可避免過多內容進入上下文。摘要行會報告實際耗時:據此選擇-TimeoutSec,而非憑猜測。 透過 PowerShell 工具時,請將工具本身的超時設定得高於-TimeoutSec。如果工具先終止了執行器,作業物件會同時中止建置:此次運行就會遺失,永遠不會變成孤立進程。 - 閱讀輸出。 執行器會列印腳本的標準輸出、任何標準錯誤輸出、實際耗時以及進程樹的峰值已提交記憶體。要求看到
DONE信號;沒有它的運行代表未完成。退出碼 137 = 監控終止(最後一行會指示是超時還是達到上限);退出碼 3 = 監控無法啟動(或直譯器缺失),因此腳本從未執行。<script>.out.txt是建置的運行日誌(README 會引用它);<script>.err.txt僅在標準錯誤有內容時存在。當發生上限終止時,在觸碰任何限制之前先進行問題分類(常見陷阱:「分類上限終止」)。 - 在報告之前進行驗證。 檢查
render6PNG 圖形,並核對其輪廓是否符合意圖。根據腳本列印的邊界框/體積來報告尺寸,而非根據記憶。透過「測量」已建構的實體來檢查每個特徵(describe、面的邊界框、一個穿過壁厚的切片平面);一個比較輸入常數與自身的斷言毫無意義。然後,以零件將被列印的方向執行h.islands(不可協商的條件 4),並報告它與零件一起標記的內容。 - 記錄。 更新資料夾的 README(要列印哪個檔案),設定 STATUS 行,並記錄下一個工作階段需要知道的任何學到的事項(請參閱「記錄」)。
零件存放位置與零件資料夾內容
零件根目錄:詢問(如果這裡仍寫著 ASK,請詢問使用者零件應存放在何處,例如 C:\Users\<name>\Documents\cad-parts,並主動提議將其寫入此處)。每個零件在其根目錄下都有自己的資料夾;將相關的零件分組存放在子資料夾中(機器人的底盤零件放一起,一次性列印件放一起)。如果某個零件的位置不明確,請詢問;不要猜測。
一個零件資料夾包含:
- 腳本、STEP 檔案和渲染圖片位於頂層;所有 STL 檔案則放在
stl/子資料夾中(使用stl_dir="stl"匯出)。在一個鏈條資料夾中(請參閱「鏈條編輯」),頂層僅保留一個該零件的「現行」版本:如果頂層零件在stl/中有一個 STL 檔案,那就是要列印的那個。一個別人交過來的損壞 STL 檔案應保留在頂層,絕不能放在stl/中,因為stl/僅代表可列印。 README.md:說明零件是什麼、其沿革(「使用中:v12,最新:v16 試驗中」),以及明確的「要列印的零件」行。未經使用者同意,不得將任何項目移至archived/。如果尚無 README:則建立一個。同一系列的不同尺寸而非版本(例如一個 11 毫米和一個 14 毫米的間隔柱)各自會有一個列印行。archived/:被取代的版本,每個版本或鏈條步驟一個資料夾,各自包含其腳本、STEP、STL、渲染圖和運行日誌,並在歸檔根目錄下有一個WHY-ARCHIVED.md。已歸檔的鏈條步驟不應在原地重新執行(它們的來源路徑假定為舊的佈局);請先複製一份到頂層。DEAD-*.md標記,用於那些「絕不能」再次出現的特徵(例如CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md:一個摧毀了兩個馬達的勒死肋條)。在接觸零件之前,請先閱讀資料夾中的任何 DEAD 檔案。- 一份列印計畫(如果有撰寫的話),並關聯到一個 STL 檔案名稱;當零件進展時,請將其標記為過時。
<script>.out.txt,建置的運行日誌。- 鏈條資料夾中的
current.json(下一個章節)。
腳本慣例
- 模組文件字串:說明零件是什麼、為何存在、如何執行,以及一個
STATUS:行(當包含 Windows 路徑時,請使用原始文件字串r""":CPython 3.14 會對\c、\s等跳脫字元發出警告):STATUS: printed 2026-09-08, fitted, FROZEN或STATUS: trial, unprinted。FROZEN 就是不可協商的條件 2 所指的「已驗證」;當列印結果返回時更新此行。 - 文件字串中應包含「此版本」的變更內容及其理由。零件的沿革和要列印哪個檔案則屬於 README。請勿將先前版本的註解向前複製(曾有一個腳本因此達到 50 KB)。
- 版本號以十分之一遞增:每個有版本號的零件線的新建置都是 +0.1,
v22->v22.1...v22.9->v23,除非使用者另有指示,否則不可跳躍。由於後續腳本可能會將早期版本作為模組匯入(import chassis_v12 as V12),而點狀模組名稱無法匯入,因此檔案中的點使用底線表示(chassis_v22_1.py、.step、stl/..._v22_1.stl);文件字串和 README 中則使用「v22.1」。現有檔案保留其編號。鏈條步驟(step8、step11e)保留它們自己的命名方案,並且蝕刻在零件上的任何版本標記應保持為使用者自己的計數。 - 所有尺寸都以毫米為單位,作為命名常量放在頂端,方便一次性編輯。
import cq_helpers as h(安裝在虛擬環境的 site-packages 中)。- 說明是哪一隻「手」:每當你寫到左或右時,請指定是機器人或零件自己的左邊(就像你身在其中,面向正前方),或是觀察者從其正面看去的左邊。兩者是相反的;在文件字串、README 或訊息中單獨寫一個「左」是缺陷。在任何多零件專案的頂端寫下軸向慣例(哪個方向是正面、+x、向上),並保持一致。
- 斷言
solid.isValid()並斷言邊界框與預期尺寸相符;也將公式用斷言保護起來(例如孔深必須大於軸的突出部分),這樣一個錯誤的參數編輯就會大聲失敗,而不是列印出廢品。 - 配合的硬體以實體建模,並使用
h.interference進行檢查。從數據手冊或卡尺取得尺寸,並在每個常數的註解中標記是「測量值」或「假設值」,以及數字來自何處。當沒有更好的資訊時,預設的緊固件值:M3 內六角螺絲頭部 5.5 x 3.0,M3 間隙孔 D3.30,M2 自攻螺絲在 PLA 中的導引孔 D1.7 到 1.8。其他標準緊固件:ISO 261 螺紋和 ISO 273 間隙孔,並標記為「假設值」。 print(..., flush=True)用於顯示進度;以print("DONE", flush=True)結尾。- 匯出:
h.export_checked(solid, str(OUT / "part_name"), stl_dir="stl"),然後h.render6(solid, str(OUT / "part_name.png"))。 - 每個匯出的檔案對應一個零件;零件是單獨列印的。
對匯入的 STEP 檔案進行鏈條編輯
許多零件是基於一個匯入的上層 STEP 檔案的增量修改(一個基礎底板曾透過九次這樣的增量修改達到步驟 10c)。規則:
- 將步驟命名為
step<N>,分支版本加上後綴字母(step7c),或重新基線的版本加上r(step5r);文件字串中的 SRC 行應指明上層檔案名稱。重新基線需要在資料夾中有一個「WHY」說明。 - 鏈條資料夾中應包含
current.json,指明現行有效的是哪個上層零件。當使用者指定要列印的零件時,或在步驟腳本中緊接在export_checked之後,使用h.set_current(folder, "part.step", note="2026-09-22: ...")來寫入。README 中的「要列印的零件」行與current.json必須一致。 - 依賴項使用
plate = h.import_current(PLATE_DIR, pin="base_plate_step10c")匯入上層零件,絕不能使用硬編碼的檔案名稱。當鏈條移動時,被固定的建置會失敗,並列出兩個零件的名稱;針對新的上層零件重新執行所有配合檢查,然後移動固定點。指紋檢查也會在 STEP 檔案被替換而沒有執行set_current時失敗。(原因:當依賴項的上層 STEP 檔案消失時,它們曾經停止運行;並且有一個依賴項在其上層零件已被更新、成為新的要列印零件時,仍然通過了所有固定於舊上層零件的檢查。) - 證明增量修改:在修改前後使用
h.diff,並斷言編輯框之外的所有內容保持不變。 - 一個「新的」依賴零件(例如一個用螺栓固定在一塊平板上的支架)至少需要斷言:安裝到位(與配合面之間有零間隙,且無重疊)、其孔軸線與上層零件對齊、螺杆在兩個孔中都有間隙、頭部和工具操作空間充足(每個頭部上方有一個六角扳手柱狀空間),以及它不得阻擋的上層零件特徵仍然可及。從上層零件的 B-rep 中讀取其孔洞,透過軸向過濾圓柱面,因為圓角也是一個圓柱面。
- 腳本的「僅參數」變體(一個 14 毫米間隔柱是 11 毫米版本的複製品):透過兩個腳本的文字差異來證明「沒有其他變更」(僅文件字串、NAME 和參數不同),並對分析體積使用
describe()。無需幾何差異探針。 - 非均勻縮放會將匯入的 B-rep 的每個面都轉換為 B-spline(常見陷阱):之後的偏移操作可能會失敗。應重建,或是縮放網格。
cq_helpers API(虛擬環境 site-packages)
export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015): 接受 Workplane 或 Shape;要求isValid();寫入.step/.stl檔案(當設定stl_dir時,STL 寫入<dir of basepath>/<stl_dir>/,此處一律為"stl");對 STL 進行 trimesh 水密 + 繞線方向檢查並自動修復(merge_vertices精度設為 5 再設為 4,fill_holes,fix_normals,僅在體積漂移小於 0.5% 時才接受);然後 STL 必須與從磁碟讀回的 STEP 檔案一致(或當step=False時與 shape 一致):每個邊的邊界框差異在 max(0.05 mm, 0.5 % of the part's largest size) 以內,體積差異在agree_tol以內。傳回 trimesh 網格。任何失敗的檢查都會引發h.GateError(一個 AssertionError 的子類,明確引發以防止python -O跳過它),從而停止運行。每寫入一個檔案就列印一行export ok:(含完整路徑和副檔名),以及一行export check:(含一致性數值)。 自動修復可以關閉有效 B-rep 上細微的曲面細分裂縫;但它「無法」修復缺失的面(請參閱「修復使用者提供的網格」)。STL 的網格是基於一個全新的副本(原始 shape 保持未網格化),因此任何先附加在 shape 上的網格都會被丟棄:請使用mesh=(deflection, angular)參數來指定(毫米絕對值,弧度;帶有細長面的供應商零件需要(0.05, 0.2),常見陷阱)。render6(shape, png_path, color="#b25563", tol=0.3):生成 6 個標準的著色視圖(前/後/左/右/頂/前-3/4 視角)並輸出到一個 PNG 檔案。這是一個基於深度緩衝的 VTK 離屏渲染(matplotlib 的畫家排序演算法在組合體上會產生虛假的透視效果,常見陷阱),使用平行投影,每個視圖都將零件居中顯示;對於 Workplane,會渲染其堆疊上的每個 Shape;tol是曲面細分的線性偏差,單位為毫米(大型組合體使用 0.6)。render_compare(shape, ref_image_path, ...): ...
[其餘內容已被截斷以符合翻譯要求]