compose-ai-tools：用 AI 视觉重新定义 Compose 开发体验

一个让 AI「看见」屏幕的工具

想象这样一个场景：你的 AI 编程助手刚刚修改了 10 个 Compose 界面文件，它信心满满地提交了代码——然而实际的渲染效果却面目全非。这不是 AI 的错，而是 AI 根本没有「眼睛」看屏幕。

compose-ai-tools 正是为解决这一痛点而生：它将 Jetpack Compose 的 @Preview 注解直接渲染为 PNG 图片，让 AI 编程 agent 能够真正「看见」自己写出的界面，从根本上解决了 AI 辅助 UI 开发中最大的信息鸿沟。

---

背景：AI 编程时代的视觉盲区

2024-2025 年，AI 编程助手（Claude Code、GitHub Copilot、Codex）已经能够独立完成复杂的功能开发。但当涉及到 UI 开发时，AI 却面临一个根本性的困境——它无法感知屏幕上的像素。

传统的 UI 开发流程中，开发者需要本地运行应用才能看到效果，每次修改都要经历「写代码 → 编译 → 运行 → 查看」的长反馈循环。即便是 AI，也要依赖人类的眼睛来验证代码变更是否符合预期。

yuri-schimke（项目作者）敏锐地捕捉到了这个痛点，开发了 compose-ai-tools。它的核心思路简洁而优雅：既然 @Preview 是 Compose 的标准声明方式，那就直接把它渲染出来。无需修改任何应用代码，无需额外配置，AI 和人类都可以通过命令行获取预览图片。

---

工作原理：四步完成 Preview 到 PNG 的转换

第一步：自动发现（Discovery）

compose-preview 插件会在 Gradle 构建过程中扫描项目编译产物（.class 文件），利用 ASM 字节码框架检测所有带有 @Preview 和 @Preview.Container 注解的方法。这些注解支持嵌套——即一个方法上的注解可以引用另一个带有 @Preview 的方法，形成链式预览集合。

扫描结果写入 build/compose-previews/previews.json，包含每个预览的名称、设备类型、尺寸、背景色、国际化等元数据。

第二步：Desktop 渲染（Skiko）

对于 Compose Multiplatform Desktop 目标，compose-preview 通过以下流程渲染：

1. 启动子进程，加载目标模块的完整 classpath
2. 通过 Compose 运行时反射 API 按名称定位目标 Composable 函数
3. 创建无头 ImageComposeScene（2x 密度）
4. 设置预览背景色、注入 LocalInspectionMode = true
5. 渲染两帧（第二帧让动画效果稳定下来）
6. Skia 表面编码为 PNG 并写入输出文件

第三步：Android 渲染（Robolectric）

对于 Android 目标，compose-preview 启动一个 Robolectric 测试沙箱（graphicsMode=NATIVE, pixelCopyRenderMode=hardware）来运行 Gradle Test 任务：

1. 通过 createAndroidComposeRule 引导 ComponentActivity
2. 通过 RuntimeEnvironment.setQualifiers 应用预览限定符（尺寸、密度、语言、设备形态等）
3. 暂停 Compose 时钟（autoAdvance = false）并步进固定时间，使无限动画能确定性终止
4. 通过 captureRoboImage（底层走 ShadowPixelCopy → HardwareRenderer → ImageReader）捕获视图并压缩为 PNG

第四步：AI 集成（MCP Server）

compose-preview 捆绑了 MCP（Model Context Protocol）服务器，将预览能力暴露给所有 MCP 感知的 AI agent：

• 每个 @Preview 都是一个 compose-preview:// URI 资源，agent 可直接读取获取最新 PNG
• 支持推送通知——预览重新渲染时自动推送 notifications/resources/updated
• 提供 register_project、render_preview、history_diff 等工具
• 支持多工作空间：同一 MCP 服务器可同时管理多个项目或同一仓库的多个 Git worktree

---

核心功能：从命令行到 VS Code

一键安装（推荐方式）

curl -fsSL https://raw.githubusercontent.com/yschimke/skills/main/scripts/install.sh | bash

