油管逐字稿代理技能

YouTube 文字記錄

下載 YouTube 影片的文字記錄（字幕／隱藏式字幕）。適用於手動建立和自動產生的文字記錄。無需 API 金鑰或瀏覽器 — 直接使用 YouTube 的內部管線 API，並在 YouTube 阻擋直接 API 路徑時自動退回使用 yt-dlp。

首次執行時擷取影片中繼資料和封面圖片，快取原始資料以便快速重新格式化。

指令碼目錄

指令碼位於 scripts/ 子目錄中。{baseDir} = 此 SKILL.md 的目錄路徑。解析 ${BUN_X} 執行階段：若已安裝 bun → bun；若 npx 可用 → npx -y bun；否則建議安裝 bun。將 {baseDir} 和 ${BUN_X} 替換為實際值。

使用方式

# 預設：附時間戳記的 Markdown（英文）
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# 指定語言（優先順序）
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# 無時間戳記
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# 章節分段
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# 說話者辨識（需要 AI 後處理）
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT 字幕檔
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# 翻譯文字記錄
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# 列出可用的文字記錄
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# 強制重新擷取（忽略快取）
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

選項

選擇性環境變數

輸入格式

接受以下任一項作為影片輸入：

• 完整網址：https://www.youtube.com/watch?v=dQw4w9WgXcQ
• 短網址：https://youtu.be/dQw4w9WgXcQ
• 嵌入網址：https://www.youtube.com/embed/dQw4w9WgXcQ
• Shorts 網址：https://www.youtube.com/shorts/dQw4w9WgXcQ
• 影片 ID：dQw4w9WgXcQ

輸出格式

輸出目錄

youtube-transcript/
├── .index.json                          # 影片 ID → 目錄路徑對應（用於快取查詢）
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # 影片中繼資料（標題、頻道、說明、持續時間、章節等）
    ├── transcript-raw.json              # 來自 YouTube API 的原始文字記錄片段（已快取）
    ├── transcript-sentences.json        # 句子分段文字記錄（依標點符號分割，跨片段合併）
    ├── imgs/
    │   └── cover.jpg                    # 影片縮圖
    ├── transcript.md                    # Markdown 文字記錄（從句子產生）
    └── transcript.srt                   # SRT 字幕（從原始片段產生，若使用 --format srt）

• {channel-slug}：頻道名稱（kebab-case 格式）
• {title-full-slug}：完整影片標題（kebab-case 格式）

--list 模式僅輸出至 stdout（不儲存檔案）。

快取

首次擷取時，指令碼會儲存：

• meta.json — 影片中繼資料、章節、封面圖片路徑、語言資訊
• transcript-raw.json — 來自 YouTube API 的原始文字記錄片段（{ text, start, duration }[]）
• transcript-sentences.json — 句子分段文字記錄（{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]），以句子結尾標點符號（.?!…。？！ 等）分割，時間戳記按字元長度比例分配，具備 CJK 感知的文字合併
• imgs/cover.jpg — 影片縮圖

後續對相同影片的執行會使用快取資料（無網路呼叫）。使用 --refresh 可強制重新擷取。若要求不同語言，快取會自動重新整理。

當 YouTube 針對直接內部管線路徑傳回反機器人／封鎖回應時，指令碼會以替代客戶端身分重試，然後在可用時退回到 yt-dlp。若需要退回但 yt-dlp 不可用，代理程式應自行決定如何讓 yt-dlp 變為可用並繼續，而非將安裝決策推給使用者。

SRT 輸出（--format srt）是從 transcript-raw.json 產生。文字／Markdown 輸出則使用 transcript-sentences.json 以獲得自然的句子邊界。

工作流程

當使用者提供 YouTube 網址並需要文字記錄時：

1. 首先以 --list 執行（若使用者未指定語言），以顯示可用選項
2. 執行指令碼時，務必對網址加上單引號 — zsh 會將 ? 視為 glob 萬用字元，因此未加引號的 YouTube 網址會導致「找不到相符項目」：使用 'https://www.youtube.com/watch?v=ID'
3. 預設：使用 --chapters --speakers 執行以獲得最豐富的輸出（章節 + 說話者辨識）
4. 指令碼會自動儲存快取資料 + 輸出檔案並印出檔案路徑
5. 對於 --speakers 模式：在指令碼儲存原始檔案後，按照下方的說話者辨識工作流程進行後處理，加上說話者標籤

當使用者僅需要封面圖片或中繼資料時，以任何選項執行指令碼也會快取 meta.json 和 imgs/cover.jpg。

對相同影片重新格式化時（例如，先文字後 SRT），會重複使用快取資料 — 無需重新擷取。

章節與說話者工作流程

章節（--chapters）

指令碼會從影片說明中解析章節時間戳記（例如 0:00 簡介），依章節邊界分段文字記錄，將片段分組為易讀的段落，並儲存為含有目錄的 .md 檔案。無需進一步處理。

若說明中沒有章節時間戳記，文字記錄會以分組的段落輸出，不含章節標題。

說話者辨識（--speakers）

說話者辨識需要 AI 處理。指令碼會輸出一個原始的 .md 檔案，包含：

• 含有影片中繼資料的 YAML 前置資料（標題、頻道、日期、封面、說明、語言）
• 影片說明（用於擷取說話者名稱）
• 來自說明的章節列表（若有）
• 原始文字記錄，SRT 格式（預先計算的開始／結束時間戳記，省 Token）

在指令碼儲存原始檔案後，產生一個子代理程式（使用較便宜的模型，例如 Sonnet，以節省成本）來處理說話者辨識：

1. 讀取儲存的 .md 檔案
2. 讀取位於 {baseDir}/prompts/speaker-transcript.md 的提示範本
3. 按照提示處理原始文字記錄：
   • 使用影片中繼資料辨識說話者（標題 → 來賓，頻道 → 主持人，說明 → 名稱）
   • 從對話流程、問答模式及上下文線索中偵測說話者轉換
   • 分段為章節（若有說明中的章節則使用，否則根據主題轉換建立）
   • 以 **說話者名稱：** 標籤、段落分組（2-4 句）和 [HH:MM:SS → HH:MM:SS] 時間戳記格式化
4. 以處理後的文字記錄覆寫 .md 檔案（保留 YAML 前置資料）

使用 --speakers 時，隱含 --chapters — 處理後的輸出總是包含章節分段。

錯誤情況