98 lines
6.3 KiB
Markdown
98 lines
6.3 KiB
Markdown
# AGENTS.md
|
||
|
||
本仓库是多模块 Monorepo，演示 **服务端驱动 UI（Server-Driven UI）**：后端用 AndroidX Remote Compose 把 UI 编译成二进制文档，Android 端下载后由 `RemoteComposePlayer` 原生渲染。
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
VibeCoding_ComposeRemote/
|
||
├── ComposeRemoteAndroid/ # 【可改】Android 客户端（Kotlin + Jetpack Compose）
|
||
├── ComposeRemoteServer/ # 【可改】Spring Boot 4 后端（生成 Remote Compose 二进制文档）
|
||
├── remotecompose/ # 【只读】GitHub 开源：Web 编辑器 + JVM 转换器 + .rc 二进制产物
|
||
└── remotecompose-android/ # 【只读】GitHub 开源：纯播放端示例 App
|
||
```
|
||
|
||
> ⚠️ `remotecompose/` 与 `remotecompose-android/` 是上游 GitHub 开源项目，**禁止修改**。
|
||
> 仅可在 `ComposeRemoteAndroid/` 与 `ComposeRemoteServer/` 中编写代码。
|
||
|
||
## 架构与数据流
|
||
|
||
```
|
||
CREATION SIDE (JVM) PLAYBACK SIDE (Android)
|
||
┌──────────────────────┐ binary ┌──────────────────────────┐
|
||
│ ComposeRemoteServer │ .rc bytes │ ComposeRemoteAndroid │
|
||
│ RemoteComposeWriter │ ── HTTP ───▶ │ OkHttp GET → RemoteDoc │
|
||
│ → byte[] (octet) │ (GET /card) │ RemoteComposePlayer 渲染 │
|
||
└──────────────────────┘ └──────────────────────────┘
|
||
```
|
||
|
||
- 后端只负责「创建」文档；前端只负责「播放」文档，**两端都不解析 JSON 布局、不共享创建端源码**。
|
||
- 通信协议：Android 向 `GET /api/remote-ui/card` 发请求，后端返回 `application/octet-stream` 的二进制 `byte[]`，前端用 `RemoteDocument(bytes)` 解码。
|
||
|
||
## 1. ComposeRemoteAndroid（可改）
|
||
|
||
- 类型：Android Application，Kotlin + Jetpack Compose（声明式 UI）。
|
||
- 构建：Gradle（AGP `9.2.1`，Kotlin `2.4.0`，Compose BOM `2026.02.01`）。
|
||
- SDK：`minSdk 29` / `targetSdk 36` / `compileSdk 36.1`，Java 语言级别 11。
|
||
- 关键依赖：
|
||
- `androidx.compose.remote:remote-player-core / -compose / -view:1.0.0-alpha17`（播放端）
|
||
- `com.squareup.okhttp3:okhttp:4.12.0`（下载二进制文档）
|
||
- 网络：`AndroidManifest.xml` 已声明 `INTERNET` 权限，且 `res/xml/network.xml` 允许明文流量（`cleartextTrafficPermitted=true`）。
|
||
- 关键文件：
|
||
- `app/src/main/java/com/ttstd/composeremote/MainActivity.kt` — 入口，`enableEdgeToEdge()`，硬编码服务端地址（`192.168.1.5:8000`）。
|
||
- `app/src/main/java/com/ttstd/composeremote/ui/RemoteUIScreen.kt` — 拉取二进制 → `RemoteDocument` → `RemoteComposePlayer` 渲染；含 loading / error 状态。
|
||
- `ui/theme/` — Material 3 主题（默认未启用 `ComposeRemoteAndroidTheme`）。
|
||
- 构建/运行（在 `ComposeRemoteAndroid/` 内）：
|
||
- `./gradlew :app:assembleDebug`
|
||
- `./gradlew :app:installDebug`（需连接模拟器/设备）
|
||
- 约定：
|
||
- 服务端地址改为常量或 `BuildConfig`/`local.properties` 注入，勿在 `MainActivity` 中硬编码内网 IP。
|
||
- 播放端代码不要引入 `remote-creation-*`（创建端）依赖。
|
||
|
||
## 2. ComposeRemoteServer（可改）
|
||
|
||
- 类型：Spring Boot 4.1.0 Web MVC 应用，Java 17，Maven 构建。
|
||
- 关键依赖：
|
||
- `spring-boot-starter-webmvc`、`jackson-databind`、`lombok`、`spring-boot-starter-test`
|
||
- `androidx.compose.remote:remote-creation-jvm:1.0.0-alpha17`（服务端生成二进制文档）
|
||
- 仓库配置：`maven.google.com`（Remote Compose artifacts 来自 Google Maven）。
|
||
- 关键文件：
|
||
- `src/main/java/com/ttstd/composeremote/server/controller/RemoteUIController.java`
|
||
- `GET /api/remote-ui/card` → `produces = APPLICATION_OCTET_STREAM`，返回二进制 `byte[]`。
|
||
- 内部用 `RemoteComposeWriter`（Profile: `DOCUMENT_API_LEVEL` / `PROFILE`，1080×1920，density 1.0）写 `header` → `startRoot`/`column`/`textComponent` → `encodeToByteArray()`。
|
||
- 构建/运行（在 `ComposeRemoteServer/` 内）：
|
||
- `./mvnw spring-boot:run`（默认端口 8080 → 需与客户端地址一致，例如 8000）
|
||
- `./mvnw clean package`
|
||
- 约定：
|
||
- 新增 UI 时复用 `buildRemoteDocument()` 的 writer/Profile 模式；保持 apiLevel/profiles 与 Android 播放端兼容。
|
||
- 注意 **Remote Compose 版本一致性**：服务端 `remote-creation-jvm` 为 `1.0.0-alpha17`，Android `remote-player` 同为 `alpha17`；而只读的 `remotecompose/server` 用的是 `alpha05`，不要混用。
|
||
|
||
## 3. remotecompose（只读，禁止修改）
|
||
|
||
- 上游：[armcha/remotecompose](https://github.com/armcha/remotecompose)。
|
||
- 内容：浏览器拖拽编辑器（Vanilla JS）、Kotlin/Wasm 预览、`server/`（JVM 转换器，`remote-creation` `alpha05`）、若干 `.json` 布局配置 + 生成的 `.rc` 二进制文档、`index.html` 实时预览。
|
||
- 用途：参考其 `.rc` 文档格式与 JSON→二进制转换逻辑；**切勿在此目录提交改动**。
|
||
|
||
## 4. remotecompose-android（只读，禁止修改）
|
||
|
||
- 上游：[armcha/remotecompose-android](https://github.com/armcha/remotecompose-android)。
|
||
- 内容：纯播放端示例 App，从 GitHub 下载 `.rc` 文件用 `RemoteComposePlayer` 渲染（4 个屏幕 + Compose Navigation）。
|
||
- 用途：播放端架构/组件封装（如 `RemoteDocumentView`、`RemoteConfigFetcher`）的参考实现；**切勿修改**。
|
||
|
||
## 版本与依赖关键约束
|
||
|
||
| 模块 | Remote Compose artifact | 版本 |
|
||
|---|---|---|
|
||
| ComposeRemoteServer | `remote-creation-jvm` | `1.0.0-alpha17` |
|
||
| ComposeRemoteAndroid | `remote-player-*` | `1.0.0-alpha17` |
|
||
| remotecompose/server（只读） | `remote-creation*` | `1.0.0-alpha05` |
|
||
|
||
- 创建端与播放端必须使用**同一 alpha 版本**（`alpha17`）以保证二进制兼容；升级时两端同步升级。
|
||
- 所有 Remote Compose 依赖均来自 Google Maven（`maven.google.com`）。
|
||
|
||
## 通用协作约定
|
||
|
||
- 提交前在各自子项目目录内构建通过（Android: `:app:assembleDebug`；Server: `./mvnw compile`）。
|
||
- 不要触碰 `remotecompose/`、`remotecompose-android/`。
|
||
- 新增「服务端驱动 UI」能力时：后端在 `RemoteUIController` 生成文档，前端在 `RemoteUIScreen` 消费，保持二进制协议一致。
|