實驗室硬體 CAD 是做什麼的？
將物理研究硬體設計為參數化 Python 原始碼，將 STEP 匯出為權威性工件，並在製造前以數值與視覺方式驗證結果。
實驗室硬體最困難的部份幾乎從來都不是幾何形狀本身，而是零件必須與尺寸固定於已發布標準或供應商圖面的設備配合。一個寬 0.5 毫米的托架就無法裝入讀盤機；一個長寬比錯誤的通道會在鍵合時塌陷；一個螺孔間距為 25.4 毫米而非 25.0 毫米的固定座將無法安裝到光學桌上。此技能的作用就是確保這些數值正確並經過檢查。
使用時機
用於任何為實驗室設計、建模或製造實體零件的請求：晶片、模具、固定座、轉接器、托架、機架、支架、外殼、治具、夾具、競技場或迷宮。也適用於檢查或修改現有的 STEP 檔案。
不要用於有限元素分析、計算流體力學、分子結構或科學繪圖。這些屬於不同技能。
設定
uv venv --python 3.12 .venv-labcad
uv pip install --python .venv-labcad/bin/python "build123d==0.11.1" "matplotlib>=3.8"
build123d 0.11.1 需要 Python >=3.10,<3.15，並透過 cadquery-ocp-novtk 引入 OpenCascade 核心。套件體積較大；建議每個專案安裝一次後重複使用。
所有整合腳本均支援 --help。check.py standards 可在不安裝 build123d 的情況下執行。
模型檔案是執行而非解析。gen.py、check.py 和 snapshot.py 會匯入 *_model.py 並呼叫其 build() 函式，該函式會執行目前環境下的任意 Python 程式碼。這是參數化 CAD 的固有特性——原始碼即為設計。僅執行由本工作階段產生或用戶從信任來源提供的模型檔案。若模型來自網際網路、共享硬碟或不可信的同事，請在執行前閱讀原始碼並告知您已這麼做。
必要工作流程
請依序執行以下步驟。步驟 5 和 6 為非選擇性的，且步驟 6 不能因步驟 5 通過而省略。
1. 歸類至裝置系列
閱讀請求，進行分類，並載入恰好一個系列參考。請勿同時載入全部四個——它們篇幅很長，且在系列之間混用慣例是常見的錯誤來源。
| 若零件為 | 載入 |
|---|---|
| 晶片、模具、通道網路、流動槽、墊片或任何具有流體端口的元件 | references/microfluidics.md |
| 固定座、支柱、光學桌轉接器、籠式系統零件、光束路徑中的濾光片或樣品座 | references/optomechanics.md |
| 適用於盤、樣品槽、管、玻片或培養皿的轉接器、插入件、機架或托架 | references/labware-adapters.md |
| 用於動物實驗的競技場、迷宮、頭部固定零件、噴嘴、繫繩或鋁擠型安裝的外殼 | references/behavior-rigs.md |
若零件確實橫跨兩個系列——例如一個需螺栓固定至光學桌的微流體晶片——請載入擁有關鍵介面的系列，然後僅讀取第二個系列的介面部份。請在回覆中說明您歸類至哪個系列。
2. 在進行任何幾何設計之前，先確定介面尺寸
每個零件至少有一個配合介面。在撰寫程式碼之前，請為每個介面記錄：
- 尺寸的來源：已發布標準、供應商圖面或用戶測量值；
- 標稱值與公差；
- 您預期的間隙或干涉及其理由。
請查閱 assets/standards.json 或系列參考文獻中的數值。**切勿憑記憶書寫介面尺寸。**如果標準檔案或參考文獻中沒有該數值，請向用戶索取供應商圖面或測量值，而非自行猜測。猜測的介面尺寸是此技能中最昂貴的失敗模式。
必須容納標準化元件的特徵，其尺寸應根據該元件的最大實體狀態——標稱值加上其正公差——來決定，然後才添加間隙。若根據標稱值決定尺寸，則只能與較小的一半合格零件配合。
python scripts/check.py standards --list
python scripts/check.py standards --show slas-microplate-footprint
已捆綁的標準 ID（確切字串；請不要猜測變體）：slas-microplate-footprint、slas-microplate-height、slas-microplate-flange、slas-well-positions-96、slas-well-positions-384、slas-well-positions-1536、cuvette-standard-10mm、optical-breadboard-metric、optical-breadboard-imperial、cage-system-30mm、sm1-lens-tube-thread。
如果零件與此清單中的任何項目都不匹配，這是很常見且沒問題的：宣告無介面，並在報告中將每個介面尺寸的名稱與其來源（用戶規格、供應商圖面、測量值）標記為未檢查。切勿為了填補空缺而對照無關的標準進行宣告——虛假的宣告比誠實的「無人檢查此項」更糟糕。
3. 在選擇幾何形狀之前，先選擇製程
請閱讀 references/fabrication-limits.md。製程決定了最小壁厚、最小特徵尺寸、可達到的公差，以及零件是否能承受高壓滅菌或接觸您的溶劑。FDM 無法保持 ±0.05 毫米的公差；SLA 樹脂在未經後固化與測試的情況下，通常不適合與細胞接觸。請在模組的檔案 docstring 中記錄製程與材料。
4. 撰寫參數化模型
編寫 <part>_model.py。原始碼是權威性工件——切勿手動編輯匯出的 STEP 檔案，也切勿從網格重新產生。
要求：
- 用戶可能更改的每個尺寸都應是模組層級的具名常數，且名稱中需包含單位：
bore_d_mm、wall_t_mm、post_h_mm。主體中除 0、1 和 2 外，不得有裸數字。 - 公開
build() -> Part函式。gen.py會呼叫它。 - 將參數分組為
INTERFACE區塊（由標準決定的尺寸，並附有標準 ID 註解）和DESIGN區塊（您可自由選擇的尺寸）。 - 在函式內部推導所有計算出的尺寸，切勿在模組層級推導，這樣
--param覆蓋才能實際生效。 - 宣告一個
interfaces()函式，回傳零件必須配合的所有尺寸，每個尺寸需包含其標準 ID 與用途。這使得介面可以在步驟 5 中由機器檢查。intent為"envelope"（當特徵必須容納任何合格零件時，例如凹槽、孔或槽——在最大實體狀態加上您的間隙後進行單邊檢查）或"match"（當此零件本身必須符合規範時，對稱帶狀）。clearance是預期的總間隙（單位為毫米），且必須為非負值。僅宣告那些約束此零件配合特徵的尺寸——配合設備的屬性（例如桌面的邊界、典型的板厚）不是您的介面。如果沒有適用的已捆綁標準，請回傳[]。 - 宣告一個
checks()函式，內含從建構實體量測的通過/不通過量規：一個clear區域，用於所有必須穿過或放入的物體（螺絲軸、光束通道、處於最大實體狀態且掉入凹槽的配合零件）；一個material區域，用於所有必須保留的物體（脊、邊緣、螺絲座）；以及一個bbox_*邊界，用於用戶所述的每個尺寸限制。將請求中的每個幾何要求映射到一個條目；這些可以捕捉is_valid、邊界框和宣告的數值無法發現的錯誤。gen.py在每次生成時執行它們，並在失敗時使建構失敗。結構與範例：references/build123d-patterns.md。 - 將製程、材料和每個介面來源放入模組的檔案 docstring 中。
"""用於客製化載物台插入件的 SLAS 微孔盤托架。
製程：FDM，PETG，0.2 mm 層厚。公差預算 +/-0.3 mm。
介面：
- 盤凹槽：ANSI/SLAS 1-2004 (R2012) 腳印 127.76 x 85.48 mm，+/-0.25。
- 載物台螺栓：用戶測量，中心距 40.0 mm（圖面位於 docs/stage.pdf）。
"""
from build123d import *
# --- 介面（由標準決定；請勿調整）---
plate_l_mm = 127.76 # ANSI/SLAS 1-2004 標稱值
plate_w_mm = 85.48 # ANSI/SLAS 1-2004 標稱值
plate_tol_mm = 0.25 # ANSI/SLAS 1-2004；凹槽尺寸為標稱值加上此公差
# --- 設計（自由）---
pocket_clearance_mm = 0.40 # 每側間隙；FDM，請參閱 fabrication-limits.md
wall_t_mm = 3.0
floor_t_mm = 2.5
body_h_mm = 12.0
def pocket_mm() -> tuple[float, float]:
"""在盤的最大實體狀態下，加上每側間隙的凹槽尺寸。
根據標稱值決定的凹槽會導致大約一半的合格盤卡住。
"""
growth = plate_tol_mm + 2 * pocket_clearance_mm
return plate_l_mm + growth, plate_w_mm + growth
def interfaces() -> list[dict]:
"""此零件必須配合的尺寸。`check.py interfaces` 會驗證每個條目。"""
pocket_l, pocket_w = pocket_mm()
return [
{"feature": "盤凹槽長度", "standard": "slas-microplate-footprint",
"dimension": "footprint_length", "value": pocket_l,
"intent": "envelope", "clearance": 2 * pocket_clearance_mm},
{"feature": "盤凹槽寬度", "standard": "slas-microplate-footprint",
"dimension": "footprint_width", "value": pocket_w,
"intent": "envelope", "clearance": 2 * pocket_clearance_mm},
]
def checks() -> list[dict]:
"""從建構實體量測的量規。根據**需求**的數值（盤的 MMC、用戶的高度限制）
來決定尺寸，而不是根據凹槽參數，這樣錯誤的參數就無法縮小量規以匹配錯誤的幾何形狀。"""
depth = body_h_mm - floor_t_mm
return [
{"feature": "處於 MMC 的盤可落入凹槽",
"clear": {"box": (plate_l_mm + plate_tol_mm, plate_w_mm + plate_tol_mm, depth),
"at": [(0.0, 0.0, floor_t_mm + depth / 2)]}},
{"feature": "載物台高度低於 15 mm", "bbox_z": {"max": 15.0}},
]
def build() -> Part:
pocket_l, pocket_w = pocket_mm()
with BuildPart() as carrier:
Box(pocket_l + 2 * wall_t_mm, pocket_w + 2 * wall_t_mm, body_h_mm,
align=(Align.CENTER, Align.CENTER, Align.MIN))
with Locations((0, 0, floor_t_mm)):
Box(pocket_l, pocket_w, body_h_mm, mode=Mode.SUBTRACT,
align=(Align.CENTER, Align.CENTER, Align.MIN))
return carrier.part
請參閱 references/build123d-patterns.md 以了解建構器與代數選擇、interfaces() 契約、草圖繪製、選擇器、圓角與螺紋嵌件孔。
5. 生成並執行檢查
python scripts/gen.py carrier_model.py --outdir out/
python scripts/check.py facts out/carrier.step
python scripts/check.py interfaces out/carrier.manifest.json
python scripts/check.py geometry out/carrier.step --model carrier_model.py
gen.py 也會根據剛建構的實體評估模型的 checks() 量規，列印每個 PASS/FAIL，將它們記錄在清單中，並在失敗時以非零值退出——因此，違反其自身宣告幾何形狀的零件不會在不知不覺中成為工件。check.py geometry 會針對已匯出的 STEP（即權威性工件）重新執行相同的量規。
out/ 是一個暫存慣例，並非必要條件。當用戶要求將交付物放在特定位置時，請直接在該位置生成（使用 --outdir .），或在完成前將 STEP、清單和 DXF 複製到該位置——僅存在於 out/ 目錄中的交付物不算已交付。
gen.py 會寫入 carrier.step（權威性）、carrier.stl（網格預覽和列印用）以及 carrier.manifest.json，其中記錄了原始碼雜湊、已解析的參數、已宣告的介面、函式庫版本以及量測到的邊界框、體積和有效性。清單是來源記錄——請與工件一同保存。
check.py facts 報告 is_valid、邊界框、體積、表面積、質心和實體數量。若零件報告 is_valid: false，則表示幾何形狀已損壞；請先修正原始碼再繼續。
check.py interfaces 會針對標準資料庫評估模型所宣告的每個條目，並在失敗時以非零值退出。**請清楚說明它驗證了什麼和沒有驗證什麼：**它檢查的是已宣告的數值——可以捕捉轉錄錯誤的尺寸、錯誤的標準以及使用標稱值而非 MMC 進行尺寸決定——但它從不量測建構的幾何形狀，而且一個根據與其檢查對象相同的常數計算出來的值，在建構上會以零餘裕通過。請勿將其引用為幾何形狀正確的證據；facts 和快照才是幾何形狀檢查。空的宣告清單會通過：一個與捆綁資料庫中任何項目都不匹配的零件沒有什麼可宣告的，其介面尺寸會在報告中被標記為未檢查。
對於內部特徵——凹槽、孔或槽——請使用 interfaces 而非 check.py fit，因為這些特徵不會出現在零件的外部邊界框中，而 fit 量測的是外部邊界框。僅在需要以手動方式檢查一個數值（--value footprint_length=128.81）時，或當零件自身的外形輪廓即為介面時（例如按盤腳印切割的墊片），才使用 fit。
對於組合件，請檢查零件之間是否干涉：
python scripts/check.py clearance out/carrier.step out/lid.step --min 0.3
6. 快照並實際查看
python scripts/snapshot.py out/carrier.step --out out/carrier.png
然後檢查 PNG 影像。此步驟在每次生成和每次修改後都是強制性的。確定性檢查通過並不能成為跳過它的理由：is_valid 和正確的邊界框都與在錯誤面上切割的凹槽、放置在主體外的凸台或吃掉一個特徵的圓角完全一致。這些錯誤在圖片中顯而易見，在數值中卻無法察覺。
也要了解渲染的局限性。一個遠小於框架的特徵——例如 40 毫米零件上的 0.3 毫米模具脊線、板上的埋頭孔階梯——可能無法從視圖中判斷。請勿報告您看到了影像無法解析的事物；這比不查看更糟糕。對於此類特徵，本技能配備了儀器：check.py bores 會列印每個圓柱面（直徑、軸線、位置、跨度、掃掠角），以便您可以比對...