VibeCoding_ComposeRemote/AGENTS.md

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。
• 内容：浏览器拖拽编辑器（Vanilla JS）、Kotlin/Wasm 预览、server/（JVM 转换器，remote-creation alpha05）、若干 .json 布局配置 + 生成的 .rc 二进制文档、index.html 实时预览。
• 用途：参考其 .rc 文档格式与 JSON→二进制转换逻辑；切勿在此目录提交改动。

4. remotecompose-android（只读，禁止修改）

• 上游：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 消费，保持二进制协议一致。