Communitygithub.com

josueh04/product-video-skills

透過影格與計時OCR文字從螢幕錄影、過去 Claude Code 對話記錄的擷圖、本機生產環境建置的應用程式以及第三方應用程式的網路研究,收集程式碼無法呈現的 UI 像素參考,並產生並排比對圖與連絡表。

product-video-skills 是什麼?

此技能專為需要真實 UI 參考的開發者與 AI Agent 設計,解決程式碼無法提供的執行時期視覺資訊問題。它支援從螢幕錄影(.mov/.mp4)分析、從 Claude Code 對話 JSONL 還原過去擷圖、執行本機生產建置並以無頭瀏覽器捕捉畫面,以及僅從公開來源研究第三方 UI。技能強制執行嚴格的隱私規則:絕不使用審查者的個人瀏覽器或帳號,所有還原素材先存放於暫存資料夾,且必須裁剪掉真實客戶資料後才能保留。透過輸出計時 OCR 時間軸、關鍵影格、並排比對圖與分析文件,幫助開發者驗證應用程式重建是否與原始錄影一致,並偵測產品缺口與動畫時長。

相容平台✓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。此技能以固定的優先順序,透過參考資料填補這些缺口,並且絕對不會在個人瀏覽器中即興發揮。

這最後一條規則有其歷史由來。在這些技能所屬的生產環境中,某個 Agent 曾被允許進入審查者已登入的個人瀏覽器來捕捉即時應用程式。即時流程卡住,Agent 在審查者說停止後仍持續執行「清理」步驟,在測試工作區留下殘留項目,最後在約 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 錄影是 2x:邏輯寬度為像素寬度的一半),因此一個影格像素等同於重建應用程式的一個 CSS px。
  2. ocr.sh 將 ocr.swift(Apple Vision)編譯一次到快取資料夾,並為每個影格寫出一行 JSON。在 Linux 上會顯示「不支援」並退出:請改為閱讀連絡表。
  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、長時間等待、OS 介面元素如 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. 如同生產環境建置的本機實例

當應用程式可以在使用者的機器上執行時,這是最可靠的參考:從生產 commit 使用生產建置參數進行建置,使用虛構資料進行種子填充,與所有共用系統隔離,並使用無頭瀏覽器捕捉畫面。在開始之前請先閱讀 references/local-instance.md;使用者必須同意執行他們的應用程式,且絕不會使用他們的帳號或共用資料庫。

4. 第三方 UI

對於其他公司的畫面,請使用 references/third-party-ui-prompt.md 啟動一個研究子 Agent:僅限公開來源(官方文件、說明中心、新聞資料包、行銷截圖、供應商擁有的公開嵌入示範),絕對不能登入、提交或預訂,大約 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} 複製一份畫面),從兩張圖片裁剪相同的邏輯區塊,然後疊放在一起。腳本會輸出每個通道的平均絕對差異;持續疊代直到數值不再下降且疊放圖片顯示無偏移。使用應用程式 px 進行測量並明確轉換:混淆縮放比例是導致座標錯誤的常見原因。

規則與原因

  • 絕不使用審查者的個人瀏覽器或設定檔,也不從中取得任何資料(字型、圖示、儲存空間)。當任何人說停止時,立即停止所有瀏覽器動作,包括清理。
  • 絕不登入、絕不讀取 Token 或瀏覽器儲存空間。 如果需要登入才能進行捕捉,使用者必須在自己的對話中輸入自己的密碼,否則就不進行捕捉。
  • 還原與錄製的素材保持私密。 先使用暫存資料夾,僅保留裁剪後的副本。
  • 標記每個推論值。 一半是猜測的參考資料必須說明哪一半是猜測的。

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.

相關技能