feat: unify CAD workflows on DesignIR 3.0

2026-07-28 14:41:26 +08:00
parent 6e33bc0e11
commit b5738e9109
36 changed files with 9690 additions and 1305 deletions
@@ -70,14 +70,17 @@ Write `cad-task.json` beside the task artifacts with this minimum shape:

 Paths are relative to the task directory unless an external input must remain absolute.
 Do not store authoritative model parameters in `cad-task.json`. Every part must
-have a sibling `*.designir.json` that owns its coordinate system, datums,
-parameters, expressions, features, constraints, edit interface, and validation
-contract. See `designir-2.0.md`.
+have a sibling `*.designir.json` as its editable source of truth. Authored
+feature models use semantic DesignIR 3.0; uploaded STEP reconstruction uses
+DesignIR 3.0 / SurfaceIR. See `designir-3.0.md`; `designir-2.0.md` is retained
+only for legacy migration.

-For an uploaded STEP, keep teacher geometry in `designir-pipeline/input/` and
-all private evidence, DesignIR candidates, rebuilds, and acceptance reports in
-`designir-pipeline/runs/`. The reconstruction task receives evidence but no
-teacher STEP or imported B-Rep.
+For an uploaded STEP, use `scripts/route.py --execute` with an explicit source
+and task directory. Do not move an ordinary upload into or scan the
+distillation corpus. The task publishes the independent DesignIR, reconstructed
+STEP, validated parameter catalog, geometry report, edit report, and
+`cad-task.json`. The reconstruction subprocess receives no teacher STEP path;
+only extraction and acceptance may read the explicit uploaded source.

 ## Backend adapter requirements

@@ -9,7 +9,7 @@ Best fit:
 - Brackets, connecting rods, cranks, levers, shafts, bushings, flanges, plates, housings, covers, enclosures, fixtures, and machined features.
 - Parametric Python sources with holes, pockets, slots, bosses, ribs, shells, fillets, chamfers, lofts, sweeps, and revolves.
 - Source-level assemblies, named datums, joints, imported components, measurements, alignment checks, and existing STEP inspection.
- STEP output compiled from executable DesignIR 2.0.
+- STEP output compiled from executable semantic DesignIR 3.0.

 Weak signals: a specialized mechanical family already implemented by SimpleCADAPI or a browser-only execution requirement.

@@ -1,5 +1,9 @@
 # DesignIR 2.0 contract

+> Legacy migration reference only. New text, image, and STEP workflows must
+> emit DesignIR 3.0. Use `designir_pipeline.py migrate` to preserve an existing
+> 2.0 semantic feature program inside the DesignIR 3.0 envelope.
+
 Every generated, reconstructed, or modified part owns one executable
 `*.designir.json`. It records design intent rather than source faces or a copied
 solid.
