cadSet/SIMPLECADAPI_2.0.2_UPDATE.md

SimpleCADAPI 2.0.2 更新对比与 CadSet 集成建议

对比日期：2026-07-28 当前集成版本：/Users/jerry/linkhand/CadSet/SimpleCADAPI，2.0.1b1 待评估版本：/Users/jerry/Downloads/SimpleCADAPI-master，2.0.2

1. 结论摘要

SimpleCADAPI 2.0.2 相比 CadSet 当前集成的 2.0.1b1 是一次明显的增量升级，不是接口重写。

本次静态对比得到：

指标	结果
当前版本	2.0.1b1
新版本	2.0.2
当前文件数	555
新版文件数	767
内容相同	351
新增文件	240
删除文件	28
修改文件	176
当前顶层公开导出	214
新版顶层公开导出	303
新增顶层公开导出	89
删除顶层公开导出	0
Python 测试文件	34 → 51
Model JSON schema	仍为 2.0

文件统计排除了 .git、虚拟环境、缓存、构建输出和 node_modules 等非源码内容。由于下载目录没有上游 Git 历史或正式 CHANGELOG，本报告基于两个目录的文件内容、公开导出、函数签名、测试、文档和依赖配置进行对比。

对 CadSet 的总体判断：

• 可以升级，现有调用大概率不会因公开 API 删除而直接失效。
• 不建议只覆盖 SimpleCADAPI/ 后结束；这样只能获得兼容性更新，无法充分利用新增能力。
• 对我们最有价值的是新版的语义标签、拓扑跟踪、单位/公差、模型入口以及 STEP B-Rep 比较工具。
• 新版 B-Rep 工具适合增强 DesignIR 重建验收，但它不是 STEP 参数化历史恢复器，也不能单独替代 SurfaceIR。
• 建议先在升级分支完成回归测试，再将新增能力分阶段接入 designir-pipeline、cad-router 和前端查看器。

2. 新增内容

2.1 统一的可重放模型入口

新版增加：

• @model
• ModelResult
• capture_result(...)
• requires_session
• get_active_session

新版推荐使用一个 @model 入口管理 GraphSession，模型函数执行后返回 ModelResult。结果对象可直接提供：

• 模型图 JSON
• 重放结果
• 场景包路径
• 会话和结果节点

这比我们目前在 designir_pipeline.py 中手动创建 GraphSession、手动导出 JSON 更完整，也更容易建立统一的生成合同。

对 CadSet 的价值：

• DesignIR 编译结果可统一包装为一个可重放模型。
• 生成、重放、导出和验收可以绑定同一个模型标识。
• 以后更容易追踪“哪个参数、哪个操作生成了哪个结果”。

2.2 物理单位和公差链

新版新增完整的单位系统：

• 长度：毫米、厘米、米、英寸、英尺
• 面积和体积单位
• 角度：度、弧度
• 百分比和无量纲单位
• 单位换算、维度推导和表达式单位检查

主要公开 API 包括：

• Unit、Dimension、UnitLike
• get_unit(...)
• convert_value(...)
• infer_dimension(...)
• canonical_unit_for_dimension(...)
• expression_uses_units(...)

同时新增公差分析：

• DimensionTolerance
• ToleranceGraph
• ToleranceRequirement
• ToleranceAnalysis
• ToleranceReport
• analyze_tolerance(...)
• check_tolerance(...)

对 CadSet 的价值：

• DesignIR 参数可以显式区分长度、角度、数量和无量纲值。
• 上传 STEP 推断出的毫米尺寸与文本中出现的英寸尺寸可以在进入后端前统一换算。
• 参数修改可以提前阻止长度与角度相加等无效表达式。
• 可以把制造公差和参数允许范围纳入修改验收。

需要注意：新版默认以毫米和度计算，但保留变量声明时的单位。旧式无单位变量仍被支持，不过不能与带单位变量任意混合。

2.3 语义标签、来源映射和拓扑跟踪增强

新增或扩展的能力包括：

