Files
make-cad/docs/updates/2.1.0.md
T
NiJingzhe a45cbf280e chore(release): 2.1.0
- version 2.0.4b3 -> 2.1.0 (pyproject, uv.lock, skill frontmatter, READMEs)
- docs/updates/2.1.0.md + zh-CN: release notes spanning the 2.0.4b2 baseline
  (absorbs the unreleased 2.0.4b3 draft: product boundaries, incremental
  assembly, crash-safe cache) plus FTC authoring, DXF engine, external
  history import, reverse-engineering studio, unified rendering, Apache-2.0
  relicensing, harness-targeted skill builds, self-contained examples, and
  the geometry fingerprint round-trip fix
2026-09-07 09:45:57 +08:00

115 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SimpleCADAPI 2.1.0 Update Notes
[Chinese](2.1.0.zh-CN.md)
> **Release notice:** Validate generated definitions, assembly constraints,
> and manufacturing geometry before production use.
SimpleCADAPI 2.1.0 turns the SDK into an agent-first CAD toolkit: a
Feature-Tree-Convention authoring discipline with compiler-verified skill
guidance, an external CAD-history import path, a reverse-engineering studio
in the browser, DXF engineering drawings, and self-contained runnable
examples — on top of the reproducible product boundaries and crash-safe
cache introduced during the 2.0.4 beta cycle.
## 1. Durable part and assembly definitions
`@scad.part` builds exactly one physical single-solid part and returns a
`PartBuildResult`: runtime `Part`, `PartDefinition`, graph/session state,
model and session JSON, interface differences, and a per-build `CacheReport`.
Its content-derived key covers normalized arguments, builder source, declared
file inputs, revision, tolerance profile, and generator/ABI profile.
`@scad.assemble` requires explicit external `PartDefinition` or nested
`AssemblyDefinition` inputs. Repeated instances share immutable definitions;
closed validation rejects missing, unused, cyclic, conflicting, or
incompatible references. Definitions round-trip independently from
process-local runtime objects. Connector interface hashing is stable across
processes, so identical interfaces no longer produce spurious definition
diffs.
## 2. Incremental assembly solve, cache, and diagnostics
Assembly state records component dependencies and public connector
interfaces; changes propagate only along affected dependency paths, and every
restored placement still passes constraint-residual verification. The shared
content-addressed store uses canonical closed records, SHA-256 objects,
atomic writes, per-key locks, stale-lock recovery, and deduplication. One
`CachePolicy` (`off` / `read_only` / `read_write` / `refresh`) governs part
and assembly caching, and the `simplecad-cache` CLI emits stable JSON status
and verify/repair reports.
## 3. Feature Tree Convention (FTC)
Model sources follow an explicit feature-block discipline — sketch/profile,
operations, booleans, modifiers — recorded as a readable dataflow
(`body = op(body, tools)`), with per-feature header comments
(`# ---- feature: <slug> (<role>) ----`). The convention is backed by:
- a constrained 2D sketch API (dimension-driven profiles, wire offset for
shell-like walls) with open chain promotion to wires;
- canonical plane/axes conventions for planar makers, covered by regression
tests;
- a verified QL selection playbook (33 selection patterns) documenting the
structured selection channels and their reach.
## 4. DXF engineering drawings
A deterministic DXF engine turns a modeled part into 2D engineering drawings
through HLR projection: sheet plans, views, dimension chains, and diagnostic
plots, driven by the same package pipeline as the 3D exporters.
## 5. External CAD history import
`tools/research/histjson` plus the SDK translation layer import external
CAD-history dialects (Fusion-style histories) into FTC model sources:
constraints are translated unconditionally with per-item conflict audit
output instead of silent fallbacks. On the reference benchmark the deep
multi-feature case reproduces geometry at machine precision (Deep ~85%,
Fusion ~77% exact-match) and the constraint channel solves ~90% (Deep) /
~93% (Fusion) of cases.
## 6. Reverse-engineering studio in the browser
`viewer/re.html` is a human-in-the-loop reverse-engineering workbench:
pick faces/edges or lasso a region on the target STEP, annotate with inline
entity and operation chips, and submit — the server composes a
`submission.json` (annotations + per-entity one-level adjacency context +
operation tips + snapshot), an agent rebuilds, and the UI streams the
comparison and evaluation back. The composer is IME-safe (CJK composition
never submits), the same operation tip can be cited multiple times, and
user selections are never truncated. The studio UI is built with React 19 +
Tailwind 4 + shadcn-style components over the imperative three.js kernel.
The companion `.scadpkg` browser inspector loads v3 packages with full
closure-hash validation, so tampered packages are rejected by name.
## 7. Unified rendering and FEM-ready exports
One screenshot pipeline serves all 3D rendering needs: 1–4 view grids,
studio styling, deterministic anti-aliasing, and per-view annotation
placement with occlusion handling. The AP242/Gmsh example chains the package
through AP242 STEP, Gmsh volume meshing, and a Calculix static solve with
von-Mises reporting; MJCF export covers MuJoCo assembly consumers.
## 8. Open-source readiness
- Relicensed from AGPL-3.0 to Apache-2.0.
- The packaged skill is compiled per host harness (omp, opencode, zcode,
claudecode, codex, dsh, kimicode) from one source tree with conditional
host-binding blocks; a typo in a target name fails the build.
- Examples are self-contained folders (sources + verification + fresh
artifacts under `examples/<name>/out/`), cover part / assembly / reverse
engineering / FEM, and every example is verified to run end-to-end.
- `scad.verifier` and the `python-fcl` dependency are removed; collision
verification is external to the SDK.
## 9. Reliability
Geometry fingerprints are stable across BRep serialize/deserialize
round-trips (bounds quantized on a fixed 1e-4 mm grid, far coarser than the
sub-tolerance recomputation wobble), so package re-validation no longer
fails on cell-edge geometries. The Python type-check baseline was reduced
by an order of magnitude, and the suite stands at 1503 passing tests across
Python 3.10–3.13.