# 原生组件版本与更新

插件版本由 `package.json.version` 管理，原生组件版本由 `package.json.qiuyaNative.version` 单独管理。三个平台原生包的 `optionalDependencies` 必须精确固定到原生版本。只修改主题、界面或 Host 业务代码时，只递增插件版本，保留原生版本与原生依赖锁定信息。

自动更新下载 `dsh-qiuya-tools.tgz`，交给 Harness 的官方插件管理器安装。Harness 使用其持久化 pnpm 缓存复用匹配系统、架构和精确版本的原生依赖。插件运行时不自行联网、编译或修改共享缓存；启动前仍校验原生清单的版本、协议、架构、文件大小和 SHA256。元数据检查仍可能联网，原生包缓存缺失时会重新下载。

原生源码或构建输入变化时，执行：

```sh
node scripts/native-version.mjs 0.7.2
```

命令同步原生版本、三个可选依赖、npm 锁文件和 `native-sources.json` 的源码指纹。版本号须换成新的稳定版本，禁止覆盖已发布版本。普通插件版本调整不要同步递增这些原生依赖。`node scripts/native-version.mjs --check` 会检查源码指纹，发布组装也会执行检查，防止忘记更新原生版本。修改原生构建脚本也计入指纹；诊断脚本、测试夹具、编译临时文件和界面文件不计入。

发布组装优先获取 npm 上已经发布的精确原生包，校验 SHA512 与包内平台、架构、协议、清单和文件 SHA256 后复用原始压缩包，避免重复编译导致签名或二进制变化。只有该版本尚未发布（404）时，才从本次构建输出打包。网络错误、身份错误或校验失败都会终止组装。

发布器按各原生包自己的版本确认 npm 状态，已发布且字节一致时跳过发布；所有依赖与插件均公开确认后，上传 `dsh-qiuya-tools-native-ready.json` 标记，客户端此后才选择小包。npm 尚在扫描期间继续提供完整包，避免下载小包后缺少原生依赖。

为兼容旧客户端，保留三个完整平台包及原有文件名；其中内嵌清单保留插件版本，独立原生包的清单使用原生版本。旧客户端首次升级仍下载一次完整包，升级到支持小包的版本之后生效。此前只装过完整包、pnpm 缓存中没有独立原生包的机器，首次切换时可能需要下载一次原生依赖。

更新界面显示的是插件小包的实际下载进度；Harness 在安装阶段处理原生依赖。原生版本变化时，下载依赖所需的时间包含在安装阶段，仍需要重启 Harness 才能切换到新组件。