cadSet/docs/CADSET_PROJECT_GUIDE.zh-CN.md

# CadSet 项目完整指南

> 面向自然语言、图文和 STEP 输入的参数化 CAD 生成、重建、修改与经验蒸馏系统。

## 1. 项目信息

- 项目浏览地址：<https://gitea.robotquan.com/xuyongjie/cadSet/src/branch/codex/remove-cadam/>
- Git 仓库地址：<https://gitea.robotquan.com/xuyongjie/cadSet.git>
- 当前开发分支：`codex/remove-cadam`
- 主要输出格式：DesignIR 2.0 JSON、STEP
- 建模后端：Build123d、SimpleCADAPI

本文档面向三类读者：

1. 想直接启动前端并生成 CAD 的使用者。
2. 想批量蒸馏 STEP、进行参数化重建实验的研究人员。
3. 想扩展 DesignIR、CAD Router、建模后端或验收系统的开发者。

---

## 2. CadSet 解决什么问题

CadSet 的目标不是只生成一个“看起来像”的网格，也不是把上传的 STEP
直接包装后宣称完成重建。系统希望得到同时满足以下条件的 CAD 模型：

- 几何能够导出为标准 STEP。
- 模型有明确的参数、基准、约束和特征顺序。
- 后续可以修改孔径、厚度、孔距、数量等参数。
- 修改后仍能稳定重建，而不是破坏模型。
- 上传 STEP 的重建过程不依赖原 STEP 本体。
- 从大量案例中学到的是通用建模方法，而不是某个零件的尺寸答案。

当前产品主线包含三种工作流：

1. **自然语言生成**：根据文字描述生成可编辑的参数化零件。
2. **图文生成与修改**：结合参考图片和文字生成或修改零件。
3. **上传 STEP 重建与修改**：把 STEP 作为教师真值，转换成自有
   DesignIR，再独立重建和参数化修改。

CadSet 当前优先面向规则机械零件，例如：

- 法兰、端盖、轴和轴套；
- 板件、支架、加强筋结构；
- 带孔块、孔阵列、槽和凸台；
- 基础壳体、连接件；
- 齿轮、齿条、轴承和部分减速器结构。

复杂自由曲面、多轨扫掠、高阶连续过渡面、缺陷 B-Rep 和大型装配仍属于
需要继续扩展的能力边界。

---

## 3. 核心设计思想

### 3.1 STEP 是几何真值，不是可编辑设计历史

STEP 通常能够保存精确 B-Rep 几何、拓扑和装配信息，但并不可靠地保存原
CAD 软件中的草图、特征树、尺寸名称和设计意图。

因此，从 STEP 中无法唯一恢复原作者的真实建模历史。例如同一个法兰既可
以通过“圆柱拉伸后打孔”得到，也可以通过“截面旋转后阵列切除”得到。

CadSet 不声称恢复唯一的原始历史。它做的是：

1. 从 STEP 提取确定性的几何证据。
2. 推断一个合理、稳定、可编辑的参数化设计方案。
3. 使用自有 DesignIR 表达这个方案。
4. 在没有源 STEP 的环境中重新生成 STEP。
5. 独立比较源 STEP 与重建 STEP。
6. 扰动参数，验证模型是否真正可修改。

### 3.2 DesignIR 2.0 是统一设计源

DesignIR 是 CadSet 自有的、后端无关的参数化设计描述。它保存设计逻辑，
而不是嵌入原始 B-Rep 或完整网格。

一个 DesignIR 通常包含：

| 字段 | 作用 |
| --- | --- |
| `coordinate_system` | 零件坐标系和轴方向。 |
| `datums` | 中心点、主轴、安装面等设计基准。 |
| `parameters` | 尺寸、角度、数量和比例参数。 |
| `expressions` | 参数之间的派生关系。 |
| `sketches` | 草图或轮廓语义。 |
| `constraints` | 同心、对称、等间距等约束。 |
| `features` | 拉伸、孔、凸台、阵列等有序特征。 |
| `patterns` | 极坐标或线性重复关系。 |
| `attachments` | 特征与主体、基准或安装面的连接关系。 |
| `construction_stages` | 推荐的构造阶段和重建顺序。 |
| `edit_interface` | 对外开放的可编辑参数与需保持的接口。 |
| `validation_contract` | 几何不变量和参数扰动测试。 |

