build123d 0.11.1 建模模式精要scientific-agent-skills 中 lab-hardware-cad 技能的几何编程实战指南【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本指南是 lab-hardware-cad 技能配套的 build123d 0.11.1 API Cookbook 的系统化展开面向用参数化 Python 源码设计实验室硬件并导出可制造文件这一核心工作流。文章以 build123d-patterns.md 为骨架结合仓库内 gen.py、check.py、_common.py 等脚本源码与 standards.json 标准数据库逐一拆解接口声明、几何量规、定位对齐、孔洞沉孔、选择器圆角、草图拉伸、多格式导出等模式并总结 12 类真实踩坑点。读完你可以写出符合本技能契约、可被--param覆盖、可被机器校验的 build123d 模型并理解每个模式背后的实现原理。文中所有代码片段均针对 build123d 0.11.1 Python 3.12 验证通过与 SKILL.md 声明的一级依赖build123d0.11.1、matplotlib3.8保持一致。模型文件契约gen.py 眼中的一个好模型在进入具体 API 之前先明确本技能对模型文件的硬性契约定义于 SKILL.md 的工作流第 4 步并由 gen.py 强制每个可被用户改动的尺寸都必须是模块级命名常量且单位写进名字bore_d_mm、wall_t_mm、post_h_mm。除 0、1、2 外函数体内不允许出现裸数字。暴露build() - Partgen.py会调用它。参数分成INTERFACE块由标准固定的尺寸标注标准 ID和DESIGN块可自由选择的尺寸。暴露interfaces()函数声明本零件必须配合的标准尺寸第 4 步机器可校验的基础以及checks()函数声明从实体上实测的通过/不通过量规第 5 步构建门禁。工艺Process、材料Material、每个接口的来源写在模块 docstring 里。gen.py 的命令行形态决定了这些约束的由来python scripts/gen.py carrier_model.py --outdir out/ python scripts/gen.py carrier_model.py --outdir out/ --param wall_t_mm4.0 python scripts/gen.py plate_model.py --outdir out/ --dxf # 2D 激光切割轮廓其中--param支持重复传入KEYVALUE解析逻辑在 _common.py值会被自动收窄为bool/int/float/str随后在import_model()中通过setattr(module, key, value)直接改写模块属性_common.py并且在导入时即应用——这正是派生尺寸必须放进函数这一铁律的根源下文会展开。Builder 模式还是代数模式build123d 提供两套等价 API本技能推荐混合使用但同一个build()内绝不混用# Builder 模式上下文管理器收集操作mode 控制布尔运算 with BuildPart() as ex: Box(80.0, 60.0, 10.0) Cylinder(radius11.0, height10.0, modeMode.SUBTRACT) part ex.part # 代数模式普通对象与运算符 part Box(80.0, 60.0, 10.0) - Cylinder(radius11.0, height10.0)本技能中的零件一律使用 Builder 模式。理由有三都与技能工作流直接相关选择器ex.edges()、ex.faces()从 builder 上下文读取十分自然这是倒角fillet和在已找到的面上放置特征如把沉孔放在顶面的必要前提gen.py、check.py、snapshot.py都约定调用build()返回builder.part见 _common.py 的run_model而 Builder 对象本身不是 Part代数模式更适合短小、纯构造性的形状作为理解布尔的速记即可。声明接口让内部特征可被机器校验实验室硬件的多数接口是内部特征——沉孔pocket、孔bore、槽slot它们不会出现在零件外包围盒bounding box上。因此check.py fit无法通过测量 STEP 找到它们而手工把数字再敲进--value恰恰重新引入了本技能要消灭的转写错误。interfaces()声明就是为了闭合这个回路gen.py 在每次生成时把声明写进 manifestcheck.py 的interfaces子命令逐一校验。契约模板与字段语义def interfaces() - list[dict]: return [ {feature: cage rod bore spacing, standard: cage-system-30mm, dimension: rod_spacing, value: rod_spacing_mm, intent: match}, {feature: cage rod bore diameter, standard: cage-system-30mm, dimension: rod_diameter, value: rod_bore_d_mm, intent: envelope, clearance: 0.4}, ]键含义standard来自check.py standards --list的标准 IDdimension该标准内部的一个尺寸名value本模型算出的数字单位 mmfeature校验输出中的人类可读标签默认取尺寸名intentmatch本零件自身必须符合标准envelope该特征必须能容纳任意合规零件默认matchclearance期望的总间隙单位 mm两侧合计默认 0_common.py 的normalise_interfaces()给出了校验细则standard、dimension、value三键必填且value必须可转浮点数intent只接受match或envelopeclearance默认 0.0。而 check.py 的_evaluate()揭示了两种 intent 的数学差异match以名义值为中心的对称带被 clearance 加宽绝不平移——low nominal - tol_minus - offsethigh nominal tol_plus offsetenvelope单侧最小下限low nominal tol_plus offset——即最大实体条件MMC名义值 正公差加 clearanceactual low即通过。若按名义值设计容纳特征只会适配合规零件中较小的那一半。offset 0会被直接拒绝check.py负 clearance 相当于声明自己移动验收带、认证一个不合格值这是该技能明确禁止的编码行为。用函数而不是静态列表# 错误--param plate_tol_mm0 静默地让 pocket_l_mm 停留在旧值 pocket_l_mm plate_l_mm plate_tol_mm 2 * pocket_clearance_mm # 正确每次调用都重算覆盖才能生效 def pocket_l_mm() - float: return plate_l_mm plate_tol_mm 2 * pocket_clearance_mm原因在 gen.py模块级的INTERFACES [...]列表在 import 时即求值——早于--param应用——任何由被覆盖参数派生的值都会被错误记录。gen.py一旦发现静态 INTERFACES 列表 --param的组合就打印警告。同样的原则适用于几何本身所有派生尺寸都在build()或辅助函数内部计算绝不在模块级。声明几何检查对着实体实测的 go/no-go 量规interfaces()只把声明数字与标准数据库比较从不触碰实体。checks()是它的实测对应物一系列布尔量规通过与build()实际产出的零件做布尔交集来求值。gen.py 每次生成都运行这些量规、逐条打印 PASS/FAIL、把结果写进 manifest并在任一失败时以非零码退出——违反自身声明几何的零件永远不会静默变成交付物。check.py 的geometry子命令则对已导出的 STEP权威工件重跑同一组量规。核心原则请求中的每个几何要求都映射为一个条目——必须穿过的东西螺丝、光束、探针→clear区域必须落入空腔的东西放入 pocket 的板→ 按配合零件最大实体条件尺寸的clearbox必须保留的东西脊、台阶、螺丝座→material区域用户声明的尺寸上限 →bbox_*边界。def checks() - list[dict]: top plate_t_mm / 2 return [ # clear 区域不得有材料侵入螺丝轴贯穿零件 {feature: M6 screws pass all four bores, clear: {cylinder: 6.0, axis: z, at: bolt_xy()}}, # 带显式区间的净空离台面 15 mm 高处的光束走廊 {feature: beam clear at 15 mm above the bench, clear: {cylinder: 5.0, axis: x, at: [(0.0, 15.0)]}}, # 量规零件必须落入 pocketMMC 下的配合件 {feature: SLAS plate at MMC drops into the pocket, clear: {box: (128.01, 85.73, pocket_depth_mm()), at: [(0.0, 0.0, floor_t_mm pocket_depth_mm() / 2)]}}, # 沉孔真的得是沉孔凹槽顶部敞开、座面存在。 # 第二条才是抓住凹槽贯穿到底的关键。 {feature: counterbore recess open at the top, clear: {cylinder: cbore_d_mm - 0.2, axis: z, at: bolt_xy(), span: (top - cbore_depth_mm 0.1, top 0.1)}}, {feature: screw seat present below the recess, material: {cylinder: cbore_d_mm - 0.2, axis: z, at: bolt_xy(), span: (-top 0.1, top - cbore_depth_mm - 0.1)}, min_mm3: 50.0}, # 用户声明的硬性上限从实体实测 {feature: clears the objective turret, bbox_z: {max: 15.0}}, ]量规模式语义键含义clear/material该区域必须不含材料 / 必须含材料{cylinder: DIA, axis: x\|y\|z, at: [(a, b), ...], span: (lo, hi)}at是垂直于轴平面上的 2D 坐标——轴 z(x, y)轴 x(y, z)轴 y(x, z)。省略span则贯穿整个零件{box: (dx, dy, dz), at: [(x, y, z), ...]}轴对齐盒形量规以各位置为球心中心点tol_mm3/min_mm3每个位置的通过阈值clear 侵入体积上限 / material 材料体积下限默认均 0.01bbox_x…bbox_z、bbox_min/mid/max实测包围盒的{min: mm, max: mm}边界区域校验规则在 _common.py 的_normalise_region/normalise_checks中逐项强制cylinder 直径必须 0、轴只能是 x/y/z、at坐标数量与轴向匹配、box 三边必须 0每个条目必须恰好拥有clear、material或一个bbox_*测量之一否则抛错。实测求值在evaluate_checks()_common.py对每个位置实体化量规 solid圆柱沿轴、at平面定位盒在 3D 中心与零件做布尔交集并累计体积——clear要求每位置侵入体积 ≤tol_mm3material要求每位置材料体积 ≥min_mm3。注意intersection_volume()_common.py对内核返回None、空Compound或无.volume的ShapeList一律按 0 处理这正是相切或分离实体的布尔结果是空的而非错误这一坑的工程化应对。量规尺寸从要求自身的数字来只有当要求是关系型的凹槽位于座面之上才用与几何相同的命名常量去度量规当要求是绝对型的——配合件的 MMC、用户的高度限制、光束位置——就用量规自身的要求数字这样错误的参数无法把量规缩小到与错误几何匹配。不改模型的一次性探针与钻孔普查对不改模型的一次性问题check.py 的probe子命令直接从命令行运行单个量规python scripts/check.py probe out/part.step --cyl 6.6 --at 37.5,37.5 --at -37.5,37.5 python scripts/check.py probe out/part.step --box 40,40,5 --at 0,0,7 --expect material而bores子命令输出每个圆柱面的普查直径、轴、位置、跨度、扫掠角用于与模型意图对账_common.py 的cylinder_census约 360° 扫掠的圆柱面是孔/轴约 90° 扫掠的是边倒角沉孔则是沿轴堆叠的两个同心全扫掠面、半径不同。这正是 SKILL.md 第 6 步渲染图分辨不出 0.3 mm 特征时的仪器化替代。定位螺栓阵列与微孔板井格Locations将其内部创建的对象整体放置是螺栓阵列的主力with Locations((10.0, 0.0), (-10.0, 0.0)): # 当前平面上的两个位置 Hole(radius3.3) with Locations((0.0, 0.0, floor_t_mm)): # z 方向偏移 Box(10.0, 10.0, 5.0, modeMode.SUBTRACT) with GridLocations(9.0, 9.0, 12, 8): # x 间距, y 间距, x 数量, y 数量 Hole(radius1.5)GridLocations把网格居中于原点而微孔板井格是按板角定标的所以要计算绝对坐标再交给Locationsa1_x_mm, a1_y_mm, pitch_mm 14.38, 11.24, 9.0 # slas-well-positions-96 origin_x -plate_l_mm / 2 origin_y plate_w_mm / 2 wells [ (origin_x a1_x_mm pitch_mm * col, origin_y - a1_y_mm - pitch_mm * row) for row in range(8) for col in range(12) ] with Locations(*wells): Hole(radiuswell_clear_d_mm / 2)这些数字的来源可在 standards.json 中核实slas-well-positions-96定义的well_pitch名义值 9.0 mm、a1_offset_x14.38 mm左外沿到第 1 列中心、a1_offset_y11.24 mm顶外沿到 A 行中心且每个井心须落在名义位置的 0.70 mm 位置公差带内——本技能的命令行入口正是check.py standards --show slas-well-positions-96。微孔板的外轮廓则来自slas-microplate-footprintfootprint_length127.76 mm、footprint_width85.48 mm±0.25 mm角区 12.7 mm 内测量侧边中点处放宽到 ±0.5 mm。对齐经典切穿地板 bug默认情况下对象以原点为中心。align移动基准点通常正是你想要的——让 pocket 从底面开始Box(x, y, z, align(Align.CENTER, Align.CENTER, Align.MIN)) # 坐落在 z 0 Box(x, y, z, align(Align.MIN, Align.MIN, Align.MIN)) # 角点在原点这个搞错就是经典的pocket 切穿地板故障——snapshot.py 生成的多视图 PNG 正是为捕捉这类问题而存在的SKILL.md 第 6 步是强制步骤不因确定性检查通过而豁免。SKILL.md 的示例模型carrier_model.py中Box(..., align(Align.CENTER, Align.CENTER, Align.MIN))配合Locations((0, 0, floor_t_mm))的Mode.SUBTRACTbox就是对齐 抬升的教科书组合主体坐底、掏空从底板顶面开始。孔沉孔的工作平面陷阱Hole贯穿整个零件CounterBoreHole与CounterSinkHole增加头部凹槽。CounterBoreHole从其所放置的工作平面向下切凹槽就在该平面上。在居中的Box上默认工作平面是零件的中间高度所以 2 元组位置会把螺丝座埋进板内——或者在薄板上让凹槽吞掉整个顶部留下一个螺丝头直接掉下去的直通孔。正确的做法是放在顶面上或给位置一个显式的顶部 zwith BuildPart() as plate: Box(60.0, 60.0, 10.0) # 覆盖 z -5 .. 5 top plate.faces().sort_by(Axis.Z)[-1] with Locations(top): with Locations((20.0, 20.0)): CounterBoreHole(radius6.6 / 2, counter_bore_radius11.0 / 2, counter_bore_depth6.5)counter_bore_depth要从螺丝头高度取而不是凭习惯M6 内六角圆柱头螺丝头高 6.0 mm1/4-20 头高 6.35 mm后者记录在 standards.json 的optical-breadboard-metric的screw_head_height中counterbore_dia11.0 mm 对应 M6 沉头孔径。4 mm 的沉孔会让两种头都高出 2 mm——别把这种叫齐平。生成后在快照或剖面里确认凹槽位于顶面且座面台阶存在这两种失败模式都能让is_valid和包围盒原样通过。另外牢记打印孔会偏小参见 fabrication-limits.mdFDM 与 SLA 的 6.0 mm 建模孔通常实测不足 6.0 mm功能孔要么放大要么计划铰孔。standards.json 中optical-breadboard-metric的clearance_hole_normal6.6 mm正是打印件优先的数字。选择器安全地倒角与圆角选择器用于找出要倒角、圆角或在其上构建的边与面。本技能需要的三个part.edges().filter_by(Axis.Z) # 保留平行于 Z 的边竖直棱角 part.edges().group_by(Axis.Z)[-1] # 最高 Z 的那一组顶部边 part.faces().sort_by(Axis.Z)[-1] # 单个最高面 part.edges().filter_by(GeomType.CIRCLE) # 只留圆形边filter_by保留所有匹配项group_by按键分区成列表[-1]是最后一组、[0]是第一组sort_by对单项排序。with BuildPart() as ex: Box(80.0, 60.0, 10.0) chamfer(ex.edges().group_by(Axis.Z)[-1], length4.0) # 顶面边倒角 fillet(ex.edges().filter_by(Axis.Z), radius5.0) # 竖直棱角圆角这些宽泛选择器只在零件仍是纯长方体时安全。一旦零件有了 pocket、孔、槽或微结构filter_by(Axis.Z)和group_by(Axis.Z)[-1]也会选中那些特征的边圆角要么抛内核错误Failed creating a fillet、BRep_API: command not done要么——更糟——成功并悄悄吃掉一面墙或一条 0.3 mm 的脊。两种都在实践中发生过。因此在添加内部特征之前对外部主体圆角/倒角或用位置、长度、GeomType刻意过滤选择只留下目标边附近几何紧张时用part.max_fillet(edges)约束半径——它返回内核在该边集上实际能构建的最大半径每个圆角/倒角半径都是命名参数内核失败时回退数值而不是对抗选择器然后检查快照被吃掉的特性在图片里一目了然在is_valid里隐形。草图后拉伸非图元轮廓与激光切割 DXF轮廓不是图元时画草图再拉伸with BuildPart() as bracket: with BuildSketch() as profile: Rectangle(40.0, 20.0) with Locations((15.0, 0.0)): Circle(radius4.0, modeMode.SUBTRACT) extrude(amount6.0)这也是通向激光切割 DXF 的路径——草图就是切割轮廓。gen.py 的_export_dxf就是这条路径的成品实现默认在零件中间高度切片因为坐落在构建板上的零件在 z0 处只有退化面把剖面平移回 z0否则 DXF 写入器会对非平面形状告警再把切割几何放到命名层CUT层色ColorIndex.RED因为激光加工商把功率/速度映射到层或颜色上。导出STEP 是唯一权威gen.py负责这些但作为参考export_step(part, part.step, unitUnit.MM) # 权威工件 export_stl(part, part.stl, tolerance1e-3, angular_tolerance0.1) # 激光切割的 2D 剖面。section() 是模块级操作不是形状的方法—— # part.section(...) 会抛 AttributeError。 from build123d.exporters import ColorIndex # 不在 from build123d import * 里 profile section(part, Plane.XY.offset(z_mm), modeMode.PRIVATE) profile profile.moved(Location((0, 0, -z_mm))) # 移回 z 0否则 DXF 写入器 # 会警告非平面形状 exporter ExportDXF(unitUnit.MM) exporter.add_layer(CUT, colorColorIndex.RED) # 激光加工商把功率/速度映射到层 exporter.add_shape(profile, layerCUT) exporter.write(part.dxf)切面要穿过材料而不是在 z0坐落在构建板上的零件在那里只有退化面。gen.py --dxf默认取零件中间高度可用--dxf-z覆盖gen.py 还会在只给了--dxf-z而没给--dxf时直接报错。导出的其他参数化入口--toleranceSTL 线性偏差默认 0.001、--angular-tolerance角度偏差默认 0.1、--no-stl。STEP 保留精确的 BREP 几何STL 是三角化近似。始终以 STEP 为真值源网格从它重新生成绝不反向。在代码里测量在模型内部断言接口时很有用bbox part.bounding_box() print(bbox.size.X, bbox.size.Y, bbox.size.Z) print(part.volume, part.area) print(part.is_valid) # 0.11.1 里是属性不是方法 print(part.center(CenterOf.MASS))is_valid是属性而非方法这是与旧版本及部分文档的真实差异访问时不要带括号。check.py 的facts子命令正是这些测量的工程化集合is_valid、包围盒、体积、面积、质心、实体数且is_valid: false时以非零码退出_common.py 的_is_valid甚至对属性 vs 方法两种形态做了兼容。易踩坑清单12 个真实教训is_valid是属性。part.is_valid()抛TypeError: bool object is not callable。section()是模块级操作不是方法。part.section(Plane.XY)抛AttributeError。应调用section(part, plane, modeMode.PRIVATE)。intersect()返回没有.volume的ShapeList运算符返回有.volume的Solid。check.py 的clearance子命令两者都处理先试交集体积再退化为最小距离。永远不要把脚本命名为inspect.py放在会进入sys.path的目录里。它会遮蔽标准库inspect破坏typing_extensions进而连 build123d 一起搞坏。这正是本技能内置脚本叫check.py的原因。Builder 对象不是 Part。返回builder.part而不是 builder。Mode.SUBTRACT需要已存在的体。在空上下文里做减法会静默地什么都不发生。扫掠或拉伸的轮廓默认以其路径/平面为中心除非你对齐。沿曲面路径扫掠Rectangle(w, h)会让半个轮廓沉到曲面下方——一条0.3 mm 的脊其实是 0.15 mm 突出。传align并在轮廓平面上给显式x_dir让轮廓落在你以为的位置然后测量结果。Curve没有.length。对边求和sum(e.length for e in curve.edges())。相切或分离实体的布尔结果是空的不是错误。取决于路径你会得到None、空Compound或无.volume的ShapeList——在任何干涉检查里读取.volume之前先做守卫_common.py 的处理即是范例。ColorIndex和LineType住在build123d.exporters不在顶层命名空间from build123d import *带不进它们add_layer(color1)会失败。OpenCascade 内核会抛多种异常类型。在布尔运算周围宽泛捕获并报告失败而不是让 traceback 逃逸gen.py 与 _common.py 均如此处理。孔洞建模后的沉孔/倒角陷阱见上文选择器与孔两节——特征选择错误与工作平面错误都既过得了is_valid、也过得了包围盒检查只能靠快照与check.py bores普查来发现。配套材料与下一步SKILL.md完整工作流8 步路由到器件族 → 建立接口尺寸 → 先选工艺 → 参数化建模 → 生成与检查 → 快照目检 → 源码修复 → 制造前报告以及全部命令的速查表。fabrication-limits.md工艺公差与最小特征、配合间隙表自由滑动 FDM 0.40 / SLA 0.20 / CNC 0.10 mm 每侧、螺纹与热熔嵌件、材料热/化学/生物相容性。standards.json11 个内置标准slas-microplate-footprint、slas-microplate-height、slas-microplate-flange、slas-well-positions-96/384/1536、cuvette-standard-10mm、optical-breadboard-metric/imperial、cage-system-30mm、sm1-lens-tube-thread全部可由check.py standards --list / --show浏览。gen.py / check.py / _common.py / snapshot.py本文引用的所有契约、校验与渲染逻辑的源码所在。器件族参考microfluidics.md、optomechanics.md、labware-adapters.md、behavior-rigs.md以及制造前清单 validation.md。编写模型时请记住技能的底线模型文件是被执行的而非被解析的——只运行本会话编写或用户可信来源提供的模型界面尺寸永远查标准文件或问用户绝不凭记忆写STEP 是权威工件绝不手改导出文件也绝不从网格逆向重建。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考