ui-recording-timeline

UI 录制时间线

生成一个包含 index.html 和视频的独立文件夹。视频铺满窗口。视频下方是一行说明文字和一条细时间线（阶段颜色、绘制刻度、悬停缩略图、拖动播放位置）。每次绘制时，视频上的变化区域都会闪现；按 l 可打开绘制列表抽屉。

此技能目录中包含所需的一切：

• scripts/timeline.py：集成所有步骤的单个 CLI。依赖项以内联方式声明，uv run 会安装它们。
• assets/template.html：页面模板。build 会将数据注入其中。

要求：ffmpeg/ffprobe 和 uv 必须位于 PATH 中。仅 preview 需要 Chrome 或 Chromium。

下文中，T 表示 uv run <this skill dir>/scripts/timeline.py。请将其定义为 shell 函数，而不是变量：zsh 不会对变量内容进行词拆分。使用技能目录的绝对路径：

T(){ uv run "/abs/path/to/ui-recording-timeline/scripts/timeline.py" "$@"; }

WD 是输出文件夹。如果用户的项目对研究资料或配套文件的存放位置有约定，请遵循该约定；否则将 WD 放在视频旁边，命名为 <video-stem>-timeline/。

工作流

1. 提取并查找候选绘制

T extract /path/to/recording.mp4 WD     # copies video, writes meta.json (frame timestamps; VFR is fine)
T candidates WD                         # table of frames that differ from the previous frame

每行包含帧索引、时间、变化百分比、类型（change / full / cursor?）和归一化边界框。细小的光标状变化会被隐藏（使用 --all 可显示）。

2. 查看帧，然后判断哪些算作绘制

不要只根据表格进行标注。查看帧：

T sheet WD --frames 0,4,14,26,61 --name overview          # labelled contact sheets -> WD/sheets/*.jpg
T sheet WD --frames 18,19 --crop 0,0,0.25,0.15 --name zoom # zoom into a small change

使用图像查看器查看图像表。确保包含每个候选帧之前的那一帧，以便看清发生了什么变化。

选择绘制的规则：

• 属于绘制： 可见的内容或布局变化。包括骨架屏出现、真实内容替换骨架屏、导航到空白页、新页面首次绘制、标签或按钮状态变化，以及表示加载状态的浏览器界面变化（重新加载图标替换停止 X）。
• 不属于绘制： 光标移动、悬停高亮、加载动画旋转、光标闪烁，或已有骨架屏上的渐变闪烁。查看边界框：连续帧中不断移动的微小区域就是光标。
• 动画： 多帧动画（如对勾动画、面板滑入）在最终帧计为一次绘制。设置 "base": <frame before the animation started>，让差异对比涵盖整个动画。
• 次要绘制： 对小范围的原位更新（如标签、按钮状态、浏览器界面）设置 minor: true。这类绘制会使用更短的刻度和较暗淡的文字。
• 阶段： 按屏幕或 URL 将绘制分组为阶段（例如：应用外壳、SSO 门禁、IdP、空白重定向、已登录应用、空闲）。帧中的地址栏通常能提供线索。阶段必须覆盖从 0 到录制结束的整个时段，不能有间隙。
• 空闲阶段： 在屏幕没有变化的时段设置 "idle": true。最后一次绘制之后的尾段始终属于空闲阶段；长时间停留在同一屏幕时也可以设置为空闲阶段。空闲阶段显示为灰色斜线纹理，而不是调色板颜色：高饱和度颜色会让人觉得画面有活动，而深灰色会让时间条看起来提前结束。不要裁掉空闲尾段；它是真实时长，视频也涵盖这段时间。
• 指标： 前两个指标会显示在说明文字中，因此请将最重要的指标排在最前（例如“主要内容”和“视觉完整”）。其他指标（如 IdP 上的耗时或空白总时长）放入抽屉。
• 注意事项： t=0 是录制的第一帧，不是导航开始时间。如果第一帧已经显示 UI，请在 notes 中说明。

3. 编写 WD/paints.json

