# 課程檔格式

每門課一個檔案 `database/seeders/courses/<slug>.php`,`return` 一個陣列。

```php
return [
  'slug' => 'linux-beginner',          // 英文小寫+連字號,唯一
  'category' => 'tech',               // tech|ai|business|exam  // Linux、容器、資安、程式開發課程都歸 tech
  'title' => 'Linux 零基礎入門',
  'summary' => '一句話簡介(500 字內)',
  'description' => '課程說明,可多行',
  'level' => '入門',                    // 入門|初級|中級|進階
  'price' => 399,                      // 整數 NT$,0 = 免費
  'published' => true,
  'chapters' => [
    ['title' => '第一章標題', 'lessons' => [
      ['title' => '...', 'type' => 'text',  'content' => "教材全文,純文字,換行以 \n", 'xp' => 10],
      ['title' => '...', 'type' => 'video', 'video_url' => 'https://www.youtube.com/watch?v=XXXXXXXXXXX', 'content' => '影片重點摘要'],
      ['title' => '...', 'type' => 'lab',   'content' => '實作任務步驟與驗收標準', 'xp' => 30],
      ['title' => '...', 'type' => 'quiz',  'pass_score' => 60, 'xp' => 20, 'questions' => [ /* 見下 */ ]],
    ]],
  ],
];
```

## 題型(questions 內每題)
`options` 為字串陣列;`answer` 一律為陣列;單選/複選的 answer 放**選項索引(從 0)**。

| type | options | answer 範例 |
|---|---|---|
| single | 3~5 個選項 | `[1]` |
| multiple | 4~5 個選項 | `[0, 2]` |
| boolean | 不用 | `['true']` 或 `['false']` |
| fill | 不用 | `['chmod', 'CHMOD']`(可接受的多種答案) |
| order | 要排序的步驟 | `[2, 0, 1]`(依正確順序列出選項索引) |

每題必填:`body`、`explanation`(為什麼)、`reference`(例如「第二章 · 使用者與權限」)。

---

# 互動式終端機練習(type = `terminal`)

學員在瀏覽器裡操作**模擬終端機**(虛擬檔案系統,不會執行任何真實指令)。每個任務完成時系統自動勾選,全部完成即通過並給 XP 與技能徽章。

```php
['title' => '單元名稱', 'type' => 'terminal', 'xp' => 30,
 'content' => <<<'TXT'
情境說明(至少 150 字):你要做什麼、為什麼、有哪些前提。可列出提示的觀念,但不要直接貼完整答案。
TXT,
 'config' => [
    'cwd' => '~',                                   // 起始目錄,可省略(預設家目錄 /home/student)
    'fs'  => [                                      // 虛擬檔案系統,路徑從 / 開始;字串=檔案內容,陣列=目錄
        'home' => ['student' => [
            'docs' => ['a.txt' => "apple\nbanana\n"],
            'run.sh' => ['__file' => "#!/bin/bash\necho hi\n", 'mode' => '644'],   // 需要指定權限時用 __file
        ]],
    ],
    'tasks' => [                                    // 至少 3 個,由簡到難;每個都要有 hint
        ['title' => '用一句話說明要做什麼', 'hint' => 'mkdir project', 'check' => ['type' => 'exists', 'path' => '~/project', 'kind' => 'dir']],
        ['title' => '...', 'hint' => '...', 'checks' => [['type' => 'cwd', 'equals' => '~/project'], ['type' => 'mode', 'path' => '~/a.sh', 'equals' => '755']]],  // checks = 全部成立才算
    ],
    'solution' => ['mkdir project', 'cd project'],  // 標準解答(依序執行的指令);必填,用來自動驗證題目可完成
 ],
],
```

## check 類型
| type | 欄位 | 說明 |
|---|---|---|
| `cwd` | `equals` | 目前所在目錄,可用 `~` |
| `exists` | `path`, 可選 `kind`=`file`/`dir` | 路徑存在 |
| `missing` | `path` | 路徑不存在(例如刪除任務) |
| `contains` | `path`, `text` | 檔案內容包含文字 |
| `equals` | `path`, `text` | 檔案內容(去頭尾空白)完全相同 |
| `empty` | `path` | 檔案存在且為空 |
| `mode` | `path`, `equals`(如 `'755'`) | 權限 |
| `count` | `path`, `equals`(整數) | 目錄內項目數 |
| `ran` | `pattern`(正規表示式) | 學員輸入過符合的指令,適合「純檢視」任務(如 `^ls -l`) |
| `out` | `pattern` | 任何一次指令的輸出符合 |

