# 插件版本与发布记录

仓库是 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
# 必须是确定的、可由底座访问的 HTTPS 分发目录；示例域名须替换。
pnpm run release:prepare --base-url https://downloads.example/source/
pnpm run test:release
```

命令会将本次打包的常规插件合并到生产源 `source/index.json`（源 ID 为 `trove-official`），并在 `dist/release/` 准备同目录结构的上传材料。故障注入插件和无效包不会进入生产源。未确定分发地址时不预先填入不可访问的下载地址。

校验规则：

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

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

## 发布顺序

1. 提交并推送源代码，记录 Git commit；需要时为各插件打独立 tag。
2. 构建和验证，准备发布索引；审阅本次新增的版本与产物。
3. 上传新安装包，拒绝覆盖已存在且内容不同的文件。
4. 从底座实际使用的网络路径下载每个新增包，核对 SHA-256 和大小。
5. 最后原子替换远程索引，提交并推送仓库中的发布索引。
6. 从该远程源刷新、安装并运行验证；不能用本地文件安装冒充远程源验收。

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

## 私有源码与下载认证

当前 `https://git.render.ink/trove/curios` 是私有源码仓库，匿名访问原始 JSON 会跳转到登录页。推送源代码本身不能使它成为可安装的软件源。

Trove 当前 HTTP 软件源没有仓库登录凭据配置。生产分发可使用免登录的安装包/索引下载入口，或在底座支持私有软件源认证后使用受保护的入口；不要把访问令牌写进 Manifest、源码索引或下载 URL。源码仓库可保持私有，安装包的可见性单独决定。