text-to-cad 詳細教學

對應 repo: https://github.com/earthtojake/text-to-cad（3.7k stars / 428 forks / MIT，截至 2026-05-21）

1. 專案定位

1.1 它是什麼

earthtojake (Jake Brukhman) 開源的 7 個跨 agent CAD skill 集合，把 coding agent（Claude Code / Codex / Cursor）變成 CAD 工程師：

生成：寫 build123d Python source → regenerate STEP / STL / 3MF / DXF / GLB
機器人：寫 URDF / SRDF / SDF
預覽：本地 CAD Explorer viewer（Next.js + WASM，無 backend）
採購：拉 step.parts off-the-shelf（螺絲 / 軸承 / 電機）
製造：SendCutSend 上傳前 preflight 檢核

1.2 它解決什麼問題

自然語言 → CAD source：「做一個 50×50mm 鋁 L-bracket 兩個 M4 孔」→ agent 寫 build123d Python → regenerate STEP
生成檔不可信問題：所有 skill 強制「edit Python source first, regenerate explicit target」（避免 agent 亂修 STEP）
agent 缺乏「指物」能力：@cad[hole_id_42] 系統讓 agent 對特定 feature 做 follow-up edit
單一 agent 無法跨硬體 / 機器人 / 模擬：本 repo 一站打通 CAD → URDF → SRDF (MoveIt2) → SDF (Gazebo / Ignition)
「我要去找這顆螺絲的 STEP 檔」：step.parts catalog 整合到 skill

1.3 與其他 text-to-CAD 工具的差異

工具	開源	source 優先	機器人	採購整合	viewer
text-to-cad / CAD Skills	✅ MIT	✅ build123d Python	✅ URDF/SRDF/SDF	✅ step.parts + SendCutSend	✅ WASM local
Zoo Modeling API (formerly KittyCAD)	部分	❌ ML-only	❌	❌	雲端
MeshyAI	❌	❌ mesh-only	❌	❌	雲端
FreeCAD AI 外掛	✅	❌ GUI	部分	❌	FreeCAD GUI

1.4 適合誰用

機械工程師 + 用 AI agent 編程：把 part design 自動化
機器人開發者：CAD → URDF → SRDF → SDF 端到端
3D printing maker：3MF / STL 生成
Laser cutting 用戶：DXF + SendCutSend preflight 一條龍
教育：10 個 benchmark 是現成的「CAD 教學案例」
本團隊：若引入「實驗器材 / 設備外殼自動化設計」，這是低門檻入口

2. 安裝指南

2.1 一鍵裝 skills（推薦）

1npx skills add earthtojake/text-to-cad
2# 重啟你的 coding agent 才會看到新 skills

2.2 Python 環境（必裝 — 給 build123d）

1cd <your-cad-project>
2python3 -m venv .venv
3source .venv/bin/activate
4
5# 從 skills/cad/requirements.txt 抄
6./.venv/bin/pip install build123d ezdxf numpy trimesh vtk
7
8# 若要做 URDF / SRDF / SDF：可能還要加 ROS-related 依賴（看各 skill README）

⚠️ OCP 安裝可能很慢：build123d 依賴 cadquery-ocp（OpenCascade Python wrapper），下載約 250MB；macOS Apple Silicon 在某些版本要走 conda-forge。

2.3 CAD Explorer viewer（render skill 自動處理）

不需要手動裝：當 render skill 第一次被觸發，會用 dev:ensure 啟動 viewer（port 動態分配）。

1# 手動啟動（debug 用）
2cd skills/render/scripts/viewer
3npm --prefix . run dev:ensure -- --file /path/to/model.step

2.4 harness（給整個 CAD 專案的 instruction）

1# 把 harness 複製到你的專案 root
2cp text-to-cad/harness/AGENTS.md your-cad-project/
3cp text-to-cad/harness/CLAUDE.md your-cad-project/
4
5# CLAUDE.md 內容就是「@AGENTS.md」— 全部規則寫在 AGENTS.md 一份