注意:任務一旦完成就不會取消(即使之後又改動)。任務在**一開始不能已經成立**。

## 模擬器支援的指令(只能用這些,寫解答前請確認)
`ls`(-l -a -h -d)、`cd`、`pwd`、`mkdir`(-p)、`rmdir`、`touch`、`cp`(-r)、`mv`、`rm`(-r -f)、`cat`(-n)、`echo`(-n -e)、`head`/`tail`(-n)、`wc`(-l -w -c)、`grep`(-i -n -v -c -r)、`find`(-name -type)、`sort`(-r -n)、`uniq`(-c)、`cut`(-d -f)、`chmod`(數字或 u+x 符號)、`whoami`、`hostname`、`uname`、`date`、`clear`、`history`、`help`、`sudo`、`du`(-h)、`df`/`free`/`ps`/`uptime`(示意輸出)。
也支援:管線 `|`、重新導向 `>` `>>`、`&&` `;`、萬用字元 `*` `?`、`~`、`$HOME`、引號、`./腳本.sh`(需有 x 權限;腳本內只會逐行執行上述指令)。
**不支援**:vim/nano、less/man、管理類指令(apt、systemctl 等)、`awk`/`sed`、`ln`、`stat`、`>` 以外的檔案描述符(如 `2>`)。需要時請在教材用文字說明,不要放進終端機任務。

## 驗證
```
php tools/validate-chapter.php <章節檔>          # 格式
node tools/validate-terminal.mjs <章節檔>        # 在模擬器重播 solution,確認所有任務都能完成
```

---

# 「AI 互動物理教室」章節規格(高中物理)

每章對應五個學習階段。**先讀示範章** `high-school-physics/_example-ch03.php`,再依 `high-school-physics/plan.php` 的規劃(章名、單元、目標、公式、迷思)撰寫。

| 階段 | 單元類型 | 要求 |
|---|---|---|
| 1 觀念教學 | `text` | 用生活例子切入、先觀念後公式、【小標題】分段;涵蓋規劃中該章的所有單元 |
| 2 互動實驗 | `simulation`(有適用的模擬時)或 `lab`(探究與實作) | 見下 |
| 3 公式與計算 | `text` | 推導或說明公式的由來;**至少 2 題完整例題**(逐步計算);常見錯誤。計算與公式區塊用 4 個空白縮排(會顯示成等寬程式碼區塊) |
| 4 AI 隨堂測驗 | `quiz` + `config => ['adaptive' => true, 'take' => 8~10]` | 題庫 **12~16 題**,每題 `difficulty`(1 簡單、2 中等、3 困難),三種難度都至少 3 題;題型混用;有計算題 |
| 5 AI 錯題分析 | (系統自動) | 答錯的題目會進錯題本,所以**每題都要有 `explanation`(含計算過程)與正確的 `reference`** |

每章結構:3~4 個 `text`(觀念教學 1~2、公式與計算 1~2)+ 1 個實驗(`simulation` 或 `lab`)+ 1 個 `quiz`。

## 單元標題與 reference
- 標題建議:「觀念教學:XXX」「公式與計算:XXX」「互動實驗:XXX」或「探究與實作:XXX」「AI 隨堂測驗:XXX」。
- 每題 `reference` 格式「第N章 · 單元名稱」,N 是**本章在該學期的章次**(檔名 chNN 的 NN),單元名稱必須逐字等於本章某個單元標題。