完整 Schema：

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

可运行示例：

[`designir-pipeline/examples/raised_hub_flange.designir.json`](../designir-pipeline/examples/raised_hub_flange.designir.json)

### 3.3 源 STEP 必须与重建环境隔离

CadSet 明确禁止以下“伪重建”方式：

- 在生成器中调用 `import_step(source.step)`。
- 把原始 B-Rep、STEP 文本或完整三角网格塞进 JSON。
- 把源 STEP 当作基础特征，再在上面做布尔修改。
- 保存源模型的面 ID、边 ID 或运行时拓扑引用。
- 重建时从隐藏路径重新读取教师 STEP。

最直接的防作弊检查是：

> 从重建运行环境中移走源 STEP，仅依靠 DesignIR 和编译器，仍然能够生成
> 完整模型。

---

## 4. 系统架构

```mermaid
flowchart LR
    U["文字 / 图片 / STEP"] --> UI["CAD Agent Studio"]
    UI --> LLM["多模态或文本模型"]
    LLM --> IR["DesignIR 2.0"]
    IR --> R["CAD Router"]
    R --> B["Build123d"]
    R --> S["SimpleCADAPI"]
    B --> STEP["重建 STEP"]
    S --> STEP
    STEP --> V["3D Viewer"]
    STEP --> A["独立验收"]
    A --> F["验收报告与反馈"]
```

对于上传 STEP，链路进一步分成教师侧和重建侧：

```mermaid
flowchart TD
    T["源 STEP（教师真值）"] --> E["确定性几何证据提取"]
    E --> RA["Agent A：重建"]
    X["已晋升通用经验"] --> RA
    RA --> D["自有 DesignIR"]
    D --> C["隔离编译器"]
    C --> R["重建 STEP"]
    T --> AB["Agent B：独立验收"]
    D --> AB
    R --> AB
    AB --> P["确定性晋升器"]
    P --> X
```

关键点是：Agent A 和隔离编译器不能读取源 STEP；Agent B 可以读取源 STEP，
但不能直接发布经验。

---

## 5. 仓库结构

```text
CadSet/
├── cad-agent-studio/     Web 前端、对话、上传、任务和 3D 预览
├── designir-pipeline/    DesignIR、双 Agent、重建、验收和经验蒸馏
├── text-to-cad/          CAD Router、Build123d CAD 能力和 Viewer 运行时
├── SimpleCADAPI/         第二建模后端和可重放操作图
├── docs/                 项目级详细文档
├── llm.config.yaml       共享 LLM 配置
├── README.md             项目概览
├── .gitignore            本地数据、依赖和生成物排除规则
└── .gitattributes        文本换行和二进制格式属性
```

### 5.1 CAD Agent Studio

[`cad-agent-studio/`](../cad-agent-studio/)

这是面向最终使用者的 Next.js 前端：

- 左侧：对话、图片/STEP 上传、模型供应商和模型选择。
- 右侧：STEP 三维预览、选择、剖切、显示和编辑辅助工具。
- 服务端：读取模型配置、调用 LLM、生成 DesignIR、调用 CAD Router 和编译器。
- 任务数据：默认保存在 `cad-agent-studio/data/tasks/<taskId>/`。

### 5.2 DesignIR Pipeline

[`designir-pipeline/`](../designir-pipeline/)

负责：

- DesignIR Schema 和验证；
- 防作弊检查；
- Build123d / SimpleCADAPI 编译适配；
- 教师隔离重建；
- 几何与参数可编辑性验收；
- STEP 批量证据提取；
- 双 Agent 合同；
- 经验候选验证和发布。

### 5.3 text-to-cad

[`text-to-cad/`](../text-to-cad/)

负责：

- CAD Router；
- 通用 STEP-first 机械建模；
- Build123d 运行时；
- 几何检查和可视化；
- CAD Viewer 相关能力。

### 5.4 SimpleCADAPI

[`SimpleCADAPI/`](../SimpleCADAPI/)

这是基于 OCP/OpenCascade 的第二建模后端，适合：

- 可重放操作图；
- 参数表达式；
- 语义标签和拓扑查询；
- 齿轮、齿条、轴承等专用机械结构；
- STEP、STL 和 FreeCAD 工作流。

---

## 6. 环境准备

### 6.1 推荐环境

