lab-hardware-cad

实验室硬件 CAD

将实体科研硬件设计为参数化 Python 源代码，导出 STEP 作为权威制品，并在制造前通过数值和视觉检查验证结果。

实验室硬件最难的几乎从来不是几何形状，而是零件必须与尺寸由已发布标准或供应商图纸固定的设备配合。支架宽了 0.5 mm，就装不进酶标仪；通道的纵横比不正确，粘合时就会塌陷；安装座的螺栓孔距若为 25.4 mm 而不是 25.0 mm，就无法安装到光学平台上。这项技能旨在确保这些尺寸正确且经过检查。

适用场景

适用于任何设计、建模或制造实验室实体零件的请求：芯片、模具、安装座、转接件、支架、机架、托架、外壳、夹具、治具、实验场或迷宫。也适用于检查或修改现有 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。即使未安装 build123d，check.py standards 也能运行。

模型文件会被执行，而不是解析。 gen.py、check.py 和 snapshot.py 会导入 *_model.py 并调用其 build()，这会在当前环境中运行任意 Python 代码。这是参数化 CAD 的固有特性——源代码就是设计。仅运行在本次会话中编写的模型文件，或由用户从可信位置提供的模型文件。如果模型来自互联网、共享驱动器或不可信的同事，请先阅读再运行，并说明你已这样做。

必需工作流

按顺序执行以下步骤。第 5 步和第 6 步不可省略；即使第 5 步通过，也不能免除第 6 步。

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 mm 的公差；SLA 树脂通常未经后固化和测试，不适合接触细胞。

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"；零件本身必须符合规范时（对称公差带），intent 为 "match"。clearance 是预期总间隙，单位为 mm，且不得为负数。只声明会限制本零件配合特征的尺寸——配套设备的属性（例如桌边缘的边界、常见板材厚度）不属于你的接口。如果没有适用的内置标准，返回 []。
• 声明一个 checks() 函数，用于定义以构建出的实体测量的通止规：为所有必须通过或适配的部分定义 clear 区域（螺杆、梁通道、落入凹槽的最大实体状态配合零件）；为所有必须保留的部分定义 material 区域（凸脊、凸缘、螺钉座）；并为用户指定的每项尺寸限制定义一个 bbox_* 边界。将请求中的每项几何要求映射到一项检查；这些检查能捕获 is_valid、边界框和声明数值无法发现的错误。gen.py 会在每次生成时运行这些检查，任何一项失败都会导致构建失败。模式和完整示例见：references/build123d-patterns.md。
• 在模块文档字符串中写明加工工艺、材料以及每项接口的来源。

"""SLAS microplate carrier for a custom stage insert.

Process: FDM, PETG, 0.2 mm layer.  Tolerance budget +/-0.3 mm.
Interfaces:
  - Plate pocket: ANSI/SLAS 1-2004 (R2012) footprint 127.76 x 85.48 mm, +/-0.25.
  - Stage bolts: user-measured, 40.0 mm centres (drawing in docs/stage.pdf).
"""
from build123d import *

# --- INTERFACE (fixed by standard; do not tune) ---
plate_l_mm = 127.76   # ANSI/SLAS 1-2004 nominal
plate_w_mm = 85.48    # ANSI/SLAS 1-2004 nominal
plate_tol_mm = 0.25   # ANSI/SLAS 1-2004; the pocket is sized to nominal + this
# --- DESIGN (free) ---
pocket_clearance_mm = 0.40   # per-side; FDM, see fabrication-limits.md
wall_t_mm = 3.0
floor_t_mm = 2.5
body_h_mm = 12.0


def pocket_mm() -> tuple[float, float]:
    """Pocket at the plate's maximum material condition plus clearance per side.

    A pocket sized from nominal jams on roughly half of conforming plates.
    """
    growth = plate_tol_mm + 2 * pocket_clearance_mm
    return plate_l_mm + growth, plate_w_mm + growth


