API 参考
CadFlow 提供两种互补的公共调用风格。面向 Session 的 API 使用 Model 和 Shape 直接处理原生几何；声明式 API 记录更丰富的操作、语义、产品结构与交换产物，便于检查和重放。两者都是受支持的公共边界，应选择能够完整保留工作流状态的最小 API 面。
选择入口
| 需求 | 推荐入口 | 结果 |
|---|---|---|
| 交互式构造与检查原生几何 | Model | 由 Session 持有的 Shape |
| 一次执行已知的原生批处理 | Graph | 通过稳定 C ABI 返回的有序字符串结果 |
| 记录并重放结构化设计流程 | @model | ModelResult、Model JSON 与 Session JSON |
| 构造带约束的二维轮廓 | Sketch API | 不可变草图状态、求解诊断与原生轮廓 |
| 组织可复用产品 | Assembly API | Part、实例、Connector、约束与报告 |
| 检查 STEP/BREP 证据 | Inspection API | 结构化拓扑、测量、对比、截面与视图 |
| 编译可移植渲染产物 | Scene API | 经过验证的 Scene 包与 GLB 资源 |
| 描述静态薄壁形态 | Flexible API | 确定性采样的 Panel 网格与导出产物 |
| 描述降阶连接行为 | Physical API | 经过验证的连接层与响应批次 |
| 打包分布式表面接触 | Simulation API | 求解器无关的接触证据与交接包 |
参考文档分层
本参考由三层组成：
- 概念与契约页解释所有权、单位、更新语义、错误行为与推荐工作流。
- 领域目录列出一个子系统中的全部公共符号。
- 自动生成的符号页记录每个符号的运行时签名、参数、返回注解、别名、字段与公共成员。
已知符号名称时使用全部 API 符号；只知道所属子系统时进入对应领域目录。
核心运行时
| 页面 | 内容 |
|---|---|
| Model | Session 生命周期、构造方法组、预检与动态操作 |
| Shape | 所有权、测量、验证、网格化与导出 |
| Session、Handle 与坐标系 | NativeSession、不透明 Handle、CoordinateFrame 与 Workplane |
| 反馈与预览 | 诊断、报告、预览缓冲区与 GLB 转换 |
建模与执行
| 页面 | 内容 |
|---|---|
| 创建与导入 | 基本体、轮廓、曲线、曲面与外部几何 |
| 特征、布尔与变换 | 拉伸、旋转、扫掠、布尔、局部特征与复制 |
| 拓扑、查询与交换 | 子形状、选择、测量、验证、STEP/STL/BREP |
| 原生 Graph | 节点引用、支持的批处理、执行与结果解码 |
| 记录、序列化与重放 | @model、GraphSession、Model JSON 与严格重放 |
| 表达式、单位与公差 | 符号值、量纲、转换与公差分析 |
通用契约
将 CadFlow 接入长期维护的应用前，请阅读 API 约定；实现自动恢复或 Agent 反馈前，请阅读错误与诊断。
重要默认规则：
- 从
cadflow或文档列出的公共子模块导入，不要导入cadflow._engine。 - 坐标和角度通常是普通 Python 数值；接受带单位值的函数会明确说明。
Shape不能跨ModelSession 使用。- 产品、草图、物理连接与仿真数据通常不可变或采用函数式更新，必须接收返回的新值。
- 路径参数可能写入产物；调用成功不能替代文件、Schema 或几何验证。
覆盖范围与版本
当前生成参考覆盖 518 个唯一公共符号，包括 414/414 个顶层导出，以及 28 个公共模块入口的显式导出。参考基于 CadFlow 0.1.0，可用以下命令核对运行时漂移：
PYTHONPATH=../CadFlow/python python scripts/generate_api_reference.py --check
CadFlow 当前为 Alpha。生产环境应固定版本、保留产物元数据，并在升级前阅读兼容与迁移。