2. 孪生模型版本标识体系设计

孪生模型的版本标识不是给文件起个名字那么简单。一个设备孪生模型同时包含几何网格、物理参数、行为脚本、映射规则和运行数据绑定关系，任何一处变化都可能影响仿真结果。版本标识体系要回答三个问题：这次改动是什么性质、能否追溯到唯一一份内容、在什么场景下应该引用哪个版本。语义化版本、时间戳版本、哈希指纹和分支标签是四种互补手段，各自解决不同层面的问题。

四种标识手段的适用条件

语义化版本采用 主版本.次版本.修订号 的形式，表达的是“兼容性承诺”。主版本号递增表示存在不兼容变更，例如设备孪生模型的接口参数被删除或单位从毫米改为米；次版本号递增表示向后兼容的功能新增，例如新增一个温度测点映射；修订号递增表示向后兼容的问题修正，例如修正某段行为脚本的边界判断。它适合对外发布、被其他系统引用的稳定版本，缺点是依赖人工判断变更性质，容易出现“改了却忘记升版本”的情况。

时间戳版本采用 YYYYMMDD-HHmmss 形式，表达的是“产生时刻”。它天然单调递增、无需人工决策，适合自动构建流水线、每日同步任务和临时快照。缺点是它不携带任何语义信息，两个相邻时间戳之间可能只是格式微调，也可能是模型结构重写，仅凭时间戳无法判断。

哈希指纹对模型内容做规范化后计算摘要，例如对几何文件、参数表、脚本分别计算再合并，得到类似 sha256:9f3c… 的短标识。它表达的是“内容唯一性”，只要内容不变指纹就不变，内容有任何字节级差异指纹就改变。它适合做完整性校验、去重存储和精确复现，缺点是可读性差，且对序列化顺序、浮点精度敏感，需要先定义规范化规则。

分支标签如 main、dev、release/1.x、device-A12，表达的是“用途或环境”。它适合区分开发、测试、交付、现场部署等不同通道，也适合按设备型号或项目分支管理。缺点是标签会移动，同一个标签在不同时间可能指向不同提交，因此不能单独作为长期引用依据。

组合策略：分层引用而非四选一

实践中不应只用一种标识，而应按“通道—语义—内容”三层组合。分支标签负责通道，语义化版本负责对外承诺，哈希指纹负责内容锁定，时间戳作为构建元数据附加。推荐的完整版本串格式为：

device-A12@v2.3.1+20250612-143502.sha256-9f3c1a7d

其中 device-A12 是设备/分支标签，v2.3.1 是语义化版本，20250612-143502 是构建时间戳，sha256-9f3c1a7d 是内容指纹短码。引用规则是：开发阶段可引用分支标签，测试阶段引用语义化版本，交付与现场部署必须引用到哈希指纹，确保任何时候都能还原出完全相同的模型内容。

为设备孪生模型设计版本号规则

下面以一个具体对象为例：某型号电机设备孪生模型 motor-M300，包含几何模型、绕组参数表、温升行为脚本和传感器映射表四类资产。设计版本号规则如下。

第一步，定义资产清单与规范化规则。四类资产分别计算内容摘要，再按固定顺序拼接后计算总指纹。规范化要求：参数表按字段名排序、浮点数统一保留 6 位小数、脚本去除行尾空白、几何文件使用二进制归一化格式。这样同一份逻辑内容无论导出顺序如何，指纹都一致。

第二步，确定语义化版本的递增判据。针对该模型约定：删除或重命名任何对外暴露的参数、改变单位、改变接口字段含义，主版本号加一；新增参数、新增测点映射、新增行为脚本分支，次版本号加一；修正脚本逻辑错误、修正参数默认值但不改变接口，修订号加一。每次提交必须由提交者在变更说明中标注变更类型，由流水线校验版本号是否与变更类型匹配。

第三步，生成组合版本串并写入模型元数据。模型包根目录放置 version.json，内容示例：

{
  "model": "motor-M300",
  "semver": "2.3.1",
  "build_time": "20250612-143502",
  "content_hash": "sha256:9f3c1a7d5e2b...",
  "branch": "release/2.x",
  "assets": {
    "geometry": "sha256:1a2b...",
    "params":   "sha256:3c4d...",
    "behavior": "sha256:5e6f...",
    "mapping":  "sha256:7a8b..."
  }
}

第四步，验证与判断。加载模型时先校验总指纹是否与元数据一致，不一致说明内容被篡改或传输损坏；再检查语义化版本是否满足调用方的兼容性要求，例如调用方要求 >=2.3.0 且 <3.0.0，则 2.3.1 通过、2.4.0 通过、3.0.0 拒绝。现场部署时额外记录部署时间与设备序列号，形成“模型版本—设备—时间”三元组，便于后续追溯。

综合来看，语义化版本回答“改了什么性质”，时间戳回答“什么时候产生”，哈希指纹回答“是不是同一份内容”，分支标签回答“给谁用、在哪个通道”。四者组合成一条完整版本串，再配合分层引用规则，就能让设备孪生模型在开发、测试、交付、运维各阶段都做到可读、可查、可复现。