# 插件版本与发布记录

仓库是 monorepo：**每个 Curio 独立版本、独立兼容范围、独立更新**。不要求一次提交中的所有插件一起升级。

| 信息 | 唯一来源 | 作用 |
| --- | --- | --- |
| 插件版本 | `curios/<name>/curio.json` 的 `version` | 底座安装、更新、切换和回滚的版本 |
| 公共服务版本 | `services.provides[].version`，与 Contract 的 `version` 一致 | 调用方依赖约束；不兼容接口升级主版本 |
| 底座兼容范围 | `engine.trove` | 声明可运行的 Trove 版本；不是插件版本 |
| 已发布版本索引 | `source/index.json` | 保存全部历史版本、平台、URL、大小和 SHA-256 |
| 源码快照 | Git commit；可打 `<curio-id>/v<version>` tag | 从一个已发布插件版本定位对应源代码 |
| 仓库工具版本 | 根 `package.json.version` | 构建/验证工具版本，不用于判断插件是否有更新 |

例如只修复 `dev.trove.qa.host` 的 UI，应将该插件从 `1.0.0` 升到 `1.0.1`，其他插件保持原版本。服务接口没有变化时，服务版本仍可保持 `1.0.0`。

## 不可变发布

一个产物由 **插件 ID + 插件版本 + 平台架构** 唯一标识：

```text
packages/dev.trove.qa.host/1.0.0/any.curio
packages/dev.trove.qa.self/1.0.0/aarch64-apple-darwin.curio
packages/dev.trove.qa.self/1.0.0/x86_64-apple-darwin.curio
```

同一版本可以补齐另一种架构，但不能替换已经发布的同架构内容。发布后发现问题要发新版本，不能重传覆盖旧文件。回滚切换到已有历史版本，不删除或重写坏版本对应的源码记录。服务有破坏性变更时还需要修改服务主版本和使用方依赖。

当前 `test-upgrade-v1` 与 `test-upgrade-v2` 是验收专用的双版本样本，共用 `dev.trove.qa.upgrade` ID。普通产品插件应只维护一份当前源码；历史通过 Git 和发布目录保存，不为每次升级复制一个源码文件夹。

## 准备发布

先修改需要发布的 Manifest，执行 `pnpm run pack` 和验证。`dist/index.json` 是可反复生成的本地开发索引；不能把它当作历史发布记录。

```sh
pnpm run release:prepare
pnpm run test:release
```

命令会将本次打包的常规插件合并到生产源 `source/index.json`（源 ID 为 `trove-official`），并把不可变安装包复制到 `source/packages/`。索引中的包地址相对于 `source/`，索引与包在同一 Git 提交中发布。`dist/release/` 保留本次发布材料副本。故障注入插件和无效包不会进入生产源。

校验规则：

- 从当前包计算大小和 SHA-256，与打包元数据比较，防止索引指向错误内容。
- 保留旧版本以及其他架构；不会因为本次只发布部分内容而重建/清空历史。
- 同 ID、版本、架构的 SHA-256、大小、URL 必须与历史完全一致；不一致会要求升级插件版本。
- 同一已发布版本的 `engine.trove` 不得悄悄变化。
- 重复准备相同材料不会改变首次发布日期。
- 先完整校验本次所有条目，再复制产物和更新本地索引。

`--catalog <目录>` 可在隔离目录试运行。正式发布应将 `source/` 的历史索引与安装包提交回仓库。该脚本只准备本地材料，不表示推送或远程安装已经成功。

需要独立 HTTP 分发时，可显式传入 `--base-url <HTTPS 分发目录>` 生成绝对下载地址，并使用 `dist/release/` 上传；已有版本的 URL 仍不能覆盖。

## 发布顺序

1. 更新需要发布的插件版本，构建并完成验证。
2. 执行 `pnpm run release:prepare`；审阅本次新增的版本、架构、大小和 SHA-256。
3. 将源码、`source/index.json` 和 `source/packages/` 在同一提交中推送；需要时为各插件打独立 tag。
4. 从远程 Git 仓库刷新、安装并运行验证；不能用本地文件安装冒充远程源验收。

发布工作串行进行；两种架构先各自构建，再将产物合并至同一版本。若更新 `shared/ui/` 或 `shared/backend/`，所有受影响且需要重新发布的插件都要增加插件版本，未受影响的插件不必修改。

## 添加仓库源

在 Trove「软件源 → 添加软件源」中填写：

- 显示名称：Trove 官方软件源
- 唯一 ID：`trove-official`
- 源类型：Git 仓库
- 仓库地址：`git@git.render.ink:trove/curios.git`
- 优先级：`0`

也支持 HTTPS 克隆地址 `https://git.render.ink/trove/curios.git`。私有仓库沿用本机 Git 的 SSH 密钥或 HTTPS credential helper；不要把访问令牌写进 Manifest、索引或 URL。添加后刷新，底座自动读取默认分支的 `source/index.json`，并固定该提交读取仓库内的安装包。用户不需要填写原始 JSON 地址或配置额外的静态下载站点。