🎓 EduCare 系統現況報告

博幼社會福利基金會 AI 教育平台 — 正常運作功能總覽與架構圖解

架構 React + TypeScript + Vite SPA 規模 ~86,500 行核心程式碼 測試 132 個測試檔案 LLM 7 家 Provider 部署 gh-pages 純靜態

1系統定位與運作模式

EduCare 是完全前端的單頁應用:沒有自建後端,LLM 金鑰存在使用者端,資料走 Turso 雲端同步 + IndexedDB 離線備援。目前穩定運作的是「教學問答、HTML 專案助理、Agent Bundle 分享」三大支柱。

3
核心工作區
(聊天 / HTML 專案 / 備課練習)
7
LLM Provider
Gemini…Groq
61+
服務層模組
services/
9
UI 元件域
components/
10
Playwright E2E
情境腳本
2
持久化層
Turso + IndexedDB

2分層架構圖

由上而下五層:進入點路由 → 工作區 UI → Agent/編排核心 → Provider 適配 → 持久化與平台服務。箭頭為實際匯入方向。

① 進入點與路由 index.tsx掛載 App.tsx AppShell / LayoutviewMode 切換工作區 SharedAssistant?share= 安全連結 BundleImportPage?bundle= 本機載入 Onboarding首次引導 ② 工作區 UI(components/) 💬 教學聊天 chat/ ChatContainer · StreamingResponse RAG 引用卡片 · 語音朗讀 GeometryBoard · 發音按鈕 🛠 HTML 專案 canvas/ HtmlProjectWorkspace FileTree · PreviewFrame AgentRunPanel 進度面板 📝 備課練習 practice/ PracticeWorkspace 練習題建立與作答 workspace 存档整合 📦 助理與 Bundle assistant/ · bundle/ Builder · Editor · Runner ShareModal · 模板選擇 ③ Agent 編排與 RAG 核心(services/) AgentRunController 运行框架 多回合工具迴圈 · 預算/中止控制 Checkpoint 中斷續跑 · 子代理委派 Web Locks 跨分頁互斥 RAG 知識管線 fileParser → 分段 → embedding 向量檢索 + rerank(knowledgeSearch) 背景知識收集 · 引用出處 HTML 專案工具群 靜態驗證(acorn / css-tree) 瀏覽器内 git(isomorphic-git) 預覽 VFS · 執行期錯誤診斷 ④ LLM Provider 適配層(llmAdapter + providers/) Gemini@google/genai OpenAInative + tools Anthropicmessages API OpenRouteropenai 相容 Ollama本地模型 LM Studio本地模型 Groqnative SSE ⑤ 持久化與平台服務 ☁️ Turso DB(libsql)雲端同步 · 跨裝置 🗄 IndexedDB + LightningFS離線備援 · 虛擬檔案系統 🔐 cryptoServiceAES-GCM 端對端加密分享 📴 offlineServiceService Worker · 離線更新
圖 1 · EduCare 五層架構 — 純前端 SPA,無自建後端;Provider 層直連各家 LLM API
聊天工作區 HTML 專案 備課練習 助理/Bundle 雲端 LLM 本地 LLM

3三大運作支柱 — 功能明細

以下功能均有完整服務層實作、單元測試與對應 E2E 腳本保護,判定為「正常運作」。

💬教學問答(RAG)穩定

  • 上傳 PDF / DOCX / MD 教材,智慧分段與 embedding
  • 向量檢索 + reranking,回答附可展開知識出處
  • 背景知識收集(knowledgeGather)不阻塞串流回覆
  • 串流回應、中止控制、思考指示器
  • 聊天歷史自動壓縮(chatCompactor)
  • 語音朗讀、單字發音、幾何圖板
  • 交談 token 用量追蹤(sessionTokenUsage)
knowledgeSearchService · fileParserService · materialDocumentService · ChatContainer

🛠HTML 專案助理穩定

  • 自然語言描述 → agent 規劃、寫檔、改檔
  • 靜態驗證:JS 用 acorn、CSS 用 css-tree
  • 瀏覽器内 git(isomorphic-git)快照與回退
  • 即時預覽 iframe + 執行期錯誤診斷
  • Agent 運行面板:待辦追蹤、進度、回合預算
  • 中斷 checkpoint 續跑、子代理平行委派
  • 需求釐清工具(clarifyTool)
agentRunController · htmlProjectStore · htmlProjectGitService · staticValidationService · htmlPreviewService

📦Agent Bundle 分享穩定

  • 多助理打包為 .educare-bundle.json(prompt + 知識 + 路由表)
  • 接待員 → 專家自動轉接,交接摘要(handoff)
  • schema-v2 密碼加密 provider 設定,僅存記憶體
  • 匯入預覽不洩漏 system prompt / 金鑰
  • QR code、安全連結、離線匯出包
  • 助理套餐可攜(assistantPackageService)
