用途:管理 Speckle 的版本与模型,支持创建与查询版本、比较变更、回滚与分页遍历历史。术语:Project(旧称 Stream)、Model(旧称 Branch)、Version(旧称 Commit)。新代码一律用当前术语,部分 SDK 参数仍保留旧名(如 ServerTransport 的 stream_id)。
主要能力:创建版本需先上传对象再关联模型;版本仅 message 字段可更新,版本本身不可变;可删除版本、在项目内跨模型移动版本;可按模型列出并分页遍历版本;提供版本比较所需的数据检索与基于 applicationId 的对象级差异思路,以及查看器 DiffExtension 的可视化差异;回滚无内置 mutation,做法是新建指向旧对象的版本;模型支持创建、更新、删除,名称可用 / 分层。
使用方式:Python 用 client.version.create/get/list/update/delete,配合 operations.send/receive 与 ServerTransport;也可用 GraphQL(versionMutations、modelMutations 等)。列出长历史务必用游标分页,不要一次加载全部。
限制与注意:版本不可修改,只能新建;删除中间版本会破坏下游引用(webhook、自动化、查看器 URL);不要用 referencedObject 作稳定标识,应用 version.id;创建版本应写明 message 和 sourceApplication;删除模型前先确认无下游依赖;DiffExtension 须在 viewer.init() 后创建;加载多模型时传 autoFit=false,全部加载后再调用 camera.setCameraView。更多 API 签名与示例见技能内 references 文件。