flowchart TD
    A[使用者 prompt] -->|natural language| B[Agent: Claude/Codex]
    B -->|cad skill| C[寫 build123d Python source]
    C -->|./venv/bin/python| D[regenerate .step / .stl / ...]
    D -->|render skill| E[CAD Explorer
WASM viewer]
    B -->|urdf skill| F[寫 gen_urdf Python source]
    F -->|scripts/urdf| G[regenerate .urdf]
    G -->|render skill| E
    B -->|srdf skill| H[寫 SRDF + MoveIt2 IK 設定]
    H -->|moveit2_server| I[本地 MoveIt2 ws server]
    B -->|step-parts skill| J[拉 off-the-shelf STEP]
    B -->|sendcutsend skill| K[DXF preflight + 上傳檢核]

3. 核心架構解析

3.1 7 個 skill 的職責分工


graph TB
    subgraph "Core CAD Pipeline"
        CAD[cad skill
build123d → STEP/STL/3MF/DXF/GLB]
        RENDER[render skill
CAD Explorer + snapshot CLI]
    end
    subgraph "Robotics Stack"
        URDF[urdf skill
機器人結構]
        SRDF[srdf skill
MoveIt2 語意]
        SDF[sdf skill
Gazebo/Ignition 模擬]
    end
    subgraph "External Integration"
        STEPP[step-parts skill
off-the-shelf catalog]
        SCS[sendcutsend skill
製造商 preflight]
    end
    CAD --> RENDER
    URDF --> RENDER
    SRDF --> RENDER
    SDF --> RENDER
    URDF -.frame/mesh.-> CAD
    SRDF -.URDF link.-> URDF
    SDF -.URDF link.-> URDF
    STEPP --> CAD
    SCS --> CAD

3.2 「source-first / regenerate explicit target」工作流


sequenceDiagram
    participant U as 使用者
    participant A as Agent
    participant CAD as cad skill
    participant Py as build123d (Python)
    participant FS as 檔案系統
    participant R as render skill

    U->>A: 「做一個 L-bracket，50x50, 3mm 厚, 兩個 M4 孔」
    A->>CAD: 讀 SKILL.md + references/natural-language-specs.md
    A->>A: 用 default assumptions（mm, XY plane, +Z up）
    A->>FS: 寫 src/l_bracket.py (build123d source)
    Py->>Py: 執行 src/l_bracket.py
    Py->>FS: 寫 STEP/l-bracket.step
    A->>R: 觸發 render（傳 STEP path）
    R->>R: dev:ensure → 啟動或重用 viewer
    R->>U: 印出 http://localhost:/view?file=...
    U->>U: 在瀏覽器看 3D 模型
    Note over U,A: 修改循環
    U->>A: 「孔位向中間移 5mm」
    A->>FS: 編輯 src/l_bracket.py（不直接改 .step！）
    Py->>FS: regenerate STEP/l-bracket.step
    A->>R: 重新 render

設計重點：所有 skill 強調 「edit Python source first, regenerate explicit .step / .urdf target」。Agent 不應該直接編輯 STEP / URDF XML — 否則下次 regenerate 會被蓋掉。

3.3 @cad[...] 參考系統

inspect script 給每個 feature 一個穩定 ID，agent 可以拿著 @cad[hole_42] 做 follow-up：

1User: 「把 @cad[hole_42] 改成沉頭螺絲（M4 countersunk）」
2Agent: ✓ 不需 re-describe 整個 part；直接找到 hole_42，改 build123d source 對應 feature

3.4 4 個 robotics output 的關係


flowchart LR
    CAD[CAD STEP/STL] --> URDF[URDF
結構 / 連桿 / 關節]
    URDF --> SRDF[SRDF
群組 / 結構限制 / 名字]
    URDF --> SDF[SDF
物理參數 / plugin]
    SRDF --> MOVE[MoveIt2
IK / planning]
    SDF --> GAZ[Gazebo / Ignition]
    URDF -.RViz / robot_state_publisher.-> RV[視覺化]

每個 skill 對應一種 robotics artifact，互不重疊但互相依賴。

