Communitygithub.com

video2agent

影片搜尋與理解工具,適用於本地檔案、螢幕錄影及平台連結。當問題最好透過即時、視覺或社群測試的影片來回答時,應主動使用——例如遊戲賽季/版本強度排行、裝備配置、產品評測、食譜、旅遊、熱門話題,以及前端/UI 測試的錄影、教學和操作指南,還有工作/學習/生活中影片比文字更豐富的場合。也適用於使用者詢問影片內容、表格/圖表/程式碼出現位置、需要時間戳記逐字稿或精確畫格,或需要處理 Bilibili 收藏/觀看記錄/資料夾(寫入操作需經明確確認)。

video2agent 是什麼?

video2agent 是一個專門用於從影片中提取資訊的 AI 工具,支援本地檔案、螢幕錄影以及 Bilibili 等平台的連結。它能讓大型語言模型直接透過工具呼叫來取得影片的逐字稿、螢幕文字、結構化大綱和精確畫格,而不是單純依賴記憶或過時的知識。這款工具特別適合回答那些依賴視覺驗證或最新社群內容的問題,例如遊戲版本強度排行、產品評測、食譜步驟或 UI 動畫的變更。它支援 Cursor、Claude Code、Codex 等主流 AI 代理平台,透過八個核心指令(find、ingest、outline、read、evidence、frames、perceive、admin)提供從搜尋、索引、分析到匯出的完整流程。工作流程建議先使用 outline 或 read 取得低成本概覽,再根據需求使用 evidence 或 frames 進行精確的畫格查證,最後才考慮匯出。使用時必須遵循「文字優先、圖片其次」的原則,避免對每個影片都呼叫工具,並妥善處理錯誤回應而非重試。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Harm0ny-AI/DSH-Video2Agent/tree/HEAD/skills/video2agent

在你喜歡的 AI 中提問

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

說明文件

DSH-Video2Agent

從影片中取得答案:逐字稿、螢幕文字、結構、精確畫格。模型負責推理;這個工具負責找出答案需要「看到」才能回答的時刻。

何時影片是更好的來源

問題不一定非得「關於某一部影片」才能用影片回答:遊戲新賽季的強度排行或裝備配置(新赛季枪械排行、配装)、產品評測、食譜、路線、即時視覺話題。在憑記憶回答之前,先在 Bilibili 上呼叫 find(或搜尋資料庫)。切勿將過時的賽季當作當前資訊呈現:檢查上傳日期和標題中的版本,並說明影片是否早於該版本。

直接呼叫

只要執行環境允許,就將 video2agent 工具作為頂層工具呼叫。絕不要透過 shell 呼叫 CLI 來執行工具動作。巢狀的 run_code 呼叫會繞過插件的 dock 渲染,因此只有在執行環境沒有其他方式能接觸到工具時才使用;否則卡片可能保持空白。

在對話中回答;僅在使用者要求時才匯出

影片的答案應該直接在對話中提供。除非使用者明確要求匯出檔案,否則不要建立或匯出筆記、Markdown 檔案、知識包、逐字稿檔案或暫存檔案。檔案不是解答的替代品。

八個指令

指令回傳內容使用時機
findBilibili 候選影片(標題/上傳者/長度/原因)尋找影片;scope:"library" 搜尋已索引的影片;url 解析單一連結
ingest任務 ID索引路徑/URL;video_ids 開始選定的候選清單;job_id 輪詢;campaign_id 推進一個批次
outline一次呼叫的索引:逐字稿/OCR 行、關鍵畫格、剪輯點、覆蓋範圍(detail:"digest")、中繼資料(overview)、視覺地圖首次查看影片
read緊湊的時間戳逐字稿,或 2-10 部影片的比較文字答案或比較
evidence指定時間戳的畫格 + 其 OCR 文字 + 逐字稿證明某個時刻;標準圖片路徑
frames精確畫格、密集視窗、圖表、鏡頭候選、OCR 視窗文字無法回答的像素問題
perceive僅數字的分析:剪輯點、每個區塊的動作、排名時刻、循環、錄製品質 — 不含圖片動作/UI/動畫問題
admin列出/匯出/OCR 索引/帳號/診斷資料庫維護、匯出、Bilibili 資料庫

工作流程

1. 搜尋 (Find)

使用 query 呼叫 find;可使用 uploader、after、before 篩選。回覆是給你看的,不是表格:閱讀中繼資料,然後用你實際推薦的 ID 呼叫 ingest;所有你將分析的影片都放在 default_selected(只有這些會開始處理,video_ids 只是列出候選)加上 primary。超過 processLimit 時 → 設定 campaign:true。

貼上的 URL → 先以 url 呼叫 find(取得標題/封面/長度,不下載),然後在使用者確認後呼叫 ingest。

2. 索引 (Ingest)

使用 source(本地路徑或 URL)呼叫 ingest 會回傳一個任務 ID。不要再次透過 URL 索引 find 找到的候選影片;候選清單已經開始處理。需要等待嗎?使用 job_id 和 wait_ms 呼叫 ingest —— 一次,一個任務(上限 90 秒;程式在 120 秒左右會終止:不要在數個任務間迴圈)。queued 表示索引槽忙碌且任務尚未開始;不要再輪詢它。錯誤的逐字稿語言 → 使用 language 參數呼叫 ingest。

3. 讀取 (Read)

