Community程式設計與開發github.com

video-ux-audit

通用工具,可快速找出任何 UI 中的問題、缺口和機會。錄製一小段真人操作過程,將所有主控台、網路和效能事件與影片幀同步記錄,讓 AI 一次性審查整條融合時間軸。輸出 prioritized findings.md,附有證據及 UX 與效能修復建議。用於「審核這個畫面/應用程式/流程」、「為什麼 X 感覺卡卡或很慢」,重新設計前,或發佈後。

video-ux-audit 是什麼?

Video + timeline UX audit 是一種結構化的檢驗方法,能同步捕捉螢幕錄影、主控台日誌、網路請求和效能指標,全部對齊在同一時間軸上。它可以生成完整的審核套件,包含 captioned 影片、事件 JSON 檔案和自動偵測的訊號(如 JS 例外、緩慢請求、版面位移),並組織成 AI 可直接處理的 `ai-pack/` 目錄。此工具支援網頁(透過 Chrome DevTools Protocol)、iOS、Android、桌面應用程式和終端機 CLI,能產出 prioritized findings.md,列出問題、缺口與機會,並附上對應的影片幀或事件作為證據。緩解方案涵蓋 UX 與效能兩個層面,且鼓勵將測試情境腳本化,以便後續回歸驗證。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/serebano/video-ux-audit/tree/HEAD

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

影片 + 時間軸 UX 審核

概念: 幾秒到幾分鐘的真實使用過程,已足以揭露大部分問題。問題之所以被忽略,是因為沒有人能同時看到所有面向:使用者的意圖、畫面顯示的內容、程式碼的紀錄、以及網路的行為。這個方法將所有資訊對齊在同一時鐘上,讓每個影片幀都能以其事件來解釋,每個事件也都能在其影片幀中被看見。AI 接著在一次處理中讀取完整圖像。

輸出

檔案說明
audit.mp4錄製的工作階段,內嵌說明文字:黑色表示意圖,紅色表示每個問題
events.json每個動作、說明文字、主控台訊息、例外、請求(狀態、毫秒、位元組、失敗)、長時間任務和版面位移,皆帶有影片時鐘的時間戳記
timeline.md融合的時間軸,加上自動偵測的訊號,每個訊號都連結到發生時的影片幀
ai-pack/以影片時間命名的關鍵幀、timeline.md 和 PROMPT.md,準備好讓任何多模態 LLM 一次性審查
findings.md最終的排名清單:問題、缺口和機會,每個都附有證據、UX 修復建議和效能修復建議

0. 安全性

  • 使用測試帳號和測試資料,僅在沙盒環境中進行寫入操作。真實的使用者資料為唯讀。
  • 絕不公開姓名、電子郵件、電話號碼、ID 或權杖。分享前請清除 events.json(URL、主控台文字)。
  • 使用一次性瀏覽器設定檔,並在結束時關閉。

1. 設定工作階段(2 分鐘)

  • 以真實使用者的口吻,列出一到三項他們想完成的工作。例如:「找到訂單」、「回覆客戶」、「變更我的方案」。
  • 根據 UI 的規模選擇錄製長度:10–60 秒用於單一畫面,2–5 分鐘用於完整流程。簡短且聚焦的工作階段優於冗長的內容。

2. 像個真實、非技術背景的使用者一樣操作

  • 在每次操作前說出你的意圖(一個 say 說明文字)。
  • 只使用可見的元素。 不輸入 URL、不使用開發者工具、不按隱藏快速鍵。
  • 先嘗試最直覺的路徑。 如果失敗了,那就是一個發現,即使有其他路徑可行。
  • 每次操作後,檢查所有元件是否一致: 列表、計數器、頁首、其他面板,以及另一方的視角。
  • 對狀態施加壓力。 重新載入、回上一頁、在新分頁中開啟、使用慢速網路、以及使用手機寬度(390×844)。
  • 留意等待時間。 如果你需要等待,使用者也需要等待。

