把 text-to-cad 塞进你的 AI Agent：STEP/URDF 输出接入机器人工作流保姆教程

把 text-to-cad 塞进你的 AI Agent：STEP/URDF 输出接入机器人工作流保姆教程

【免费下载链接】text-to-cadGive your agent CAD superpowers.项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

如果说 2024 年 "text-to-CAD" 还停留在"网页上敲一句英文、转圈等待、下载一个 STL"的 Demo 阶段，那么现在这个生态已经换了一副面孔。社区里围绕 Zoo Text-to-CAD 的讨论，从"如何在 5 分钟内生成一个 19 齿直齿轮"（CSDN 上的大量上手教程），已经演进到"一句话生成 CAD、机器人模型和工程文件"——把设计能力真正放进 Agent 手里。而这个生态背后最值得研究的开源实现之一，就是这个仓库：text-to-cad（"Give your agent CAD superpowers."）。

它不再是一个"文本生成模型"的前端壳子，而是一套以 Agent 为中心、本地运行的设计与制造工作流：Agent 用自然语言（或图片）驱动 Python 源码生成三维模型，导出 STEP / STL / 3MF / GLB，再做可制造性检查、工程图纸，甚至直接对接 3D 打印、钣金与 CNC 服务；对机器人场景，它还能在同一个 Agent 会话里产出 URDF / SRDF / SDF 描述文件。本文基于仓库源码，把它拆成三部分：Agent 化的 Skill 形态是怎么组织的、如何接入你自己的 Agent，以及机器人与硬件项目里真正跑起来的工作流长什么样。

一、text-to-cad 的 Agent 化能力与 Skill 形态

1.1 从"生成模型"到"交付工程文件"的能力栈

社区文章通常把 text-to-cad 的能力概括为"语义解析 + 几何生成 + 多格式输出 + 实时预览"四层，而仓库里实际的组织方式要更进一步：它把能力切成一组可被 Agent 独立调用的Skills，每个 Skill 都有独立的SKILL.md契约和配套参考文档。根目录 README.md 的 Skills 清单给出了全景：

这套"先写可追溯源码，再导出 STEP/STL/URDF 工程文件"的流程，正是掘金上《这可能是 AI Agent 的下一个硬核入口》一文描述的核心模式：Agent 生成的是可读、可重跑、可版本化的源码，而不是一次性的二进制模型。模型即 Python 脚本，这一点是整套设计的基石。

1.2 模型即源码：@step装饰器契约

在 skills/cad/SKILL.md 里，CAD 模型被定义为"一个无参的装饰器函数 + 返回 build123d 形状"的纯 Python 脚本。以其中的 bracket 示例为例：

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-generation.md 里的契约约束，有几条对"Agent 生成代码"这件事特别关键：

• 模型无参数、一个入口一个配置：参数化几何放在普通工厂函数里，模型只是"选择一种配置"。这让缓存和增量构建成为可能——改动不触及的模型脚本不会重跑。
• 子模型组合即 Python 组合：父装配体在函数体内直接调用子模型函数，子模型过期则自动重建，否则从缓存加载，返回的几何通过.moved()或Location * shape放置。多模型可以并行构建，无需任何调度代码。
• 依赖追踪是"按结果"的：父模型钉住子模型的几何哈希，子模型编辑后几何不变，父模型依然"当前"。注释、常量、工厂函数的追踪粒度各不相同。
• 输入的隐性声明：模型打开的每个文件（STEP、JSON、字体）都被记录为构建输入，改文件即过期，cadgen store why可以解释一个模型为何需要重建。

这意味着 Agent 在一个大装配项目里改一个子零件，不需要理解整棵构建树——python src/robot.py会自动"重建过期部分、链接其余部分"。

1.3 多格式输出与"格式门"（format door）

Skill 强调"生成没有 CLI，模型脚本就是工具"；反过来，从已保存的文件导出则统一走cadgen <format> <verb>命令族——仓库称之为"格式门"（format door）。比如从 STEP 一次性转网格：