- macOS 或 Linux；
- Node.js 22 或更高版本；
- Python 3.12；
- Git；
- 能够运行 OpenCascade / Build123d 的本地环境；
- 支持 WebGL 的现代浏览器。

### 6.2 克隆项目

```bash
git clone https://gitea.robotquan.com/xuyongjie/cadSet.git
cd cadSet
git switch codex/remove-cadam
```

如果已经存在本地仓库：

```bash
git fetch origin
git switch codex/remove-cadam
git pull --ff-only origin codex/remove-cadam
```

### 6.3 Python 环境

前端默认查找：

```text
text-to-cad/.venv/bin/python
```

如果仓库中没有可用虚拟环境，可创建：

```bash
python3.12 -m venv text-to-cad/.venv
source text-to-cad/.venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r text-to-cad/requirements-dev.txt
python -m pip install -e SimpleCADAPI
```

也可以显式指定其他 Python：

```bash
export CAD_PYTHON=/absolute/path/to/python
export CAD_EXPERIENCE_PYTHON=/absolute/path/to/python
```

### 6.4 前端依赖

```bash
cd cad-agent-studio
npm install
```

依赖目录 `node_modules/` 不进入 Git。

---

## 7. LLM 配置

默认配置文件位于仓库根目录：

```text
llm.config.yaml
```

前端按以下顺序寻找配置：

1. `CAD_AGENT_STUDIO_CONFIG` 指定的绝对路径；
2. 仓库根目录 `llm.config.yaml`；
3. `cad-agent-studio/config/llm.config.yaml`；
4. `cad-agent-studio/config/llm.config.yaml.example`。

推荐使用环境变量保存密钥：

```yaml
defaultProvider: deepseek
defaultModel: deepseek:deepseek-chat

providers:
  deepseek:
    type: openai-compatible
    apiKeyEnv: DEEPSEEK_API_KEY
    baseURL: https://api.deepseek.com
    models:
      default: deepseek-chat
      reasoner: deepseek-reasoner

uploads:
  maxImageMB: 20
  maxStepMB: 200
  maxOtherMB: 50
  allowed:
    - image/png
    - image/jpeg
    - image/webp
    - .step
    - .stp

cad:
  taskRoot: ./data/tasks
  viewer:
    mode: iframe
    allowedOrigins:
      - http://127.0.0.1
      - http://localhost
```

然后设置密钥：

```bash
export DEEPSEEK_API_KEY="your-key"
```

配置也支持直接写 `apiKey`，但不要把真实密钥复制到公开文档、日志或公开仓库。
前端公开配置接口不会返回密钥和环境变量名称。

---

## 8. 启动项目

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

浏览器打开：

<http://127.0.0.1:53821>

生产构建：

```bash
npm run build
npm run start -- -H 127.0.0.1 -p 53821
```

如果前端不在 CadSet 根目录的直接子目录，可以指定引擎根目录：

```bash
export CAD_ENGINE_ROOT=/absolute/path/to/CadSet
```

---

## 9. 如何使用

### 9.1 自然语言生成零件

在对话框中尽量提供：

- 零件类型；
- 关键尺寸和单位；
- 孔、槽、凸台、圆角等特征；
- 阵列数量和分布方式；
- 哪些尺寸需要后续编辑；
- 是否有必须保持的安装界面。

示例：

```text
生成一个半径 50 mm、厚度 4 mm 的法兰盘。
中心孔直径 20 mm，中心孔外有一圈高 1 mm 的凸台。
在直径 80 mm 的分度圆上均匀分布 8 个 M3 间隙孔。
外径、厚度、孔径、孔数和分度圆直径都需要可编辑。
```

系统会：

1. 让模型生成完整 DesignIR。
2. 运行 CAD Router 选择后端。
3. 执行 DesignIR Schema 与防作弊验证。
4. 在隔离目录中生成 STEP。
5. 生成 Viewer 所需预览数据。
6. 在任务目录保存 DesignIR、STEP 和任务清单。

### 9.2 根据图片和文字生成

上传零件图片后，应补充图片无法可靠表达的信息：

- 实际尺寸；
- 对称关系；
- 被遮挡特征；
- 孔是否贯穿；
- 板厚；
- 圆角、倒角或拔模角；
- 图片是透视图、正视图还是技术图。