outline(detail:"digest")是最便宜的初步查看:一個有界索引,包含時間戳逐字稿/OCR 行、關鍵畫格、場景剪輯點和覆蓋範圍。然後:

  • 內容問題 → 使用 start/end 呼叫 read(scope:"transcript");回覆會攜帶 next_start_ms,因此繼續使用而非要求整個檔案。
  • 比較 2-10 部影片 → 使用 compare_video_ids 和 aspects 呼叫 read(scope:"compare")。
  • 詞語可能不同(ASR 拼寫變體、計費/收費/價格)→ 在一次呼叫中對 find(scope:"library")傳入 2-8 個 queries 變體。單一字面查詢是誤判「影片中沒有該內容」的最常見原因。
  • 零結果搜尋並非證據:請閱讀 NO_MATCH、OCR_NOT_INDEXED、OCR_INDEX_PARTIAL;它們會說明文字是否曾被讀取。

3b. 短影片快速路徑

對於長度約 6 分鐘以下、問題是關於「說了什麼」(而非螢幕上顯示什麼)的片段,可以跳過 outline 直接呼叫 read:整個逐字稿通常可以塞進一次回覆(約 150–800 個 token),相較之下 outline 需要約 1.4k 個 token 加上一張聯絡表圖片。實測:6000 字的 read 上限大約涵蓋 8 分鐘的快節奏中文評論和 5.5–7 分鐘的英文內容。如果回覆攜帶了 next_start_ms,表示被截斷了——改用 search/outline 處理其餘部分,而不是分頁。當你需要結構、螢幕文字或視覺內容時使用 outline;需要動作時使用 perceive。如果使用者自己貼上了逐字稿/字幕,就直接從那段文字回答問題,只在需要圖片的時刻才使用影片。

4. 查看 (evidence / frames)

使用 at 呼叫 evidence 會回傳畫格及其螢幕文字和逐字稿。預設 2 張圖片;images:0 僅文字,images:1 一張圖片。

frames 用於文字無法回答的問題(計數、動作、顏色、佈局):

  • at + count:精確畫格。
  • start/end:密集視窗(≤5 秒);sheet:true 將最多 9 個畫格拼貼成一張帶標籤的圖片;windows:N 將一個命名範圍取樣成一張覆蓋圖並回報覆蓋/缺失情況。
  • view:"candidates":鏡頭列表(時間碼 + 關鍵畫格),用於「找出一個片段」。
  • view:"ocr":當螢幕上的某行文字改變時,對一個短視窗的每個畫格執行 OCR。

5. 動作分析 (perceive)

對於動畫、UI 轉場、「什麼改變了」、「它往哪裡移動」:在呼叫 frames 之前先呼叫 perceive。它會以數字形式回傳剪輯點、每個區塊的動作、排名 moments(t_ms 峰值、onset_ms 開始時間、cell、settles)、循環狀態和錄製品質(丟幀/重複幀、閃爍)。

  • 長度超過 10 分鐘的影片需要一個視窗:先找到時刻(逐字稿/搜尋),然後使用 start/end;沒有任何範圍的呼叫會回傳 E_WINDOW_REQUIRED。
  • brief:true 是概覽(約 340 個 token,包含剪輯點和 4 個時刻);然後再次呼叫(不含此參數)以取得所需視窗(約 850 個 token,適用於 2.5 分鐘的內容)。
  • loop.found == false 表示「在此處未偵測到循環」,而非「沒有循環」。未指定 regions 和 coverage 時,切勿稱一部影片為靜態。
  • 字幕可信度可被測量:overview 會回報 metrics.caption_check(音訊 vs 字幕)。CAPTION_AUDIO_UNVERIFIED 表示字幕無法被驗證——請如實說明,而不是將它們當作精確內容引用。

6. 帳號與匯出

使用 admin_action:"account" 呼叫 admin 可讀取收藏/觀看記錄/資料夾;寫入操作僅限 CLI(--confirm);資料夾名稱 ≤20 個字元,每次寫入 ≤100 部影片。

使用 admin_action:"export" 呼叫 admin 僅在使用者要求時才寫入知識包。

嚴格規則

  • 絕不要將本地路徑傳送到答案中。 請使用 image_urls / image_markdown(只有 image_attached: true 的位置才是真正的圖片);原始路徑會渲染出一個壞掉的佔位符。
  • 等於或超過媒體結尾的時間戳是 E_OUT_OF_RANGE,而不是空的成功;錯誤訊息會攜帶媒體長度。at/start 中的純數字代表秒;要表示毫秒,請寫 1234ms 或 HH:MM:SS.mmm。
  • 失敗就是答案。 當收到 {ok:false,error:{code,message,remedy}} 時,請回報錯誤碼和補救措施;絕不要憑空編造內容或默默重試。
  • 文字優先,圖片其次。 transcript/search 能回答大部分問題;每一張圖片都會消耗 token。預設 images:2,當文字足夠時使用 0 或 1。
  • 圖片與其文字來自同一個畫格 — 請信任 ocr_frame_ms。
  • 不要傾倒資料。 read 有上限(預設 6000 字元);outline 很精簡;請使用範圍和 next_start_ms。
  • 不要對每部影片都呼叫工具:逐字稿就能回答內容問題;perceive 僅用於時間/UI 相關問題。

參考文件

  • references/commands.md — 8 個動詞 → CLI 對應及所有旗標。
  • references/evidence.md — evidence 酬載欄位與引用格式。
  • references/visual-types.md — 畫格能回答與不能回答的問題。
  • references/dsh.md — DSH 渲染規則。

相關技能