Text-to-CAD：面向 CAD/CAE/CAM 的 Agent 技能库

项目地址：https://github.com/earthtojake/text-to-cad  协议：MIT  Stars：16,002  更新：2026-09-17

一、产品深度介绍

（一）它是什么

Text-to-CAD 在官方仓库里的自我定位非常直接：这是「一个用于生成、检查、采购、切片以及交接 CAD 与机器人描述文件的代理技能库」。它并不是又一个带图形界面的 CAD 软件，而是一组供 AI 代理在本地项目文件上工作的「技能（skill）」。代理接到用户需求后，会调用对应技能，把自然语言或参考图转成可工程化的产物。

这套设计的核心取舍在于：把建模、校验、预览、交接这些工序从「人点按钮」改造成「代理可调用的确定性步骤」。每个技能都自带精确的命令接口与验收流程，因此产物是 STEP、STL、URDF 这类可被下游加工、仿真、打印直接消费的工程文件，而不是仅供观看的概念图。

（二）技术表现与架构

从 README 与技能文档可以归纳出它的技术骨架：

• 技能规模：库内包含 11 个技能，覆盖 CAD 建模、二维 DXF 制图、URDF/SRDF 机器人描述、SDF 仿真世界、DfAM 可打印性检查、G-code 切片与 Bambu Labs 打印对接。
• 底层引擎：所有技能命令都是 cadgen 分发上的薄入口。cadgen 基于 build123d（Python 参数化建模）与 OCP（OpenCascade 的 Python 绑定），渲染侧通过 three.js 与 React 提供浏览器内预览。
• 产物格式：以 STEP 为主输出，并支持导出 STL、3MF 与 GLB 网格；机器人侧产出 URDF、SRDF、SDF 等描述文件。
• 运行模型：模型是纯 Python 脚本（用 @step 装饰器声明），命令操作文档（STEP/STL 文件）。「脚本被运行，命令处理文档」，二者分工明确。
• 缓存与并发：默认在 ~/.cache/cadgen 维护一个内容寻址的本地存储，warm daemon 常驻 worker，子模型并行构建、按结果共享。

小黑配图：把一句自然语言需求投进流水线，经过建模、校验、预览，最终产出 STEP 零件与机器人描述文件。

二、主要功能特点与应用场景

项目把 11 个技能的能力边界在 README 中以表格明确列出，下面按用途分组说明其在工程链路中的位置。

• CAD：从自然语言或图像请求创建、修改 CAD 模型，主输出为 STEP，并可导出 STL、3MF、GLB。
• CAD Viewer：在本地浏览器中预览 CAD 与机器人文件，是校验后交接的落点。
• step.parts：检索螺丝、轴承、电机、连接器等现成 STEP 标准件，避免在装配里手搓占位几何。
• DXF：从 Python 源或 CAD 几何生成二维 DXF 图纸，如轮廓、模板、垫片与切割排版。
• URDF：编写含 link、joint、限位、惯性与网格的机器人结构文件。
• SRDF：为 URDF 增补 MoveIt 规划组、末端执行器、位姿与碰撞规则。
• SDF：创建含坐标系、物理、传感器与灯光的仿真模型与世界。
• SendCutSend：上传外协加工前，对 DXF 与 STEP 文件做预检。
• DfAM Check：按工艺评估网格可打印性，覆盖壁厚、悬垂、支撑体积与构建方向。
• G-code：用真实切片器 CLI，把支持的网格切片为带打印机配置的合规 FDM .gcode。
• Bambu Labs：对校验过的 .gcode 做空跑、上传并谨慎启动本地 Bambu Lab 打印任务。

适用场景包括：机械零件与外壳的快速建模、3D 打印从模型到切片的全链路、机器人本体的 URDF/SRDF 描述、Gazebo 类仿真世界的 SDF 搭建，以及把标准件采购、外协切割、桌面打印接入代理工作流的自动化工程管线。

三、安装与使用

项目推荐用 Skills CLI 安装，这会把各个技能直接装到支持的代理里：

npx skills add earthtojake/text-to-cad

同一命令也用于更新——add 会重新拉取并覆盖已安装内容，既刷新旧技能也装上新版新增的技能。注意 npx skills update 只会刷新锁文件中已有的技能，会静默漏掉新增技能。若上游下架了某个技能，需用 npx skills remove <skill> 手动移除。Codex、Claude Code 与 Grok Build 还提供原生插件安装：

# Codex（需 Codex 0.142.0 及以上）
codex plugin marketplace add earthtojake/text-to-cad
codex plugin add cad@text-to-cad

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

# Grok Build
grok plugin install earthtojake/text-to-cad --trust
grok plugin enable cad

安装 CAD 技能后，需要先装好它的运行依赖（渲染还需浏览器）：

python -m pip install -r requirements.txt
python -m playwright install chromium

如果遇到 ImportError: DLL load failed while importing OCP，可运行 cadgen doctor，它会探查 CAD 内核并点名根因（在 Windows 11 上通常是 Smart App Control 拦截了未签名的内核模块）。这不是重装能解决的机器级设置。

一个最小的模型脚本长这样（来自 CAD 技能文档）：

