text-to-cad安装与配置避坑指南：常见报错原因与解决方案

text-to-cad安装与配置避坑指南常见报错原因与解决方案【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cadtext-to-cad 是一个面向 CAD、CAE、CAM 的 Agent 技能库agent skills library让 AI 助手能够用自然语言生成并校验 STEP 零件、STL/3MF 网格、URDF/SRDF/SDF 机器人描述文件并在本地浏览器中预览。很多新手在 text-to-cad 安装与配置阶段会踩到技能装不上Viewer 起不来文件打不开等坑本文按正确安装 → 常见报错 → 解决方案的顺序逐一拆解帮你一次性配通。先搞懂它text-to-cad 是怎么工作的text-to-cad 不是一个独立软件而是一组可安装到你 AI Agent 里的技能Skills。安装后Agent 就能调用本地脚本来建模、检查、导出和预览 CAD 文件。内置技能包括技能作用说明文档CAD用自然语言/图片生成 STEP 零件可导出 STL、3MF、GLBskills/cad/SKILL.mdCAD Viewer浏览器本地预览 CAD 与机器人文件skills/cad-viewer/SKILL.mdURDF / SRDF / SDF生成机器人结构、规划组与仿真模型skills/urdf/SKILL.md等G-code / Bambu Labs切片并校验 FDM 打印文件对接本地打印skills/gcode/SKILL.mdDXF / SDF / SendCutSend2D 图纸、仿真世界与厂商前校验skills/dxf/SKILL.md等理解这一点很重要几乎所有装好却用不了的问题本质都是 Agent 没有真正拿到技能文件下面的排错都围绕它展开。安装步骤三条正规路径路径一Skills CLI推荐npx skills install earthtojake/text-to-cad这是官方首选安装方式会为受支持的 Agent 逐个安装技能。路径二Codex / Claude Code 插件# Codex要求 Codex 0.142.0 或更高版本 codex plugin marketplace add earthtojake/text-to-cad codex plugin add cadtext-to-cad # Claude Code claude plugin marketplace add earthtojake/text-to-cad claude plugin install cadtext-to-cad路径三克隆仓库生产使用请从main分支安装或克隆main分支包含各 Agent 安装器需要的生成产物git clone https://gitcode.com/GitHub_Trending/tex/text-to-cad本地开发则从develop分支切入并用仓库自带脚本建立技能软链接流程见CONTRIBUTING.mdscripts/install/install-skills.sh --agent codex 装完记得重启或重载你的 Agent让它重新扫描技能目录否则新技能不会出现在列表里。常见报错与解决方案按踩坑频率排序坑 1Codex 版本太旧插件静默消失现象执行了codex plugin add没有任何报错但codex plugin list里看不到 cad 插件。原因旧版 Codex低于 0.142.0无法解析仓库根级插件会直接跳过且不报错。解决升级 Codex 后重新安装npm install -g openai/codexlatest坑 2从develop分支安装技能文件凭空缺失现象技能目录存在但脚本、运行时文件缺失运行直接失败。原因develop分支用软链接symlinks指向共享源码各 Agent 安装器对软链接的处理不一致——Skills CLI 会解引用成真实文件Claude Code 原样保留而Codexplugin add会无提示地丢弃软链接装出来的技能运行时文件是空的。解决使用者/生产环境只从main分支安装main中全部是真实文件贡献者本地开发用scripts/dev/setup-symlinks.sh --check检查链接布局是否完整缺了重跑一次该脚本即可。坑 3Python 环境报错ModuleNotFoundError / 语法错误原因CAD 技能需要Python 3.11仓库开发环境推荐用 Python 3.12 建虚拟环境见CONTRIBUTING.md。解决python3.12 -m venv .venv ./.venv/bin/python -m pip install --upgrade pip ./.venv/bin/python -m pip install -r requirements-dev.txtCAD 技能运行时依赖很轻核心是cadgen与playwright见skills/cad/requirements.txt一般由安装流程自动带入无需手动安装。坑 4克隆后图片/模型文件只有 133 字节现象assets/下的演示 GIF、models/下的示例 CAD 文件内容是一行version https://git-lfs...文本。原因这些大文件由 Git LFS 管理轻量克隆默认不拉取真实内容。解决按需显式拉取git lfs pull --includeassets/** git lfs checkout models坑 5CAD Viewer 启动失败现象 A端口冲突。Viewer 固定监听3245十六进制的 0xCAD端口被占用时直接报错退出不会自动换端口。解决手动指定空闲端口npm --prefix scripts/viewer run start -- --host 127.0.0.1 --port 空闲端口现象 BCannot find package cadjs。Node 依赖缺失。解决在对应目录执行npm install后重试。现象 C/返回 404后端 API 却正常。这是有后端没前端——start命令提供的是预构建的dist/包没有构建产物就只有 API。解决先构建再启动npm --prefix viewer run build npm --prefix viewer run start -- --host 127.0.0.1现象 D沙箱环境出现EPERM/EACCES本地绑定失败。属正常现象用所需权限重新运行即可说明见skills/cad-viewer/SKILL.md。坑 6Viewer 打开链接后找不到文件三个高频细节全部写在skills/cad-viewer/SKILL.md里URL 路径必须是绝对目录。Viewer 从任意工作目录启动相对路径会解析到错误位置路径填模型工作区而不是文件所在文件夹例如指向项目的models/根目录再用?file选中具体文件这样文件浏览器能列出全部模型点开头目录会被目录扫描跳过。模型放在.review/等隐藏目录下时直接查询能打开但目录树里永远不显示看起来就像文件不存在——把可构建的模型移出点目录即可。Windows 用户注意盘符要放在 URL 路径里并使用正斜杠例如D:\project\models写作.../3245/D:/project/models。坑 7生成模型时脚本报路径/权限类错误原因CAD CLI 的目标路径相对于命令当前工作目录解析而不是相对技能目录在错误目录执行会让产物写进技能目录或找不到输入。解决始终在拥有这些 CAD 文件的工程目录下运行命令并传 cwd 相对的目标路径约定见skills/cad/SKILL.md。另外若输出出现waiting for another run to finish building ...说明有并发构建持锁属正常等待无需干预。装好了怎么验证三步自检全过即配置成功看链接是否建立scripts/install/install-skills.sh --list-agents列出各 Agent 的目标目录对照确认技能链接指向本仓库的skills/重启 Agent后让它列出可用技能cad、cad-viewer等应出现在列表中跑一次最小任务让 Agent 用 CAD 技能生成一个简单零件并启动 CAD Viewer 预览能拿到本地预览链接即全链路打通。常见问题速查表报错/现象原因一句话解决codex plugin list里没有技能Codex 版本低于 0.142.0静默跳过升级 Codex 到最新版重装技能文件缺失、脚本报错从develop安装软链接被丢弃改用main分支安装Python 模块/语法报错Python 版本低于 3.11用 3.12 重建 venv文件是 133 字节文本Git LFS 未拉取git lfs pullViewer 端口报错退出3245 被占用不会自动换端口加--port nViewer/返回 404缺少预构建前端dist/先npm run build再启动链接文件不存在相对路径 / 点开头目录 / 路径不是工作区用绝对路径指向models/根目录小结text-to-cad 的安装配置要点其实就三条从main分支装、装完重启 Agent、Python 用 3.11。绝大多数报错都源于从develop分支安装导致的软链接丢失以及 Codex 旧版本静默跳过插件。遇到 Viewer 问题时记住绝对路径 固定端口 预构建产物三要素基本不会翻车。遇到具体技能的工作流问题可以直接阅读对应技能目录下的SKILL.md如skills/cad/SKILL.md里面写明了该技能的正确用法与校验流程。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考