技能使用指南

build123d-cad(build123d参数化CAD建模)Skill 是什么?

想用 Python 脚本做参数化 3D 建模?build123d-cad 技能支持一键导出 STEP/STL/SVG,内置尺寸测量、2D 截面与装配干涉、间隙、扫掠碰撞验证,输出 PASS/WARN/FAIL 结论,让设计检查可自动化。本文详解安装步骤、命令用法、竞品对比与典型场景,帮你快速上手。

build123d参数化CAD建模Skillbuild123d-cad
12 个章节 约 21 分钟阅读 AI 智能生成

build123d参数化CAD建模Skill:用一段 Python 脚本完成 3D 零件的设计、测量、验证与导出

核心结论速览

  • 这是一个把「参数化 3D CAD 建模」封装成可执行脚本的 AI 技能,基于开源 Python CAD 库 build123d,用代码而不是鼠标来设计零件与装配体。
  • 它不止能建模,还自带测量(包围盒、体积、表面积、质心、面/边数量)、截面(2D 横截面 SVG)、装配体验证(干涉、间隙、扫掠碰撞)三类工程校验能力,形成「建模—校验—导出」闭环。
  • 导出格式覆盖 STEP(给下游 CAD 用)、STL(给 3D 打印用)和 SVG(给截面/图纸用),所有结果以 JSON 形式回传,便于自动化流水线读取。
  • 首次安装只需两条命令(创建 Python 3.12 虚拟环境 + 安装 build123d),之后每次调用都是「写脚本 → 跑命令 → 拿结果」。
  • 最适合需要反复迭代尺寸的零件设计、外壳与安装件建模、多部件装配体间隙检查等场景,尤其适合把设计过程纳入版本管理与自动化流程的开发者。

一、该技能叫什么?如何一键安装 AI 技能提升开发效率?

技能基本信息

项目 内容
技能中文名 build123d参数化CAD建模Skill
技能英文名 build123d-cad
技能 ID 14405
运行依赖 需要本机具备 python3(技能元数据中声明的必需可执行文件)
版本 1.0.0

它解决什么问题

传统 CAD 软件以鼠标交互为主,改一个尺寸往往要重新点选草图、拉伸、倒角、打孔,反复几轮下来很容易出错,而且设计过程难以复现、难以版本化。这个技能把「3D 零件建模」变成一段可读、可改、可复用的 Python 脚本:尺寸写成变量,几何体由代码描述,导出与校验由命令行完成。你想把外壳厚度从 3mm 改成 3.5mm,只需改一个数字再跑一遍;你想确认运动部件在 ±45° 摆动的过程中会不会撞到壳体,也只需跑一次验证命令。

一键安装的思路与步骤

该技能的安装分为「环境准备」与「技能本身调用」两层,以下命令均来自技能说明原文。

前提条件:

  1. 本机已安装 python3;
  2. 本机具备 uv 包管理与虚拟环境工具(技能说明中的安装命令基于 uv);
  3. 已安装该技能本身,能访问技能所在的 {baseDir} 目录。

第一步:进入技能目录

cd {baseDir}

其中 {baseDir} 是该技能安装后的根目录,具体路径以你所在平台/客户端的官方说明为准。

第二步:创建 Python 3.12 虚拟环境并安装 build123d(仅首次需要)

uv venv --python 3.12
uv pip install build123d

这两条命令会在技能目录下生成 .venv 虚拟环境,并把 build123d 及其依赖装进去。之后所有脚本都通过 {baseDir}/.venv/bin/python 这个解释器来执行,不会污染系统全局 Python 环境。

第三步:验证安装是否生效

最轻量的验证方式是先调用 API 速查表脚本:

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_api.py

如果安装成功,该命令会输出一段 JSON,内容包含 build123d 的基本体、操作、选择器与导出函数等信息。能打印出这份速查表,说明虚拟环境与库都已就绪。

第四步(可选):跑一次最小建模验证全链路

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_generate.py \
  --script 'from build123d import *
with BuildPart() as result:
    Box(100, 60, 40)' \
  --format step \
  --filename my_box

成功时返回类似:

{ "success": true, "artifact_path": "...", "format": "step", "file_size_bytes": N, "bounding_box_mm": {...} }

拿到 artifact_path 即表示「脚本 → 几何体 → STEP 文件」全链路打通。导出文件默认保存到 ~/.openclaw/workspace/cad-output/(以官方说明为准)。

提示:具体的技能安装入口、界面位置、目录路径等,请以你所使用平台的官方说明为准。上述命令与参数来自技能详情,可直接参考。


