Text-to-CAD 是一套开源的 Agent 技能库（GitHub 项目 earthtojake/text-to-cad），安装后可让 Codex、Claude Code、DeepSeek Harness 等 AI 编程 Agent 通过一句自然语言或一张参考图，生成尺寸精确、可编辑的参数化 3D CAD 模型，并导出 STEP、STL、3MF 等工程标准格式。本教程将从项目介绍、工作原理讲起，完整演示三种安装方式，并通过实战案例带你完成从一句话描述到 3D 打印文件的整个流程。
前置教程
如想快速开始学习本教程，你可能需要先完成以下前置教程：
- DeepSeek Harness 安装与使用教程，本教程以 DeepSeek Harness 作为主要 Agent 宿主演示技能安装与调用。
- DeepSeek Harness等Agent Skill安装与应用教程，帮助理解 Agent Skill 的加载机制与触发方式。
- Node.js和Npm安装与使用教程，Skills CLI 安装方式通过 npx 命令运行，需要 Node.js 环境。
- Python环境管理详解与UV的安装与使用教程，CAD 技能依赖 Python 3.11+ 运行环境，用于安装 Python 依赖。
- Codex 安装与DeepSeek v4 Flash接入教程，选择 Codex 插件方式安装时需要先准备好 Codex。
资源下载
- text-to-cad GitHub 仓库，项目源码与发布版本。
- text-to-cad 官方文档，技能用法与参考手册。
1. Text-to-CAD 是什么
1.1 从一句话到一张工程图
传统 3D 建模流程中，工程师需要在 SolidWorks、Fusion 360 或 FreeCAD 等软件中手动绘制草图、拉伸特征、装配零件，一个简单的支架往往要花费数十分钟。Text-to-CAD 把这个过程交给 AI 编程 Agent：你在对话中写下"帮我设计一个 40 毫米宽、带两个 5 毫米安装孔的 L 形铝制支架"，Agent 会自动拆解尺寸、编写参数化建模代码、调用 CAD 内核生成模型，并输出符合工程标准的 STEP 文件。
项目的核心定位是面向 Agent 的 CAD、CAE 与 CAM 技能库。它当前在 GitHub 上获得超过 1.6 万 Star，采用 MIT 协议完全开源免费，所有计算都在本地完成，模型与文件不上传云端。
1.2 项目核心特性
| 特性 | 说明 |
|---|---|
| 参数化建模 | 生成的是可编辑的 Python 参数化模型源码，改一个数字即可重新生成模型 |
| STEP 优先输出 | 主输出为工业标准 STEP 格式，可直接导入主流 CAD 软件与 CAM 流程 |
| 多格式导出 | 支持导出 STL、3MF（3D 打印）与 GLB（网页预览）格式 |
| 图纸建模 | 支持从参考图片或 2D 图纸中提取尺寸进行建模 |
| 本地运行 | CAD 内核与渲染全部在本地完成，无需 API Key、无云端依赖 |
| 多 Agent 支持 | 以 Skill 或插件形式接入 Codex、Claude Code、Cursor、Grok Build 等 Agent |
1.3 技能清单
Text-to-CAD 是一套覆盖 CAD、制造与机器人领域的技能组合，安装后 Agent 会根据任务自动选择对应技能：
| 技能 | 用途 |
|---|---|
| CAD | 核心技能，从自然语言或图片创建、编辑 CAD 模型，输出 STEP/STL/3MF/GLB |
| CAD Viewer | 启动本地浏览器预览页，查看 CAD 与机器人模型文件 |
| step.parts | 搜索螺丝、轴承、电机、连接器等现货 STEP 零件模型 |
| DXF | 生成轮廓、垫片、切割排版等 2D DXF 图纸 |
| URDF | 编写机器人结构描述文件（连杆、关节、惯性、网格） |
| SRDF | 为 URDF 补充 MoveIt 规划组、末端执行器与碰撞规则 |
| SDF | 创建仿真器模型与世界文件（坐标系、物理、传感器、灯光） |
| SendCutSend | 上传前检查 DXF/STEP 文件是否符合 SendCutSend 加工要求 |
| DfAM Check | 按工艺检查网格可打印性：壁厚、悬垂、支撑量与打印朝向 |
| G-code | 调用真实切片器 CLI，把网格文件切片为 FDM 打印的 gcode |
| Bambu Labs | 对校验过的 gcode 做试运行、上传并谨慎启动拓竹打印机任务 |
1.4 与 Blender MCP 的对比
本系列此前介绍过 Blender MCP安装配置与AI建模实战教程，它通过 MCP 协议驱动 Blender 完成建模。两者代表了 AI 生成 3D 模型的两条技术路线：
| 对比项 | Text-to-CAD | Blender MCP |
|---|---|---|
| 建模内核 | OpenCascade（工程 CAD 内核） | Blender（影视级网格建模） |
| 模型精度 | 参数化精确尺寸，毫米级 | 网格近似，尺寸精度依赖提示词 |
| 输出格式 | STEP/STL/3MF/GLB，工程标准 | blend/fbx/obj/glTF |
| 可复现性 | Python 源码即模型，可版本管理与批量修改 | 依赖操作序列回放，难以增量修改 |
| 适用场景 | 机械零件、装配体、3D 打印、机器人 | 影视道具、场景、艺术创作 |
一句话概括选型：做能加工的工程零件选 Text-to-CAD，做视觉效果选 Blender。
2. 工作原理
2.1 整体架构
Text-to-CAD 的本质是一组写入 Agent 技能目录的 Markdown 指令文件（SKILL.md）加一个名为 cadgen 的 Python 命令行工具。Agent 读取技能指令后，用大模型编写 Python 建模代码，再由 cadgen 调用 OpenCascade CAD 内核完成几何计算。整个流程如下：
自然语言或图片] --> B[Agent 宿主
Codex / Claude Code 等] B --> C[加载 CAD 技能
SKILL.md 指令] C --> D[大模型编写
Python 参数化模型] D --> E[cadgen CLI
调用 OpenCascade 内核] E --> F[输出 STEP 主文件
STL / 3MF / GLB] F --> G[快照审查与
浏览器预览] G --> H{尺寸与外观
是否达标} H -- 不达标 --> D H -- 达标 --> I[交付模型文件
与审查报告] style B fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style D fill:#d6eaf8 style E fill:#d5f5e3 style G fill:#fadbd8
流程中的关键设计是验证闭环：技能要求 Agent 在生成几何后必须生成快照图片并自查，尺寸不符时回到模型源码修正后重新运行，直到满足要求才交付。
2.2 模型即源码：Python 装饰器契约
Agent 生成的每个模型都是一个普通 Python 脚本，其中包含一个用装饰器标记的无参数函数，函数返回 build123d 几何对象。下面是技能文档中的官方示例 src/bracket.py：
from cadgen import build123d as bd
from cadgen import step
WIDTH = 40.0
@step(out="../STEP/bracket.step")
def bracket():
body = bd.Box(WIDTH, 20, 6)
body.label = "bracket"
return body
if __name__ == "__main__":
bracket()
运行 python src/bracket.py 即可在 STEP/ 目录生成 bracket.step 文件。这种设计带来三个好处：
| 好处 | 说明 |
|---|---|
| 可复现 | 模型就是源码，放进 Git 即可追踪每次设计变更 |
| 可增量修改 | 想改宽度只需改 WIDTH = 40.0 一个数字再运行 |
| 可组合 | 装配体模型可以调用子模型并声明相对位置，父模型重新运行即同步子件变更 |
2.3 输出格式说明
| 格式 | 定位 | 生成方式 |
|---|---|---|
| STEP | 主输出，工程交换标准，含精确几何 | @step 装饰器，每次运行自动生成 |
| STL | 3D 打印通用网格格式 | @stl 装饰器或 cadgen stl build 命令 |
| 3MF | 3D 打印现代格式，含颜色与单位信息 | @threemf 装饰器或 cadgen 3mf build 命令 |
| GLB | 网页与 AR 预览格式 | @glb 装饰器或 cadgen glb build 命令 |
3. 安装 Text-to-CAD
3.1 环境要求
| 依赖 | 要求 | 用途 |
|---|---|---|
| Python | 3.11 及以上 | 运行建模代码与 cadgen 工具 |
| Node.js | 18 及以上 | 仅 Skills CLI 安装方式需要，用于 npx 命令 |
| Agent 宿主 | Codex 0.142.0+ / Claude Code / DeepSeek Harness 等 | 承载技能、驱动大模型 |
| Chromium | 由 Playwright 自动安装 | CAD Viewer 渲染快照与预览页 |
Windows 11 用户请先阅读 6.1 节的 Smart App Control 说明，再决定在 Windows 还是 WSL 中安装，避免安装完成后运行报错。
3.2 方式一：Skills CLI 安装（推荐）
Skills CLI 是官方推荐的安装方式，一条命令即可把技能装进当前机器上已支持的各类 Agent。在终端执行：
npx skills add earthtojake/text-to-cad
安装过程会列出识别到的 Agent（如 Claude Code、Codex、Cursor 等），按提示选择要安装的目标即可。安装完成后技能文件会出现在对应 Agent 的技能目录中。
两点使用约定需要注意。其一，更新与安装使用同一条命令：add 会重新拉取最新包并覆盖已安装技能，同时装上新版新增的技能；npx skills update 只刷新锁文件里已有的技能，会漏掉新版新增的技能。其二，若某个技能在上游被移除，需要手动执行 npx skills remove <技能名> 清理。
3.3 方式二：Codex 插件安装
如果你主要使用 Codex，可以用插件方式安装，要求 Codex 版本不低于 0.142.0：
codex plugin marketplace add earthtojake/text-to-cad
codex plugin add cad@text-to-cad
旧版本 Codex 会静默跳过该插件，codex plugin list 中看不到任何条目。遇到这种情况先用以下命令升级 Codex 后重试：
npm install -g @openai/codex@latest
3.4 方式三：Claude Code 插件安装
Claude Code 用户可执行：
claude plugin marketplace add earthtojake/text-to-cad
claude plugin install cad@text-to-cad
DeepSeek Harness 等兼容 Claude Code 技能目录的 Agent，建议改用 3.2 节的 Skills CLI 方式安装，安装后如果技能列表中没有出现新技能，重启 Agent 即可。
3.5 安装 CAD 技能的 Python 依赖
技能文件本身只是指令，真正的几何计算依赖需要按技能要求安装到项目解释器中。先在任意目录验证 Python 版本：
python --version
确认输出为 3.11 及以上后，找到技能安装目录中的 cad/requirements.txt（Skills CLI 安装时通常位于 Agent 技能目录下，可在安装输出中查看具体路径），执行：
python -m pip install -r /path/to/installed/cad/requirements.txt
python -m playwright install chromium
其中依赖的核心包有两个：cadgen 是技能配套的命令行工具，负责运行模型、导出格式、生成快照；build123d 与 OCP 提供参数化建模 API 与 OpenCascade 几何内核。
3.6 验证安装
text-to-cad 提供了自诊断命令 cadgen doctor，它会检查技能包版本与 CAD 内核是否可用：
cadgen doctor /path/to/installed/cad
输出中确认包版本与内核加载均无错误，即表示安装成功。若提示 cadgen 命令不存在，可用等价写法 python -m cadgen.cli 替代，例如：
python -m cadgen.cli doctor /path/to/installed/cad
4. 实战：从一句话到 3D 模型
本章以 DeepSeek Harness 为例，完成第一个 AI 建模任务。其他 Agent 的操作完全一致，只是入口不同。
4.1 创建建模项目
text-to-cad 推荐使用固定的项目目录结构组织 CAD 工程。先建好骨架：
mkdir -p cad-demo/src cad-demo/STEP cad-demo/tmp
cd cad-demo
目录约定如下：src/ 存放模型源码，STEP/、STL/ 等按格式存放输出文件，tmp/ 存放审查快照等临时产物。之后启动 Agent 并进入该目录开始对话。
4.2 用自然语言描述零件
在 Agent 对话框中输入需求。描述越具体，首次成功率越高。推荐按"零件用途 + 关键尺寸 + 特征细节"三段式描述：
在当前目录创建一个 CAD 项目，用 CAD 技能建模一个 L 形安装支架：
底板长 60mm、宽 40mm、厚 5mm，立板高 35mm、厚 5mm，
底板上有两个直径 5mm 的通孔，孔中心距两端各 10mm。
建模完成后导出 STEP，并生成快照给我确认。
Agent 会自动加载 CAD 技能，拆解尺寸后在 src/ 下生成参数化模型脚本，运行脚本生成 STEP/l_bracket.step，再用 cadgen 生成快照图片自查，全程无需人工干预。
4.3 理解 Agent 生成的模型代码
打开 Agent 生成的 src/l_bracket.py，你会看到与 2.2 节示例同构的结构：文件顶部导入 cadgen 提供的建模模块，尺寸以大写常量集中声明：
PLATE_LENGTH = 60.0
PLATE_WIDTH = 40.0
THICKNESS = 5.0
HOLE_DIAMETER = 5.0
完整文件以 Agent 实际生成为准。修改任何尺寸常量后重新运行脚本，即可同步更新 STEP 输出。
读懂三个要素即可接管这份代码：尺寸常量在文件顶部集中声明；几何构建逻辑在装饰器函数内完成（拉伸、打孔、倒角等 build123d 操作）；输出路径由 @step(out=...) 声明，注意该路径相对于模型脚本所在目录解析。
4.4 导出 STL 用于 3D 打印
模型确认后，让 Agent 继续导出打印格式，或者直接在项目根目录手动执行：
cadgen stl build STEP/l_bracket.step STL/l_bracket.stl
cadgen 3mf build STEP/l_bracket.step 3MF/l_bracket.3mf
生成的 STL 可直接导入 Cura、OrcaSlicer 等切片软件；3MF 则保留了单位信息，是拓竹、Bambu Studio 等切片器的推荐格式。
4.5 快照审查与浏览器预览
技能流程要求 Agent 对每次几何变更生成快照并自查，对应命令为：
cadgen step snapshot STEP/l_bracket.step tmp/review.png
如果安装了 CAD Viewer 技能，Agent 交付时会附上一个本地浏览器预览链接，可在网页中旋转、缩放查看模型。你也可以主动说"打开预览"，让 Agent 启动本地预览页面。
5. 进阶应用
5.1 按图片建模
把机械图纸、产品照片或手绘草图直接拖入对话，并补充文字约束。Agent 会从图中提取已标注的尺寸建模，对图中未标注的部分记录假设并在交付说明中列出，例如"图上未标注壁厚，按 3mm 处理"。对关键假设不满意时，直接指出并让 Agent 修改对应常量即可。
5.2 装配体建模
装配体由多个子模型组合而成。实践时按"一个零件一个源文件"组织，装配模型调用子模型并声明相对位置。Agent 收到"把 A 和 B 按某某位置装配"的指令后，会自动建立装配文件并把子件输出聚合。子零件修改后重新运行父装配脚本，装配结果随之更新。
5.3 现货零件搜索
需求中出现标准件时，告诉 Agent"优先搜索现货零件"即可触发 step.parts 技能。它会检索螺丝、轴承、电机、连接器等常见现货 STEP 模型，找到后直接引入装配；检索不到时按占位模型处理并记录假设。这一步能显著减少手绘标准件的工作量。
5.4 从 CAD 到 3D 打印的完整链路
text-to-cad 把打印前后的工序也做成了技能，串联起来就是一条完整的桌面制造流水线：
生成 STEP] --> B[DfAM Check
壁厚与悬垂检查] B --> C[G-code 技能
调用切片器切片] C --> D[Bambu Labs 技能
试运行并启动打印] style A fill:#d5f5e3 style B fill:#fadbd8 style C fill:#d6eaf8 style D fill:#ffecd6
其中 DfAM Check 按具体工艺（FDM、光固化等）测量壁厚、悬垂角、支撑体积并建议摆放朝向；G-code 技能调用本机真实切片器 CLI 生成经过校验的 gcode；Bambu Labs 技能面向拓竹打印机，支持先试运行再实际启动打印任务。
5.5 机器人描述文件
URDF、SRDF、SDF 三个技能面向机器人开发者：URDF 描述连杆与关节结构，SRDF 补充 MoveIt 运动规划组，SDF 生成 Gazebo 等仿真器的模型与世界文件。配合 CAD Viewer 可以在浏览器中直接查看机器人模型并验证逆运动学。
6. 常见问题排查
6.1 Windows 11 下 OCP 模块加载失败
这是 Windows 用户最常遇到的问题。CAD 内核 OCP（OpenCascade 的 Python 绑定）的安装包中包含未签名的原生模块，而 Windows 11 全新安装默认开启的 Smart App Control（智能应用控制）会拦截未签名原生代码，导致所有 cadgen 命令与 import build123d 报错：
ImportError: DLL load failed while importing OCP
cadgen doctor 会主动识别并报告这一情况。该拦截没有按应用放行的机制，只有两条出路：
| 方案 | 操作 | 影响 |
|---|---|---|
| 关闭 Smart App Control | 设置 > 隐私和安全性 > Windows 安全中心 > 应用和浏览器控制 > 智能应用控制设置 | 关闭后只有重装 Windows 才能重新开启 |
| 改用 WSL 运行 | 在 WSL 的 Ubuntu 环境中安装技能与依赖 | 不受该策略影响，推荐已经配置 WSL 的用户使用 |
6.2 安装后 Agent 里看不到新技能
三个排查方向：其一，重启 Agent 宿主，部分 Agent 只在启动时扫描技能目录；其二，确认技能安装到了当前使用的 Agent 目录，Skills CLI 安装时会列出目标 Agent，装错目标时重新执行 npx skills add earthtojake/text-to-cad 勾选正确目标；其三，Codex 插件方式要求 0.142.0 及以上版本，低版本会静默跳过。
6.3 技能版本过旧
新版本会新增技能与修复模型契约，执行与安装相同的命令即可完成更新：
npx skills add earthtojake/text-to-cad
更新后按 3.5 节重新安装一遍技能的 requirements.txt，保证 cadgen 版本与技能文档匹配。
6.4 生成的模型尺寸不对
把具体数字写进需求，避免"差不多""适中"这类描述；建模完成后让 Agent 执行几何检查，技能要求 Agent 用 read_scene 读取已保存的 STEP 文件实测尺寸；对仍存在的偏差，指出具体部位与目标尺寸让 Agent 修改源码重新生成。
7. 总结
7.1 核心内容回顾
- Text-to-CAD 是一套开源免费的 Agent 技能库，让 Codex、Claude Code、DeepSeek Harness 等 AI 编程 Agent 从自然语言或图片生成参数化 CAD 模型。
- 推荐用
npx skills add earthtojake/text-to-cad一条命令安装，Codex 与 Claude Code 也可用各自的插件命令安装。 - 技能安装后还需在 Python 3.11+ 环境执行技能自带的
requirements.txt安装，并用cadgen doctor验证。 - 模型即 Python 源码，尺寸是可修改的常量，STEP 为主输出，STL/3MF/GLB 按需导出。
- Windows 11 用户注意 Smart App Control 会拦截 OCP 内核，可关闭该功能或改在 WSL 中运行。
- 进阶链路覆盖图片建模、装配体、现货零件搜索、可打印性检查、切片与拓竹打印控制。
7.2 常见问题与解答
问：生成的 STEP 文件能导入 SolidWorks 或 Fusion 360 吗？
答：可以。STEP 是 CAD 行业的标准交换格式，生成的文件可直接导入 SolidWorks、Fusion 360、FreeCAD、Onshape 等主流软件继续编辑。
问：需要付费的 API Key 吗？
答：Text-to-CAD 本身完全免费且本地运行，不调用任何云端几何服务。唯一的成本来自 Agent 宿主所用大模型的调用费用，模型选择取决于你的 Agent 配置。
问：生成的模型能保证可以加工吗？
答：技能内置了验证闭环，Agent 会自查尺寸并生成快照，DfAM Check 技能还能按工艺检查壁厚与悬垂。涉及真实加工时，仍建议人工复核关键尺寸与公差后再投产后处理。
问：中文描述建模需求有效吗？
答：有效。建模指令由大模型理解并翻译为 Python 建模代码，中文、英文均可，混合标注尺寸的图片同样支持。
举手提问