这条命令同时安装 CLI 和 agent skill，安装后即可直接用 compose-preview render 命令渲染所有预览。无需修改任何项目文件——CLI 在运行时将自己注入 Gradle 构建过程。

VS Code 插件

在 VS Code 扩展市场搜索「Compose Preview」安装，即可在编辑器内实时预览 Compose 界面，无需打开模拟器或 Android Studio。支持 VS Code 衍生产品（Cursor、Windsurf、VSCodium）和 Open VSX。

MCP 集成

compose-preview mcp install

该命令自动检测本地安装的 AI 编程工具（Claude Code、Codex、Antigravity）并注册 MCP 服务器。注册后，AI agent 在处理 Compose 项目时会自动获得视觉能力。

---

部署方式：多层次覆盖

compose-ai-tools 提供了从本地开发到云端托管的完整部署选项：

本地 CLI：安装后直接在项目目录运行 compose-preview render，零配置。

Docker 一键部署：deploy/image/docker-compose.yml 提供了完整的容器化方案，预构建镜像（ghcr.io/yschimke/compose-preview-host）无需本地编译即可运行预览服务。使用 Caddy 作为反向代理，支持 TLS。部署命令仅需 docker-compose up。

云端部署：项目提供了 Google Cloud Run 和 Oracle VPS 的部署配置，适合 CI/CD 流水线集成。

Daemon 模式：可选的长驻进程模式，保持 Robolectric / Compose-Desktop 环境热启动，使重复渲染速度大幅提升。

---

技术亮点与设计哲学

零侵入设计

整个工具链对目标项目完全零侵入。CLI 模式下无需在项目中添加任何依赖或配置——它直接通过 Gradle 注入运行时。Gradle 插件模式仅需一行 apply plugin: "ee.schimke.composeai" 即可启用。

确定性渲染

Android 渲染模式下，Compose 时钟被暂停并步进固定时间，确保无限动画（如 loading 动画）不会导致渲染进程卡死。这对于 AI agent 的自动化流水线至关重要。

数据产品（Data Products）

除了 PNG，compose-preview 还可输出结构化数据：语义树（accessibility tree）、布局树、主题 token、重合成热图、文本绘制信息、资源快照等。这些数据为 AI 编程 agent 提供了更丰富的上下文信息。

---

局限与挑战

平台限制：目前仅支持 Android（通过 Robolectric）和 Compose Multiplatform Desktop（通过 Skiko）。iOS（Compose iOS）和 Web（Compose JS/WASM）暂不支持渲染。

硬件要求：Android 渲染依赖 Robolectric + Android SDK，内存占用较高（建议 4GB+）。Desktop 渲染依赖本地 GTK/Qt 环境。

代理网络问题：中国区网络访问 GitHub 资源可能不稳定，部分安装脚本需要配置代理。

版本兼容性：要求 Java 17+、Gradle 8.13+、Android Gradle Plugin 8.13.0+、Kotlin 2.0.21+，对老项目升级成本较高。

---

行业意义：AI 编程的视觉基础设施

compose-ai-tools 的出现代表了一个重要趋势：AI 编程工具正在从「代码生成器」进化为「具备感知能力的开发伙伴」。视觉反馈是 UI 开发的核心需求，能看见屏幕的 AI 代理将显著提升 UI 代码的正确率和开发效率。

该项目已被用于真实生产环境——例如 yschimke/meshcore-mobile 项目中，AI agent 直接从 @Preview 渲染 Play Store 截图，替换了原本手工绘制的 PNG 素材。

---

快速上手

# 一键安装 CLI + agent skill
curl -fsSL https://raw.githubusercontent.com/yschimke/skills/main/scripts/install.sh | bash

# 渲染所有预览为 PNG
compose-preview render

# 安装 MCP 服务器（让 AI agent 获得视觉能力）
compose-preview mcp install

# VS Code 用户：扩展市场搜索 "Compose Preview"

官方网站：https://yschimke.github.io/compose-ai-tools/