UI 参考捕获
代码提供了结构、样式、字符串和图标。但它没有提供运行时会发生什么(后端返回什么、元素出现的顺序、真实应用等待了多长时间),也对其他公司的 UI 一无所知。本技能按照固定的优先级顺序,用参考来填补这些空白,并且绝不在用户的个人浏览器中即兴操作。
最后那条规则是有历史教训的。在这些技能来源的生产环境中,一个代理被允许进入审查者已登录的个人浏览器来捕获一个正在运行的应用程序。实时流程挂起了,代理在审查者说停止后仍在执行所谓的“清理”步骤,在测试工作区留下了遗留项,经过大约 68 分钟后会话糟糕地结束了,没有构建出任何可用的东西。同样的捕获后来在几分钟内从会话记录中就恢复了。优先使用离线参考;只有用户明确要求时才使用浏览器,且必须是隔离的,并在用户说停止的那一刻立即停止。
内容存放位置
- 输入(用户提供的录制文件、导出文件、截图):收到后立即复制到
products/<slug>/references/<name>/。下载文件夹和操作系统临时捕获文件夹将被清理,因为在源生产环境中,有一个录制文件存放在一个系统可能会删除的文件夹里。macOS 录制文件名在 AM/PM 前包含一个窄无间断空格 (U+202F):使用 glob 模式查找,不要直接输入名称。 - 工作素材(数千帧、恢复的捕获、原始 OCR 文本):存放在所有仓库外的一个临时文件夹中,例如
$TMPDIR/pvs-<slug>-<name>/。 - 值得保留的结果(OCR 时间线、已裁剪真实数据的关键帧、分析结果):存放在
references/<name>/中,并从 SOURCES.md 引用。
真实工作区的录制和捕获文件包含真实客户姓名、电子邮件、电话号码、内部 ID 和他人的对话。它们绝不应进入工作仓库,且视频中不得显示这些信息:第 1 节的第 6 步列出了必须修改的内容。
选择技术方案
| 你拥有 | 技术方案 | 阅读文档 |
|---|---|---|
| 产品的屏幕录制 | 1. 分析录制文件 | references/recording-analysis.md |
| 曾经查看过应用的过往会话 | 2. 从会话记录恢复截图 | 本文件第 2 节 |
| 可以在本地运行的应用 | 3. 像生产环境一样构建本地实例 | references/local-instance.md |
| 其他公司的产品 | 4. 网络研究,仅限公开来源 | references/third-party-ui-prompt.md |
| 什么都没有(电话通话、结束卡片、生成的文本) | 从工具包中设计并标记 | product-truth (mock) |
按照这个顺序尝试。在要求任何人录制之前,先检查第 2 节:可能已经有捕获文件存在。如果四种方法都不行,请如实说明;不要退而求其次使用审查者的浏览器。
1. 分析屏幕录制
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/ui-reference-capture/scripts"
W="$TMPDIR/pvs-acme-board" # 临时文件夹,不在仓库内
bash "$S/frames.sh" references/board/rec.mov "$W" --fps 10 --logical-width 1440
bash "$S/ocr.sh" "$W/logical" "$W/ocr.jsonl" # 仅 macOS
"$PVS_HOME/bin/pvs-py" "$S/ocr_events.py" "$W/ocr.jsonl" references/board/ocr-timeline.txt --fps 10 \
--region "panel=0.6,0,1,[email protected]"
"$PVS_HOME/bin/pvs-py" "$S/grid.py" sheet "$W/overview.png" "$W/logical" --every 20 --cols 4
frames.sh写入小缩略图(用于变化检测)以及应用逻辑宽度下的帧(Retina 录制是 2 倍:逻辑宽度是像素宽度的一半),因此一个帧像素对应重建应用中一个 CSS px。ocr.sh将ocr.swift(Apple Vision)编译一次到缓存文件夹,并为每帧写入一行 JSON。在 Linux 上它会退出并显示“unsupported”:请改用联系页。ocr_events.py将逐帧 OCR 转换为稳定的跨度,格式为start-end [region] text。该时间线给出了真实应用显示的确切字符串及时间,这远比通过肉眼观察视频进行猜测要好。grid.py sheet制作联系页:每 2 秒一张概览,然后每个阶段有密集的 10 fps 页面。grid.py overlay在帧上绘制逻辑像素网格用于测量。- 将关键帧保存为
references/<name>/frames/<t>-<state>.jpg(已裁剪掉真实数据)。 - 根据
references/recording-analysis.md中的结构编写references/<name>/analysis.md:包含精确字符串的真实时间线、测量到的动画(面板打开需要多长时间、光标停留多久)、“视频中必须修改”表(真实姓名、邮箱、电话、工作区、内部 ID、长时间等待、操作系统 Chrome 如 Dock 栏),以及在任何人基于这些进行构建之前需要提出的产品差距(故事需要的步骤,但录制显示该步骤失败)。
当等待时间被压缩时,录制会隐藏差距;请记录你所缩短的每一个等待时间。
2. 从过往会话中恢复截图
工具在 Claude Code 会话中返回的每张图片(浏览器截图、窗口捕获、读取的图片)以及粘贴到聊天中的每张图片,都存储在该会话的 JSONL 文件中。
"$PVS_HOME/bin/pvs-py" "$S/recover_transcript_images.py" ~/.claude/projects/<project>/<session>.jsonl \
[--from-line N] [--tool screenshot]
如果不指定输出文件夹,它会写入一个新的临时文件夹,并且拒绝任何位于 git 工作树内部的文件夹,因为这些截图显示了真实账户。它会写入 index.tsv(包含文件、时间、工具、输入信息),方便你找到需要的屏幕。通过联系页(grid.py sheet <out> <dir> --labels name)查看它们,然后只将经过处理(已裁剪真实数据)的副本复制到 references/<name>/。在源生产环境中,有一个完整的视频就是由 117 张恢复的图片加上代码构建而成的。
3. 像生产环境一样构建的本地实例
当应用可以在用户机器上运行时,这是最可靠的参考:从生产环境提交版本使用生产构建参数进行构建,用虚构数据填充,与所有共享系统隔离,并通过无头浏览器捕获。开始之前请阅读 references/local-instance.md;用户必须同意运行他们的应用,并且绝不允许使用他们的账户或共享数据库。
4. 第三方 UI
对于其他公司的屏幕,使用 references/third-party-ui-prompt.md 启动一个研究子代理:仅限公开来源(官方文档、帮助中心、媒体资料包、营销截图、供应商拥有的公开嵌入演示),绝不涉及登录、提交或预订,约 30 分钟。每个返回的值都标记为已验证、测量或推断。当产品本身包含相关组件时优先使用(例如,一个渲染聊天应用预览的产品具有预览组件;使用它而不是重建聊天应用)。只有当展示的是一个真实的集成时,才显示完整的第三方屏幕;在其他情况下,在产品内部使用标志和徽标。
验证:证明重建与产品一致
"$PVS_HOME/bin/pvs-py" "$S/pair.py" snapshots/nocam-12.4s.png references/board/frames/12.4-board.png \
640 40 1100 300 "$W/pair-board-header.png" --ref-scale 2 --logical-width 1440 --render-width 1920
使用比例为 1 的相机(即 #camera{transform:none!important} 合成的副本)获取我们的快照,从两者中裁剪相同的逻辑框,并将它们并排堆叠。脚本会打印每个通道的平均绝对差异;重复迭代,直到差值不再下降并且堆叠图像显示没有偏移。使用应用像素测量并显式转换:混淆比例一直是产生错误坐标的常见原因。
规则及原因
- 绝不允许使用审查者的个人浏览器或个人资料,也不得从中获取任何内容(字体、图标、存储)。当任何人说停止时,立即停止所有浏览器操作,包括清理。
- 绝不登录,绝不读取令牌或浏览器存储。 如果捕获需要登录,由用户在其自己会话中输入自己的密码,否则捕获不进行。
- 恢复和录制的资料保持私密。 先使用临时文件夹,仅保留裁剪后的副本。
- 标记每一个推断值。 一半靠猜测的参考必须说明哪一半是猜测的。