cadSet/README.md

CadSet

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

系统的统一设计源是自有的 DesignIR 2.0。STEP 是主要交换与验收格式，但上传的源 STEP 只作为教师证据和验收真值，不作为重建时的几何依赖。

完整的安装、使用、架构和蒸馏说明见 docs/CADSET_PROJECT_GUIDE.zh-CN.md。

产品范围

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

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

CAD Router 会在两个执行后端之间选择：

• text-to-cad / Build123d：通用机械零件、特征建模、几何验证和 STEP 输出。
• SimpleCADAPI：可重放操作图、语义化机械结构和专用机械零件能力。

系统架构

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

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

Teacher STEP
  -> private geometry evidence
  -> Reconstruction Agent
  -> DesignIR 2.0
  -> isolated compiler without Teacher STEP access
  -> rebuilt STEP
  -> independent Acceptance Agent
  -> deterministic experience promotion

仓库结构

路径	职责
cad-agent-studio/	独立 Next.js 前端，负责对话、图片与 STEP 上传、任务管理和模型预览。
designir-pipeline/	DesignIR Schema、双 Agent、隔离编译、验收和经验晋升。
text-to-cad/	CAD Router、Build123d CAD Skill、CAD Viewer 和共享 CAD 运行时。
SimpleCADAPI/	第二建模后端，提供可重放操作图和机械建模 API。
llm.config.yaml	前端共享的模型供应商、模型和密钥配置。

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

DesignIR 2.0

DesignIR 保存设计意图，而不是复制 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-2.0.schema.json

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

• extrude_circle
• extrude_rectangle
• add_cylinder
• through_hole
• polar_hole_pattern

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

STEP 蒸馏与验收

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

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/scripts/cad-experience extract-folder

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

本地开发

环境要求

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

启动前端

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 命令

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。

验证

前端：

cd cad-agent-studio
npm test
npm run build

DesignIR、经验库与 CAD Router：

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

经验库审计：

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

当前边界

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

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