Merge branch 'release/2.1.0' into dev

This commit is contained in:
NiJingzhe
2026-09-07 09:45:59 +08:00
7 changed files with 225 additions and 18 deletions
+11 -8
View File
@@ -134,19 +134,22 @@ the full crank cycle sweeps clean in the same sim ·
---
## Update Notes (2.0.4b3 development)
## Update Notes (2.1.0)
> **Beta release:** Validate generated definitions, assembly constraints, and
> **Release notice:** Validate generated definitions, assembly constraints, and
> manufacturing geometry before production use.
SimpleCADAPI 2.0.4b3 adds reproducible `@part`/`@assemble` product boundaries,
incremental assembly solves, and a persistent crash-safe cache for whole parts.
See the [full English update notes](docs/updates/2.0.4b3.md) for contracts,
SimpleCADAPI 2.1.0 turns the SDK into an agent-first CAD toolkit: the Feature
Tree Convention authoring discipline, external CAD-history import, the
browser reverse-engineering studio, DXF engineering drawings, and
self-contained runnable examples — on top of the reproducible
`@part`/`@assemble` product boundaries and the persistent crash-safe cache.
See the [full English update notes](docs/updates/2.1.0.md) for contracts,
cache modes, diagnostics, limitations, and verification coverage.
All formal single-script examples emit a synchronized `.scadpkg`, AP242
`.step`, and editable `.FCStd` from the same product package. The
split AP242/Gmsh example under `examples/12_ap242_gmsh_volume_mesh/` exposes
split AP242/Gmsh example under `examples/ap242_gmsh_volume_mesh/` exposes
each build and export stage as a separate directly runnable script.
---
@@ -167,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 development beta: `simplecadapi==2.0.4b3`.
Current release: `simplecadapi==2.1.0`.
## What It Provides
@@ -519,7 +522,7 @@ uv run python examples/20_integrated_bldc_joint_actuator/main.py
## Documentation
- 2.0.4b3 update notes: [`docs/updates/2.0.4b3.md`](docs/updates/2.0.4b3.md)
- 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md)
- Reconstruction Agent test specification:
[`docs/guides/reconstruction-agent-test-prompt.md`](docs/guides/reconstruction-agent-test-prompt.md)
- STEP BREP reverse-engineering guide:
+8 -6
View File
@@ -120,13 +120,15 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真
---
## 更新日志(2.0.4b3 开发中)
## 更新日志(2.1.0)
> **Beta 版本:** 用于生产前,请验证生成的定义、装配约束和制造几何。
SimpleCADAPI 2.0.4b3 新增可复现的 `@part`/`@assemble` 产品边界、增量装配求解,
以及整零件的持久化崩溃安全缓存。契约、cache mode、诊断、限制和验证范围见
[完整中文更新说明](docs/updates/2.0.4b3.zh-CN.md)。
SimpleCADAPI 2.1.0 把 SDK 推向 agent-first CAD 工具箱:Feature Tree Convention
建模纪律、外部 CAD 历史导入、浏览器逆向工作台、DXF 工程图与自包含示例,全部
建立在可复现的 `@part`/`@assemble` 产品边界与持久化崩溃安全缓存之上。契约、
cache mode、诊断、限制和验证范围见
[完整中文更新说明](docs/updates/2.1.0.zh-CN.md)。
---
@@ -143,7 +145,7 @@ SimpleCADAPI 2.0.4b3 新增可复现的 `@part`/`@assemble` 产品边界、增
SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK,提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API,可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件,以及将记录的模型转换为 FreeCAD 工作流。
当前开发 Beta:`simplecadapi==2.0.4b3`。
当前版本:`simplecadapi==2.1.0`。
## 核心能力
@@ -363,7 +365,7 @@ uv run --extra fem python examples/12_ap242_gmsh_volume_mesh/study_mesh_converge
## 文档
- 2.0.4b3 更新说明:[`docs/updates/2.0.4b3.zh-CN.md`](docs/updates/2.0.4b3.zh-CN.md)
- 2.1.0 更新说明:[`docs/updates/2.1.0.zh-CN.md`](docs/updates/2.1.0.zh-CN.md)
- Reconstruction Agent 测试规范:
[`docs/guides/reconstruction-agent-test-prompt.md`](docs/guides/reconstruction-agent-test-prompt.md)
- STEP BREP 逆向工程指南:
+2 -2
View File
@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
license: Apache-2.0
metadata:
project: simplecadapi
version: 2.0.4b3
version: 2.1.0
package-name: simplecadapi
package-version: 2.0.4b3
package-version: 2.1.0
---
# SimpleCAD SDK Skill
+114
View File
@@ -0,0 +1,114 @@
# SimpleCADAPI 2.1.0 Update Notes
[Chinese](2.1.0.zh-CN.md)
> **Release notice:** Validate generated definitions, assembly constraints,
> and manufacturing geometry before production use.
SimpleCADAPI 2.1.0 turns the SDK into an agent-first CAD toolkit: a
Feature-Tree-Convention authoring discipline with compiler-verified skill
guidance, an external CAD-history import path, a reverse-engineering studio
in the browser, DXF engineering drawings, and self-contained runnable
examples — on top of the reproducible product boundaries and crash-safe
cache introduced during the 2.0.4 beta cycle.
## 1. Durable part and assembly definitions
`@scad.part` builds exactly one physical single-solid part and returns a
`PartBuildResult`: runtime `Part`, `PartDefinition`, graph/session state,
model and session JSON, interface differences, and a per-build `CacheReport`.
Its content-derived key covers normalized arguments, builder source, declared
file inputs, revision, tolerance profile, and generator/ABI profile.
`@scad.assemble` requires explicit external `PartDefinition` or nested
`AssemblyDefinition` inputs. Repeated instances share immutable definitions;
closed validation rejects missing, unused, cyclic, conflicting, or
incompatible references. Definitions round-trip independently from
process-local runtime objects. Connector interface hashing is stable across
processes, so identical interfaces no longer produce spurious definition
diffs.
## 2. Incremental assembly solve, cache, and diagnostics
Assembly state records component dependencies and public connector
interfaces; changes propagate only along affected dependency paths, and every
restored placement still passes constraint-residual verification. The shared
content-addressed store uses canonical closed records, SHA-256 objects,
atomic writes, per-key locks, stale-lock recovery, and deduplication. One
`CachePolicy` (`off` / `read_only` / `read_write` / `refresh`) governs part
and assembly caching, and the `simplecad-cache` CLI emits stable JSON status
and verify/repair reports.
## 3. Feature Tree Convention (FTC)
Model sources follow an explicit feature-block discipline — sketch/profile,
operations, booleans, modifiers — recorded as a readable dataflow
(`body = op(body, tools)`), with per-feature header comments
(`# ---- feature: <slug> (<role>) ----`). The convention is backed by:
- a constrained 2D sketch API (dimension-driven profiles, wire offset for
shell-like walls) with open chain promotion to wires;
- canonical plane/axes conventions for planar makers, covered by regression
tests;
- a verified QL selection playbook (33 selection patterns) documenting the
structured selection channels and their reach.
## 4. DXF engineering drawings
A deterministic DXF engine turns a modeled part into 2D engineering drawings
through HLR projection: sheet plans, views, dimension chains, and diagnostic
plots, driven by the same package pipeline as the 3D exporters.
## 5. External CAD history import
`tools/research/histjson` plus the SDK translation layer import external
CAD-history dialects (Fusion-style histories) into FTC model sources:
constraints are translated unconditionally with per-item conflict audit
output instead of silent fallbacks. On the reference benchmark the deep
multi-feature case reproduces geometry at machine precision (Deep ~85%,
Fusion ~77% exact-match) and the constraint channel solves ~90% (Deep) /
~93% (Fusion) of cases.
## 6. Reverse-engineering studio in the browser
`viewer/re.html` is a human-in-the-loop reverse-engineering workbench:
pick faces/edges or lasso a region on the target STEP, annotate with inline
entity and operation chips, and submit — the server composes a
`submission.json` (annotations + per-entity one-level adjacency context +
operation tips + snapshot), an agent rebuilds, and the UI streams the
comparison and evaluation back. The composer is IME-safe (CJK composition
never submits), the same operation tip can be cited multiple times, and
user selections are never truncated. The studio UI is built with React 19 +
Tailwind 4 + shadcn-style components over the imperative three.js kernel.
The companion `.scadpkg` browser inspector loads v3 packages with full
closure-hash validation, so tampered packages are rejected by name.
## 7. Unified rendering and FEM-ready exports
One screenshot pipeline serves all 3D rendering needs: 1–4 view grids,
studio styling, deterministic anti-aliasing, and per-view annotation
placement with occlusion handling. The AP242/Gmsh example chains the package
through AP242 STEP, Gmsh volume meshing, and a Calculix static solve with
von-Mises reporting; MJCF export covers MuJoCo assembly consumers.
## 8. Open-source readiness
- Relicensed from AGPL-3.0 to Apache-2.0.
- The packaged skill is compiled per host harness (omp, opencode, zcode,
claudecode, codex, dsh, kimicode) from one source tree with conditional
host-binding blocks; a typo in a target name fails the build.
- Examples are self-contained folders (sources + verification + fresh
artifacts under `examples/<name>/out/`), cover part / assembly / reverse
engineering / FEM, and every example is verified to run end-to-end.
- `scad.verifier` and the `python-fcl` dependency are removed; collision
verification is external to the SDK.
## 9. Reliability
Geometry fingerprints are stable across BRep serialize/deserialize
round-trips (bounds quantized on a fixed 1e-4 mm grid, far coarser than the
sub-tolerance recomputation wobble), so package re-validation no longer
fails on cell-edge geometries. The Python type-check baseline was reduced
by an order of magnitude, and the suite stands at 1503 passing tests across
Python 3.10–3.13.
+88
View File
@@ -0,0 +1,88 @@
# SimpleCADAPI 2.1.0 更新说明
[English](2.1.0.md)
> **发布提示:** 用于生产前,请验证生成的定义、装配约束和制造几何。
SimpleCADAPI 2.1.0 把 SDK 推向 agent-first CAD 工具箱:Feature Tree
Convention 建模纪律 + 编译器校验的 skill 指引、外部 CAD 历史导入、浏览器内
逆向工作台、DXF 工程图、自包含可运行示例——全部建立在 2.0.4 beta 周期落地的
可复现产品边界与崩溃安全缓存之上。
## 1. 持久零件与装配定义
`@scad.part` 构建且只构建一个物理单实体零件,返回 `PartBuildResult`:运行时
`Part`、`PartDefinition`、图和 session 状态、model/session JSON、接口差异以及
单次构建的 `CacheReport`。内容派生 key 覆盖规范化参数、builder 源码、声明的
文件输入、revision、容差 profile 和 generator/ABI profile。
`@scad.assemble` 要求显式传入外部 `PartDefinition` 或嵌套
`AssemblyDefinition`。重复实例共享不可变定义;封闭校验会拒绝缺失、未使用、
循环、冲突或不兼容引用。定义可脱离进程内运行时对象独立往返。connector 接口
哈希跨进程稳定,相同接口不再产生虚假定义差异。
## 2. 增量装配求解、缓存与诊断
装配状态记录组件依赖和公共 connector 接口;变化只沿受影响的依赖路径传播,
每个恢复位置仍必须先通过约束残差验证。共享内容寻址存储使用规范封闭 record、
SHA-256 object、原子写入、逐 key 锁、陈旧锁恢复和对象去重。一个 `CachePolicy`
(`off` / `read_only` / `read_write` / `refresh`)同时治理零件与装配缓存,
`simplecad-cache` CLI 输出稳定 JSON 的 status 与 verify/repair 报告。
## 3. Feature Tree Convention(FTC)
模型源码遵循显式特征块纪律——sketch/profile、操作、布尔、修改器——以可读的
数据流记录(`body = op(body, tools)`),每个特征带头部注释
(`# ---- feature: <slug> (<role>) ----`)。该纪律由以下部分支撑:
- 约束 2D 草图 API(尺寸驱动轮廓、面向等壁结构的 wire 偏置),开链可提升为
wire;
- 平面 maker 的规范平面/轴向约定,带回归测试覆盖;
- 经过验证的 QL 选择 playbook(33 个已验证选择模式),沉淀结构化选择通道及
其覆盖范围。
## 4. DXF 工程图
确定性 DXF 引擎通过 HLR 投影把建模零件变成 2D 工程图:SheetPlan、视图、尺寸
链与诊断图,与 3D 导出器共用同一 package 管线。
## 5. 外部 CAD 历史导入
`tools/research/histjson` 加上 SDK 翻译层把外部 CAD 历史(Fusion 系)导入为
FTC 模型源码:约束无条件翻译,逐条输出冲突审计而不是静默回落。在参考基准上,
深多特征案例以机器精度复现几何(Deep ~85%、Fusion ~77% 全等),约束通道约
90%(Deep)/ 93%(Fusion)可解。
## 6. 浏览器内逆向工作台
`viewer/re.html` 是人在回路的逆向工作台:在目标 STEP 上点面/点边或套索圈选,
用内联实体与操作 chip 做标注并提交——服务端组装 `submission.json`(标注 +
逐实体一级邻接上下文 + 操作提示 + 截图),agent 重建,UI 回流对比与评审。
输入框对输入法安全(CJK 组词期永不提交)、同一操作提示可引用多次、用户的
选择集合永不截断。工作台 UI 用 React 19 + Tailwind 4 + shadcn 风格组件构建,
命令式 three.js 内核保持不变。
配套的 `.scadpkg` 浏览器检查器加载 v3 包并做全闭包哈希校验,被篡改的包会
按成员点名拒绝。
## 7. 统一渲染与 FEM 就绪导出
一条截图管线覆盖全部 3D 出图需求:1–4 视图网格、studio 风格、确定性抗锯齿、
逐视角标注放置与遮挡处理。AP242/Gmsh 示例把同一 package 串过 AP242 STEP、
Gmsh 体网格与 Calculix 静力求解并输出 von-Mises 报告;MJCF 导出覆盖 MuJoCo
装配消费者。
## 8. 开源就绪
- 许可证从 AGPL-3.0 改为 Apache-2.0。
- 打包 skill 从单一源码树按 host harness 条件编译(omp、opencode、zcode、
claudecode、codex、dsh、kimicode);目标名拼写错误会让构建直接失败。
- 示例是自包含目录(源码 + 验证脚本 + `examples/<name>/out/` 下最新产物),
覆盖零件 / 装配 / 逆向 / FEM 四类,且每个例子都验证过端到端可运行。
- `scad.verifier` 与 `python-fcl` 依赖移除;碰撞验证外置于 SDK。
## 9. 可靠性
几何指纹在 BRep 序列化往返下保持稳定(bounds 在固定 1e-4 mm 网格上量化,
远粗于亚容差的重算抖动),包重开校验不再在格边界几何上失败。Python 类型
检查基线下降一个数量级,测试套件在 Python 3.10–3.13 上共 1503 个用例通过。
+1 -1
View File
@@ -1,6 +1,6 @@
[project]
name = "simplecadapi"
version = "2.0.4b3"
version = "2.1.0"
description = "A simplified OCP-native CAD modeling Python API"
readme = "README.md"
license = { file = "LICENSE" }
Generated
+1 -1
View File
@@ -2954,7 +2954,7 @@ wheels = [
[[package]]
name = "simplecadapi"
version = "2.0.4b3"
version = "2.1.0"
source = { editable = "." }
dependencies = [
{ name = "cadquery-ocp" },