shakedal1/lecture-deck-remake

Lecture deck remake

將枯燥的課程簡報轉變為學生真正能學習的教材。輸出是使用 Slides artifact 類型製作的簡報（每種語言一份）。有關投影片格式、檔案和發布的所有事項均遵循該類型的說明。此技巧在此基礎上增加了教學設計、動畫和命令規則，以及希伯來文 RTL 技術。

在撰寫第一張投影片之前，請閱讀 references/patterns.md。其中包含下方提到的每種模式的即用標記。

1. 先閱讀整個原始檔案

• PDF：每次以最多 20 頁為一組進行 Read，直到讀完所有頁面。PPTX：使用 pptx 技巧提取文字和圖片。
• 閱讀時，列出：按順序的主題、每個命令或程式碼片段、每個定義、原始簡報中已有的每個測驗或問題，以及任何重複使用相同螢幕截圖但更改一個標註的投影片。這些重複的投影片是首先要合併的。
• 也要列出每張值得保留的圖片：照片、真實物體或模型、工具螢幕截圖，以及顯示手繪無法表達的內容的圖片。在 Read 預覽中標記每個圖片的頁碼和大約位置，因為你稍後需要裁剪它（§6）。
• 保留來源中的所有事實：名稱、日期、電子郵件、評分、連結、命令標誌。切勿編造無法從來源或範例本身的邏輯推導出的數字、引用或工具行為。

2. 規劃教學，然後建構

用一句話向使用者說明計畫並開始，無需等待批准。

• 一個進行中的範例。 選取來源本身的範例，並賦予它一個具體的物理圖像（一個 3 位元 one-hot FSM 變成了「一個 3 燈追光器」）。在每張投影片上重複使用它：屬性變成關於它的簡單問題，結果用它的術語來解釋。
• 每個概念一個類比，來自日常生活，用斜體寫在投影片上，緊鄰正式定義（模擬 vs 形式 = 嘗試 1000 把鑰匙 vs 鎖匠證明機制；重置 =「新遊戲」；時鐘 = 節拍器；邊界 = 街道上最近的咖啡店；除錯「為什麼」= 回到過去的偵探）。
• 每 4-6 張投影片設置測驗：執行前預測、手動追蹤、「如果我們改變 X 會怎樣」、對/錯。答案是一個固定框，點擊時會逐步顯示；同時將答案放在講者備註中。
• 保留來源的圖片，並繪製其餘部分。 使用者希望原始檔案的相關圖片出現在簡報中。不要為了繪圖而捨棄它們。對於清單中的每張圖片：
  • 如果它顯示的內容與你的繪圖相同（例如解析度條、工具的實際視窗、前後對比），請使用圖片而非繪圖。
  • 如果它增加了繪圖無法表現的內容（例如真實照片、真實 3D 模型、真實資料集），請將其放在與進行中範例繪圖同一張投影片上，並加上一行說明文字，將兩者聯繫起來。
  • 如果它純粹是裝飾性或重複另一張圖片，則省略它，並在報告中說明。 將原始檔案僅用文字描述的內容繪製為 SVG/div（patterns.md）：狀態圖、波形、時間軸、數線、進行中範例的逐步建構。
• 每張投影片一個想法，約 20-26 張投影片。使用節奏：封面、每個章節開頭和回顧使用深色陳述投影片；內容使用淺色背景；測驗使用暖色調背景。
• 以速查表結尾：按順序列出每個命令，附帶 2-3 個字的說明，以及關鍵術語的詞彙表。

3. 動畫是必要的，而非可選的

使用者要求更多動畫。每個簡報必須：

• 在每個章節上放置 data-transition：大部分使用 fade，進入新章節時使用 push，在顯示同一圖表兩個狀態的兩張投影片之間使用 magic。
• 每張內容投影片至少有一個建構序列：主要元素是 position:absolute 的子元素，帶有 data-build-in="<效果> <順序>"，以便它們在簡報模式下逐一出現。建構僅作用於固定位置的子元素，因此逐步揭示的投影片需要使用明確的 left/top/width 進行佈局。
• 使用有教學意義的建構。逐步揭示流程（rise 1, rise 2, …），逐箭頭繪製狀態機（每個箭頭組一個固定的 SVG），逐週期展示波形，在定義之後揭示類比，並最後顯示測驗答案。
• 使用 magic move 來動畫顯示變化：在連續兩張投影片的匹配固定元素上使用相同的 id（燈點亮、高亮移動到下一個週期、邊界區間縮小）。
• 有目的地變化效果：列表和步驟使用 rise，結果或勾選使用 pop，從某個方向到來的元素使用 left/right，註釋使用 fade，重大揭示使用 scale。每張投影片的建構不要超過約 6 個。

4. 命令必須從投影片中脫穎而出

使用者要求更顯眼的命令。每個命令、標誌或 Tcl/shell 行都使用 patterns.md 中的命令晶片格式，投影片上其他內容不能與之相似：

• 獨立區塊（<p>），絕不內嵌在句子中。Span 只能攜帶顏色，因此 span 上的 font-family 會被靜默捨棄。
• 等寬字體（JetBrains Mono），32-40px，粗體。深色晶片背景，一個僅保留給命令使用的亮色強調色，前緣有粗的強調條，以及提示符號（Tcl 使用 %，shell 使用 $）。
• 在每個晶片旁邊，加上一個簡短標籤說明其功能（「編譯」、「證明所有」）。
• 在步驟投影片上，命令晶片是標題之後最大的元素，並且首先建構進入。
• 程式碼清單（整個檔案）使用單獨的、較安靜的程式碼卡片樣式，以便命令仍然從中脫穎而出。

5. 語言

如果使用者要求兩種語言，則使用該類型製作兩個獨立的簡報，具有相同的投影片 ID 和內容。先建構原始語言（或英文），再建構另一種語言。希伯來文需要使用 patterns.md 中的 RTL 技術：用 ⁧…⁩ 隔離每個希伯來文文字區塊，將希伯來文內部的內聯程式碼包裹在 ⁦…⁩ 中，使用 text-align:right 和 row-reverse 行，反轉表格列順序，在序列中使用 ←，並分別隔離每個 <br> 分隔的行。程式碼、命令晶片、波形和 GUI 線框保持由左至右。Rubik 字體涵蓋希伯來文和拉丁文。

6. 建構和發布

遵循 Slides 類型自身關於檔案和呼叫的說明，並加上這些經使用驗證的規則：

• 編寫 project/deck.json（完整的 order、sections、faces）和封面，發布，然後每輪編寫和發布約 4 張投影片。
• 使用 edits 的發布不能同時攜帶 files。使用編輯工具進行編輯，然後發布檔案。
• 如果發布因網路錯誤而失敗，請重新發送相同的檔案。這樣做是安全的。
• 從 PDF 裁剪來源圖片（在編寫使用這些圖片的投影片之前執行此操作）：
  • 將 PDF 複製到便條紙中的一個新資料夾中，並將裁剪結果寫入單獨的 assets 資料夾。
  • 使用 python -I -c "import pypdf,sys;print(pypdf.PdfReader(sys.argv[1]).pages[0].mediabox)" <pdf> 獲取頁面尺寸。此處未安裝 PyMuPDF 和 Pillow；pdftoppm（MiKTeX）已安裝。忽略其「需要 Windows 10」的警告。
  • 直接從頁面裁剪：pdftoppm -f N -l N -r 250 -x X -y Y -W W -H H -png -singlefile <pdf> <assets>/<name>。座標來自 Read 預覽：比例 = (250 / 72) × 頁面寬度（pt）/ 預覽寬度（px）。一個 720 pt 的頁面預覽為 1000 px 寬，給出 ×2.5 的比例。
  • 每次 Read 一個裁剪結果並修正其邊緣，然後上傳：常見問題是包含相鄰圖片的一小部分。
  • 將一個面板條（例如，一個包含 7 種解析度的圖片）分割為每個面板一個裁剪結果，以便面板可以逐一建構進入。
  • 在一次呼叫中上傳所有裁剪結果：使用 url、asset: true 和 file_paths（最多 25 個）進行 Artifact 發布。在 <img src> 中直接使用每個返回的 /_blob/<id>，搭配 object-fit:contain 以及與裁剪結果長寬比相符的寬度和高度。
  • 對於 PPTX，取得 pptx 技巧提取的圖片，然後以相同方式上傳。
• 預算高度：邊距內 824px。標題區塊約 130px，表格行約每行 2.1 × 字型大小，固定框必須在 y 952 以上結束。在縮小文字之前先縮短文字，並保持文字 24px 或更大。
• 除非使用者要求，否則不要渲染或截圖驗證。

7. 報告

提供每個簡報的連結、與原始簡報相比的更改（進行中範例、類比、插圖、保留了哪些來源圖片及其位置、省略了哪些、測驗、動畫、命令樣式、合併了哪些重複投影片），以及你未檢查的內容。提醒使用者簡報在分享前是私密的。