• apply_tag_rselection(...)
• explain_tag(...)
• 带 scope 的 list_tags(...)
• TrackingPolicy
• LineagePolicy
• TopologyPropagation
• TagBinding、TagTarget、TagEvidence
• TagProducer、TagPropagation、TagLineageWitness
• source_binding、source_topology、output_role、solids 等 QL 查询

基础体和特征操作现在可以直接声明角色标签。例如盒体可分别标记顶面、底面、前后左右面；圆柱可标记起始面、结束面、侧面、圆边和接缝边。拉伸、扫掠、圆角、倒角、布尔运算也增加了结果角色和跟踪策略。

对 CadSet 的价值非常直接：

• DesignIR 中的 feature_id 可以映射为 SimpleCADAPI 的语义 tag。
• 参数的 affected_face_ids 不必只依赖庞大的原始面 ID 列表，可逐步转成“特征角色 + 稳定选择条件”。
• 修改孔径、板厚或法兰间距后，可以通过标签验证目标特征是否变化、非目标特征是否保持。
• 对布尔运算后的拓扑命名问题，新版提供了更明确的来源证据和传播策略。

这部分是最值得优先接入 DesignIR 3.0 的更新。

2.4 Scene Schema 1.0 与 .scene.zip

新版新增完整的场景编译与归档子系统：

• SceneRoot
• SceneSource
• SceneCompileOptions
• CompiledScenePackage
• compile_scene(...)
• export_scene(...)
• GLB 三角面和边线生成
• 场景清单、规范化 JSON、哈希和资源校验
• 浏览器端 Scene Viewer

使用 @model(export_dir=...) 时可以生成一个自包含的 <graph_id>.scene.zip。包内包含：

• scene.json
• model/model.json
• 操作来源映射涉及的 Python 文件
• Viewer 所需的 GLB、实体和选择资源

新版同时加入：

• scene-contract/：独立 TypeScript 场景合同、规范化、校验和 ZIP 工具
• viewer/：Vite/TypeScript 浏览器查看器

对 CadSet 的价值：

• 可把“可视化几何 + 模型图 + 源码映射 + 选择信息”打成一个可验证产物。
• CAD Agent Studio 目前分别管理 STEP、GLB 和 DesignIR；后续可以评估把 .scene.zip 作为 SimpleCADAPI 模型的附加交付物。
• 场景包适合预览、审计和语义选择，但不能替代 STEP、URDF 或 MJCF。

2.5 STEP B-Rep 逆向检查和比较

新版新增 simplecadapi.inverse_engineer.brep 及命令：

simplecad-brep inspect
simplecad-brep compare
simplecad-brep render
simplecad-brep slices

主要能力：

• 检查 STEP 的实体、壳、面、边、曲面和曲线类型。
• 输出结构化 B-Rep 报告。
• 对目标 STEP 与候选 STEP 做双向几何和拓扑检查。
• 渲染一致的正交视图和等轴测视图。
• 对指定物理截面采样并生成 XOR 差异图。

其中 render 和截面图片依赖可选的 matplotlib。

对 CadSet 的价值：

• 可作为上传 STEP 重建前的几何证据提取补充。
• 可作为验收 Agent 的第二套独立检查器。
• 截面 XOR 对内部孔、腔体和薄壁差异尤其有帮助。
• 可为失败零件生成更易分析的结构化报告。

边界说明：

• 该模块明确是检查、比较和诊断工具。
• 它不会从 STEP 恢复原始草图、约束和真实建模历史。
• 它不能证明两个文件拥有相同的建模意图。
• 是否达到我们的“1:1”标准，仍需结合体积、质心、包围盒、双向表面距离、对称差体积、关键截面和参数修改测试。

2.6 新增 CAD 翻译后端

原有 FreeCAD 翻译器被重构为公共的翻译器后端合同，并新增：

• Fusion 360 translator
• SolidWorks translator
• 共享的 translator base、types 和 errors
• 各后端 capability 描述

对 CadSet 的建议：

• 初期将其视为可选派生产物，不要把它们作为 DesignIR 的权威重建后端。
• 先用一组参数化零件验证生成脚本在目标软件中的可执行性、拓扑一致性和参数可编辑性。
• FreeCAD 原有流程也需要回归，因为内部实现已经拆分重构。

