preview-screens

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出消息，请在继续之前向用户显示。

共享说明：shared-instructions.md ——请先阅读。

屏幕预览

生成一个独立的 HTML 文件，将应用中的每个屏幕渲染为手机边框模型（375 × 812），并提供标签页导航和深色／浅色切换。Agent 会读取 TSX 文件，理解 Tamagui 组件树，并生成等效的 HTML/CSS——不会以编程方式解析 TSX。

适用场景

• 生成屏幕后，无需运行 Metro/Expo 即可快速查看视觉预览
• 与利益相关者分享可直接截图的模型
• 部署前验证布局

不适用场景

• 运行实际应用 → 使用 npm run dev
• 修改屏幕 → 使用 /edit-app；screen-builder 是由编排技能调用的内部 Agent

工作流

1. 定位项目 → 2. 发现屏幕 → 3. 读取参考映射 → 4. 读取并转换每个屏幕 → 5. 组装 preview.html → 6. 写入文件 → 7. 在浏览器中打开

---

步骤 1 — 定位项目

确定工作目录：

• 如果 $ARGUMENTS 包含 --working-dir <path>，则使用该路径。
• 否则使用当前工作目录。

验证项目：

Glob pattern="power.config.json" path="<working_dir>"

如果不存在，检查是否有 package.json。如果两者都不存在，则报告错误并停止。

如果存在 memory-bank.md，读取它以获取页面标题所用的项目名称：

Grep pattern="^# " path="<working_dir>/memory-bank.md"

备选方案：从 package.json 中读取 name。

步骤 2 — 发现屏幕

遥测检查点：discover_app_screens

查找应用目录下的所有 TSX 文件：

Glob pattern="app/**/*.tsx" path="<working_dir>"

排除以下模式——它们不是屏幕：

• _layout.tsx（导航布局）
• +not-found.tsx（Expo Router 错误边界）
• 位于以 . 开头的目录中的文件
• 如果应用根目录下的 index.tsx 仅包含身份验证重定向，则排除（读取文件进行确认）
• 如果至少存在一个其他可见屏幕，则排除未经修改的模板 app/(app)/home.tsx。 仅当其源文件仍同时包含 Power Apps Standalone 和 Build your first screen by connecting data sources 时，才将其识别为该模板。 如果它是唯一的可见屏幕，则保留它，以确保预览不会为空。

根据文件路径推导屏幕名称：

• app/(app)/home.tsx → “主页”
• app/(app)/recipes/index.tsx → “食谱”
• app/(app)/recipes/[id].tsx → “食谱详情”
• app/login.tsx → “登录”
• app/oauth-callback.tsx → 跳过（不是可见屏幕）

如果工作目录中存在 native-app-plan.md，读取其 ## Screens 部分，获取适合用户阅读的标签。

构建有序列表：[ { path, screenName, screenId } ]。

默认标签页排序——主页优先，然后是两个详情页，最后是其他屏幕。 第 5 步会将第一个条目标记为 active，因此下方的顺序会直接决定用户打开 preview.html 时首先看到的屏幕。

按以下优先级对列表排序：

1. 主页／仪表盘优先。 优先选择 native-app-plan.md 标识为主页或落地页的屏幕。 否则，按以下优先级使用第一个匹配路径的剩余屏幕： app/(app)/home.tsx、app/(app)/index.tsx、app/(app)/dashboard.tsx、app/index.tsx （仅当它是真正的主页，而非身份验证重定向或第 2 步排除的未经修改的初始模板路由时）。
2. 接着最多排列两个详情页。 “详情页”是指路由片段使用动态参数的任意 TSX 屏幕——文件路径中包含 [ 和 ]（例如 app/(app)/recipes/[id].tsx、app/(app)/orders/[orderId]/edit.tsx）。按发现顺序取前两个（按路径字母顺序排列即可）。
3. 然后排列其他所有屏幕，顺序与发现时一致。

如果详情页少于两个，则只纳入现有详情页，然后继续排列其他屏幕——不要为了凑足三个而加入非详情页。

不要丢弃任何屏幕——此规则仅调整顺序。每个发现的屏幕仍会获得一个标签页。

Step 3 — 阅读映射参考

加载 Tamagui 到 HTML 的映射参考：

Read file_path="${PLUGIN_ROOT}/shared/references/tamagui-html-mapping.md"

熟悉以下内容：

• 组件 → HTML 元素和 CSS 映射（第 1 节）
• Token → 间距、字体大小、颜色的像素值（第 2 节）
• 转换指南——占位符规则、图标替换、需要跳过的内容（第 3 节）
• 手机框架 HTML 模板（第 4 节）——这是外层框架

同时检查项目是否有自定义品牌 Token：

Glob pattern="tamagui.config.ts" path="<working_dir>"

如果找到，请阅读并提取所有自定义颜色 Token（查找 tokens: { color: { ... } }）。将它们作为额外的 CSS 自定义属性添加到生成的 HTML 中。

Step 4 — 阅读并转换每个屏幕

遥测检查点：render_screen_preview_frames

开始前打印：

"→ 正在将 个屏幕读取并转换为 HTML/CSS（每转换一个屏幕就打印一次）。"

对于步骤 2 中有序列表里的每个屏幕：

1. 读取完整的 TSX 文件。

2. 识别组件树。 遍历 JSX return 语句，记录每个 Tamagui 组件、其 props 和子元素。

3. 使用步骤 3 中的映射生成等效的 HTML/CSS：

   • YStack → <div style="display:flex; flex-direction:column; ...">
   • 将每个简写 prop 映射为对应的 CSS（flex={1} → flex:1，bg="$color2" → background:var(--color2) 等）
   • 将 Token 值映射为像素值（p="$4" → padding:16px）
   • 将 <Ionicons name="..." /> 图标替换为对应的 Unicode 字符（参见映射参考第 3 节，指南 4——图标替换表使用 Ionicons 名称）

4. 处理动态内容：

   • 对数组使用 .map() → 生成 3–4 个有代表性的占位项
   • useQuery / useMutation → 仅显示已填充状态（跳过加载/错误分支）
   • 表单 defaultValues → 使用这些值预填输入框

原生 PDF/签名笔控件需要如实地静态模拟：

• PDF 查看器操作 → 渲染紧凑的报告/PDF 区块，其中包含文件名、生成时间、存储标签（例如 Stored in Evidence PDF File 或 On-device share only）以及禁用状态的 View PDF 按钮。如果来源 URL 不是明确的 HTTPS 地址，请标注为 Preview unavailable in browser，不要显示虚假的查看器。
• 生成的 PDF 报告 → 渲染已生成/就绪状态，以及计划或代码中注明的任何持久化标签，例如 Uploads to Evidence PDF File。不要嵌入浏览器 PDF iframe，也不要暗示预览中可以运行原生查看器。
• 签名笔输入 → 渲染签名板占位区域，显示笔迹示例和已捕获的预览状态。已知时请注明持久化标签，例如 Stored in Signature Image 或 Uploads to Signature File。
• 不要添加浏览器点击处理程序，以免虚假模拟签名笔输入捕获、打开原生 PDF 查看器、分享、打印或上传。此预览仅供视觉展示。

5. 生成一个 <div class="screen" id="screen-{screenId}">，将转换后的 HTML 包裹在其中。

在元素上使用内联样式。每个屏幕的 HTML 都应自成一体（除主题变量外，不同屏幕之间不共享 CSS 类）。

Step 5 — 组装 preview.html

使用映射参考（第 4 节）中的手机框架模板作为外层框架。

替换占位符：

• {{APP_NAME}} — 步骤 1 中的项目名称
• {{TABS}} — 每个屏幕对应一个 <button class="tab" ...>，第一个标签页添加 active 类
• {{SCREENS}} — 步骤 4 中生成的所有屏幕 <div> 块，第一个屏幕添加 active 类

如果项目有自定义品牌 Token（来自步骤 3），请将其添加到 :root CSS 块中。

Step 6 — 写入文件

遥测检查点：write_screen_preview_document

Write file_path="<working_dir>/preview.html"

打印确认信息：

✅ Preview generated: <working_dir>/preview.html
   Screens: <N> (<comma-separated list of screen names>)
   Toggle: dark/light mode button in top-right

第 7 步 — 在浏览器中打开

遥测检查点：open_screen_preview

不要提示用户。 <working_dir>/memory-bank.md 中的 visual_companion 标志已经记录了答案；再次询问是多余的。此标志由项目创建期间的 /design-system（第 6.75 步）设置；如果未运行 /design-system，则默认为 yes。

读取标志并执行操作：

grep -E "^visual_companion:[[:space:]]*(yes|no)" '<working_dir>/memory-bank.md' 2>/dev/null

标志	操作
MOBILE_APP_EMBED_PREVIEW=1	输出链接并停止。所属编辑计划会嵌入这些屏幕。
visual_companion: no	输出链接并停止。不要自动打开。
visual_companion: yes（或缺少 memory-bank，或独立调用）	输出链接，然后自动打开。

visual_companion: no — 输出：

“预览地址：file://<working_dir>/preview.html（Visual Companion 已关闭 — 请手动打开。）”

否则 — 一次性输出链接并自动打开，不要提示：

“预览地址：file://<working_dir>/preview.html — 正在打开。”

然后依次尝试适用于操作系统的打开程序；如果都不起作用，则回退为输出链接：

open '<working_dir>/preview.html' 2>/dev/null \
  || xdg-open '<working_dir>/preview.html' 2>/dev/null \
  || MOBILE_APP_PREVIEW_PATH='<working_dir>/preview.html' \
     powershell.exe -NoProfile -Command 'Start-Process -FilePath $env:MOBILE_APP_PREVIEW_PATH' 2>/dev/null \
  || printf '%s\n' 'Could not auto-open. Open this URL in your browser: file://<working_dir>/preview.html'

open 仅适用于 macOS；该调用链还会尝试 Linux（xdg-open）和 Windows（powershell.exe Start-Process）。Windows 路径会作为数据传递，而非 PowerShell 源代码。在无头环境或不受支持的跨主机会话中，应报告启动失败并提供手动链接，不要声称浏览器已打开。

---

备注

• 只读，不修改源代码。 此技能只会创建或覆盖 preview.html，绝不会修改 TSX 文件、布局、配置或 memory bank。
• 静态近似预览。 预览不会运行 React、处理状态或获取数据。动态列表会显示占位项。交互（按钮点击、导航）不可用。
• 原生功能仅为占位内容。 PDF 查看器、PDF 报告、分享、打印以及手写笔／签名捕获都只会显示静态状态。浏览器预览不得让人误以为原生捕获／查看器 API 在此可用。
• 重新运行 /preview-screens 会覆盖之前的 preview.html。
• 无需更新 memory bank — 预览是临时产物。

参考资料

• tamagui-html-mapping.md — 组件与令牌映射及手机框架模板
• tamagui-component-recipes.md — 可复制粘贴的 Tamagui 代码片段（用于了解如何识别模式）
• screen-templates.md — 屏幕原型布局