Quinus/screen-flow

屏幕流程

从运行中的应用的真实截图生成独立的 HTML 屏幕流程。包含三个步骤：

1. 映射屏幕及它们之间的链接，主要从代码中获取，并写入 flow.json。
2. 捕获运行中应用的每个屏幕，使用代理工具。对于每个链接，还要记录其热点：触发该链接的按钮、标签或行在截图上的位置。查看器将从该点开始绘制箭头。
3. 构建页面，使用 scripts/build_flow.py。该脚本处理布局、箭头、平移和缩放，并嵌入图片。永远不要自己编写查看器 HTML。把你的精力放在正确的映射和好的截图上。

以下路径相对于该技能所在的文件夹（本文件所在的文件夹）。

0. 范围与输出

• 范围：feature（一个功能或流程，例如“结账”或“家长控制”）或 app（所有屏幕）。如果请求未指定，使用他们命名的功能。如果没有命名功能，则使用整个应用。
• 功能范围：包括进入该功能的入口屏幕，例如包含打开该功能按钮的标签页或主屏幕。将它们放在一个小的 nav 组中，以便读者可以看到功能的起始位置。不要捕获应用的其余部分。
• 输出文件夹：使用用户要求的位置。否则使用项目中的 screen-flows/<slug>/：包含 flow.json、screens/<screen-id>.png 和 screen-flow.html。在写入仓库之前，检查 screen-flows/ 是否应添加到 .gitignore。PNG 文件可能很大。

1. 映射导航（在截图之前）

阅读代码以构建清单。不要随意点击。查找位置：

技术栈	导航位置
React Router / TanStack Router	路由配置、createBrowserRouter、<Route>、routes/ 文件夹
Next.js / Remix / Nuxt / SvelteKit	基于文件的路由：app/、pages/、routes/、src/routes/
Angular / Vue	*-routing.module.ts、router/index.ts
SwiftUI / UIKit	NavigationStack、TabView、.sheet、.fullScreenCover、协调器、storyboard/segues
Android	NavHost / composable(...) 路由、nav_graph.xml、Manifest 中的 Activity、底部导航菜单
Flutter	GoRouter / routes: / Navigator.push、BottomNavigationBar
React Native	createNativeStackNavigator、createBottomTabNavigator、Expo Router app/ 文件夹
TV / 10英尺应用	基于焦点的菜单、轨道、遥控器的返回键、深层链接处理程序

然后找到连接屏幕的触发器：按钮、链接、标签栏、菜单、navigate(...)、router.push、.sheet(isPresented:)、登录后重定向、守卫。每个触发器成为一个边。

编写一个不带图片的初始 flow.json。完整格式见 references/flow-schema.md。简而言之：

• 分组
  • 为主要的导航外壳创建恰好一个 kind: "nav" 分组：标签栏或侧边栏目标、主屏幕和全局菜单。这些屏幕在画布顶部排成一行。
  • 每个功能创建一个 kind: "feature" 分组，其屏幕按任务顺序排列（例如：列表 → 详情 → 编辑 → 确认）。
  • 将引导、登录和注册放入它们自己的功能分组中。
• 屏幕：每个不同的视图一个屏幕。当对流程重要时，模态视图、表单、对话框和重要状态（空、错误、付费墙）也算作屏幕。用 state 标记它们。在分组起始的屏幕上设置 entry: true。
• 边：将用户的操作写为标签，例如 "点击'结账'" 或 "向左滑动"。使用 kind 表示 back（返回路径）、modal 和 redirect（自动导航）。除非必要，省略明显的返回链接。不要将每个标签页连接到其他每个标签页。仅从默认标签页连接到其他标签页，这样5标签页应用有4条边，而不是20条。

使用 python3 scripts/build_flow.py flow.json --check 检查映射。对于超过约25个屏幕的整个应用，向用户显示分组和屏幕列表，并在捕获前请求确认。

2. 捕获真实截图

阅读 references/capture.md 了解每个平台使用的工具和命令。所有平台的规则：

