## 组件身份保持稳定

同一组件更新继续使用原 ID，提升 `version`，保持用户熟悉的名称和图标。不要靠换 ID 躲开发行冲突；这会切断更新关系和原有数据归属。

版本号应对应实际发行内容。已经发布的同版本不可作为可随时覆盖的文件槽位。

## 功能、宿主和数据有三个版本

| 版本 | 管理什么 |
| --- | --- |
| 组件 `version` | 本次业务和界面发行内容 |
| `minAppVersion` / `maxAppVersion` | 支持的宿主范围 |
| 数据 `schemaVersion` | 用户状态与项目数据结构 |

只改界面不一定需要更新宿主；需要新 preload、原生或主进程能力时必须配套版本。数据格式变化也不能只依赖组件版本字符串猜测。

## 为迁移留一个可恢复过程

1. 读取旧状态并识别 schemaVersion。
2. 验证必要输入与输出引用。
3. 保留旧副本，再生成新格式。
4. 检查新状态和实际文件。
5. 成功后替换当前状态；失败则保留旧内容并解释原因。

迁移不能顺手清空用户项目、模型设置或历史输出。任务未完成的临时文件与用户成果也要分开归属。

## 发布前做兼容矩阵

测试最低支持宿主、当前宿主、上一组件版本创建的项目，以及新组件在不兼容宿主中的拒绝表现。对于正式包，还要核对发行范围和运行环境。

每项结果应记录实际组合；没有测过的版本不要写成兼容。

## 回退不是覆盖旧摘要

回退按照当前服务器和宿主支持的发行状态处理。需要修复时通常生成更高版本；撤回或恢复已有发行，也应保留可追溯的文件和记录。

不能把旧发行文件同名覆盖为新内容，再继续使用旧的签名、摘要或登记状态。

## 旧项目怎么处理

如果项目已被新版本迁移，不应直接承诺旧组件仍可读取。先确认是否存在兼容读取或受支持的回迁；必要时使用迁移前备份，在明确说明下恢复。

用户已经完成的论文、图表和源代码不应随着组件卸载或回退被删除。

## 一份清楚的更新说明

```text
组件：稳定 ID 与公开名称
版本：1.0.1
变化：具体触发条件与现在的行为
宿主要求：实际最低版本
数据影响：是否迁移，保留哪些旧内容
安装方式：对应类别的正式包或已有更新入口
已知限制：尚未覆盖的明确场景
```

更新说明面向使用者，写清具体变化和要求。内部文件名、源码已经修改或工具执行成功，都不能单独证明用户已经安装新版本。