SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场compose-preview

compose-preview

编程与开发

查看项目

更新于 10-16 03:30

技能介绍

Compose Preview（compose-preview）是一个把 Jetpack Compose 或 Compose Multiplatform 的 @Preview 可组合项渲染为 PNG 的工具，无需 Android Studio。Android 通过 Robolectric 渲染，CMP Desktop 通过 Skia 渲染。CLI、Gradle 插件和渲染器来自 compose-ai-tools，MCP 服务器来自 compose-preview-server。

一、用途 用于在不打开 Android Studio 的情况下，将 Compose 预览渲染成图片查看，或在代理（agent）工作流中执行渲染、比对与验证。适用于按名称调用预览渲染、变体/设备/字体缩放/区域的多渲染扫描、设计规范评审、无障碍与布局检查等。

二、主要能力

  1. 渲染：通过 MCP 服务器（compose-preview-server 3.78.0+）的 render_preview preview=<FunctionName> 直接按函数名渲染，无需先检索预览或阅读源码；服务器按函数名查找。
  2. 结果信息：结果为 pngPath、sha256、dimensions 和 changed。客户端可读本地文件（如 Claude Code、Codex、Gemini CLI、OpenCode、Antigravity）时传 inline=false，则不返回图像 token。
  3. 多匹配处理：若结果包含 otherMatches，仅在用户询问该预览时才渲染；若带有 variantChoice 且提示需要询问（多个预览匹配且宿主未显示选择器），由用户选择，需回复已渲染结果并把 choices 中每一项列为编号列表询问，不得自行挑选或简化为“其他变体可用”。
  4. 图像查看：只有在需要描述或判断 UI 时才读取 pngPath；若 changed 或 sha256 已能回答问题（如“我的修改是否生效”），可跳过读取。只描述所见内容；若在此处无法查看图像，应明确说明。
  5. 库组件：当用户指定的是库组件（如 Material 3、Wear M3 EdgeButton）而非自己的预览时，使用托管目录 compose-catalogs：catalog_list_previews，再用 resources/read 读取已发布快照；仅需调整旋钮时才请求实时访问 catalog_render_preview。未经用户要求，不要向用户项目添加预览文件。
  6. 扫描：多渲染（变体、设备、字体缩放、区域、前后对比）时传 observe=hash 或使用 render_matrix 且 contactSheet: false，仅返回每个单元格的哈希；只对最终画面或哈希变化的单元格获取像素。
  7. 设计规范评审：按 design-guidelines.md 执行，涵盖无密钥代理评审、已发布结果和 CLI 的 compose-preview review 循环，包括明确的界面选择、必需图片和不完整覆盖。
  8. 多渲染评审委托：若存在 design-reviewer 子代理（compose-agent-plugins 插件提供），可将无障碍、字体缩放、圆形设备等矩阵检查委托给它，以免图片进入自身上下文，并转达其结论与路径；无该代理时自行执行同一清单并说明委托不可用。常规哈希扫描保持 contactSheet: false；被要求的视觉规范对比需要像素，即使无评审者也要检查其必需帧。只使用相关的单张图片或有界对比表，不得仅凭哈希声称完成视觉覆盖。
  9. 源码修改后：再次调用 render_preview；notify_file_changed 为可选。若结果标记为过期，仅再用 force: {"reason": "<why>"} 调用一次。不要为追查渲染而运行 ./gradlew、clean 或删除 build/ 目录；若强制渲染仍错误，阅读 mcp.md 的 Troubleshooting（先执行 compose-preview mcp doctor）。
  10. 细节按需添加：仅在用户询问无障碍或布局时添加 details: ["a11y", "layout"]；observe=png 会为无法读取文件的客户端返回内联像素。

三、使用方式

  1. MCP 路径：接入本地 MCP 服务器后，按其 initialize 指令调用 render_preview preview=<FunctionName>，无需先探索或注册，也不要手工构造 mock。常规渲染最多三次工具调用，回复中不含 base64，仅在需要查看时才返回图像。第一次调用即渲染，不要先 grep 或阅读源码；只有渲染失败时才去查询。
  2. 无 MCP 工具时用 CLI：compose-preview show --json --filter <Name>，然后读取返回条目的 pngPath。过期时用 --force=<reason>，仅一次。详见 cli.md。
  3. 回复要求：简短回复并给出 pngPath，便于用户打开同一图像；不要写“上图”，因为在终端或 print 模式宿主中用户看不到工具返回的图像。
  4. 安装/更新（仅在缺失时）：先用 compose-preview --version 检查。安装技能与 CLI：npx skills add yschimke/skills --global --yes --skill compose-preview --skill compose-ui-builder；无 Node 时：curl -fsSL https://raw.githubusercontent.com/yschimke/skills/main/scripts/install.sh | bash。更新用 compose-preview update（技能用 npx skills update）。插件设置、MCP 注册和 Gradle init 脚本见 setup.md。
  5. 不可预览的情况（如需要 ViewModel 或注入服务）：建议抽取无状态的内部可组合项再预览（state-hoisting.md）。

四、适用场景

  • 通过函数名快速渲染某个 @Preview 并查看结果。
  • 同一预览在多变体、多设备、多字体缩放、多区域下的批量扫描与哈希比对。
  • 修改源码后确认改动是否生效。
  • 按 Android 设计规范对预览或目录设计进行评审。
  • 无障碍（ATF、compose-preview a11y）、布局、重组、SVG 等逐渲染数据的检查。
  • Wear Compose UI / Wear Tiles、CMP :shared 模块、Android XML drawable/图标、运行时权限等专项预览。
  • 远程 Compose、远程目录 MCP（serve，无需 checkout）、受限服务器访问、代理允许列表、云沙箱等场景。

五、与平台技能协作 官方平台技能（如 Android 的 Wear Compose Material 3 skill）负责 API、依赖与迁移选择；本技能只负责渲染与验证。应遵循平台技能决定使用哪个组件、API 或版本，不要将本技能的参考当作第二份 API 指南。迁移期间哈希或图像变化属于信息而非回归；只有渲染失败或新增无障碍错误会阻塞。不要恢复旧截图或为匹配旧图而调 UI。托管目录渲染固定库版本，可能与项目的 libs.versions.toml 不同，详见 catalog-mcp.md § Choosing a component。迁移工作流：编辑前对每个文件执行 find_previews_for_file 并以 render_preview observe=hash 记录基线；按平台技能编辑后重新渲染，把失败和新增无障碍错误（get_preview_data kind=a11y/atf）作为阻塞项报告；对一到三个关键界面展示前后对比，并在 Wear 上检查小圆形设备和最大字体缩放。详见 wear-ui.md § Verification workflow。

六、限制与注意

  • 只有渲染工具的输出才算渲染，绝不能用手工构造的 HTML、CSS 或 SVG mock 代替。渲染失败需报告其错误。
  • 不要向用户项目添加预览文件来展示库组件，除非用户要求。
  • 多匹配且有 variantChoice 提示询问时，选择权在用户，不得替用户决定。
  • 不得仅凭哈希声称完成视觉覆盖；被要求的视觉规范对比需要检查像素。
  • 详细主题（安装与 Gradle 插件、CLI 命令与参数、本地 MCP 服务器工具与历史、交互循环、无障碍、逐渲染数据、多预览与 GIF 捕获、Wear、CMP shared 模块、XML 资源预览、运行时权限、覆盖旋钮、显示过滤器、远程 Compose、目录 MCP、受限服务器访问、代理允许列表、云沙箱、VS Code 扩展等）分别见对应的 setup.md、cli.md、mcp.md、agent-loop.md、a11y.md、data-products.md、capture-modes.md、wear-ui.md、wear-tiles.md、cmp-shared.md、resource-previews.md、runtime-permissions.md、override-knobs.md、display-filters.md、remote-compose.md、catalog-mcp.md、server-access.md、permissions.md、agent-cloud.md、vscode.md 文档。
  • CI 与 PR 评审位于可选同级技能 compose-preview-ci（基线、PR 评论 Actions）和 compose-preview-review（base 与 head 渲染及 diff），可用 npx skills add yschimke/skills --global --yes --skill <name> 添加。
  • 本工具的具体收费、价格、平台支持范围、渲染效果承诺等信息，资料中暂未提供。