YouTube摘要 是做什麼的？
工作流程：取得逐字稿 -> 全部讀取 -> 撰寫結構化Markdown摘要 -> 輸出PDF。
scripts/fetch_transcript.py 負責第一步，scripts/md_to_pdf.py 負責最後一步。你在中間撰寫摘要。
1. 存取權限：僅限使用者本即可觀看的內容
- 公開與非公開影片無需登入。優先嘗試不使用cookies。
- 私人或會員限定影片會使腳本以
NEEDS_SIGNIN狀態退出。你只能透過從一個已授予存取權限的使用者帳戶所登入的瀏覽器中讀取cookies來繼續。- 先詢問使用哪個瀏覽器（如果使用者使用多個設定檔，也要問是哪個），然後傳遞
--browser參數。Cookies就是使用者的憑證。 - 告知使用者，yt-dlp的文件警告：自動化使用已登入帳戶可能導致帳戶被限速或封鎖。對於他們自己的上傳內容，使用YouTube Studio下載或Google Takeout是無風險的替代方案，而腳本也接受這些方式產生的本地檔案。
- 先詢問使用哪個瀏覽器（如果使用者使用多個設定檔，也要問是哪個），然後傳遞
- 切勿嘗試繞過隱私設定、地區限制、DRM或付費牆，也切勿使用他人帳戶。如果使用者的帳戶無法觀看該影片，請直接告知並停止。
- 即使使用
--browser仍顯示「此影片為私人影片」，通常表示擁有存取權的帳戶並非瀏覽器預設登入的帳戶。建議使用--browser chrome:"Profile 2"，或在一個全新設定檔中登入該帳戶。
2. 取得逐字稿（分離執行：長影片需時較久）
使用一個持久的作業資料夾，切勿使用可能在工作進行中被清除的臨時區：~/youtube-summaries/<影片ID或檔案主檔名>/。
以分離模式啟動作業，使其在會話結束後仍能繼續執行：
OUT=~/youtube-summaries/<ID>; mkdir -p "$OUT"
nohup python3 -I ~/.claude/skills/youtube-summary/scripts/fetch_transcript.py "<網址或檔案>" \
--out "$OUT" [--browser chrome] [--lang en|auto] [--force-audio] [--audio mp3|m4a|wav] \
> "$OUT/run.log" 2>&1 &!
然後使用一個背景Bash until迴圈來等待，而不是輪詢，例如：
until grep -qE '^(DONE|FAILED|NEEDS_SIGNIN)' "$OUT/status"; do sleep 15; done; cat "$OUT/status"。
腳本會做什麼：
- 探測元數據，然後優先使用手動字幕，若無則使用自動字幕；
- 完全沒有字幕時，下載音訊並使用mlx-whisper large-v3-turbo（Apple Silicon）或openai-whisper（其他平台）進行語音轉文字。如果系統未安裝ffmpeg，則從
imageio-ffmpeg取得； - 移除Whisper產生的沉默幻覺（例如「Thank you.」）以及自動字幕中的重複內容；
- 將結果寫入
transcript.txt，以每2分鐘[h:mm]段落的形式呈現，並產生meta.json。
時間估算：在8GB記憶體的M系列Mac上，每小時音訊約需4-5分鐘進行語音轉文字，此外還需加上下載時間。告知使用者預期等待時間，如果他們詢問進度，則回報下載百分比或run.log中的最新時間戳記。
當自動字幕品質不佳時（如音樂、口音重、語言錯誤），使用 --force-audio。對於非英語影片，使用 --lang auto。
音訊提取： 每當使用者想要音訊本身時（如「給我mp3」、「提取音訊」、播客版本或離線收聽），傳遞 --audio mp3（或 m4a/wav）。檔案將以 <標題>.<格式> 格式儲存在 $OUT 中，其路徑會記錄在 meta.json 的 audio_file 欄位。如果可用，仍會使用字幕來產生逐字稿，因此要求音訊並不會強制進行緩慢的語音轉文字。如果使用者只想要音訊而不要摘要，則在此步驟後停止並回報檔案。
3. 讀取所有內容，然後進行摘要
讀取完整的 transcript.txt；使用者通常想要所有細節。超過約6萬詞時，請按順序分塊讀取，並在寫入前為每個區塊做筆記。
用你自己的話寫出 $OUT/summary.md：這是一份摘要，不是逐字稿。簡短引用是可以的；但不要長篇照抄。預設結構（請根據影片內容調整章節）：
# <影片標題>
| | |
|---|---|
| 影片 | <標題> |
| 頻道 | <頻道名稱> |
| 連結 | <網址> |
| 長度 | <時長> |
| 講者 | <僅限影片中實際提及的名字> |
| 逐字稿來源 | <手動字幕 / 自動字幕 / 本地Whisper語音轉文字> |
## 1. 概覽
- 5-8個要點：影片涵蓋的內容和主要結論
## 時間軸
| 時間 | 主題 |
|---|---|
| 0:00 | ... |
## 2. <按影片順序，每個章節/主題一個區段>
### <子主題>
- 每一個具體的事實、數字、名稱、定義、範例、步驟、警告和建議
- 示範和逐步操作以編號步驟呈現；比較則使用表格
## 重點摘要 / 關鍵要點
| 項目 | 數值 |
## 關於此摘要的備註
> 逐字稿是如何產生的；你修正了哪些聽錯的術語；講者說錯的陳述（附上修正）；任何聽不清楚或不確定的部分。
為什麼採用這種結構：時間軸讓讀者可以跳到影片的特定部分；表格彙整了人們日後常搜尋的事實；備註區則讓你誠實面對語音轉文字的錯誤。語音轉文字常會搞錯產品名稱和專業術語，請根據上下文修正它們並列出修正內容。核實講者說錯的事實，而不是照單全收。
保持內容有據可查：備註區以上的所有內容都應來自逐字稿或 meta.json。讀者將這份文件視為「影片內容」的紀錄，因此你碰巧知道的關於影片的資訊（例如講者真實身份、拍攝地點、歷史）不應放在主體中，即使你非常確定。如果這些背景資訊確實有幫助，請放在備註區並標明「影片外資訊」。切勿指定影片未提供的姓名或代名詞。如果影片描述與內容無關（重複使用或垃圾描述很常見），請忽略它，並在備註區中說明。
文件篇幅應與影片長度相符。僅在需要為超長文件（例如數小時直播的每個章節）開始一個新的主要部分時，才使用 <!-- pagebreak -->，切勿在封面表格之後立刻使用。一個2分鐘的短片應只佔一兩頁。
4. 渲染並檢查PDF
uv run ~/.claude/skills/youtube-summary/scripts/md_to_pdf.py "$OUT/summary.md" "$OUT/<標題>.pdf"
在報告之前，先將第1頁和一個內容密集的頁面渲染為PNG檢查：
uvx --with pypdfium2 --with pillow python -c "..."。
然後提供給使用者：
- PDF的絕對路徑和頁數；
- 3-5行的概覽；
- 任何注意事項：自動產生的逐字稿、聽不清楚的段落。
音訊檔案可能很大。請提及這點，讓使用者決定是否刪除。
故障排除
- 公開影片出現
請登入以確認你不是機器人/ HTTP 403：請等待並重試。如果持續發生，則是IP或限速問題。不要迴圈重試。 - yt-dlp JS執行時期警告：當缺少Deno時，腳本會傳遞
--js-runtimes node。需要Node 22或更高版本。 - 逐字稿沒有文字，或充滿垃圾內容：請檢查語言設定（
--lang auto），或使用--force-audio重新執行。