cadSet/text-to-cad/skills/cad-router/SKILL.md

---
name: cad-router
description: Route natural-language or image-guided CAD generation and modification, plus uploaded STEP/STP reconstruction and modification, across text-to-cad and SimpleCADAPI. Use unified executable DesignIR 3.0 in semantic-feature mode for authored models and SurfaceIR mode for uploaded STEP reconstruction, without teacher geometry dependencies, with independent validation and CAD Viewer review.
---

# CAD Router

Choose a backend before modeling, keep its source as the editable authority, and normalize every result into one handoff contract. `text-to-cad` is the backend-neutral orchestrator and DesignIR owner, not a backend that must win by default. `build123d` and SimpleCADAPI 2.0.2 are equal-priority authoring backends selected from evidence. Uploaded STEP reconstruction is executed by SurfaceIR and independently checked by both the existing geometry validator and SimpleCADAPI B-Rep comparison.

## Required workflow

1. Convert the natural-language or image-guided request into a brief: part type, dimensions, units, assembly relationships, editability, and validation targets. Every model uses DesignIR 3.0 plus STEP geometry. New text/image models use `fully_semantic_parametric`; uploaded STEP reconstruction uses `surface_parametric`. A generated semantic model may include a compiled SurfaceIR snapshot and then uses `hybrid_semantic_surface_parametric`, while its semantic layer remains authoritative.
   Never treat a teacher STEP or a single-case DesignIR as experience. Batch case
   JSON belongs to the separate CAD Experience plugin. Generation may consume
   only its promoted schema `2.0` generalized library.
   Never read `cad-experience-plugin/parser/input`, `parser/output`, or private
   case JSON during creation, modification, or reconstruction.
2. Run the deterministic router from this skill directory. For a new model it
   matches only the requested primary part against the SimpleCADAPI standard
   part catalog in `scripts/capabilities.json`. A catalog match selects
   SimpleCADAPI; every unmatched request selects text-to-cad/build123d. It does
   not read capability documents or let an LLM choose the backend:

   ```bash
   python3 scripts/route.py "<request>" --explain
   ```

   Add explicit signals when known: `--edit-source path/to/source`, `--existing-model`, or `--assembly`.
   The router auto-discovers the workspace `cad-experience-library/library.json`,
   infers an experience family and feature roles from the request, and emits a
   backend-neutral `design_plan`. When promoted `reconstruction_grammar`
   records match, instantiate their symbolic parameter roles, datum roles,
   canonical stages, and validation roles in the new part's
   DesignIR; fill values from explicit user dimensions first and
   dimensionless distributions second. Use `--experience-library`,
   `--experience-family`, or repeated `--experience-feature` only to override
   those defaults.
   For one uploaded STEP, execute the route rather than stopping after the
   routing decision:

   ```bash
   ../../.venv/bin/python scripts/route.py \
     "重建上传的 STEP，并返回可修改参数" \
     --edit-source /absolute/path/to/upload.step \
     --task-dir /absolute/path/to/task \
     --execute
   ```

   This command must finish extraction, source-independent reconstruction,
   geometry acceptance, parameter perturbation acceptance, and artifact
   publication. A route decision alone is not a completed reconstruction.
3. Follow the selected route unless a hard environmental constraint makes it unavailable. If overriding it, record the reason in the task manifest.
4. Use the selected backend directly:
   - `build123d`: use `$cad` for custom brackets, housings, shafts, flanges, fixtures, source-level assemblies, and every new part outside the catalog.
   - `simplecadapi`: use the installed SimpleCADAPI 2.0.2 runtime only for catalogued standard primary parts: gears, ring gears, racks, cycloidal discs, ball bearings, roller-chain sprockets, bolts, and nuts.
