在 Linux 上从源码运行 text-to-cad Studio
text-to-cad 是一套「用自然语言做机械设计」的工具链:背后是 build123d(OCP)建模内核,加上 netgen 网格与 CalculiX 强度校核,再加上 3D 打印、CNC、导出等一批技能。Studio 则是它的桌面外壳——一个 Electron 应用,你在里面和 agent 对话,agent 调用 CAD 工具把零件真正建出来。
问题在于,官方打包脚本在 Linux 上直接 stop,没有现成的安装包。所以想在 Linux 用上它,只能从源码跑仓库自带的 dev 版(checkout 版 Studio)。下面是我在自己机器(CachyOS、x86_64、Wayland)上跑通的完整步骤。
几个先要知道的事实,能帮你判断值不值得动手:
- 整套依赖装下来约 1.5~3 GB,第 5 步最耗时;
cadquery-ocp/netgen-mesher/cad-ccx的 cp314 轮子只有 Linux x86_64,ARM64 缺 netgen,强度校核不可用;- 需要 git、uv,以及一个 26.x 的 Node(见第 2 步)。
1. 准备 git repo
1 | |
CAD 能力全在 text-to-cad 子模块里,Studio 启动时会先检查它的 .claude-plugin/marketplace.json,缺了就直接退出。
子模块命令一定要带路径,这不是风格问题:仓库索引里有 vendored 的 gitlink(.repos/alchemy-effect/...),但 .gitmodules 只声明了 text-to-cad,所以不带路径的 git submodule status 和任何 --recurse-submodules 都会报 no submodule mapping found。
最后那条检查点的含义是:行首是一个空格(而不是 - 或 +),且 sha 与父仓库记录的 pin 一致,说明子模块处在干净状态。
2. 确认 Node.js 26 环境
monorepo 的 package.json 里 engines.node 写的是 26.12.1:
1 | |
低于 26 通常只是告警——vite-plus@1.4.0 自身允许 ^24.11.0,我一开始就是在 24 上把依赖装完的。但如果哪一步真被 engines 拦下来,切到 26 重跑即可。
具体用哪种方式装 Node 26 随意,下面只是我用的 fnm;nvm、volta、发行版包、官方二进制都一样,本质是让 PATH 上的 node 是 26.x:
1 | |
换 Node 大版本不需要重装 node_modules:它按项目放,不按 Node 版本,而且这个仓库里没有按 ABI 编译的原生模块(node-pty、sharp、koffi 都是 N-API 或按平台的 prebuild)。唯一代价是 engines 是个精确值,切过去之后建议在第 3 步重跑一次 vp install(store 命中,十几秒)。
3. 装 monorepo
1 | |
仓库用 vite-plus 的 vp 管依赖,版本在 catalog 里固定为 1.4.0。本机没有全局 vp,所以用 npx 临时拉这个版本执行安装。
4. 下载 Electron 运行时
1 | |
Electron 从某个版本起不再带 install 脚本,运行时得单独拉一次。
5. 准备 text-to-cad(checkout 版插件要用)
1 | |
这一步就是在造一个独立的 Python 3.14 环境,把 CAD 建模、网格、求解所需的二进制全装进去。最后那行 import 检查点跑通,说明建模、网格、求解、导出四条链路都齐了。
6. 启动脚本
写启动脚本 ~/.local/bin/cad-studio:
1 | |
1 | |
几个关键字都是有意为之:
TEXT_TO_CAD_STUDIO_HOME是 Studio 自己的状态根目录(数据库、会话历史、插件副本、cad/state),不设时默认是~/.text-to-cad-studio,带TEXT_TO_CAD_DEV=1时是~/.text-to-cad-studio-dev。它必须写绝对路径,Node 不展开~。TEXT_TO_CAD_DEV=1决定跑哪套 CAD 工具。不设时 Studio 会用uvx从 PyPI 拉发布版cad-mcp,技能只有 Jake 自带的 10 个;设了才用第 5 步刚建好的.venv,并多出fdm、export、board-fab、cnc这批 job 技能。建议始终带上。STUDIO_PROJECTS_DIR/STUDIO_NEW_PROJECTS_DIR分别是项目记录目录和新项目文件夹位置。换一套路径就等于换一套状态,旧项目不会自动出现。exec node_modules/.bin/vpr而不是pnpm studio:desktop:少一层 corepack/pnpm 解析,只依赖node,行为完全一致。exec 9>…+flock -n 9做单实例:文件描述符跟着exec进到 Studio 进程里,所以锁的生命周期就是 Studio 的生命周期。
7. 启动
1 | |
终端会先打印构建开发插件的信息,然后弹出 Electron 窗口,标题是 Studio。注意:关掉窗口不等于退出——dev server 还在跑,要 Ctrl-C 或关掉终端窗口,整棵进程树才会干净结束。
8. 开始菜单启动项(可选)
装图标(来源是仓库自带的 512×512 图标):
1 | |
写菜单项 ~/.local/share/applications/cad-studio.desktop:
1 | |
验证:
1 | |
三条容易踩的点:
Exec必须写绝对路径,~不会被展开;Icon=cad-studio是图标名,对应上面装进图标主题的文件名(不带扩展名);Terminal=true是刻意的:这套 dev 启动是「vp pack --watch+ Electron」,带终端才能靠 Ctrl-C 把 dev server 一起收掉;而且Categories只能有一个 main category,写成Development;Graphics;会让条目在菜单里出现两次。
之后在开始菜单里搜 CAD Studio 就能点开。点第二次只会打印 Studio is already running. 然后退出,不会起第二套。
如果这篇文章对您有帮助,欢迎打赏支持