text-to-cad：为 AI Agent 构建的 CAD/CAE/CAM 技能库——从 STEP 参数化建模到机器人描述、切片打印的全链路实战

text-to-cad：为 AI Agent 构建的 CAD/CAE/CAM 技能库——从 STEP 参数化建模到机器人描述、切片打印的全链路实战

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

text-to-cad 是一个面向 AI Agent（如 Codex、Claude Code 等）的 CAD/CAE/CAM 技能库，将"生成、检查、采购、切片、交接 CAD 与机器人描述工件"的标准流程封装为一组可安装、可验证的 Agent 技能（Skill）。本文以仓库根目录 README.md 为骨架，结合 skills/ 下各技能的核心说明与源码结构，系统讲解技能全景、安装接入方式、各技能的内部工作流与校验机制，以及开发者如何在本地贡献与发布。读完本文，你将掌握如何在项目中安装并编排这些技能，让 Agent 从一句自然语言需求出发，产出经几何校验的 STEP 模型、机器人 URDF/SRDF/SDF 描述乃至可打印的 G-code。

项目定位：不是 CAD 软件，而是 Agent 的"技能库"

README 对项目的定义只有一句话：A library of agent skills for CAD, CAE and CAM（一个用于 CAD、CAE 和 CAM 的 Agent 技能库）。它的价值不在于自己实现一个建模内核，而在于把经过验证的专业工作流拆解成 Agent 可以"即插即用"的 Skill：

• 生成（generating）：从自然语言或参考图生成参数化 CAD 模型；
• 检查（inspecting）：对几何做引用解析、测量、对齐、差异比对与快照渲染；
• 采购（sourcing）：通过 step.parts 找到标准件（螺丝、轴承、电机等）的真实 STEP 文件；
• 切片（slicing）：调用真实切片器 CLI 把网格文件切成带打印机配置的 FDM G-code；
• 交接（handing off）：把产物交给本地 CAD Viewer，返回可直接在浏览器中查看的实时链接。

安装该库后，Agent 便获得了"聚焦的工作流"：CAD 建模、加工制造（DXF/SendCutSend）、机器人描述文件（URDF/SRDF/SDF）、仿真与本地可视化审查都能在统一的规范下完成。项目默认以STEP 作为首要 CAD 工件，STL、3MF、GLB 等网格格式作为次要导出，这一"STEP-first"原则贯穿全部技能设计。

下图依次展示了 CAD 技能在 CAD Viewer 中生成与预览几何、URDF 技能输出机器人描述、SRDF/MoveIt2 技能演示逆运动学的运行效果（来源见 assets/）：

🧰 技能全景：11 个 Skill 一览

README 用一个表格完整列出了当前仓库提供的技能。下表按"建模 → 描述 → 制造 → 打印 → 实验"的流水线顺序整理，并附各技能的权威说明文档路径：

这些技能彼此衔接、职责互补：CAD 产出 STEP 几何，DXF 从 STEP 投影 2D 图纸，SendCutSend 对 DXF/STEP 做加工预检，URDF/SRDF/SDF 描述机器人，G-code 把网格切成打印指令，Bambu Labs 再把 G-code 送到打印机，Implicit CAD 则提供一条通往 GLSL 隐式建模的实验性路径。

核心技能深度拆解

CAD：STEP-first 的参数化建模工作流

CAD 是整套技能库的核心。从 skills/cad/SKILL.md 可以看到，它遵循一套严格的原则：

两条进入 STEP 工作流的路径

• 从 build123d Python 源码生成：默认路径，适用于从零设计或修改已生成的模型；
• 直接导入现有 STEP/STP 文件：当没有生成器、或用户明确以 STEP 文件为目标时使用。

两条路径最终产出同一种可检查的工件。对于装配体，技能推荐使用cadgen.assembly.AssemblyHelper，配合源码级的 build123d 关节（joint）、命名配合基准（mating datum）与原生标签（label）来表达部件间真实的装配关系。

五个命令行工具（从技能目录运行，python为解释器占位符，可用--help查看完整接口）：