## 文字規範
- 繁體中文(台灣用語)。不用 LaTeX;用 Unicode:v²、½、√、Δ、θ、λ、π、×、÷、⁻¹、°。
- 語音朗讀會略過縮排區塊,所以**重要公式要同時用文字說明**(例如「合力等於質量乘以加速度」)。
- 所有數字都要**自己算對**:用 Python 驗算每一題例題與測驗答案。不確定的觀念不要編造,在回報中標示。
- 物理量要有單位;g 統一取 9.8 m/s²(測驗中若用 10 要在題目寫明)。
- fill(填充)題的 answer 要列出常見等價寫法(如 `['3', '3.0']`),題目要寫清楚單位與格式(例:「只填數字」)。

## 互動實驗(`simulation`)
```php
['title' => '互動實驗:XXX', 'type' => 'simulation', 'xp' => 30, 'content' => '情境說明(≥150 字)', 'config' => [
    'sim' => 'newton2',                                   // 見下表
    'params' => ['m' => 2, 'F' => 4, 'mu' => 0],         // 起始值(可省略,預設為各參數的預設值)
    'tasks' => [                                          // ≥3 個,由易到難,每個都要 hint
        ['title' => '拖動質量滑桿,觀察加速度', 'hint' => '…', 'check' => ['type' => 'touched', 'key' => 'm']],
        ['title' => '讓加速度剛好是 3 m/s²', 'hint' => '…', 'checks' => [['type' => 'param', 'key' => 'mu', 'approx' => 0, 'tol' => 0.001], ['type' => 'out', 'key' => 'a', 'approx' => 3, 'tol' => 0.05]]],
    ],
    'solution' => [['m' => 3], ['mu' => 0, 'm' => 2, 'F' => 6]],   // 依序套用的參數組;必填
]],
```
check 類型:`param`(參數接近某值)、`out`(結果接近某值)、`range`(參數或結果在範圍內)、`touched`(學員拖動過某個參數)。`approx` 與 `tol`(容許誤差)。任務一旦完成就不取消;**一開始不能已經成立**。

