实验室硬件CAD

实验室硬件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 内核。该 wheel 包体积较大；每个项目安装一次后重复使用。

所有捆绑脚本均接受 --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树脂通常未经后固化和测试不适合接触细胞。在模型的文档字符串中记录工艺和材料。

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。
• 将工艺、材料和每个接口来源放在模块的文档字符串中。

"""用于定制载物台插件的SLAS微孔板载架。

工艺：FDM，PETG，0.2毫米层高。公差预算 +/-0.3毫米。
接口：
  - 孔板凹槽：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]:
    """从构建的实体上测量的量规。尺寸基于要求中的数值
    （孔板最大实体状态、用户的高度限制），而不是基于凹槽参数，因此
    错误的参数不能缩小量规以匹配错误的几何结构。"""
    depth = body_h_mm - floor_t_mm
    return [
        {"feature": "最大实体状态下的孔板能放入凹槽",
         "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毫米以适配载物台", "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

有关构建器与代数方法的选择、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（权威工件）重新运行相同的量规。

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 根据标准数据库评估模型声明的每个条目，并在失败时以非零退出。请明确它能验证什么和不能验证什么： 它检查声明的数值——捕获转录错误的尺寸、错误的标准以及基于标称值而非最大实体状态的尺寸——但它从不测量构建的几何结构，而且一个基于与其检查时相同的常量计算出的值，在构建时会通过且没有余量。不要引用它作为几何结构正确的证据；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 打印每个圆柱面（直径、轴线、位置、跨度、扫掠角），因此您可以对比理论设计和实际几何结构。