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；未推断任何额外功能。