python scripts/gen ... # 从 gen_step() Python 源码渲染 GLB/topology 包 python scripts/export ... # 从 Python 源码或导入的 STEP 生成 STL/3MF/GLB 网格 python scripts/inspect ... # refs、measure、align、frame、diff 等几何检查 python scripts/snapshot ... # PNG/GIF 视觉复查包 python scripts/artifact ... # 调试一次按需渲染包构建（针对导入的 STEP）

其中gen只针对显式生成器目标运行，禁止目录级批量生成；需要.step文件本身时加--write；需要网格文件时用export。stdout 承载结果（gen对每个目标打印<outcome> <package path>），stderr 承载进度与失败信息，两者绝不交错，因此2>/dev/null后 stdout 依然是可解析的；gen、export、snapshot支持--json，inspect天然输出 JSON（--format text可转散文格式）。并发构建同一模型时，构建会等待而非竞争，可通过--lock-timeout SECONDS设定放弃等待的时限。

默认建模假设（用户未指定时的首轮建模默认，非可制造性/公差/认证承诺）：

• 单位：毫米；坐标原点：按部件类型默认（见 references/positioning.md），一般取主体中心；
• 基准面 XY，拉伸/竖轴为正 Z；
• 输出几何为闭合、正体积实体；
• 未指定时小塑料外壳壁厚 2.0–3.0 mm，装饰圆角 1.0–3.0 mm（在局部几何安全的前提下），M3/M4/M5 普通过孔为 3.4/4.5/5.5 mm。

必备工作流（十个步骤，规模随任务缩放）：

1. 分类任务（新零件/新装配/源码修改/直接 STEP 检查等）；
2. 只加载所需的渐进式参考文档；
3. 撰写自然语言 CAD brief（references/cad-brief.md）；
4. 检查具名可采购部件：装配体含现成电机、舵机、电路板、连接器时，先用$step-parts搜索，找不到精确匹配才用文档化的包络几何；
5. 编码前规划参数、意图标签、源路径、预期包围盒与配合/定位基准；
6. 编辑源码而非生成的工件：用gen_step()编写 build123d Python，入口生成器命名<name>.step.py；
7. 生成显式目标（gen+ 按需--write/export）；
8. 几何校验：scripts/inspect refs <target> --facts --planes --positioning为基线，再用measure、align、frame、diff逐项核对规格要求；inspect validate只保证 ref 解析，开放壳与翻转实体都能通过，因此必须结合针对性测量；
9. 快照校验是强制的：创建或明显修改主 STEP 后必须运行scripts/snapshot并人工复查（跳过情形见 references/snapshot-review.md，且需说明理由）；
10. 失败即修复最小责任源码段并重跑校验。

非协商事项（Non-negotiables）：STEP 是首要校验工件，STL/3MF/GLB 均为派生工件；使用命名参数、闭合实体、详细的原生 build123d 标签与源码受控的几何意图；装配定位必须在源码中表达（references/positioning.md 对此有权威说明）；禁止用git status/git diff/文件大小变化来比较大型导出工件，应改用源码变更、inspect摘要、快照或生成的拓扑输出；只报告实际运行过或有工具输出支持的检查。

CAD Viewer：统一的本地可视化与交接枢纽

所有生成类技能（CAD、URDF、SRDF、SDF、DXF、step.parts、SendCutSend、Implicit CAD、Bambu Labs 的.3mf产物）都有一条共同规则：完成后必须把显式文件路径交接给$cad-viewer技能，由它启动本地 CAD Viewer 并返回实时查看链接。若该技能不可用或启动失败，必须报告而不能静默省略。

skills/cad-viewer/SKILL.md 给出了运行方式：npm --prefix scripts/viewer run start -- --host 127.0.0.1，监听固定端口3245（即十六进制0xCAD，恰好是 "CAD"）。Viewer 的 URL 形态是"路径即绝对目录 +file=选工件"：

http://127.0.0.1:3245/absolute/project/models?file=mechanisms/lift_table.step.py

