Communitygithub.com

josueh04/product-video-skills

通过屏幕录像帧、时序OCR文本、历史Claude Code会话截图、本地生产级构建实例以及第三方应用公开资源,收集端到端UI像素级参考,用于验证代码与真实产品的一致性。

product-video-skills 是什么?

该技能解决了一个核心问题:代码本身无法提供运行时行为(后端响应、元素出现顺序、真实等待时长)和第三方UI细节。它严格按照优先级顺序捕获参考,绝不访问审查者的个人浏览器——这条规则源于一次事故:允许代理登录浏览器导致流程挂起、残留数据,最终68分钟无果。 支持四种场景:(1) 分析产品屏幕录像(.mov/.mp4),通过帧提取、OCR文本识别和接触页生成精确时序与像素对齐;(2) 从Claude Code会话JSONL中恢复历史截图;(3) 构建本地生产级实例并用无头浏览器捕获;(4) 仅使用官方文档、帮助中心等公开资源研究第三方UI。 工作流程包括:将输入放入 `products/<slug>/references/<name>/`,临时工作在 `$TMPDIR/pvs-<slug>-<name>/`,最终结果保留在 `references/<name>/`。核心脚本包括 `frames.sh`(帧提取)、`ocr.sh`(OCR,仅macOS)、`ocr_events.py`(时序文本)、`grid.py`(接触页)、`pair.py`(像素级对比)。所有输出标记为已验证、测量或推断,并自动裁剪真实数据(用户姓名、邮箱等)。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/ui-reference-capture

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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
  1. frames.sh 写入小缩略图(用于变化检测)以及应用逻辑宽度下的帧(Retina 录制是 2 倍:逻辑宽度是像素宽度的一半),因此一个帧像素对应重建应用中一个 CSS px。
  2. ocr.sh 将 ocr.swift(Apple Vision)编译一次到缓存文件夹,并为每帧写入一行 JSON。在 Linux 上它会退出并显示“unsupported”:请改用联系页。
  3. ocr_events.py 将逐帧 OCR 转换为稳定的跨度,格式为 start-end [region] text。该时间线给出了真实应用显示的确切字符串及时间,这远比通过肉眼观察视频进行猜测要好。
  4. grid.py sheet 制作联系页:每 2 秒一张概览,然后每个阶段有密集的 10 fps 页面。grid.py overlay 在帧上绘制逻辑像素网格用于测量。
  5. 将关键帧保存为 references/<name>/frames/<t>-<state>.jpg(已裁剪掉真实数据)。
  6. 根据 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} 合成的副本)获取我们的快照,从两者中裁剪相同的逻辑框,并将它们并排堆叠。脚本会打印每个通道的平均绝对差异;重复迭代,直到差值不再下降并且堆叠图像显示没有偏移。使用应用像素测量并显式转换:混淆比例一直是产生错误坐标的常见原因。

规则及原因

  • 绝不允许使用审查者的个人浏览器或个人资料,也不得从中获取任何内容(字体、图标、存储)。当任何人说停止时,立即停止所有浏览器操作,包括清理。
  • 绝不登录,绝不读取令牌或浏览器存储。 如果捕获需要登录,由用户在其自己会话中输入自己的密码,否则捕获不进行。
  • 恢复和录制的资料保持私密。 先使用临时文件夹,仅保留裁剪后的副本。
  • 标记每一个推断值。 一半靠猜测的参考必须说明哪一半是猜测的。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

相关技能