refactor: separate plugin repositories and release-based catalog

docs/development.md

@@ -1,62 +1,47 @@
-# Curio 开发与验收
+# 官方软件源的维护与发布
 
-此仓库承载 Trove 正式插件与生产软件源。当前包含用于首批验收的简单插件；生产发布以 `source/index.json` 为准，本地测试材料位于 `dist/`。
+`trove/curios` 保存官方软件源索引、插件仓库登记和发布工具。底座在 `trove/app`；插件源码与安装包分别位于 `trove-plugins` 下各仓库的代码和 Releases。
 
-正式插件 **Harmony Connector** 的使用、构建、发布和真机验收步骤见 [Harmony Connector](harmony-connector.md)。它采用独立实现和构建命令，不属于下面的 QA 套件。
+## 仓库职责
 
-## 底座测试套件
+- `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 上执行收录。
 
-15 个插件工程（14 个插件 ID，其中升级插件有两个版本），覆盖 UI、Host 服务、Rust 原生后端、跨插件服务、可选/必需依赖、版本约束、生命周期、故障恢复和升级回滚。另有 22 个故意无效的安装包和 4 个异常软件源。
+安装包不进入 Git，所有 `*.curio` 都被忽略。Git 软件源仍指向 `https://git.render.ink/trove/curios.git`。
 
-```sh
-pnpm install --frozen-lockfile
+## 发布协议
 
-# 已安装 trove 命令时可省略此变量；也可指向本机 app 仓库构建产物。
-export TROVE_BIN=/absolute/path/to/app/target/debug/trove
-pnpm run pack
+插件仓库根目录的 `release.json` 声明仓库、插件 ID 和是否为共享测试套件。普通插件 tag 为 `v<curio.json version>`；测试套件独立打 tag，各测试插件保留自身版本。
 
-# 可选：使用真实底座组件在临时目录自动验证。
-export TROVE_APP_DIR=/absolute/path/to/app
-pnpm run verify
-```
+Release 先以草稿创建，上传每个平台的 `.curio` 和 `trove-release.json` 后再发布。描述文件包含仓库、tag、源码 commit、插件 Manifest 摘要，以及附件名、平台、大小和 SHA-256。插件图标以小型图片 Data URL 收录，私有图片也无需额外鉴权。
 
-打包需要 macOS、Rust/Cargo、Node.js 22+、pnpm、Python 3 和 Trove CLI。原生包只面向当前构建机器的架构；安装后的插件无需 Node.js、Python 或 Cargo。SDK 使用仓库内的版本化 `@trove/plugin-sdk@0.1.0` 包，离线复制到 UI 中。
+本机手动生成发布目录，上传全部附件并发布 Release 后，插件的 Linux workflow 使用 `CATALOG_TOKEN` 调用源仓库的 `sync-release.yml`，传入 `repository` 与 `tag`。收录只接受登记仓库及其所属插件 ID，并下载附件校验大小和 SHA-256。
 
-生成结果：
+源 workflow 使用 `PLUGIN_RELEASE_TOKEN` 读取私有插件 Release，使用本任务的 `GITEA_TOKEN` 更新自身索引。写入以 Gitea Contents API 的当前文件 SHA 为前提，并发冲突后重新读取、重新合并，不覆盖其他发布。
 
-- `dist/packages/`：15 个可安装 `.curio` 包。
-- `dist/index.json`：常规测试源，8 个插件 ID / 9 个版本包。
-- `dist/faults-index.json`：6 个故障/异常依赖插件，按需安装。
-- `dist/invalid/`：22 个无效包、4 个异常源及预期错误码。
-- `dist/verification.json`：自动验证的逐项结果、环境和观察项。
+相同插件 ID、版本和平台的产物不可变。重复收录没有副作用；相同版本的 URL、大小或 SHA-256 发生变化会报错。
 
-在 Trove 添加**本地软件源**，选择 `dist/index.json` 的绝对路径，即可安装常规测试插件。若要测试 HTTP 下载：
+## 新增插件
 
-```sh
-pnpm run serve
-# 在底座添加 HTTP 软件源：http://127.0.0.1:8765/index.json
-# 用 QA_HTTP_PORT 环境变量更换端口，Ctrl-C 停止。
-```
+1. 在 `trove-plugins` 创建独立仓库，添加源码、`curio.json`、`release.json` 和发布 workflow。
+2. 将仓库与 ID 登记到 `source/repositories.json`，授予收录机器人读取该仓库的代码与 Release 的权限。
+3. 在对应平台准备构建环境与 Trove CLI，提交源码，运行插件仓库的手动发布脚本并上传 Release。
 
-完整步骤、覆盖矩阵与当前限制见 [测试指南](testing.md)。
+现有插件仓库中的发布 workflow 可作为模板。发布工具从源仓库检出，统一维护。
 
-插件各自通过 `curio.json.version` 管理版本；公开服务契约版本与底座兼容范围分别维护。历史发布索引只追加版本、禁止覆盖同版本产物，详见 [版本与发布](versioning.md)。`pnpm run release:prepare` 将安装包与索引准备到 `source/`，提交并推送后即可通过 Git 仓库源安装。`pnpm run test:release` 验证版本约束。
+## 失败恢复
 
-## 目录
+Release 成功但收录失败时，在插件 Actions 手动运行发布 workflow，填写已有 tag；该 workflow 使用 Linux runner，只重试收录，不重新构建或替换附件。也可在源仓库直接运行收录 workflow。
 
-- `curios/<name>/`：各插件独立 Manifest 与公共服务契约。
-- `shared/ui/`、`shared/backend/`：测试面板和原生后端源码；构建时复制到各插件。
-- `source/index.json`：生产软件源与历史版本索引。
-- `tools/`：构建、打包、测试源和真实底座验证适配器。
-- `vendor/`：版本化 SDK 分发包与来源说明。
+## 私有源
 
-项目依赖使用 pnpm；插件通过版本化的 `@trove/plugin-sdk` 引用 SDK，不通过 `../app` 引用源文件。仅自动验证适配器通过显式的 `TROVE_APP_DIR` 编译待测底座组件，插件构建与运行不依赖该路径。App 仓库保留协议规范和教学模板。
+当前仓库保持私有。底座用本机 Git 凭据读取索引；下载同一 Git 服务器上的私有 Release 附件时，在服务器要求鉴权后查询 Git HTTPS credential helper。账户必须能读取源仓库和对应插件仓库。SSH 密钥仅用于 Git，附件下载还需要本机 HTTPS 凭据。凭据不写进索引或安装包。
 
-## 发布约定
+## 自动化身份
 
-1. 各插件独立声明版本、平台、依赖与权限。
-2. 构建并执行 trove curio check / pack。macOS 原生后端使用 Mac Runner 构建。
-3. 执行 `pnpm run release:prepare`，检查 `source/index.json` 的新增版本与 `source/packages/` 中的不可变版本包。
-4. 将索引和安装包在同一提交中推送，再使用 Git 仓库地址完成远程安装与运行验证。私有仓库沿用本机 Git 认证。
-
-官网：https://trove.render.ink
+`trove-publisher` 负责跨仓库通信：可以读取源代码、触发源 Actions，并读取已登记插件的 Release；没有底座仓库访问权限，也不能直接改写源代码。源索引写入由源 workflow 自身的任务令牌完成。