Compose Preview Catalogs

Compose Preview 服务端

compose-preview serve 背后的服务端：目录托管、实时渲染会话、playground 和浏览器查看器界面。它的历史从 yschimke/compose-ai-tools 中拆分出来；CLI 仍在该仓库中，并会启动此仓库的发行版。

此仓库发布的内容

每次 GitHub 发布都会提供归档文件，Maven Central 上则没有任何内容。

资产	内容
compose-preview-server-<v>.tar.gz	服务端：目录托管、HTTP 路由、playground 和查看器界面。compose-preview serve、browse 和 ui-builder 启动的内容
compose-preview-viewer.html	可移植的 MCP App 查看器；yschimke/compose-preview-mcp 会将其与本地 MCP 服务一起重新发布
compose-preview-mcp-<v>.tar.gz	这是一个桥接包，并非此仓库构建的内容：将 compose-preview-mcp 的最新发行版重新挂载到本次发布的名称下，供早于 compose-ai-tools#5929、仍从此处获取该包的 CLI 使用

Compose/Wasm 前端不是这些发行版的资产。它由 yschimke/compose-ui-builder 构建并发布为该仓库自身发布页面上的 compose-preview-ui-builder-web-<v>.zip，此构建会从那里解析该文件——服务端归档无论如何都会附带一份已解压的副本，而独立 zip 则用于自行提供编辑器，或通过 --ui-builder-dir 指定给现有的 serve 使用。

此处没有任何 Maven 坐标。过去有六个模块会发布——compose-preview-serve、compose-preview-mcp，以及另外四个仅因第一个模块的 POM 声明了它们才出现在 Central 上的模块——这种安排得不偿失。项目依赖会以坐标的形式引用已发布的 POM，因此向 :server 添加依赖就意味着也必须发布该依赖；配置错误导致 3.1.0 发布了 compose-preview-server:ui-builder-export-jvm:unspecified，而 3.3.0 至 3.8.0 发布的 compose-preview-serve 则无法解析。六次发布都无人能解析，所包含的传递依赖也无人需要。

唯一的库使用方是 compose-ai-tools 的 :cli，它针对 compose-preview-serve 编译了两个协议漂移测试。现在这些测试会启动发行版（compose-ai-tools#5436）——serve 无论如何都会运行该制品，因此测试检查的正是实际发布的协议。直到并包括 3.24.0 的已发布坐标仍可在 Central 上解析；之后不会再有新坐标。

