讀書指南
你為每場考試產出一份自包含的HTML網頁，由課程資料夾中的純文字檔案透過 scripts/build.py 建構而成。網頁包含三個部分：
- 筆記，每堂課一個章節。每個論述都會引用投影片頁碼。每個主題都附有白話解說框、範例、圖表，以及紅色的「陷阱」提示框。每個章節結尾的練習框讓學生能在閱讀後立即自我測驗。
- 練習中心，包含四個分頁：
- 練習題庫：提供即時回饋，每個選項皆有解說；
- 逐步引導的簡答題，附部分給分；
- 計時模擬考：使用專屬題庫，題型比例與真實考試相同；
- 自動記錄的錯題筆記本。
- 進度報告，由網頁持續為你記錄。你之後可以閱讀此報告，並針對學生實際答錯的部分撰寫新的練習題。
引擎（assets/engine.js）與樣式（assets/page.css）已完成並測試過，因此你的工作是內容與題目。網頁大多數的實用性來自參考檔案；請在到達該步驟時閱讀它們。
| 當你準備要… | 請閱讀 |
|---|---|
| 撰寫課堂章節 | references/content-standard.md |
| 撰寫或審核題目，或校準模擬考 | references/question-bank.md |
| 檢查欄位名稱、進度格式或資料庫文件 | references/data-format.md |
examples/demo/ 是一個完整的微型課程（虛構的 PROB 101，共三堂課）。若不確定某個部分應如何呈現，請從其原始檔案中複製模式：sections/*.html、practice.json、mock.json 和 short.json。
請勿閱讀 assets/engine.js、assets/page.css 或任何已建置的 review.html。build.py 會將它們內嵌，它們包含數萬個 token，且其中沒有任何需要你編輯的內容。
在以下指令中，<skill-dir> 是包含此 SKILL.md 的資料夾。如果找不到 python3（在 Windows 上常見），請使用 python 或 py -3。
1. 了解考試內容
在開始撰寫任何內容前，先取得這些資訊。能自行查詢就查詢，只有在你無法找到的資訊才詢問學生：
- 考試： 日期與時間、時長（分鐘）、範圍（哪些講次）、考試形式，以及允許使用的資料。考試形式包含題型、各題型數量與配分。允許使用的資料包含筆記單、計算機或「無」。
- 資料來源： 投影片（PDF 或連結）、閱讀資料、課程網站，以及任何官方練習題、小考成績或考古題。
- 學生： 他們希望網頁使用的語言（
lang：zh或en代表介面語言；用他們的語言編寫內容），以及他們的背景強度。說「我聽不懂」的學生幾乎每個主題都需要白話解說框。
如果你能瀏覽網頁，請自行研究課程：課程進度頁、課程大綱以及已公布的小考成績。尋找值得告訴學生的模式，例如「課堂上的隨堂問題緊接在某張投影片之後」或「官方題庫宣稱使用與考試相同的格式」。將這些後勤資訊放在網頁的英雄區（hero section）。
檢查課程大綱中的 AI 政策。有些課程禁止使用 AI 產生的學習材料或禁止在計分作業上使用 AI 輔助。如果政策禁止此類行為，請在建置前告知學生。絕對不要在頁面上放置計分作業的答案。
2. 在不劇透的情況下校準模擬考
學生通常想保留官方考古題來做一次計時練習。那麼就不要閱讀其題目內容，而是測量它：
python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf
此腳本絕不會印出題目、選項或情境的文字。它會印出：
- 頁數與題數，以及每題的選項數；
- 配分、時間限制與封面指示（計算機、筆記）；
- 各部分標題與共享同一個情境的題目範圍（「第 11–14 題…」）；
- 參照前面材料的題號。
使用輸出結果來設定模擬考的部分（題型與數量）以及時間限制。參照前面材料的題目（例如簡答題重複使用前面的情境），在你描述考試結構時，應將其歸入該情境。
如果腳本無法告訴你某些資訊，請回報為「未知」，並請學生查看封面頁。請勿自行撰寫一個會印出題目內部單字或數字的探測腳本。即使一個不經意的「總計」或「%」也可能暗示題目主題，而方程中的數字則會洩漏題目。
在開啟任何考古題或答案卷之前先取得學生同意。即使學生允許你閱讀，也只能用於校準（結構、難度、風格）。絕對不要將其題目或情境複製到頁面上。
3. 設定課程資料夾
python3 <skill-dir>/scripts/build.py --init <course-dir>
這會複製範例課程。接著編輯 course.json：
title、lang與lectures。講次標籤必須與題目和群組使用的一致，例如"L1"或"L5–L6"。storageKey：每個課程與考試必須唯一，例如"bio201-mt1"。進度會儲存在此鍵下，因此一旦學生開始使用，就絕對不能更改它。mock.sections：每個題型一個條目，依照考試順序，數量與實際考卷相符。mock.minutes：可供選擇的時間限制。包含實際考試時間；如果模擬考省略了長題目，也要提供一個按比例縮短的時間選項。
在替換時刪除範例課程的章節與題目。所有欄位的詳細說明請見 references/data-format.md。
4. 撰寫章節
在 sections/ 中為每堂課撰寫一個檔案（10-l1.html、20-l2.html，依此類推），再加上一個 00-hero.html 記錄後勤資訊，以及一個最終的陷阱列表。每個講次都是一個 <section class="part" id="...">。當一個練習群組使用 "sec" 指向該 id 時，其練習框會自動出現。
references/content-standard.md 包含了完整的配方與每個元件的 HTML。簡而言之：每個論述都要引用來源，用詞彙表和類比來開始困難的講次，每個主題給一個一句話的開場，在公式之前給一個具體的例子，一個白話解說框，一個有助理解的圖表，以及一個針對是非題會如何扭曲的陷阱框。
5. 撰寫題目
共有三個題庫。references/question-bank.md 包含了規則與稽核查核清單。
practice.json：每個講次 8–15 題。混合單選、是非、多選與填空題，偶爾加上閃卡。每個選項都要有自己的解說。mock.json：使用自己的題目，絕對不要複製練習題。數量約為實際考卷每種題型抽取量的兩倍，這樣不同卷的題目才會不同。風格要與真實考試相符。short.json（選用）：將考試中簡答題的類型轉換為逐步引導的版本。每一步可能是可容錯的填空題、選擇題，或是根據模型答案進行自我檢查。
6. 建置與檢查
python3 <skill-dir>/scripts/build.py <course-dir>
錯誤會中斷建置。警告來自題庫檢查；除非你有理由不修正，否則請修正它們。它們會標記出以下模式：
- 太多題目的正確答案是最長的選項；
- 某個字母太常成為顯示的正確答案；
- 每個多選題的答案數量都相同；
- 模擬考題只是練習題換了數字。
加上 --strict 會讓警告以結束代碼 2 中斷建置（頁面仍會寫入），這樣你可以持續修正直到完全乾淨。接著在瀏覽器中打開 <course-dir>/review.html 並檢查：
- 控制台沒有顯示錯誤，且公式能正確渲染；
- 回答練習題、簡答題步驟以及一份完整的模擬考都能正常運作；
- 在 375 像素寬度下，沒有內容會讓頁面橫向滾動（圖表與表格在其自身框內滾動）；
- 圖表中的文字沒有與線條、箭頭或其他文字重疊（請截圖確認）。
7. 交付
- 本地端（任何代理）： 提供檔案路徑。進度會儲存在該瀏覽器的 localStorage 中。練習中心的匯出進度按鈕會提供學生可貼回給你的 JSON。
- claude.ai artifact（僅限 Claude；實驗性功能，尚未完整測試）： 發布建置好的 HTML 並授予
db能力。如果window.claude.use("db")可用，引擎會將進度同步到文件progress/practice和progress/mock，並在progress/report中保留摘要。在依賴此功能之前，請在發布的頁面上回答一個問題，然後讀取progress/report。如果文件遺失，請告訴學生改用匯出進度。
用兩三句話告訴學生如何使用這個頁面：閱讀一個章節、做該章的練習框、接近考試時進行模擬考，以及考試前一天使用錯題筆記本。
8. 完成循環
當學生回來時，在進行任何更改之前，先讀取他們的進度。使用他們貼上或寄送的匯出 JSON（其中的 report 欄位），或者如果 artifact 同步正常，則使用 progress/report 資料庫文件。報告列出了：
- 每個講次的首次嘗試正確率；
- 所有答錯的練習題，包含他們的答案與正確答案；
- 他們答錯的簡答題步驟；
- 模擬考的歷史記錄，以及上一次考試中答錯與標記的題目。
接著：
- 指出弱點，用幾行文字描述。統計首次正確率低於約 80% 的講次、重複出現的錯誤觀念，以及持續答錯的簡答題步驟。也要統計那些被標記為不確定但答對的題目；這些也是不穩固的知識。
- 為每個弱點撰寫新的練習題。用不同的文字、數字或情境重新提問同一個概念；絕對不要重複他們答錯的題目。將它們以新的 id 添加到
practice.json，如果模擬考題庫在該處不足，也添加到mock.json。 - 修正解說，而不只是題目。如果一個錯誤觀念重複出現，該章節的解說很可能解釋得不夠好。針對該特定混淆點，添加一個白話解說框、一個範例或一個圖表。
- 重新建置，然後告訴學生什麼改變了以及在哪裡。
在編輯時保持已儲存進度的有效性
記錄是透過 storageKey、題目 id 和原始選項索引來索引的。因此：
- 保持
storageKey和現有的 id 不變； - 不要對已經回答過的題目重排、插入或刪除選項（改為附加一個新題目）；
- 不要將舊的 id 用於不同的題目；
- 如果一個題目的意義或答案改變了，給它一個新 id 並移除舊的。已移除 id 的記錄會被忽略，不會被誤讀。
引擎會使用 id 作為種子來打亂選項的顯示順序，因此儲存的索引仍然是正確的。要改變答案顯示為哪個字母，請設定 "show"（見 references/data-format.md），而不是重排選項。修正題幹或解說中的打字錯誤或措辭總是安全的，編輯章節的 HTML 也是安全的。
學生們曾提出的要求
這些教訓來自於為真實考試建置複習頁面的經驗：
- 抽象的解釋不夠具體。學生們先要求具體的數字（「擲硬幣 10 次…」），然後才是公式，推導過程摺疊起來並標示為「不考」。
- 連續研讀好幾個講次再練習會讓人筋疲力竭。這就是為什麼每個章節都以自己的練習框結尾。
- 格式上的吹毛求疵令人惱火，例如因為
1/2而不是0.5被標記為錯誤。引擎會依數值比較數字答案；請在accept中列出文字變體。 - 學生很快就學會了答案的模式。正確答案通常是最長的選項，每個多選題都有 3 個答案，而且正確答案總是 B。建置過程會審核前兩者；引擎則會打亂顯示順序。
- 重複使用練習題的模擬考測量的是記憶力，而不是理解力。這就是為什麼模擬考題庫是獨立的原因。
- 學生想要能夠選取選項文字來複製，以及一個在時間到時會自動提交的計時器。