@@ -0,0 +1,129 @@
+# DesignIR 3.0 unified contract
+
+DesignIR 3.0 is the only editable part contract. It has three explicit modes:
+
+- `fully_semantic_parametric`: authored from text or images. `semantic_layer`
+  contains design intent, named parameters, constraints and executable
+  features.
+- `surface_parametric`: inferred from an uploaded STEP. `surface_layer`
+  contains analytic/B-spline surfaces, boundary curves, pcurves, vertices,
+  tolerances, shells and solids in CadSet's vocabulary.
+- `hybrid_semantic_surface_parametric`: a semantic feature program plus a
+  compiled SurfaceIR snapshot extracted from its generated STEP. The semantic
+  layer remains authoritative.
+
+The two authoring paths share one envelope and edit vocabulary, but they do not
+claim equivalent evidence. Text/image generation authors design intent. STEP
+ingestion infers semantics from final B-Rep and never claims to recover the
+source CAD application's sketch or feature history.
+
+## Text and image authoring
+
+Author these top-level values:
+
+```json
+{
+  "schema_version": "3.0",
+  "designir_kind": "independent_parametric_cad",
+  "model_id": "part_id",
+  "family": "semantic_part_family",
+  "units": "mm",
+  "document_status": "geometry_present",
+  "reconstruction_mode": "fully_semantic_parametric",
+  "authoring_mode": "semantic_feature_program",
+  "backend_hint": "build123d",
+  "semantic_layer": {
+    "reconstruction_status": "ready",
+    "coordinate_system": {
+      "origin": [0, 0, 0],
+      "x_axis": [1, 0, 0],
+      "y_axis": [0, 1, 0],
+      "z_axis": [0, 0, 1]
+    },
+    "datums": {},
+    "parameters": {},
+    "expressions": {},
+    "sketches": [],
+    "constraints": [],
+    "features": [],
+    "patterns": [],
+    "attachments": [],
+    "construction_stages": []
+  },
+  "edit_interface": {
+    "semantic_parameters": [],
+    "surface_parameter_groups": [],
+    "modification_levels": ["semantic_feature"],
+    "preserved_interfaces": []
+  },
+  "validation_contract": {
+    "source_independence": true,
+    "geometry_checks": ["solid_count", "bounding_box", "volume"],
+    "edit_checks": ["parameter_perturbation"],
+    "invariants": [],
+    "perturbations": [],
+    "thresholds": {}
+  }
+}
+```
+
+Every name in `semantic_parameters` must identify an editable parameter, drive
+at least one feature, and have a perturbation test. Prefer intent names such as
+`flange_thickness`, `shelf_depth`, `hole_spacing`, `rib_count`,
+`bore_diameter`, and `bolt_circle_diameter`.
+
+After isolated compilation, attach SurfaceIR only from the generated STEP and
+switch the mode to `hybrid_semantic_surface_parametric`. Never use a teacher
+STEP to fill the compiled snapshot.
+
+## Uploaded STEP execution
+
+Run an uploaded file through the router's executable adapter:
+
+```bash
+../../.venv/bin/python scripts/route.py \
+  "重建上传的 STEP，并返回可修改参数" \
+  --edit-source /absolute/path/to/part.step \
+  --task-dir /absolute/path/to/task \
+  --execute
+```
+
+The task directory contains:
+
+- `<part>.designir.json`: independent editable source of truth;
+- `<part>.reconstructed.step`: reconstructed geometry;
+- `parameters.json`: only parameters that passed perturbation acceptance;
+- `validation/geometry.json`: teacher-versus-reconstruction measurements;
+- `validation/edits.json`: parameter acceptance outcomes;
+- `cad-task.json`: route, artifacts, isolation and validation state.
+
+## Isolation boundary
+
+Extraction and acceptance may read the uploaded STEP. The reconstruction
+subprocess receives only DesignIR and an output path. DesignIR must not contain
+a teacher path, an import operation, STEP text, embedded B-Rep, or a mesh
+substitute.
+
+The runtime performs an anti-cheat scan before rebuilding. Geometry acceptance
+requires valid reconstructed topology and the thresholds recorded in
+`validation/geometry.json`.
+
+The adapter loads only formally promoted experiences whose scope is
+`surfaceir_reconstruction` or `surfaceir_semantic_editing`. These methods are
+applied conditionally by the runtime; `cad-task.json` records both the available
+method count and the exact method IDs used for the task.
+
+## Parameter boundary
+
+STEP does not contain authoritative feature names or modeling history. The
+semantic layer therefore records inferred canonical parameters separately from
+validated editable parameters.
+
+Only parameters in `parameters.json` are public edit controls. Each was changed
+in isolation, rebuilt, and checked for target response, preserved validity and
+non-target stability. Use the `edit_command_template` in `cad-task.json` to
+produce an edited DesignIR and STEP.
+
+An accepted baseline reconstruction does not imply that every inferred
+parameter is editable. An empty `parameters.json` is valid for an empty source
+document and must not be presented as editable geometry.