图像能力依赖所选模型。如果使用纯文本模型，例如不支持视觉输入的模型，
它不能直接理解图片。此时应切换到支持视觉的 OpenAI-compatible 模型，或
先把图纸尺寸和结构转成文字。

### 9.3 上传 STEP 进行参数化重建

在前端上传 `.step` 或 `.stp` 后，说明希望重建和开放的参数，例如：

```text
重建这个 STEP。识别主体、孔、槽、凸台和阵列关系。
优先开放整体长度、板厚、孔径、孔距和孔数量。
重建结果不能依赖原 STEP，并对这些参数分别做扰动测试。
```

处理原则：

1. 上传 STEP 只作为教师和验收真值。
2. 系统先读取确定性几何证据。
3. 模型根据证据生成 DesignIR。
4. 重建编译器不能访问教师 STEP。
5. Agent B 比较教师 STEP 与重建 STEP。
6. 参数扰动测试验证修改能力。

STEP 没有完整建模历史，因此复杂零件不保证一次得到理想的参数化分解。
系统应当对无法表达的特征明确输出
`unsupported_feature_vocabulary`，而不是偷偷复用原几何。

### 9.4 修改已生成模型

选中已有任务后，可以使用自然语言修改：

```text
把 plate_thickness 从 4 mm 改成 6 mm，其他尺寸不变。
```

或者：

```text
孔数改为 10，保持分度圆直径和中心孔不变。
```

修改应优先作用于任务中记录的 `*.designir.json`。系统会为修改请求创建
revision，保存 `edit-request.json`，然后重新生成 STEP 和 Viewer 资源。

不要直接修改最终 STEP 作为长期设计源，否则参数语义和编辑接口会丢失。

---

## 10. CAD Router 的工作方式

CAD Router 根据任务特征选择后端：

### Build123d

适合：

- 通用机械零件；
- 法兰、支架、轴、壳体和连接件；
- 一般机加工特征；
- 几何测量和验证；
- 自定义特征组合。

### SimpleCADAPI

适合：

- 齿轮、齿条、内齿圈；
- 轴承、摆线结构和部分减速器；
- 需要可重放操作图的任务；
- 需要语义标签和拓扑查询的任务。

查看路由决策：

```bash
text-to-cad/.venv/bin/python \
  text-to-cad/skills/cad-router/scripts/route.py \
  "生成一个带 8 个安装孔的法兰" \
  --explain
```

强制指定后端：

```bash
text-to-cad/.venv/bin/python \
  text-to-cad/skills/cad-router/scripts/route.py \
  "生成一个参数化齿轮" \
  --backend simplecadapi \
  --explain
```

路由器可以读取已发布经验库：

```text
designir-pipeline/output/library.json
```

它不能读取 `designir-pipeline/input/` 或 `designir-pipeline/runs/` 中的私有
教师数据和蒸馏过程。

---

## 11. DesignIR 命令行

以下命令均在仓库根目录执行。

### 11.1 验证 DesignIR

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

### 11.2 防作弊检查

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

如果同时有后端生成器：

```bash
text-to-cad/.venv/bin/python \
  designir-pipeline/scripts/designir_pipeline.py anti-cheat \
  part.designir.json \
  --generator generator.py
```

### 11.3 编译 STEP

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

### 11.4 隔离重建

```bash
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 simplecadapi
```

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

### 11.5 独立验收

```bash
text-to-cad/.venv/bin/python \
  designir-pipeline/scripts/designir_pipeline.py accept \
  --teacher /path/to/teacher.step \
  --designir /path/to/part.designir.json \
  --rebuilt /path/to/rebuilt.step \
  --report /path/to/acceptance-report.json
```

---

## 12. STEP 蒸馏系统

### 12.1 简化后的数据目录

```text
designir-pipeline/
├── input/                 原始 STEP/STP
├── runs/                  全部蒸馏过程
└── output/
    └── library.json       最终发布经验库
```

Git 规则：

| 数据 | 是否提交 |
| --- | --- |
| `input/*.step`、`input/*.stp` | 否 |
| 提取的私有几何证据 | 否 |
| Agent 草稿和中间 DesignIR | 否 |
| 重建 STEP | 否 |
| 验收报告和失败记录 | 否 |
| `output/library.json` | 是 |
| Schema、脚本、Agent 合同和测试 | 是 |

`runs/` 中的目录由程序按需创建：

