diff --git a/README.md b/README.md index d9e665ea..0b8c70e9 100644 --- a/README.md +++ b/README.md @@ -134,17 +134,17 @@ the full crank cycle sweeps clean in the same sim · --- -## Update Notes (2.1.1) +## Update Notes (2.1.2) > **Release notice:** Validate generated definitions, assembly constraints, and > manufacturing geometry before production use. -SimpleCADAPI 2.1.1 is a tooling patch (SDK API unchanged): a CadQuery→FTC -translator toolset with snapshot constraint recovery under -`tools/research/cadqueryftc`, aligned with the histjson four-stage research -pattern. See the [full English update notes](docs/updates/2.1.1.md) for the -tracer/translator/validator split, the recovery axioms, and verification -coverage; the 2.1.0 agent-first feature set is described in +SimpleCADAPI 2.1.2 anchors the `@scad.part` cache to the builder script's own +directory (standalone sources run anywhere, no `pyproject.toml` required) and +makes translator-emitted corpus keyword-form with an explicit cache anchor. +See the [full English update notes](docs/updates/2.1.2.md) for the anchor +semantics, compatibility notes, and the FTC convention's new `@scad.part` +section; 2.1.0's agent-first feature set is described in [docs/updates/2.1.0.md](docs/updates/2.1.0.md). All formal single-script examples emit a synchronized `.scadpkg`, AP242 @@ -170,7 +170,7 @@ 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 release: `simplecadapi==2.1.1`. +Current release: `simplecadapi==2.1.2`. ## What It Provides @@ -531,6 +531,7 @@ against a target STEP (see `examples/bowl_connector/`). ## Documentation +- 2.1.2 update notes: [`docs/updates/2.1.2.md`](docs/updates/2.1.2.md) - 2.1.1 update notes: [`docs/updates/2.1.1.md`](docs/updates/2.1.1.md) - 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md) - Reconstruction Agent test specification: diff --git a/README.zh-CN.md b/README.zh-CN.md index 1569e660..f9fb52dc 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -120,14 +120,14 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真 --- -## 更新日志(2.1.1) +## 更新日志(2.1.2) > **发布说明:** 用于生产前,请验证生成的定义、装配约束和制造几何。 -SimpleCADAPI 2.1.1 是工具链补丁版本(SDK API 无变化):在 -`tools/research/cadqueryftc` 下新增 CadQuery→FTC 翻译工具集与快照约束 -恢复引擎,与 histjson 四阶段研究工具同构。tracer/翻译器/验证器分工、 -恢复公理与验证范围见[完整中文更新说明](docs/updates/2.1.1.zh-CN.md); +SimpleCADAPI 2.1.2 把 `@scad.part` 缓存锚定到 builder 脚本所在目录 +(独立脚本随处可运行,无需 `pyproject.toml`),翻译器产物全面 keyword +参数化并显式声明缓存锚点。锚点语义、兼容性说明与 FTC 规范新增的 +`@scad.part` 一节见[完整中文更新说明](docs/updates/2.1.2.zh-CN.md); 2.1.0 的 agent-first 能力全貌见 [docs/updates/2.1.0.zh-CN.md](docs/updates/2.1.0.zh-CN.md)。 @@ -146,7 +146,7 @@ SimpleCADAPI 2.1.1 是工具链补丁版本(SDK API 无变化):在 SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK,提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API,可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件,以及将记录的模型转换为 FreeCAD 工作流。 -当前版本:`simplecadapi==2.1.1`。 +当前版本:`simplecadapi==2.1.2`。 ## 核心能力 @@ -366,6 +366,7 @@ uv run --extra fem python examples/ap242_gmsh_volume_mesh/study_mesh_convergence ## 文档 +- 2.1.2 更新说明:[`docs/updates/2.1.2.zh-CN.md`](docs/updates/2.1.2.zh-CN.md) - 2.1.1 更新说明:[`docs/updates/2.1.1.zh-CN.md`](docs/updates/2.1.1.zh-CN.md) - 2.1.0 更新说明:[`docs/updates/2.1.0.zh-CN.md`](docs/updates/2.1.0.zh-CN.md) - Reconstruction Agent 测试规范: diff --git a/docs/skill/SKILL.md b/docs/skill/SKILL.md index 708b0c45..4a7d6e55 100644 --- a/docs/skill/SKILL.md +++ b/docs/skill/SKILL.md @@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo license: Apache-2.0 metadata: project: simplecadapi - version: 2.1.1 + version: 2.1.2 package-name: simplecadapi - package-version: 2.1.1 + package-version: 2.1.2 --- # SimpleCAD SDK Skill diff --git a/docs/skill/references/discipline/feature-tree-convention.md b/docs/skill/references/discipline/feature-tree-convention.md index 2272fe83..67d64960 100644 --- a/docs/skill/references/discipline/feature-tree-convention.md +++ b/docs/skill/references/discipline/feature-tree-convention.md @@ -101,6 +101,44 @@ design parameters) stay in the source; geometric verification never does — it lives in the external verification scripts per `geometric-validation.md`. +## The `@scad.part` decorator and its cache + +`@scad.part` accepts keyword parameters only; emitted corpus sources state +them explicitly so the meaning is legible from the source itself: + +- `id` — logical part identity (defaults to the function name); part of the + cache key. +- `revision` — `'1.0.0'` by default; bump it to force rebuilds; part of the + cache key. +- `inputs` — sequence of `file_input()` declarations; the referenced files' + content snapshots enter the cache key. +- `cache` — cache policy: `"auto"` (read/write), `"off"`, `"read_only"`, + `"read_write"`, `"refresh"`, or a policy dict / `CachePolicy`. +- `project_root` — anchor for the part cache, file inputs, and project + config. Default: the directory containing the builder's source file — + a script is its own project, runs from anywhere, and its cache lands + beside it. Pass it explicitly only to anchor at a larger project + (project-level cache or `[tool.simplecadapi.cache]` config). +- `tolerance_profile` — kernel tolerance fingerprint (default + `'simplecad-default'`); part of the cache key. + +**Where the cache lands.** The cache root is `/.simplecad/cache` +(`records/`, `objects/`, `locks/`, `quarantine/`); part interface state +lives beside it at `/.simplecad/state/latest-parts.json` and +follows the cache root. Overrides resolve as decorator `cache=` > +environment (`SIMPLECAD_CACHE_DIR`, `SIMPLECAD_CACHE_MODE`, …) > +`[tool.simplecadapi.cache]` in the `pyproject.toml` at the anchor > +defaults. The cache key covers `id`, `revision`, `tolerance_profile`, +normalized call arguments, the whole-file source fingerprint, file-input +snapshots, and the generator profile (SDK/OCC versions) — any source edit +invalidates. + +**Delivered sources state the anchor explicitly.** A translator-emitted +or standalone `.ftc.py` passes `project_root=Path(__file__).parent` +explicitly so the cache location is legible from the source itself — +even though it matches the default, the corpus states it rather than +relying on implicit resolution. + ## Reference shape of a compliant source ```python @@ -111,7 +149,8 @@ PLATE_T = scad.var("plate_t", 6.0, unit="mm") def _pocket_tools(p): ... # block-local, geometry tier when tools are pure primitives -@scad.part(id="motor-mount", revision="1.0.0", ...) +@scad.part(id="motor-mount", revision="1.0.0", + project_root=Path(__file__).parent) def build_motor_mount() -> scad.Part: # ---- feature: base-plate (build, profile=sketch) ---- s = scad.make_sketch_rsketch(name="base", plane="XY") diff --git a/docs/updates/2.1.2.md b/docs/updates/2.1.2.md new file mode 100644 index 00000000..27d4e92e --- /dev/null +++ b/docs/updates/2.1.2.md @@ -0,0 +1,54 @@ +# 2.1.2 Update Notes + +> **Release notice:** Validate generated definitions, assembly constraints, and +> manufacturing geometry before production use. + +## Script-anchored part cache (SDK behavior change) + +The `@scad.part` / `@scad.assemble` anchor is now the directory containing the +builder's source file. The content-addressed part cache and the part interface +state land at `