> 以 CADDesigner（Zhejiang University, *Computer-Aided Design* 198, 2026）及其配套开源实现为研究对象，剖析一个“从自然语言/草图到可执行 CAD 脚本”的 LLM Agent 是如何把**人类设计意图**转化为**参数化三维模型**的。

---

## 0. 腾讯云架构师技术同盟 2026.07.13 的【科技热点】 

浙江大学杜鹏团队研发的CADDesigner智能体通过多模态输入（文本+草图）和显式上下文命令式范式（ECIP），实现了自然语言到精准CAD建模代码的转化。

其创新性体现在：
1）API设计强调语法、参数与行为一致性，使大模型能举一反三生成可靠代码；
2）约束系统采用声明式规则，模型仅需描述设计意图而非计算几何细节；
3）通过功能标签机制解决对象选择难题，关键零件可被精准追踪；
4）提供含错误定位与修复建议的反馈系统，支持模型迭代优化。

该成果发表于《Computer-Aided Design》，其技术路径为意图驱动的人机协同设计提供了新范式。

开源地址：https://github.com/NiJingzhe/SimpleCADAPI

---

## 1. 背景与问题

传统 CAD 建模需要设计师熟练掌握 SolidWorks、CATIA、OnShape 等软件的复杂操作。概念设计阶段往往只有一段模糊描述或一张草图，把它变成可编辑参数化模型门槛很高。

CADDesigner 提出用 **ReAct 风格的 LLM Agent** 来弥合这道鸿沟：

- 输入：文本描述 +（可选）草图/参考图
- 输出：可执行的 Python 脚本 `model.py`，运行后导出 `.step`/`.stl`
- 核心挑战：大模型容易在 API 名称、参数类型、返回类型、几何选择上产生幻觉

为降低幻觉，作者提出 **ECIP（Explicit Context Imperative Paradigm）** / 项目实现中称 **SimpleCADAPI**，并围绕它构建了一套“知识约束的代码生成”体系。

---

## 2. 整体数据流：从意图到模型

```mermaid
flowchart LR
 A[用户输入 文本 / 草图 / 参考图] --> B[需求细化 Specialist make_user_query_more_detailed]
 B --> C[结构化需求规格 req_xxxx 存于 SketchPad]
 C --> D[代码生成 Specialist cad_code_generator]
 D --> E[model.py]
 E --> F[执行 Command uv run python model.py]
 F --> G[导出 .step / .stl]
 G --> H[视觉反馈 get_visual_feedback]
 H -->|PASS| I[任务完成]
 H -->|FAIL / 建议| D
```

**关键观察**：这不是一条写死的流水线，而是一个**由主 Agent 动态编排的闭环**。每个 Specialist 都是独立的 LLM 子代理，拥有自己的工具箱（读文件、写文件、执行命令、操作 SketchPad）。

---

## 3. API 文档的生成：把源码变成 LLM 可读的参考

CADDesigner 并没有让大模型直接读 Python 源码包，而是先把源码抽成结构化的 Markdown 文档。

### 3.1 文档生成流程

```mermaid
flowchart TB
 subgraph Source["SimpleCADAPI 源码"]
 S1[operations.py]
 S2[field.py]
 S3[constraints.py]
 S4[evolve.py]
 S5[ql.py]
 end

 subgraph Pipeline["自动化文档流水线"]
 P1[解析函数签名 类型注解 / 参数 / 返回值]
 P2[提取 docstring]
 P3[按统一模板生成 Markdown]
 P4[按二级标题 ## 做语义分块]
 P5[附加锚点关键词 便于向量检索]
 end

 subgraph Docs["references/docs/api/"]
 D1[README.md API 索引]
 D2[make_box_rsolid.md]
 D3[union_rsolidlist.md]
 D4[... 每个 API 一页]
 end

 S1 & S2 & S3 & S4 & S5 --> P1
 P1 --> P2 --> P3 --> P4 --> P5
 P5 --> D1 & D2 & D3 & D4
```

### 3.2 每页 API 文档的统一模板

以 `union_rsolidlist.md` 为例：

| 区块 | 作用 |
|------|------|
| API Definition | 显式签名：`def union_rsolidlist(*solids, clean=True, glue=True, tol=None) -> List[Solid]` |
| Description | 做什么、行为边界、注意事项 |
| Parameters | 每个参数的语义与类型 |
| Returns | 返回类型，强调“永远是 `List[Solid]`” |
| Raises | 可能抛出的异常 |
| Examples | 可直接复制的代码片段 |