• 优先使用你的工具套件提供的工具。 这些包括浏览器或预览工具、设备或模拟器工具，以及 Playwright/Chrome DevTools MCP 服务器。如果没有，使用 capture.md 中的备用方案：scripts/capture_web.mjs (Playwright)、xcrun simctl io 或 adb exec-out screencap。
• 自己运行应用。 使用项目自己的运行说明（README、AGENTS.md/CLAUDE.md、package.json 脚本、运行配置）。使用本地或开发构建，并带有测试数据。
• 使用测试账户登录。 如果需要凭据，询问用户。不要猜测，不要使用真实客户的账户，也不要将秘密粘贴到 flow.json 中。
• 在整个流程中使用同一设备和视口。 对于移动端 Web，使用 390×844 2倍率。对于桌面端 Web，使用 1440×900。对于原生应用，使用同一个模拟器或仿真器型号。在所有地方使用相同的主题和语言。
• 尽可能像用户一样到达每个屏幕。 这也可以检查你的边。如果某个步骤缓慢或不稳定，使用深层链接或 URL 直接打开屏幕。如果实际路径与映射不同，修复映射。
• 等待屏幕稳定。 没有旋转器、骨架屏，图片已加载，没有提示条（除非它们是重点）。关闭开发覆盖层和调试横幅。
• 永远不要进行破坏性或不可逆的操作，例如支付、删除、发送邮件或消息（在沙箱之外）。捕获确认屏幕并停止。
• 将每个截图保存为 screens/<screen-id>.png，并在 flow.json 中设置 image。
• 为每个链接记录一个热点，当你在源屏幕上时：用户点击的元素的边界框。使用与截图相同的坐标系（图片的像素，或0到1的分数）。在 Web 上，scripts/capture_web.mjs 通过选择器为你完成此操作并写入 hotspots.json。在原生平台上，从 UI 树中获取元素边界（参见 capture.md）。对于不是可见元素的链接，例如滑动、自动重定向或系统返回按钮，可以跳过。
• 保存后检查每个截图，使用图片查看器或 Read 工具。重新捕获任何空白、裁剪、错误屏幕、登录墙或错误页面的截图。
• 如果某个屏幕无法到达，在映射中保留它但不设置 image，并在 notes 中写入原因。查看器将为它显示一张“未捕获截图”的卡片。

3. 构建与检查

python3 scripts/build_flow.py <out>/flow.json            # 写入 <out>/screen-flow.html
python3 scripts/build_flow.py <out>/flow.json -o docs/flow.html --max-width 900

该脚本只需要 Python 标准库。它会读取 flow.json 旁边的 hotspots.json（如果存在），或通过 --hotspots 传递的文件。为了保持文件较小，当 Pillow 或 macOS sips 可用时，它会缩小宽度超过 --max-width（默认 1000 像素）的截图。

打开 HTML 并查看。使用浏览器工具截图，或为用户打开它。然后通过 flow.json 修复布局并重新构建：

问题	修复
组内屏幕顺序错误	重新排列 screens，设置 entry: true，或使用 "column": n 固定屏幕
分组是一组松散的屏幕，而不是序列	在分组上设置 "layout": "grid"
长序列应排成一行	设置 "layout": "row"
功能远离其起点	添加通向它的边，或设置 "parent": "<group-id>"
箭头太多	移除不需要的返回链接，或仅从默认标签页链接标签页
箭头在截图上的起始位置错误	修复该边的 hotspot（在详情面板中检查）

PNG 与 PDF 导出

如果用户要求图片或 PDF，或者流程需要进入拉取请求、工单、Confluence 或幻灯片，请无头导出。这使用与页面的导出按钮相同的渲染器：

node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png                 # 整个流程
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout   # 一个分组
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf                 # 概览 + 每个分组一页

选项：--theme light|dark（默认 light），--no-hotspots，--no-group-pages（PDF）。该脚本需要 Playwright，设置方式与 capture_web.mjs 相同。在交付前查看 PNG。

4. 报告

向用户提供 screen-flow.html 的路径以及屏幕和分组的数量。列出任何没有截图的屏幕及其原因。提及以下查看器控件：

• 拖拽平移；滚动或捏合缩放。
• 点击一个屏幕可放大查看其传入和传出链接。
• 拖拽屏幕或通过其标题拖拽分组以重新排列；这会在该浏览器中保存。
• 热点（工具栏按钮，或快捷键 H）使每条箭头从其触发按钮处开始。在详情面板中，热点是可点击的，因此读者可以像原型一样点击浏览流程。
• / 搜索，快捷键 F 适应所有内容到屏幕。
• 导出（工具栏）下载整个流程、当前视图或一个分组的 PNG 或 PDF，使用浅色或深色主题。PDF 包含一个概览页加上每个分组一页。导出遵循当前的切换状态（标签、跨组链接、返回链接、热点）。
• 在 URL 末尾添加 #<screen-id> 可直接打开该屏幕。