video-qa

video-qa 是做什麼的？

根據預期的腳本故事板，對展示 MP4 影片進行評論，並回傳一份如同敏銳人類審查員會撰寫的帶有時間戳記的檢查清單。此技能包含兩個層次：確定性探測（使用 ffmpeg/ffprobe/node 進行機械式偵測，無模型推理）以及一個全新的分析子代理，它會根據探測產生的緊湊 JSON 報告以及一組有限的、針對腳本提取的影格進行推理。

嚴格規則：分析作業永遠在全新的子代理中執行

呼叫端（您，位於主執行緒）只需執行最低限度的工作：

1. 定位輸入。
2. 執行探測腳本。
3. 產生一個全新的獨立子代理（使用 Agent 工具）來執行分析。
4. 將子代理的問題清單轉交給使用者。

切勿在主執行緒中自行讀取擷取的影格或推理報告。 整個要點在於代幣隔離：一部 5 分鐘的影片會產生約 50 張影格與一個大型 JSON 報告；對它們進行推理會消耗數萬個圖像和分析的代幣。如果這些代幣進入呼叫端的上下文，將會毒害會話的其餘部分。子代理會吸收這些資訊，並僅回傳簡短的問題清單。這不是一個可選項或「方便時才做」——每次 video-qa 的呼叫都必須進行交接。請參閱 references/handoff.md。

步驟 1 — 收集輸入

您需要：

• 影片路徑 — 要進行 QA 的 MP4 檔案（審查員會觀看的已組裝 / 最終剪輯版本）。
• 故事板 / 腳本 — 預期的腳本節拍、時間順序、時機期望以及每個片段應顯示的內容。如果使用者沒有提供，請向他們索取（或索取產生此影片的 issue 或 demo-video 故事板）。請勿憑空編造腳本節拍。
• 預期卡片 — 腳本中指定的卡片（封面、議程、每個串場、摘要），依序排列。將它們寫成一個小型 JSON 檔案，提供給 --cards-file 參數：一個包含 { "label": "Cover (title + subtitle)" } 條目的陣列（可以加入 "minRead": <秒> 來覆蓋較多文字卡片的閱讀時間條）。這將驅動確定性的卡片交叉比對——這是一個一級輸出，因為卡片是腳本化的敘述內容。
• 品牌標示 — 卡片/背景顏色以及游標/註解顏色，以便探測器可以分類品牌卡片，且子代理可以檢查對比度。如果未指定，則使用預設值：向使用者詢問；請勿猜測品牌。

步驟 2 — 執行確定性探測

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<absolute/path/to/video.mp4>" \
  --out   "<workdir>/video-qa-report.json" \
  --frames-dir "<workdir>/video-qa-frames" \
  --card-rgb 15,81,255 \          # 品牌卡片顏色，以 R,G,B 格式指定（例如 #0F51FF）
  --cards-file "<workdir>/cards.json"   # 預期的腳本卡片，依序排列

使用一個暫存/臨時的 <workdir>（例如在 /tmp 下），而非使用者的儲存庫。探測器會寫入 JSON 報告和受限的影格集合，並印出報告路徑。它會執行三個全影片濾鏡處理（凍結畫面、場景切換、動作）以及每個場景的取樣——預計花費約影片播放時間的 1–1.5 倍。可調參數（皆為選擇性，已內建合理的預設值）：--card-tol、--demo-freeze、--annot-freeze、--card-min-read（閱讀時間條，2.5 秒）以及 --annotate-rgb R,G,B——註解呼叫的顏色。當指定此參數時，一個包含該顏色註解環的空白片段將被視為有意的節奏控制（annotated: true），並從主要的空白片段計數中排除，而非標記為缺陷。請參閱 references/detectors.md，了解每個偵測器測量的內容以及為什麼閾值設定在此處。

註解偵測的範圍僅限於空白片段區域，因此 annotatedRegionCount: 0 並不等於「影片中沒有註解」。 一個環僅在它與一個停頓/凍結的片段重疊時才會被記錄；如果構建修剪了空白片段（或該環在有動作的片段上播放），該環仍會在螢幕上渲染，但沒有空白片段區域攜帶它——因此根據設計，計數會是 0。切勿僅從這個數字就斷定註解缺失；如果一個腳本節拍設計要對某物進行環形標記，請從該片段的影格（每個場景的 span-* 影格，或在註解時間戳記處提取影格）進行確認。