from cadgen import build123d as bd
from cadgen import step

WIDTH = 10.0

@step
def bracket():
    return bd.Box(WIDTH, 10, 10)

if __name__ == "__main__":
    bracket()

直接运行脚本即可构建并写出 STEP；命令侧则处理文档：

python bracket.py                 # 运行模型，写出 bracket.step
cadgen step build IN OUT          # 重新生成带持久注解的 STEP
cadgen step inspect ...           # 引用/测量/对齐/干涉/校验
cadgen step snapshot ...          # 生成 PNG 预览包

四、获取方式

• GitHub 仓库：https://github.com/earthtojake/text-to-cad
• 官方文档：https://www.texttocad.dev
• 社区交流：https://discord.gg/5FGB9DwJYU
• 作者：https://x.com/earthtojake

五、同类方案对比

Text-to-CAD 的差异化不在某个单一模型，而在于把工程链路封装成代理可调用的确定性技能。下表把它与几类常见替代方案放在一起看。

六、核心机制深度解析

理解 Text-to-CAD 的关键，是分清「模型」与「门（door）」两种入口。模型是带 @step 装饰函数的纯 Python 脚本，只有被运行时才构建；命令则是处理文档（STEP/STL 文件）的门，它从不在脚本上运行，而是问存储：这份文件的字节是否已有对应树？有则读取，无则作为任务在池里编译。这套分工解释了为什么修改模型要靠重跑脚本、而命令只认文件。

存储（默认 ~/.cache/cadgen，可用 CADGEN_CACHE_DIR 覆盖）内部是内容寻址的 objects/ 与记录索引 index/，只存派生结果。一个「新鲜度门（freshness gate）」按哈希追踪源文件、按值追踪常量、按结果追踪子模型，从而决定模型是重建、复用还是跳过。子模型调用会立即提交构建并继续，父模型在首次读取几何时才等待，因此整棵构建树天然并行。常驻的 warm daemon 为每个模型保留 worker，空闲十分钟后解绑；测试与调试可用 CADGEN_DAEMON=0 退回临时 worker。排查「为什么重建/没重建」时，cadgen store why <model>.py 会逐条给出门的判定。

七、实用技巧

• 用 add 而非 update 更新：npx skills add 会同步新版新增的技能，npx skills update 只会刷新锁文件里已有的，会漏掉新增项。
• Windows 11 的 Smart App Control：OCP 的 wheel 携带未签名原生模块，会被系统拦截并导致 ImportError: DLL load failed while importing OCP。cadgen doctor 会点名；要么关闭 Smart App Control，要么在 WSL 中运行 CAD 技能（WSL 不受此限制）。
• 模型脚本是唯一真源：所有 STEP/STL/GLB 都是派生产物，永远改脚本重跑，不要手改导出的 STEP；导入的 STEP 直接交给 cadgen step inspect 与 snapshot。
• read_step 放进函数体：在模块顶层调用 read_step 会在每次重跑时都付出内核与解析开销；把它放进函数体或它调用的函数里，仅在真正构建时才触发。
• 善用 store 工具：cadgen store why 看重建判定，cadgen store forget 丢弃单条记录，rm -rf ~/.cache/cadgen 整体重置存储始终安全（仅派生结果，不动工程文件）。

八、更新动态

项目以 main 分支作为源树持续发布，每个技能的 requirements.txt 都锁定了随版本发布的 cadgen 发行版。README 中明确指出，发行版会逐步新增技能——目前库内 11 个技能里的 SendCutSend 外协预检、DfAM Check 可打印性检查、G-code 切片与 Bambu Labs 打印对接，都是这类渐进扩展的体现，因此保持「用 add 更新」尤为重要。

在集成侧也有明确里程碑：Codex 的仓库根插件自 0.142.0 起才被解析，旧版本会静默跳过、不出现在 codex plugin list 中，需要升级到最新 Codex；Grok Build 则复用既有的 .claude-plugin/marketplace.json，没有单独的 Grok 插件清单。贡献流程上，开发需从 main 分支开分支、向 main 提 PR，并遵循 CONTRIBUTING.md 中的本地工作流与校验指引。

九、常见问题 FAQ

十、总结

Text-to-CAD 把「从一句话到一块可加工零件、一个可仿真机器人」之间的工程步骤，封装成一组可被 AI 代理确定性调用的技能。它的真正价值不在于某个单一生成模型，而在于用本地 cadgen 引擎（build123d + OCP）把建模、校验、预览、交接串成一条可复现、可并行、可内容寻址缓存的工具链，并覆盖了从 CAD 到 CAE（仿真描述）再到 CAM（切片与打印）的完整环节。对于想把机械设计、机器人建模与制造流程接入代理工作流的团队与个人，这是一个值得部署的开源基座。

在撰写本文的过程中，我主要参考了 Text-to-CAD 的 GitHub 仓库（earthtojake/text-to-cad）README.md、各技能目录下的 SKILL.md（如 skills/cad/SKILL.md）、官方文档站 texttocad.dev 与 LICENSE。文中数据以官方公开信息为准，可能随版本更新而变化。