DSH-Video2Agent
從影片中取得答案:逐字稿、螢幕文字、結構、精確畫格。模型負責推理;這個工具負責找出答案需要「看到」才能回答的時刻。
何時影片是更好的來源
問題不一定非得「關於某一部影片」才能用影片回答:遊戲新賽季的強度排行或裝備配置(新赛季枪械排行、配装)、產品評測、食譜、路線、即時視覺話題。在憑記憶回答之前,先在 Bilibili 上呼叫 find(或搜尋資料庫)。切勿將過時的賽季當作當前資訊呈現:檢查上傳日期和標題中的版本,並說明影片是否早於該版本。
直接呼叫
只要執行環境允許,就將 video2agent 工具作為頂層工具呼叫。絕不要透過 shell 呼叫 CLI 來執行工具動作。巢狀的 run_code 呼叫會繞過插件的 dock 渲染,因此只有在執行環境沒有其他方式能接觸到工具時才使用;否則卡片可能保持空白。
在對話中回答;僅在使用者要求時才匯出
影片的答案應該直接在對話中提供。除非使用者明確要求匯出檔案,否則不要建立或匯出筆記、Markdown 檔案、知識包、逐字稿檔案或暫存檔案。檔案不是解答的替代品。
八個指令
| 指令 | 回傳內容 | 使用時機 |
|---|---|---|
find | Bilibili 候選影片(標題/上傳者/長度/原因) | 尋找影片;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 渲染規則。