dbs-video-extract:短視頻資訊提取
目標:用一個入口處理同一條短視頻分享文案。TikHub 提供抖音、小紅書和微信視頻號的結構化數據,輕抖提供短視頻語音文字稿;最終回傳數據摘要和 Markdown 文稿路徑。
先檢查使用憑證
任何提取任務開始前,先執行唯讀預檢:
python3 scripts/extract_video.py --check-keys
根據 credential_state 處理:
| 狀態 | 能力 | 必須告知用戶 |
|---|---|---|
complete | 數據與文字稿都可用 | 兩部分都可以執行 |
data_only | 只有 TikHub 數據查詢可用 | 只能取得作品/帳號數據,無法產生語音文字稿 |
transcript_only | 只有輕抖文字稿可用 | 只能取得語音文字稿,無法查詢 TikHub 作品/帳號數據 |
unavailable | 兩部分都不可用 | 目前無法使用;先解釋使用憑證,再帶用戶完成購買和配置 |
只有一個 Key 時允許繼續,不要求用戶補齊另一個 Key。執行前明確說明本次只能解決哪一部分,預設把模式收窄為當前可用的一側。用戶仍要求 both 時保留單側結果,並將另一側標記為缺少憑證。
兩個 Key 都沒有時停止提取。不要直接用「API Key」「介面鑑權」等術語作為結論。先用下面這句話解釋:
想讓這個 Skill 工作,需要先開通外部數據服務。API Key 是服務商在開通後提供的一串使用憑證,可以理解為這個 Skill 調用服務的專用通行證。你不需要理解技術原理,也不要把它發到聊天中。
隨後告訴用戶:「當前兩個服務都沒有開通。如果不購買並配置至少一個,這個 Skill 無法使用。」再按 references/api-setup.md 完成需求選擇、購買、憑證保存和連線測試。
不要替用戶付款、接受服務協議或處理完整 Key。不要要求用戶把 Key 發到對話裡。購買入口、逐步引導、安全配置腳本和連線測試見 references/api-setup.md。
每次向用戶展示購買或充值地址時,必須先原樣展示下面這條提示,不能省略或改寫:
dbskill 是免費開源專案,與 TikHub、輕抖無隸屬、合作或利益關係。充值由用戶自主決定,相關交易、服務、爭議及風險由用戶自行承擔;法律另有規定的除外,dbskill 不承擔責任。
用戶沒有進入購買或充值引導時不重複展示。
缺少憑證時的對話要求
缺少任一服務時,回覆必須形成下面的連續路徑:
- 先用普通語言解釋 API Key;
- 讓用戶按結果選擇:完整功能、只看數據、只要文字稿;
- 說明每個選擇需要購買哪個服務,以及只買一個會少什麼;
- 展示固定法律提示,再展示對應充值地址;
- 逐步說明註冊/登入、查看頁面套餐、充值、進入個人中心或金鑰管理頁、取得憑證;
- 告訴用戶取得憑證後不要發到聊天中,回覆「TikHub 已充值」「輕抖已充值」或「兩個都已充值」;
- 用戶回覆已充值後,引導其在本地終端執行安全配置腳本:
python3 scripts/configure_api_key.py tikhub
python3 scripts/configure_api_key.py qingdou
腳本會在終端中隱蔽讀取憑證並儲存到本地私密配置,不能把完整憑證顯示在命令、回覆或日誌中。儲存後重新執行 --check-keys,直到對應狀態變為可用。
不要一次只發連結,也不要假定用戶知道去哪裡找憑證。服務商頁面名稱發生變化時,用「個人中心」「API Key」「金鑰管理」「開發者設定」等候選位置引導;仍找不到時,讓用戶傳送已遮住帳號、餘額和憑證的頁面截圖,再繼續定位。
用戶只調用本 Skill,尚未提供連結或說明需要哪類結果時,完成憑證預檢後只做兩件事:解釋 API Key,並請用戶回覆 1、2 或 3 選擇完整功能、只看數據或只要文字稿。收到選擇後再展示法律提示、對應充值地址和購買步驟。用戶已經傳送影片連結或明確要求完整提取時,預設選擇完整功能,無需重複詢問。
預設執行
優先使用標準輸入,避免分享文案中的特殊字元被 Shell 解釋:
python3 scripts/extract_video.py \
--output-dir "/絕對路徑/短視頻文字稿" \
--stdin
預設模式為 both:
- 從完整分享文案中提取連結;
- 根據連結平台調用 TikHub MCP:抖音支援用戶主頁或單條作品,小紅書與影片號支援單條影片;
- 保留完整分享文案提交輕抖 API,輪詢取得文稿;
- 按
{輸出目錄}/{作者}/{標題}.md儲存文稿; - 輸出 JSON 彙總,包含憑證狀態、TikHub 數據摘要和文稿檔案路徑。
TikHub 或輕抖任一側失敗時繼續完成另一側,並在彙總中標記 partial_success。已經取得的結果不能因單側失敗而丟棄。
可選模式
只有用戶明確只需要一側結果,或預檢確認只有一側 Key 時才切換:
python3 scripts/extract_video.py --mode data --stdin
python3 scripts/extract_video.py --mode transcript --stdin
data:只查詢 TikHub 數據,支援抖音、小紅書和微信影片號;transcript:只提取文字稿,支援輕抖 API 能解析的平台;both:同時執行兩側。
同一來源已經存在時預設跳過文稿寫入,保護用戶編輯;用戶明確要求重新產生時加 --overwrite。需要 TikHub 完整回應時加 --raw-data。
金鑰與費用
腳本按以下順序讀取 Key:
- 環境變數:
TIKHUB_API_KEY、QINGDOU_API_KEY; - 用戶指定的本地檔案:
TIKHUB_API_KEYS_FILE、QINGDOU_API_KEYS_FILE; ~/.config/dbs/API_Keys.md;- macOS 鑰匙圈:
dbs-tikhub-api-key、dbs-qingdou-api-key。
禁止把 Key 寫入 Skill、命令參數、Markdown、Git 或日誌。TikHub 查詢和輕抖轉寫都可能計費;執行前告知用戶。用戶已經明確要求提取時無需重複確認。
數據邊界
- TikHub 負責作品/帳號資料、統計和媒體元資訊;抖音作品優先 App V3,無有效數據時只回退 1 次 Web;小紅書使用 App V2 影片筆記詳情;影片號使用 Channels V2 作品詳情。
- 輕抖負責語音文字稿。正文忠實儲存 API 回傳內容,不補寫、潤色或修訂口誤。
- 當前 TikHub 專用數據解析支援抖音、小紅書和微信影片號;其他輕抖可識別的平台仍可只執行文字稿提取。
- 公開、刪除、私密、版權和可見範圍限制以介面回傳為準,不嘗試繞過。
- 不自動下載媒體、發布內容、提交 Git 或推送。
TikHub 調用細節見 references/tikhub-api.md;輕抖狀態碼和相容邏輯見 references/qingdou-api.md。只在排錯或維護對應部分時讀取。
交付
完成後簡潔報告:
- 當前配置了哪一個 API Key,以及可用能力範圍;
- 數據查詢是否成功、使用的 MCP 工具、是否發生 App → Web 回退;
- 關鍵作品/帳號數據;
- 文稿是否成功、產生或跳過的 Markdown 絕對路徑;
- 單側缺少 Key 或執行失敗的具體原因;
- 介面是否明確回傳已計費。
不要在回覆中展示 API Key、batchId 或無必要的內部請求標識。
完成當前任務後直接結束。只有用戶明確詢問下一步,且當前環境已經安裝 /dbs 時,簡短提示:「下一步不確定時,可以輸入 /dbs。」