二、该技能的主要功能和特点

  • 参数化实体建模:通过 BuildPart 上下文构建 3D 实体,支持 Box、Cylinder 等基本体,Locations 定位,fillet 倒角,CounterBoreHole 沉头孔等特征。技能的设计规则明确要求「所有尺寸参数化」,避免脚本里出现难以维护的「魔法数字」。
  • 多格式导出(cad_generate.py):一条命令把脚本导出为 STEP、STL 或 SVG。STEP 面向 CAD 下游流程,STL 面向 3D 打印,SVG 面向二维图纸与截面展示。
  • 几何量测(cad_measure.py):自动返回包围盒尺寸、体积、表面积、质心坐标、面数与边数,方便在导出前做「数值自查」,无需打开任何 CAD 界面。
  • 二维截面(cad_section.py):指定平面(如 XY)与偏移量,即可得到该平面上的 2D 横截面 SVG,用于检查内部结构、壁厚与间隙可视化。
  • 装配体验证(cad_validate.py):这是该技能相对普通建模脚本最突出的差异化能力。支持四种模式:
    • static:对所有部件两两做布尔交集,检测静态干涉;
    • clearance:基于包围盒计算最小间隙;
    • sweep:让运动部件在给定角度范围内旋转,检查扫掠过程中是否碰撞;
    • full:三种模式全跑(默认),并可设置 --min-clearance 阈值。 最终给出 PASS / WARN / FAIL 三档结论:PASS 表示无干涉且间隙正常;WARN 表示间隙低于阈值但无硬碰撞;FAIL 表示部件相交或运动件在扫掠中发生碰撞。扫掠体还会导出为 swept_<name>.step 便于可视化。
  • API 速查自学习(cad_api.py):不确定某个 API 怎么用时,先跑它拿速查表,降低「凭记忆写错 API」的试错成本。
  • 结构化输出:所有脚本统一把结果以 JSON 打到 stdout,字段固定(如 success、artifact_path、bounding_box_mm、verdict),非常适合被 AI 代理或自动化脚本继续解析和判断。
  • 内置设计规则:技能明确给出工程建议——应力集中处加圆角(塑料件最小 1mm、金属件最小 0.5mm)、在适用处包含凸台/支座/螺丝柱等安装特征、在注释中注明材料与加工假设、同时保留脚本与导出文件。

和普通工具比强在哪: 普通 CAD 插件通常只负责「生成文件」,而这个技能把量测与装配验证做成了同一条流水线上的标准命令,并且用 JSON + PASS/WARN/FAIL 这样的机器可读结论,让「设计是否正确」从人工目检变成可自动判定的步骤。


三、如何使用该技能?

标准工作流(技能推荐顺序)

第 1 步:先查 API,再动笔

如果对 build123d 的 API 不熟,先执行:

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_api.py

从返回的 JSON 中确认可用的基本体、操作、选择器与导出函数。

第 2 步:编写参数化脚本

单部件脚本必须把最终实体赋给 result,并且所有关键尺寸都要参数化。示例(带圆角与沉头孔的盒子):

from build123d import *

with BuildPart() as result:
    Box(100, 60, 40)
    fillet(result.edges().filter_by(Axis.Z), radius=5)
    with Locations((0, 0, 40)):
        CounterBoreHole(radius=5, counter_bore_radius=8, counter_bore_depth=3, depth=40)

注意:技能约定所有尺寸单位为毫米。

第 3 步:先测量,确认尺寸对不对

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_measure.py \
  --script 'from build123d import *
with BuildPart() as result:
    Cylinder(10, 50)'

返回示例字段:

{ "success": true, "bounding_box_mm": {...}, "volume_mm3": N, "surface_area_mm2": N, "center_of_mass_mm": {...}, "face_count": N, "edge_count": N }

用 bounding_box_mm 核对总体外形,用 volume_mm3 估算材料用量,用 center_of_mass_mm 判断重心是否偏移。

第 4 步:多部件装配体,先验证再导出

验证脚本不使用 result,而是定义 parts 字典,可选定义 sweeps 列表:

from build123d import *

with BuildPart() as enclosure:
    Box(100, 80, 50)
    offset(amount=-3, openings=enclosure.faces().sort_by(Axis.Z)[-1:])

with BuildPart() as pcb:
    with Locations((0, 0, 5)):
        Box(60, 40, 2)

with BuildPart() as servo_arm:
    with Locations((30, 0, 25)):
        Box(5, 20, 3)

parts = {
    "enclosure": enclosure.part,
    "pcb": pcb.part,
    "servo_arm": servo_arm.part,
}

sweeps = [
    {
        "name": "servo_arm",
        "axis_origin": (30, 0, 25),
        "axis_direction": (0, 1, 0),
        "angle_start": -45,
        "angle_end": 45,
        "angle_step": 5,
    },
]

