simplecadapi 2.0.0b2__tar.gz → 2.0.0b4__tar.gz

{simplecadapi-2.0.0b2 → simplecadapi-2.0.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.0.0b2
+Version: 2.0.0b4
 Summary: A simplified OCP-native CAD modeling Python API
 Project-URL: Homepage, https://github.com/NiJingzhe/SimpleCADAPI
 Project-URL: Repository, https://github.com/NiJingzhe/SimpleCADAPI
@@ -358,10 +358,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.10
-Requires-Dist: cadquery-ocp>=7.8.1
+Requires-Python: <3.14,>=3.10
+Requires-Dist: cadquery-ocp>=7.9.3.1
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: rich>=14.0.0
 Provides-Extra: dev
@@ -375,192 +376,143 @@ Description-Content-Type: text/markdown
 
 # SimpleCADAPI
 
-SimpleCADAPI is an OCP-native imperative CAD modeling Python package. It keeps the 1.x-style functional API while adding v2 graph recording, expression parameters, and replayable model JSON workflows.
+SimpleCADAPI is an OCP-native Python SDK for building CAD models with clear,
+functional operations and replayable model graphs. It wraps OpenCascade geometry
+in a compact public API for creating solids, applying features, tagging semantic
+intent, querying topology, exporting manufacturing files, and translating recorded
+models into FreeCAD workflows.
 
-## README Scope
+Current beta: `simplecadapi==2.0.0b4`.
 
-This README only covers package-level capabilities, installation methods, publishing/packaging workflows, and Skills usage instructions.
-Experimental scripts and temporary modeling examples are not included as formal documentation.
+## What It Provides
 
-## Package Installation (Python Package Managers)
+- OCP-native shape types: `Vertex`, `Edge`, `Wire`, `Face`, and `Solid`.
+- Functional modeling operations for primitives, profiles, extrude, revolve,
+  loft, sweep, booleans, transforms, patterns, fillets, chamfers, and shells.
+- Replayable modeling with `GraphSession`, `export_model_json(...)`,
+  `import_model_json(...)`, and `replay_model_json(...)`.
+- Expression parameters with `var(...)`, arithmetic expressions, and serialized
+  expression graphs.
+- QL selectors for geometry grounding, topology queries, and stable feature
+  selections.
+- Semantic tags through `apply_tag(shape, tag)` and `list_tags(shape)`.
+- STEP/STL export and FreeCAD translation helpers for script or `.FCStd` output.
 
-Current package name: `simplecadapi` (see `pyproject.toml` for the version).
-
-### Method A: Install from package repository with pip
+## Install
 
 ```bash
 pip install simplecadapi
 ```
 
-Optional development dependencies:
-
-```bash
-pip install "simplecadapi[dev]"
-```
-
-### Method B: Install with uv
-
-Install in the current virtual environment:
-
-```bash
-uv pip install simplecadapi
-```
-
-Add as a project dependency in `pyproject.toml`:
+With `uv`:
 
 ```bash
 uv add simplecadapi
 ```
 
-### Method C: Install from local build artifacts
-
-Build a local wheel/sdist first if you want to install from local artifacts:
+For local development from this repository:
 
 ```bash
-uv build
+uv sync --group dev
 ```
 
-## Quick Verification of Installation
+## Quick Start
 
 ```python
-import simplecadapi as scad
-
-box = scad.make_box_rsolid(10.0, 20.0, 30.0)
-scad.export_stl(box, "example_box.stl")
-scad.export_step(box, "example_box.step")
-```
-
-## How to Package SDK Skills
+from pathlib import Path
 
-This project provides the `skill-pack` CLI for generating lightweight SDK reference skills: **No built-in SDK source code**, focused on API and architecture descriptions.
-
-### 1) Packaging Command
-
-Execute in the repository root directory:
-
-```bash
-uv run skill-pack --refresh-docs --archive --skill-name simplecadapi
-```
-
-Common parameters:
-
-- `--output-root <dir>`: Output directory (default `./skills`)
-- `--package-name <pkg>`: Runtime installation package name (default reads from `project.name`)
-- `--package-version <ver>`: Runtime installation version (default reads from `project.version`)
-- `--no-clean`: Do not clean existing output directory
-- `--archive`: Additionally generate `<skill-name>.tar.gz`
+import simplecadapi as scad
 
-### 2) Packaging Result Structure
+out = Path("out")
+out.mkdir(exist_ok=True)
 
-After packaging, you will get a directory similar to:
+base = scad.make_box_rsolid(60.0, 36.0, 8.0, bottom_face_center=(0.0, 0.0, 0.0))
+hole = scad.make_cylinder_rsolid(5.0, 14.0, bottom_face_center=(0.0, 0.0, -3.0))
+slot = scad.make_box_rsolid(18.0, 8.0, 14.0, bottom_face_center=(14.0, 0.0, -3.0))
 
-- `skills/simplecadapi/SKILL.md`
-- `skills/simplecadapi/references/`
-- `skills/simplecadapi/references/docs/api/`
-- `skills/simplecadapi/references/docs/core/`
+part = scad.cut_rsolid(base, hole, slot)
+boss = scad.make_cylinder_rsolid(8.0, 7.0, bottom_face_center=(-18.0, 0.0, 8.0))
+part = scad.union_rsolid(part, boss)
+part = scad.apply_tag(part, "role.demo.bracket")
 
-### 3) Read the SDK skill
+print("volume", round(part.get_volume(), 3))
+print("faces", len(part.get_faces()))
+print("tags", scad.list_tags(part))
 
-```bash
-cd skills/simplecadapi
+scad.export_step(part, str(out / "bracket.step"))
+scad.export_stl(part, str(out / "bracket.stl"))
 ```
 
-Key entry points:
-
-- `skills/simplecadapi/SKILL.md`
-- `skills/simplecadapi/references/SDK_OVERVIEW.md`
-- `skills/simplecadapi/references/SDK_SURFACES.md`
-- `skills/simplecadapi/references/V2_MODELING_WORKFLOWS.md`
-- `skills/simplecadapi/references/SDK_PACKAGE_SUMMARY.md`
-- `skills/simplecadapi/references/docs/api/README.md`
-- `skills/simplecadapi/references/docs/core/README.md`
+## Replayable Modeling
 
-### 4) Preferred v2 replay workflow
+Use `GraphSession` when a model should be inspectable, serializable, replayable,
+or translated into another CAD environment.
 
 ```python
-from simplecadapi import GraphSession, export_model_json, replay_model_json
-
-with GraphSession() as session:
-    ...
-
-model_json = export_model_json(session)
-rebuilt = replay_model_json(model_json)
-print(len(rebuilt))
-```
-
-## Serialization and Replay Docs
-
-For detailed operation-by-operation JSON formats and replay behavior, see:
-
-- [`docs/core/serialization/README.md`](docs/core/serialization/README.md)
-- [`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
-- [`examples/07_serialization_operation_tree.py`](examples/07_serialization_operation_tree.py)
-
-## Auto Tools
-
-The project includes 4 main CLIs:
-
-- `auto-docs-gen`: Generate `docs/api/` documentation from the public API source surface
-- `make-export`: Update imports/exports in `src/simplecadapi/__init__.py`
-- `evolve`: Extract functions from scripts for repository-managed evolve modules
-- `skill-pack`: Package thin SDK skill (documentation only)
-
-Examples:
-
-```bash
-uv run make-export --dry-run
-uv run auto-docs-gen
-uv run evolve path/to/your_case.py
-uv run skill-pack --refresh-docs --archive
-```
-
-## RAGFlow Documentation Sync
-
-`scripts/sync_ragflow_docs.py` is used to incrementally sync Markdown files under `docs/` to the specified RAGFlow dataset, chunked by H2 headings; the document's `chunk_method` is set to `manual`.
-
-Prepare the environment:
-
-```bash
-.venv/bin/python -m pip install ragflow-sdk
-```
-
-It is recommended to use `.env` (already added to `.gitignore`):
-
-```bash
-RAGFLOW_API_KEY=your_key_here
-RAGFLOW_BASE_URL=http://localhost
-RAGFLOW_DATASET_NAME=SimpleCADAPI
+import simplecadapi as scad
+from simplecadapi import ql as Q
+
+with scad.GraphSession() as session:
+    body = scad.make_box_rsolid(40.0, 24.0, 10.0, bottom_face_center=(0.0, 0.0, 0.0))
+    cutter = scad.make_cylinder_rsolid(4.0, 16.0, bottom_face_center=(0.0, 0.0, -3.0))
+    drilled = scad.cut_rsolid(body, cutter)
+
+    bottom_circle = (
+        Q.edges()
+        .where(Q.curve_type("circle"))
+        .order_by(Q.center_axis("z"))
+        .take(1)
+        .exactly(1)
+    )
+    final = scad.chamfer_rsolid(drilled, bottom_circle, 0.6)
+
+model_json = scad.export_model_json(session)
+rebuilt = scad.replay_model_json(model_json)
+
+print("recorded_nodes", session.graph.node_count)
+print("replayed_outputs", len(rebuilt))
 ```
 
-Run the sync:
+## Modeling Mental Model
+
+- Start from design intent: reference axes, critical profiles, and the features
+  that produce the final solid.
+- Build from lower-dimensional geometry to higher-dimensional geometry: profile
+  wires/faces first, then solid features such as extrude, revolve, loft, and
+  sweep.
+- Keep operations functional. Create new values with public functions such as
+  `make_rectangle_rface(...)`, `extrude_rsolid(...)`, `cut_rsolid(...)`, and
+  `fillet_rsolid(...)`.
+- Use tags for semantic intent and selection anchors, for example
+  `role.mounting.surface`, `anchor.datum.primary`, or `group.fasteners`.
+- Store numeric and geometric facts in metadata or graph payloads, not in tags.
+- Use QL to ground selections by geometry facts rather than relying on topology
+  iteration order.
+- When an indexed topology pick is intentional, pass the index to the plural
+  child-geometry getter, such as `get_edges(index)`, `get_faces(index)`,
+  `get_wires(index)`, or `get_vertices(index)`, so replayable graph workflows
+  preserve the pick as a geo select node.
+- Use model JSON as the interchange boundary for replay, tests, and FreeCAD
+  translation.
+
+## FreeCAD Translation
+
+Recorded model JSON can be translated into a FreeCAD Python script:
 
-```bash
-set -a && source .env && set +a
-.venv/bin/python scripts/sync_ragflow_docs.py --create-dataset
+```python
+script = scad.translate_model_json_to_freecad_script(model_json)
 ```
 
-Common parameters:
-
-- `--dataset-id` / `RAGFLOW_DATASET_ID`: Directly specify the dataset ID (avoid name conflicts)
-- `--delete-removed`: Delete documents that have been removed locally
-- `--dry-run`: Only preview changes without executing writes
-- `--progress-interval N`: Print progress every N documents
-
-## Development and Testing
-
-Local development installation (editable):
+If FreeCAD or FreeCADCmd is available, the same model JSON can be written as an
+`.FCStd` file:
 
-```bash
-uv pip install -e ".[dev]"
+```python
+scad.translate_model_json_to_fcstd(model_json, "bracket.FCStd")
 ```
 
-Run unit tests:
+## Examples
 
-```bash
-uv run python -m unittest test/test_all_features.py
-```
-
-Run examples:
+Run examples from the source checkout:
 
 ```bash
 uv run python examples/01_basic_modeling.py
@@ -571,18 +523,23 @@ uv run python examples/06_parametric_gear_model.py
 uv run python examples/07_serialization_operation_tree.py
 ```
 
-## Core Design Constraints (Brief)
+## Documentation
 
-- API functions uniformly use `snake_case` and reflect return types in function names (e.g., `*_rsolid`, `*_rwire`).
-- Core types are OCP-native wrappers and are kept as stable as possible; functionality is extended by adding new functions (Open-Closed Principle).
-- Support `SimpleWorkplane` context for local coordinate modeling.
-- Export interfaces support single entities, multiple entities, and nested list inputs.
+- Public API reference: [`docs/api/`](docs/api/)
+- Core type and modeling notes: [`docs/core/`](docs/core/)
+- Serialization and replay details:
+  [`docs/core/serialization/README.md`](docs/core/serialization/README.md)
+- Operation graph JSON spec:
+  [`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
 
-## Documentation Entry Points
+## Development
 
-- API documentation: `docs/api/`
-- Core documentation: `docs/core/`
+```bash
+uv sync --group dev
+uv run python -m pytest test tests
+python3 -m compileall src/simplecadapi
+```
 
 ## License
 
-MIT, see `LICENSE`.
+MIT, see [`LICENSE`](LICENSE).

simplecadapi-2.0.0b4/README.md

@@ -0,0 +1,169 @@
+# SimpleCADAPI
+
+SimpleCADAPI is an OCP-native Python SDK for building CAD models with clear,
+functional operations and replayable model graphs. It wraps OpenCascade geometry
+in a compact public API for creating solids, applying features, tagging semantic
+intent, querying topology, exporting manufacturing files, and translating recorded
+models into FreeCAD workflows.
+
+Current beta: `simplecadapi==2.0.0b4`.
+
+## What It Provides
+
+- OCP-native shape types: `Vertex`, `Edge`, `Wire`, `Face`, and `Solid`.
+- Functional modeling operations for primitives, profiles, extrude, revolve,
+  loft, sweep, booleans, transforms, patterns, fillets, chamfers, and shells.
+- Replayable modeling with `GraphSession`, `export_model_json(...)`,
+  `import_model_json(...)`, and `replay_model_json(...)`.
+- Expression parameters with `var(...)`, arithmetic expressions, and serialized
+  expression graphs.
+- QL selectors for geometry grounding, topology queries, and stable feature
+  selections.
+- Semantic tags through `apply_tag(shape, tag)` and `list_tags(shape)`.
+- STEP/STL export and FreeCAD translation helpers for script or `.FCStd` output.
+
+## Install
+
+```bash
+pip install simplecadapi
+```
+
+With `uv`:
+
+```bash
+uv add simplecadapi
+```
+
+For local development from this repository:
+
+```bash
+uv sync --group dev
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+import simplecadapi as scad
+
+out = Path("out")
+out.mkdir(exist_ok=True)
+
+base = scad.make_box_rsolid(60.0, 36.0, 8.0, bottom_face_center=(0.0, 0.0, 0.0))
+hole = scad.make_cylinder_rsolid(5.0, 14.0, bottom_face_center=(0.0, 0.0, -3.0))
+slot = scad.make_box_rsolid(18.0, 8.0, 14.0, bottom_face_center=(14.0, 0.0, -3.0))
+
+part = scad.cut_rsolid(base, hole, slot)
+boss = scad.make_cylinder_rsolid(8.0, 7.0, bottom_face_center=(-18.0, 0.0, 8.0))
+part = scad.union_rsolid(part, boss)
+part = scad.apply_tag(part, "role.demo.bracket")
+
+print("volume", round(part.get_volume(), 3))
+print("faces", len(part.get_faces()))
+print("tags", scad.list_tags(part))
+
+scad.export_step(part, str(out / "bracket.step"))
+scad.export_stl(part, str(out / "bracket.stl"))
+```
+
+## Replayable Modeling
+
+Use `GraphSession` when a model should be inspectable, serializable, replayable,
+or translated into another CAD environment.
+
+```python
+import simplecadapi as scad
+from simplecadapi import ql as Q
+
+with scad.GraphSession() as session:
+    body = scad.make_box_rsolid(40.0, 24.0, 10.0, bottom_face_center=(0.0, 0.0, 0.0))
+    cutter = scad.make_cylinder_rsolid(4.0, 16.0, bottom_face_center=(0.0, 0.0, -3.0))
+    drilled = scad.cut_rsolid(body, cutter)
+
+    bottom_circle = (
+        Q.edges()
+        .where(Q.curve_type("circle"))
+        .order_by(Q.center_axis("z"))
+        .take(1)
+        .exactly(1)
+    )
+    final = scad.chamfer_rsolid(drilled, bottom_circle, 0.6)
+
+model_json = scad.export_model_json(session)
+rebuilt = scad.replay_model_json(model_json)
+
+print("recorded_nodes", session.graph.node_count)
+print("replayed_outputs", len(rebuilt))
+```
+
+## Modeling Mental Model
+
+- Start from design intent: reference axes, critical profiles, and the features
+  that produce the final solid.
+- Build from lower-dimensional geometry to higher-dimensional geometry: profile
+  wires/faces first, then solid features such as extrude, revolve, loft, and
+  sweep.
+- Keep operations functional. Create new values with public functions such as
+  `make_rectangle_rface(...)`, `extrude_rsolid(...)`, `cut_rsolid(...)`, and
+  `fillet_rsolid(...)`.
+- Use tags for semantic intent and selection anchors, for example
+  `role.mounting.surface`, `anchor.datum.primary`, or `group.fasteners`.
+- Store numeric and geometric facts in metadata or graph payloads, not in tags.
+- Use QL to ground selections by geometry facts rather than relying on topology
+  iteration order.
+- When an indexed topology pick is intentional, pass the index to the plural
+  child-geometry getter, such as `get_edges(index)`, `get_faces(index)`,
+  `get_wires(index)`, or `get_vertices(index)`, so replayable graph workflows
+  preserve the pick as a geo select node.
+- Use model JSON as the interchange boundary for replay, tests, and FreeCAD
+  translation.
+
+## FreeCAD Translation
+
+Recorded model JSON can be translated into a FreeCAD Python script:
+
+```python
+script = scad.translate_model_json_to_freecad_script(model_json)
+```
+
+If FreeCAD or FreeCADCmd is available, the same model JSON can be written as an
+`.FCStd` file:
+
+```python
+scad.translate_model_json_to_fcstd(model_json, "bracket.FCStd")
+```
+
+## Examples
+
+Run examples from the source checkout:
+
+```bash
+uv run python examples/01_basic_modeling.py
+uv run python examples/02_graph_replay.py
+uv run python examples/03_expressions.py
+uv run python examples/05_loft_sweep_revolve.py
+uv run python examples/06_parametric_gear_model.py
+uv run python examples/07_serialization_operation_tree.py
+```
+
+## Documentation
+
+- Public API reference: [`docs/api/`](docs/api/)
+- Core type and modeling notes: [`docs/core/`](docs/core/)
+- Serialization and replay details:
+  [`docs/core/serialization/README.md`](docs/core/serialization/README.md)
+- Operation graph JSON spec:
+  [`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
+
+## Development
+
+```bash
+uv sync --group dev
+uv run python -m pytest test tests
+python3 -m compileall src/simplecadapi
+```
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).

{simplecadapi-2.0.0b2 → simplecadapi-2.0.0b4}/docs/api/README.md

@@ -1,6 +1,6 @@
 # SimpleCAD API Index
 
-This index includes generated docs for the public SimpleCAD API surface, including v2 graph, expression, and model JSON workflows.
+This index includes generated docs for the public SimpleCAD API surface, including geometry operations, graph/model JSON workflows, expressions, QL, and export helpers.
 
 ## Import Surfaces
 
@@ -56,8 +56,8 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 
 ## Boolean Operations
 
-- [cut_rsolidlist](cut_rsolidlist.md) *(from operations.py)* `top-level`
-- [intersect_rsolidlist](intersect_rsolidlist.md) *(from operations.py)* `top-level`
+- [cut_rsolid](cut_rsolid.md) *(from operations.py)* `top-level`
+- [intersect_rsolid](intersect_rsolid.md) *(from operations.py)* `top-level`
 - [union_rsolid](union_rsolid.md) *(from operations.py)* `top-level`
 
 ## Export
@@ -65,6 +65,11 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 - [export_step](export_step.md) *(from operations.py)* `top-level`
 - [export_stl](export_stl.md) *(from operations.py)* `top-level`
 
+## FreeCAD Translation
+
+- [translate_model_json_to_fcstd](translate_model_json_to_fcstd.md) *(from freecad_translator.py)* `top-level`
+- [translate_model_json_to_freecad_script](translate_model_json_to_freecad_script.md) *(from freecad_translator.py)* `top-level`
+
 ## Modeling Graph and Replay
 
 - [GraphSession](GraphSession.md) *(from graph.py)* `top-level`

simplecadapi-2.0.0b2/docs/api/cut_rsolidlist.md → simplecadapi-2.0.0b4/docs/api/cut_rsolid.md

@@ -1,16 +1,16 @@
-# cut_rsolidlist
+# cut_rsolid
 
 ## API Definition
 
 ```python
-def cut_rsolidlist(*solids: Union[Solid, Sequence[Solid]], skip_non_intersecting: bool = True) -> Solid
+def cut_rsolid(*solids: Union[Solid, Sequence[Solid]], skip_non_intersecting: bool = True) -> Solid
 ```
 
 *Source: operations.py*
 
 ## Import Surface
 
-- top-level: `from simplecadapi import cut_rsolidlist`
+- top-level: `from simplecadapi import cut_rsolid`
 
 ## Description
 

simplecadapi-2.0.0b2/docs/api/intersect_rsolidlist.md → simplecadapi-2.0.0b4/docs/api/intersect_rsolid.md

@@ -1,16 +1,16 @@
-# intersect_rsolidlist
+# intersect_rsolid
 
 ## API Definition
 
 ```python
-def intersect_rsolidlist(*solids: Union[Solid, Sequence[Solid]]) -> Solid
+def intersect_rsolid(*solids: Union[Solid, Sequence[Solid]]) -> Solid
 ```
 
 *Source: operations.py*
 
 ## Import Surface
 
-- top-level: `from simplecadapi import intersect_rsolidlist`
+- top-level: `from simplecadapi import intersect_rsolid`
 
 ## Description
 

simplecadapi-2.0.0b4/docs/api/translate_model_json_to_fcstd.md

@@ -0,0 +1,17 @@
+# translate_model_json_to_fcstd
+
+## API Definition
+
+```python
+def translate_model_json_to_fcstd(json_str: str, output_path: str, *, document_name: str = 'SimpleCADModel', freecad_cmd: Optional[str] = None) -> str
+```
+
+*Source: freecad_translator.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import translate_model_json_to_fcstd`
+
+## Description
+
+Translate canonical model JSON to `.FCStd` via FreeCADCmd/FreeCAD.

simplecadapi-2.0.0b4/docs/api/translate_model_json_to_freecad_script.md

@@ -0,0 +1,17 @@
+# translate_model_json_to_freecad_script
+
+## API Definition
+
+```python
+def translate_model_json_to_freecad_script(json_str: str, document_name: str = 'SimpleCADModel') -> str
+```
+
+*Source: freecad_translator.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import translate_model_json_to_freecad_script`
+
+## Description
+
+Translate exported model JSON into a FreeCAD Python script.

{simplecadapi-2.0.0b2 → simplecadapi-2.0.0b4}/docs/architecture/sdk-architecture-review.md

@@ -57,7 +57,7 @@ SimpleCADAPI 的顶层 API 选择是正确的：它没有把用户拖进传统 C
 
 - 顶层 API 被 aliases 稀释了。`create_box`、`create_line`、`extrude`、`union`、`to_step` 等别名降低了 canonical API 的唯一性。对用户友好，但对文档、LLM、图记录和长期兼容不友好。参考：`src/simplecadapi/__init__.py:145`、`src/simplecadapi/__init__.py:318`。
 - README 说 API 函数统一用 return type 反映命名，但公开面包含 `translate_shape`、`rotate_shape`、`export_step`、`export_stl` 和大量 aliases。这个声明过强。参考：`README.md:200`、`src/simplecadapi/__init__.py:47`、`src/simplecadapi/__init__.py:187`。
-- `rsolidlist` 命名混杂了“参数类型”和“返回类型”：`cut_rsolidlist`、`intersect_rsolidlist` 实际返回 `Solid`，而 `linear_pattern_rsolidlist` 返回 `List[Solid]`。这会伤害 API 语义一致性。参考：`src/simplecadapi/operations.py:2994`、`src/simplecadapi/operations.py:3102`、`src/simplecadapi/operations.py:4121`。
+- `rsolidlist` 命名混杂了“参数类型”和“返回类型”：`cut_rsolid`、`intersect_rsolid` 实际返回 `Solid`，而 `linear_pattern_rsolidlist` 返回 `List[Solid]`。这会伤害 API 语义一致性。参考：`src/simplecadapi/operations.py:2994`、`src/simplecadapi/operations.py:3102`、`src/simplecadapi/operations.py:4121`。
 - public op 名和 graph op 名不完全一致：`translate_shape` 记录为 `make_translate_rshape`，`extrude_rsolid` 记录为 `make_extrude_rsolid`。这种分层可以接受，但必须正式化为“source API”和“canonical IR”的稳定映射表。参考：`src/simplecadapi/operations.py:117`、`src/simplecadapi/serializer.py:116`。
 - 一些非 session 分支仍记录 legacy op 名，如 `make_box`、`make_cylinder`、`make_segment_wire`，和 canonical `make_*_r*` 命名不一致。参考：`src/simplecadapi/operations.py:785`、`src/simplecadapi/operations.py:1534`、`src/simplecadapi/operations.py:1638`。
 
@@ -186,7 +186,7 @@ QL 是架构上最应该继续投资的部分。
 
 - `tracked_union` 接收 `glue` 和 `tol`，但没有把它们设置到 `BRepAlgoAPI_Fuse`。也就是说用于结果的 union 和用于 tracking 的 union 参数可能不一致。参考：`src/simplecadapi/tracking.py:338`、`src/simplecadapi/tracking.py:352`。
 - `union_rsolid` replay 忽略记录过的 `clean`、`glue`、`tol`，只调用 `ops.union_rsolid(all_solids)`。参数不 faithful。参考：`src/simplecadapi/operations.py:2946`、`src/simplecadapi/serializer.py:1029`。
-- `cut_rsolidlist` 对无交集 tool 直接跳过，这对 modeling convenience 可能友好，但对 replay/diagnostic 来说可能隐藏错误。参考：`src/simplecadapi/operations.py:3033`。
+- `cut_rsolid` 对无交集 tool 直接跳过，这对 modeling convenience 可能友好，但对 replay/diagnostic 来说可能隐藏错误。参考：`src/simplecadapi/operations.py:3033`。
 - 多 tool cut/intersect 只保留最后一次 delta，前面 tool 的 lineage 丢失。参考：`src/simplecadapi/operations.py:3020`、`src/simplecadapi/operations.py:3127`。
 - extrude face classification 使用 center 精确相等、normal dot 精确等于 0、angle 精确等于 pi，这在 CAD 数值几何里非常脆弱。参考：`src/simplecadapi/operations.py:2631`、`src/simplecadapi/operations.py:2646`、`src/simplecadapi/operations.py:2653`。