Text-to-CAD:给编码代理装 CAD 超能力的开源插件与技能套件

一句话定位

text-to-cad 是一个装进编码代理的 CAD 插件与技能套件:给 Claude Code、Codex、Cursor、Gemini、Grok 等代理一条「把自然语言或一张参考图变成参数化 CAD 模型」的本地工作流,主交付物是 STEP,并可导出 STL、3MF、GLB。它同时做可制造性审查、生成带尺寸的工程图纸,并对接 3D 打印、钣金与 CNC 加工服务。仓库 2026 年 4 月开源,MIT 协议,到 2026 年 10 月已有约 2.06 万星、2 千 fork;内核是 build123d 与 OpenCascade 的 Python 绑定 OCP,发布版 cadgen 在 PyPI 上,当前版本 0.7.21,官网 texttocad.dev。

仓库本身有三张脸。skills/ 是产品本体,十二个技能覆盖建模、标准件检索、图纸、制造审查、机器人描述与切片发送;packages/cadgen 是发布到 PyPI 的引擎与命令面;models/ 是随仓库维护的示例与机器人描述夹具,从行星齿轮级、六轴工业臂到研究用人形与腱驱动手。根目录同时就是插件包:.claude-plugin、.codex-plugin、.cursor-plugin、gemini-extension.json 与 mcp.json 全部在根上,安装器跟随的 latest 分支只放插件清单,每个发布提交一次。

十二个技能:从建模到出厂

技能	职责
CAD	自然语言或图片创建/编辑参数化模型,主输出 STEP,可导出 STL、3MF、GLB
step.parts	检索螺丝、轴承、电机、连接器等标准件 STEP
Engineering Drawing	由零件生成带尺寸的工程图纸 PDF:视图、隐藏线、尺寸、孔标注、标题栏
DXF	由 Python 源码或 CAD 几何生成二维 DXF:轮廓、模板、垫片、排样
URDF	写机器人结构:连杆、关节、限位、惯量、网格
SRDF	为 URDF 补 MoveIt 规划组、末端执行器、姿态与碰撞规则
SDF	建仿真模型与世界:坐标系、物理、传感器、灯光
SendCutSend	上传 SendCutSend 前检查 DXF 与 STEP
DfAM Check	按工艺测网格可打印性:壁厚、悬垂、支撑体积、摆放方向
DFM	钣金、CNC、注塑审查,每条结论带测量证据与引用规则
G-code	用 OrcaSlicer 与用户自己的打印机预设切片出可打印 G-code
Bambu Labs	经 Bambu Connect、官方应用或 Bambu Studio 发送打印

分工有一条清晰的线:CAD 技能拥有任何三维零件,DXF 技能拥有它的二维投影;机器人结构交给 URDF、SRDF、SDF 三个技能;制造侧的 DFM 与 DfAM 只出带测量证据与引用规则的结论,从不改几何;G-code 与 Bambu Labs 把模型送进真实打印机。

运行模型:一条启动命令,一个常驻构建守护进程

所有入口共用同一条 uvx 启动命令(uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.21 加子命令),插件的 MCP 服务、代理的每个线程、每个技能里的命令行都指向同一个安装,因而共享同一个常驻构建守护进程与它的构建池。模型是一段普通 Python:一个无参函数被 @step、@dxf、@stl、@glb、@threemf 或 @eng_drawing 装饰,返回 build123d 形状;python model.py 是唯一的源码入口,它过门禁、构建、写出装饰器声明的全部产物。命令行只吃文档:cadgen step build、cadgen snapshot 等子命令的输入是已保存的 STEP 或 STL 文件,缺树时按字节在构建池里编译,绝不解析脚本。

十九条设计法:把「看起来对」挡在门外

