在大语言模型逐步渗透软件工程各个领域的今天，CAD 建模这一传统工科疆域也正在经历 AI 驱动的范式转变。text-to-cad 作为一款开源的文本到 CAD 生成框架，为开发者与工程师提供了一种全新的工作流：将自然语言描述直接转化为可参数化控制的 CAD 模型，并支持 STEP、STL、3MF 等多种工业级格式导出。本文将从几何约束求解、参数化建模与格式导出三个维度，剖析该框架的工程实现细节与实践要点。
从自然语言到几何约束：文本驱动的建模逻辑
text-to-cad 的核心设计理念是将 LLM 的语义理解能力与参数化 CAD 建模的确定性相结合。用户通过自然语言描述零件或装配体的几何特征后，框架会引导编码代理（如 Claude Code、Codex）生成对应的 Python 脚本。这些脚本并非直接绘制几何图形，而是调用 build123d 或 OCP（Open Cascade Python）等 CAD 内核，通过编程方式定义几何约束与拓扑关系。
参数化建模的关键在于约束系统的建立。与传统 GUI 建模不同，text-to-cad 生成的代码将所有尺寸、位置、旋转角度显式表达为变量或表达式。例如，一个简单的轴类零件可能包含直径、长度、倒角半径等多个参数，当用户后续提出 “将长度增加 20 毫米” 时，代理只需修改变量值并重新执行脚本，即可获得更新后的几何模型。这种基于代码的建模方式天然具备版本控制与可复现性优势。
值得注意的是，框架引入了几何契约（Geometry Contract）的概念。当任务涉及非平凡的几何编辑（如在复杂装配体中添加新特征或修改特定面）时，代理被要求先编写简短的契约文档，明确定义目标几何的约束条件，再进行代码修改。这种前置约束声明的方式显著降低了模型生成的不确定性，提升了迭代效率。
几何引用与精确编辑：@cad 引用机制
在实际工程中，CAD 模型往往需要渐进式修改而非一次性生成。text-to-cad 为此设计了 @cad [...] 引用机制，为大语言模型提供了一种稳定且精确的几何定位手段。当用户在 CAD Explorer 中查看生成的模型时，可以获取特定面、边、角点或装配体成员的引用句柄，这些句柄在后续提示中可以被解析为具体的几何元素。
该机制的工作流程如下：CAD Explorer 在渲染 STEP 文件时，会自动提取拓扑信息并生成确定性选择器（Deterministic Selector）。当提示包含 @cad [face:id] 这样的引用时，框架会调用 cadref 工具解析引用，从源 STEP 数据中检索对应的几何事实（Face、Edge、Corner 或 Occurrence），并据此执行面级或边级的精细编辑。这一设计解决了传统 AI 生成方案中常见的 “语义模糊” 问题 —— 代理不再需要猜测用户的意图指向模型的哪个部分，而是通过引用获得唯一的几何目标。
工程实践中，建议将截图作为辅助理解手段，而以 @cad 引用作为信任基准。若两者出现不一致，应以引用和源几何为准，截图仅用于辅助理解设计意图。
导出格式与工程适配：STEP、STL 与 3MF 的选择
text-to-cad 支持多种 CAD 导出格式，每种格式针对不同的工程场景具有独特优势。理解这些格式的特性与适用条件，是实现高质量模型交付的关键。
STEP（STandard for the Exchange of Product model data）是目前工业界最广泛使用的 CAD 交换格式，采用基于 B-rep（边界表示）的完整几何与拓扑描述。STEP 文件保留了参数化特征、装配关系与元数据，能够在主流 CAD 软件（如 SolidWorks、CATIA、NX）之间无损传递模型。text-to-cad 通过 build123d 与 OCP 内核生成符合 AP203/AP214 规范的 STEP 文件，适用于需要下游制造或详细工程分析的场景。
STL（Stereolithography）格式则采用三角网格离散化表示几何外形，文件结构简单但精度受限。该格式主要用于快速原型制造、3D 打印以及可视化渲染，不包含拓扑连接信息，因此不适合需要保留参数化特征的 downstream 应用。text-to-cad 生成的 STL 可通过快照工具快速生成验证图像，用于迭代过程中的快速检视。
3MF（3D Manufacturing Format）是近年来兴起的面向增材制造的开放标准，它在保留三角网格的同时支持材料、颜色与纹理信息，且文件体积远小于 STL。对于需要多材料打印或保留外观属性的制造场景，3MF 是优于 STL 的选择。
对于二维工程图场景，框架同时支持 DXF 格式导出，可与激光切割、数控加工等制造工作流无缝衔接。
验证与快照：迭代闭环的工程保障
参数化建模的一个核心优势在于变更的可验证性。text-to-cad 内置了验证与快照机制，确保每次模型更新都能得到及时确认。验证流程遵循 “最小成本原则”—— 使用足够强但不冗余的证明手段。对于简单的几何存在性检查，可能只需执行脚本并捕获异常；对于涉及装配关系或制造约束的验证，则需要更复杂的几何分析。
快照工具（scripts/snapshot/cli.py）可生成模型的 PNG 渲染图像，这些图像被自动嵌入到代理的工作上下文中，作为快速视觉反馈。与传统的手动截图不同，快照由确定性脚本生成，具有可重复性，且可与版本控制系统解耦 —— 开发者被明确指示不要使用 git 跟踪比较导出文件的变化，而是通过审查源代码变更、确定性摘要或快照来确认修改正确性。
工程实践中，建议将验证步骤嵌入到 CI 流程中，特别是对于需要满足特定制造公差或装配间隙的模型。sendcutsend-skill 作为框架的可选扩展，提供了针对 SendCutSend 设计和制造指南的 DXF/STEP 文件验证能力，可用于激光切割与 CNC 加工的前置检查。
本地化部署与工作流整合
text-to-cad 的另一个重要特性是完整的本地化运行能力。框架不依赖云端后端服务，所有 CAD 渲染、格式转换与模型检查均可通过本地环境完成。开发者只需安装 Python 3.11+ 虚拟环境与 Node.js 依赖，即可在任意项目目录中启动 CAD Explorer 服务。
Explorer 基于 React 与 Vite 构建，扫描由 EXPLORER_ROOT_DIR 环境变量指定的目录，默认使用命令执行的当前工作目录。启动后，用户可通过浏览器访问本地服务地址，查看生成的 STEP、STL、3MF 或 DXF 文件的三维渲染与拓扑信息。这一设计使得 text-to-cad 能够与现有的代码仓库工作流深度整合 ——CAD 源文件、生成脚本与导出产物均保存在项目目录中，便于版本控制与团队协作。
典型的工程工作流包含以下步骤：首先，用户描述期望的零件或装配体特征；接着，编码代理根据描述生成或修改 Python CAD 脚本；然后执行脚本生成目标格式的导出文件；随后在 CAD Explorer 中检视模型的几何正确性；若需进一步修改，通过 @cad 引用定位特定几何元素并进行增量编辑；最后，将源代码与生成产物一并提交至版本仓库。
工程落地的关键参数与监控要点
在将 text-to-cad 集成到实际工程项目时，以下参数与监控点值得关注。Python 虚拟环境应使用 Python 3.11 或更高版本以确保兼容性，CAD 依赖通过 requirements.txt 统一管理，建议锁定版本以避免内核 API 变更导致脚本失效。CAD Explorer 服务默认运行于本地 4178 端口，若需要同时服务多个工作空间，可通过不同的 EXPLORER_ROOT_DIR 启动多个实例，但应避免端口冲突。
对于需要版本追溯的参数化模型，建议在代码中显式定义所有关键尺寸参数，并编写对应的几何契约文档。导出文件命名应遵循一致性规范，便于下游系统自动化解析。验证环节的监控指标包括：脚本执行成功率、导出文件大小阈值（异常大或小可能表示生成失败）、几何完整性检查（如封闭体检测、面法向一致性）以及格式规范校验。
此外，对于需要交付给制造环节的模型，应在导出后运行制造规则检查。sendcutsend-skill 等预检工具能够识别超出材料加工范围的几何特征、不可达内腔或最小壁厚不足等问题，将质量前移到设计阶段。
小结
text-to-cad 为文本驱动的参数化 CAD 生成提供了一个工程化的开源解决方案。通过将大语言模型的语义理解与 build123d、OCP 等确定性 CAD 内核相结合，框架实现了从自然语言描述到可版本化、可验证的工业模型的全流程覆盖。@cad 引用机制解决了精确几何编辑的难题，STEP/STL/3MF 多格式导出满足了不同工程场景的需求，而本地化部署与 CI 集成能力则使其能够无缝融入现有的软件开发工作流。
对于希望在设计自动化领域探索 AI 应用的团队，text-to-cad 不仅仅是一个工具，更代表了一种新的 CAD 工作范式 —— 从手工绘制到代码驱动，从孤立文件到版本化资产，从手动验证到自动化检查。随着 AI 编码能力的持续提升，这一范式有望在更复杂的工程场景中得到验证与拓展。
资料来源：text-to-cad GitHub 仓库（https://github.com/earthtojake/text-to-cad）