a45cbf280e
- 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
115 lines
5.6 KiB
Markdown
115 lines
5.6 KiB
Markdown
# 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.
|