packages/cadgen/README.md 把架构写成十九条「法」,每条附一个动手前的压力测试。其中最硬的几条:生成文件与源码彻底解耦——删光项目里的 .py,渲染结果不变,因为 sidecar 里的运动学是解析后的数字与标签;store(~/.cache/cadgen)只存派生结果,内容寻址、默认 20GB 上限、任何时候可删可重建;字节确定性是 writer 的承诺而不是内核的承诺,内核两次运行可能差最后一位,相等字节只意味着复用,比较两次构建要按几何容差而不是文件哈希;装饰器参数永远不改几何,它只决定文件落在哪、怎么写、sidecar 声明什么,历史上违反这条的 kinematics 烘焙点与 kind 参数两个特性被直接删除;缓存围绕模型运行而不进入其中,脚本在 cadgen 里与在裸 Python 里的每一步相等性判断答案必须相同;安装完成之后,任何命令、构建、快照、服务与页面都不等网络。

第十条法是整份文档的道德底线:响亮失败或正确输出,二者之间没有东西。退出码 0 却给出「看起来对」的错文件被列为头号罪;没有静默回落、没有通配符猜测,渲染失败的请求路径上不留任何文件。

看模型:CAD Viewer 与 MCP Apps 的两种宿主形态

cadgen viewer 是一个本地 HTTP 服务(默认端口 3245),按绝对路径服务本机任何 CAD 文件;cadgen mcp 则是 MCP Apps 服务器,宿主在 initialize 时被区分:声明 tab 入口的宿主(如 Codex)得到侧边栏主页、每个线程一个 CAD 标签页与「用 CAD 打开」;其余 MCP Apps 宿主(如 Claude Desktop)在对话里挂载内联卡片,新卡片让旧卡片退役为最后一帧的静帧。每个视图有自己的历史,前进后退与浏览器同语义;代理能读视图、截图,也能把人选中的内容取回上下文。

机器人一侧:URDF、SRDF、SDF 与随仓夹具

对具身智能社区,这个仓库的接口是三个机器人描述技能:URDF 写连杆、关节、限位、惯量与网格;SRDF 补 MoveIt 的规划组、末端执行器、姿态与碰撞规则;SDF 建仿真模型与世界,带坐标系、物理、传感器与灯光。models/ 里的夹具不是玩具:研究用人形带左右手分件与共享库,腱驱动手、六轴工业臂、月球车角总成、猎鹰重型的公开资料复现都在其中;每个 cad 项目同构——src/ 放作者代码,格式文件夹放产物,产物一律 gitignore,新 clone 跑一遍脚本即可再生成。

制造与交付:结论必须带证据

DFM 技能按钣金、CNC 或注塑审查零件,每条结论都带测量证据与它引用的规则,从网格量拔模角、倒扣与投影面积;DfAM 按工艺测壁厚、悬垂、支撑体积与摆放方向;SendCutSend 技能在上传前检查 DXF 与 STEP;G-code 技能用 OrcaSlicer 与用户自己的打印机预设切片,Bambu Labs 技能经 Bambu Connect、官方应用或 Bambu Studio 发送打印。工程图纸技能则把零件变成带视图、隐藏线、尺寸、孔标注与标题栏的 PDF。

工程治理:发布即合并,测试面巨大

改 VERSION 的 PR 就是发布 PR,合并即发布:Publish Release 工作流找到记录了该树全量测试的 Test 运行,构建插件 ZIP、bundle 与 wheel,安装并实际跑一遍 wheel,上传 sourcemap 与 PyPI,等 PyPI 索引列出它之后才把插件单独提交到 latest 与 claude-plugin 分支,再部署文档站、打 tag。仓库的测试面以百计:tests/python 下数百个文件覆盖 store、守护进程、STEP 写回、快照与 viewer 路由,viewer 还有一套 golden 快照。遥测默认开启但只发计数与固定词表的失败原因,从不发文件名、路径、内容或提示词,一条 uvx cadgen telemetry off 关闭并删除已发数据。

边界与诚实

它不做云端 CAD,也不做网格提取:交付物是程序化、可 diff、可版本控制的参数模型与其 STEP 工件。内核 OCP 的 wheel 未签名,Windows 11 的 Smart App Control 会拦下它,仓库文档直接写明这条坑与 WSL 的绕法,而不是假装兼容。对代理而言,它的价值是把「设计一个零件」从 GUI 操作变成一次可审查、可重试、可进 CI 的代码运行——这正是机器人结构、夹具与末端执行器设计需要的形态。