text-to-cad：用自然语言生成 3D 模型的 AI CAD 插件部署指南

text-to-cad 是一个面向 AI 编码 Agent 的本地 CAD 插件，发布在 PyPI 上的包名叫 cadgen。它让你的 Agent 用自然语言或图片需求生成可制造的 3D 模型，输出格式覆盖 STEP、GLB、STL 与 3MF，同时还能做可制造性设计检查（DFM）、生成带尺寸的工程图纸（PDF），并对接主流的 3D 打印、钣金与 CNC 加工服务。它支持所有主流插件或 skills 框架，包括 Claude Code、Codex、Cursor、Gemini 与 Grok。

它的工作方式是三步：Agent 先把每个模型写成一段基于 build123d（底层是 Open CASCADE）的 Python 脚本；运行 python model.py 时，cadgen 的引擎把模型构建成 .xbf 文档（包含零件、名称、颜色、材质与关节）以及脚本声明的 STEP/GLB/STL/3MF 文件，引擎把模型留在内存里，所以一次编辑只重建改动的部分；CAD 查看器在你的 Agent 应用或浏览器里实时显示模型，并跟随每次重建刷新。

这种"脚本即模型"的设计带来一个好处：模型不再是某个私有二进制文件里的黑盒，而是一段可读、可版本管理、可 diff 的 Python 代码。你可以把它提交进 Git，和队友在代码评审里讨论"为什么这个圆角是 R5"，也可以让 Agent 在旧脚本基础上做增量修改，而不是每次重新生成一份模型。.xbf 作为中间文档，把几何、零件结构、颜色、材质和装配关节统一描述出来，供后续查看、出图与制造环节复用。

一、项目官方信息

二、项目背景

传统 CAD 建模依赖工程师在 SolidWorks、Fusion 等软件里逐点拖拽草图、拉伸、倒角，学习曲线陡，且把一个想法变成可加工的 STEP 文件往往要几小时。text-to-cad 把这件事反过来：你用一句"帮我做一个带 M3 螺纹孔、壁厚 3mm 的电机支架"描述需求，Agent 自动生成 build123d 脚本并在本地构建出模型，再导出成可送进 3D 打印机或 CNC 机床的文件。

它的价值不止于"生成模型"，更在于打通了从设计到制造的闭环：模型建好后可以做钣金、CNC 加工、注塑成型的 DFM 审查，量出拔模角、倒扣与投影面积；可以生成带尺寸线、隐藏线、孔标注与标题栏的工程 PDF；可以切出 G-code 发到 Bambu Lab 打印机，或在上传 SendCutSend 这类钣金服务前做预检。所有计算都在本地完成，不上传你的设计文件。

之所以强调"本地"，是因为 CAD 模型往往是企业的核心设计资产，上传到云端生成服务意味着图纸、尺寸、工艺细节都要交给第三方。text-to-cad 把建模内核（Open CASCADE / OCP）和 cadgen 引擎都跑在你自己的机器上，Agent 只负责生成 build123d 脚本，真正的几何求解在本地完成。这样既保留了大模型"听懂人话"的交互优势，又守住了设计数据不出内网的底线。对小团队与独立硬件开发者来说，这相当于用自然语言免费拥有了一个随时待命的 CAD 工程师。

三、核心特性

• CAD 建模：从自然语言或图片需求生成 Python 脚本，构建为 XBF 文档，导出 STEP、STL、3MF、GLB。
• 标准件库（step.parts）：直接查找螺丝、轴承、电机、连接器等现成 STEP 标准件。
• 工程图纸：从零件生成带视图、隐藏线、尺寸、孔标注与标题栏的 PDF 工程图。
• 2D DXF：从 Python 源码或 CAD 几何生成轮廓、模板、垫片与切割布局。
• 机器人描述文件：URDF（连杆、关节、限位、惯性、网格）、SRDF（MoveIt 规划组、末端执行器、碰撞规则）、SDF（仿真模型与世界）。
• DFM 与 DfAM 检查：针对钣金、CNC、注塑做可制造性审查，逐条给出测量证据与引用规则；DfAM 按工艺评估壁厚、悬垂、支撑体积与构建方向。
• 制造对接：G-code 切片（基于 OrcaSlicer，用你自己的打印机预设）、Bambu Lab 打印发送、SendCutSend 上传前检查。
• 本地查看器：插件自带 cadgen mcp 本地服务器，浏览器里用 cadgen viewer 查看模型。

这套技能库覆盖了从设计到打样的整条链路：CAD 技能负责把想法变成三维模型，step.parts 负责调用标准件减少重复建模，Engineering Drawing 与 DXF 负责出图，URDF/SRDF/SDF 面向机器人与仿真场景，DfAM 与 DFM 负责可制造性审查，G-code、Bambu Labs 与 SendCutSend 负责把模型送进真实的打印机或加工服务。你可以把它理解成一个"装配好的 Agent 工具箱"，而不是孤立的建模脚本。