| sim | 參數(範圍,步進) | 結果 |
|---|---|---|
| `kinematics` | v0(−20~20,1,m/s)、a(−10~10,0.5,m/s²)、t(0~10,0.5,s) | v、x |
| `newton2` | m(0.5~10,0.5,kg)、F(0~30,1,N)、mu(0~0.5,0.05) | f(摩擦力)、net(合力)、a |
| `projectile` | v0(5~50,1,m/s)、th(0~90,1,°) | T、R、H |
| `shm` | m(0.1~5,0.1,kg)、k(1~100,1,N/m)、A(0.05~0.5,0.05,m) | T、f、vmax、E |
| `wave` | f(1~500,1,Hz)、lam(0.1~5,0.1,m) | v、T |
| `ohm` | V(0~24,1,V)、R(1~100,1,Ω) | I、P |
| `lorentz` | m(1~20,1,u=1.66×10⁻²⁷ kg)、q(1~3,1,e=1.6×10⁻¹⁹ C,正電荷)、B(1~100,1,mT)、v(10~1000,10,km/s) | r(mm,= mv/qB)、T(μs,= 2πm/qB)、f(kHz) |
| `photoelectric` | f(2~12,0.1,×10¹⁴ Hz)、I(10~100,10,% 相對光強)、phi(1.5~6,0.1,eV;Cs 2.1、Na 2.3、Zn 4.3、Cu 4.7、Pt 5.6) | emit(1 射出/0 不射出)、f0(×10¹⁴ Hz)、K(eV,= hf−φ,不射出時 0)、Vs(V)、Isat(μA,= 0.1×I,不射出時 0);h = 6.63×10⁻³⁴、e = 1.6×10⁻¹⁹ |
| `lens` | f(−30~30,1,cm;負為凹透鏡,**不能為 0**)、p(5~60,1,cm) | q(cm,1/p+1/q=1/f,q>0 實像;p=f 時為 ∞)、m(= −q/p)、real(1 實像/0 虛像/−1 不成像)、up(1 正立/−1 倒立/0 不成像) |
| `torque` | F1(1~20,1,N)、d1(10~100,5,cm)、F2(1~20,1,N)、d2(10~100,5,cm);支點在中央,F1 在左、F2 在右,皆垂直向下 | tauL(N·m,逆時針)、tauR(N·m,順時針)、net(= τ₁−τ₂,逆時針為正)、state(1 左端下沉/0 平衡/−1 右端下沉) |
| `collision` | m1、m2(0.5~5,0.5,kg)、v1、v2(−5~5,0.5,m/s,向右為正;滑車 1 在左)、e(0~1,0.05,恢復係數:1 完全彈性、0 完全非彈性) | u1、u2(碰後速度)、pb、pa(碰前/後總動量)、kb、ka(碰前/後總動能)、dk(動能損失)。v1 ≤ v2 時不相撞,速度不變 |
| `gas` | n(0.5~5,0.5,mol)、T(100~600,10,K)、V(5~50,1,L)、M(2~44,1,g/mol;H₂ 2、He 4、Ne 20、N₂ 28、O₂ 32、CO₂ 44) | Pk(kPa)、Pa(atm,1 atm = 101.325 kPa)、vrms(m/s,= √(3RT/M));R = 8.314 |
| `coulomb` | q1、q2(−10~10,1,μC,可正負)、r(10~200,5,cm) | F(N,大小,k = 9.0×10⁹)、kind(1 排斥/−1 吸引/0 無)、E(kN/C,中點電場,向右為正) |
| `doubleslit` | d(0.1~1,0.05,mm)、L(0.5~5,0.1,m)、lam(400~700,10,nm)、m(0~5,1,亮紋級次) | dy(mm,= λL/d,小角度近似)、ym(mm,= m·Δy) |
| `density` | m(1~300,1,g)、V(1~100,1,cm³)、liq(0~3,1:0 酒精 0.8、1 水 1.0、2 鹽水 1.2、3 水銀 13.6 g/cm³) | rho(g/cm³,= m/V)、rhoL(液體密度)、state(1 漂浮/0 懸浮/−1 下沉)、frac(浸入體積比例 %,漂浮 = ρ物/ρ液×100,否則 100) |
| `buoyancy` | V(10~100,5,cm³)、rho(0.2~8,0.1,g/cm³)、liq(0~3,同 density)、frac(0~100,10,% 浸入比例);g = 10 N/kg | W(N,= ρVg)、Vd(cm³,排開體積)、B(N,= ρ_l·V排·g,即排開液體重)、reading(N,彈簧秤讀數 = max(0,W−B))、state(放手後 1/0/−1)、eq(漂浮時浸入 %) |
| `liquid-pressure` | h(0~10,0.5,m)、liq(0~3,同 density)、A(1~100,1,cm²);g = 10 N/kg、大氣壓 1.0×10⁵ Pa | P(Pa,= ρgh)、Pt(Pa,+ 大氣壓)、F(N,= PA)、Ft(N,= Pt·A) |
| `heat-mixing` | m1、m2(10~500,10,g)、mat1、mat2(0~4,1:0 水 1.00、1 酒精 0.58、2 鋁 0.22、3 鐵 0.11、4 銅 0.093 cal/g·°C)、T1、T2(0~100,1,°C);不計熱損失 | Teq(°C)、Q(cal,轉移熱量)、QJ(J,1 cal = 4.2 J)、dir(1 物質 1→2/−1 物質 2→1/0 無) |
| `refraction` | th1(0~90,1,°入射角)、n1、n2(0~3,1:0 空氣 1.00、1 水 1.33、2 玻璃 1.50、3 鑽石 2.42;光由介質 1 射向介質 2) | thr(反射角)、th2(折射角,全反射時 −1)、thc(臨界角 °,n₁ ≤ n₂ 時 −1)、tir(1 全反射/0 否) |
| `circuit` | V(1~24,1,V)、R1、R2(1~50,1,Ω)、mode(0 串聯/1 並聯) | Req(Ω)、I(A,總電流)、V1、V2(V)、I1、I2(A)、P1、P2(W) |
| `simple-machine` | kind(0 槓桿/1 動滑輪組/2 斜面)、m(1~50,1,kg,W = 10m N)、n(1~10,1:力臂比/承重繩段數/斜面長÷高)、eta(10~100,5,% 效率)、h(0.1~2,0.1,m 重物升高) | W(N)、F(N,= W/(n·效率))、MA(= n)、AMA(= W/F)、d(m,施力移動距離 = nh)、Win(J)、Wout(J,= Wh) |
| `echo` | T(−10~40,1,°C)、d(5~1000,5,m)、t(0.05~6,0.05,s) | v(m/s,= 331 + 0.6T)、te(s,= 2d/v)、dt(m,= vt/2)、clear(1 回聲可分辨 te ≥ 0.1 s/0) |
| `electromagnet` | N(10~200,10,匝)、I(0~3,0.1,A)、core(0 無鐵芯/1 有鐵芯) | S(磁力指數 = N·I,有鐵芯 ×10,示意模型)、clips(吸起迴紋針數 = min(20, ⌊S/100⌋),示意) |
| `measure-reading` | kind(0 直尺最小刻度 0.1 cm/1 量筒 1 mL/2 溫度計 1 °C)、v(0~100,0.01,真實值,單位依工具)、sig(0 只記到最小刻度/1 估計到下一位) | md(最小刻度)、reading(應記錄的讀數)、certain(準確值)、est(估計位數字 0~9)、err(讀數 − 真實值) |
| `thermometer-scales` | T(−50~150,1,°C)、liq(0 酒精:78°C 沸騰/1 水銀:−39°C 凝固)、rng(0 −20~110/1 −30~50/2 35~42 °C 量程) | F(°F = 1.8C+32)、K(= C+273)、h(液柱占量程 %)、state(0 正常/1 超出量程/2 液體沸騰/3 液體凝固) |
| `heating-curve` | m(10~200,10,g 冰質量)、T0(−40~0,5,°C 冰初溫)、P(100~1000,100,W,熱量全被吸收)、t(0~3600,10,s);冰 0.5、水 1、汽 0.5 cal/g·°C,熔化熱 80、汽化熱 540 cal/g | Q(cal,= Pt/4.2)、T(°C)、phase(0 冰/1 熔化中/2 水/3 沸騰中/4 水蒸氣)、frac(該階段完成 %) |
| `plane-mirror` | p(5~50,1,cm 物到鏡面垂直距離)、h(1~10,1,cm)、th(0~60,1,° 入射角)、alpha(0~30,1,° 鏡面轉動角) | q(像距 = p)、d(物像相距 = 2p)、hi(像高 = h)、thr(反射角 = th + alpha)、turn(反射光轉動 = 2α) |
| `eye-optics` | p(10~500,5,cm)、f(1.8~2.6,0.05,cm 水晶體焦距)、D(−4~4,0.5,屈光度,負凹正凸,貼眼:1/f總 = 1/f + D/100);晶體到視網膜 2.4 cm | ft(等效焦距 cm)、q(像距 cm)、diff(像 − 視網膜 mm,正為後方)、where(−1 視網膜前/0 剛好在視網膜(±0.3 mm)/1 後) |
| `force-arrows` | F1、F2(−30~30,1,N,向右為正)、m(0.5~10,0.5,kg) | R(= F1+F2,有號)、mag、dir(1 向右/−1 向左/0 平衡)、a(= R/m) |
| `hooke-spring` | W(0~500,10,gw 掛重)、k(5~50,5,gw/cm)、L0(5~20,1,cm 原長)、lim(100~500,50,gw 彈性限度);1 gw ≈ 0.01 N | ext(cm,= W/k;超過限度後斜率變 3 倍示意)、L(= L0 + ext)、F(N,= 0.01W)、state(0 彈性限度內/1 超過) |
| `friction` | m(1~20,1,kg)、F(0~100,1,N)、surf(0 冰 μs 0.1/μk 0.05、1 木 0.4/0.3、2 橡膠 0.8/0.7)、P(0~50,5,N 額外下壓);g = 10 | N(= 10m + P)、fmax(= μs N)、f(靜止時 = F,滑動時 = μk N)、state(0 靜止/1 滑動)、a |
| `pressure-area` | F(10~500,10,gw)、a(0.1~10,0.1,cm² 單點面積)、n(1~100,1,接觸點數) | A(= n·a cm²)、P(gw/cm²,= F/A)、Pa(Pa,= 100 P) |
| `torricelli` | alt(0~5000,100,m 海拔)、tilt(0~60,5,° 管傾斜)、liq(0 水銀/1 水) | Pc(cmHg,= 76·e^(−alt/8000))、Pa(= 1360·Pc)、hv(垂直液柱高 cm,水為 13.6 倍)、len(= hv/cosθ) |
| `circular-motion` | r(0.5~3,0.1,m)、v(1~10,0.5,m/s)、m(0.5~5,0.5,kg) | T(= 2πr/v)、w(= v/r)、ac(= v²/r)、Fc(= mv²/r,N) |
| `work-power` | F(1~50,1,N)、s(0.5~10,0.5,m)、t(1~20,1,s)、th(0~90,5,° 力與位移夾角) | W(J,= Fs cosθ)、P(W)、v(= s/t)、works(1 有作功/0 沒有) |
| `energy-skate` | h0(0.5~5,0.5,m 起點高度)、m(0.5~5,0.5,kg)、h(0~5,0.5,m 觀察點)、lam(0~50,5,% 每下降 1 m 損失的位能比例);g = 10 | U(= mgh)、K、E(= U + K)、Qh(摩擦熱)、v、reach(1 可到達/0 h > h0) |
| `static-charging` | mode(0 摩擦/1 感應/2 接觸)、A、B(0~3,1:0 毛皮、1 玻璃棒、2 絲綢、3 橡膠棒;摩擦序靠前者帶正電)、n(1~10,1,摩擦次數)、gnd(0 不接地/1 接地) | q1(A 最後電量)、q2(第二物體:摩擦為 B、其餘為導體球)、force(1 排斥/−1 吸引/0 無) |
| `wire-resistance` | L(10~100,10,cm)、S(0.1~2,0.1,mm²)、mat(0 銅 ρ0.017/1 鐵 0.10/2 鎳鉻 1.1 Ω·mm²/m)、V(1~12,1,V) | R(Ω,= ρL/S)、I(A)、P(W)、warn(1 電流 > 10 A) |
| `power-bill` | P(10~2000,10,W)、h(0.5~24,0.5,每天小時)、days(1~60,1)、price(1~10,0.5,元/度);家用 110 V | kwh(度)、E(MJ,= 3.6 kwh)、cost(元)、I(A,= P/110) |
| `household-circuit` | a1~a4(0 關/1 開:電燈 100 W、電鍋 800 W、電暖器 1000 W、吹風機 1200 W)、fuse(5~30,5,A);並聯接 110 V | Ptot(W)、I(A,= Ptot/110)、blow(1 熔斷:I > fuse) |
| `right-hand-rule` | form(0 直導線/1 螺旋管)、dir(0 正向/1 反向)、I(0~5,0.5,A)、N(1~20,1,螺旋管匝數,長 10 cm)、r(1~10,1,cm 距直導線) | B(μT;直線 = 2×10⁻⁷I/r,螺旋管 = μ₀NI/ℓ)、rot(直線:1 逆時針/−1 順時針/0)、npole(螺旋管:1 N 極在右/−1 左/0) |
| `motor-force` | I(0~5,0.5,A)、idir(0 向右/1 向左)、B(0.1~1,0.1,T)、bdir(0 進入紙面/1 穿出紙面)、N(1~20,1,匝;導線長 L = 10 cm) | F(N,= BIL)、Ft(= N·F)、dir(1 向上/−1 向下/0;向右電流 + 進入紙面磁場 → 向上) |
| `generator-induction` | mode(0 磁鐵進出線圈/1 發電機)、spd(0~5,0.5,磁鐵 m/s 或轉速圈/秒)、N(10~100,10,匝)、B(0.1~1,0.1,T)、dirm(0 靠近/1 遠離,僅磁鐵模式) | emf(V;磁鐵 = NB·0.05·v,發電機峰值 = NB·0.002·2πf)、I(A,R = 10 Ω)、f(Hz)、dir(1 指針右偏/−1 左偏/0 無/2 交流) |

