Jo5i4swastaken/Skills-Locker

/watch

你沒有影片輸入；這個技能為你提供一個。一個 Python 腳本會先取得字幕，選擇性地下載影片，將影格提取為 JPEG 格式（場景感知，或在 efficient 詳細程度下使用快速關鍵影格），取得帶有時間戳的逐字稿（優先使用原生字幕，備用 Whisper API），並列印影格路徑。接著，你可以 Read 每個影格路徑來查看圖片，並將它們與逐字稿結合，以回答使用者的問題。

解析 SKILL_DIR（在任何命令前執行此步驟）

以下每個 python3 ... 命令都是在執行 SKILL_DIR/scripts/ 下的捆綁腳本。將 SKILL_DIR 設為包含你剛剛讀取的這個 SKILL.md 檔案的目錄的絕對路徑 — 你的平台在讀取結果中告訴了你該路徑。腳本總是與此檔案位於同一個目錄 (SKILL_DIR/scripts/watch.py)，無論安裝佈局為何：

Read ~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md → SKILL_DIR=…/skills/watch
Read ~/.codex/skills/watch/SKILL.md                                          → SKILL_DIR=~/.codex/skills/watch
Read ~/.agents/skills/watch/SKILL.md                                         → SKILL_DIR=~/.agents/skills/watch

在每個命令中將該文字路徑替換為 ${SKILL_DIR}。這適用於所有平台（Claude Code、Codex、Cursor、Gemini CLI 等），無需依賴任何平台特定的環境變數。在執行開始時，請進行一次檢查：

SKILL_DIR="<包含你讀取的 SKILL.md 檔案的目錄的絕對路徑>"
if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
  echo "錯誤：在 SKILL_DIR=$SKILL_DIR 下找不到 scripts/watch.py" >&2
  echo "請重新檢查你讀取的 SKILL.md 的目錄，並將其設定為 SKILL_DIR。" >&2
  exit 1
fi

步驟 0 — 設定前置檢查（每次 /watch 調用時執行，成功時保持靜默）

Python 直譯器： 此技能中的所有 python3 ... 命令都是為 macOS/Linux 設計的。在 Windows 上，請替換為 python — Windows 上的 python3 命令是 Microsoft Store 的存根，無法執行腳本。

在會話中首次調用 /watch 時，使用結構化前置檢查來偵測首次執行設定：

python3 "${SKILL_DIR}/scripts/setup.py" --json

根據兩個欄位進行分支：

• can_proceed: true 且 first_run: false → 設定已完成（使用者可能故意跳過 Whisper 金鑰 — 這是允許的）。直接進入步驟 1，無需評論。
• first_run: true → 真正的首次設定。請依序執行以下操作：
  1. 如果 missing_binaries 不為空，請先執行安裝器（它在 macOS 上自動安裝，在其他平台上列印命令 — 請參閱下文）並確認二進位檔已安裝。不要跳過此步驟直接跳到偏好設定。
  2. 如有需要，再次執行安裝器，以便它建立 ~/.config/watch/.env 的模板（它只在檔案不存在時才寫入模板，所以請先讓它建立檔案，然後你才能將任何值寫入其中）。
  3. 鼓勵使用者提供 Whisper API 金鑰並詢問下方的 watch 偏好問題，然後將選定的值寫入 ~/.config/watch/.env，並將 SETUP_COMPLETE 設為 true。
• can_proceed: false 且 first_run: false → 設定先前已完成，但環境出現回退（例如 OS 變更後 missing_binaries）。執行安裝器進行修復，然後繼續。無需重新詢問偏好。

缺少 Whisper 金鑰是鼓勵修復，而非必要條件：在真正的首次執行時，即使二進位檔已存在，status 也會顯示 needs_key — 這是鼓勵你提供金鑰的提示，而不是阻礙。

在同一個會話中後續調用 /watch 時，使用靜默檢查：