四、环境要求

• Python 运行时：支持 Python 3.11 及以上；官方启动命令使用 uv 托管的 Python 3.13。
• uv 包管理器：CAD 通过 uv 运行，先执行 uv --version 确认已安装，缺失则按 uv 官方安装脚本装好。
• 首次启动联网：插件第一次启动会下载 CAD 运行时，需要网络连接。
• Windows 11 注意：CAD 内核 OCP（OpenCascade 的 Python 绑定）的 wheel 自带未签名原生模块，Windows 11 默认开启的 Smart App Control 会拦截，导致每个 cadgen 命令和 import build123d 都报 ImportError: DLL load failed while importing OCP。要么在系统设置里关闭 Smart App Control（关闭后只能通过重装 Windows 才能恢复），要么在 WSL 里运行 CAD 技能。

由于 CAD 计算量不小，官方建议在有足够内存的机器上使用；复杂装配体或高分辨率网格导出时，渲染与切分会占用较多 CPU。对团队服务器，可以把 cadgen 作为本地 MCP 服务常驻，让多个 Agent 共享同一套 CAD 引擎，而不是每人各装一份。

五、部署步骤

方式一：让 Agent 自动安装（推荐）

直接把下面这句话发给你的 Agent（Claude Code、Codex、Cursor、Gemini、Grok 等），它会替你完成安装：

Install text-to-cad from https://github.com/earthtojake/text-to-cad

插件会带上 skills 与 CAD 查看器（一个本地服务器 cadgen mcp）；对没有插件的 Agent，则只装 skills。注意在一个应用里二选一，不要插件和 skills 都装，否则每个技能会出现两份。

方式二：手动本地安装（Claude Code）

先确认 uv 可用，然后执行：

claude plugin marketplace add earthtojake/text-to-cad#latest
claude plugin install text-to-cad@earthtojake

插件会同时启动 CAD 服务器。在能显示应用视图的环境里，模型以 viewer 卡片形式出现在对话中；在终端里则会给你一个链接，用浏览器在 CAD Viewer 中打开。更新时执行 claude plugin marketplace update earthtojake 与 claude plugin update text-to-cad@earthtojake，再重启 Claude Code。

其他 Agent 的命令：Codex 在插件目录搜索安装，或手动 codex plugin marketplace add earthtojake/text-to-cad --ref latest；Cursor 可 git clone --depth 1 --branch latest https://github.com/earthtojake/text-to-cad ~/.cursor/plugins/local/text-to-cad；Gemini 用 gemini extensions install https://github.com/earthtojake/text-to-cad --ref latest --consent --auto-update；Grok Build 用 grok plugin install earthtojake/text-to-cad@latest --trust。

方式三：无插件 Agent 用 skills CLI 安装

npx skills add earthtojake/text-to-cad#latest

它会询问你要装给哪个 Agent、装到哪里；想跳过问答可加 -g -a <agent> -y。没有插件就没有 CAD 服务器，skills 会直接在浏览器里的 CAD Viewer 打开模型。注意安装命令默认取 latest 分支：该分支只含插件本身，每次发布到 PyPI 后才更新；main 是开发分支，可能包含尚未发布的改动。每个应用用不同写法指定分支（#latest、--ref latest、@latest 或 --branch latest），省略不写就会装 main，生产环境建议锁定 latest。

方式四：浏览器网页端查看模型（cadgen viewer）

cadgen 自带一个 localhost 的网页查看器。安装好后，在任意支持 MCP 的客户端里让它"显示某个模型"，终端类 Agent 会返回一个本地链接，用浏览器打开即可旋转、缩放、查看模型；插件模式下则在对话内以 viewer 卡片呈现，你可以环绕观察、把所选区域加进提示词，Claude 还能读取你选中的内容、看到你所看到的。

Claude Desktop 也可以手动配置 MCP：在 设置 → Developer → Edit Config 里加入下面这段，重启即可；如果找不到 uvx，用 which uvx 拿到完整路径填进去：

{
  "mcpServers": {
    "cad": {
      "command": "uvx",
      "args": ["--no-config", "--managed-python", "--python", "3.13", "--from", "cadgen==0.8.1", "cadgen", "mcp"],
      "env": {"CADGEN_INSTALL_CHANNEL": "claude-desktop"}
    }
  }
}

六、使用方法

安装并重启 Agent 后，直接用自然语言下需求即可，例如："用 build123d 写一个带两个 M3 沉孔、长 80mm、壁厚 2.5mm 的电机安装支架，并导出 STEP 与 STL"。Agent 会生成脚本、调用 cadgen 构建、在查看器里显示结果，再按你的反馈迭代。由于引擎把模型留在内存里，你改一句"把壁厚改成 3mm"，它只重建受影响的部分，而不是从头重算，迭代很快。