```text
runs/
├── evidence/      STEP 提取的私有证据
├── designir/      Agent A 输出
├── rebuilt/       隔离重建 STEP
├── acceptance/    Agent B 验收报告
├── review/        语义批次和 LLM 草稿
└── quarantine/    失败和能力缺口
```

### 12.2 放入蒸馏数据

把所有目标 STEP/STP 直接放入：

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

无需再创建 `teacher/inbox` 等多层目录。

### 12.3 批量提取证据

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

默认读取：

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

默认写入：

```text
designir-pipeline/runs/evidence/
```

提取器会根据内容哈希跳过已处理的重复文件。私有证据可以包含精确尺寸、
坐标、曲面类型、轴线、包围盒、体积和拓扑统计，但这些内容不能直接发布。

### 12.4 准备语义蒸馏批次

```bash
designir-pipeline/scripts/cad-experience prepare
```

输出：

```text
designir-pipeline/runs/review/semantic-batch.json
```

这个批次会移除不适合公开的实例信息，并保留：

- 零件家族；
- 参数角色；
- 基准角色；
- 特征角色；
- 关系角色；
- 特征数量等级；
- 推荐构造阶段；
- 无量纲比例观察；
- 验证目标；
- 失败和修复候选。

### 12.5 Agent 进行语义归纳

调用 `cad-experience-builder`，让当前大模型完整阅读
`semantic-batch.json`，输出：

```text
designir-pipeline/runs/review/experience-draft.json
```

大模型应该归纳：

- 通用特征组合；
- 约束和设计不变量；
- 参数角色及依赖关系；
- 家族级 reconstruction grammar；
- 构造顺序；
- 验证方法；
- 可复用的失败修复策略。

它不应该复制：

- 某个零件的绝对尺寸；
- 源文件路径和哈希；
- 绝对坐标；
- 面、边或拓扑 ID；
- 完整实例参数字典；
- 教师几何。

### 12.6 确定性验证与发布

```bash
designir-pipeline/scripts/cad-experience publish \
  --draft designir-pipeline/runs/review/experience-draft.json
```

发布器会重新核对私有语料中的支持数量和置信度，拒绝实例泄漏，只把通过
验证的内容写入：

```text
designir-pipeline/output/library.json
```

审计：

```bash
designir-pipeline/scripts/cad-experience audit \
  designir-pipeline/output/library.json
```

查询经验：

```bash
designir-pipeline/scripts/cad-experience query \
  designir-pipeline/output/library.json \
  --family flanged_hub_adapter \
  --features base_flange,hollow_sleeve,counterbore
```

直接绕过 LLM 语义归纳进行纯统计 `distill` 会被阻止。原因是简单共现统计
难以可靠地区分“设计方法”和“某批数据中的偶然尺寸模式”。

---

## 13. 双 Agent 的职责

### Agent A：Reconstruction Agent

输入：

- `runs/evidence/` 中的单案例私有证据；
- 用户修改目标；
- 已晋升的通用经验；
- DesignIR Schema 和支持的操作词汇。

输出：

- `runs/designir/*.designir.json`；
- 需要隔离编译的重建请求；
- 不确定项和缺失能力。

禁止：

- 读取源 STEP；
- 导入 B-Rep；
- 使用完整网格代替参数化模型；
- 保存源拓扑引用；
- 直接发布经验。

### Agent B：Acceptance Agent

输入：

- `input/` 中的教师 STEP；
- Agent A 生成的 DesignIR；
- `runs/rebuilt/` 中的重建 STEP；
- 修改测试合同。

输出：

- `runs/acceptance/` 中的机器可读报告；
- `pass`、`fail` 或 `quarantine` 建议。

Agent B 检查：

- 实体和拓扑数量；
- 包围盒；
- 体积和质心；
- 对称差体积；
- 关键解析特征；
- 参数扰动成功率；
- 非目标区域保持情况；
- 自交、零厚度、非流形和不稳定重建。

Agent B 同样不能直接把经验写入正式库。最终发布由确定性程序执行。

### 纯文本模型能否完成蒸馏和验收

可以完成大量工作，但存在边界：

- STEP 几何证据由程序提取后，纯文本模型可以阅读 JSON、归纳特征和生成
  DesignIR。
- 数值验收由几何程序完成，不要求模型直接看图。
- 纯文本模型可以根据验收 JSON 分析失败和提出修复。
- 对视觉外观、复杂曲面、特征语义歧义和图纸理解，多模态模型通常更强。

