介绍
# CAD Agent
> 为您的 AI 智能体赋予 CAD 工作的视觉能力。
## 描述
CAD Agent 是一个渲染服务器，让 AI 智能体能够看到它们正在构建的内容。发送建模命令 → 接收渲染图像 → 视觉迭代。
**适用于：** 设计 3D 打印零件、参数化 CAD、机械设计、build123d 建模
## 架构
**关键：** 所有 CAD 逻辑都在容器内运行。您（作为智能体）只需： 1. 通过 HTTP 发送命令 2. 查看返回的图像 3. 决定下一步做什么
``` YOU (agent) CAD AGENT CONTAINER ───────────── ─────────────────── Send build123d code → Executes modeling ← Returns JSON status Request render → VTK renders the model ← Returns PNG image *Look at the image* Decide: iterate or done ```
**切勿**在容器外进行 STL 操作、网格处理或渲染。容器处理一切——您只需指挥和观察。
## 安装设置
### 1. 克隆仓库
```bash git clone https://github.com/clawd-maf/cad-agent.git cd cad-agent ```
### 2. 构建 Docker 镜像
```bash docker build -t cad-agent:latest . ```
或者使用 docker-compose：
```bash docker-compose build ```
### 3. 运行服务器
```bash # Using docker-compose (recommended) docker-compose up -d
# Or using docker directly docker run -d --name cad-agent -p 8123:8123 cad-agent:latest serve ```
### 4. 验证安装
```bash curl http://localhost:8123/health # Should return: {"status": "healthy", ...} ```
> **Docker-in-Docker 注意事项：** 在嵌套容器环境（例如 Clawdbot 沙箱）中，主机网络可能无法工作——即使服务器绑定到 `0.0.0.0:8123`，`curl localhost:8123` 也会失败。请改用 `docker exec cad-agent python3 -c "..."` 命令。在正常的 Docker 主机上，localhost 访问可以正常工作。
## 工作流
### 1. 创建模型
```bash curl -X POST http://localhost:8123/model/create \ -H "Content-Type: application/json" \ -d '{ "name": "my_part", "code": "from build123d import *\nresult = Box(60, 40, 30)" }' ```
### 2. 渲染与查看
```bash # Get multi-view (front/right/top/iso) curl -X POST http://localhost:8123/render/multiview \ -d '{"model_name": "my_part"}' -o views.png
# Or 3D isometric curl -X POST http://localhost:8123/render/3d \ -d '{"model_name": "my_part", "view": "isometric"}' -o iso.png ```
**查看图像。** 看起来正确吗？如果不正确，请修改并重新渲染。
### 3. 迭代
```bash curl -X POST http://localhost:8123/model/modify \ -d '{ "name": "my_part", "code": "result = result - Cylinder(5, 50).locate(Pos(20, 10, 0))" }'
# Re-render to check curl -X POST http://localhost:8123/render/3d \ -d '{"model_name": "my_part"}' -o updated.png ```
### 4. 导出
```bash curl -X POST http://localhost:8123/export \ -d '{"model_name": "my_part", "format": "stl"}' -o part.stl ```
## 端点 (Endpoints)
| 端点 | 功能 | |----------|--------------| | `POST /model/create` | 运行 build123d 代码，创建模型 | | `POST /model/modify` | 修改现有模型 | | `GET /model/list` | 列出会话中的模型 | | `GET /model/{name}/measure` | 获取尺寸 | | `POST /render/3d` | 3D 着色渲染 (VTK) | | `POST /render/2d` | 2D 技术图纸 | | `POST /render/multiview` | 四视图合成 | | `POST /export` | 导出 STL/STEP/3MF | | `POST /analyze/printability` | 检查是否可打印 |
## build123d 速查表
```python from build123d import *
# Primitives Box(width, depth, height) Cylinder(radius, height) Sphere(radius)
# Boolean a + b # union a - b # subtract a & b # intersect
# Position part.locate(Pos(x, y, z)) part.rotate(Axis.Z, 45)
# Edges fillet(part.edges(), radius) chamfer(part.edges(), length) ```
## 重要事项
- **不要绕过容器。** 不要使用 matplotlib、外部 STL 库或网格破解。 - **渲染是您的眼睛。** 修改后始终请求渲染。 - **视觉迭代。** 整个重点在于您可以看到正在构建的内容。
## 设计文件安全性
该项目具有防止意外提交 CAD 输出的保障措施： - `.gitignore` 屏蔽 *.stl, *.step, *.3mf 等文件。 - Pre-commit 钩子拒绝设计文件。 - 用户的设计保持本地状态，永不纳入版本控制。
## 链接
- [仓库](https://github.com/clawd-maf/cad-agent) - [build123d 文档](https://build123d.readthedocs.io/) - [VTK](https://vtk.org/)