然后执行:

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_validate.py \
  --script '...' \
  --mode full \
  --min-clearance 1.0

返回 verdict 为 PASS / WARN / FAIL,并附带 static_interference、clearance、swept_volume 三部分细节。技能明确要求:出现 FAIL 或 WARN 时,先修复再继续,不要直接导出。

第 5 步:导出成品文件

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_generate.py \
  --script '...' \
  --format step \
  --filename my_box
  • 下游走 CAD 流程 → --format step
  • 要送去 3D 打印 → --format stl
  • 需要二维图形 → 用 cad_section.py 或 SVG 相关导出

第 6 步:需要看内部结构时,切一张截面图

{baseDir}/.venv/bin/python {baseDir}/scripts/cad_section.py \
  --script '...' \
  --plane XY \
  --offset 5.0

返回 { "success": true, "artifact_path": "...", "plane": "XY", "offset_mm": 5.0 },打开生成的文件即可查看该平面上的截面形状。

第 7 步:交付时报告文件路径与验证结论

技能要求最终同时输出脚本与导出文件,并说明文件路径和验证结论(PASS/WARN/FAIL),便于他人复现。


四、同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
build123d-cad(本技能) 面向 AI 代理的脚本化参数 CAD 工具链 脚本建模 + STEP/STL/SVG 导出 + 测量 + 截面 + 干涉/间隙/扫掠验证 需 python3 与 uv,首次执行两条安装命令;用命令行与 Python 脚本交互 参数化零件、外壳、安装件、支架、多部件装配体校验、自动化设计流水线 优势:建模与工程校验一体化,结果 JSON 化、可自动判定 PASS/FAIL,易纳入版本管理;不足:需要写 Python,无图形化拖拽界面,复杂曲面造型仍依赖 API 熟练度
OpenSCAD 经典脚本化实体建模工具 用脚本描述几何体,导出 STL 等格式 需单独安装桌面程序;有自己的脚本语言 简单机械件、3D 打印小物件 优势:语法简单、上手快、社区大;不足:语言能力相对有限,缺少内置的装配干涉与扫掠碰撞校验,需自行搭校验流程
CadQuery Python 参数化 CAD 库 用 Python 构建实体并导出 STEP/STL 需自行配置 Python 环境并安装库;无现成命令封装 开发者自建 CAD 脚本、批量出图 优势:同为 Python 生态、灵活度高;不足:只提供库,不提供测量/验证/截面的成套脚本入口,需自己写封装
FreeCAD / 商业云 CAD(如 Fusion 类) 图形化参数 CAD 软件 草图、特征建模、装配、工程图 需安装较大客户端或使用云端账号,部分为商业授权(以官方说明为准) 需要可视化交互、复杂曲面与工程图的正式产品设计 优势:可视化直观、生态成熟;不足:难以完全脚本化与自动化,团队协作与批量迭代成本较高,难以直接被 AI 代理调用

选型建议: 如果你的核心诉求是「让 AI 或自动化脚本反复迭代同一套参数化零件,并在每轮迭代后自动判定设计是否合格」,本技能的「建模 + 测量 + 验证 + 导出」一体化封装更省事;如果你只是偶尔画个简单模型打印出来,OpenSCAD 或图形化软件可能更直接。


五、该技能的典型应用场景与实际体验情况

场景一:硬件工程师做产品外壳

痛点是外壳要反复适配内部 PCB 尺寸,每改一次板子就要重画壳体。使用方式是:把内腔尺寸、壁厚、螺丝柱位置全部写成参数,先 cad_validate.py --mode full 检查 PCB 与壳体的间隙,再 cad_generate.py --format step 出图。实际体验:改成参数后重复迭代非常快,clearance 模式能以包围盒方式直接告诉你间隙还剩多少;注意技能提示的壁厚处理(示例中用 offset(amount=-3, ...) 挖空)需要你确认开口面的选择逻辑是否正确,否则可能挖空方向反了。

场景二:机器人/舵机结构件与运动干涉检查

痛点是舵机臂摆动时是否撞到壳体,二维图纸很难判断。使用方式:定义 parts 字典和 sweeps 列表,指定旋转轴原点、方向、起止角度与步进角(如 -45 到 45、步进 5),跑 --mode sweep 或 full。实际体验:这是该技能最「超预期」的部分,扫掠体会导出到 ~/.openclaw/workspace/cad-output/swept_<name>.step,可以直接拿去可视化确认;注意扫掠是离散角度采样,步进越细越可靠,但计算量也随之上升。

场景三:3D 打印爱好者做支架与安装件

