# CadSet

CadSet 是一个面向机械零件的 STEP-first 参数化 CAD 系统。它覆盖自然语言与图文生成、上传 STEP 的独立参数化重建、模型修改、几何验收，以及从批量 STEP 案例中蒸馏可复用建模经验。

系统的统一设计源是自有的 **DesignIR 3.0**。文字/图片生成使用语义参数化层，上传 STEP 使用 SurfaceIR 层；STEP 是主要交换与验收格式，但上传的源 STEP 只作为教师证据和验收真值，不作为重建时的几何依赖。

## 产品范围

当前主线只包含三类工作流：

1. 根据自然语言生成可编辑 CAD。
2. 根据文字和参考图片生成或修改可编辑 CAD。
3. 将上传的 STEP 重建为 DesignIR，独立生成新的 STEP，并继续参数化修改。

CAD Router 不再设置永久默认后端，而是根据已有源、标准件覆盖、语义
重放需求、几何词汇、装配关系和验收要求在两个平权建模后端之间选择：

- **Build123d**：定制机械零件、复杂轮廓与曲面、源级装配和 STEP 输出。
- **SimpleCADAPI 2.0.2**：标准机械工厂、ModelResult 可重放图、语义拓扑、
  单位/公差、场景包、CAD 翻译和严格 B-Rep 对比。

`text-to-cad` 是 DesignIR、路由、修复、验收和交付编排层，不再因为它
承载 Build123d Skill 而给 Build123d 额外默认分。上传 STEP 由 SurfaceIR
独立重建，不伪装成任一文字生成后端。

## 系统架构

```text
                         ┌────────────────────┐
 Text / Image / STEP ──> │  CAD Agent Studio  │
                         └─────────┬──────────┘
                                   │
                         ┌─────────▼──────────┐
                         │ CAD Router/DesignIR │
                         └──────┬───────┬─────┘
                                │       │
                    ┌───────────▼─┐   ┌─▼────────────────┐
                    │  Build123d  │   │ SimpleCADAPI 2.0.2│
                    └───────────┬─┘   └─┬────────────────┘
                                └────┬────┘
                                     │
                           DesignIR 3.0 + STEP
                                     │
                         ┌───────────▼───────────┐
                         │ Viewer / Acceptance   │
                         └───────────────────────┘
```

上传 STEP 的重建链路使用严格的教师隔离：

```text
Teacher STEP
  -> private geometry evidence
  -> Reconstruction Agent
  -> DesignIR 3.0 / SurfaceIR
  -> isolated compiler without Teacher STEP access
  -> rebuilt STEP
  -> independent Acceptance Agent
  -> SimpleCADAPI strict B-Rep comparison
  -> deterministic experience promotion
```

## 仓库结构

| 路径 | 职责 |
| --- | --- |
| [`cad-agent-studio/`](cad-agent-studio/README.md) | 独立 Next.js 前端，负责对话、图片与 STEP 上传、任务管理和模型预览。 |
| [`designir-pipeline/`](designir-pipeline/README.md) | DesignIR Schema、双 Agent、隔离编译、验收和经验晋升。 |
| [`text-to-cad/`](text-to-cad/README.md) | CAD Router、Build123d CAD Skill、CAD Viewer 和共享 CAD 运行时。 |
| [`SimpleCADAPI/`](SimpleCADAPI/README.md) | `2.0.2` 平权建模与验收后端，提供标准件、可重放图、语义拓扑、单位/公差、场景和 B-Rep 工具。 |
| [`llm.config.yaml`](llm.config.yaml) | 前端共享的模型供应商、模型和密钥配置。 |

依赖目录、虚拟环境、构建缓存和批量运行数据不会进入 Git。锁文件、源码、Schema、Agent 定义和确定性测试会进入版本控制。

## DesignIR 3.0

DesignIR 3.0 使用统一外壳和三种明确模式：

- `fully_semantic_parametric`：文字/图片生成的设计意图与特征程序。
- `surface_parametric`：上传 STEP 推断出的独立 SurfaceIR 重建程序。
- `hybrid_semantic_surface_parametric`：语义程序加生成 STEP 的 SurfaceIR 快照，语义层仍是修改权威。