要点：路径必须是绝对目录（Viewer 的运行目录并不等于模型目录），file=相对该目录解析；应选择用户视为"模型工作区"的目录（通常是项目的models/），而不是工件自身所在深目录，这样文件浏览器能列出整个项目。对生成的模型应传生成器源码<name>.step.py（目录清单即列它，后端按需直接构建渲染工件，且只有这种形式携带paramssidecar）；对无生成器的导入 STEP才传.step/.stp本身。端口被占用时启动器直接报错而非滚动换端口，用--port <n>显式指定。从源码结构看，Viewer 前端运行在 viewer/ 与packages/cadjs、packages/implicitjs之上，其 Python 后端位于 skills/cad-viewer/server_py/。

URDF / SRDF / SDF：机器人描述三件套

机器人描述文件在 text-to-cad 中遵循清晰的职责边界：

• URDF拥有物理结构：link、joint、几何、inertial、limit、mimic joint、transmission、状态发布；
• SRDF拥有 MoveIt 规划语义：虚拟关节、被动关节、规划组、组状态、末端执行器、禁用碰撞对；
• SDF拥有仿真/world 语义：physics、sensor、light、plugin、world。

URDF（skills/urdf/SKILL.md）把 URDF 工作视为"受约束的运动学建模"而非 XML 写作，核心风险是 frame 放置、关节轴语义、单位一致性、网格缩放与惯性数据。关键规则包括：.urdf是事实来源，直接编辑 XML，没有gen_urdf()契约；写 XML 前必须建立设计台账（ledger）并作为注释块嵌入文件顶部（references/design-ledger.md）；严格遵守 frame 语义（references/frame-semantics.md）；绝不凭印象推断空间变换，绝不手写计算型数值（惯性张量、质心、多链路单位换算、镜像变换都要算出来，见 references/inertials.md）。校验器只依赖 Python 标准库：

python scripts/validate path/to/robot.urdf python scripts/validate path/to/robot.urdf --strict python scripts/validate path/to/robot.urdf --format json python scripts/validate path/to/robot.urdf --package robot_description=/path/to/pkg

--strict把警告视为失败，--json输出机器可读发现文档，--package解析package://网格 URI。校验是一次遍历收集全部发现（严重级、代码、XML 路径），覆盖 XML 结构、树拓扑、关节语义（limit/mimic/dynamics）、几何、网格引用、材质、惯性物理与拼写错误的元素。技能同时强调"校验是护栏而非空间证明"——一个结构全对的 URDF 也可能把关节放在错误位置，因此台账 + Viewer 全关节扫查必不可少。

SRDF（skills/srdf/SKILL.md）强调 SRDF 正确性是"规划语义"问题，常见失败不是 XML 非法，而是给 MoveIt 错误的规划组、错误的工具 link、错误的默认状态、不安全的禁用碰撞矩阵或错误的关节单位。其 13 步工作流要求：从有效 URDF 出发；先提取 URDF 的 link/joint 表并只从表中复制名称（绝不凭记忆输入）；与 URDF 通过"同目录 + 相同<robot name>"配对，这正是唯一的配对机制（校验器、Viewer、MoveIt2 server 都按此解析，每个 robot name 每目录只能有一个 URDF）；组状态必须使用 URDF 原生单位（revolute/continuous 用弧度，prismatic 用米），且不能设置 fixed/mimic 关节；禁用碰撞对必须有证据（URDF 关节表邻接关系、MoveIt Setup Assistant 采样或用户提供的碰撞矩阵），禁止臆造宽泛的禁用列表。校验器会对照配对的 URDF 交叉校验全部名称、链、状态与碰撞对（skills/srdf/SKILL.md 的scripts/validate）。

SDF（skills/sdf/SKILL.md）专指 SDFormat（而非符号距离场），作者直接编辑.sdfXML，没有gen_sdf()契约。核心规则包括：新输出优先version="1.12"；默认 SI 单位；在每个非平凡 pose 与轴上显式写relative_to/expressed_in——"隐式 frame 默认是 SDF 头号失败模式"（references/frame-semantics.md）；绝不手写计算数值；当机器人已有 URDF 时从 URDF 派生 SDF 而非重写几何（references/interoperability.md）。除内置校验外，还可用--gz-check auto|required|never调用可选的gz sdf --check，且完成任务时要求按固定模板输出"校验了什么/跳过了什么/假设/风险"的报告。

DXF：2D 图纸的三种生成路径

