chore(catalog): initialize production plugin source

docs/development.md

@@ -0,0 +1,59 @@
+# 官方软件源的维护与发布
+
+`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>`。
+
+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 服务器上的私有 Release 附件时，在服务器要求鉴权后查询 Git HTTPS credential helper。账户必须能读取源仓库和对应插件仓库。SSH 密钥仅用于 Git，附件下载还需要本机 HTTPS 凭据。凭据不写进索引或安装包。
+
+## 自动化身份
+
+`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/)。