Text-to-CAD：参数化源码、几何证据与负责任的交接
Text-to-CAD 本地配置：匹配技能依赖，从正确的模型目录启动
区分技能安装、cadgen 依赖和浏览器渲染，并理解查看器链接为什么依赖启动目录。
你将学会
- 技能文本和运行时必须匹配
- 从有意选择的模型工作区启动
- 交付查看链接前先核对文件
开始前需要
- 了解 Python 函数、模块与文件路径
- 理解单位以及设计和实物之间的区别
规划有边界的 CAD 练习，区分源码新鲜度、文档检查、视觉审阅和制造决策。
先看结论
- 运行时应匹配技能固定的依赖版本。
- 查看器当前目录决定服务的工作区。
- 使用启动器返回的 URL 并核对文件路径。
技能文本和运行时必须匹配
README 介绍逐项技能安装，而各技能 requirements 文件固定预期 cadgen 版本。CAD 指南要求使用当前项目解释器与对应依赖，并通过 cadgen doctor 检查所选技能目录的兼容性。不能假设任意全局 cadgen 都匹配刚下载的说明。
查看器指南要求 Python 3.11 或以上，cadgen 包携带服务端及预构建客户端，运行时不需要 Node。截图渲染还需要单独安装浏览器，这不是 Python 依赖安装自动完成的事。缺少 Chromium 与缺少 cadgen 属于不同问题。
从有意选择的模型工作区启动
查看器服务的是启动时的当前目录，进程运行期间固定不变。应该选择小范围模型工作区，而不是含依赖和无关文件的仓库根目录。读取 JSON 返回的 URL，不要假设默认起始端口一定空闲。
文档说明启动器可以复用同一真实目录与查看器标识的实例，也可以使用空闲端口启动新实例。链接中的 file 参数相对于该实例服务的根目录。因此，不同实例中同样的相对链接可能指向不同文件。
交付查看链接前先核对文件
先构建生成模型并确认文件存在。查看器能根据导入或已有 STEP 的字节编译显示内容，但不能通过运行源码创建缺失几何。目录或不可访问路径都不能替代目标文件。
示例假定已完成审阅后的安装，当前目录就是模型工作区。练习使用本地绑定。本次没有安装软件包或浏览器、启动 CAD 查看器、公开暴露服务或建立制造设备连接。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
选择专用解释器和已审阅技能版本。
- 2
检查运行时与浏览器可用性。
- 3
构建或找到准确文档。
- 4
从模型工作区启动并读取返回链接。
可复制示例
cadgen viewer --host 127.0.0.1 --json
cadgen viewer list常见问题
查看器运行时必须安装 Node 吗？
所检查指南说明 cadgen 已携带服务端和预构建客户端，运行时不需要 Node。
打开链接会运行缺失的模型源码吗？
不会，它显示已有文件，生成文件需要先完成构建。
资料来源
- Text-to-CAD / README.md来源核查 2026-09-14
- Text-to-CAD / skills/cad/SKILL.md来源核查 2026-09-14
- Text-to-CAD / skills/cad-viewer/SKILL.md来源核查 2026-09-14