國中物理 9 個實驗(`density` … `electromagnet`,以及對應 plan.php「新增:」的 20 個:`measure-reading` … `generator-induction`,名稱與 plan.php 完全相同;g = 10 N/kg、水密度 1 g/cm³、水比熱 1 cal/g·°C)的示範設定在 `tools/sim-demos/junior-high-sims-demo.php`;另外新增 8 個實驗的示範設定(含任務與標準解答)在 `tools/sim-demos/new-sims-demo.php`,可用 `node tools/validate-sim.mjs tools/sim-demos/new-sims-demo.php` 驗證。`out` 檢查對 `real`、`kind`、`state`、`emit` 等代碼結果同樣有效(approx 填代碼值,tol 0.1)。

重點:任務裡的目標值要用模擬的**真實計算結果**(例如 newton2 取 g = 9.8:摩擦力上限 = mu × m × 9.8)。沒有適合的模擬時,改用 `lab`(探究與實作:目的、器材、步驟、數據記錄、分析、討論;文字說明即可)。

## 動畫教學(`animation`)
階段 1「觀念教學」除了文字,也可以放理論動畫:動畫 + 同步字幕,學員可播放、暫停、重播、拖動時間軸、調速度,也能點字幕跳到那一刻,並選擇用 AI 語音朗讀字幕;**看完整段會自動記錄完成**。
```php
['title' => '動畫教學:XXX', 'type' => 'animation', 'xp' => 10, 'content' => '一兩句說明(≥60 字)', 'config' => [
    'anim' => 'newton3',                      // 見下表
    'params' => ['mA' => 2, 'mB' => 1],       // 可省略(用預設值)
    'duration' => 12,                         // 可省略(用動畫預設總長)
    'steps' => [                              // 字幕時間軸(≥3 個):at = 秒數,第一個必須是 0,遞增,且小於總長
        ['at' => 0, 'text' => '…'], ['at' => 3, 'text' => '…'],
    ],
]],
```
字幕要像老師在旁白:一句話一個重點,**要與該時刻畫面正在演的內容一致**(先看下表各動畫的時間軸再寫)。