skills/dxf/SKILL.md 定义了 DXF 图纸的事实来源：一个专用 Python 生成器文件<name>.dxf.py，定义gen_dxf()，CLI 拥有输出路径。默认构建产物是图纸包（drawing package）——CAD Viewer 服务并按需自动重建的渲染工件：

<model-folder>/__cadgen__/models/<name>.dxf.py/ drawing.json # 来源 + 新鲜度描述符 drawing.dxf # 构建出的 DXF（交换工件） preview.glb # 烘焙的 3D 展开图（Viewer 渲染内容）

三条工作流：① 从零独立起草（垫片、面板、模板、切割排样，直接用 ezdxf 建文档）；② 从生成的 STEP 部件派生（旁置<name>.dxf.py，通过cadgen.sources.load_source_module路径加载.step.py复用其几何）；③ 从导入的 STEP 派生（读 STEP 后用cadgen.flatten投影）。规则上gen_dxf()必须单独位于.dxf.py，同文件同时定义gen_step()与gen_dxf()会被拒绝。默认单位毫米且须显式设置（doc.units = ezdxf.units.MM），切割轮廓须闭合（开轮廓仅限雕刻/参考图层），CAD 支撑件用cadgen.flatten从真实实体拓扑投影并做union_projected_faces，切缝/刀径补偿用offset_geometry而非手工平移坐标。校验内建于生成过程（闭合性、零长度/退化实体、重复几何、无单位文档、空 modelspace 均失败），也可对既有文件后置校验：

python scripts/gen path/to/source.dxf.py python scripts/gen path/to/source.dxf.py --write python scripts/gen --validate path/to/file.dxf

step.parts、SendCutSend 与制造预检

step.parts（skills/step-parts/SKILL.md）为装配体提供标准件采购：当装配含具名现货致动器、舵机、电机、电路板、连接器时，先用$step-parts搜索再考虑简化占位几何。仓库自带确定性下载器：

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

下载后须用记录的sha256校验文件。搜索时注意 API 的 AND/OR 语义：查询词 AND 连接，同一 facet 内 OR、不同 facet 之间 AND；舵机类型号要同时尝试别名与厂商拼写（如STS3215可能写作ST3215、3215或带family=feetech）。

SendCutSend（skills/sendcutsend/SKILL.md）面向激光切割/CNC 路由前的上传预检：DXF 用于激光薄板切割，STEP/STP 用于 CNC 路由与 3D 模型上传。它把官方下单指南、目录 JSON、规格 JSON 视为"证据源而非稳定 API"，坚持只对比可信证据对：引证来源字段路径 + 被测量的文件事实。DXF 侧检查$INSUNITS（只认1英寸与4毫米，缺失或异常即报单位/缩放错误）、闭合切割轮廓、退化/重复几何、不支持标注、折弯线两侧局部法兰深度等；STEP 侧检查可读性、实体体、单位/包围盒/厚度、折弯半径（对比 SKU 的bending_specs.effective_bend_radius等）。状态标签严格限定为✅ pass/❌ fail/❓ need more info，禁止无证据的"ready"结论。

G-code 与 Bambu Labs：从切片到打印

G-code（skills/gcode/SKILL.md）是打印链路的起点：把.stl、.obj、未切.3mf、.ply、.glb、.gltf通过真实切片器 CLI切成普通 FDM G-code。技能明确拒绝.step/.stp/.dxf/.svg/.urdf/.sdf，并给出带remediation对象的结构化错误（例如 STEP 先由$cad导出 STL sidecar 再切片）。工作流强制：先discover探测后端 →inspect检查输入 →--dry-run试运行 →--execute真正执行 →validate校验。切片必须提供包装配置 JSON，其中native_config指向原生切片器配置的绝对路径，并声明打印机床尺寸、运动边界与耗材参数：

{ "backend": "orcaslicer", "native_config": "/absolute/path/to/native-slicer-profile", "machine": { "name": "Example Printer", "bed_size_mm": [180, 180], "z_height_mm": 180 }, "filament": { "type": "PLA", "nozzle_temp_c": 220, "bed_temp_c": 65 } }

