Files
make-cad/docs/skill/references/discipline/mechanical-modeling.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

3.6 KiB

Discipline: Mechanical Modeling

How to choose a construction strategy before selecting SimpleCADAPI operations. This document separates SDK contracts from mechanical design guidance.

Evidence labels

  • SDK contract means behavior verified in the public API or generated API documentation.
  • Modeling guidance is an engineering recommendation. The SDK does not infer manufacturing intent, strength, fit, or optimal feature order from it.

Decide the construction before writing geometry

  • Make the spec's controlling dimensions direct named parameters. Profile-driven shapes get one closed profile plus extrude/revolve/sweep/ loft; block-and-feature parts get a base solid plus subtractive features. Choose whichever lets the user's dimensions appear as parameters instead of derived values.
  • Decide part vs assembly before modeling. Bodies that are separately manufactured, purchased, or movable belong in an assembly with connectors and placements; monolithic manufacturing intent gets a single fused solid. Never leave a multi-body result where one labeled product was intended.
  • Pick the origin and orientation from the functional datum — the mating interface, mounting plane, or symmetry axis — not from wherever the first primitive happened to land. See datums-and-coordinate-systems.md.
  • Model the part as a sequence of intentional operations, not one opaque final shape: each feature is a named step, so a failed operation points at exactly one feature and a parameter change touches one obvious place.

Build from low to high dimensionality

Vertex / Edge / Wire / Face profiles
→ Solid features: extrude, revolve, sweep, loft
→ booleans for openings and merged bodies
→ detail: fillets, chamfers, shells last

SDK contract: keep replayable modeling operations in public API calls such as make_circle_rface, extrude_rsolid, cut_rsolid, and fillet_rsolid; use keyword arguments for documented public APIs. The SDK records graph operations when a GraphSession is active, but it does not require every local helper to be a one-line public call.

Distinguish physical roles

  • Monolithic part: one manufactured body, one fused solid.
  • Independent manufactured part: own file, own Part, placed in the assembly.
  • Purchased/standard component: stdlib factory or imported geometry with measured interfaces; never re-modeled by hand when a factory exists.
  • Motion component: interfaces expressed as connectors; relations as declarative constraints (revolute/prismatic/gear/rack-pinion/belt).

Parameters are design intent

  • Every meaningful dimension is a named parameter in the file that consumes it; no magic numbers buried inside geometry calls.
  • Exposed tunable parameters are var()/Var declarations (optionally with unit and tolerance); everything else is a plain constant in place.
  • Numbers that are the result of computation (centers, radii from fits, cumulative offsets) are computed, never freehanded.

Sanity-check proportions before generating

Compare the expected bounding box against the real-world object, wall thickness against overall size, feature positions against edges and neighbors. Order-of-magnitude and collision errors pass geometric validation and fail only at review — catch them in the brief.

What geometry cannot tell you

A valid, closed, positive-volume solid says nothing about strength, fatigue, thermal behavior, vibration, tolerance compliance, or regulatory fitness. Do not claim any of those without the corresponding analysis having actually run. See manufacturing-boundaries.md.