| anim | 內容與時間軸 | params(預設) |
|---|---|---|
| `vector-add` | 0.3–2.5 秒畫出 A;3–4.5 畫出 B;4.5–6.5 B 平移到 A 的箭頭端;6.5–8.5 畫出合向量 A+B;9–10.5 出現虛線的平行四邊形。總長 12 | ax 160、ay 60、bx 90、by 120 |
| `kinematics-graphs` | 物體沿直線等加速度運動,同步畫出 x–t 圖與 v–t 圖。總長 10 | v0 0、a 2、T 10 |
| `free-fall-strobe` | 慢動作頻閃:A 自由落下、B 水平拋出,兩者同一時刻到同一高度。約 9 秒才落地。總長 10 | vx 60 |
| `newton3` | 0–3 A 推 B;3–4.5 出現一對大小相等方向相反的力(作用在不同物體);4.5 後兩物體依各自質量加速;7 秒起顯示說明。總長 12 | mA 2、mB 1 |
| `circular-motion` | 球繞圓運動;3 秒起出現沿切線的速度;6 秒起出現指向圓心的加速度。總長 12 | period 4、r 100 |
| `wave-superposition` | 兩個脈衝相向行進、約 8.6 秒在中央相遇,下方為合成波;sign = 1 同相(加強)、−1 反相(抵消)。總長 14 | sign 1 |
| `doppler` | 波源向右移動,前方波前變密、後方變疏。總長 12 | vs 0.5 |
| `em-induction` | 0–5 磁鐵靠近線圈(指針右偏);7–12 磁鐵遠離(指針左偏);其餘靜止。總長 14 | — |
| `pendulum-energy` | 單擺擺動,同步顯示位能、動能與總和長條圖。總長 12 | amp 0.7(弧度)、period 4 |
| `atomic-levels` | 0–3 電子在高能階;3–5.5 躍遷;5.5 起放出光子並顯示能量與波長。總長 12 | from 3、to 2 |

## 驗證
```
php tools/validate-chapter.php <章節檔>     # 格式、題庫大小與難度分布、reference
node tools/validate-sim.mjs <章節檔>        # 互動實驗的標準解答能完成所有任務
node tools/validate-anim.mjs <章節檔>       # 動畫教學:動畫存在、字幕時間軸合法、整段都畫得出來
```
