text-to-cad 实测：给智能体装上 CAD 内核——参数化建模，导出 STEP/STL，本地渲染快照

给智能体"CAD 超能力"的项目最近挺火，text-to-cad（earthtojake/text-to-cad，约 2 万星，MIT）是其中一个代表性实现。它的定位不是又一个在线建模网站，而是一套跑在本地的 CAD 工具链 + agent 插件：Claude Code、Codex、Cursor、Gemini 等装上官方的插件或 skills 之后，你用自然语言描述零件，agent 调 cadgen 生成为 STEP/GLB/STL/3MF，还能做可制造性检查、出工程图、对接 3D 打印与 CNC 服务。

我把仓库拉下来完整跑了一遍：写参数化脚本、导出 STEP/STL、本地渲染快照，全程第一手。这篇是实测记录。

一、它到底是什么

拆开看是三层：

1. 插件层：面向各 agent app 的插件（claude plugin marketplace add earthtojake/text-to-cad#latest 一行装上），附带 skills 和 MCP server（cadgen mcp），让 agent 能调用 CAD 能力并在对话里看模型（viewer card）；
2. 引擎层：核心包 cadgen（PyPI 可装），底下是 build123d 0.11 + Open CASCADE 7.9 的参数化建模内核；
3. CLI 层：cadgen 命令行同时对人服务——build、snapshot、viewer、daemon、doctor、telemetry、store 一应俱全。

也就是说，agent 能用它，人也能直接用。官网 texttocad.dev，仓库 MIT。

二、安装与首次运行：走 uv 管道

和其他 Python 工具不同，它通过 uv 运行（README 明确 "CAD runs through uv"）：

uvx cadgen --help

agent 场景下的安装更简单——直接把仓库地址丢给 agent："Install text-to-cad from https://github.com/earthtojake/text-to-cad"，或手动装插件。

两个首次运行的注意点（我都遇到了）：

• 首次启动会下载 CAD 运行时：Chrome Headless Shell 约 115MB + FFmpeg + Winldd（渲染快照用），需要联网，下载完进 uv 缓存复用；
• 遥测默认开启：发用量统计和崩溃报告（随机 ID，不含文件/路径/prompt），介意的话 uvx cadgen telemetry off 一键关。

三、实测：写一个四孔垫片

我写了一个最简单的参数化零件——40×40×5 的四孔垫片（spacer.py，472 字节）：

from cadgen import build123d as bd
from cadgen import step

PLATE = 40.0
THK = 5.0
HOLE_R = 3.0


@step(out="spacer.step")
def spacer():
    plate = bd.Box(PLATE, PLATE, THK)
    holes = [
        bd.Pos(x, y) * bd.Cylinder(HOLE_R, THK)
        for x in (-PLATE / 2 + 6, PLATE / 2 - 6)
        for y in (-PLATE / 2 + 6, PLATE / 2 - 6)
    ]
    plate = plate - sum(holes[1:], holes[0])
    plate.label = "spacer"
    return plate


if __name__ == "__main__":
    spacer()

运行（uv 会自动解析 cadgen 依赖，输出 JSON 进度流）：

uv run --with cadgen python spacer.py

实测输出（约 4.8 秒）：

{"model":"...spacer.py","state":"building","phase":"Writing outputs","elapsed":1.144}
{"model":"...spacer.py","state":"building","phase":"STEP saved","elapsed":1.276}
[cadgen] wrote STEP: spacer.step
built spacer.step

然后导出 STL 和渲染快照（注意 OUT 是位置参数，不是 --out，我第一次用 --out 直接被拒）：

uvx cadgen stl build spacer.step spacer.stl
uvx cadgen step snapshot spacer.step spacer.png

三个产物全部拿到：spacer.step（31KB，Open CASCADE 7.9 生成）、spacer.stl（67KB，二进制网格）、spacer.png（131KB 渲染图，四孔和板体清清楚楚）。整个流程从写脚本到出图不到一分钟。

四、CLI 面：这是给 agent 也给人用的双面工具

cadgen --help 的真实命令清单（节选）：

• step build / step compile / step snapshot：STEP 的重发射（可加运动学、材质、动画）、树编译、渲染；
• stl / glb / 3mf build + snapshot：网格导出与渲染；
• mcp：MCP server（agent 宿主接入用）；
• viewer：起本机 CAD Viewer；
• daemon / daemon status：热构建守护进程；
• doctor / store / telemetry：自检、模型仓库管理、遥测开关。

这个命令面说明它不是"玩具"——build daemon、store、DFM 都是工程化部署才会有的东西。

五、坑与边界

1. 系统 Python 装不到它：cadgen 走 uv 管道，我在两个系统 Python 里 import cadgen 全部失败——别往系统 site-packages 里装，用 uv run --with cadgen 或 uvx；
2. 首次运行要下载 115MB 运行时：离线/代理环境首次启动会卡在下载，提前让 uv 缓存热好；
3. CLI 的输出参数是位置参数：cadgen stl build in.step out.stl，没有 --out；
4. 参数化建模本质还是写 Python（build123d API）："自然语言出模型"那层在 agent 侧；要手工精修复杂曲面，传统 CAD 软件仍然更顺手。

六、小结

text-to-cad 把"CAD 内核 + agent 接口 + 本地 CLI"三件事打包在一起，对两类人都有价值：用 agent 工作流的——一句话出可制造的参数化模型；不碰 agent 的——uvx cadgen 就是一个顺手的 build123d/Open CASCADE 命令行。MIT 协议，试错成本很低。

参考与署名：本文实测项目为 earthtojake/text-to-cad（MIT License，2026-10-13 克隆实测）；核心依赖 build123d 0.11 / Open CASCADE 7.9；文中示例与产物均为笔者实跑生成。