# 官方软件源的维护与发布

`trove/curios` 保存官方软件源索引、插件仓库登记和发布工具。底座在 `trove/app`；插件源码与安装包分别位于 `trove-curios` 下各仓库的代码和 Releases。

## 仓库职责

- `source/repositories.json`：登记插件 ID 与发布仓库的对应关系。
- `source/index.json`：底座消费的 Source Index v1，保留版本、兼容范围、平台、Release 附件 URL、大小与 SHA-256。
- `tools/prepare-release.mjs`：手动构建后生成发布目录。
- `tools/publish-release.mjs`：可选的命令行上传工具，上传全部附件后发布 Release。
- `tools/notify-release.mjs`：由插件仓库的 Linux workflow 在 Release 发布后触发源收录。
- `tools/sync-release.mjs`：校验登记关系和附件，合并版本，通过文件 SHA 比较后更新远端索引。
- `.gitea/workflows/sync-release.yml`：在 Linux runner 上执行收录。

安装包不进入 Git，所有 `*.curio` 都被忽略。Git 软件源仍指向 `https://git.render.ink/trove/curios.git`。

## 发布协议

插件仓库根目录的 `release.json` 声明仓库、插件 ID。每个仓库只发布一个插件，tag 为 `v<curio.json version>`。

正式发布前，Manifest 版本统一使用 `0.0.1-alpha.x`，Tag 统一使用 `v0.0.1-alpha.x`，并将 Gitea Release 标记为 **Pre-release**；具体约定见[版本与 Release](versioning.md)。

Release 先以草稿创建，上传每个平台的 `.curio` 和 `trove-release.json` 后再发布。描述文件包含仓库、tag、源码 commit、插件 Manifest 摘要，以及附件名、平台、大小和 SHA-256。插件图标以小型图片 Data URL 收录，私有图片也无需额外鉴权。

本机手动生成发布目录，上传全部附件并发布 Release 后，插件的 Linux workflow 使用 `CATALOG_TOKEN` 调用源仓库的 `sync-release.yml`，传入 `repository` 与 `tag`。收录只接受登记仓库及其所属插件 ID，并下载附件校验大小和 SHA-256。

源 workflow 使用 `PLUGIN_RELEASE_TOKEN` 读取私有插件 Release，使用本任务的 `GITEA_TOKEN` 更新自身索引。写入以 Gitea Contents API 的当前文件 SHA 为前提，并发冲突后重新读取、重新合并，不覆盖其他发布。

相同插件 ID、版本和平台的产物不可变。重复收录没有副作用；相同版本的 URL、大小或 SHA-256 发生变化会报错。

## 新增插件

1. 在 `trove-curios` 创建独立仓库，添加源码、`curio.json`、`release.json` 和发布 workflow。
2. 将仓库与 ID 登记到 `source/repositories.json`，授予收录机器人读取该仓库的代码与 Release 的权限。
3. 在对应平台准备构建环境与 Trove CLI，提交源码，运行插件仓库的手动发布脚本并上传 Release。

现有插件仓库中的发布 workflow 可作为模板。发布工具从源仓库检出，统一维护。

## 失败恢复

Release 成功但收录失败时，在插件 Actions 手动运行发布 workflow，填写已有 tag；该 workflow 使用 Linux runner，只重试收录，不重新构建或替换附件。也可在源仓库直接运行收录 workflow。

## 下载访问

Git 索引使用本机 Git 的访问方式，SSH 密钥仅用于 Git。Release 附件必须允许匿名 HTTP(S) 下载，底座不读取或附带本机鉴权凭据。公开分发可使用允许匿名访问的 Release 或独立下载存储；Gitea 全站登录限制也不能拦截这些下载地址。索引和安装包不得嵌入账号、Token 或密码。发布 workflow 的服务端凭据仅用于发布与索引同步。

## 自动化身份

`trove-publisher` 负责跨仓库通信：可以读取源代码、触发源 Actions，并读取已登记插件的 Release；没有底座仓库访问权限，也不能直接改写源代码。源索引写入由源 workflow 自身的任务令牌完成。

## 大陆网络环境

发布流程直接从本 Gitea 拉取源代码，不依赖 GitHub 的 checkout/setup-node Action，也不在 Linux runner 上构建 macOS 原生产物。

- npm 默认 `https://registry.npmmirror.com`；仓库级 `.npmrc` 也使用该镜像。
- runner 已有 Node.js 22+ 时直接复用；否则从 `https://npmmirror.com/mirrors/node` 下载固定 Node.js 22.23.2，并校验预置的官方 SHA-256。
- 收录只安装锁定版本的 semver，不下载 Corepack/pnpm，不执行 npm 生命周期脚本。
- Actions Variables `NPM_REGISTRY`、`NODE_MIRROR` 可覆盖镜像地址，未设置时采用上述国内地址。
- Linux job 需要 bash、git、curl、tar、xz 和 CA 证书。runner 容器镜像拉取发生在 workflow 执行前；如更换 runner 镜像，应在 VPS 的 Docker 配置或 runner 配置中使用可访问的镜像仓库。

参考：[npmmirror 使用说明](https://npmmirror.com/)、[Gitea Action 下载机制](https://docs.gitea.com/usage/actions/faq/)。