**为什么用 Markdown 而不是直接读源码？**

1. **结构化**：源码中的类型提示和 docstring 是分散的，统一模板让 LLM 一次看到完整语义。
2. **可检索**：按二级标题分块后，适合做 RAG/向量检索；论文中使用的是“语义友好分块 + 锚点关键词”。
3. **可验证**：`scripts/validate_skill.sh` 会检查必需文件是否存在，确保知识库完整。

---

## 4. API 文档的读取：Prompt 驱动的按需检索

这是整个系统最精妙的地方：**系统不会自动把所有 API 文档塞进 LLM 上下文，而是在 prompt 中强制要求子代理自己用文件工具去读。**

### 4.1 子代理读文档的数据流

```mermaid
sequenceDiagram
 autonumber
 participant User as 用户
 participant Agent as CADAgent
 participant ReqSpec as 需求细化 Specialist
 participant CodeGen as 代码生成 Specialist
 participant FT as 文件工具集 read_file / grep
 participant Docs as references/docs/api/

 User->>Agent: "设计一个带 4 个螺栓孔的法兰盘"
 Agent->>ReqSpec: 调用 make_user_query_more_detailed
 ReqSpec->>FT: read_file(SKILL.md)
 FT-->>ReqSpec: 技能元数据 + MUST 规则
 ReqSpec->>FT: read_file(references/docs/api/README.md)
 FT-->>ReqSpec: API 索引：Creation / Boolean / Pattern / Assembly ...
 ReqSpec->>FT: read_file(make_cylinder_rsolid.md) read_file(make_n_hole_flange_rsolid.md) read_file(union_rsolidlist.md) ...
 FT-->>ReqSpec: 具体 API 详情
 ReqSpec-->>Agent: 结构化需求规格 req_xxxx

 Agent->>CodeGen: 调用 cad_code_generator(req_xxxx)
 CodeGen->>FT: read_file(SKILL.md)
 CodeGen->>FT: read_file(references/docs/api/README.md)
 CodeGen->>FT: 按需读取本次用到的 API 页
 FT-->>CodeGen: API 详情
 CodeGen->>FT: echo_into(model.py)
 CodeGen->>FT: execute_command(uv run python model.py)
 FT-->>CodeGen: 执行结果 / 报错
 CodeGen-->>Agent: model.py + 执行报告
```

### 4.2 强制读文档的 Prompt 工程

在 `tools/common.py` 中，系统会生成一段 `[Workspace Facts]`：

```text
[Workspace Facts]
Current working directory: ...
Repository root: ...
Preferred skill root: ./workspace/skills/simplecad-self-evolve
You MUST read these files before choosing APIs:
- ./workspace/skills/simplecad-self-evolve/SKILL.md
- ./workspace/skills/simplecad-self-evolve/references/docs/api/README.md
```

这段文本被注入到两个 Specialist 的 prompt 中：

- `tools/requirements_tools.py`：
 > “Before you write the final answer, you MUST use file tools to read the preferred skill root's `SKILL.md`, then `references/docs/api/README.md`, then the exact API Markdown pages you cite.”

- `tools/code_tools.py`：
 > “Read the chosen skill root's `SKILL.md`, then `references/docs/api/README.md`, then the exact API Markdown pages you use.”

**效果**：模型不会“凭记忆”乱写 API，而是像人类开发者一样先查文档再写代码。

---

## 5. Python 代码的生成：ECIP 范式

ECIP 的核心思想是：**显式传递上下文，而不是隐式链式调用。**

### 5.1 CadQuery（隐式上下文） vs ECIP（显式上下文）

```mermaid
flowchart TB
 subgraph CQ["CadQuery Fluent API"]
 C1[wp = cq.Workplane]
 C2[wp.box(10,10,10)]
 C3[wp.cylinder(5,20)]
 C4[wp.union()]
 C1 --> C2 --> C3 --> C4
 end

 subgraph ECIP["ECIP / SimpleCADAPI"]
 E1[box = make_box_rsolid(10,10,10)]
 E2[cyl = make_cylinder_rsolid(5,20)]
 E3[result = union_rsolidlist(box, cyl)]
 E1 --> E3
 E2 --> E3
 end
```