agentBundleService · assistantRoutingService · bundleProviderCredentialsService · cryptoService

📝備課與練習穩定

  • 練習題工作區(PracticeWorkspace)
  • 數學計算工具(mathComputeService)
  • 工作區存档/還原(workspaceArchiveService)
practiceWorkspaceService · workspaceArchiveService · mathComputeService

🔄同步與離線穩定

  • Turso 雲端同步 + IndexedDB 離線 fallback
  • Service Worker 離線 shell 與更新流程
  • 聊天草稿自動暫存(workspaceDraftService)
  • 離線狀態 banner 提示
db.ts · tursoService · offlineService · workspaceDraftService

⚙️設定與金鑰管理穩定

  • 7 家 provider 逐使用者金鑰(免 env)
  • 「僅此分頁」session 金鑰,關頁即清
  • provider 設定加密分享/匯入檔案
  • 外觀主題設定、外觀偏好
apiKeyManager · providerRegistry · providerSettingsShareService

4RAG 教學問答 — 資料流

從教材上傳到附引用回答的完整管線,目前在線上運作的實際路徑。

教材上傳 PDF · DOCX · MD documentParser 分段 + Hash textChunkingService 重疊視窗控 token Embedding HuggingFace transformers.js 檢索 + 重排 向量搜尋 → rerank 背景收集不阻塞串流 串流生成 context 注入 prompt 引用出處可展開 查詢 query embedding 知識庫持久化(IndexedDB / Turso)
圖 2 · RAG 管線 — 上傳到附引用回覆;檢索層於背景執行,不拖慢首字延遲

5HTML 專案 Agent — 運行迴圈

AgentRunController 是運作框架的核心:規劃 → 授權工具 → 執行 → 驗證 → 回報,每步可回退、可中斷續跑。

Agent Run 回合預算 maxTurns AbortSignal · 跨分頁鎖 ① 規劃 setProjectTodos ② 編輯檔案 writeFiles / replace ③ 靜態驗證 acorn · css-tree ④ git 快照 isomorphic-git ⑤ 預覽診斷 iframe + runtime errors ⑥ 回報/回退 gitLog · revert 工具迴圈 ×N 回合 ⏸ 中斷 → Checkpoint 存檔 → 續跑(預算/副作用需使用者確認) 🤝 可委派 1–4 個子代理平行執行,每批最多一個寫入任務
圖 3 · Agent Harness 運行迴圈 — 「每步可回退」由瀏覽器内 git 保證,驗證失敗先修復再提交

6分享與交接拓撲

基金會師生跨裝置、跨班級使用同一套助理,有四條分享路徑,全部走端對端加密或純本機載入。

老師的 EduCare 助理 + 教材 + provider 設定 🔗 安全連結 ?share= AES-GCM 加密 · 金鑰在 #fragment 📱 QR Code classroom 掃碼即開 📦 離線匯出包 zip · 無網路也能搬資料 .educare-bundle.json 多助理 + 路由表(預設不含金鑰) schema-v2 加密設定 密碼另渠道交付 · 僅存記憶體 學生端 BundleRunner 接待員 → 專家轉接 + 交接摘要
圖 4 · 四條分享路徑 — 左側為連結/檔案分享,右側為 Bundle 匯入與運行;金鑰預設不隨 bundle 流轉

7品質保障現況

測試金字塔扎實:services 層幾乎一比一附測試,另有四組 Playwright 配置覆蓋功能、UI/UX、離線情境。

E2E Playwright ×10 腳本 整合測試 ChatContainer · BundleRunner · bundle DB Vitest 單元測試 ×132 檔 agentRun · git · store · RAG · provider 全覆盖 pnpm quality = typecheck + lint + format + test
圖 5 · 測試金字塔 — husky + lint-staged 提交前攔截
E2E 配置涵蓋情境
functionality-*agent 運行、備課練習、搜尋 RAG、分享、工作區
offline-shell / update離線載入 shell、離線更新流程
api-setup-chat金鑰設定到首次對話
uiux / 性能腳本側欄導航、主題對比、性能量測
model-comparison多模型評測(獨立實驗軌)

8部署與運行模式

🌐gh-pages 靜態部署

  • pnpm run deploy 一鍵發布
  • 無伺服器成本,符合基金會資源

🔒HTTPS 開發模式

  • pnpm run dev:https
  • HTML 專案沙箱需 secure context

🖥全本地推理

  • Ollama / LM Studio 走本機 API
  • 偏鄉無外網也能跑教學

🗝金鑰零伺服端

  • 金鑰只存瀏覽器(session 預設)
  • Bundle 預設不含憑證