痛点是建模软件学习成本高,且改孔位很麻烦。使用方式:写一段带 CounterBoreHole 沉头孔、fillet 圆角的脚本,cad_measure.py 先看体积估算耗材,再 --format stl 导出切片。实际体验:上手难度中等,只要会一点 Python 就能跑通最小示例;建议遵循技能设计规则,塑料件圆角最小 1mm,能明显改善打印件强度。

场景四:教学与自动化设计流水线

痛点是 CAD 教学难复现、批量定制件难以自动化。使用方式:把每个零件存成独立脚本,配合 cad_api.py 速查表让学生自学 API,用 cad_section.py 输出截面图辅助讲解内部结构。实际体验:JSON 输出让批处理脚本可以直接判断 success 与 verdict,适合做成 CI 式的「设计检查」环节;注意所有尺寸单位统一为毫米,混用单位是最常见的踩坑点。


六、该技能能为用户带来的价值

  • 把重复劳动变成一次编写:参数化的最大收益是「改一个数,全模型跟着变」。同一个支架换个长度、换个孔径,不需要重新建模,脚本改完重跑即可。
  • 把「看起来对」变成「验证过对」:cad_measure.py 交付精确的体积、表面积、质心与包围盒;cad_validate.py 用 PASS/WARN/FAIL 明确回答「装得进去吗、转得开吗」。这类检查如果靠人工目检,往往要等到打样回来看实物才发现问题。
  • 降低 CAD 的入门与协作门槛:会 Python 就能建模,不需要掌握复杂软件的交互范式;脚本可进 Git、可被 Review、可被同事直接复用,设计知识从「某个人的手感」变成「团队可读的代码」。
  • 天然适配 AI 与自动化:固定字段的 JSON 输出 + 命令行入口,意味着它可以被 AI 代理或其他脚本直接编排成「生成 → 测量 → 验证 → 导出」的自动流水线,这是图形化 CAD 很难做到的。
  • 降低试错成本:在导出之前先测量、先验证,把错误挡在文件生成之前;扫掠体与截面图让「看不见的内部问题」变得可视化。
  • 长期价值:随着参数库与零件脚本积累,团队会形成一套可复用的「代码化零件库」,新项目可以直接拼装与改参,而不是从零画起。

七、常见问题 FAQ

Q1:这个技能怎么安装?需要提前准备什么?

需要本机具备 python3(技能元数据中声明的必需可执行文件),并具备 uv 工具。安装只需在技能目录下执行两条命令:先 uv venv --python 3.12 创建 Python 3.12 虚拟环境,再 uv pip install build123d 安装建模库。验证方式是运行 cad_api.py,能输出包含基本体、操作、选择器与导出函数的 JSON 即表示生效。具体目录路径与安装入口以官方说明为准。

Q2:这个技能收费吗?

技能本身在技能详情中未涉及任何定价信息,是否收费取决于你获取该技能的渠道与平台,请以官方说明为准。需要注意的是,它依赖的开源库 build123d 与工具 uv 均为独立开源项目,其许可与使用条件请参考各自官方文档。

Q3:它适合谁用?我不会 CAD 能用吗?

最适合三类人:需要反复迭代参数化零件的硬件/结构工程师、需要做装配间隙与运动碰撞检查的机器人开发者、以及习惯用代码管理一切的设计与教学人员。如果你完全没接触过编程,入门会有一段学习曲线;但如果你会一点 Python,最小示例(一个 Box)几乎可以立刻跑通。反过来,如果你需要复杂自由曲面造型或精细工程图,图形化 CAD 仍然更合适。

Q4:它和 OpenSCAD、CadQuery 这类方案怎么选?

关键看你是否需要「校验」环节。OpenSCAD 与 CadQuery 都能用脚本生成模型,但本技能的差异点在于把测量、截面、装配干涉与扫掠碰撞验证做成了标准命令,并统一以 JSON + PASS/WARN/FAIL 输出,适合嵌入自动化流程。如果你只是画个简单件打印,OpenSCAD 更轻;如果你是开发者想自己搭工具链,CadQuery 更灵活;如果你想让 AI 代理端到端完成「设计—校验—导出」,本技能的一体化封装更省事。

Q5:能导出哪些格式?验证结果 FAIL 了怎么办?

导出支持 STEP、STL,截面脚本可输出 2D 横截面 SVG;STEP 适合交给下游 CAD,STL 适合 3D 打印,文件默认保存在 ~/.openclaw/workspace/cad-output/。如果 cad_validate.py 返回 FAIL(部件相交或运动件在扫掠中碰撞)或 WARN(间隙低于 --min-clearance 阈值),技能建议的处理方式是先修复再导出:调整部件位置、加大间隙或缩小运动件尺寸,然后重新跑一次 --mode full 验证,直到结论为 PASS。