python3 "${SKILL_DIR}/scripts/setup.py" --check

這是一個 <100ms 的查詢。退出碼 0 表示 /watch 可以執行 — 這包括已完成設定但沒有 Whisper 金鑰的使用者（允許無金鑰）。退出碼為 0 時，腳本不輸出任何內容 — 直接進入步驟 1，無需評論。不要向使用者宣告「設定已完成」 — 他們不需要在每次輪次都看到狀態訊息。步驟 0 唯一可接受的使用者可見輸出是當需要修復時。

若退出碼不為零，請依照下表處理：

退出碼	含義	動作
2	缺少二進位檔 (ffmpeg / ffprobe / yt-dlp)	執行安裝器
3	真正的首次執行但沒有 Whisper API 金鑰	執行安裝器以建立 .env 模板，然後鼓勵提供金鑰（使用者可以拒絕 — 使用 --no-whisper 繼續）
4	兩者皆缺	執行安裝器，然後鼓勵提供金鑰

退出碼 3 僅在使用者完成設定前觸發。一旦寫入 SETUP_COMPLETE=true，無金鑰的安裝將返回退出碼 0，並且不會再被詢問。

安裝器是冪等的 — 重新執行是安全的：

python3 "${SKILL_DIR}/scripts/setup.py"

在 macOS 上使用 Homebrew 時，它會自動安裝 ffmpeg 和 yt-dlp。在 Linux/Windows 上，它會列印出準確的安裝命令供使用者執行。它會建立 ~/.config/watch/.env 模板，包含註解掉的佔位符和預設的 watch 設定，權限設為 0600。

如果安裝後仍然缺少 API 金鑰： 使用 AskUserQuestion 詢問使用者是否有 Groq API 金鑰（首選 — 更便宜、更快）或 OpenAI 金鑰。然後將其寫入 ~/.config/watch/.env — 設定對應的 GROQ_API_KEY=... 或 OPENAI_API_KEY=... 行。如果他們不想設定 Whisper，請使用 --no-whisper 繼續，並告知他們沒有原生字幕的影片將僅返回影格。

首次執行的 watch 偏好設定： 在安裝器建立了 ~/.config/watch/.env 之後，使用 AskUserQuestion 詢問一個問題：

• 預設詳細程度（一個轉盤）。依照此確切順序將這些選項呈現為 AskUserQuestion 選項 — 從最輕到最重 — 並將 (recommended) 保留在 balanced 上，即使它不是第一個選項（不要重新排序以將推薦選項放在最前面）：
  • transcript — 沒有影格，僅逐字稿（當字幕存在時跳過影片下載）。
  • efficient — 快速關鍵影格傳遞（上限 50）。
  • balanced（推薦）— 場景感知影格（上限 100，預設）。
  • token-burner — 場景感知，無上限（最高保真度；高 token 成本）。

將答案直接寫入 ~/.config/watch/.env，在單獨一行設定裸鍵 — 不要有尾隨的內聯註解（值後面的 # 註解 可能會破壞解析）：

WATCH_DETAIL=balanced

使用使用者選擇的值。如果他們跳過問題，則保留推薦的預設值。一旦處理完依賴項、API 金鑰選擇和此偏好設定，請在同一檔案中寫入或更新 SETUP_COMPLETE=true。當 SETUP_COMPLETE=true 時，不要再詢問此偏好問題。

結構化模式（可選）： python3 "${SKILL_DIR}/scripts/setup.py" --json 輸出 {status, can_proceed, first_run, setup_complete, missing_binaries, whisper_backend, has_api_key, config_file, watch_detail, platform}，其中 status 是 ready | needs_install | needs_key | needs_install_and_key 之一。status 描述了理想狀態（鼓勵使用金鑰，因此無金鑰的首次執行顯示 needs_key）；can_proceed 是操作閘門（二進位檔已存在且（已設定金鑰或設定已完成））。根據 can_proceed/first_run 分支來決定是否執行；使用 status 來決定要鼓勵什麼。