想检查可制造性时，让它做一次 DFM 审查：它会量出壁厚、拔模角、倒扣等并逐条引用规则给出依据；想送 3D 打印时，让它用 OrcaSlicer 切片出 G-code 并发到 Bambu Lab；想出工程图时，让它生成 PDF 工程图。版本迁移方面，为 cadgen 0.7 写的工程需要按官方迁移指南移植到 0.8，带 CAD 技能的 Agent 可以照指南一步步完成。更新插件时，新版 cadgen 会在首次运行时自动下载，旧版本留在 uv 缓存里，用 uv cache prune 可清理。

遥测默认开启，按随机安装 ID 统计使用量与崩溃报告，绝不包含你的文件名、路径、内容或提示词；关闭命令为 uvx --no-config --managed-python --python 3.13 --from cadgen==0.8.1 cadgen telemetry off，也可在应用菜单里关掉，或设 DO_NOT_TRACK=1 / CADGEN_TELEMETRY=0。

典型的使用场景包括：硬件创业者快速验证一个外壳的装配尺寸、工程师为机器人项目生成 URDF 描述文件、创客把想法直接切片发到自己的 Bambu Lab 打印机、钣金打样前用 SendCutSend 预检避免浪费材料。对团队而言，把生成脚本纳入 Git 还能让设计变更可追溯——每次改了哪个尺寸、谁改的、为什么改，都和代码评审一样留痕。

与传统"对话式 3D 生成"服务相比，text-to-cad 的差别在于它输出的是参数化、可重新计算的工程几何，而不是一张不可编辑的三角网格。你说"壁厚改成 3mm"，它改的是脚本里的参数，引擎据此重建几何，尺寸、公差、装配关系都是可控、可复查的。这对真正要把零件送进机床或打印机的人来说至关重要——艺术化的概念模型不能直接加工，而 STEP/STL/G-code 才是制造环节认的格式。

七、常见问题 FAQ

Q：Windows 11 上一跑 cadgen 就报 DLL 加载失败？ A：这是 Smart App Control 拦截了 OCP 的未签名原生模块，事件查看器会记录 Event ID 3077。要么关闭 Smart App Control（只能靠重装 Windows 恢复），要么在 WSL 里运行 CAD 技能。

Q：插件和 skills 都装了会怎样？ A：不要在同一个应用里都装，否则每个技能会出现两份。有插件就用插件，没有插件再用 npx skills add 只装 skills。

Q：生成的模型是什么格式？能直接送打印吗？ A：默认构建成 .xbf 文档，并按脚本声明导出 STEP、GLB、STL、3MF。STL/3MF 可直接切片打印；STEP 可送 CNC 或钣金服务；上传前建议先跑 DFM 与 SendCutSend 预检。

Q：模型脚本如何升级 cadgen 版本？ A：为 0.7 写的工程需要移植到 0.8，官方提供了分步迁移指南，带 CAD 技能的 Agent 可以照着完成。

Q：遥测会上传我的设计吗？ A：不会。遥测只统计每个 CAD 工具被调用次数、失败原因固定词、导出格式数量等，按随机 ID 聚合，绝不包含文件名、路径、内容或提示词；可随时关闭。

Q：首次启动很慢/报错？ A：首次启动会下载 CAD 运行时，需要联网；确保 uv 已安装且 Python 版本满足 3.11+。离线环境下功能仍可用，只是不发遥测。

Q：Cursor 或 Grok 已经装了 Claude Code 插件还要再装吗？ A：不用。Cursor 与 Grok Build 都会加载 Claude Code 安装的插件，若 Claude Code 插件已装好，这两个应用里就已经有 text-to-cad，直接跳过即可。

Q：想给没有插件的 Agent 用怎么办？ A：用 npx skills add earthtojake/text-to-cad#latest 只装 skills，它会在浏览器里打开 CAD Viewer 看模型。如果你的 Agent 目前还没有对应插件，可以去仓库提 issue 请求一个。

八、跳转链接

总体而言，text-to-cad 把"用自然语言设计实物"变成了一条可工程化的链路：Agent 生成 build123d 脚本，cadgen 引擎本地构建出可制造的 STEP/STL/3MF，再经 DFM 检查、工程出图、切片发送送到真实的制造环节。它不追求生成不可编辑的概念模型，而是输出参数化、可版本化的工程几何，这正是它能真正服务硬件开发的原因。

• GitHub 仓库：earthtojake/text-to-cad
• 官方网站：texttocad.dev
• 安装文档：texttocad.dev/install
• PyPI 包：cadgen
• 隐私政策：privacy-policy
• 底层建模库：gumyr/build123d
• 社区：Discord
• 问题反馈：GitHub Issues