后端优先级为orcaslicer→prusa-slicer→curaengine。校验器检查非空内容、温度指令、运动指令、挤出移动、XYZ 边界与未知指令告警。该技能只产普通.gcode，不联系打印机。

Bambu Labs（skills/bambu-labs/SKILL.md）负责本地局域网打印交接，通过 Bambu LAN FTPS/MQTT 协议工作。安全规则是硬约束：默认全部 dry-run，真实流量需--execute；启动打印必须--execute --confirm-start-print，取消必须--execute --confirm-cancel-print。推荐的 A1 Mini 路径是--handoff template-project：从已校验 G-code 出发，复制同打印机已知良好的.gcode.3mf模板、替换Metadata/plate_N.gcode、写入 plate MD5、经 FTPS 上传到根目录并发布print.project_file。--handoff plain仅作诊断；--handoff bambox-project当前只对p1s-0.4配合 PLA/ASA/PETG-CF 启用。命令形如：

python scripts/bambu_lan_print.py status --printer a1-mini --push-all --wait-seconds 10 python scripts/bambu_lan_print.py send --printer a1-mini --gcode /tmp/job.gcode \ --handoff template-project --template-project /path/to/template.gcode.3mf \ --action upload-start --execute --confirm-start-print

Implicit CAD：实验性的 GLSL 隐式建模

skills/implicit-cad/SKILL.md 提供浏览器原生隐式 CAD：主工件是.implicit.js/.implicit.mjsES 模块，导出schema: "implicit.js/0.1.0"对象，核心是 GLSL 符号距离场float sdf(vec3 p)与可选的过程式vec3 color(vec3 p, vec3 normal)：

export default { schema: "implicit.js/0.1.0", name: "rounded capsule block", glsl: ` float sdf(vec3 p) { float sphere = implicit_sphere(p, vec3(0.0), 22.0); float block = implicit_box_centered(p, vec3(34.0, 18.0, 18.0), vec3(0.0)); return implicit_union_round(sphere, block, 3.0); } vec3 color(vec3 p, vec3 normal) { return mix(vec3(0.20, 0.55, 0.95), vec3(0.95, 0.45, 0.20), smoothstep(-15.0, 20.0, p.z)); } `, };

内置implicit_*GLSL 助手（implicit_sphere、implicit_box_centered、implicit_union_round等），也支持params、animations与可选的bounds（省略时自动从 SDF 估算）。schema 事实来源在scripts/packages/implicitjs/src/lib/implicitCad/schema.js，scripts/lib/implicit-cad.mjs以SCHEMA重新导出。命令包括python scripts/gen <model.implicit.js>（构建 Viewer 打开的渲染包）、node scripts/export.mjs --input ... --stl/--3mf/--glb（网格导出，一次运行 meshing 一次所以各格式几何一致）与python scripts/snapshot（支持多输出 JSON job、动画 GIF）。技能自标注为实验性，明确要求除非用户明确要求隐式模型，否则始终优先常规 STEP-first 工作流。

💻 安装与接入：把技能装进你的 Agent

README 给出了三种安装路径，生产使用一律基于main分支（该分支包含提供商安装器所需的已生成技能产物）。

Skills CLI（推荐）

npx skills install earthtojake/text-to-cad

这是首选路径，为受支持的 Agent 直接安装各个独立技能。

Provider 原生插件

Codex（需 0.142.0 或更新版本）与 Claude Code 均支持仓库根目录即插件包的形式：

# Codex（需 Codex 0.142.0 或更新） codex plugin marketplace add earthtojake/text-to-cad codex plugin add cad@text-to-cad

Codex 从 0.142.0 起才解析仓库根插件；旧版本会静默跳过且不出现于codex plugin list，升级方式为npm install -g @openai/codex@latest。

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

若新装技能不出现，重启 Agent 即可。本地开发则应基于develop分支并分支开发、向develop提 PR，使用下述 symlink 工作流。

本地开发：symlink 安装与卸载

从 CONTRIBUTING.md 可以看到，本地开发用 symlink 把本仓库的技能目录链接进 Agent（不要复制目录，这样修改立即可见）。仓库提供了安装器脚本：

scripts/install/install-skills.sh --agent codex scripts/install/install-skills.sh --list-agents scripts/install/install-skills.sh --agent codex --agent claude scripts/install/uninstall-skills.sh --agent codex