在同一個會話中，你可以跳過後續 /watch 調用的步驟 0 — 一旦 --check 返回 0，環境在輪次之間不會改變。

何時使用

• 使用者貼出影片 URL（YouTube、Vimeo、X、TikTok、Twitch 剪輯、大多數 yt-dlp 支援的網站）並詢問相關內容。
• 使用者指向一個本機影片檔案（.mp4、.mov、.mkv、.webm 等）並詢問相關內容。
• 使用者輸入 /watch <網址或路徑> [問題]。

建議限制

• 最佳準確度：10 分鐘以下的影片。 影格覆蓋率與時長成反比。
• 通用速率上限：2 fps。 即使預算或 --fps 暗示更多，腳本也絕不取樣超過 2 fps。
• 影格上限由詳細程度模式決定（~/.config/watch/.env 中的 WATCH_DETAIL，或 --detail），而非單一全域上限：
  • transcript → 無影格
  • efficient → 最多 50（關鍵影格）
  • balanced（預設）→ 最多 100（場景感知）
  • token-burner → 無上限（場景感知；超過 250 影格時會輸出軟性警告）
  • --max-frames N 會覆蓋模式原本使用的任何上限。
• 按時長計算的完整影片影格預算。 Token 成本隨影格數量增加，因此腳本會根據時長設定預算。此預算設定 fps 和均勻取樣備用方案；場景感知選擇最多可以填充到上述詳細程度上限，兩者取較低者：
  • ≤30 秒 → 約 12-30 影格
  • 30 秒-1 分鐘 → 約 40 影格
  • 1-3 分鐘 → 約 60 影格
  • 3-10 分鐘 → 約 80 影格

  • 10 分鐘 → 最多到詳細程度上限，稀疏間隔（輸出警告）

• 如果使用者提供長影片，請考慮在耗用 token 進行稀疏掃描之前，詢問他們是否需要特定區段。

如何調用

步驟 1 — 解析使用者輸入。 將影片來源（URL 或路徑）與使用者提出的任何問題分開。例如：/watch https://youtu.be/abc 這影片是什麼語言？ → 來源 = https://youtu.be/abc，問題 = 這影片是什麼語言？。

步驟 2 — 執行 watch 腳本。 直接傳遞來源。除了正常的引用之外，不要自行對其進行 Shell 跳脫：

python3 "${SKILL_DIR}/scripts/watch.py" "<來源>"

可選標誌：

• --detail transcript|efficient|balanced|token-burner — 保真度/速度轉盤。transcript = 無影格（僅逐字稿，當字幕存在時跳過影片下載）；efficient = 快速關鍵影格（上限 50）；balanced = 場景感知影格（上限 100）；token-burner = 場景感知，無上限。
• --start T / --end T — 聚焦於某個區段。接受 SS、MM:SS 或 HH:MM:SS。當設定了其中任何一個時，fps 會自動調整得更密集（參閱下方「聚焦於某個區段」）。
• --timestamps T1,T2,… — 在這些絕對時間戳（SS、MM:SS 或 HH:MM:SS）處獲取一個影格。在讀取逐字稿後使用此選項，以捕捉主持人指示的時刻（「看這裡」、「如您所見」、「注意這個」），這些是純視覺選擇可能遺漏的。請參閱「逐字稿提示影格」。
• --max-frames N — 覆蓋預設上限以獲得更緊的 token 預算（例如 --max-frames 40）
• --resolution W — 更改影格寬度（單位為像素）（預設 512；僅當使用者需要閱讀螢幕上的文字時才增加到 1024）
• --fps F — 覆蓋自動 fps（限制為最高 2 fps）
• --out-dir DIR — 將工作檔案保留在特定位置（預設：自動生成的暫存目錄）
• --whisper groq|openai — 強制使用特定 Whisper 後端（預設：如果兩個金鑰都存在，則偏好 Groq）
• --no-whisper — 完全停用 Whisper 備用方案（如果沒有字幕，則僅返回影格）
• --no-dedup — 保留近乎重複的影格。預設情況下，影格差異傳遞會丟棄與前一個保留影格在視覺上幾乎相同的影格（如靜止投影片、靜態螢幕錄影、暫停的影片），以便影格預算用於不同的內容；報告的 Frames 行會註明丟棄了多少。僅在使用者需要每個取樣影格時才傳遞此選項（例如判斷細微的影格間運動）。