| 特性 | CadQuery Fluent API | ECIP |
|------|---------------------|------|
| 上下文传递 | 隐式，通过 workplane 内部状态 | 显式，每个变量都是独立对象 |
| 插入 Python 控制流 | 困难（破坏链式调用） | 自然（if/for/列表推导） |
| LLM 可理解性 | 低，需要追踪隐式状态 | 高，每步输入输出清晰 |
| 调试 | 链中某步出错难以定位 | 每步变量可打印、可检查 |

### 5.2 命名规范即类型系统

ECIP 强制函数命名：`_<操作>_r<返回类型>`

```textnmake_box_rsolid → 创建盒子，返回 Solid
make_circle_rwire → 创建圆，返回 Wire
union_rsolidlist → 布尔并，返回 List[Solid]
translate_shape → 变换形状，返回 Shape
```

这对 LLM 极其友好：即使不看文档，函数名本身就告诉模型“输入什么、返回什么”，从而大幅降低返回类型误用。

### 5.3 代码生成 Specialist 的工作流程

```mermaid
flowchart LR
 A[接收任务 prompt 含 req_xxxx + target_file_path] --> B[读取 SKILL.md + API 索引]
 B --> C[读取具体 API 页]
 C --> D[用 echo_into 写入 model.py]
 D --> E[执行 uv run python model.py]
 E -->|成功导出 .step/.stl| F[返回结果]
 E -->|报错| G[读取错误信息]
 G --> H[定位失败 API]
 H --> C
```

---

## 6. Python 代码的执行与反馈闭环

生成代码只是第一步，系统会反复执行、检查、修正，直到成功。

### 6.1 执行与验证流程

```mermaid
flowchart TB
 A[model.py] --> B[execute_command uv run python model.py]
 B --> C{执行结果}
 C -->|成功| D[检查 .stl 与 .step/.stp 是否存在]
 C -->|失败| E[捕获 traceback]
 E --> F[结构化错误三元组 cause / location / fix]
 F --> G[代码生成 Specialist 修复]
 G --> A
 D -->|文件存在| H[视觉反馈 渲染 6 视图]
 D -->|文件缺失| I[重新生成/调试]
 H --> J{视觉检查}
 J -->|PASS| K[任务完成]
 J -->|FAIL| L[生成视觉问题 + 修改建议]
 L --> G
```

### 6.2 结构化错误信息

ECIP 把底层 CadQuery 的模糊报错，包装成 LLM 容易利用的三元组：

```textnerror = (cause, location, fix)
```

| 字段 | 含义 | 示例 |
|------|------|------|
| `cause` | 根因 | `union_rsolidlist received a Face instead of Solid` |
| `location` | 出错位置 | `model.py:42` |
| `fix` | 修复建议 | `use make_face_from_wire_rface to close the wire first` |

论文消融实验（Table 2）显示：去掉该错误系统后，虽然首次通过率只从 0.45 降到 0.41，但平均重试次数从 1.86 涨到 2.62，最终成功率从 100% 降到 81.5%。这说明**结构化反馈主要价值不是“一次做对”，而是“快速收敛”**。

### 6.3 视觉反馈

视觉反馈工具 `get_visual_feedback` 内部有两步：

1. **渲染 6 视图**：Front-Top-Left、Back-Bottom-Right、Back-Top-Left、Front-Bottom-Right、Top、Right
2. **视觉问答**：先生成针对性问题，再用多模态模型回答，输出 PASS/FAIL + 修改建议

```mermaid
flowchart LR
 A[.step / .stl 模型] --> B[渲染 6 视图]
 B --> C[生成视觉问题 vq]
 C --> D[多模态模型回答 vf]
 D --> E{终止信号 tau}
 E -->|tau=1| F[交付用户]
 E -->|tau=0| G[返回修改建议]
```

---

## 7. 四大创新点解析

下面把论文 claimed 的创新性与代码实现一一对应。

### 7.1 API 设计强调语法、参数与行为一致性

**实现方式：**

- 统一命名规范：`_<操作>_r<返回类型>`
- 统一参数顺序：几何对象在前，数值参数在后
- 统一返回类型：布尔运算永远返回 `List[Solid]`，必须检查 `len(result)`
- 统一文档模板：每个 API 一页 Markdown，结构完全一致

**为什么能让大模型举一反三？**

大模型具有强模式识别能力。当所有 API 遵循同一套“语法-参数-返回”模式时，模型可以把从一个 API 学到的规律迁移到另一个 API。例如：

