Walid-Ahmed/flashcard-deck

Flashcard 牌組

將一個主題轉變為問答卡片牌組，卡片會先教授一般概念，列印清晰，並可轉變為 YouTube 影片。卡片以一個 Python 檔案 (deck.py) 搭配小型輔助工具撰寫，並透過捆綁的腳本從該檔案渲染所有產出，因此修改一張卡片只需一次編輯與一次重建。

工作分為四個階段。在每個會耗費使用者時間或發佈任何內容的階段前，務必先詢問，因為牌組只有在涵蓋使用者所需時才有用，且影片需要數分鐘的編碼時間。

1. 訪談：詢問要建立什麼。
2. 規劃：提出主題與卡片問題；取得同意。
3. 卡片：撰寫 deck.py，渲染，檢視每張卡片，修正不吻合之處。
4. 附加功能（僅在需要時）：影片、縮圖、發佈。

1. 訪談

從詢問開始，不要直接開始建立。使用 AskUserQuestion 工具，讓使用者可以點選答案。在單次呼叫中詢問所有問題（最多可問 4 個），並跳過使用者訊息或開啟專案中已回答的任何問題。優先提供一個推薦選項，並標記「(推薦)」。

詢問以下事項。該工具最多接受 4 個問題，因此當素材來源為使用者提供的資料，且需要第五個問題時，請在第二次呼叫中詢問最後一個問題。

• 來源：卡片涵蓋的範圍。選項例如：使用者已有的材料（檔案或資料夾：PDF、投影片、Word 或 Markdown 筆記、課程、程式庫或現有閃卡）、此儲存庫、基於自身知識的主題，或使用者將貼上的筆記。如果請求已指明來源，則跳過此項。
• 遵循程度（僅當來源為使用者的資料時）：僅遵循資料所述（推薦）、資料加上標記為新增的遺漏基礎知識，或將資料作為起點。
• 受眾與深度：初學者（每張卡片一個概念，用語平實）、中級（概念加上簡短程式碼範例）或進階（權衡取捨、邊緣情況）。
• 最大卡片數量：最多 10 張（快速集合）、最多 20 張（推薦）、最多 40 張（完整課程）或無限制（視資料需要）。使用者可輸入任何其他數字。將其記錄為 deck(..., max_cards=N)：如果牌組超過此數量，建置作業會停止，因此後續分割卡片不會悄悄地超出限制。更多卡片意味著更多主題，而非更長的卡片。
• 輸出：僅卡片圖檔與 PDF（推薦）、加上影片、再加上影片與縮圖。無論如何，影片都需在卡片獲得批准後才會製作。

然後，如果仍未知，以純文字詢問（無需工具）：每張卡片上顯示的牌組標題（例如「FastAPI」或「Kubernetes」）、輸出儲存位置（建議使用目前專案中的 flashcards/ 資料夾，或一個新資料夾），以及程式碼範例是否可以提及原始專案名稱，或應保持通用。對於使用者自己的資料，也詢問每張卡片是否應顯示其來源（例如「第 3 章，第 42 頁」）。

2. 規劃

首先閱讀來源。如果來源是使用者已有的資料，現在閱讀 references/existing-material.md：其中涵蓋如何讀取 PDF、投影片、Word 檔案、資料夾與現有閃卡，對應所有資料以防遺漏、忠於原始資料，並將每張卡片指向原始頁面。對於基於自身知識的主題，則決定學習者在所選深度下需要什麼。接著將牌組以簡短清單形式提出：按學習順序列出主題，並在每個主題下列出每張卡片的問題（一行一個問題）。按概念分組（HTTP 基礎、驗證、授權），而非按檔案分組。每個主題目標為 3 到 9 張卡片。小型牌組（低於約 12 張卡片）可以分為 2 或 3 個主題，每個主題 2 到 4 張卡片。

將規劃控制在最大卡片數量內，並預留一兩次分割的空間。如果資料所需的卡片數量超過最大允許值，則先涵蓋核心概念，然後列出被遺漏的主題或章節，並提議提高限制。

顯示規劃並在撰寫卡片前徵求同意、修改或刪減。撰寫 40 張關於錯誤主題的卡片最耗費時間，因此此檢查值得一次來回溝通。

3. 卡片

先撰寫 deck.py，從第一個主題開始

將 references/deck_template.py 複製到輸出目標旁的資料夾。撰寫第一個主題的卡片，僅渲染該主題（--topic 1），向使用者展示其中兩三張，並詢問樣式與深度是否合適。然後再撰寫其餘卡片。在第三張卡片時發現使用者想要更短的卡片代價較低；在第四十張卡片時發現則不然。在撰寫第一張卡片前，請先閱讀 references/components.md：它展示了所有建構區塊（導語、方塊、步驟、表格、程式碼範例、提示框、圖表）及其對應的 HTML。

如何寫好一張卡片，以及原因：

• 概念優先。 問題與開頭句子（lead）應陳述通用概念，使其適用於任何情境。專案特定的程式碼應放在標題為「範例：...」的 example(...) 方塊中，讓學習者先了解規則，再看到一個案例。當範例專案與常見做法不同時，請在範例的註解中說明。
• 每張卡片一個概念。 一個問題若結合了兩個獨立的概念（例如「什麼是 X，以及如何部署它？」）應拆分為兩張卡片。對比（例如「X 與 Y 有何不同？」）或只有放在一起才有意義的一組概念，則視為一個概念。
• 導語，接著結構，然後範例。 先以一兩句話回答問題，接著是兩三個方塊、步驟或一個小型表格來分解內容，然後是選擇性的提示框與程式碼範例。讀者應能僅從導語獲得答案。
• 頁尾是應該記住的句子，少於 15 個詞彙。標籤是用於命名該概念的一兩個詞彙。
• 用語精確、平實。 使用簡短句子。直接寫出真實的狀態碼、函式名稱與指令，不要暗示。
• 圖表僅在能增加價值時使用：例如流程圖、包含失敗路徑的決策圖，或 URL/訊息的組成部分。不要在已有表格顯示結構的卡片上使用圖表。
• 交叉引用應說明參照位置：「應用程式結構中的第 4 張卡片顯示了伺服器端。」

渲染與檢查

python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR             # 所有卡片、PDF、README
python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR --topic 1   # 一個主題，快速檢查

<skill-dir> 是此 SKILL.md 所在的資料夾。使用 python3，或在使用 Python 3 的環境中使用 python。該腳本需要安裝了 playwright 和 Pillow 的 Python（pip install playwright pillow），以及 Google Chrome 或透過 playwright install chromium 安裝的 Chromium。它會將每張卡片渲染為 2400 x 1698 像素的 A4 橫向 PNG，檢查每張卡片的內容是否在範圍內（高度與寬度），並對不符合的卡片停止處理並命名。然後它會為每個主題寫入一個 PDF、print/all-cards.pdf 和 README.md。

• 重複內容：範圍檢查測量的是尺寸而非意義。找出重複步驟或導語的方塊，並將其刪除。
• 超過最大限制：如果牌組的卡片數量超過 max_cards，建置作業會停止。合併或刪除最不重要的卡片，或要求使用者提高限制。請勿自行提高。
• 卡片不符合範圍：縮短文字、刪除一個方塊，或將其分割為兩張卡片（例如「9a」和「9b」，或兩個問題）。切勿為了塞入內容而縮小字型；卡片必須在列印時保持可讀。
• 檢查每張卡片：渲染後，透過開啟 PNG 檔案來檢查。範圍檢查能捕捉到溢位問題，但無法捕捉到令人困惑的卡片、誤導性的圖表或錯字。修正後重新渲染；--topic N 可快速重新渲染一個主題。
• 留有空白是正常的。 建置作業會報告 1200 x 849 卡片（PNG 為其兩倍大小）上以 CSS px 為單位的剩餘空間。簡單的卡片經常留下 150 到 350 像素的空白，這對閱讀和列印來說是好的。不要為了填滿卡片而填充內容。如果一張卡片留下超過約 400 像素的空白且感覺內容單薄，它可能需要一個圖表或範例，或者可能應合併到相鄰的卡片中。

4. 附加功能：影片、縮圖、發佈

僅在使用者需要且批准卡片後才進行。詢問想要的影片風格，並大致說明編碼所需的時間（每張卡片在筆電上約需 15 秒編碼）。

python3 <skill-dir>/scripts/build_videos.py deck.py --cards OUT_DIR --out VIDEO_DIR [--mode both|questions|cards]
python3 <skill-dir>/scripts/build_thumbnails.py deck.py --cards OUT_DIR --out VIDEO_DIR/thumbnails [--mode both|questions|cards]

• --mode both（預設）：每個問題先顯示隱藏答案與時間條（6 秒），接著顯示完整卡片（12 秒）。
• --mode questions：測驗模式，每個問題顯示 10 秒，不顯示答案。
• --mode cards：複習模式，每張完整卡片顯示 15 秒。
• 每種模式都會為每個主題製作一部影片，以及一部包含所有卡片的影片，並以模式名稱命名（-questions、-cards），避免樣式互相覆蓋。將相同的 --mode 傳遞給 build_thumbnails.py，以確保名稱匹配。
• 每部影片都有開場與主題標題畫面，以及一個 .txt 描述檔，其章節 YouTube 會轉換為可點擊的章節。章節至少 10 秒，這是 YouTube 的要求。
• 影片需要 ffmpeg。將 VIDEO_DIR 放置在 git 儲存庫之外，因為影片檔案很大。
• 縮圖為 1280 x 720 的 JPEG 檔案，命名與每部影片匹配。topic(..., hook="A · B · C") 設定每個主題標題下方的小字。
• 建置完成後，提供可直接貼上的 YouTube 標題與描述：標題少於 70 個字元，包含主題與鉤子；描述包含開場白、每個主題一個項目符號、任何連結，以及來自 .txt 檔案的章節。

在推送、發佈或上傳任何內容之前務必詢問，因為這些操作會觸及他人。如果牌組的程式碼範例來自其他人的課程或儲存庫，請在公開前提及此事，並提供致謝行（deck(..., credit="...") 會在 README 中加入一行致謝）。

後續修改牌組

編輯 deck.py 並再次執行 build_deck.py；它會重建每張卡片、PDF 與 README，並刪除已刪除卡片的圖片。僅在使用者希望更新影片時才重建影片，而 --descriptions-only 只會重寫影片描述。

此技能中的檔案

• scripts/build_deck.py：卡片、範圍檢查、PDF、README。
• scripts/build_videos.py、scripts/build_thumbnails.py：附加功能。
• scripts/flashcards/：deck.py 匯入的輔助工具（__init__.py）、渲染引擎（engine.py）以及卡片樣式表（card.css：列印友善、白色背景搭配彩色邊框、固定 A4 橫向）。
• references/components.md：每個卡片建構區塊及其範例。撰寫卡片前請先閱讀。
• references/deck_template.py：一個可用的小型牌組範本，可供複製。
• references/existing-material.md：從使用者自己的筆記、PDF、投影片、儲存庫或閃卡建立牌組。當來源為此類資料時請閱讀。