cadgen stl build STEP/bracket.step STL/bracket.stl cadgen 3mf build STEP/bracket.step 3MF/bracket.3mf cadgen glb build STEP/bracket.step GLB/bracket.glb

TARGET [OUT]语法在所有格式间一致，省略 OUT 则生成同名兄弟文件。此外cadgen step build还能对外来 STEP做"规范化重写 + 注解"：重新用 OCCT 内核写出确定性字节，并通过--kinematics/--materials/--animation向无源码的 STEP 附加运动学、材质与动画侧车（sidecar）。

二、把 CAD/URDF 生成接进自定义 Agent 的步骤

2.1 三种接入形态：插件（Plugin）、Skills、MCP

仓库同时支持三种形态，对应不同 Agent 生态：

1. Agent 插件（plugin）：Claude Code / Codex / Cursor / Grok Build / Gemini 直接安装插件，plugin.json 定义了元数据（名称 text-to-cad、版本 0.7.17、keywords 含 cad/robotics/step/urdf/sdf/gcode）。插件同时带来 Skills 和本地 CAD 服务（cadgen mcp服务器）。
2. 纯 Skills（无插件支持的 Agent）：用 Skills CLI 安装，核心 CAD 工作流与浏览器中的 CAD Viewer 都可用，只是没有 MCP 服务器。
3. MCP 服务器：任意 MCP 客户端都能挂载。仓库自带的 claude.mcp.json 就是一个最小示例：

{ "mcpServers": { "cad": { "command": "uvx", "args": [ "--no-config", "--managed-python", "--python", "3.13", "--from", "cadgen==0.7.17", "cadgen", "mcp" ], "env": { "CADGEN_INSTALL_CHANNEL": "claude-github" } } } }

所有 cadgen 命令都统一通过uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.17 cadgen运行（Skill 文档称之为cadgen的规范展开），所以 Skills、MCP 服务器、构建守护进程共享同一个安装与同一个"热构建守护进程"。

2.2 给 Agent 的一句话安装

README 给出的官方推荐方式非常"Agent 原生"——把这句话发给你的 Agent 即可：

Install text-to-cad from https://github.com/earthtojake/text-to-cad

自己手动装则分三类：Claude Code 用claude plugin marketplace add earthtojake/text-to-cad#latest+claude plugin install text-to-cad@earthtojake；无插件支持的 Agent 用npx skills add earthtojake/text-to-cad#latest；通用 MCP 客户端按上面 JSON 配置。首次启动会下载 CAD 运行时（即 cadgen 发行版），所以需要网络；此后 Skills 与服务器共享同一个安装，后续更新直接改cadgen==版本号。

2.3 Skill 内部如何"引导" Agent 行为

每个 Skill 的 frontmatter 里有一份description，它就是 Agent 的触发条件。以 URDF 为例（skills/urdf/SKILL.md）：

URDF robot description authoring and validation. Use when creating, editing, inspecting, validating, or debugging.urdffiles, robot links, joints, limits, inertials, visual/collision geometry, mesh references, frame conventions, or robot-description artifacts. Use the SRDF skill for MoveIt2 semantic groups ...

这份描述决定了"什么任务路由到哪个 Skill"：CAD 任务进$cad，机器人结构进$urdf，MoveIt 规划语义进$srdf，仿真世界进$sdf，2D 图纸进$dxf。而 Skill 正文则进一步约束 Agent 的执行纪律——URDF Skill 的"核心规则"明确写了：.urdf文件是唯一事实来源，必须直接编写 XML 而不是生成 Python 管线；写之前先建立 frame/joint/geometry/unit 的"设计台账"（design ledger）并作为注释块嵌入文件；从不凭感觉手填计算值（惯性张量、质心、跨链路单位换算必须算出来）；每个文件交付前必须过cadgen urdf validate。

这种"把工程纪律写进 Agent 指令"的做法，是这套体系与普通"生成模型 + 下载"工具拉开差距的关键：不是让大模型自由发挥，而是给它一套带检查点的可执行规程。

