jin-zi-xuan/kaobuddy-pwa

📚 KaoBuddy – AI 驅動的考試備考工作區（PWA）

是什麼

• 一個你可在本地執行（或自行部署）的網頁應用，當你只剩幾天時間準備考試時非常實用。你只需上傳所有學習資料——PDF、DOCX、掃描的手寫筆記、B 站影片字幕等——內建 AI 會提取關鍵概念，建立學習卡片，產生練習題，建構模擬考試，甚至提供「臨考衝刺卡片」模式。

為何存在

• 大多數學習工具假設你有數週或數月時間來整理知識庫。KaoBuddy 則假設相反：你距離考試僅剩幾天，需要一種快速方式將雜亂無章的檔案堆轉化為結構化、可學習的計畫。

核心功能

功能	作用
AI 驅動的知識提取	解析上傳的 PDF、DOCX、RTF、純文字、手寫筆記圖片以及 B 站影片字幕。AI 識別與考試相關的 知識要點（例如「死結」、「銀行家演算法」），分配難度／重要性，並記錄來源句子。
每日學習計畫	基於考試日期、可用學習時間、目標分數和識別出的弱點，生成逐日計畫。未完成項目會自動順延。
互動式學習模組	面對每個知識要點，可查看面向初學者的解釋，產生 3+ 題練習題，或建立 4–6 張不同類型的閃卡（概念、錯誤、考試、快速記憶）。
模擬考試產生器	可自訂長度和題型。AI 從你自己的材料中產生試卷，自動評分（選擇題、簡答題），還能幫你答題以供對比。
臨考衝刺閃卡模式	將知識要點濃縮為簡潔卡片，包含核心概念、記憶口訣、典型出題角度和常見陷阱——非常適合最後一天使用。
錯題本	模擬考試中的錯題會被保存，按嚴重程度標記，可後續回顧。
離線優先資料儲存	所有使用者資料（專案、檔案、計畫、卡片、考試結果）均儲存在瀏覽器的 IndexedDB 中；透過 JSON 備份／還原可在裝置間遷移。API 金鑰儲存在 localStorage，不會包含在備份中。
無帳號／無雲同步	隱私優先：除非你選擇自架後端，否則所有資料都保留在本地。

AI 整合

• 支援任何 OpenAI 相容服務。預設設定包括 DeepSeek、Kimi（CN/國際版）和 OpenAI GPT-5.5/mini。你提供自己的 API 金鑰（BYOK），或若有邀請碼，可使用托管配額。
• 兩種請求模式：純文字（適用於無視覺能力的模型）和視覺增強（適用於掃描 PDF 或手寫影像）。後端將金鑰和相關內容轉發給模型；不會持久化金鑰。

如何開始

1. Windows – 從 Releases 頁面下載 zip，解壓後執行 start-kaobuddy.bat。它將啟動本地伺服器（http://127.0.0.1:8000）。
2. macOS – 執行 open-kaobuddy.command 指令碼（需 Python 3 + Node LTS）。目前尚未提供簽署二進位檔。
3. 從原始碼（任意系統） – 安裝 Python 3 和 Node 後：

   npm install
   npm run dev   # 啟動 FastAPI 後端（8000）和 Vite 開發伺服器（5173）
   

4. 自行部署 – 包含 Dockerfile、Fly.io、Railway 和 DEPLOY.md 指南。容器執行 FastAPI 後端並提供建構好的 React 應用。

技術堆疊

• 前端：React 19 + TypeScript，Vite 6，Framer-Motion，Phosphor 圖示，Service Worker + Web Manifest（PWA）。PDF 處理由 pdfjs-dist，匯出使用 jspdf/html2canvas。
• 後端：FastAPI + Uvicorn（非同步，SSE 流式傳輸），httpx 用於 OpenAI 相容呼叫。
• 資料：瀏覽器 IndexedDB + localStorage（用於金鑰）。
• 打包：多階段 Docker（node → python），GitHub Actions CI（類型檢查、pytest、前端測試、建構驗證）。
• 許可證：MIT。

適合對象

• 面臨即將到來的考試、手頭有散亂的數位／掃描資料，需要快速 AI 輔助整理的學生。
• 想要一個現成的 AI 增強文件處理、規劃與閃卡產生 PWA 範例的開發者。

---

以上所有細節均直接來自倉儲的 README；未推斷任何額外功能。