2.7 标准件和机械零件库扩展

新增标准库模块：

• std/fastener.py
• std/chain.py

新增或正式公开的工厂能力：

• make_bolt_rsolid
• make_nut_rsolid
• make_roller_chain_sprocket_rsolid
• make_straight_bevel_gear_rsolid

现有轴承和齿轮能力仍然保留。

对 CadSet 的价值：

• cad-router 可将螺栓、螺母、滚子链轮和直齿锥齿轮优先路由到 SimpleCADAPI。
• DesignIR 可用语义化标准件特征代替大量低层几何操作。
• 对标准件修改，参数命名和约束可以更稳定。

2.8 新增几何操作

新增公开操作：

• twisted_sweep_rsolid

适用于带扭转角的扫掠实体。它拓展了现有拉伸、旋转、放样和普通扫掠的表达范围，但仍需在我们的后端能力表中明确其限制并增加测试。

3. 修改内容

3.1 现有函数以增量参数为主

抽查 CadSet 当前使用的核心函数，新版没有删除原有必需参数，主要增加可选的关键字参数：

函数	主要变化
make_box_rsolid	新增结果和六个方向面的标签参数
make_cylinder_rsolid	新增结果、端面、侧面、圆边和接缝标签参数
union_rsolid	新增 tracking_policy
cut_rsolid	新增 tracking_policy
export_model_json	新增 result_node_ids
list_tags	新增 scope
拉伸/扫掠/圆角/倒角	新增输出角色、结果标签或跟踪相关参数

因此现有代码不是立即失效。普通命名参数建议改为关键字调用，避免参数顺序变化；union_rsolid 和 cut_rsolid 的实体输入仍是 *solids 可变位置参数，不能写成不存在的 solids=、solid= 或 cutters= 关键字。

CadSet 当前存在的典型调用：

scad.union_rsolid([shape, tool], clean=True)
scad.cut_rsolid(shape, cutters, skip_non_intersecting=False)

建议将布尔实体作为明确的位置参数传入，并将控制项保留为关键字参数：

scad.union_rsolid(shape, tool, clean=True)
scad.cut_rsolid(
    shape,
    *cutters,
    skip_non_intersecting=False,
)

新版也继续兼容嵌套序列，因此当前的 scad.union_rsolid([shape, tool], clean=True) 和 scad.cut_rsolid(shape, cutters, ...) 仍符合源码合同。新代码采用展平的位置参数只是为了表达更清晰。

3.2 Skill 推荐工作流发生变化

当前 Skill 主要指导 Agent 手动管理 GraphSession 和导出函数；新版 Skill 将以下方式设为标准：

1. 一个 @model 模型入口。
2. 子构建器使用 @requires_session。
3. 使用 capture_result(...) 明确最终结果。
4. 通过 ModelResult 获取模型 JSON、重放结果和场景产物。
5. 使用标签解释和来源映射，而不是只依赖面/边遍历顺序。

如果升级源码但不更新 Skill，Agent 仍会继续按旧范式生成代码，新增能力无法被稳定利用。

3.3 FreeCAD 翻译器内部重构

FreeCAD 翻译器从较集中的实现拆分为：

• API
• capability 分析
• code generation
• context
• exporter
• script translator
• backend translator

公开用途仍然是从 Model JSON 生成 FreeCAD Python 或 .FCStd，但内部重构意味着必须重新跑翻译器测试，不能只依据顶层 API 未删除就判断行为完全一致。

3.4 示例与文档重组

新版增加了单位公差链示例，同时删除或移出了多个旧的独立示例和复杂项目示例。保留并修改了部分大型减速器和 BLDC 执行器示例。

这是仓库内容整理，不代表对应的公开建模 API 被删除。升级时不应以覆盖目录的方式误删我们可能引用的旧示例；需要先确认这些示例是否被 CadSet 文档或测试使用。

4. 依赖和工具链变化

运行时新增：

jsonschema = ">=4.25.1,<5.0.0"
rfc8785 = ">=0.1.4,<0.2.0"
typing-extensions = ">=4.12,<5"

可选依赖新增：

inverse-engineer = ["matplotlib>=3.7.0"]

