學生對複雜問題啟動的 ReAct 多步研究模式：跨工具蒐集證據、自我反思、整合成帶引用的完整答案。涵蓋規劃 / 行動 / 觀察 / 反思 / 整合的閉環設計，與五層成本與安全防線。
Deep Research（深度研究）是 Uedu 平台上針對「需要跨多個資料來源、多步驟推理」的學習問題提供的研究模式。當學生提出涉及課程教材整合、跨領域比較、文獻檢索、課程規劃等難以一句話回答的問題時，AI 會自動進入 ReAct（Reasoning + Acting）循環，先規劃、再分步呼叫工具蒐集證據、過程中持續反思是否充分，最後整合成帶引用的完整答案。
這個設計回應了一般 LLM 對話的兩個侷限：
ClassroomGPT 是教師設定的單回合問答助教；Aida 是 AIDA 框架下的蘇格拉底式引導夥伴；Deep Research 是針對複雜問題的「研究員」角色，會自主跨多步、多工具完成研究任務。三者共用同一份 chat_tools.py tool registry，但流程模式截然不同：助教與 Aida 是即時往返對話，Deep Research 是長時間、多輪、可在背景執行的任務式工作。
Deep Research 預設關閉，由教師在頻道設定第 6 區「Deep Research（深度研究模式）」開關啟用後，學生對話框才會出現青綠色放大鏡按鈕。
每次研究皆走 Plan → (Action → Observation → Reflect)* → Synthesize 的循環，直到 LLM 判斷已收集充分資料、或觸及系統上限為止。
| 階段 | 輸出 | 負責角色 |
|---|---|---|
| Plan 規劃 | 判斷複雜度（simple / moderate / complex）、拆解 2~6 個子問題、預估會用到的工具 | Planner LLM（GPT-5.4-mini） |
| Action 行動 | 從工具註冊表選擇下一個要呼叫的工具，並產生參數 | Action LLM with function calling |
| Observation 觀察 | 記錄工具回傳結果（前 N 字摘要 + 完整資料供後續 LLM 使用） | 引擎 |
| Reflect 反思 | 判斷已收集的觀察是否足以回答原問題；若不足則回到 Action，若足夠則進入 Synthesize | Reflection LLM |
| Synthesize 整合 | 整合所有觀察、產出最終答案、組裝引用列表 | Synthesizer LLM with structured output |
Planner 將原問題拆成 2~6 個可獨立研究的子問題，並對每個子問題建議可能適用的工具。複雜度判斷會影響後續執行步數與整體 token 預算：
| 複雜度 | 典型子問題數 | 典型工具呼叫次數 |
|---|---|---|
| simple | 2~3 | 2~5 |
| moderate | 3~4 | 5~10 |
| complex | 4~6 | 10~20 |
所有階段透過 Server-Sent Events 推送給前端，事件類型包含 connected、task_created、status_change、plan_complete、action_thinking、action_dispatch、action_complete、reflection_done、limit_hit、cancelled、completed、failed 與每 15 秒一次的 heartbeat。前端可即時顯示步數、tokens、工具呼叫狀態。
研究可能跑數分鐘，引擎每 15 秒推送一次 heartbeat 事件，確保 SSE 長連線在無工具回應的等待期間不被中斷，學生端進度顯示也持續更新。
Deep Research 啟動後消耗 30~60 秒、數萬 token，並非每個問題都值得啟用。系統提供兩條觸發路徑：
學生明確按下放大鏡按鈕後送出問題，引擎以 trigger_mode='forced' 直接啟動。
學生在一般輸入框輸入問題時，前端會以輕量 LLM 判斷是否「值得啟動」。判斷器（auto-judge）會檢視以下特徵：
| 適合 Deep Research 的特徵 | 不適合的特徵 |
|---|---|
| 需要跨多個資料源整合 | 單一事實查詢可一句話回答 |
| 涉及論文 / 教材 / 課綱比較 | 純算術、單概念定義 |
| 需要有引用的學術性回答 | 閒聊、情緒回應 |
| 規劃類問題（教學順序 / 學習路徑） | 已被工具呼叫即可解決的單步問題 |
判斷器同時回傳信心度（0~1）。前端在信心度高於閾值時顯示「這個問題適合用 Deep Research 深度研究」提示卡，學生可自行決定是否升級成 DR 模式或維持一般對話。
Deep Research 的單次成本約是一般對話的 30~100 倍。為避免學生誤點消耗配額，Auto 模式只「建議」不「自動啟動」——最終由學生明確確認，研究才會真正執行。這個門檻是有意設計的：保留學生的決定權，也讓他們在按下按鈕前思考「這個問題值不值得深入研究」。
Deep Research 的 Action 階段共用 ClassroomGPT / Aida 的 chat_tools.py 工具註冊表，但實際被呼叫的子集會依問題情境動態調整。常見的工具調度組合：
| 問題類型 | 典型工具序列 |
|---|---|
| 課程教材整合 | get_course_overview → search_channel_materials → list_uedu_team_papers |
| 學科教學順序規劃 | get_hs_curriculum → search_channel_materials → search_advisor_papers |
| 研究領域探索 | list_research_clusters → get_cluster_advisors → search_external_papers（OpenAlex） |
| 跨課程比較 | get_course_overview（多次）→ search_channel_materials → list_uedu_universities |
search_channel_materials 是 Deep Research 在課程情境下最常呼叫的工具。它從教師上傳的本頻道 RAG 教材（PDF / DOCX / PPTX）中以語意檢索（cosine similarity）找出相關段落，回傳檔名、頁碼、段落原文，供 Synthesizer 引用。詳見RAG 方法論。
search_external_papers 透過 OpenAlex 公開 API 查詢台灣 / 新加坡 / 日本 / 韓國 / 中國五國機構的學術論文。引擎會在 Synthesize 階段嚴格區隔：
search_advisor_papers）：可標示作者、提供 advisor profile 連結單次研究最多 30 步（每步可能呼叫 1~N 個工具）、累計 200,000 tokens、執行時間 10 分鐘。任一上限觸及即進入 Synthesize 階段（仍會產出答案，但會在 SSE 推送 limit_hit 告知原因）。
所有 Action 階段的觀察會與原問題一同送進 Synthesizer LLM，輸出 結構化 JSON（answer + citations）。Synthesizer 採用 response_format={"type":"json_object"} 強制 JSON 輸出，並指示 LLM 在 answer 內以 [1]、[2] 等標號引用來源。
| 欄位 | 內容 |
|---|---|
answer | Markdown 格式的答案文字，內嵌 [N] 標號 |
citations[] | 每筆含 id、title、url、source_tool、snippet |
Synthesizer 是整個流程中最容易出問題的環節，因為要在固定 token 預算內整合大量觀察。實務上踩過兩個雷：
reasoning_effort='medium' 會吃掉大半 max_completion_tokens，留給輸出的空間不足，產出空字串max_completion_tokens 設太低（如 6,000）容易在輸出中段截斷目前生產環境設定為 reasoning_effort='low' + max_completion_tokens=12000，並檢查 finish_reason 是否為 length 來偵測截斷。
每個 citation 都附上 source_tool（產生該引用的工具名）與 snippet（原始段落或前 N 字）。學生可從答案下方的引用列表展開查看原始內容，研究結果頁也保留完整 plan_json / observations，供後續稽核。
Deep Research 是平台上單次成本最高的功能。為避免被誤用、濫用或失控導致成本暴衝，引擎建構了五層防線：
| 層級 | 機制 | 觸發條件 |
|---|---|---|
| 1. 引擎內建上限 | 單次研究 30 步 / 200K tokens / 10 分鐘 | 任一上限觸及 → 進入 Synthesize（仍產出答案） |
| 2. 個人配額 | 學生 20 次 / 日，助教 40 次 / 日，教師與管理員無上限 | 當日累計達上限 → 直接拒絕啟動 |
| 3. 速率限制 | Flask-Limiter（每使用者每分鐘） | 短時間連續呼叫 → 429 Too Many Requests |
| 4. 成本告警 cron | scripts/deep_research_cost_alert.py 每日跑 |
當日累計成本 > UEDU_DEEP_RESEARCH_ALERT_USD（預設 $20）→ 寄信告警 |
| 5. 平台每日硬上限 | 全平台累計成本 cap | 觸及 → 暫停所有新研究啟動 |
單層防線不足以應付各種失控情境。例如：個人配額無法防止單次研究因 LLM 自迴呼叫工具而 token 暴衝（需引擎內建上限）；引擎上限無法防止整個學校學生同時湧入（需平台日上限）；硬上限無法即時告知管理員問題正在發生（需告警 cron）。多層獨立防線提供「就算其中一層失靈，其他層仍能擋住損害」的容錯保證。
引擎在啟動時根據以下優先序判定使用者角色，決定當日配額：
classroomgpt_teacher）→ 無上限（teacher）classroomgpt_ta）→ 40 次 / 日（ta）採滾動 24 小時視窗，從第一次啟動的時間點往後算 24 小時。每次啟動成功扣 1.0 次（取消時依規則減扣）。
POST /api/deep_research/start — 啟動研究（SSE 串流）POST /api/deep_research/cancel — 取消進行中的研究GET /api/deep_research/quota — 查詢當前配額剩餘GET /api/deep_research/my_tasks — 個人歷程列表GET /api/deep_research/task/<uuid> — 單一 task 詳情| 層級 | 儲存位置 | 內容 |
|---|---|---|
| 1. Task 主表 | deep_research_tasks |
task_uuid、user_question、status、plan_json、final_answer、citations_json、tokens_used、duration_seconds |
| 2. 步驟明細 | deep_research_steps |
每一步的 tool_name、args、result_preview、duration_ms |
| 3. Chat 紀錄 | classroomgpt_my_log |
request 列（學生問題）+ response 列（DR 答案，type='deep_research'），帶 deep_research_task_uuid 外鍵 |
Chat 紀錄的雙列設計有兩個目的：(1) 答案出現在對話歷程中，重整頁面後仍可看見；(2) 後續對話的 LLM context 會帶到研究結論，學生可以基於研究結果繼續深入提問。
研究啟動時，引擎先把 request log 寫入 classroomgpt_my_log（並觸發 Bloom 認知層次分析），SSE 推送 request_log_id 給前端後，前端對該問題泡泡 polling Bloom badge。研究結束時再寫入 response log，並把對話歷程裡的 inline 進度卡就地置換成答案泡泡。重整頁面後從 chat history 重新載入，視覺結果與即時渲染一致。
每次研究的結果頁路徑為 /deep_research/task/<uuid>，可分享給同儕或老師。權限收緊：只有擁有者本人、頻道擁有者、超級助教（Super TA）、平台 admin 能查看，避免敏感的研究內容（含學生個人提問）外流。
/deep_research/my 列出使用者本人所有研究紀錄（含已完成、已取消、失敗），可依狀態與筆數篩選，每筆可點開重看完整答案。
Deep Research 的學生使用資料（task、步驟、答案）皆涵蓋於 Uedu 既有的 IRB 核准（NTU-REC 202507EM058）之內。教師端開啟頻道 DR 開關時，預設遵循該知情同意框架——學生在頻道中使用即視為已同意對話資料納入研究分析。
DR 工具集嚴格遵循 Uedu 平台的資料邊界規範：
search_channel_materials 限定當前頻道）Deep Research 答案的 disclaimer 直接寫在每張答案泡泡裡：「本答案由 AI 整合多個資料來源，請自行核對引用內容；不可直接用於作業繳交」。教師端若擔心學生濫用，可在頻道層級關閉 DR 開關，或在 system prompt 中註明使用規範。
Deep Research 產生的資料可橫跨 EO 框架的多個維度，是少數能同時提供認知、語言、社會三組學習行為訊號的功能：
| Omics 維度 | Deep Research 提供的資料 |
|---|---|
| Cognomics（認知歷程） | 問題的 Bloom 認知層次、子問題拆解模式、ReAct 反思深度 |
| Linguomics（語言表達） | 學生原問題的語言複雜度、答案被進一步追問的模式 |
| Sociomics（社會互動） | 分享連結點擊次數、研究結果在頻道內被討論的擴散 |
| Ethicomics（倫理規範） | 學生對 disclaimer 的回應、是否誤用結果於作業繳交 |
研究者可循 Uedu 既有資料治理流程（簽署研究者責任書、匯出同意書、超級助教 NDA）申請匯出 DR 相關資料。詳見資料匯出與資料治理方法論。
學術論文中若提及本系統，建議引用格式：
Chang, C.-K. (2026). Uedu Deep Research: A ReAct-based multi-step research mode for university learners. Uedu Platform.