# 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` 消费，保持二进制协议一致。