{
  "title": "vercel.com/vercel-labs with an SSO redirect",
  "notes": "Recording starts mid-navigation: the dashboard shell is already on screen at t=0.",
  "metrics": [
    {"value": "6.50 s", "label": "main content"},
    {"value": "8.37 s", "label": "visually complete"},
    {"value": "2.53 s", "label": "on Okta"}
  ],
  "phases": [
    {"start": 0.0,   "end": 0.802,  "name": "Dashboard (unauthenticated)"},
    {"start": 0.802, "end": 2.002,  "name": "Vercel SSO gate"},
    {"start": 2.002, "end": 8.468,  "name": "Okta and back"},
    {"start": 8.468, "end": 10.935, "name": "Idle", "idle": true}
  ],
  "paints": [
    {"frame": 0,  "label": "Dashboard shell: sidebar nav and header skeleton (recording start)"},
    {"frame": 4,  "label": "Projects and usage skeleton cards"},
    {"frame": 19, "label": "Team switcher changes to \"Select Team\"", "minor": true},
    {"frame": 87, "label": "Okta Verify check badge (animates 2.668 to 3.068 s)", "minor": true, "base": 74}
  ]
}

• frame 是 candidates 中解码后帧的索引。时间取自帧的实际时间戳，因此不要手动计算。阶段边界以秒为单位：使用每个阶段起始绘制的 t，最后一个阶段的结束时间使用 extract 返回的时长。
• 标签应简短具体。说明出现、变化或消失的内容，并引用屏幕上的文字。
• 可按阶段设置 "color": "#hex"。默认颜色来自调色板。

4. 计算并检查变化区域

T regions WD     # move-aware diff for every paint -> regions.json
T check WD       # boxes drawn on every paint frame -> WD/sheets/check-*.jpg

查看每张检查表。粉色表示绘制，蓝色表示移动，细灰线表示内容原来的位置。差异的工作原理（详见 compute_regions）：

• 变化的布局形状会贴合到完整元素：单词、图标、输入框、卡片。微弱的闪烁边缘也会纳入。
• 如果在上一帧附近找到某个形状，且其原位置已空出，就算作移动。例如，插入侧边栏项目时，其下方的行会向下滑动。同一偏移量的移动会归为一组。
• 对于有歧义的重复形状（相同的尖括号、行），如果它们与同一帧中已发现的某个偏移量对齐，就算作移动。
• 光标是通过学习识别的，不是根据大小猜测的。光标图像（箭头、手形、文本光标）来自 candidates 帧，在这些帧中，只有一个小元素自行移动。只有在任一帧中包含已知光标图像的框才会被排除。徽标、图标或工具栏按钮等小型真实绘制会保留。因此，请先运行 candidates，再运行 regions。
• 其他所有内容都算作绘制，包括纯色填充（例如新的背景）。

如果某个框看起来不对：

• 先检查绘制选择。base 错误，或绘制帧中存在悬停状态，通常是原因。
• 只有在此之后，才考虑调整 compute_regions 顶部的常量。这些常量针对 1710 px 宽度调优，并会自动缩放：EDGE/CHG 阈值、SEARCH 距离、光标大小和扩展容差。

5. 构建、预览并打开

T build WD                    # paint thumbnails + WD/index.html
T preview WD --t 6.502        # headless screenshot with boxes frozen -> WD/preview.png
open WD/index.html

查看 preview.png，确认布局正确，且叠加层与视频对齐。更改 paints.json 或 regions.json 后，重新运行 build。只有在绘制帧或基础帧发生变化时，才再次运行 regions。

页面参考

• 按键：←/→ 在绘制帧之间切换，space 播放，d 切换变化闪烁效果，l 打开绘制列表抽屉，f 进入全屏。点击视频可播放或暂停。点击或拖动时间轴可定位，悬停时会显示缩略图。
• URL 选项：#t=6.502 可深度链接到某个时间点，?hold 可冻结方框，便于截图。
• “Shown”表示到下一次绘制之前的时长。
• 此文件夹可移植：index.html、recording.*、paints/。meta.json、paints.json、regions.json 和 sheets/ 是输入和调试输出，可以保留。

反馈内容

总结各个阶段、关键指标以及值得注意的事项（空白屏幕、差异显示为移动的布局偏移、长时间等待）。提供 index.html 的路径。说明 t=0 的注意事项，并注明时间精度为 ±1 帧。