def interfaces() -> list[dict]:
    """What this part must fit. `check.py interfaces` verifies every entry."""
    pocket_l, pocket_w = pocket_mm()
    return [
        {"feature": "plate pocket length", "standard": "slas-microplate-footprint",
         "dimension": "footprint_length", "value": pocket_l,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
        {"feature": "plate pocket width", "standard": "slas-microplate-footprint",
         "dimension": "footprint_width", "value": pocket_w,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
    ]


def checks() -> list[dict]:
    """Gauges measured from the built solid. Sized from the REQUIREMENT's numbers
    (plate MMC, the user's height limit), not from the pocket parameters, so a
    wrong parameter cannot shrink the gauge to match the wrong geometry."""
    depth = body_h_mm - floor_t_mm
    return [
        {"feature": "plate at MMC drops into the pocket",
         "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": "under 15 mm for the stage", "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

关于 builder 与 algebra 的选择、interfaces() 约定、草图绘制、选择器、圆角和螺纹嵌件孔，请参阅 references/build123d-patterns.md。

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 重新运行相同的检查项；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 mm 零件上的 0.3 mm 模具凸棱，或板件上的沉孔台阶——可能根本无法通过视图判定。不要声称看到了图像无法分辨的内容；这比不查看更糟。对于这类特征，该技能提供了检测工具：check.py bores 会打印每个圆柱面（直径、轴线、位置、跨度、扫掠角度），以便你核对钻孔与模型意图是否一致；check.py probe 则无需编辑模型，即可回答一次性的“此区域是否畅通／此处是否有材料”问题。请引用测量数值；对于图片，只报告图片实际显示的内容。

六个视图都是真正的正投影，轮廓线是模型的真实边线，且不执行隐藏线消除。因此，透过材料可见的圆，是远侧的孔，而不是窗口——零件并不透明。请按此方式解读，不要报告并不存在的孔。

请在回复中说明你在快照中看到了什么，而不只是说你生成了快照。

7. 通过源代码修复

如果任何检查未通过，请编辑参数或模型代码，重新运行 gen.py，然后重新执行第 5 步和第 6 步。切勿修改 STEP 文件。

8. 制作前先报告

按照 references/validation.md 完成检查，并向用户说明：工艺和材料、每个接口尺寸及其来源和公差、所选间隙、快照显示的内容，以及任何未通过的检查。

明确标出自动检查无法覆盖的每个接口——例如供应商图纸、用户测量值或捆绑数据库中没有的标准。check.py interfaces 只会报告模型声明且符合已知标准的内容，因此没有报告不代表已确认；无法检查的尺寸必须明确指出。

单位

build123d 内部不使用单位，本技能中的所有数值均以毫米和度为单位。调用 export_step 时使用 Unit.MM。光机结构中经常会用到英制硬件（1/4-20 螺钉、1 英寸网格、SM1 螺纹）；在定义位置将其换算为毫米，并使用一个有名称的常量，表达式中绝不要混用单位制。1 英寸恰好等于 25.4 mm，25 mm 公制光学网格不能与 1 英寸英制网格互换——四个孔的误差会累积到 1.6 mm。

公差和配合

标称尺寸不等于配合尺寸。每个配合尺寸都需要根据 references/fabrication-limits.md 中的工艺公差，审慎选择间隙。常用默认值（每侧）：

配合	FDM	SLA	CNC
可自由滑动（板件置于凹槽中）	0.40 mm	0.20 mm	0.10 mm
定位但可拆卸	0.25 mm	0.10 mm	0.05 mm
压入／过盈	-0.05 mm	-0.03 mm	-0.02 mm

这些值是首次试制的起点，并非保证值。报告这些值时请说明这一点，并建议在制作完整零件前，先打印关键接口的测试样件。

科学注意事项

• 材料兼容性至关重要。 几何完美但聚合物选错的零件，实际使用中仍会失效：高压灭菌循环会使 PLA 变形，许多溶剂会使亚克力产生龟裂，而未固化的 SLA 树脂具有细胞毒性。对于任何会接触细胞、组织、溶剂或热量的用途，推荐材料前请先查看 references/fabrication-limits.md。
• 光学零件还有非几何要求。 自发荧光、表面粗糙度和杂散光散射无法从 STEP 文件中看出。黑色树脂不一定具有低散射特性。
• 供应商的实验室耗材各不相同。 SLAS 标准规定了微孔板的占地尺寸，但未规定孔的几何形状、裙边轮廓或盖子的配合情况；不同供应商的耗材管也存在差异。有标准时应按标准设计；否则必须进行测量。
• 包围盒检查通过不代表零件合格。 fit 只会检查提供给它的尺寸。它无法发现缺失的特征，也不能取代快照检查。

参考资料

文件	内容
references/microfluidics.md	通道横截面和纵横比、模具与芯片的极性、不同工艺的最小特征尺寸、接口和管路连接、键合面、死体积
references/optomechanics.md	光学面包板网格和螺钉间隙、支杆和底座高度、30 mm 笼式结构几何形状、SM 镜筒螺纹、光束高度
references/labware-adapters.md	ANSI/SLAS 1-4 微孔板尺寸、比色皿、试管、载玻片、培养皿、平台和载物台的限制
references/behavior-rigs.md	场地和迷宫几何形状、头部固定接口、出液口和接口、T 型槽铝型材、清洁和耐用性
references/fabrication-limits.md	工艺公差、最小壁厚和特征尺寸、间隙和螺纹嵌件、材料、高压灭菌、溶剂和生物相容性
references/validation.md	制作前检查清单，以及每项检查可发现的失效模式
references/build123d-patterns.md	build123d 0.11.1 API 指南：构建器与代数模式、草图、选择器、关节、导出

脚本

命令	用途
gen.py <model.py> --outdir DIR	运行 build()，导出 STEP 和 STL，并写入溯源清单
gen.py <model.py> --dxf [--dxf-z MM]	同时切片生成用于激光切割的 2D DXF 轮廓（默认平面：中高位置）
check.py facts <step>	检查有效性、边界框、体积、面积、质心和实体数量
check.py interfaces <manifest|model.py>	根据标准检查每个声明的接口编号；失败时以非零状态退出
check.py geometry <model.py|step --model M>	根据构建的实体评估模型的 checks() 量规——测量所得，而非声明所得
check.py probe <step> --cyl D|--box X,Y,Z --at ...	单项临时量规：检查此区域是否没有材料，还是被材料填充
check.py bores <step>	统计所有圆柱面：直径、轴线、位置、跨度和扫掠角
check.py fit --standard ID --value DIM=MM	手动检查一个尺寸，或检查外包络即为接口的零件
check.py clearance <a> <b> --min MM	计算两个实体之间的最小距离；检测干涉
check.py standards [--list|--show ID]	浏览随附的标准数据（仅使用标准库）
snapshot.py <step> --out PNG	生成六视图正交投影和等轴测渲染图，供目视检查

所有命令均接受 --json 以输出机器可读数据，并将进度写入 stderr。 未安装 build123d 时，仍可运行 check.py standards，以及针对清单运行 check.py interfaces。

Agent 操作流程

1. 检查环境。 确认仪器或平台型号、API 版本、凭据，以及是否有可用的模拟器。
2. 确定输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的数值都应询问，不要猜测。
3. 先运行小规模版本。 在使用真实样本前，先模拟该协议，或用水或虚拟实验室器具运行。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 核实体积、平台布局和实验室器具定义；执行前由人工批准协议。
6. 报告。 说明运行内容（版本、命令、参数）、已检查的事项，以及仍不确定的内容。

如果发生这种情况	应这样处理
协议在模拟中失败	在模拟中修复；绝不要在未经验证的情况下在硬件上运行协议。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自身的文档（help()、--help、官方文档），调整做法并告知用户。绝不要编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 绝不捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证，须明确说明。
• 未经用户明确确认，绝不触发实际操作、下单或收费。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档加以确认。
• 涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作时，须先征求同意。

相关技能

• fictiv：在用户的浏览器中操作 Fictiv 按需制造 Web 应用（app.fictiv.com），因为它没有公开 API。