驅動方式有兩種:

  • 腳本化(Scripted)。 一個包含步驟的 scenario.json。可重複執行,且同一份檔案在修復後可作為回歸測試的依據。
  • 自由探索(Free)。 {"url": "...", "freeSeconds": 90}。由真人或代理程式手動操作瀏覽器,同時錄製一切。適用於探索性測試。

3. 錄製(網頁:Chrome DevTools Protocol,無相依套件)

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/vua   # 一次性設定檔
node scripts/record.mjs scenario.json --port 9222 --out ./audit-out
bash scripts/encode.sh ./audit-out                 # → audit.mp4
node scripts/timeline.mjs ./audit-out              # → timeline.md, signals.json, ai-pack/
node scripts/report.mjs ./audit-out --title "X"    # → findings.md (含說明的發現)

步驟類型:goto、say、click(CSS 選擇器,附帶可見指標)、type(模擬人類輸入速度)、press、scroll、wait 和 problem(紅色說明文字、螢幕截圖和一個發現)。

其他環境使用相同方法,但採用不同的錄製工具。 無論平台為何,請錄製螢幕畫面加上該平台的日誌和網路串流,將它們全部對齊在同一時鐘上,然後作為 events.json 傳遞給 timeline.mjs:

平台螢幕錄製日誌和網路
iOSxcrun simctl io booted recordVideolog stream;代理伺服器 (mitmproxy) 用於網路
Androidadb shell screenrecordadb logcat;代理伺服器用於網路
桌面 / Electron作業系統螢幕錄製CDP 連接埠,如同網頁
終端機 / CLIasciinemastderr,附帶時間戳記

4. 自動訊號(自動為你找出,請針對其影片幀逐一驗證)

訊號典型含義
js-exception, console-error功能損壞,對使用者而言通常是靜默的
request-failed, http-5xx, http-4xx資料遺失、狀態錯誤、權限不足
slow-request (≥ 1 秒;P1 為 ≥ 3 秒)使用者感受到的等待;可考慮快取、預先提取或建立索引
heavy-payload (≥ 500 KB)在行動裝置上速度較慢;請分頁、壓縮或修剪欄位
duplicate-request (2 秒內相同呼叫)浪費資源;請去除重複或快取
never-finished請求掛起、缺少 timeout、旋轉圖示永不停止
long-task (≥ 200 毫秒;P1 為 ≥ 500 毫秒)UI 凍結;請分割工作、虛擬化、移至 Worker
layout-shift (≥ 0.05,無輸入)內容跳動;請預留空間

可使用 --slow 和 --big 參數調整閾值。

5. 一次性 AI 審查

將 ai-pack/(關鍵幀、timeline.md 和 PROMPT.md)提供給 AI。它會在單次處理中產出:

  1. 問題,每個都附有嚴重性和證據:一個影片幀以及解釋該問題的時間軸行數。
  2. 缺口:死路、缺少回饋、不明確的狀態、缺少可供性(affordance),以及兩個畫面不一致的情況。
  3. 機會:可以移除、快取或預先提取的請求;可以合併的步驟;可以設定的預設值;主要競爭對手做得更好的地方。
  4. 排名清單,根據使用者影響力 ÷ 努力程度排序。

規則:沒有證據,就不列入。 每個主張都必須引用一個影片幀或一個事件。

6. 嚴重性

  • P0:資料遺失、傳送對象錯誤、隱私或安全漏洞,或核心工作無法完成。
  • P1:核心工作中斷或誤導、動作耗時超過 1 秒或畫面載入超過 3 秒、JS 例外出現在主要路徑上,或兩個表面不一致。
  • P2:操作摩擦、用詞混淆、外觀問題,或浪費請求。

7. 關閉迴圈

  • 優先修復 P0,然後是 P1,每個發現只做一個小改動。
  • 每次修復後重新執行同一個工作情境。新的時間軸就是證據:訊號消失,時間也改善了。請附上修改前後的比較。
  • 將工作情境視為函式庫保存。每次發佈後重新執行它們,可以在數秒內發現回歸問題。

相關技能