cadSet/README.md

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 / Image / STEP ──> │  CAD Agent Studio  │
                         └─────────┬──────────┘
                                   │
                         ┌─────────▼──────────┐
                         │ CAD Router/DesignIR │
                         └──────┬───────┬─────┘
                                │       │
                    ┌───────────▼─┐   ┌─▼────────────────┐
                    │  Build123d  │   │ SimpleCADAPI 2.0.2│
                    └───────────┬─┘   └─┬────────────────┘
                                └────┬────┘
                                     │
                           DesignIR 3.0 + STEP
                                     │
                         ┌───────────▼───────────┐
                         │ Viewer / Acceptance   │
                         └───────────────────────┘

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

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/	独立 Next.js 前端，负责对话、图片与 STEP 上传、任务管理和模型预览。
designir-pipeline/	DesignIR Schema、双 Agent、隔离编译、验收和经验晋升。
text-to-cad/	CAD Router、Build123d CAD Skill、CAD Viewer 和共享 CAD 运行时。
SimpleCADAPI/	2.0.2 平权建模与验收后端，提供标准件、可重放图、语义拓扑、单位/公差、场景和 B-Rep 工具。
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

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

• 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 任务触发，尚未提供常驻目录监听服务。