5. When the route reports `requirement_refinement` or `visual_repair`, refine the brief, generate, execute, inspect multiple views, and repair no more than three visual mismatch rounds before asking the user.
6. Generate into a task-owned directory and start CAD Viewer with that task directory as `--dir`; do not expose the repository-wide fixture library for a task review. Write one DesignIR 3.0 `*.designir.json` per part and treat it as the editable geometry contract; keep `cad-task.json` as the execution record. Read `references/designir-3.0.md` for both semantic authoring and uploaded STEP reconstruction. `references/designir-2.0.md` is migration-only. Never change backend during an edit unless conversion is explicitly requested; modify the recorded authoritative layer.
   For a supplied STEP/STP, use `scripts/route.py --execute`; do not manually
   approximate the model when the executable adapter is available. The
   deterministic ingestion service extracts private teacher evidence into
   DesignIR 3.0. The independent rebuild subprocess receives the DesignIR and
   output path, never the STEP path. The acceptance stage alone receives both
   teacher and reconstruction.
   The DesignIR and generator must not import STEP, embed B-Rep or meshes, retain
   face references, or use the source model as a base feature. The acceptance
   agent alone compares the teacher and reconstructed STEP.
   Dense SurfaceIR may be stored losslessly in the DesignIR 3.0
   `gzip+base64+json` envelope. CAD runtimes verify and decode it; LLM prompts
   receive only the semantic layer, edit interface, and validated parameter
   catalog, never the encoded geometry payload.
   Only expose parameters listed by `parameters.json`; every listed parameter
   has passed an isolated perturbation test. Other inferred names remain
   evidence, not a promised edit interface.
   The acceptance zone also runs the installed SimpleCADAPI 2.0.2 strict B-Rep
   comparator. `brep_exact` requires both the bidirectional geometric-set check
   and the geometry-labelled incidence graph check. A geometry-equal but
   topology-different result is returned as `review_required`, not silently
   described as an exact reconstruction. Failure or absence of the supplemental
   comparator must be recorded separately and must not be confused with a pass.
7. Validate against the brief. Run STEP geometry inspection and snapshot review.
   For experience-informed generation, record which generalized methods were
   applied, including the reconstruction grammar ID and instantiated symbolic
   roles. Validate against the user's brief and held-out targets, never against
   parameters exposed from the same source case.
8. Write a `cad-task.json` manifest using the contract in `references/backend-contract.md`. Hand the STEP artifact to `$cad-viewer` and return its live link.
9. Export URDF or MJCF only on explicit request. Run the deterministic
   DesignIR robot-description exporter lazily and return its portable ZIP with
   XML, STL visual/collision geometry, and export manifest. When authoritative
   assembly/joint/material evidence is absent, export one fixed `base_link`;
   never invent joints, limits, actuators, mass, or inertia.

## Routing rules

- Prefer an explicit user backend when it can produce the editable STEP contract.
- Preserve the backend of an explicitly supplied DesignIR or Python generator unless conversion is requested.
- Do not assign a permanent default backend. Score native-source continuity, factory coverage, semantic/replay needs, geometry vocabulary, assembly needs, and validation needs.
- For a new model, do not use semantic, graph, tolerance, assembly, or generic mechanical keywords to choose a backend. Use the standard-part catalog only.
- Select SimpleCADAPI only when the primary requested part matches an entry in `scripts/capabilities.json`. Standard-part words used only as features, such as bolt holes or bearing seats, are excluded from that match.
- Select build123d for every unmatched new request, including custom machined parts, source-driven assemblies, and freeform or surface-heavy work.
- For uploaded STEP, report SurfaceIR as the effective reconstruction engine. The selected authoring backend describes future semantic repair/edit work; it is not allowed to read the teacher STEP during reconstruction.
- Prefer source quality and future modification over the shortest first generation.

## V1 boundaries

- Do not promise lossless conversion of feature history between backends.
- Do not claim engineering certification, tolerance analysis, FEA, CAM toolpaths, or manufacturability without separate checks.

## References

- Read `references/capabilities.md` when comparing or invoking backends.
- Read `references/backend-contract.md` before writing a task manifest or adding another backend.
- Read `references/designir-3.0.md` for semantic authoring, uploaded STEP reconstruction, and edits.
- Read `references/designir-2.0.md` only when migrating legacy artifacts.
- `scripts/capabilities.json` is the machine-readable V1 registry used by `scripts/route.py`.