因此 DeepSeek 等纯文本模型可以参与批量蒸馏闭环，但不应让模型自己“凭
感觉”验收。验收真值必须来自确定性几何比较；关键失败案例可再交给多模态
模型或人工复核。

---

## 14. 经验为什么会随着数据增加而变好

蒸馏数据量增加后，系统可能提升：

- 零件家族识别；
- 特征分解；
- 主参数发现；
- 参数依赖推断；
- 基准和约束识别；
- 构造顺序选择；
- 修改接口设计；
- 常见失败修复；
- 验收目标选择。

但数据量不是唯一因素。能力增长受三个条件共同限制：

1. **DesignIR 能否表达**：没有 sweep、loft、shell 或复杂孔词汇时，再多
   数据也无法独立重建这类结构。
2. **证据质量是否足够**：提取器必须提供可用于推断的曲面、轴线、关系和
   截面证据。
3. **验收是否严格**：如果只比较截图或包围盒，错误经验也可能被晋升。

经验晋升必须同时满足：

```text
几何接近
AND 特征语义合理
AND 参数可编辑
AND 修改后稳定
AND 多个独立案例重复支持
```

当前默认晋升策略至少要求 3 个独立案例状态通过；经验归纳命令默认使用更
保守的 `min_support=20` 和 `min_confidence=0.8`。两者用途不同：

- `minimum_independent_cases=3` 是完整重建和回放状态的最低发布门槛。
- `min_support=20` 是从批量语料归纳通用经验时的默认统计支持度。

策略文件：

[`designir-pipeline/config/promotion-policy.json`](../designir-pipeline/config/promotion-policy.json)

---

## 15. 验收指标

不要把所有结果压缩成一个不透明的“相似度分数”。建议分别保存：

### 几何一致性

- 相对体积误差；
- 包围盒各轴误差；
- 质心误差；
- 对称差体积比例；
- 双向表面距离；
- 关键截面误差。

### 特征语义

- 特征召回率；
- 特征准确率；
- 孔、槽、筋和凸台数量；
- 轴线、半径、同心和阵列关系；
- 是否生成多余特征。

### 参数化能力

- 关键尺寸参数覆盖率；
- 参数扰动成功率；
- 修改目标准确率；
- 非目标区域保持率；
- 约束保持率；
- 编辑接口稳定性。

### 几何有效性

- 是否为闭合实体；
- 是否为空；
- 是否自交；
- 是否出现零厚度；
- 是否出现非流形几何；
- 重复执行是否确定。

当前策略中的主要默认阈值包括：

- 相对体积误差不超过 `1%`；
- 质心误差不超过 `0.1 mm`；
- 包围盒各轴误差不超过 `0.1 mm`；
- 对称差比例不超过 `2%`；
- 参数扰动成功率要求 `100%`。

这些阈值是当前工程默认值，不是所有零件和制造场景的通用标准。

---

## 16. 任务产物

前端任务默认保存在：

```text
cad-agent-studio/data/tasks/<taskId>/
```

典型产物包括：

```text
<taskId>/
├── cad-task.json
├── model.designir.json
├── model.step
├── model.simplecad.model.json    可选
├── acceptance-report.json       STEP 重建时可选
├── revisions/
│   └── <revisionId>/
│       └── edit-request.json
└── Viewer 预览资源
```

职责划分：

- `model.designir.json`：可编辑设计源。
- `model.step`：主要几何交换结果。
- `cad-task.json`：路由、后端、产物和验证记录。
- `*.simplecad.model.json`：SimpleCADAPI 的可重放操作图。
- `acceptance-report.json`：教师与重建件的独立验收结果。
- `revisions/`：后续修改请求记录。

`cad-agent-studio/data/` 是本地运行数据，不提交 Git。

---

## 17. 测试与质量检查

### 前端测试

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

### DesignIR、经验库和 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
designir-pipeline/scripts/cad-experience audit \
  designir-pipeline/output/library.json
```

### Git 数据边界检查

确认没有 STEP 输入和蒸馏过程被跟踪：

```bash
git ls-files designir-pipeline/input \
  designir-pipeline/runs \
  designir-pipeline/output
