Files
make-cad/docs/updates/2.0.2.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

107 lines
5.4 KiB
Markdown

# SimpleCADAPI 2.0.2 Update Notes
[Chinese](2.0.2.zh-CN.md)
> **Experimental release notice:** The capabilities described below are still
> experimental. Breaking changes may be introduced in later releases, so this
> version is not recommended for immediate production use.
SimpleCADAPI 2.0.2 expands the project from an OCP-native geometry API into an
end-to-end, inspectable CAD workflow. The release covers model creation,
parameter and tolerance reasoning, replayable persistence, cross-CAD
translation, browser inspection, assembly verification, and STEP reverse
engineering.
## 1. Cross-CAD Translation
Canonical model JSON can be translated into automation scripts for FreeCAD,
Fusion 360, and SolidWorks. The FreeCAD backend can also write an editable
`.FCStd` document when FreeCAD/FreeCADCmd is available, preserving sketches,
features, parts, assemblies, links, and source selections where supported.
Fusion 360 exports target its Python automation environment. The SolidWorks
backend emits automation scripts and can drive a STEP export via COM. A single
parameterized SimpleCAD model can therefore serve multiple downstream CAD
systems without maintaining separate scripts.
## 2. Browser 3-D Viewer
The `viewer/` application opens generated `.scene.zip` packages without
importing Python or OpenCascade. It renders GLB geometry and CAD edges, provides
orbit/pan/zoom inspection, exposes an assembly/component tree with per-
occurrence visibility controls, and lets users select faces, edges, and vertices
to inspect measured properties and semantic/topological identity.
The Features view displays the replayable operation tree, parameters, output
counts, tags, and embedded source code, including the originating call and
highlighted source range. Scene packages also validate resource sizes and
SHA-256 metadata before loading referenced assets.
## 3. Structured Persistence, Replay, and Source Mapping
Modeling work recorded through `@model` or `GraphSession` can be exported as
canonical model/session JSON and replayed deterministically with
`import_model_json(...)` and `replay_model_json(...)`. A scene export can
package `scene.json`, `model/model.json`, embedded project-relative Python
sources, and GLB/entity assets into one portable artifact.
Every recorded operation captures best-effort source provenance. A feature-tree
node can be traced to the Python file, function call, assignment target, and
line range that produced it. This provides a foundation for automation,
collaboration, regression testing, and versioned model review.
## 4. Physical Units and Tolerance Analysis
Unit-aware variables preserve declared units in the model graph while converting
CAD operations to canonical millimeters and degrees. Expressions infer
dimensions across arithmetic and supported trigonometric operations, reject
incompatible combinations, and retain their parameter graph for replay.
Manufacturing tolerances can be propagated through dimension chains, analyzed
with nominal and bound results, and checked against explicit requirements. The
result supports unit conversion, dimensional chains, and assembly tolerance
studies without reducing the model to unexplained bare numbers.
## 5. Standard Mechanical Parts and Gear Performance
The standard library includes parameterized bolts and nuts, ball-bearing
assemblies, roller-chain sprockets, spur/helical/herringbone gears, internal
ring gears, racks, cycloidal discs, and bevel gears. These factories return
ordinary SimpleCAD shapes or assemblies, so results can be transformed,
tagged, combined, serialized, translated, and exported like custom geometry.
Gear construction and standard-library graph tracking were also optimized;
representative gear workloads are reported to complete in about one-third of
their previous time.
## 6. Assemblies, Meshes, and Collision Verification
Parts, components, connectors, placements, and assemblies can be persisted as a
structured product tree with fixed, revolute, prismatic, gear, belt, and
rack-and-pinion constraints. Constraint solving and residual inspection make
assembly relationships measurable. Render meshes and edge meshes are generated
for scene assets and downstream inspection.
The optional `simplecadapi[collision]` extra adds static, current-pose mesh
penetration checks through `python-fcl`, with configurable component scopes,
penetration tolerances, contact reporting, and non-fatal backend warnings. This
first verifier checks mesh contact penetration; it does not yet solve motion or
detect every complete-containment case.
## 7. STEP Inspection and Reverse Engineering
The `simplecad-brep` CLI and `simplecadapi.inverse_engineer.brep` API inspect
STEP BREP files and report volumes, surface areas, bounds, topology counts, and
geometric primitive labels. Bidirectional comparisons can apply a hard gate
based on geometric point-set equality and a geometry-labelled face-edge-vertex
incidence graph, rather than relying only on a volume delta.
The toolkit also renders consistent STEP views and compares sampled physical
slices with XOR overlays. These diagnostics help verify whether a reconstructed
part agrees with the original in both geometry and topology.
## Related Documentation
- [STEP BREP reverse-engineering guide](../skill/references/inspect/brep-reverse-engineering.md)
- [Browser viewer README](../../viewer/README.md)
- [Core serialization and replay documentation](../skill/references/docs/core/serialization/README.md)