WikiTA · 操作說明 v2 phase 1

總覽

WikiTA 是給研究實驗室「新人入訓」用的 onboarding 系統。AI 帶學生跑一輪 Probe → Deepen → Reassess 的適性學習循環，PI 在 dashboard 看 mastery heatmap 即時介入。一個 server 可以同時 host 多個 lab， 彼此資料隔離（row-level security）。

核心概念

學習引擎流程

每次學生答題後，orchestrator 重新判斷下一階段：

三個引擎做什麼

• Probe engine — 入口階段，快速掃哪些 concept 是 shaky 的。優先順序：unseen → struggling → developing。
• Deepen engine — 挑「prereq 都 ≥ proficient 的最弱 concept」加強。錯了會分類 no_idea / careless / confusion / prereq_gap，下一題會根據錯因換 tier/換 concept。
• Reassess engine — 固定題數的跨 concept 小測驗，確認 deepen 階段的進展是真的，不是 short-term recall。
• Grader — MC 直接比，free-text 走 LLM 判分；錯題會被 LLM 升級分類（如 confusion）。
• Mastery propagation — 答對：往上拉 prereq；答錯：往下拉 dependent。單向。

角色 × 權限矩陣

如何進入系統

Landing page（/）會列出 server 上所有 lab；點任一張卡 → /{slug}/login 登入。 Beta lab 帳號是把 alpha 換成 beta（beta-s / beta-s-pw 等）。

Student（學生） student

學生是 WikiTA 的主受眾。一個 topic 從 picker → study → completed，全部在 http://<host>:5174 的單一 SPA 裡跑。

1. 主題挑選（📚 主題 tab）

登入後預設停在 picker，畫面採兩段式：

• 分類 grid（首頁）：依 visible_to 過濾掉看不到的，剩下的 topic 按 Category 分組顯示為一張張卡片（卡片上有 PI 設的 emoji + 色塊 + display_name + topic 數）。沒分類的 topic 會被放進「未分類」群組。
• Topic 清單：點分類卡 → 看該分類底下所有 topic。每張卡顯示 display name、簡介、目前 mastery（如果已開始過）、最近活動時間。已 completed 的會標示但仍可重進去複習。點 topic → 觸發 POST /api/topic/enter 建 session → 拿到第一題。

2. 答題與學習（study mode）

進 topic 後左邊是題目區，右邊（非 interviewer）是側邊欄。

題目區動作

• MC 題：選一個選項 → 「送出」。
• Free-text 題：在 textarea 打字 → 「送出」。LLM 判分，秒級。
• 判分後立刻顯示「對 / 錯 / 部分對」+ LLM 的 feedback + 下一題按鈕。
• 「離開」回到 picker（session 保留，下次回來接續）。

顯示資訊

• 目前 concept 名稱、tier、stage（probe / deepen / reassess）。
• 該 concept 的 mastery 分數 + 進度條。
• 如果 PI 對你下了 directive（見 PI 章節），會在頂端顯示。

3. 💡 提示 與 🤖 TA

右側邊欄（interviewer 看不到）：

4. 🆘 求救（escalate）

「真的卡住了，要人介入」時按 escalate：

• 系統建一筆 alert（type=escalate），所有 PI/mentor 的 dashboard 馬上看到。
• 後台 mentor/PI 可以 acknowledge、resolve、或直接傳訊息給你。
• 同一題短時間內按多次 escalate 不會重複建 alert。

5. 📖 看 wiki / supplements

• 每個 concept 旁有「看 wiki」按鈕 → 開 modal 顯示該 concept 的 wiki 內文（markdown rendered + KaTeX）。
• PI 可以掛補充材料（URL / 圖 / PDF）；學生在 wiki modal 也看得到。

6. 👤 我的進度 tab

• 每個 topic 的整體 mastery、概念熱圖、最近答題時間軸。
• 錯題簿：列出近期答錯的題目 + 當時的 feedback，可重做。
• TA 對話歷史：過去的 TA chat thread。
• 登入記錄：最近的 login activity（含 IP）。
• CSV 下載：你自己的所有 attempts 匯出。

7. 📬 訊息 tab

• 跟 PI / mentor / 其他學生通訊。
• 未讀數會在 tab title 上顯示紅點。
• PI directive 不在這裡 — 那會直接出現在 study 畫面上方。

Interviewer（面試 / 旁聽） interviewer