在交接之前，對印出的摘要（片段數量、空白片段區域、畫面異常數量、影格數量以及 cardCheck.countMatches）進行合理性檢查。如果 cardSpans 為 0，則 --card-rgb 很可能設定錯誤——請修正後重新執行，否則每張卡片都會被歸類為 ui，且凍結/空白/卡片的分類將毫無意義。如果 cardCheck 顯示數量不匹配，這是一個真實的發現（缺少或多了一張卡片），而不是探測器錯誤——讓子代理根據影格進行確認。

步驟 3 — 移交給分析子代理

使用 Agent 工具（subagent_type: general-purpose）產生一個全新的子代理。根據 references/analysis-prompt.md 建立其提示詞，並替換其中的變數：

• {{REPORT_PATH}} → 步驟 2 中的 --out 路徑。
• {{FRAMES_DIR}} → --frames-dir 路徑。
• {{OUT_FINDINGS}} → 您將要讀取的發現結果檔案路徑（例如 <workdir>/video-qa-findings.md）。
• {{STORYBOARD}} → 步驟 1 中的預期腳本節拍，原文照搬。
• {{BRANDING}} → 步驟 1 中的品牌規則。

告訴子代理——作為其初始提示詞中的一條明確指令——在其回合的最後一步，將其發現結果寫入 {{OUT_FINDINGS}}。讀取該檔案是可靠的檢索路徑：產生的代理的最終文字訊息並非總是能傳遞給呼叫端，而後續的「把你的發現結果發給我」的請求常常會命中一個空閒的代理，它不會重新參與對話。該檔案僅包含問題清單（不含影格），因此不會破壞代幣隔離。子代理仍然會讀取報告 + 影格並逐個節拍推理；它只是將結果持久化儲存在您能夠讀取的地方。

步驟 4 — 轉交

讀取發現結果檔案（{{OUT_FINDINGS}}）並將問題清單按原樣傳遞給使用者（它已經是交付格式）。不要添加您自己對影格的任何推理——按照設計，您從未看過它們。如果使用者希望將其作為帶有品牌標示的 HTML 產出物，那是另一個獨立的後續動作。

在將「無法確定」的項目視為缺陷之前，請先進行抽樣檢查。 探測器會取樣一組有限的影格（數十個，而非每個影格），因此一個確實發生的腳本節拍可能落在取樣之間，並以「無法確定」或「看起來頁面跳轉 / 未顯示」的標記回傳——這是一個取樣間隙，而非真正的缺失。這些是最容易出錯的發現。對於每個此類項目，在其應該發生的確切時間戳記處提取幾個影格（例如 ffmpeg -ss <t> -i video.mp4 -frames:v 1 …）並直接確認，然後再將其報告為缺陷。僅報告完整影片中實際缺少的內容；將確認存在的腳本節拍降級為 ✅，並附上一條說明，指出已在取樣集合之外進行驗證。

它能偵測到什麼（以及它不能偵測到什麼）

• 可靠、機械式的偵測： 空白片段 / 凍結的 UI 區域（動作密度掃描）、場景/片段結構、品牌卡片 vs UI 分類、畫面異常集群（偶發的刷新 / 頁面跳轉閃爍）、整體對比度/亮度統計。
• 子代理基於有限影格的推理： 偏離腳本的管道型 UI（管理儀表板、日誌、錯誤追蹤）——包括腳本節拍之間的短暫登入/載入/空白/管理員閃現以及中段重新載入，這些都被視為潤飾缺陷，而非可接受的過場；過度剪輯 / 硬切（空白片段修剪過頭，切掉了真實的動作——游標瞬間移動無移動軌跡、頁面過渡變成硬跳躍、動作進行中的剪切）看起來會很假；缺少/錯誤的腳本節拍；導航風格作為一級檢查（瀏覽過產品 vs 跳頁到深層頁面）；對於卡片的評判不僅僅是存在與否，而是它們是否落地（可讀的持續時間、不被矛盾/空白的相鄰卡片削弱），其中封面與議程卡片會根據內容進行區分；錯誤的螢幕資料（計數、損壞的行）；缺少註解；品牌/對比陷阱。
• 盲點： 在一個活躍區域中缺少螢幕上的字幕（載入動畫會被視為動作），以及一個動作是否真的失敗了，還是被從畫面中剪掉了。子代理會將這些標記為「無法確定」。

references/validation-notes.md 記錄了此技能對照參考測試裝置的人工審查黃金清單的表現評分。