2.4 安装后立即可用的验证回路

接入完成后，Agent 就拥有了一条完整的"生成 → 校验 → 视觉复查 → 交付"回路：

cadgen urdf validate path/to/robot.urdf # 结构性校验（一次收集全部问题） cadgen urdf validate path/to/robot.urdf --strict # 警告视为失败 cadgen urdf validate path/to/robot.urdf --json # 机器可读输出 cadgen urdf snapshot path/to/robot.urdf review.png # 无头浏览器渲染复查

URDF 校验器覆盖 XML 结构、树拓扑、关节语义（limits/mimic/dynamics）、几何、网格引用、材质、惯性物理与拼写错误；SRDF 校验器则把同目录下 robot name 匹配的 URDF 配对，交叉校验规划组、链路径、状态与禁碰撞对。Skill 文档反复强调一句值得记住的话："Validation is a guardrail, not spatial proof"——结构性校验通过不等于空间摆放正确，轴线正负号要靠 Viewer 逐关节扫描才能发现。这正是cadgen urdf snapshot+ CAD Viewer 的定位：让 Agent 自己把模型渲染成图再"看"一遍。

三、机器人与硬件项目的实际应用示例

3.1 仓库内三个"活教材"：juno、lyra 与 joint_playground

这套工作流不是纸面文档——仓库的models/下就有三个可运行的机器人工程：

• models/juno：约 1.40 m 高的紧凑人形平台概念，27 个本体自由度（每条腿 6、每条臂 6、腰 1、颈 2）。完整工程 =juno.urdf+juno.srdf（直接编写的机器人描述）+src/juno.py（28 个 occurrence 的装配体）+ 28 个 per-link 模型脚本。
• models/lyra：五指的灵巧手概念，16 个自由度，肌腱驱动架构。每个 link 脚本同时堆叠@step与@threemf，一次运行同时产出 STEP 零件和 URDF 引用的 3MF 网格。
• models/tests/joint_playground/joint_playground.urdf：纯几何基元搭的"关节游乐场"，覆盖 continuous / revolute / prismatic / mimic / fixed 等每种关节类型，无需任何网格文件即可在 Viewer 里逐关节摆姿势。

以 juno 为例看目录约定（注意STEP/、3MF/、tmp/是生成物、不入库，克隆后重跑脚本即可再生）：

models/juno/ juno.urdf juno.srdf 直接编写的机器人描述（非生成） src/ juno.py 完整的 28-occurrence 装配体 <link>.py x28 每个 URDF link 一个脚本：@step + @threemf lib/ 共享零件构建器 + 链参数规格 STEP/ 3MF/ 生成输出

3.2 关键设计：一份链参数，CAD 与 URDF 永不漂移

机器人工件最大的坑是"CAD 与机器人描述对不上"。juno 的解法很巧妙：用src/lib/chain.py这一份共享规格同时喂给 CAD 装配体、typed mates 和 URDF/SRDF。

在 models/juno/src/juno.py 里，27 个自由度被声明为cadgen.revolutetyped mates，轴的位置/方向来自chain.world_joint_axes()（链 FK 在 authored 姿态下的世界坐标），limits 是 URDF 行程减去 authored 角度，SRDF 的五个组状态（zero、athletic_ready、t_pose、wave_right、squat）全部以 athletic 姿态为基准存成DELTA——因为 STEP 烘焙的就是 athletic ready 姿态，所以每个 mate 的 rest 值即该姿态。代码里写得很直白：

# ZERO IS THE ARTIFACT AS WRITTEN. The STEP is baked in the athletic ready # stance, so each mate's rest value is that stance: # - axis = the joint's world frame AT the authored pose (chain FK), which # is exactly the screw axis a product-of-exponentials FK needs; # - limits = the URDF travel range minus the authored angle; # - poses = each SRDF group state minus the authored angle. def _kinematics() -> dict: axes = chain.world_joint_axes() rest = chain.athletic_ready_deg() ...

