1. 痛点突围：它究竟击穿了什么工程死穴？
传统大语言模型处理硬件设计时，其输出往往卡在虚幻的文本描述或畸形的坐标矩阵中。开发人员向 AI 索要一个三维结构时，得到的只能是无法直接导入生产线的代码片段或缺乏几何拓扑拓扑约束的网格文件。缺乏对物理制造边界的感知、缺乏对公差与切片格式的理解，导致 AI 生成的几何体无法直接承载任何真实的工程加工价值。
earthtojake/text-to-cad 通过技能注册表模式，将 CAD 几何内核、切片引擎、机器人描述规范直接编译为 Agent 可以精确调用的本地原语。模型不再凭借参数幻觉盲目猜测三维坐标，而是通过调用专门的 cadgen 库与本地依赖，在隔离沙箱中完成从草图、参数化实体到 STEP 工业交换格式的完整构建流。工程人员借此绕过了复杂的三维建模软件 API 学习曲线，用最熟悉的自然语言或图纸输入驱动本地硬件生产管线。
💡 架构核心洞见：通过将复杂的 CAD 几何计算下沉至本地受控的 CLI 与插件运行时，该架构成功将不可控的 LLM 文本生成收敛为确定性的工程文件输出。
2. 核心架构与底层数据流向解析
该项目采用基于 Skills 注册表的契约式分发机制。每一个具体的技能目录内均包含独立的依赖约束与执行契约，根目录通过 npx skills 或各大 AI IDE 插件市场进行统一挂载。当用户输入设计指令时，Agent 通过上下文动态路由激活对应的技能模块，借助本地安装的 Python 运行时驱动底层几何引擎生成中间产物。
[ User Prompt / IDE ] ---> [ Skills CLI / Plugin ] ---> [ Context Router ]
│
▼
[ Local Review / Viewer ] <--- [ CAD / G-code / DFM Engine ] <--- [ Isolated Execution ]
底层执行依赖 uv 运行时对隔离环境进行包管理，确保每一次几何构建或切片操作都在精确锁定的 cadgen 版本下运行。在 Codex 或 Claude Code 插件中，本地服务器被唤醒并托管网页端可视化网格，直接将渲染出的 STEP 或网格文件注入到开发者的聊天侧边栏或独立浏览器标签页中，实现从对话到物理视图的无缝衔接。
3. 技术选型与性能横向硬核对比
| 选型维度 | 本方案 (text-to-cad) | 传统实现范式 | 典型竞品方案 | 生产环境收益 |
|---|---|---|---|---|
| 依赖分发机制 | 动态 Skills CLI 注入 | 手动配置 Python 虚拟环境 | 封闭云端 SaaS API | 降低 90% 的本地环境配置成本 |
| 输出格式丰富度 | STEP, URDF, SRDF, G-code, DXF | 仅限 STL 或基础网格 | 专有闭源格式 | 直接对接主流数控机床与 3D 打印机 |
| 本地安全性 | 代码全在本地沙箱运行，数据零外泄 | 敏感模型上传第三方云服务器 | 极高云端依赖度 | 满足严苛的硬件机密保护要求 |
| 可视化闭环 | 插件内嵌 CAD Viewer 与对话侧边栏联动 | 需切换至外部大型 CAD 软件查看 | 无原生预览能力 | 调试效率提升数倍 |
这套技术选型彻底抛弃了依赖云端重型渲染集群的传统思路。通过在本地 IDE 中挂载轻量级 Skill，开发者既能保有对本地 CAD 核心算力的完全控制权，又无需承担高昂的商业闭源软件授权费用。
4. 手把手极客实操：从零构建最小闭环
在本地环境中部署 text-to-cad 技能库，首先确保已安装 Node.js 与 Astral uv 运行时。通过官方 Skills CLI 将全部硬件开发技能直接注入至支持的 Agent 宿主环境中。
# 使用 Skills CLI 全局安装全部硬件交互技能
npx skills add earthtojake/text-to-cad
# 如果需要接入 Codex 插件市场，执行以下命令
codex plugin marketplace add earthtojake/text-to-cad
codex plugin add text-to-cad@earthtojake
# 验证本地 uv 运行时状态并检查技能连通性
uv --version
在完成依赖安装并重启 Agent 宿主应用后，可直接在对话框中调用以下生产级测试指令：
# 示例：通过 Agent 触发 cad 技能生成带有 4 个 M3 安装孔的铝合金支架
# 代理会自动调用 text-to-cad 内部的 cad 模块并导出高精度 STEP 文件
import cadquery as cq
# 定义基础长宽与厚度参数
length, width, thickness = 100.0, 50.0, 10.0
# 构建带倒角的底板实体并打上定位孔
bracket = (
cq.Workplane("XY")
.box(length, width, thickness)
.faces(">Z")
.workplane()
.rect(80, 30, forConstruction=True)
.vertices()
.hole(3.2)
)
# 导出标准的 STEP 工业交换格式供下游 CNC 或 DFM 校验
cq.exporters.export(bracket, "bracket_output.step")
运行上述脚本后，指定的本地目录将即时生成 bracket_output.step 文件，且 Agent 侧边栏的 CAD Viewer 会自动加载渲染该实体的网格状态。
5. 生产落地踩坑指南与避坑建议 (Gotchas)
在团队生产环境中落地该技能库时，必须警惕由于底层几何内核更新或包管理冲突引发的隐性故障。
⚠️ 避坑预警 [更新命令盲区]：切勿使用
npx skills update期望拉取最新发布的硬件技能。该命令仅会刷新当前锁文件（lockfile）中已有的条目，导致上游新追加的技能被静默忽略。必须通过重新执行npx skills add earthtojake/text-to-cad来强制覆盖全量技能树。⚠️ 避坑预警 [旧版插件残留命名冲突]：早期版本中的市场命名或已废弃的独立组件（例如
cad-viewer）可能导致命名空间污染。若在升级时遇到冲突，必须手动执行npx skills remove cad-viewer并在 IDE 插件管理中移除旧版text-to-cad市场，再重新添加earthtojake命名空间下的最新插件。
严格遵循版本固定与依赖隔离策略，能够确保 AI 硬件生成流水线在本地开发机或 CI 持续集成服务器上长期稳定运转。