从 scripts/install/install-skills.sh 源码可以看到其行为：扫描skills/下每个含SKILL.md的目录，为每个技能创建一条 symlink，并保留已存在的非 symlink 路径不动；卸载器只删除指向本仓库的 symlink 并剪除空目录（除非--keep-empty-dirs）。支持的本地开发目标：

claude-code、gemini-cli、agents、repo为别名；--all安装到全部目标。安装/卸载后需重启或重载 Agent 以重新扫描技能。

技能间的协作模式：一条完整的"需求 → 实物"流水线

将各技能串联起来，text-to-cad 实际上提供了一条从自然语言需求到可交付工件的流水线：

1. $cad依据需求或参考图产出经校验的 STEP，并以scripts/inspect+scripts/snapshot完成几何与视觉双重验证；
2. $step-parts在装配体遇到电机、轴承等标准件时先查现货 STEP，替代占位几何；
3. $dxf从 STEP 实体拓扑投影出闭合切割轮廓，供激光/水刀等切割工艺使用；
4. $sendcutsend在把 DXF/STEP 上传给切割服务前生成证据化预检报告；
5. $urdf/$srdf/$sdf把几何沉淀为机器人描述：URDF 管结构，SRDF 配 MoveIt 规划语义，SDF 进 Gazebo 等仿真器；
6. $gcode把网格切成带打印机配置的 G-code，$bambu-labs再把它安全地送到局域网打印机；
7. $cad-viewer是贯穿全程的交接枢纽，每个生成类技能完成工作后都必须把文件路径交接给它并返回实时查看链接。

每一步都内建校验护栏（validate/inspect/生成期检查），并且只报告实际运行的检查——这是所有技能共用的底线原则。

🛠️ 贡献与发布：develop 分支与 Release 流水线

README 与 CONTRIBUTING.md 共同描述了仓库的工程纪律：

• 分支策略：开发全部基于develop，PR 打向develop而非main；main是仅发布分支，仓库根即 Agent 插件包。
• symlink 布局：develop用 symlink 让生成输出指向规范源（scripts/dev/setup-symlinks.sh），而main必须用真实副本替换 symlink——因为各安装器对 symlink 行为不一（Skills CLI 会解引用、Claude Code 原样保留、Codexplugin add会无报错丢弃导致技能文件缺失），scripts/github-workflows/check-builds.sh 是强制这一点的门禁。
• 发布流水线：版本统一从VERSION派生，由ReleaseGitHub Actions 工作流一次性完成版本 bump、release PR、发布到main、cadgen上传 PyPI、文档部署、semver 标签与 GitHub Release；bump=none用于恢复失败的发布或演练，target_branch=build-test仅用于 CI/CD 改造演练。
• 技能自包含：每个技能安装后必须自包含、独立运行，不得在运行时引用其他技能或仓库根模块；共享运行时助手以packages/为源，通过 bundle 流程 vendor 进各消费技能（scripts/bundle/bundle.sh）。
• 本地开发环境：python3.12 -m venv .venv后安装requirements-dev.txt；测试入口包括 scripts/test/test.sh 及聚焦的 test-js/test-python/test-docs/test-global 脚本。
• 工件纪律：测试与样例工件写入models/，快照 PNG/GIF 等审查媒体渲染到/tmp并随 PR 附上，不进models/；assets/**演示 GIF 走 LFS 且默认不随轻量克隆拉取（需要时git lfs pull --include="assets/**"）。

小结

text-to-cad 的独特之处在于：它把 CAD/CAE/CAM 中"最容易出错、最依赖领域知识"的环节——几何正确性、坐标系语义、单位一致性、碰撞与制造约束——固化成 Agent 可执行、可校验的技能契约。无论是用$cad走 STEP-first 参数化建模、用机器人三件套产出 URDF/SRDF/SDF，还是用$gcode+$bambu-labs直接切片打印，每一步都有对应的校验工具与本地可视化交接闭环。安装它之后，你的 Agent 便不再是"会写 XML/代码的通用模型"，而是一台拥有完整机械工程工作流的终端。

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad