compose-preview

Compose Preview

无需 Android Studio 即可将 @Preview 可组合项渲染为 PNG（Android 使用 Robolectric，CMP Desktop 使用 Skia）。CLI、Gradle 插件和渲染器由 compose-ai-tools 提供；MCP 服务由 compose-preview-server 提供。

先渲染

收到渲染或展示预览的请求时，请遵循下面的简短流程。收到设计规范审查请求时，请先使用审查清单，再选择本地、托管或 UI Builder 流程，然后调用工具。已发布的目录和托管在服务端的设计应优先使用托管工具；没有本地检出目录并不意味着需要克隆、使用 Gradle 或配置云环境。若工具不可用，请说明受阻的证据，并遵循集成的设置指南。

连接本地 MCP 服务（compose-preview-server 3.78.0+）后，initialize 指令会说明如何调用它：render_preview preview=<FunctionName>，无需先探索或注册，也不要手动构建模拟对象。请遵循这些指令。此技能还设定了调用预算：常规渲染最多调用三次工具，回复中不包含 base64，且仅在需要查看图像时才读取图像。

第一次调用就是渲染。不要先用 grep 查找预览或读取其源代码：服务会通过函数名称查找。只有渲染失败时才查找相关信息。

1. 渲染。 如果客户端能读取本地文件（Claude Code、Codex、Gemini CLI、OpenCode、Antigravity），请传入 inline=false。结果会提供 pngPath、sha256、尺寸和 changed，不包含图像 token。如果结果列出 otherMatches，只有在对方询问时才渲染其中一项。 如果结果包含 variantChoice，且其 message 要求询问（匹配到多个预览，且宿主未显示选择器），应由对方选择，而不是你来选：回复渲染出的匹配项以及 choices 中的所有条目，并按编号列出，然后询问对方指的是哪一个，并停止。不要替对方选择，也不要把列表缩短成“还有其他变体可选”。如果结果是网格，或对方拒绝选择，则无需提问。
2. 仅在需要时查看。 在描述或评判 UI 之前，先用文件读取工具读取 pngPath；这才是对方看到的内容。如果 changed 或 sha256 已经回答了问题，例如“我的修改生效了吗？”，则跳过读取。只描述你实际看到的内容。如果你无法在此处查看图像，请直说。
3. 简短回复，并附上 pngPath，方便对方打开同一张图。不要写“上图”：在终端或打印模式的测试框架中，对方看不到工具返回的图像。请改为指向 pngPath。

库组件来自目录。 对方指定的是库组件（Material 3、Wear M3 EdgeButton 等），而不是他们自己的预览时，请使用托管目录（compose-catalogs）：调用 catalog_list_previews，然后通过 resources/read 读取已发布的快照。只有在需要通过 catalog_render_preview 修改参数时，才请求 live 访问权限。除非对方提出要求，否则绝不要为了展示库组件而将预览文件添加到对方的项目中。 请参阅 catalog-mcp.md。

批量渲染使用哈希。 一次渲染多个版本、设备、字体缩放比例或语言环境，或进行前后对比时，请传入 observe=hash，或使用 render_matrix 并设置 contactSheet: false；这两种方式都只返回每个单元格的哈希。只有最终屏幕、哈希发生变化的单元格，或必须通过肉眼判断的单元格才获取像素数据：每个此类单元格调用一次 render_preview（传入其 overrides 或 uri，并设置 inline=false），然后读取一次其 pngPath。 设计指南审查。 如果有人要求根据 Android 设计指南审查预览或目录设计，请阅读 design-guidelines.md。其中涵盖无密钥的 Agent 审查、已发布结果和 CLI 的 compose-preview review 工作流，包括明确选择界面、所需图片和覆盖范围不完整等内容。该指南包含在默认技能包中；无需安装可选的 PR 审查包。

将多渲染审查交给 design-reviewer。 如果有 design-reviewer 子 Agent 可用（compose-agent-plugins 插件中就包含一个），请将无障碍、字体缩放、圆形设备和其他矩阵检查委派给它，这样图片就不会占用你的上下文，并转达它的结论和路径。向它提供审查对象、主页/修订版本、目录规则和所需覆盖范围。如果没有可用的子 Agent，请自行执行相同的检查清单，并说明无法委派。 进行常规哈希扫描时，保持 contactSheet: false。如果有人要求与视觉指南进行对比，就必须查看像素：即使没有审查员，也要在自己的上下文中检查所需帧。优先只查看相关的单张图片或范围有限的对比图，绝不能仅凭哈希声称已完成视觉审查。

修改源文件后，再次调用 render_preview。notify_file_changed 为可选操作。如果结果显示已过时，请再调用一次，并使用 force: {"reason": "<why>"}。绝不要运行 ./gradlew、clean，也不要删除 build/ 目录来解决渲染问题；如果强制渲染仍然不正确，请阅读 mcp.md § Troubleshooting （从 compose-preview mcp doctor 开始）。

按需提供详情。 只有当对方询问无障碍或布局时，才添加 details: ["a11y", "layout"]。observe=png 会返回内嵌像素图，供无法读取文件的客户端使用。

没有 MCP 工具？ 使用 CLI：compose-preview show --json --filter <Name>， 然后读取该条目的 pngPath。已过时：使用 --force=<reason>，仅一次。参阅 cli.md。无论采用哪种方式，只有渲染工具的输出才算渲染结果：绝不要使用手工编写的 HTML、CSS 或 SVG 模拟图。渲染失败时，请报告错误信息。

无法预览（需要 ViewModel 或注入的服务）？建议提取一个无状态的内部可组合项，并为其创建预览 （state-hoisting.md）。

安装/更新（仅在缺失时）

使用 compose-preview --version 检查。如果 CLI 缺失，请运行此技能的存根， bash <this skill's dir>/scripts/compose-preview --version：首次运行会安装 CLI 并将其添加到 PATH。其他安装方式、更新方法以及 Gradle 插件均见 setup.md；MCP 配置（本地服务和托管 URL）见 mcp.md。

与平台技能协作

官方平台技能（例如 Android 的 Wear Compose Material 3 技能） 负责 API、依赖项和迁移选择。本技能仅用于渲染和验证：

• 遵循平台技能。 按照平台技能选择要使用的组件、API 或版本。不要把本技能的参考资料当作第二份 API 指南。
• 变更在预期之中。 迁移期间，哈希或图像发生变化是信息，并非回归。只有渲染失败或出现新的无障碍错误才会阻止流程。不要恢复旧截图，也不要调整 UI 来匹配它们。
• 留意目录版本。 托管目录使用一个固定的库版本进行渲染，该版本可能与项目的 libs.versions.toml 不同。参见 catalog-mcp.md § 选择组件。

迁移工作流。 编辑前，对每个文件运行 find_previews_for_file，并使用 render_preview observe=hash 记录基线。按照平台技能进行编辑，然后重新渲染，并将失败和新的无障碍错误（get_preview_data kind=a11y/atf）报告为阻塞项。展示一到三个关键屏幕的前后对比，并检查 Wear 上的小尺寸圆形设备和最大字体缩放。 详情见： wear-ui.md § 验证工作流。

参考索引

只阅读任务所需的内容。

主题	阅读
安装、更新、选择哪些技能、应用 Gradle 插件、零代码初始化脚本	setup.md
CLI 命令、--filter/--id/--force、counts 分类、渲染文件名、SVG 输出、Gradle 任务、用于非预览构建的 build-brief	cli.md
选择哪个 MCP 服务（本地还是托管的 https://preview.coo.ee/mcp）；本地服务设置、工具、历史记录、多工作区、故障排查	mcp.md
交互循环：语义引用、observe 模式、diff_semantics、裁剪、render_matrix（变体/矩阵）、记录 → 测试、失败 kind	agent-loop.md
无障碍（ATF、compose-preview a11y）	a11y.md
每次渲染的数据（无障碍、布局、重组、SVG）	data-products.md
多预览、GIF、@SettledPreview、滚动捕获	capture-modes.md
Wear Compose UI / Wear Tiles	wear-ui.md、wear-tiles.md
CMP :shared 模块	cmp-shared.md
Android XML 可绘制资源 / 图标	resource-previews.md
每次渲染的运行时权限	runtime-permissions.md
可编辑的覆盖参数	override-knobs.md
显示过滤器	display-filters.md
Remote Compose、compose-preview rc	remote-compose.md
托管目录 MCP 工具和授权流程（serve，无需检出代码）	catalog-mcp.md
受限服务访问（compose-preview auth request）	server-access.md
Agent 允许列表、暂存 PNG	permissions.md
云沙箱	agent-cloud.md
VS Code 扩展（供人类使用）	vscode.md

CI 和 PR 审查位于可选的同级技能中： compose-preview-ci（基线、PR 评论 Actions）和 compose-preview-review （基线与分支头部渲染及差异对比）。如需添加，请参见 setup.md § 选择哪些技能。