语义层保存设计意图，而不是复制教师 STEP 的 B-Rep 或三角网格。主要结构包括：

- coordinate systems 与 datums
- editable parameters 与 expressions
- sketches 与 constraints
- ordered features、patterns 与 attachments
- construction stages
- edit interface
- validation and perturbation contracts

Schema 位于：

[`designir-pipeline/contracts/designir-3.0.schema.json`](designir-pipeline/contracts/designir-3.0.schema.json)

当前两个后端共同支持的首批操作包括：

- `extrude_circle`
- `extrude_rectangle`
- `add_cylinder`
- `through_hole`
- `polar_hole_pattern`

不支持的几何必须显式进入 quarantine，并记录缺失能力；系统禁止使用源 STEP、嵌入 B-Rep、完整网格替身或源拓扑引用绕过重建。

## STEP 蒸馏与验收

将待处理的 STEP/STP 文件放入：

```text
designir-pipeline/input/
```

蒸馏目录只保留三层：

| 路径 | 用途 | Git |
| --- | --- | --- |
| `designir-pipeline/input/` | 原始教师 STEP/STP | 不提交 |
| `designir-pipeline/runs/` | 证据、DesignIR、重建件、验收、草稿和失败记录 | 不提交 |
| `designir-pipeline/output/library.json` | 通过确定性校验的经验库 | 提交 |

`runs/` 内部由程序按需创建 `evidence`、`designir`、`rebuilt`、
`acceptance`、`review` 和 `quarantine`。目录层级只负责整理文件；两个
Agent 的读写边界由程序和合同控制。

详细说明见 [`designir-pipeline/README.md`](designir-pipeline/README.md)。

批量提取教师证据：

```bash
designir-pipeline/scripts/cad-experience extract-folder
```

蒸馏得到的经验必须同时通过几何一致性、特征语义、参数可编辑性和修改稳定性验收。两个 Agent 都无权直接发布经验，最终晋升由确定性策略执行。

## 本地开发

### 环境要求

- Node.js 22+
- Python 3.12
- OpenCascade/Build123d 所需的本地运行依赖

### 启动前端

```bash
cd cad-agent-studio
npm install
npm run dev -- -H 127.0.0.1 -p 53821
```

打开 `http://127.0.0.1:53821`。

前端默认读取仓库根目录的 `llm.config.yaml`。也可以通过 `CAD_AGENT_STUDIO_CONFIG` 指向其他配置文件。

### DesignIR 命令

```bash
text-to-cad/.venv/bin/python \
  designir-pipeline/scripts/designir_pipeline.py validate \
  designir-pipeline/examples/raised_hub_flange.designir.json

text-to-cad/.venv/bin/python \
  designir-pipeline/scripts/designir_pipeline.py isolated-rebuild \
  designir-pipeline/examples/raised_hub_flange.designir.json \
  --output /tmp/raised_hub_flange.step \
  --backend build123d
```

`simplecadapi` 后端还会在 STEP 旁生成可重放的 `*.simplecad.model.json`。

## 验证

前端：

```bash
cd cad-agent-studio
npm test
npm run build
```

DesignIR、经验库与 CAD Router：

```bash
text-to-cad/.venv/bin/python -m unittest \
  designir-pipeline/tests/test_designir_pipeline.py \
  designir-pipeline/tests/test_experience_library.py \
  text-to-cad/tests/python/skills/cad-router/test_route.py
```

经验库审计：

```bash
text-to-cad/.venv/bin/python \
  designir-pipeline/skills/cad-experience-builder/scripts/cad_experience.py \
  audit designir-pipeline/output/library.json
```

## 当前边界

DesignIR 当前优先覆盖规则机械零件，例如法兰、板件、支架、轴套、带孔块和基础壳体。自由曲面、多轨扫掠、复杂铸造过渡和高阶连续曲面仍需要扩展特征词汇。

工作区已经具备批量证据提取、角色隔离、独立重建、验收和经验晋升能力；批处理目前由命令或 Agent 任务触发，尚未提供常驻目录监听服务。