开发依赖新增：

datamodel-code-generator = "==0.32.0"

CLI 新增：

simplecad-brep

这些依赖分别服务于场景 schema 校验、RFC 8785 规范化 JSON、类型兼容、B-Rep 可视化和 schema 模型生成。

升级后必须同步锁文件和部署环境。否则源码替换后可能在导入场景模块时出现缺包，而不是在安装阶段明确失败。

5. CadSet 当前实际使用情况

CadSet 目前对 SimpleCADAPI 的核心集成位于：

designir-pipeline/scripts/designir_pipeline.py

当前适配器主要使用：

• GraphSession
• make_box_rsolid
• make_cylinder_rsolid
• union_rsolid
• cut_rsolid
• export_model_json
• export_step

路由和前端相关位置包括：

text-to-cad/skills/cad-router/
text-to-cad/viewer/
cad-agent-studio/

当前尚未接入的 2.0.2 新能力：

• @model 和 ModelResult
• 单位与公差链
• 丰富的角色标签和来源解释
• Scene Schema 1.0 与 .scene.zip
• STEP B-Rep 检查、比较和截面 XOR
• Fusion 360、SolidWorks 翻译器
• 新的紧固件、链轮和锥齿轮工厂

因此，当前项目不会因为把下载目录放在旁边就自动获得这些能力。

6. 对 DesignIR 3.0 和上传 STEP 重建的意义

6.1 可以直接帮助的部分

1. 重建前证据提取

   • 用 simplecad-brep inspect 输出面、边、曲面、曲线和拓扑摘要。
   • 将摘要作为 DesignIR 特征推断的证据之一。

2. 独立验收

   • 用 compare 检查候选与源 STEP 的双向几何和拓扑。
   • 用 slices 比较关键截面并输出 XOR。
   • 与现有 SurfaceIR 验收指标交叉验证。

3. 稳定参数修改

   • 把 DesignIR feature ID 映射为语义标签。
   • 用来源映射和拓扑跟踪验证修改影响范围。
   • 用单位和公差阻止不合法参数修改。

4. 可审计产物

   • 对 SimpleCADAPI 生成结果附带 Model JSON 或 .scene.zip。
   • 让查看器、验收器和后续 Agent 使用同一份模型语义。

6.2 不能直接解决的部分

• STEP 本身没有原始草图和建模历史，新版也不会凭空恢复真实历史。
• B-Rep inspection 只能提供几何与拓扑证据，特征树仍然是推断结果。
• .scene.zip 是 SimpleCADAPI 自有模型的场景包，不是把任意 STEP 自动转成参数化模型的万能格式。
• 语义标签只能在我们生成或映射标签后生效，不能自动让所有历史 STEP 拥有可靠参数名。
• 自由曲面、复杂过渡面和多实体装配的独立参数化重建仍需 DesignIR/SurfaceIR 扩展。

7. 兼容性与风险

风险项	级别	说明
顶层 API 删除	低	静态对比未发现删除的顶层公开导出
函数行为变化	中	特征、跟踪、标签和翻译器内部有明显修改
依赖缺失	中	新增三个运行时依赖和一个可选可视化依赖
Model JSON 兼容	低到中	schema 仍为 2.0，但节点负载和语义证据可能增加
FreeCAD 翻译回归	中	后端内部大幅拆分，并新增统一 translator contract
Viewer 重复建设	中	新 Scene Viewer 与 CadSet 现有 Viewer 功能有重叠
上传 STEP 能力被高估	高	B-Rep 工具不是自动参数化历史恢复工具
直接目录覆盖	高	可能覆盖本地改动、旧示例、Skill 和未提交文件

8. 推荐升级方案

阶段 A：安全升级源码

1. 新建升级分支，不直接覆盖 main。
2. 记录 CadSet 当前 SimpleCADAPI/ 是否存在本地改动。
3. 用 2.0.2 更新源码、文档、Skill 和依赖配置。
4. 保留 CadSet 自己的适配层，不把项目逻辑写入上游目录。
5. 同步 Python 锁文件和部署安装脚本。
6. 运行 SimpleCADAPI 上游测试和 CadSet 集成测试。

