curios/docs/versioning.md

插件版本与发布记录

仓库是 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 + 插件版本 + 平台架构 唯一标识：

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 是可反复生成的本地开发索引；不能把它当作历史发布记录。

# 必须是确定的、可由底座访问的 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。源码仓库可保持私有，安装包的可见性单独决定。