聚焦於某個區段（更高影格率）

當使用者詢問特定時刻時 — 「2 分鐘標記處發生了什麼？」、「聚焦 0:45 到 1:00」、「前 10 秒」 — 請傳遞 --start 和/或 --end。腳本會切換到聚焦模式預算，這比完整影片預算更密集（仍然限制在 2 fps，並且仍然受詳細程度模式上限約束 — 以下計數假設預設 balanced 上限為 100；efficient 上限為 50）：

• ≤5 秒 → 2 fps（最多 10 影格）
• 5-15 秒 → 2 fps（最多 30 影格）
• 15-30 秒 → 約 2 fps（最多 60 影格）
• 30-60 秒 → 約 1.3 fps（最多 80 影格）
• 60-180 秒 → 約 0.6 fps（100 影格，已達上限）

聚焦模式是以下情況的正確選擇：

• 任何使用者明確命名的時刻/範圍（「大約 2:30」、「開場」、「最後 30 秒」）。
• 任何時長超過約 10 分鐘的影片，且使用者的問題是關於某個特定部分 — 對相關區段執行聚焦模式遠比對整個影片進行稀疏掃描有用得多。
• 在完整掃描後，發現某個區域的詳細程度不夠時重新執行。

逐字稿會自動過濾到相同範圍。影格時間戳是絕對的（真實影片時間軸，而非相對於起始點的偏移）。

範例：

# 1 分鐘影片的最後 10 秒
python3 "${SKILL_DIR}/scripts/watch.py" video.mp4 --start 50 --end 60

# 以 2 fps 聚焦 2:15 → 2:45（60 影格）
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2

# 從 1h12m 到影片結束
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 1:12:00

步驟 3 — 讀取腳本列出的每個影格路徑。 Read 工具會直接將 JPEG 渲染為圖片供你查看。在一條訊息中閱讀所有影格（並行工具呼叫），以便你同時看到它們。影格按時間順序排列，並帶有 t=MM:SS 時間戳，以便你將它們與逐字稿對齊。

步驟 4 — 回答使用者。 你現在有兩個證據串流：

• 影格 — 每個時間戳畫面上有什麼
• 逐字稿 — 每個時間戳說了什麼。報告的標頭會顯示來源（captions = yt-dlp 提取了原生字幕；whisper (groq) 或 whisper (openai) = 由 API 轉錄）。

如果使用者問了特定問題，請直接回答並引用時間戳。如果他們沒有問任何東西，請總結影片中發生了什麼 — 結構、關鍵時刻、值得注意的視覺內容、口語內容。

這也適用於 transcript 詳細程度：即使沒有影格，也要像其他模式一樣產生一個摘要 — 不要將完整的逐字稿貼到聊天中。綜合結構、關鍵時刻和帶有時間戳的口語內容；僅引用重要的台詞。僅在使用者明確要求時才提供原始逐字稿。

步驟 5 — 清理。 腳本會在最後輸出工作目錄。如果使用者不打算針對此影片提出後續問題，請使用 rm -rf <目錄> 刪除它。如果他們可能會提問，則保留它。

詳細程度與影格

預設行為來自 ~/.config/watch/.env：

• WATCH_DETAIL=transcript|efficient|balanced|token-burner（預設：balanced）

在 ...

[由於內容已截斷，此處翻譯僅到提供的內容為止]