跟學生用同一個 SPA 殼，但**所有「外援」都被砍掉**。場景：lab 申請者的能力檢測、 或實驗室訪客體驗系統。

跟 student 的差別

PI（實驗室負責人） pi

PI 是 lab 的最高權限者。主介面是 http://<host>:5173/teacher， 9 個 tab 涵蓋所有日常管理。另有獨立的 Bundle 編輯器（/bundle-editor）用來建/改 topic。

① 學生進度 tab（progress）

左：學生清單（可搜尋）。中：選中的學生詳情。右：可選 topic 的 heatmap。

• 學生詳情：各 topic 的 mastery 分數 + tier、最近 attempts、persona 偏好。
• 🧭 holistic 摘要：LLM 寫的 1 段話總結這個學生最近狀況（強項、卡點、建議）。On-demand 產生。
• CSV 下載：該學生所有 attempts。
• Heatmap：選 topic → 看 (學生 × concept) 矩陣，每格是 mastery 分數，顏色標 status。
• Topic ACL(存取控制清單)（pin to students）：在 heatmap 頁可以把某 topic 限定給特定學生（其他人看不到、進不去）。

② 註冊審核 tab（signup）

所有 signup request 列表（包括 Google OIDC 註冊但未配 role 的人）。

• 每筆顯示：email、申請角色、申請時間、備註。
• 批准 → 啟用帳號（user.approval_status=active）。
• 拒絕 → 標 rejected；同 email 不能再申請。

③ 內容審核 tab（content）

學生分享過來的 3 種內容，pending 狀態的全部列在這裡：

• ta_log — 學生想公開的 TA 對話片段
• inline_question — 學生在 wiki 上補的「我也想問」
• peer_qa — 學生問 / 其他學生答的 Q&A

每筆可以：

• 批准 → 變成 topic 內公開可見的補充材料。
• 編輯後批准 → 改 body / 加 reason，再 commit（寫入 pi_content_overrides 留 audit）。
• 軟刪除 → 隱藏，並記 reason。

📁 分類 tab（categories）

把 lab 內的 topic 分組。學生 SPA picker 進來會先看到分類 grid、點分類才看分類底下的 topic 清單。一個 topic 最多歸一個分類，不指派就是「未分類」。兩個 panel：

分類管理（上）

• 欄位：
  • slug（必填，小寫英數+連字號，例：basics。建立後不可改）
  • display_name（必填，顯示給學生看的中文/英文名）
  • icon（emoji，顯示在學生卡片上，例：📚）
  • color（卡片色塊，hex 例：#7fc5b3）
  • display_order（同 lab 內排序，越小越前面）
  • description（選填，顯示在學生 category 卡片下方）
• 動作：每筆可 inline 編輯（除 slug 外）或刪除。 刪除時若分類下有 topic，會跳 confirm；確定後 topic 變「未分類」（ON DELETE SET NULL），不會刪 topic 本身。

Topic 指派（下）

• 列出 lab 內所有 topic，每筆右邊有分類 dropdown。改了 dropdown → 點「套用」即可重指派。
• 選「（未分類）」會把該 topic 從分類抽出。

跟 Bundle Editor 的關係

• Bundle Editor 的 config 表單也有 category dropdown，可在匯入 topic 時就指定。但選項只列當下這個 lab 已存在的分類 — 先去這個 tab 建分類，bundle 那邊才會看到。
• Bundle 在不同 lab 間搬：config.json 裡寫的是 slug 字串。如果目標 lab 沒有同名分類，匯入時靜默 fallback 成「未分類」（不報錯），PI 自己進 dashboard 重指。

④ PI 指令 tab（directive）

對某 (student, topic) 寫一段 free-text 指令。設定後：

• 學生在那個 topic 的 TA 對話、hint，都會把這段話當「最高優先級 system instruction」吃進去。
• 典型用法：「這位學生有 git 經驗，跳過基礎 commit 教學，直接講 rebase」、 「該 concept 要強調 X 角度」。
• 清除指令：按 delete 即可恢復預設 TA 行為。
• 每次設定 / 修改都進 audit log。

⑤ 掌握度 override tab（verbs）

對單一 (student, concept) 套用「四個動詞」：

• 每次 override 必填 reason，會記 teacher_actions 表。
• 該 (student, concept) 的歷史列在右側面板。

⑥ 🆘 警示 tab（alerts）

