cadSet/text-to-cad/skills/cad-router/references/designir-3.0.md

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:

{
  "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:

../../.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.