YouTube 轉錄 v4.0.0
主要完整產品執行環境是 youtube-note-reader Obsidian 桌面外掛。它擁有確定性狀態機、呼叫已設定的 OpenAI 相容模型、執行這些腳本、持久化任務狀態，並將完成的筆記寫入作用中的 Vault。Chrome 擴充功能僅提供當前影片 URL 與瀏覽器 Cookie。OpenCode 仍是選用的純技能入口，完整的瀏覽器與 Obsidian 安裝不需要它。
將此技能嚴格視為狀態機。不要即興發明其他提取路徑。
版本
當使用者詢問當前版本時，執行：
python .obsidian/skills/youtube-transcript/scripts/video_note.py --version
回傳命令輸出。永遠不要憑記憶回答。它會報告安裝的版本、來源路徑以及核心檔案的 SHA-256 值。
固定工作流程
對每個 URL，請依序完成下列步驟，然後再處理下一個 URL。如果遇到第一個非零的腳本結果，立刻停止整個批次。
- 提取來源素材：
python .obsidian/skills/youtube-transcript/scripts/extract_transcript.py "<url>" --output-dir "YouTube video" --deadline 300
-
閱讀產生的筆記及其 SRT。建立一個包含
article_outline與frames的 JSON 計畫。article_outline包含 3-8 個從轉錄稿中推導出的章節；每個項目皆有section_id、title、start、end、core_claims與learning_goal。根據學習價值選擇圖格（frames），通常每個視覺上有意義的章節需要一個必要圖格，外加一些可選的證據用於不同的步驟或結果。大部分影片需要 6-14 個圖格；24 只是硬性的安全上限，絕非目標。不要為了增加數量而建立多個極度相似的時間點。每個圖格都有section_id、timestamp、purpose與required。使用相同的section_id將每個截圖綁定到其詳細摘要章節。不要重新命名或改寫筆記。不要撰寫探測腳本或手動檢查影片格式。 -
恰好一次提取計畫中的圖格。在取得成功的素材結果後，這是唯一允許的下一步可執行命令：
python .obsidian/skills/youtube-transcript/scripts/extract_frames.py "<url>" --plan "<plan.json>" --note "<generated-note.md>" --output-dir "YouTube video" --deadline 120
-
確認圖格結果中包含
status: ok、至少一個螢幕截圖，以及一個真實的manifest路徑。腳本會自動將frame_manifest寫入筆記的 YAML。如果缺少以上任何一項，請停止；不要撰寫最終筆記，也不要使用縮圖替代。 -
根據 references/note-contract.md 在原地重新命名並改寫產生的筆記。在
## 详细内容总结下方，將每個article_outline.title作為精確的###標題，解釋其核心主張，並將每個成功的必要圖格插入到對應章節並附上中文說明。對於 Vault 本機截圖，一律使用 Obsidian wiki 嵌入格式，例如![[YouTube video/assets/VIDEO_ID/frame.jpg]]；絕不使用含有空格的未跳脫 Markdown 目標。只有 manifest 所列出的圖片才算作螢幕截圖。 -
驗證：
python .obsidian/skills/youtube-transcript/scripts/validate_note.py "<finished-note.md>"
- 若驗證失敗，僅編輯該筆記一次，然後再次執行驗證器。修復期間絕對不要執行提取、撰寫暫存腳本、檢查實作程式碼或診斷平台行為。如果仍失敗，請停止並回傳所報告的錯誤。成功驗證後，驗證器會自動刪除相同資料夾中名為
待命名 - ...且 YAMLurl與最終筆記完全相符的 Markdown 草稿；不相符的中斷草稿則保留以便恢復。
失敗策略
PIPELINE_RESULT 是真相來源。當狀態為 status: error 時，立即停止並報告該 URL、階段、代碼、訊息、動作、已完成的 URL 列表以及尚未開始的 URL 列表。
絕對不要因為失敗就去執行另一個下載器、瀏覽器、Puppeteer、Chrome/Edge Cookie 提取、網路搜尋、音訊錄製或再次嘗試。唯一受控的重試機制在腳本內部：一個最後已知良好的 Cookie 檢查，以及在目標圖格提取期間的一次影片串流 URL 重新整理。
ASR 預設為停用。只有當使用者明確接受音訊下載與較慢處理時，才使用 --allow-asr。
視覺需求
- 螢幕截圖是證據，不是裝飾。
- 使用示範、介面、圖表、參數、比較狀態與結果。
- 圖格腳本首先嘗試使用含 yt-dlp 請求標頭的遠端 720p 或更低解析度串流。若遠端尋訪失敗，它可能會僅下載每個計畫時間點前後 8 秒的區段。暫存區段會立即刪除，絕不會為了截圖而下載完整影片。
- 必要圖格失敗或低於 70% 的圖格計畫覆蓋率即為硬性失敗。
- 封面、縮圖、手動複製的圖片或重複的嵌入絕不算作關鍵影格。
- 即使計畫中的圖格總體布局相似，也應保留。終端文字、程式碼、投影片與 UI 狀態變更都很有用。僅拒絕真正空白的黑/白圖格；不要使用 OCR、AI 影像分析或感知重複過濾。
- 除非存在
frame_manifest且每個必要的 manifest 圖格都出現在## 详细内容总结，否則絕不聲稱完成。 - 不要建立 Canvas 檔案。
最終筆記需求
- 檔案名稱：
中文标题 - English Title。 - YAML 包含
skill_version: 4.0.0、quality_profile_version: 1，以及由extract_frames.py寫入的有效frame_manifest。 - 主體從
## 一句话摘要開始，沒有重複的 H1 標題。 - 從最終主體中移除來源狀態、影片描述、視覺素材索引、提取警告、任務指示以及自我檢查段落；YAML 已承載來源元資料。
- 優先使用繁體中文；首次使用必要的英文術語時應加以解釋。
- 讓轉錄稿決定文章大綱與深度。圖片支援說明；絕不因為缺少對應圖格而縮短或省略重要內容。
- 文章深度應與影片長度匹配。每個計畫中的章節都需要實際的解釋、影片證據或範例，以及明確的學習意涵。避免泛泛的填充文字與重複段落。
- 在結尾處連結 SRT。不要貼入原始轉錄文字。
- 在最終完成前移除自我檢查清單。