backend scheduler（60s 一次）+ 學生 escalate 會丟 alert 進來：

• stuck — 連續 N 題在同 concept 上錯，scheduler 自動偵測
• escalate — 學生按求救按鈕
• escalation — alert 沒人處理超時 → 升級提醒

每筆可：

• Acknowledge — 我看到了（兩者都可）
• Resolve — 處理完了（PI only）

⑦ 📝 題庫 tab（questions）

選 topic → 列出該 topic 所有題目。可篩 approved/pending。

• Approve：題目進入正式 pool（學生會抽到）。
• Unapprove：撤回，學生不會再被分到。
• Edit：改 stem / tier / choices / answer。
• Delete：硬刪。

題目來源：bundle 匯入 + LLM auto-generator（pi_generation router）。

⑧ 💰 LLM 成本 tab（cost）

• 按日聚合：calls 數、in / out tokens、cache hit、估算 USD。
• 下方明細表：最近 50 筆 LLM 呼叫（哪個 prompt、哪個 caller、耗時、tokens）。
• 支援切換時間範圍（7 / 30 / 90 天）。

⑨ 📬 訊息 tab（messages）

• 所有跟你（PI 帳號）有交互的 conversations 列表。
• 點開 thread → 看歷史 + 回覆。
• 新對話：選一個學生 → 開新 thread。
• 未讀數即時更新。

獨立頁：Bundle 編輯器（/bundle-editor）

PI 用來「一次到位」建立 / 更新一個 topic。網址： http://localhost:5173/bundle-editor

輸入：一個 markdown bundle 檔（包含 topic config、所有 concepts、wiki、questions 都在一份 .md 裡）。

• 支援三種來源：① 貼上文字 ② 上傳 .md 檔 ③ 從既有 topic 載入。
• 右側檔案樹列出 bundle 解析出的內容；點任一檔案看 preview。
• 左下 驗證結果面板列出 E1–E15（errors）、W1–W9（warnings）。Errors 必須清掉才能匯入。
• 匯入：把整個 bundle 寫進 DB。Topic 若已存在會被替換（注意：不會清掉學生的 mastery）。

Mentor（共同指導者） mentor

Mentor 用跟 PI 一樣的 /teacher dashboard，但是 讀多寫少。設計上 mentor 是 PI 的副手：可以看、可以聊、可以 acknowledge alert，但不負責管帳號和改 mastery。

Mentor 看得到 / 做得到

• 學生進度 tab — heatmap、學生詳情、holistic 摘要、CSV 下載：都可
• 警示 tab — 看 alert、acknowledge alert：可
• 訊息 tab — 跟學生 / PI 雙向訊息：可
• LLM 成本 tab — 可看
• 題庫 tab — 可看（題目列表），但 approve / edit / delete 是 PI only

Mentor 看不到 / 做不了

• 註冊審核（signup）— PI only
• 內容審核（content）— PI only
• PI 指令（directive）— PI only
• 掌握度 override（verbs）— PI only
• Resolve alert（acknowledge 可，但結案是 PI）
• Bundle 編輯器：開得了頁，但匯入會被 backend 擋（PI only）

技術上：teacher.html 在沒許可的 tab 還是會顯示，但點 PI-only 動作時 backend 會回 403。前端不主動 hide tab，是為了讓 mentor 知道「這些功能存在，找 PI 處理」。

共通：密碼 / 登出 / 註冊

登入

• 所有 SPA 的 /login 頁支援兩種方式：
  1. Password：填 lab slug + username + password。
  2. Google OIDC：用 Google 帳號登入（前提：lab 有設 Google client ID）。
• 成功後拿到一個 15 min 有效的 access JWT + 7 day refresh cookie。expires 前 api-client.js 會自動 refresh。

登出

• 右上角 Logout → 呼叫 /api/logout revoke refresh token → 清 localStorage → 回登入頁。

改密碼

• 「我的進度」 → 改密碼區塊：填舊密碼 + 新密碼。
• 新舊密碼不能同。長度限制由 backend 控制。

忘記密碼

• 登入頁的「忘記密碼」連結 → /password_reset。
• 輸 email → backend 寄 reset link（email subject 包 token）。
• 點 link 回到同一頁，填新密碼即可。

申請帳號（student）

• 學生 SPA 的 /signup。
• 填 email + lab + 想要的 username + 自我介紹 → 送 PI 審。
• PI 核可前無法登入。

FAQ & 疑難排解