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
frames.sh寫出小型縮圖(用於變更偵測)以及應用程式邏輯寬度的影格(Retina 錄影是 2x:邏輯寬度為像素寬度的一半),因此一個影格像素等同於重建應用程式的一個 CSS px。ocr.sh將ocr.swift(Apple Vision)編譯一次到快取資料夾,並為每個影格寫出一行 JSON。在 Linux 上會顯示「不支援」並退出:請改為閱讀連絡表。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、長時間等待、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 或瀏覽器儲存空間。 如果需要登入才能進行捕捉,使用者必須在自己的對話中輸入自己的密碼,否則就不進行捕捉。
- 還原與錄製的素材保持私密。 先使用暫存資料夾,僅保留裁剪後的副本。
- 標記每個推論值。 一半是猜測的參考資料必須說明哪一半是猜測的。