docs/skill: domain, discipline, workflow and guide pages follow the one-solid Part (and the open-solids rule)

DECISION: the skill pages that tell a model author how to structure a part, a notebook and an editor session say
what the SDK now does: a Part holds exactly one solid; several solids that exist together while building are
notebook values; a part notebook with one open solid has an implicit Part, with several it has no product.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
The multi-body Part was made so that the editor could hold several solids in one notebook with no assembly
constraint (pattern a tool, then cut). The owner judged it a wrong decision because it makes assembly hard; the
agreed analysis was that those solids are intermediate values of a notebook, not product items, so a Part is one
solid and the editor shows loose solids. The skill is what an agent reads before it writes a model: if it kept
recommending `make_part_rpart(bodies={...})` or "the runtime makes the Part from all open bodies", agents would
write code that now fails (or, worse, rely on a rule that no longer exists). The pages also have to tell the
author what to do instead, because the old advice was "keep them as bodies of the part".

WHAT CHANGES
- domains/part-modeling.md: "Multi-body parts" becomes "One Part, one solid" (refusal and its remedy: one Part per
  solid in an Assembly, or union / cut; part.body / part.bodies; the open-solids rule and the editor's "N open
  solids" / use_as_product; mass). The split-cut paragraph says the pieces are notebook values and several pieces
  cannot be one Part. The colour section uses set_body_appearance_rpart(part, color=...) (body id "body") and
  part.bodies[0] for the read-back.
- domains/assembly-and-product.md: a Part wraps one Solid; every Part can be placed, mated and given connectors;
  the "several bodies of one part" entry in "Do not use" is removed (there is no such thing).
- discipline/notebook-cell-design.md C9: one open solid -> implicit Part; several -> SeveralOpenBodiesError, choose
  the solid that is the part.
- discipline/mechanical-modeling.md, discipline/failure-and-repair.md ("Union returns multiple bodies"): the answer
  for "several bodies" is an Assembly of Parts, not a multi-body Part.
- docs/guides/notebook-runtime.md: the implicit-Part rule and the "A Part holds exactly one solid" bullet; the part
  definition is always profile simplecad-part-definition-2 with one solid.
- domains/editor-gui-features.md: "New body" leaves a loose solid beside the first ("N open solids"); use_as_product
  makes the Part from the chosen one.
- workflows/single-part-modeling/role-4-build.md: a split cut's pieces are one Part each in an Assembly.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Ni Jingzhe
2026-11-10 04:07:37 +08:00
parent 6441107ed3
commit fb50a97b07
8 changed files with 76 additions and 73 deletions
@@ -60,9 +60,8 @@ which claims cannot be made (see "Reporting failed repairs"). Interactive: the r
`union_rsolid` requires a one-manifold-`Solid` result and fails if it cannot
produce one. If the design is one body, use a contact or overlap that is
topologically capable of producing one solid, then recompute. If the design is
actually multiple parts, the answer is an assembly, not a union; if it is one
part whose bodies stay apart, make a multi-body part
(`make_part_rpart(bodies=...)`).
actually multiple parts, the answer is an assembly, not a union: a Part holds
exactly one solid, so make one Part per solid and put them in an Assembly.
### Fillet/chamfer failure
@@ -22,9 +22,10 @@ This document separates SDK contracts from mechanical design guidance.
- **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.
Several bodies of one part are deliberate: name them in
`make_part_rpart(bodies={...})`. Never leave stray solids out of the product,
or overlapping bodies, where one labeled product was intended.
A Part holds exactly one solid: several solids that belong together are one
Part per solid in an Assembly (identity placements if they only sit side by
side). Never leave stray solids (tools, construction) out of the product 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`.
@@ -86,15 +86,18 @@ depends only on the parameters it reads, so many parameters in one cell cost
nothing; a geometry line in the params cell would re-run with every parameter
change.
**C9. A part notebook (`kind = "part"`) needs no product cell: the runtime
makes the Part from its open bodies** (each public top-level solid no other cell
reads becomes a body named by its variable; the pieces of a split cut become
`<name>_1..n`). Write the product cell (last, id `scad.notebook_id()`) only for
connectors, a material, or to choose and name the bodies yourself:
`make_part_rpart(part_id=scad.notebook_id(), bodies={"base": base, "lid": lid})`;
solids left out of it (tools, construction) are not part of the product. An
assembly notebook ends with its layout cell. A family of parts uses
`scad.use(path, id=...)`.
**C9. A part notebook (`kind = "part"`) needs no product cell when it ends with
one open solid: the runtime makes the Part from it** (the one public top-level
solid no other cell reads). A Part holds exactly one solid. When several solids
are open at the end (a tool left next to its body, the pieces of a split cut) and
no cell makes the Part, there is no product: the run raises
`SeveralOpenBodiesError` naming them, and the editor draws them side by side
("N open solids"). Choose the one that is the part: write the product cell (last,
id `scad.notebook_id()`), also needed for connectors or a material:
`make_part_rpart(part_id=scad.notebook_id(), body=base)`; solids left out of it
(tools, construction) are not part of the product. Solids that are separate parts
are one Part each in an Assembly. An assembly notebook ends with its layout cell.
A family of parts uses `scad.use(path, id=...)`.
**C10. In an assembly notebook, one `scad.use(...)` per child, the mates in
their own cell, the solve in its own cell.** Do not carry the whole assembly
@@ -86,10 +86,11 @@ if __name__ == "__main__":
that no other cell reads and that no other such value was built from; a cell
that only makes construction geometry -- workplanes, wires, edges, e.g. a path
through the body's vertices -- does not count as reading it), with
the notebook id. One open body is a one-body Part (body id `"body"`); several
are the bodies of one Part, named by their variables (pieces `<name>_1..n`).
Write a `make_part_rpart` cell only to add connectors or a material, or to
choose and name the bodies yourself; it then wins. The headless run and the
the notebook id. One open body is the Part (body id `"body"`). A Part holds
exactly one solid, so with several open bodies the runtime does not choose:
see the bullet "A Part holds exactly one solid" below.
Write a `make_part_rpart` cell to add connectors or a material, or to
choose the solid that is the part; it then wins. The headless run and the
editor use the same rule (`runtime/projection.py`, `find_product`).
A notebook with no Part, Assembly or solid yet (a new one, or only sketches,
curves and workplanes so far) raises `NoProductYetError` (a
@@ -105,12 +106,15 @@ if __name__ == "__main__":
(`run_notebook(..., id=...)`, `scad.use(..., id=...)`, `sca run --id`);
cells read the id of their run with `scad.notebook_id()` — see
[Part families](notebook-composition-and-cache.md#part-families).
- **A part with several bodies** is one product:
`scad.make_part_rpart(part_id=scad.notebook_id(), bodies={"base": base, "lid": lid})`.
Each body keeps its own BRep, topology snapshot and tags in the package, whose
part definition then has profile `simplecad-part-definition-3` (an older SDK
refuses it instead of reading one body). One-body parts are unchanged.
The cell cache restores a multi-body part like any other value.
- **A Part holds exactly one solid.** A part notebook (`kind = "part"`) that ends
with one open solid needs no product cell. With several open solids (a tool
left next to the body it cut) and no cell making the Part, `find_product` raises
`SeveralOpenBodiesError` naming them (`sca run` and export stop with it; the
editor draws them side by side, "N open solids", and its `use_as_product` makes
the Part from the one you choose). Make the Part from the solid that is the part,
`scad.make_part_rpart(part_id=scad.notebook_id(), body=base)`, or make one Part
per solid and an Assembly of them. The part definition is always profile
`simplecad-part-definition-2` with one solid.
- **Parameters** are ordinary top-level variables. Overriding one replaces it,
and the cell that defines it does not run, so all variables of that cell
must be overridden together. Group parameters into cells by what changes
@@ -22,16 +22,15 @@ deliver `.scadpkg` packages.
- Monolithic single-body manufacturing intent: fuse with `union_rsolid` in
`domains/part-modeling.md`.
- Several bodies of one part that never move apart and are one BOM item
(a multi-body part, `make_part_rpart(bodies=...)`): `domains/part-modeling.md`.
- Export or translation decisions: they branch from the package in
`domains/export-and-translation.md`.
## Structure model
- `Part` wraps one `Solid` (or several named bodies, `bodies=`) plus identity
and optional material (`make_part_rpart`, `assign_material_rpart`,
`make_material_rmaterial`). In an assembly a multi-body part is one component;
its bodies are never placed or jointed separately.
- `Part` wraps exactly one `Solid` plus identity and optional material
(`make_part_rpart`, `assign_material_rpart`, `make_material_rmaterial`). Every
Part can be placed, mated and given connectors because it is one solid; several
solids that belong together are one Part each, as components of an Assembly
(identity placements when they only sit side by side).
- Display colour: `Material.color` is the default for every body of a part;
`set_body_appearance_rpart(part, body_id, color=..., opacity=..., name=...)`
overrides it per body for display (preview, package scene node
@@ -41,10 +41,11 @@ HOLE_DIAMETER = scad.var(name="hole_diameter", default=6.0, unit="mm", comment="
(`_x_by_tag`, `_x_by_geometry`) still runs and its form keeps the block; a pick the kernel cannot name (a body
without recorded history, `sca feature add` with geometry only) is still written that way.
- A new part notebook (`sca new NAME`, or the editor's "new") has no cells and a `kind = "part"` header: no product cell is written,
the runtime makes the Part from the open bodies (see `docs/guides/notebook-runtime.md`; a solid made with "New body"
is one more body of the same Part, not an assembly), so every new feature previews
and a deleted cell cannot leave the notebook without a product. Setting connectors (or "use as product" on a body
that is not the last) writes an explicit `make_part_rpart` cell, which then wins.
the runtime makes the Part from the one open body (see `docs/guides/notebook-runtime.md`), so every new feature previews
and a deleted cell cannot leave the notebook without a product. A solid made with "New body" stays beside the
first one as a loose solid (the header says "N open solids"); a Part holds exactly one solid, so with several open
solids there is no product until you choose: "use as product" on a body writes an explicit `make_part_rpart` cell
for it. Setting connectors (or "use as product" on a body that is not the last) also writes that cell, which then wins.
- Besides the curated features (box, hole, pull face, extrude of a sketch ...), every SDK and standard-library operation
the forms can offer is a feature of its own, `op.<operation>` (`# gui: {"spec": "op.make_spur_gear_rsolid", ...}`): the
form is made from the operation's signature (`sca ops NAME`), and the cell is one plain call
+32 -36
View File
@@ -2,17 +2,16 @@
Model one physical mechanical part with the core geometry API: primitives,
profiles, 3D features, booleans, detail features, and transforms. A part is
usually one solid body; it may hold several named bodies (see "Multi-body
parts" below).
one solid body: a Part holds exactly one solid (see "One Part, one solid"
below).
**Read when:** the deliverable is one physical part (one body or several bodies kept apart in one product item), or an
**Read when:** the deliverable is one physical part (one solid body), or an
existing part source needs a geometry edit (Role 4 of `workflows/single-part-modeling.md`).
## Use when
- The deliverable is one physical part that will be manufactured or exported as
one product item: normally a single solid body, or several bodies of one part
(a case and its lid modelled side by side, the pieces of a split cut).
one product item: a single solid body.
- The request names brackets, plates, enclosures bodies, shafts, spacers,
bosses, flanges, blades, or any monolithic part geometry.
- An existing part source needs a geometry edit: new features, dimension
@@ -40,8 +39,7 @@ existing part source needs a geometry edit (Role 4 of `workflows/single-part-mod
## Outputs
- A positive-volume, closed `Solid`, or a `Part` via `make_part_rpart` when the
product boundary is needed (`body=solid`, or `bodies={"base": base, "lid": lid}`
for a multi-body part).
product boundary is needed (`body=solid`).
- Semantic tags on mating/role surfaces and numeric facts in metadata.
- A replayable `GraphSession` model JSON when the flow must be replayable or
interchange-exported.
@@ -101,10 +99,11 @@ consult their own documentation before the first call.
`list[Solid]` ordered by centroid (x, then y, then z); it never drops a piece.
Pass `on_split="error"` where exactly one Solid is required. A tool that
consumes the body still raises. `cut_rsolid_list(base, tools)` always returns
a list (empty when nothing is left). The pieces become bodies of the part:
`make_part_rpart(part_id=..., body=pieces)` gives `body_1 .. body_n`,
`bodies={"bar": pieces}` gives `bar_1 .. bar_n`. A body is one closed volume:
OCCT and STEP have no valid "one solid with several lumps".
a list (empty when nothing is left). The pieces are notebook values: a Part holds one solid, so
`make_part_rpart(part_id=..., body=pieces)` with several pieces is an error;
make one Part per piece in an Assembly, or union the pieces if they are one
body. A solid is one closed volume: OCCT and STEP have no valid "one solid
with several lumps".
- The pieces are a `scad.Pieces` (a list) and keep flowing: an operation that
takes one shape (`translate_shape`, `shell_rsolid`, a further `cut_rsolid(pieces, tool)`,
fillet, chamfer ...) runs on every piece and returns `Pieces` in the same order.
@@ -113,36 +112,33 @@ consult their own documentation before the first call.
`union_rsolid(pieces)` joins them. A plain list passed to `cut_rsolid` is still
base-then-tools.
## Multi-body parts
## One Part, one solid
- `make_part_rpart(part_id=scad.notebook_id(), bodies={"base": base, "lid": lid})`
keeps several solids apart in one Part. The dict order is the body order;
body ids are identifiers, unique within the part.
- Read them with `part.bodies` (`Body.body_id`, `Body.solid`, `Body.name`),
`part.get_body("lid")`, `part.body_ids()`. `part.body` is the Solid of a
one-body part (id `"body"`) and raises `TypeError` on a multi-body part.
- Bodies have no placements, joints or connectors: anything that moves, or is
bought or made separately, is a component of an assembly
(`domains/assembly-and-product.md`). Connectors on a multi-body part are
refused for now.
- Tool and construction solids are not bodies: leave them as notebook values
and do not pass them to the Part.
- Overlapping bodies are allowed but warned (`BodyOverlapWarning` when the
definition is built); check with `inspect_body_overlaps_rlist(part)`. Union
bodies that are one piece of material.
- Mass per body and in total: `measure_part_mass_rmassreport(part)` (density
from the part's material, or `density=`).
- The preview draws one node per body (`node/<part>/body:<id>`); STEP export
writes one product holding every body.
- `make_part_rpart(part_id=scad.notebook_id(), body=bracket)`. A Part is the unit
an assembly places, mates and gives connectors to, so it holds exactly one
solid. Several solids (`bodies=`, a list of several pieces) are refused with a
ValueError: make one Part per solid and put them in an Assembly (identity
placements when they only sit together), or union / cut them into one solid.
- `part.body` is the Solid; `part.bodies` is that body as a one-element tuple
(`Body.body_id` is `"body"`, `Body.solid`, `Body.name`).
- Solids that sit side by side while the model is built (a tool next to the body
it cuts, the tools of a pattern before the cut, the pieces of a split cut) are
ordinary notebook values, not a Part. A part notebook that ends with one open
solid needs no product cell; with several open solids and no cell making the
Part there is no product (`SeveralOpenBodiesError` names them): make the Part
from the solid that is the part. The editor draws the open solids side by side
("N open solids") and its `use_as_product` makes the Part from the chosen one.
- Mass: `measure_part_mass_rmassreport(part)` (density from the part's material,
or `density=`).
## Colours and names for people
- A body's display colour, opacity and name are one recorded operation:
`part = scad.set_body_appearance_rpart(part, "lid", color=(0.9, 0.3, 0.2), opacity=0.6, name="Lid")`
(a one-body part: leave `body_id` out, it is `"body"`). Colours are RGB floats
- A part's display colour, opacity and name are one recorded operation:
`part = scad.set_body_appearance_rpart(part, color=(0.9, 0.3, 0.2), opacity=0.6, name="Lid")`
(the body id is `"body"`, the default). Colours are RGB floats
in [0, 1], linear like `Material.color`. `None` keeps a value, `reset=True`
clears all three first. Read back with `part.get_body("lid").color` / `.opacity` / `.name`.
- The material colour is the default; a body colour overrides it for display
clears all three first. Read back with `part.bodies[0].color` / `.opacity` / `.name`.
- The material colour is the default; the body colour overrides it for display
only (preview, package scene, STEP surface colour of that solid). Mass and
density never read it. STEP writes the colour and the body name, not the opacity.
- Name a face, an edge or a vertex with a tag; there is no second naming system:
@@ -34,8 +34,8 @@ For the current stage:
from a named base solid, create each additive boss/rib/flange or
subtractive bore/pocket/opening as a separately named solid or tool, then
use `union_rsolid`, `cut_rsolid`, or `intersect_rsolid` to obtain the next
single Solid (a cut that splits the body returns its pieces as a list:
keep them as bodies of the part only when that is the design). Repeat construct-feature -> Boolean -> verify for each
single Solid (a cut that splits the body returns its pieces as a list;
a Part holds one solid, so one Part per piece in an Assembly when that is the design). Repeat construct-feature -> Boolean -> verify for each
required feature group; ensure intentional positive overlap for unions
and tool overshoot for cuts. Do not assemble an opaque final shape in one
expression.