mairp/video-to-deck

video-to-deck 是做什麼的？

從影片製作簡報。你（模型）是純文字模型——你無法聽到音訊或看到畫面。因此，此技能的腳本負責觀看與聆聽，並將文字證據包（evidence.md）交給你。你的工作是僅進行歸納：閱讀證據並寫出好的簡報。請勿憑空捏造證據不支援的內容。

輸出為 Marp Markdown（deck.md）：一個你現在就能閱讀的一般 .md 檔案，並可透過後續的 render.sh 指令產生真正的投影片簡報（PPTX/PDF/HTML）。

$SKILL 下方 = 此技能所在的目錄（包含此檔案的文件夾）。

流程

1. 一次性設定（冪等）

bash "$SKILL/scripts/setup.sh"

安裝 faster-whisper（語音轉錄）、tesseract（OCR），且若 npm 存在，則安裝 marp-cli 與 mermaid-cli。可安全重複執行。必須已預先安裝 ffmpeg。

2. 尋找影片

bash "$SKILL/scripts/find_videos.sh" "<資料夾>"        # 遞迴列出每行一個路徑

若是單一指定檔案，請直接使用該路徑，略過此步驟。

3. 為每支影片建立證據包（一次一支）

bash "$SKILL/scripts/process_video.sh" "<影片>" "<輸出目錄>/<影片主檔名>"

此腳本會：提取音訊 → 轉錄文字，取樣關鍵畫面 → 對螢幕上文字進行 OCR，並寫入 <輸出目錄>/<影片主檔名>/evidence.md（以及 transcript.txt、segments.tsv、frames/、ocr.txt）。在 CPU 上處理長影片會很慢；設定 WHISPER_MODEL=small 可獲得良好品質，或使用 CUDA GPU 以提升速度（會自動偵測；請參閱 scripts/transcribe.py 中的 WHISPER_DEVICE）。請依序處理影片，不要平行處理。

選用視覺辨識功能（Qwen-VL）。 OCR 只能讀取文字。若要捕捉文字無法表示的內容——例如圖表及其趨勢、圖示、UI 佈局、講者的手勢——可以啟用一個視覺模型，為每個保留的關鍵畫面加上說明。此功能預設為關閉；若要啟用，請在執行相同指令的環境中設定 VISION_MODEL（以及必要的 VISION_ENDPOINT）：

VISION_MODEL=qwen2.5-vl \
VISION_ENDPOINT=http://127.0.0.1:8081/v1/chat/completions \
  bash "$SKILL/scripts/process_video.sh" "<影片>" "<輸出目錄>/<影片主檔名>"

啟用後，evidence.md 會在 OCR 的基礎上增加一個 「## 視覺描述」 區段——請將其用於圖表/圖示投影片。任何與 OpenAI 相容的視覺端點皆可使用（例如透過 llama.cpp/llama-swap 或 Ollama 在本機啟動的伺服器，或託管 API；若需要令牌則設定 VISION_API_KEY）。若端點無法連線，腳本會繼續僅使用 OCR 執行——不會造成中斷。

4. 撰寫簡報

閱讀完整的 evidence.md。將 "$SKILL/templates/deck.marp.md" 複製到 <輸出目錄>/<影片主檔名>/deck.md 並填入內容。規則：

• 保留 marp: true 的前置資料——這是使其成為投影片簡報的關鍵。
• 使用轉錄稿來了解內容；使用 OCR / 螢幕文字 來取得投影片上顯示的精確標籤、數字、標題與程式碼；若存在 「視覺描述」 區段（已啟用視覺辨識功能），請用它來呈現 OCR 無法傳達的圖表/圖示/UI。
• 在必要時為某項主張加上時間戳記，例如 [00:04:12]。
• 將投影片的關鍵畫面放在投影片上——這是預設行為，而非可選的裝飾。 ocr.txt 中每個 ### [時間區間] frames/kf_####.jpg 區塊都標明了該投影片的代表性畫面；請將其帶入它所產生的簡報投影片：![](frames/kf_0007.jpg)。關鍵畫面是投影片的證據，它顯示了文字項目符號只能描述的圖表/圖示/UI，並使簡報能反映原始來源。僅在該投影片是你用 Mermaid 重新繪製的純圖表投影片，或該畫面不包含任何視覺資訊（例如單純的講者頭像、過場畫面）時，才省略它。當一個來源投影片被拆分為兩個簡報投影片時，請使用該來源投影片片段的兩個不同畫面，而不是重複同一個。
• 僅包含證據支援的內容。 若轉錄稿和 OCR 都為空，請說明該影片沒有可提取的內容，而不是憑空創作簡報。

密度——簡報必須整合證據，而不是將其濃縮掉。 最常見的失敗是簡報內容過於薄弱：20 張投影片，每張只有短短幾個字的項目符號，浪費了影片實際包含的大部分內容。證據包的建立成本很高，而簡報才是人們閱讀的內容。

• 每個來源投影片對應一張簡報投影片。 OCR 區段中每個 ### [時間區間] frames/… 區塊都是影片中的一個真實投影片——這個列表就是你的檢查清單，也大致是你的投影片數量。不要將三個來源投影片合併成一個項目符號。一場 40 分鐘的演講通常會有 30-45 張投影片。
• 將具體細節帶入投影片。 證據中出現的每個數字、指標、閾值、百分比、產品名稱、CRD、設定鍵和標籤都應該出現在投影片上。如果來源投影片有六個項目符號和四個統計數據，你的投影片就應該有六個項目符號和四個統計數據，而不是「提升了準確度」。
• 項目符號是一行完整的句子（約 15-20 個字），而不是四個字。 每張投影片 5-8 個項目符號是正常的。只有在來源本身就簡潔時，才能使用簡潔的寫法。
• 當來源是表格形式時，請使用表格來呈現——例如路由矩陣、基準測試表格、等級定義、優先級規則。請重現每一行和每一列，而不是只取樣本。
• 講者備註是補充性的，用於記錄投影片上沒有的、但在演講中被提及的內容：例如注意事項、經驗故事、「為什麼」的說明、問答細節。不要將應該放在投影片上的內容隱藏在備註中。
• 完成前進行覆蓋率檢查。 依序瀏覽 ocr.txt 中的 ### [..] 區塊，確認每個區塊都有對應的簡報投影片。如果你跳過了某個區塊，要能說出原因——它是重複/動畫效果、演示畫面，或是其他情況。

5. 圖表處理（「這個可以做成圖表嗎？」檢查）

對於每個主題，請問：這是結構性的嗎（元件+連接、參與者互動、流程、狀態+轉換、實體+關係）？如果是，請在單獨的投影片上將其繪製為 Mermaid（預設）或 PlantUML 圖表，而不是使用項目符號。請參閱 "$SKILL/references/diagrams-cheatsheet.md" 以了解內容→類型對照表以及可直接複製貼上的骨架。不要強行將純敘述性內容繪製成圖表。

6. （選用）匯出真正的投影片簡報

bash "$SKILL/scripts/render.sh" "<輸出目錄>/<影片主檔名>/deck.md" pptx   # 或 pdf | html | all

此腳本會先將圖表區塊預先渲染成圖片，然後產生 PPTX/PDF。若未安裝 marp/mermaid，簡報會保持為 .md 格式（仍然有效且可檢視）。

若要一次處理整個樹狀結構，請在批次驅動腳本（如下）中加入 --pdf 參數，而不是為每個簡報分別呼叫 render.sh。

批次 / 巢狀資料夾

對於整個資料夾——尤其是巢狀課程樹——建議使用 scripts/drive_decks.sh <根目錄>：它會在 bash 中循環，並為每支影片啟動一個全新的代理程式（永不溢出模型的上下文），並將來源子資料夾鏡像至輸出目錄，保留父→子層級結構。接著執行 scripts/rename_by_topic.sh <簡報目錄>，根據每個葉節點在其課程資料夾內的主題來產生 slug。如果要在撰寫完成後將所有簡報匯出為 PDF，請加上 --pdf 參數——Mermaid 會預先渲染為圖片，並且葉節點資料夾會被摺疊，使得每個 PDF 檔案位於其父資料夾中（<輸出>/課程A/章節/deck.md → <輸出>/課程A/章節.pdf），避免為每個 PDF 建立一個子資料夾。若要重建由舊版批次執行時產生扁平結構的簡報層級，請使用 scripts/regroup_by_source.sh <簡報目錄>——它會讀取每個 evidence.md 中的 Source: 行，將每個簡報放置在其課程父節點下（重複項目隔離至 _duplicates/），然後執行重新命名。請參閱 README.md 以取得完整的批次使用指南。

參考資料

• references/marp-cheatsheet.md — Marp 投影片語法（分隔線、圖片、備註、欄位）。
• references/diagrams-cheatsheet.md — 何時繪製圖表以及每種圖表類型的語法。

備註

• OCR 能很好地捕捉螢幕錄製/投影片影片的螢幕文字。對於實景拍攝的影片，轉錄稿承載了大部分資訊——請依賴它，不要過度解讀視覺內容。
• 轉錄、OCR 和渲染永遠在本機進行。撰寫步驟是否離開機器，完全取決於你透過 --agent-cmd 指向的代理程式。
• 此設計與模型無關：任何能夠執行 bash 和讀取檔案的純文字代理程式都可以使用此技能。