text-to-cad 跨平台安装避坑：一条命令从零到跑通
【免费下载链接】text-to-cadGive your agent CAD superpowers.项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
text-to-cad 把 CAD 能力装进你的 AI Agent：你用自然语言描述零件，它生成 STEP 模型、导出 STL/3MF/GLB、写 URDF/SRDF 机器人描述文件，并在本地浏览器里直接预览。这份清单覆盖 Windows、macOS、Linux 三大平台的 text-to-cad 安装：环境检查、安装命令、平台差异、装完验证和排错。照做一遍，你能独立完成部署，并让 Agent 画出一个能在本地 Viewer 里转的 STEP 零件。
最快跑通路径
⚡ 赶时间的话，记住这两行：
uv --version # 预期：显示 uv 版本号 npx skills add earthtojake/text-to-cad#latest # 预期：提示选择要安装的 Agent第一条确认uv在场（CAD 运行时全靠它跑），第二条用 Skills CLI 把技能装进 Agent 的技能目录。命令会问装给哪个 Agent，想跳过交互就写成npx skills add earthtojake/text-to-cad#latest -g -a <agent> -y。装完重启 Agent，技能列表不热加载。
如果你更习惯原生插件，Claude Code 跑claude plugin marketplace add earthtojake/text-to-cad#latest加claude plugin install text-to-cad@earthtojake；Codex 跑codex plugin marketplace add earthtojake/text-to-cad --ref latest加codex plugin add text-to-cad@earthtojake；Cursor 直接克隆到~/.cursor/plugins/local/text-to-cad。
它到底怎么跑起来的
text-to-cad 本质是一组"技能包"加一个本地运行时。插件安装 = 技能 + 一个本地 CAD 服务器（cadgen mcp，CAD Viewer 的后台）；没有插件支持的 Agent 只装技能，模型照样能在浏览器 localhost 页面里预览。整个运行链是 Python 脚本 → cadgen（build123d 建模栈 + OpenCASCADE 内核）→ 浏览器本地预览，不经过任何云端渲染。
| 组件 | 干什么 | 你需要准备什么 |
|---|---|---|
| 12 个技能（skills/） | 生成/检查 STEP、STL、DXF、URDF/SRDF、DfM、G-code | 无，随安装命令落地 |
| cadgen（packages/cadgen/） | CAD 内核运行时，经 uv 管理 Python | 装好 uv，首次运行需联网 |
| CAD Viewer | 本地浏览器预览模型，localhost 服务器 | 无，插件自带 |
| 切片器（可选） | 把网格切成 G-code | OrcaSlicer，仅打印场景需要 |
划重点：没有服务器要部署、没有数据库、不需要 GPU，一台能跑 Node.js 和 Python 的电脑就够。唯一要留意的默认行为是遥测——使用统计默认上报（随机 ID，不含文件、路径和提示词），不放心就uvx cadgen telemetry off。
动手前确认这几点
- uv：
uv --version有版本号即可。CAD 运行时统一走 uv，技能固定用它托管的 Python 3.13，所以系统里 Python 多旧都无所谓。 - Node.js（LTS）：
node --version。Skills CLI 通过npx调用。 - Git：
git --version，仅手动克隆路径需要。 - 网络：首次运行会下载 cadgen 运行时和快照用的无头浏览器，第一次生成模型必须在线。
- 切片器（可选）：只有要切 G-code 才装 OrcaSlicer，其余场景跳过。
完整安装步骤
Step 1：装好 uv 并确认
CAD 的 Python 环境全部由 uv 托管，缺它后面全卡住。
uv --version # 预期：输出 0.x 版本号；缺失则按 uv 官方文档装一遍Step 2：按你的 Agent 装 text-to-cad
推荐路径是 Skills CLI（跨平台行为最一致）：
npx skills add earthtojake/text-to-cad#latest # 预期：安装成功提示，技能文件落入对应 Agent 的技能目录没有 Skills CLI 环境的 Agent 走各自插件命令（见上一节），Cursor 则克隆仓库到~/.cursor/plugins/local/text-to-cad。注意各应用对分支的写法不同（#latest/--ref latest/@latest），别省略——稳定安装取latest分支，省略则装main，里面可能带着未发布的改动。
Step 3：重启 Agent
必须整进程重启，不是重开聊天窗口。技能列表只在启动时扫描，热加载不存在，这是"装完没反应"的头号原因。
Step 4：首跑自检
首次调用 cadgen 会下载运行时，顺手用 doctor 确认内核能加载（技能文档里把这个 uvx 长命令简写为cadgen）：
uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.24 cadgen doctor <skill-dir> # 预期：报告当前安装与版本，CAD 内核加载成功如果之后要切 G-code，再单独装 OrcaSlicer 并把可执行目录加进PATH；要推 Bambu 打印机则装 Bambu Studio，见 skills/gcode/。
不同环境的坑：安全策略、执行权限与下载
⚠️Windows 11 Smart App Control 拦内核（安全策略）。现象：每条 cadgen 命令都报ImportError: DLL load failed while importing OCP。原因：OCP（OpenCASCADE 的 Python 绑定）的 wheel 带未签名原生模块，Smart App Control 默认开启时直接拦截，事件查看器记为 Event ID 3077。解法：cadgen doctor会点名这个原因；关掉 Smart App Control（一次性操作，关了回不去）或改用 WSL2 跑，WSL 里不受影响。
PowerShell 执行策略拦 npx（权限）。现象：npx报"无法加载，因为在此系统上禁止运行脚本"。原因：PowerShell 默认执行策略。解法：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，或干脆换命令提示符执行。
Python 版本冲突（版本）。现象：自己手动跑脚本时 build123d 报错。原因：你用了系统里的旧 Python 而不是 uv 托管的 3.13。解法：所有建模命令都走uvx --from cadgen==... python，别用裸python。
首次运行卡住（依赖下载）。现象：第一条 cadgen 命令迟迟没输出。原因：首次运行要下载运行时，首次快照还要下载无头浏览器。解法：确认网络可达后等它下完，失败就检查代理再重试一次。
macOS 隐私策略（权限）。现象：Agent 读不到技能文件。原因：技能写在~/.claude/skills等用户目录，受"文件与文件夹"授权管理。解法：系统设置里给对应 Agent 放行文件夹访问。
遥测默认开启（隐私策略）。现象：担心数据外发。原因：使用统计默认上报，但只有计数和随机 ID，无文件名、路径、内容。解法：uvx cadgen telemetry off，同时删除已发送的数据。
跑起来之后：第一个 STEP 验证
✅ 最小验证就一句话——把你的 Agent 打开，说："画一个 40×20×6 mm 的 bracket，生成 STEP，在 CAD Viewer 里给我看"。预期结果：对话里出现 viewer 卡片，或给你一个 localhost 链接；浏览器打开后模型能旋转、能缩放，就像这样：
没看到模型？按顺序查三点：
- Agent 重启了没有（技能扫描只在启动时发生）。
cadgen doctor是否报告内核加载成功——失败多半是上面 Windows 安全策略那条。- 首跑下载是否完成：断网环境第一次一定失败，连上网重跑即可。
想跑现成样例，仓库里 models/examples/l_bracket.py 这类脚本让 Agent 执行一遍，输出落在声明的 STEP 目录里。
装不上 / 不生效？高频问题
装完 Agent 里看不到技能？
重启 Agent，技能列表不热加载。仍看不到就确认文件真的落到了目标目录，ls ~/.claude/skills（各 Agent 目录不同）。
报 ImportError: DLL load failed while importing OCP？
Windows 11 Smart App Control 拦截了未签名的 OCP 内核模块。cadgen doctor确认原因后，关掉 Smart App Control 或改用 WSL2。
技能行为和文档对不上？
多半是省略了#latest装到了main。重跑同一条安装命令即可更新，然后重启 Agent。
G-code 技能提示找不到切片器？
OrcaSlicer 不随 text-to-cad 附带，需另装并加进PATH，macOS 一条brew install --cask orcaslicer搞定。
遥测数据发的是什么，能关吗？
只有工具调用计数、版本等统计，绑随机安装 ID，不含你的文件和提示词。uvx cadgen telemetry off关闭并删除已发数据。
一条命令：npx skills add earthtojake/text-to-cad#latest覆盖三大平台的主体安装，插件式 Agent 换各自的 marketplace 命令。
装完重启：技能列表只在 Agent 启动时扫描，不重启等于没装。
认准分支：稳定安装带#latest，省略装到main会混进未发布改动。
全程本地：无服务器、无数据库、无 GPU，预览渲染都在你自己的机器上完成。
现在就可以打开你的 Agent，说一句"画一个 40×20×6 mm 的 bracket 并生成 STEP"，几分钟后在浏览器里转起来的就是你的第一个零件。
【免费下载链接】text-to-cadGive your agent CAD superpowers.项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