```

正常情况下只应看到：

```text
designir-pipeline/input/.gitkeep
designir-pipeline/output/library.json
```

---

## 18. 常见问题

### 前端提示找不到 Python

确认以下文件存在并可执行：

```text
text-to-cad/.venv/bin/python
```

或者设置：

```bash
export CAD_PYTHON=/absolute/path/to/python
```

### 前端提示找不到 LLM 配置

确认仓库根目录存在：

```text
llm.config.yaml
```

或者：

```bash
export CAD_AGENT_STUDIO_CONFIG=/absolute/path/to/llm.config.yaml
```

### 模型可以对话但不能生成 STEP

检查：

1. Python 环境是否包含 Build123d/OCP 或 SimpleCADAPI。
2. `CAD_ENGINE_ROOT` 是否指向 CadSet 根目录。
3. DesignIR 是否通过 Schema 验证。
4. DesignIR 是否使用了当前不支持的 operation。
5. Router 选择的后端是否在当前 Python 环境可用。

### 上传图片后模型仍说看不到

当前所选模型可能不支持视觉输入。更换支持图片的模型，或把图片中的结构
和尺寸转换成文字描述。

### STEP 重建几何接近但不好修改

这通常表示参数化分解不合理，例如：

- 所有尺寸都被写成固定常量；
- 孔和阵列没有独立参数；
- 基准选择不稳定；
- 特征顺序导致参数变化后布尔失败；
- 修改合同没有覆盖关键参数。

应优先改进 DesignIR 和特征分解，而不是放宽几何验收。

### 为什么不直接修改上传的 STEP

直接在源 STEP 上做布尔操作可以快速得到几何结果，但无法建立稳定、通用
的参数化设计能力，也不能随着蒸馏数据增加而学习更好的重建方法。CadSet
把源 STEP 限定为教师和验收真值，是为了让系统真正学会独立重建。

### 为什么过程数据不提交 Git

原始 STEP、证据 JSON、重建件和验收报告会快速增长，而且可能包含私有
实例尺寸。仓库只提交经过净化和验证的经验库结果，以及复现管线所需的代码、
Schema、合同和测试。

---

## 19. 扩展项目

### 新增 DesignIR 操作

至少需要同步更新：

1. `designir-2.0.schema.json` 的 operation 词汇；
2. Build123d 编译适配；
3. SimpleCADAPI 编译适配，或明确标记仅支持某后端；
4. anti-cheat 检查；
5. 参数扰动和几何验收；
6. 示例与测试；
7. CAD Router 能力表。

### 新增后端

新后端应满足：

- 接收显式 DesignIR 和输出路径；
- 不隐式扫描整个工作区；
- 不读取教师 STEP；
- 输出标准 STEP；
- 保留可编辑的后端源或操作图；
- 返回明确的成功/失败状态；
- 记录后端名称和版本；
- 接入统一验收合同。

### 扩展蒸馏能力

推荐按失败聚类驱动扩展：

1. 收集 `runs/quarantine/` 中的失败。
2. 区分证据不足、词汇不足、推断错误和编译错误。
3. 对高频缺口新增 DesignIR 操作或几何证据。
4. 加入针对性重建和参数扰动测试。
5. 在 held-out STEP 上验证。
6. 通过后再允许经验晋升。

---

## 20. 当前边界与研发建议

CadSet 当前已经形成了完整的工程骨架：

- 独立 Web 前端；
- 统一 DesignIR；
- 双建模后端；
- STEP 隔离重建；
- 双 Agent 职责边界；
- 参数扰动验收；
- 批量经验蒸馏；
- 防实例泄漏发布器；
- 运行数据与 Git 结果隔离。

下一阶段最值得投入的方向：

1. 扩展 DesignIR 的扫掠、放样、薄壁、倒角、圆角和复合孔词汇。
2. 增强 STEP 解析中的特征关系、关键截面和对称性识别。
3. 建立按零件家族分层的数据集和 held-out 测试集。
4. 增加表面双向距离和局部非目标区域保持指标。
5. 将失败案例自动聚类为“证据不足、词汇不足、编译失败、参数失稳”。
6. 为大规模数据增加任务队列、断点续跑、并发控制和状态看板。
7. 对高价值复杂案例加入多模态复核，但继续以确定性几何验收为最终依据。

CadSet 的核心原则可以概括为：

> STEP 只做教师，DesignIR 才是设计源；模型必须独立重建，经验必须经过
> 多案例和修改测试验证后才能进入生产。