阶段 B：保持功能等价

首先只做兼容迁移：

• 将调用统一改为关键字参数。
• 验证盒体、圆柱、布尔、导出 STEP 和 Model JSON。
• 验证现有 DesignIR 示例在升级前后：
  • 实体数一致
  • 包围盒一致
  • 体积误差在容差内
  • STEP 导出成功
  • Model JSON 可重放

这一阶段不改变路由决策，也不宣称重建精度提高。

阶段 C：接入语义能力

建立 DesignIR → SimpleCADAPI 映射：

DesignIR feature.id
    → SimpleCAD tag
    → operation output role
    → topology/source evidence
    → edit validation contract

优先覆盖：

• base/body
• bore/hole
• boss
• pocket/slot
• fillet/chamfer
• linear/polar pattern
• mounting face
• datum axis/plane

修改后验证目标 tag 的几何变化，并检查非目标 tag 是否保持。

阶段 D：接入上传 STEP 验收

建议将新工具接入验收 Agent，而不是直接让重建 Agent把报告当成答案：

源 STEP
  ├─ SurfaceIR/DesignIR 现有证据
  └─ SimpleCAD B-Rep inspection
             ↓
        重建候选 STEP
             ↓
  ┌──────────┴──────────┐
  │ 现有几何验收        │
  │ SimpleCAD compare   │
  │ 关键截面 XOR        │
  └──────────┬──────────┘
             ↓
       统一验收报告

两个检查器得出冲突结论时不自动晋升经验，应进入人工审查或失败聚类。

阶段 E：扩展路由和交付物

回归稳定后再做：

• 路由新增 bolt、nut、sprocket、roller chain、bevel gear 关键词。
• 对 SimpleCADAPI 模型可选生成 .scene.zip。
• 评估 CAD Agent Studio 是否复用 Scene Contract，而不是立刻替换现有 Viewer。
• 将 Fusion 360、SolidWorks 脚本作为可选下载项。

9. 建议的验收矩阵

9.1 基础回归

类型	用例
基础体	box、cylinder
特征	extrude、revolve、loft、sweep、twisted sweep
布尔	union、cut、intersect
修饰	fillet、chamfer、shell
阵列	linear、polar
导出	STEP、STL、Model JSON
重放	Model JSON replay

9.2 CadSet 集成回归

• designir-pipeline 的 SimpleCADAPI 后端测试全部通过。
• cad-router 的后端选择测试全部通过。
• 文本生成、图文生成和 DesignIR 参数修改各跑一组真实用例。
• 升级前后同一 DesignIR 输出做几何差异比较。
• 前端仍可加载 STEP/GLB，下载链路不受影响。

9.3 新能力验收

• 单位混合与非法维度表达式测试。
• 公差链通过与失败测试。
• 标签在布尔、圆角和倒角后的追踪测试。
• .scene.zip schema、哈希、资源集合和 Viewer 加载测试。
• simplecad-brep inspect/compare/render/slices CLI 测试。
• FreeCAD、Fusion 360、SolidWorks 翻译能力边界测试。
• 新标准件尺寸、轴线、体积和参数修改测试。

10. 最终建议

建议升级到 2.0.2，但采用“先兼容、再利用”的方式：

1. 先完成源码和依赖升级，证明现有 CadSet 功能没有回退。
2. 优先接入标签、来源映射和拓扑跟踪，增强参数修改的可解释性。
3. 把 B-Rep inspection、compare 和 slices 接入上传 STEP 的独立验收。
4. 再接入单位、公差、新标准件和场景包。
5. Fusion 360、SolidWorks 和新 Viewer 放在后续可选阶段。

对我们的核心目标“上传 STEP → 自有 DesignIR → 独立重建 → 参数修改 → 自动验收”而言，2.0.2 最重要的贡献不是让 STEP 自动恢复建模历史，而是提供了更好的语义记录、拓扑来源、模型重放和独立几何诊断基础。正确接入后，它能提升重建与修改闭环的可验证性；是否真正提高 1:1 重建率，仍必须通过同一批真实 STEP 的升级前后基准测试来证明。