3.5 CAD Explorer viewer 技術棧

Framework: Next.js + React + Vite
3D engine: three.js
STEP/STP rendering: WASM-based OCCT (OpenCascade Technology) build → 在瀏覽器解析 STEP
URDF rendering: urdf-loader (npm)
No backend：完全本機跑，dev server 動態分配 port
Demo: https://demo.cadskills.xyz

最近 10 個 commit 都跟 docs / viewer 的 Vercel build / three.js dependency 有關 — 顯示 production 部署仍在收斂。

4. Helper Scripts 詳細用法

4.1 skills/cad/scripts/

Script	用途
`inspect/cli.py`	給 build123d 物件加 stable feature ID（`@cad[...]` 來源）
`dxf/cli.py`	把 build123d face / sketch 轉 DXF
`render/cli.py`	snapshot HTTP request 到 viewer
`common/metadata.py`	用 `ast.literal_eval` 安全解析 metadata envelope

4.2 skills/render/scripts/viewer/ (CAD Explorer)

命令	用途
`npm --prefix . run dev:ensure -- --file <path>`	啟動或重用 viewer，傳檔
`npm --prefix . run snapshot -- --file <path> --out <png>`	不用瀏覽器，直接出 PNG

重要規則（從 SKILL.md）：

不要用 npm run dev -- --port ... 或 raw vite dev（會繞過 port reuse policy）
若 dev:ensure 報 EPERM / EACCES，用 sudo 重試同一個 port，不要換 port
一般 review 用 still snapshot，不用 GIF（除非是 STEP 參數動畫）

4.3 skills/render/scripts/moveit2_server/

本地 MoveIt2 WebSocket server，可選用 — 給 SRDF skill 做 IK / path planning 測試。

4.4 skills/urdf/scripts/urdf

URDF generator + validator；validation 預設打開，URDF XML 出錯會 fail fast。

4.5 harness/AGENTS.md 規範

對使用本 skill 的 CAD 專案的共用規則（不是 skill 自己的）：

Python 環境優先 ./.venv/bin/python
不在 harness 重複 skill 內容
CAD outputs 走 Git LFS
Project-specific context 寫到 PROJECT.md（root-level compact note）
不要 broad repo scan — skill tool 是 file-targeted

4.6 10 個 benchmark

 1benchmarks/
 2├── 01-rectangular-calibration-block.md
 3├── 02-circular-flange.md
 4├── 03-l-bracket.md
 5├── 04-stepped-shaft-keyway.md
 6├── 05-open-top-electronics-enclosure.md
 7├── 06-clevis-bracket-lightening-cutouts.md
 8├── 07-radial-engine-cylinder.md
 9├── 08-centrifugal-impeller.md
10├── 09-spiral-staircase.md
11├── 10-planetary-gear-stage.md
12└── benchmark_*.gif (10 個 GIF)

每個 .md 是「給 agent 的 brief」，照著它能跑出對應的 STEP。這是學 CAD Skills 的最佳起點。

5. 應用場景

場景	怎麼用
印電子盒 / 散熱片 / 機構件	cad skill 寫 build123d → STL / 3MF for 3D printing
設計實驗器材 fixture	cad skill + sendcutsend preflight → laser-cut DXF
機器人原型 → 模擬 → 實機	urdf → srdf (MoveIt2) → sdf (Gazebo) → 實機
快速找現成零件 STEP 模型	step-parts skill → 拉螺絲 / 軸承 / 電機
CAD review meeting 出 snapshot	render skill → PNG / GIF for 簡報
教學機械工程	benchmarks/ 是現成 10 個 problem set
CAD 版本控制	source 在 git，artifacts 走 LFS — `.gitattributes` 已設定

6. 資安掃描報告