> 学过 `make_cylinder_rsolid(radius, height)` 和 `make_cone_rsolid(radius, height)`，模型自然能猜出 `make_box_rsolid(width, height, depth)` 的参数语义。

代码中的 `SKILL.md` 第 9 条规则进一步强化：

> “Boolean operations always return `List[Solid]`. You MUST check `len(results)` before using `results[0]`.”

### 7.2 约束系统采用声明式规则

**实现方式：**

SimpleCADAPI 提供一组 `constrain_*` 函数，用于装配体约束：

- `constrain_coincident_rassembly`
- `constrain_concentric_rassembly`
- `constrain_distance_rassembly`
- `constrain_offset_rassembly`

模型只需描述“这两个面重合”“这两个孔同轴”，底层的几何求解由 `solve_assembly_rresult` 自动完成。

```mermaid
flowchart LR
 A[设计意图 "法兰盘底面与底板顶面贴合"] --> B[constrain_coincident(face_a, face_b)]
 B --> C[solve_assembly_rresult(assembly)]
 C --> D[自动计算变换矩阵]
```

**意义**：设计师不需要手动计算平移、旋转、对齐的具体数值，只需要声明关系。这与传统 CAD 的“先画草图再标注约束”理念一致，但用代码表达得更直接。

### 7.3 功能标签机制解决对象选择难题

**实现方式：**

每个几何对象都继承 `TaggedMixin`，可以附加标签和元数据：

```python
box = make_box_rsolid(10, 10, 10)
box.add_tag("base_frame")
box.set_metadata("material", "aluminum")
```

更重要的是，SimpleCADAPI 会自动给拓扑元素打语义标签：

- `make_box_rsolid` 会自动给面打上 `top`、`bottom`、`left`、`right`、`side`
- 布尔运算后会通过 `TopoDelta` 追踪新生成的面，打上 `origin.tool`、`track.event: generated`

然后使用 **QL（Query Language）** 做声明式选择：

```python
top_hole_edge = (
 ql.edges()
 .where(ql.curve_type("circle"))
 .order_by(ql.center_axis("z"), desc=True)
 .take(1)
 .exactly(1)
)

result = chamfer_rsolid(model, top_hole_edge, distance=0.5)
```

```mermaid
flowchart TB
 A[几何对象] --> B[自动/手动打标签]
 B --> C[QL 查询语言]
 C --> D[按 tag / metadata / 几何属性筛选]
 D --> E[返回选中边/面/体]
 E --> F[传入后续操作]
```

**意义**：传统 CAD 编程中，“选第几个面”非常容易因拓扑变化而失效。标签机制把选择从“索引位置”提升到“语义角色”，让代码更鲁棒，也让 LLM 更容易表达“我要对顶面的圆孔倒角”。

### 7.4 含错误定位与修复建议的反馈系统

**实现方式：**

整个系统有三层反馈：

| 反馈层级 | 触发条件 | 修复动作 |
|----------|----------|----------|
| 执行错误反馈 | Python 脚本抛异常 | 结构化错误三元组 → 代码生成 Specialist 修复 |
| 视觉反馈 | 脚本成功但模型不匹配 | 多模态模型生成修改建议 → 代码生成 Specialist 修复 |
| 用户反馈 | 用户确认/拒绝 | 满意则加入案例库，不满意则继续迭代 |

```mermaid
flowchart TB
 subgraph Layer1["Layer 1: 执行反馈"]
 L1A[model.py 运行报错] --> L1B[结构化错误信息] --> L1C[自动修复代码]
 end

 subgraph Layer2["Layer 2: 视觉反馈"]
 L2A[模型已导出] --> L2B[6 视图渲染] --> L2C[视觉问答] --> L2D[PASS/FAIL + 建议]
 end

 subgraph Layer3["Layer 3: 用户反馈"]
 L3A[用户满意?] -->|是| L3B[加入 evolve cases 知识库]
 L3A -->|否| L3C[继续迭代]
 end

 L1C --> L2A
 L2D -->|FAIL| L1C
 L2D -->|PASS| L3A
```

**意义**：LLM 生成代码不可能一次全对。系统把“试错”过程自动化，让 Agent 能像人类开发者一样：运行 → 看报错 → 查文档 → 改代码 → 再运行。论文 Table 2 证明，这套反馈机制让最终成功率达到 100%（在允许重试的情况下）。

---

## 8. 知识库与自我进化

CADDesigner 把成功的建模案例保存到 `cases/simplecad_self_evolve_cases/`，形成可复用的复合操作。

