chore: publish clean Curio source

2026-09-23 16:09:14 +08:00
commit 4ab217897e
12 changed files with 991 additions and 0 deletions
@@ -0,0 +1,129 @@
+# 向 Trove 官方软件源投稿 / Contributing to the Trove Curio Source
+
+<!-- trove:zh:start -->
+
+官方软件源是公开索引，不接收 Curio 源码或安装包。外部作者与官方仓库使用同一条发布路径：先在 Curio 仓库发布 Release，再通过 Pull Request 更新本仓库。
+
+### 1. 发布 Curio Release
+
+Release 必须公开提供：
+
+- 一个或多个 `.curio` 安装包；
+- 一个名为 `trove-release.json` 的描述文件；
+- 与 Curio Manifest 相同的通用 SemVer 版本。Tag 可以是版本本身，也可以只多一个 `v` 前缀。
+
+描述文件使用 `schemaVersion: 2`，并显式选择本软件源：
+
+```json
+{
+  "schemaVersion": 2,
+  "repository": "owner/repository",
+  "tag": "v1.2.3",
+  "commit": "完整的 Git commit SHA",
+  "registries": ["trove/curios"],
+  "plugins": [
+    {
+      "id": "dev.example.curio",
+      "name": "Example Curio",
+      "description": "一句面向使用者的说明。",
+      "icon": "https://example.com/curio.png",
+      "version": "1.2.3",
+      "engine": { "trove": ">=0.0.1-alpha.1 <0.0.2" },
+      "artifacts": [
+        {
+          "target": "aarch64-apple-darwin",
+          "asset": "dev.example.curio-1.2.3-aarch64-apple-darwin.curio",
+          "sha256": "64 位小写十六进制 SHA-256",
+          "size": 123456
+        }
+      ]
+    }
+  ]
+}
+```
+
+版本只按通用 SemVer 校验，不要求使用某条特定预发布版本线。开发阶段的预发布版本允许重建并替换同名安装包；稳定版本发布后不可覆盖，需要修正时发布新版本。
+
+### 2. 更新索引
+
+PR 只修改 [`source/index.json`](https://git.render.ink/trove/curios/src/branch/main/source/index.json)，以及可选的单个 Curio 图标：
+
+- `repository` 填写公开的 HTTP(S) 仓库地址；
+- `descriptor` 指向该 Release 的 `trove-release.json`；
+- `url` 指向公开可下载的 Release 安装包；
+- `size` 和 `sha256` 必须由最终安装包计算；
+- Curio 按 ID 排序，版本按 SemVer 从新到旧排序，产物按 target 排序。
+
+图标属于 Curio，不属于版本。可以使用公开的 HTTP(S) 图片地址；也可以提交一次 `source/icons/<curio-id>.png` 或 `.webp`，大小不超过 256 KiB，并在所有版本中复用同一个 URL。不要提交 Base64 图标。
+
+### 3. 身份与审核
+
+首次收录会人工确认 Curio 的名称、用途、仓库和发布者意图。通过后，Curio ID 会与该仓库永久绑定；稳定版本的 `(id, version, target)` 不可覆盖，预发布版本允许由同一绑定仓库重建。仓库迁移需要单独审核，不能夹在版本 PR 中。
+
+后续版本仍会从上游 Release 重新读取描述文件和安装包，核对仓库、版本、显式软件源授权、大小与 SHA-256。校验全部通过的已绑定仓库版本可以自动合并；校验失败的 PR 不能合并。
+
+<!-- trove:zh:end -->
+
+<!-- trove:en:start -->
+
+The official source is a public index; it does not host Curio source code or packages. Third-party and official repositories follow the same path: publish a Release in the Curio repository, then update this repository through a pull request.
+
+### 1. Publish a Curio Release
+
+The public Release must contain:
+
+- one or more `.curio` packages;
+- a descriptor named `trove-release.json`;
+- a generic SemVer matching the Curio manifest. The tag may be the version or the version with one leading `v`.
+
+The descriptor uses `schemaVersion: 2` and explicitly opts in to this source:
+
+```json
+{
+  "schemaVersion": 2,
+  "repository": "owner/repository",
+  "tag": "v1.2.3",
+  "commit": "full Git commit SHA",
+  "registries": ["trove/curios"],
+  "plugins": [
+    {
+      "id": "dev.example.curio",
+      "name": "Example Curio",
+      "description": "A short user-facing description.",
+      "icon": "https://example.com/curio.png",
+      "version": "1.2.3",
+      "engine": { "trove": ">=0.0.1-alpha.1 <0.0.2" },
+      "artifacts": [
+        {
+          "target": "aarch64-apple-darwin",
+          "asset": "dev.example.curio-1.2.3-aarch64-apple-darwin.curio",
+          "sha256": "64 lowercase hexadecimal SHA-256 characters",
+          "size": 123456
+        }
+      ]
+    }
+  ]
+}
+```
+
+Versions are checked as generic SemVer and are not tied to a particular prerelease line. Prerelease assets may be rebuilt in place during development; stable Release assets are immutable and require a new version for corrections.
+
+### 2. Update the index
+
+A PR changes only [`source/index.json`](https://git.render.ink/trove/curios/src/branch/main/source/index.json) and, optionally, one stable Curio icon:
+
+- `repository` is the public HTTP(S) repository URL;
+- `descriptor` points to that Release's `trove-release.json`;
+- `url` points to a publicly downloadable Release asset;
+- `size` and `sha256` are calculated from the final package;
+- Curios are sorted by ID, versions by descending SemVer, and artifacts by target.
+
+An icon belongs to a Curio, not a version. Use a public HTTP(S) image URL, or add one `source/icons/<curio-id>.png` or `.webp` file up to 256 KiB and reuse its URL across releases. Do not embed Base64 icons.
+
+### 3. Identity and review
+
+The first submission is manually reviewed for its name, purpose, repository, and publisher intent. Once accepted, the Curio ID is permanently bound to that repository. Stable `(id, version, target)` entries are immutable; prerelease entries may be rebuilt only by the bound repository. Repository transfers require a separate review.
+
+Later versions are verified again from the upstream Release: repository, version, explicit registry opt-in, byte size, and SHA-256 must all match. A verified update from a bound repository may merge automatically; a failing PR cannot merge.
+
+<!-- trove:en:end -->