掃描範圍：skills/*/scripts/、harness/、docs/、Python 與 mjs files。

風險面	燈號	說明
Shell injection（CLI scripts）	🟢 低	多數 `subprocess.run` 用 list 形式（如 `skills/cad/scripts/inspect/tests/test_cli.py:12`）
`eval()` 使用	🟢 低	`metadata.py:378` 用 `ast.literal_eval`（白名單 parser，比 eval 安全）
網路出口	🟡 中	render skill 對本機 viewer 用 `urllib.request.urlopen`；step-parts 會去 step.parts catalog 抓 STEP；SendCutSend 會發送 preflight；都是預期行為，但要知道
Git LFS 大檔	🟢 低	CAD output（STEP / STL / GLB）正確走 LFS，避免 bloat repo
build123d / OCP 依賴	🟢 低	都是上游知名 OSS（gumyr/build123d、CadQuery/OCP），活躍維護
viewer 的 three.js / vite 依賴鏈	🟡 中	docs/ 是 Next.js + Vercel build；最近 commit 全在處理依賴解析；正常前端風險
viewer port 暴露	🟡 中	CAD Explorer 預設 listen 本機 — 個人開發無虞；多用戶機器要注意（多 process 多 port 互衝）
SendCutSend 帳號	🟡 中	`sendcutsend` skill 會用使用者的 SendCutSend 帳號做 preflight；不會自動下單，但會送材料 / SKU 資訊
ROS / MoveIt2 server	🟢 低	`moveit2_server/pyproject.toml` 限定本機 ws；非 default
LICENSE	🟢 低	MIT，每個 skill 內自帶 LICENSE 拷貝
第三方 catalog 信任	🟡 中	step.parts 是另一個服務（同作者運營）；下載的 STEP 會直接被使用 — 對 mission-critical 用前最好用 `cad inspect` 確認

綜合燈號：🟢 / 🟡（無紅燈；個人 maker / 小團隊使用安全）

重點建議：

不要在生產 STEP 上跑沒 review 過的 agent 修改（用 git diff source.py 確認）
SendCutSend 用 preflight 模式（不要直接付款 / 下單）
step.parts 拉的 STEP 用 inspect 工具看 feature 統計

7. FAQ

Q1：與其他 4 個 repo 的關係？ A：

garden-skills：跨 agent 寫 web 設計 / 簡報的 skill 集；本 repo 是 CAD 領域版
agentmemory：通用持久記憶；本 repo 是專業領域 skill
dari-docs：測 docs 清晰度；本 repo 的 README + 10 benchmark 可以餵給 dari-docs 自評
claude-plugins-official：本 repo 也可以 list 進去（透過 marketplace.json）

Q2：可以不用 Claude / Codex 跑嗎？ A：可以。skills CLI 支援多家 agent；只要 agent 支援 SKILL.md 規格 + 能執行 Python（給 build123d）+ Node（給 viewer），都能用。

Q3：作者 earthtojake 是誰？ A：Jake Brukhman；本 repo 是個人 maintain（commit 99% 都是他）；步調飛快，2026-04-22 開 repo 1 個月 3.7k stars。

Q4：build123d / OpenCascade 是什麼？ A：

OpenCascade (OCCT)：開源 CAD kernel（C++ 寫，30 年歷史，FreeCAD / CADQuery 都用它）
OCP：OpenCascade 的 Python binding
build123d：基於 OCP 的 Pythonic API（比 CADQuery 更新、更 ergonomic）

選 build123d 是因為「寫 Python 比寫 OpenSCAD 更給 AI agent 友善」— Python 是 agent 最熟的語言。

Q5：URDF / SRDF / SDF 三者差別？ A：

URDF (Unified Robot Description Format)：機器人結構（連桿 / 關節 / 限制 / mesh）— RViz、robot_state_publisher 用
SRDF (Semantic RDF)：在 URDF 之上加「群組」「碰撞 disable list」「IK 配置」— MoveIt2 用
SDF (Simulation Description Format)：URDF + 物理參數 + 模擬器 plugin — Gazebo / Ignition 用

本 repo 三者都支援，且互相串接（SDF 可直接連 URDF link）。

Q6：個人 maker 想做 3D printing 用哪個 skill？ A：只用 cad + render。output STL 或 3MF。step-parts 用來找標準件。

Q7：商用 / 公司用安全嗎？ A：MIT license，可商用；但 sendcutsend 是「美國公司 SendCutSend」的 preflight — 若公司在亞洲，這個 skill 可能用不上（fork 改成自家供應商）。

Q8：為什麼最近 commit 都在處理 docs build？ A：作者剛把 docs site (cadskills.xyz) 上線到 Vercel，three.js / GLTFLoader 等 ESM module 在 Vercel 環境的解析有眉角；commit history 顯示「Fix Vercel three dependency / Alias GLTFLoader / Correct alias」連續修。核心 skill 邏輯穩定；只是 docs site 在迭代。

8. 進階技巧

8.1 寫好「自然語言 → build123d」prompt

參考 skills/cad/references/natural-language-specs.md（在 repo 內讀）。重點：

明確 units（mm 預設）
明確 origin（part 中心或裝配介面）
明確 holes 標準（M3/M4/M5 normal clearance = 3.4/4.5/5.5 mm）
不要要求 JSON 規格 — 全 prose 比較好

8.2 用 @cad[...] 做精準 follow-up

1User: 「inspect L-bracket.step，把所有 feature 列出來」
2Agent (cad inspect): hole_1, hole_2, fillet_3, ...
3User: 「把 hole_1 改成 countersunk for M4」
4Agent: ✓ 改 build123d source 對應 feature，不影響其他孔

8.3 機器人原型完整流程

用 cad skill 設計 link STEP 們（每個 link 一個 STEP）
用 urdf skill 寫 gen_urdf() 把 link 串起來
用 srdf skill 加 MoveIt2 groups + IK 設定
用 sdf skill 加 simulator parameters
用 render skill → CAD Explorer 看每階段視覺化
用 srdf skill 的 moveit2_server 做 IK 測試

8.4 整合進 CI（regenerate target 一致性）

1# .github/workflows/regen-check.yml
2- run: ./.venv/bin/python src/all_parts.py
3- run: git diff --exit-code STEP/  # source 改了但 STEP 沒 regen → CI fail

8.5 把生成的 STEP 自動同步到 step.parts（如果你也有 catalog）

拉 step.parts 的 catalog 入口腳本，加 --auto-publish flag — 內部團隊 catalog 一鍵發布。

8.6 fork 自家工廠的 sendcutsend 變體

抄 skills/sendcutsend/ → skills/your-vendor/
改 references 內的 catalog / SKU / 服務清單
改 SKILL.md 的 description 對應廠商名

9. 整合進其他工作流

既有 skill	整合方式
`ai-gh-save`	已存 standard gh-save md 在 `inbox/2026-05-21-github-earthtojake-text-to-cad.md`
`gh-tutorial-qd`	本檔產出
`garden-skills`	兩者都是「SKILL.md skill 集合」結構相同；可以併存
`agentmemory`	CAD design 跨 session 連續性靠 agentmemory 記
`dari-docs`	10 個 benchmark md 可以餵給 dari-docs 跑：「給定 brief，agent 能不能成功產出 STEP？」
`paper-qa-lite`	對 references/ 跑 RAG 問答（CAD frame semantics / URDF design ledger 等）
`meeting-intel`	若團隊評估「引入 AI agent 設計流程」，meeting-intel 對 CAD Skills repo 做 thematic 拆解
`patent-creator`	可能適用！若公司未來要做專利申請涉及 CAD 設計流程，CAD Skills 的「source-first / regenerate target」設計可能是 patent claim 元素 — 但須走機密邊界

10. 重點摘要 Checklist

3.7k stars / 428 forks / MIT / 1 個月生命週期（2026-04-22）
7 個 skill：cad / render / urdf / srdf / sdf / step-parts / sendcutsend
共用 harness/AGENTS.md + CLAUDE.md
10 個 benchmark md + GIF（rectangular / flange / L-bracket / shaft / enclosure / clevis / engine / impeller / staircase / planetary gear）
CAD 輸出格式：STEP / STP / STL / 3MF / DXF / GLB
Robotics 輸出格式：URDF / SRDF / SDF
WASM-based CAD Explorer viewer（本機跑，無 backend）
step.parts 整合 + SendCutSend 整合
@cad[...] 穩定 feature 參考系統
source-first / regenerate explicit target 設計品味
Python: build123d + ezdxf + numpy + trimesh + vtk
一鍵裝：npx skills add earthtojake/text-to-cad
資安綜合燈號：🟢 / 🟡（無紅燈）

11. 進一步閱讀

官方 docs：https://www.cadskills.xyz
Live demo：https://demo.cadskills.xyz
作者 X：https://x.com/earthtojake
step.parts catalog：https://step.parts
build123d 上游：https://github.com/gumyr/build123d
OCP（OpenCascade Python）上游：本 repo skills/cad/requirements.txt
對應姊妹專案 ConardLi/garden-skills：inbox/2026-05-21-github-ConardLi-garden-skills.md
本知識庫先前 tutorial：inbox/2026-05-21-tutorial-agentmemory.md

text-to-cad / CAD Skills 詳細教學 — 自然語言 → build123d → STEP / URDF / SDF 的 agent skill 集

Contents

text-to-cad 詳細教學

1. 專案定位

1.1 它是什麼

1.2 它解決什麼問題

1.3 與其他 text-to-CAD 工具的差異

1.4 適合誰用

2. 安裝指南

2.1 一鍵裝 skills（推薦）

2.2 Python 環境（必裝 — 給 build123d）

2.3 CAD Explorer viewer（render skill 自動處理）

2.4 harness（給整個 CAD 專案的 instruction）

3. 核心架構解析

3.1 7 個 skill 的職責分工

3.2 「source-first / regenerate explicit target」工作流

3.3 @cad[...] 參考系統

3.4 4 個 robotics output 的關係

3.5 CAD Explorer viewer 技術棧

4. Helper Scripts 詳細用法

4.1 skills/cad/scripts/

4.2 skills/render/scripts/viewer/ (CAD Explorer)

4.3 skills/render/scripts/moveit2_server/

4.4 skills/urdf/scripts/urdf

4.5 harness/AGENTS.md 規範

4.6 10 個 benchmark

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

8.1 寫好「自然語言 → build123d」prompt

8.2 用 @cad[...] 做精準 follow-up

8.3 機器人原型完整流程

8.4 整合進 CI（regenerate target 一致性）

8.5 把生成的 STEP 自動同步到 step.parts（如果你也有 catalog）

8.6 fork 自家工廠的 sendcutsend 變體

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Comments

text-to-cad / CAD Skills 詳細教學 — 自然語言 → build123d → STEP / URDF / SDF 的 agent skill 集

Contents

text-to-cad 詳細教學

1. 專案定位

1.1 它是什麼

1.2 它解決什麼問題

1.3 與其他 text-to-CAD 工具的差異

1.4 適合誰用

2. 安裝指南

2.1 一鍵裝 skills（推薦）

2.2 Python 環境（必裝 — 給 build123d）

2.3 CAD Explorer viewer（render skill 自動處理）

2.4 harness（給整個 CAD 專案的 instruction）

3. 核心架構解析

3.1 7 個 skill 的職責分工

3.2 「source-first / regenerate explicit target」工作流

3.3 @cad[...] 參考系統

3.4 4 個 robotics output 的關係

3.5 CAD Explorer viewer 技術棧

4. Helper Scripts 詳細用法

4.1 skills/cad/scripts/

4.2 skills/render/scripts/viewer/ (CAD Explorer)

4.3 skills/render/scripts/moveit2_server/

4.4 skills/urdf/scripts/urdf

4.5 harness/AGENTS.md 規範

4.6 10 個 benchmark

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

8.1 寫好「自然語言 → build123d」prompt

8.2 用 @cad[...] 做精準 follow-up

8.3 機器人原型完整流程

8.4 整合進 CI（regenerate target 一致性）

8.5 把生成的 STEP 自動同步到 step.parts（如果你也有 catalog）

8.6 fork 自家工廠的 sendcutsend 變體

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments