ipas-ai-quiz: Instructions file for Codex

AGENTS.md — 給 AI 代理 / 貢獻者的修改指南

這份是讓「你(或你的 AI agent)clone 本 repo 後,能安全地擴充、改題、改功能」的說明。 本站是純靜態前端(無框架、無 build),題庫是 JSON,後端只有一個選用的 Cloudflare Worker。

檔案地圖

檔案	作用	改它要注意
index.html	版面 + 全部 CSS(inline <style>)+ PWA head	改到快取檔請 bump sw.js 版號
app.js	全部前端邏輯(ES module,vanilla JS)	DOM 操作集中在這
core.js	純邏輯(Leitner、計分、統計、出題優先序),有單元測試	改完跑 node core.test.mjs
core.test.mjs	core.js 的測試	改邏輯要同步更新斷言
questions.json	題庫(主要要改的就是這個)	見下方 schema
concepts.json	每日 AI 觀念卡池	{ "cards": [...] }
sw.js	Service Worker(離線快取 + 推播顯示)	改任何快取檔就把 CACHE 版號 +1
manifest.json	PWA 安裝資訊
assets/*.png	帶圖題的圖
tools/sources.json tools/extract.sh	官方試題來源清單 + 抽文字腳本	加新梯次用
worker/	Cloudflare Worker:同步 + 推播 + cron	要自架後端才需動

題庫 schema(questions.json)

{
  "meta": {
    "title": "...",
    "note": "...",
    "defaultTimeLimitMin": 90,
    "guides": { "科目1:人工智慧基礎概論": "<學習指引PDF網址>", ... }
  },
  "questions": [
    {
      "id": "115-1-b-s1-q3",        // 唯一;慣例 <梯次>-<b初級/m中級>-s<科>-q<N>;帶圖題用 -f<N>
      "level": "初級",              // 初級 / 中級
      "round": "115年第一次",
      "subject": "科目1:人工智慧基礎概論",
      "chapter": "機器學習",         // 練習「範圍」依此分組;沒填會退回用 subject
      "topic": "監督式學習",         // 細標籤(自由),關鍵字搜尋會吃到
      "question": "題幹…",
      "options": ["A選項", "B選項", "C選項", "D選項"],  // 必須剛好 4 個
      "answer": 2,                  // 正解的 0-based 索引:A=0 B=1 C=2 D=3
      "explanation": "詳解…",        // 為何對 + 為何其他錯 + 概念
      "image": "assets/<id>.webp",  // 選填:帶圖題才有,檔名一律 = 題目 id(WebP lossless)
      "source": "學習指引"           // 選填:來源。缺省=歷屆考古題;"學習指引"=官方學習指引範例題(id 以 lg- 開頭、答案與解析皆官方)
    }
  ]
}

加題目最小步驟:把新物件 append 進 questions.questions,確認 options 4 個、answer 是 0-3、id 不重複,然後:

node -e "JSON.parse(require('fs').readFileSync('questions.json'))"   # 驗 JSON 合法
node core.test.mjs                                                   # 驗邏輯沒壞
python3 -m http.server 8000                                          # 開 http://localhost:8000 看

• chapter 請沿用既有的(統計頁/範圍選單會自動多出該組);不填則以 subject 當範圍。
• 帶圖題:圖放 assets/,檔名一律命名為 <題目 id>.webp(WebP lossless,例如 assets/114-2-m-s3-f1.webp),image 欄填 assets/<id>.webp。看 id 就知道圖、看圖就知道哪題,別沿用原始 PDF 的圖片序號(早期 114-2 沒這樣做,踩過坑)。不要把含「答案欄」的整頁截圖放進去(會洩答案)——只放圖本身。
• 題幹若寫「附圖/如圖/下圖」就一定要有 image(歷史教訓:q39 抽圖時漏掛,題目變成無法判讀)。加完用 node tools/check-questions.mjs 驗。