render-host 之所以存在，是因为渲染打包后的 bundle 并从 git 中读取预览时间线时不会打开任何套接字，只做这些操作的调用方不应为此引入 ktor-server-*、jmdns 和 kotlin-reflect。它由 compose-ai-tools 发布，而非由此处发布：它所依赖的所有内容都位于该仓库，离线行为也应归属该层 (#180)。它过去是此仓库的 :render-host 模块，发布坐标为 compose-preview-render-host；对于固定使用该坐标的用户，它仍可通过最终的 2.x 版本解析，而新坐标则采用 compose-ai-tools 的版本线。测得的前后对比，以及它有意保留、无法移除的传递依赖，都记录在该仓库的构建文件中；checkRenderHostIsServerFree 也一并迁移了。 UI 构建器位于第二个仓库 — yschimke/compose-ui-builder —，:server 以发行版的形式使用它。:ui-builder-runtime 在该仓库中负责权威持久化设计状态、精确的目录验证以及固定修订版本的导出编排；:server 提供 HTTP/身份验证，并将其精简的渲染请求适配到渲染主机。因此，运行时不依赖 Ktor、守护进程/渲染主机、MCP 或 Compose UI，而离线渲染主机也不依赖 UI 构建器协议或服务接口。三个 jar 和一个 BOM 从 Maven Central 获取，坐标为 gradle/libs.versions.toml 中的 composeai-ui-builder；编辑器归档则来自该仓库的 GitHub 发行版；同时开发两个项目时，-PcomposeUiBuilderDir 会将这四项全部替换为本地检出版本。

此构建有意保持独立于仓库。Compose Preview 实现制品按 gradle/libs.versions.toml 中指定的版本从 Maven Central 获取；wire 合约则从 compose-preview-contracts 单独获取。构建不使用 mavenLocal() 仓库，也不依赖此仓库之外的共享版本目录。只有主动选择时才会启用组合构建 — 对上游项目使用 -PlocalBuilds=tools,daemon,contracts， 对 UI 构建器使用 -PcomposeUiBuilderDir — 对于尚未发布的合约或生成器变更，则通过显式的 本地依赖清单选择从本地检出编译的制品。不设置这些选项时，将保留已发布的依赖关系图。

Java

在 Java 17 或更高版本上运行此发行版。UI 构建器的 PNG/SVG 导出需要 Java 21。

这两个版本号之间存在差异，值得明确说明，而不是让读者从构建文件中自行推断。服务器本身、mcp serve 以及此仓库发布的所有制品都以 Java 17 为目标，因为 compose-ai-tools 的 CLI 使用 Java 17 工具链编译这些制品，其 serve / mcp serve 命令会将此发行版的启动脚本作为独立进程启动，并通过 JAVA_HOME/PATH 查找 java。只有 UI 构建器的渲染器需要更高版本：它光栅化的设计由使用 Java 21 编译的 Compose 预览绘制，打包到渲染包中，再解压到使用服务器自身 JVM 运行的守护进程中。

在较旧的 JVM 上，服务器仍可启动，其他功能也都正常；但 UI 构建器会失去 PNG 和 SVG 导出功能，并在启动时说明检测到的版本以及所需版本。将 JAVA_HOME 指向 Java 21 JDK 即可恢复导出功能；也可以传入 --ui-builder-state-dir none，完全不启用 UI 构建器。已发布的容器镜像 （deploy/image/Dockerfile）基于 Temurin 21 构建，两个版本要求都能满足。

两个最低版本都在 gradle/libs.versions.toml 中分别以 java-server 和 java-ui-builder 声明，相关原因也记录在该文件中。:server:checkServerJvmFloor 会在任何高于 java-server 的内容进入发行版类路径时导致构建失败；渲染包则将 java-ui-builder 作为数据附带，以确保启动消息与其描述的字节内容保持一致。

Renovate 会将 Java 17/21 两条版本线以及 Temurin 21 镜像保留在各自选定的主版本上，同时允许维护更新。采用更新运行时的理由、Java 25 提案的相关依据以及采用更新版本的要求，记录在 Java 版本策略中。

构建

./gradlew check 只需要一个 JDK：17。UI Builder 的前端通道会在其自身仓库中使用 JDK 21 编译，而这里唯一仍需要同时使用两个 JDK 的通道是 visual-harness，它会从检出目录构建该仓库的 Wasm 发行版。Gradle 会在其已扫描的位置（/usr/lib/jvm、SDKMAN、asdf、jabba）查找已安装的 JDK 21；如果找不到，报错会是 No matching toolchains found for requested specification: {languageVersion=21}，解决方法是安装一个，而不是降低目标版本。

./gradlew check ktfmtCheckAll
npm --prefix serve-web ci
npm --prefix serve-web run verify

可独立安装的视觉测试框架位于 preview-harness/。实验性的 Compose/Wasm 前端位于 wasm-ui/。UI Builder 本身——编辑器、渲染器、图片资源和 Jetcaster 测试夹具——位于 yschimke/compose-ui-builder；此构建会从该仓库的发行版中解析其编辑器归档、运行时和导出文件，而测试框架会从该仓库的检出目录构建渲染器和测试夹具发行版。服务端发行版会将编辑器打包到 /ui-builder/；现有按目录限定的 /wasm/<system>/ 预览应用仍是独立的功能和路由。编辑器路由会打开一个围绕冻结版 Jetcaster 设计的交互式 Wasm 编辑器；独立视觉测试框架仍可使用干净的基准测试模式。编辑器会在沙盒 iframe 中挂载精确保留的渲染器运行时，路径为 /ui-builder/runtime/<runtimeId>/，并接收测量得到的节点／插槽几何信息，而不会将编辑器叠加层放入 Compose 树中。目录运行时会在目录代次清理后保留一个按提交固定的精简源描述符，因此较旧的设计版本可以在重启后恢复其精确运行时。压缩归档会共用有界的目录 Blob 池；展开后的历史树则是带有不活动超时和硬性数量上限的进程内租约，而不是无界的第二个制品存储。

Remote Compose 创作扩展由默认关闭的编译时选项 -PuiBuilderRemoteCompose=true 控制。它涉及两个仓库——MCP 适配器部分在此处生成，服务端部分则在 UI Builder 导出时构建到其中，因此启用服务端部分时，需要基于启用了该选项的 UI Builder 检出目录进行构建（-PcomposeUiBuilderDir=…）。请参阅功能范围与验证。

重启后，已配置的目录会在加载期间保留其首页卡片。使用持久卷上的 --catalog-cache-dir 时，每张卡片都可以显示上次成功加载的主图缩略图，并附带小型“正在加载目录…”标签。缩略图的作用范围限定为目录配置的仓库和分支。打开待加载的目录会将其提升到其余启动获取任务之前；已经开始的获取任务会先完成。加载页面会自动重试，直至目录可用。

Agent 插件

从 yschimke/compose-agent-plugins 安装本地 MCP 插件 compose-preview，或安装托管目录和 UI Builder 插件 compose-catalogs。 该指南涵盖每种受支持的 Agent 宿主、来自 yschimke/skills 的规范技能包，以及从旧版 marketplace 迁移。

远程目录 MCP

该服务可以通过 /mcp 上的单个聚合 Streamable HTTP MCP 端点公开所有托管目录。使用 --agent-grants --catalog-mcp 启用；已发布资源需要短时有效的 preview 授权，而按需渲染和结构化数据产品需要 live 授权。该端点与有状态的 UI Builder 创作 MCP 界面相互独立，但两者使用相同的用户身份验证、授权和撤销流程。请参阅目录 MCP 设计与设置指南。

本地守护进程 MCP

Agent 和编辑器插件使用的本地 stdio MCP 服务 compose-preview-mcp 已迁移至 yschimke/compose-preview-mcp，其历史记录 和发布版本也都保留在该仓库，并采用独立的版本线。compose-preview mcp serve 会从该仓库的 发布版本中获取它。相关工具、design_open 编辑器应用和 .rc 查看器的文档见该仓库的 （docs/LOCAL_MCP.md）。本仓库保留由托管的 /mcp 提供的 MCP App 页面 （mcp-app/compose-preview-viewer.html、mcp-app/preview-library.html）；compose-preview-mcp 会按标签从每个发布版本中复制这些页面。

在手机上使用

这些页面可在手机上使用，网站也可安装为带有分享目标的应用：分享截图给它，即可打开附有图片的 Bug 报告。serve --lan 会打印二维码，方便在手机上打开笔记本电脑运行的服务。普通 HTTP 局域网地址不属于安全上下文，因此安装应用、Web Share 和剪贴板功能需要 HTTPS 或 adb reverse。参见 在手机上使用 Compose Preview。

空间与 WebXR 预览

可移植包可以将 XR 预览发布为版本 1 的 SpatialScene 文档及其面板纹理：

previews/<preview-id>.spatial/scene.json
previews/<preview-id>.spatial/<panel>.png

查看器会在可旋转的 Three.js/WebGL 场景中打开这些场景；当浏览器提供 immersive-vr WebXR 会话时，还会显示 进入 VR。WebXR 需要安全上下文，因此头显必须通过 HTTPS 访问服务（localhost 仍适用于桌面 WebGL 开发）。上传的包只能包含 JSON 场景文档和 PNG/JPEG/WebP 纹理；所有资源都通过场景同源的 /spatial/ 路由提供。

使用独立发行版进行构建和运行：

./gradlew :server:distTar
tar -xzf server/build/distributions/compose-preview-server-*.tar.gz
./compose-preview-server-*/bin/compose-preview-server help

二进制文件有五个命令，使用 help 可查看：

命令	功能
serve	托管预览——获取的包、已发布的目录，或带有 --module / --discover 的本地模块 @Preview 函数。
ui	构建本项目的预览，并启动 Compose UI 构建器。
playground	允许使用代码片段编译通道的 serve。
design	从已启动的服务渲染、导出或读取 UI 构建器设计。这是唯一不提供服务的命令。
help [command]	命令列表，或某个命令的选项。

即使不在命令前指定命令，也仍可传入标志：compose-preview-server --module app 等同于 compose-preview-server serve --module app，并继续受支持。

本地模块页面（serve --module / --discover，以及 compose-preview browse）有一个 重新构建按钮：编辑后，它会请求构建主机运行 :<module>:composePreviewCompile，并显示结果，无需重启服务。仅类发生变化时，正在运行的守护进程会替换这些类，并清除缓存的渲染结果；守护进程的类路径或预览集发生变化时，会话会基于新构建重启。构建失败时，屏幕上会保留上一次成功的渲染结果。同一个 POST /{session}/rebuild 也支持 Bazel 工作区，其构建主机会通过重新构建模块目标来响应编译请求。

browse 还会在保存时重新构建（--no-watch 可关闭此功能；serve 则通过 --watch 启用）。它会监视 Gradle 模块的项目目录，跳过 build/ 和工具状态目录；对于 Bazel 模块，则监视其源目录，并在一连串保存操作结束后重新构建一次。已打开的页面会监听长轮询 GET /{session}/reload：新渲染结果会就地替换图片，重启会重新加载页面，构建失败时会显示包含原因的 stale:，同时保留上一次成功的渲染结果。Gradle 模块之外的编辑（例如相邻模块或共享构建脚本）不会受到监视；请点击重新构建。 ui 需要一个构建主机——compose-preview 二进制文件——因为发现并构建本地 Gradle 项目这项工作，是此服务通过管道请求它完成的，而不是由服务自行完成。构建器的调色板是打包好的设计系统目录；ui 所做的，是将 --ui-builder-components 指向模块中发现的 components.json，让 Compose 导出为你的可组合项生成调用点。在已安装 CLI 的代码检出目录中：

compose-preview-server ui --module app

design 是这条流程中的客户端部分，也是这里唯一不会启动服务的命令：它会与已运行的服务通信——本地 serve 或某个部署——并将设计的像素或生成的源代码写入文件。否则，会话就得重新实现这一过程：用 curl 请求 /mcp，用 jq 解包信封，再用 base64 -d (#529)：

export COMPOSE_PREVIEW_TOKEN=...          # or let the command ask a human to approve a grant
compose-preview-server design list --server https://preview.example.com
compose-preview-server design status --workspace . --summary
compose-preview-server design render spotify-wear-widget -o cover.png
compose-preview-server design export spotify-wear-widget -o Widget.kt
compose-preview-server design get spotify-wear-widget > design.json

凭据从 $COMPOSE_PREVIEW_TOKEN 读取（或读取较旧的 $COMPOSE_PREVIEW_UI_BUILDER_TOKEN，scripts/ui-builder/design-sync.mjs 会读取此变量），绝不会从标志读取。如果这两个变量都未设置，或者重启后授权已失效，该命令会运行服务自身的设备代码流程：打印批准链接和代码，等待用户操作，然后继续执行。若导出被拒绝，命令会将生成器自身的诊断信息输出到 stderr，并以非零状态码退出，不写入任何内容，因此适用于 CI。

design status 是范围受限的 SessionStart 探测：它会读取代码检出目录中的 ui-builder/designs/index.json，统计服务器主页设计上尚未确认的评论，并将每个受跟踪的临时副本与服务器上的当前文档进行比较。它绝不会启动授权流程，也绝不会跟随受跟踪的服务器 URL 跳转到其他源；--summary 会打印一行脱敏信息（没有需要处理的事项时则不打印）。--json 会输出带版本的状态信封。

--local 是该命令中完全不需要服务器的部分：它会运行与服务器相同的生成器、编译器和渲染守护进程，在本地针对磁盘上的目录包执行——并说明缺失帧的原因，而不只是报告缺失；线上的响应无法做到这一点 (#551)。这让有问题的主机可以调试：design get 会捕获其文档（这是一次读取，并非可疑的渲染流程），该文件可在任何地方重放。

compose-preview-server design get spotify-wear-widget --server https://preview.example.com > doc.json
compose-preview-server design render --document doc.json --local \
  --catalog wear-m3.bundle --assets ./assets -o replay.png
compose-preview-server design export --document doc.json --local   # the generated Kotlin, no server

本地渲染会打印解析出的类路径、构建的守护进程启动器以及编译器自身的诊断信息；--components <catalog>=<components.json> 用于指定记录驱动型目录的调用点所依据的记录，与 serve --ui-builder-components 的行为完全相同。

浏览器客户端可以通过 GET /api/ui-builder/v1/catalogs/{system}/templates 读取目录已发布的起始文档。此接口需要 UI-builder 读取权限，并遵循主机的目录限制。共享的 CatalogTemplateDocumentsV1 响应包含模式版本、完整的 catalogPin（系统、修订版本、能力摘要和运行时），以及以模板 ID 为键的 templates 映射。选择器顺序取自目录的有序元数据，而非文档映射。如果目录刷新后，文档尚未与已提供的能力对齐，则会返回 409；客户端应重试并保留上一组匹配项。响应使用 Cache-Control: no-store；离线编辑器会在浏览器存储中，按完整目录固定信息显式存储经过验证的文档。

已登录用户可以在 /ui-builder/designs 浏览服务允许其读取的所有设计。页面会将自有设计与他人共享的设计分开显示，说明无法打开某项设计的确切服务端原因，并允许所有者直接管理共享设置。此页面限定于当前操作者，与 /admin/ui-builder 上面向运维人员的全部设计页面无关。 /ui-builder/projects 将多个设计文件、共享 JSON 资源和协作者整合到一个应用工作区中。项目可以加载来自 GitHub、固定到特定提交的 .uid 文件，并以拉取请求的形式提出经过审核的编辑，同时显示每个设计的规范主页；请参阅 UI_BUILDER_HOSTED_PROJECTS.md。

已提供服务的目录中的可组合项也可以作为组件包提供给构建器的目录内部使用（--ui-builder-packs confetti-mobile=mobile,confetti-wear=wear），作者可在编辑器设置中启用此功能；请参阅 docs/design/UI_BUILDER_COMPONENT_PACKS.md。

发布版本会将该发行包附加到 GitHub 发布版本，然后发布可复用的 ghcr.io/yschimke/compose-preview-host 镜像。使用 deploy/example 启动自己的实例，这是一个具有持久化状态和可选 HTTPS 的独立 Compose 示例；当你需要滚动发布、自动更新或大型主机时，可扩展到 deploy/image 中功能齐全的技术栈。部署自己的实例 介绍了此仓库提供的内容，以及哪些内容应属于你自己的部署配置。

发布

release.yml 中只有一条流水线：构建 compose-preview-server-<v>.tar.gz，并将其与 compose-preview-viewer.html 一起附加到 GitHub 发布版本，然后构建 compose-preview-host 镜像。

在该流水线成功之前，GitHub 发布版本会保持为草稿，因此构建失败时不会留下资源文件尚不存在的标签。

过去还有第二条可跳过的 Maven 流水线，可通过 release:no-maven 标签和 publish_maven 工作流输入将其关闭。随着发布功能的取消，这两者也都已移除——现在每次发布都会执行该标签过去要求的操作。

仓库边界

checkServeModuleBoundary 会遍历解析后的运行时类路径，包括传递依赖。它会拒绝项目依赖、渲染器／守护进程实现、Gradle 插件，以及任何未注册的 ee.schimke.composeai 坐标。只有在有意调整并经过审核的依赖下限时，才更新其允许列表。

为保持二进制／源码连续性，源代码包仍为 ee.schimke.composeai.cli.serve。包重命名与仓库归属彼此独立，不属于此次提取的一部分。