Files
make-cad/docs/updates/2.0.4b3.md
T
Ni Jingzhe c454a3af10 feat(skill): per-harness skillbuild toolchain replaces skill-pack (#18)
* feat(skill): replace skill-pack with per-harness conditional compiler

skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
  targets; name-list conditions only, no else/nesting, fail-loud on
  unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
  name check

Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
  references/, generated api/stdlib/core/guides now under
  references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
  files)
- auto_docs_gen output redirected into the tree (docs/api ->
  docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
  dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
  entries and their orphaned test), release workflow builds via
  skillbuild + tar; README updated

First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).

Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).

* refactor(tools): auto_docs_gen moves out of the installed package

tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
  auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
  if pyproject.toml missing; site-packages/cwd fallback branches were
  dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
  release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
  runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
  updated to direct examples/ scripts; dangling runner-contract test
  (runpy.run_path into the deleted script) removed

Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).

* refactor(skill): strip harness and build-tool content from the skill tree

The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
  mount block and its !omp complement were the only conditional
  blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
  conditional compilation', skillbuild packaging/validation claims —
  link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
  (omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
  leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
  untracked from git, skills/simplecadapi-*/ gitignored, release.yml
  and README build via skillbuild and tar the omp output directly
  (bsdtar has no --transform; inner dir keeps its suffixed name)

Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.

* chore(docs): drop stale architecture review and design notes
2026-08-22 20:20:49 +08:00

6.4 KiB

SimpleCADAPI 2.0.4b3 Update Notes

Chinese

Beta release notice: Validate generated definitions, assembly constraints, and manufacturing geometry before production use.

SimpleCADAPI 2.0.4b3 adds reproducible product build boundaries and a persistent, crash-safe cache spanning whole parts and incremental assembly solves.

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.

2. Incremental assembly solve

Assembly state records component dependencies and public connector interfaces. Changes to geometry, connectors, connector bindings, material, or a nested assembly's public connector declaration propagate only through affected dependency paths. Unchanged component placements can be restored from cache, but every restored placement still passes constraint-residual verification before it is accepted.

3. PRT reuse

In read_only and read_write modes, calls to the same decorated @scad.part builder and build key reuse one runtime PRT with zero cache I/O. Concurrent same-key calls share one build. off and refresh preserve their explicit rebuild semantics.

Durable whole-part bundles remain the cross-run boundary. A newly decorated builder or later process restores an unchanged PRT from its validated bundle and creates fresh runtime graph provenance. Corrupt records or objects degrade to misses and are quarantined before recomputation.

4. Crash-safe content store and policy

The shared CAS uses canonical closed records, SHA-256 objects, atomic writes, per-key locks, stale-lock recovery, and object deduplication.

One CachePolicy controls part and assembly caching. Precedence is explicit API argument, environment, [tool.simplecadapi.cache], then defaults. The supported modes are off, read_only, read_write, and refresh.

5. Cache diagnostics CLI

The new simplecad-cache command emits stable JSON:

simplecad-cache status [--namespace NAME]
simplecad-cache verify [--namespace NAME] [--repair]
simplecad-cache prune [--apply]
simplecad-cache clear [--namespace NAME] --yes

Inspection and default prune are read-only. Explicit --repair, --apply, or --yes is required to mutate state. verify always validates record identity, object presence, byte length, and SHA-256. Namespace clearing preserves objects still referenced elsewhere.

6. Product-package CAD translation

Validated .scadpkg definition closures now translate to one editable FreeCAD document or one XCAF-backed AP242 STEP file. FreeCAD output uses a dependency-first definition registry so repeated parts, nested assemblies, occurrence names, solved placements, materials, connectors, constraints, grounding, revision, and content hashes survive in native document structure.

AP242 output uses AP242_MANAGED_MODEL_BASED_3D_ENGINEERING, preserves evaluated BREP and product occurrences, and writes materials, colors, density, plus named definition/occurrence properties. The property descriptions contain canonical sorted JSON for durable IDs and semantics. Feature history is not reconstructed as AP242 features; .scadpkg remains the canonical replayable artifact.

Product mesh export now shares one direct OpenCASCADE tessellation of evaluated BREP solids. OBJ and binary STL contain the same oriented triangles; OBJ keeps shared vertex indices while STL stores independent facets. The public accuracy controls are linear_deflection, angular_deflection_degrees, and relative. No remeshing dependency or Python 3.11 version gate is involved, so mesh export works across the package's complete supported Python range.

The scripts in examples/12_ap242_gmsh_volume_mesh/ build one .scadpkg and demonstrate every package exporter and translator as independent downstream commands: AP242 STEP, STL, OBJ, FCStd, FreeCAD, Fusion 360, and SolidWorks. The optional Gmsh stage continues from AP242 STEP to a tetrahedral .msh without adding Gmsh to the core runtime dependency set.

7. Native render crash isolation

On macOS, VTK 9.5's Cocoa offscreen backend can terminate the interpreter with SIGSEGV after repeated or concurrent render-window use. Inspection and SDK screenshot calls now tessellate in the caller, then render through one-shot VTK workers guarded by a cross-process lock. Completion markers distinguish a finished image from a partial native crash; incomplete workers retry, while a post-write teardown crash cannot terminate the modeling or test process.

8. Verification

Regression coverage exercises artifact schema closure, deterministic IDs and hashes, atomic concurrent write deduplication, corruption quarantine, all cache modes, in-process same-key PRT reuse, concurrent PRT build deduplication, cross-wrapper persistent part restore, interface invalidation, assembly definition DAGs, incremental dependency propagation, residual verification, nested connector changes, translator backend contracts, and generated API docs.

The nested package smoke writes and reads a native FreeCAD hierarchy with shared definitions and solved placements. AP242 round-trip checks the managed-model schema, five-level product explorer records, material and color data, plus seven named metadata property items for three definitions and four occurrences. The Gmsh smoke imports AP242 as one 3D volume and generates a non-empty tetrahedral mesh.