```mermaid
flowchart LR
 A[成功建模任务] --> B[用户确认]
 B --> C[scripts/add_new_case.sh]
 C --> D[cases/.../evolve.py]
 D --> E[后续任务可直接导入]
 E --> F[from simplecad_self_evolve_cases.evolve import my_case]
```

目前代码仓库中 `evolve.py` 是空的（`__all__ = []`），说明这套自我进化机制是为实际部署后的持续学习预留的。

---

## 9. 总结

CADDesigner 的核心不是“让 LLM 直接写 CadQuery 代码”，而是构建了一个**围绕 LLM 认知特点重新设计的 CAD 编程接口 + 知识约束 + 反馈闭环**的完整系统。

| 环节 | 关键设计 | 解决的问题 |
|------|----------|------------|
| API 文档 | 从源码自动抽取结构化 Markdown | 模型不会凭空编造 API |
| 文档读取 | Prompt 强制按需读 `SKILL.md` + `api/README.md` + 具体 API 页 | 控制上下文、保证接地 |
| 代码范式 | ECIP 显式上下文 + 命名即类型 | 降低状态追踪难度、减少返回类型错误 |
| 对象选择 | 标签 + QL 查询语言 | 避免脆弱索引、实现语义级选择 |
| 约束系统 | 声明式 `constrain_*` + 自动求解 | 设计师只需描述意图 |
| 错误反馈 | 结构化错误三元组 | 快速定位与自动修复 |
| 视觉反馈 | 6 视图 + 视觉问答 | 检查几何是否符合设计意图 |
| 自我进化 | 成功案例入库 | 持续积累领域知识 |

最终，这套机制让 CADDesigner 在 DeepCAD 200 模型测试集上，相比去掉 API 知识库的基线，能够稳定生成有效模型；在文本+图像输入模式下取得了最佳的 IoU、Chamfer Distance 和 Hausdorff Distance。

---

## 参考路径

- **开源仓库（SimpleCADAPI / CADDesigner 配套实现）**：https://github.com/NiJingzhe/SimpleCADAPI
- **论文**：Fan et al. *CADDesigner: Conceptual CAD model generation with a general-purpose agent*. Computer-Aided Design, 198, 2026. [PDF 链接](https://562590763.github.io/CADDesigner/files/CADDesigner.pdf)
- **Skill 元数据**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/workspace/skills/simplecad-self-evolve/SKILL.md
- **API 索引**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/workspace/skills/simplecad-self-evolve/references/docs/api/README.md
- **核心工具 `tools/common.py`**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/tools/common.py
- **需求细化 `tools/requirements_tools.py`**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/tools/requirements_tools.py
- **代码生成 `tools/code_tools.py`**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/tools/code_tools.py
- **主 Agent `agent/CADAgent.py`**：https://github.com/NiJingzhe/SimpleCADAPI/blob/main/agent/CADAgent.py

以 CADDesigner（Zhejiang University, Computer-Aided Design 198, 2026）及其配套开源实现为研究对象，剖析一个“从自然语言/草图到可执行 CAD 脚本”的 LLM Agent 是如何把人类设计意图转化为参数化三维模型的。

论文研究：意图驱动的 CAD Agent 实现

发表于《Computer-Aided Design》的一篇论文解读，其技术路径为意图驱动的人机协同设计提供了新范式。

人工智能

开发工具

架构设计

浙江大学杜鹏团队研发的CADDesigner智能体通过多模态输入（文本+草图）和ECIP范式，实现自然语言到精准CAD建模代码的转化。创新点包括：API设计确保语法一致性、声明式约束系统、功能标签机制和智能反馈系统，显著提升LLM生成CAD代码的准确率。开源地址：https://github.com/NiJingzhe/SimpleCADAPI

代码解释

云架构

数据流

智能体

Python

Agent

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

浙江大学杜鹏团队研发的CADDesigner智能体通过多模态输入（文本+草图）和ECIP范式，实现自然语言到精准CAD建模代码的转化。创新点包括：API设计确保语法一致性、声明式约束系统、功能标签机制和智能反馈系统，显著提升LLM生成CAD代码的准确率。开源地址：https://github.com/NiJingzhe...

论文研究：意图驱动的 CAD Agent 实现-腾讯云开发者社区-腾讯云

论文研究：意图驱动的 CAD Agent 实现

论文研究：意图驱动的 CAD Agent 实现

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