# Curio 开发与验收

此仓库承载 Trove 正式插件与生产软件源。当前包含用于首批验收的简单插件；生产发布以 `source/index.json` 为准，本地测试材料位于 `dist/`。

正式插件 **Harmony Connector** 的使用、构建、发布和真机验收步骤见 [Harmony Connector](harmony-connector.md)。它采用独立实现和构建命令，不属于下面的 QA 套件。

## 底座测试套件

15 个插件工程（14 个插件 ID，其中升级插件有两个版本），覆盖 UI、Host 服务、Rust 原生后端、跨插件服务、可选/必需依赖、版本约束、生命周期、故障恢复和升级回滚。另有 22 个故意无效的安装包和 4 个异常软件源。

```sh
pnpm install --frozen-lockfile

# 已安装 trove 命令时可省略此变量；也可指向本机 app 仓库构建产物。
export TROVE_BIN=/absolute/path/to/app/target/debug/trove
pnpm run pack

# 可选：使用真实底座组件在临时目录自动验证。
export TROVE_APP_DIR=/absolute/path/to/app
pnpm run verify
```

打包需要 macOS、Rust/Cargo、Node.js 22+、pnpm、Python 3 和 Trove CLI。原生包只面向当前构建机器的架构；安装后的插件无需 Node.js、Python 或 Cargo。SDK 使用仓库内的版本化 `@trove/plugin-sdk@0.1.0` 包，离线复制到 UI 中。

生成结果：

- `dist/packages/`：15 个可安装 `.curio` 包。
- `dist/index.json`：常规测试源，8 个插件 ID / 9 个版本包。
- `dist/faults-index.json`：6 个故障/异常依赖插件，按需安装。
- `dist/invalid/`：22 个无效包、4 个异常源及预期错误码。
- `dist/verification.json`：自动验证的逐项结果、环境和观察项。

在 Trove 添加**本地软件源**，选择 `dist/index.json` 的绝对路径，即可安装常规测试插件。若要测试 HTTP 下载：

```sh
pnpm run serve
# 在底座添加 HTTP 软件源：http://127.0.0.1:8765/index.json
# 用 QA_HTTP_PORT 环境变量更换端口，Ctrl-C 停止。
```

完整步骤、覆盖矩阵与当前限制见 [测试指南](testing.md)。

插件各自通过 `curio.json.version` 管理版本；公开服务契约版本与底座兼容范围分别维护。历史发布索引只追加版本、禁止覆盖同版本产物，详见 [版本与发布](versioning.md)。`pnpm run release:prepare` 将安装包与索引准备到 `source/`，提交并推送后即可通过 Git 仓库源安装。`pnpm run test:release` 验证版本约束。

## 目录

- `curios/<name>/`：各插件独立 Manifest 与公共服务契约。
- `shared/ui/`、`shared/backend/`：测试面板和原生后端源码；构建时复制到各插件。
- `source/index.json`：生产软件源与历史版本索引。
- `tools/`：构建、打包、测试源和真实底座验证适配器。
- `vendor/`：版本化 SDK 分发包与来源说明。

项目依赖使用 pnpm；插件通过版本化的 `@trove/plugin-sdk` 引用 SDK，不通过 `../app` 引用源文件。仅自动验证适配器通过显式的 `TROVE_APP_DIR` 编译待测底座组件，插件构建与运行不依赖该路径。App 仓库保留协议规范和教学模板。

## 发布约定

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