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

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 地址或配置额外的静态下载站点。