产物侧，models/juno/juno.urdf 的每个 link 都用3MF/<link>.3mf作为视觉网格（scale="0.001 0.001 0.001"，把 mm 导出换算成 URDF 的米制）、CAD 实体体积属性算出的惯性张量（统一假定密度使全机 35 kg）、以及粗粒度 AABB 碰撞盒。URDF Skill 的 meshes.md 明确给出了这条最佳实践：导出单元是 link 而非装配体，每个 link 的网格要在其自身坐标系下导出，这样所有<visual><origin>都是 identity，最容易被审计。

3.3 把整条工作流串起来：一个典型的机器人交付流程

把上面所有环节连起来，一个 Agent 完成"做一个六轴机械臂并交付可规划模型"的典型流程是：

1. 出 CAD：对每个 link 编写模型脚本（@step(out="../STEP/<link>.step")，需要网格时堆叠@threemf），装配体脚本调用各 link 模型并放置，运行python src/arm.py生成 STEP。
2. 检索标准件：需要电机、轴承、螺丝时先过$step-parts——step-parts Skill 规定必须先查询https://api.step.parts的/v1/parts，命中后下载 STEP 并核对sha256，而不是直接造占位几何：

python scripts/download_step_part.py "bearing 608zz" --limit 5 python scripts/download_step_part.py "M3 socket head 12" --download

3. 写 URDF：按 URDF Skill 的流程先建设计台账，直接编写 XML，每个 link 引用已导出的网格，惯性值用公式或辅助脚本算出，然后cadgen urdf validate校验。
4. 补 SRDF（如需 MoveIt 规划）：从 URDF 提取 link/joint 表，规划组、末端执行器、组状态、禁碰撞全部从该表与拓扑推导，cadgen srdf validate交叉校验。
5. 视觉复查：cadgen step snapshot/cadgen urdf snapshot渲染成图，或启动本地 CAD Viewer 逐关节扫描——这一步专门抓"轴符号反了""网格缩放 1000 倍"这类校验器看不见的问题。
6. 收尾：按 SDF Skill 的"required report shape"交付一份简洁报告，写明跑了哪些检查、跳过了哪些、有哪些假设。

3.4 硬件落地的延伸：从模型到制造

机器人做出来最终要落地制造，而这套 Skill 生态正好把"设计 → 制造"闭环补齐：dfam-check按工艺度量网格可打印性（壁厚、悬垂、支撑体积、打印朝向）；dfm针对钣金/CNC/注塑给出带测量证据的评审结论；gcode用 OrcaSlicer 直接切片；bambu-labs把打印任务发给 Bambu Lab 打印机；sendcutsend上传前先本地检查 DXF/STEP。社区文章里反复强调的"5 分钟从文字到 3D 模型"，在仓库语境下被延伸成了"从自然语言需求到可直接送去加工或仿真的工程文件"。

结语

text-to-cad 的价值不在于"AI 能画图了"，而在于它把 Agent 生成三维资产这件事变成了有源码、有校验、有复查、可增量构建、可对接制造的工程流程。对于机器人开发者，最有吸引力的部分在models/juno、models/lyra这类工程：CAD 装配体、typed kinematics 与 URDF/SRDF 共享同一份链参数规格，从一句话需求到可被 MoveIt/RViz/仿真器消费的完整机器人描述，Agent 可以在一个会话里端到端完成，而每一步都有可执行的检查点兜底。

如果要在自己的项目里起步，最省力的路径是：装好插件（或 Skills）→ 照着 models/tests/joint_playground/joint_playground.urdf 熟悉关节语法 → 打开 models/juno/src/lib/chain.py 理解"一份规格喂三份产物"的套路 → 然后用自然语言指挥你的 Agent 做第一版机械臂。剩下的，就是让 CAD 变成 Agent 的原生输出能力之一。

【免费下载链接】text-to-cadGive your agent CAD superpowers.项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad