# EduAgent

**Repository Path**: rr84/edu-agent

## Basic Information

- **Project Name**: EduAgent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduAgent

<div align="center">

**AI 驱动的教育平台，将课程材料转化为交互式学习工具**

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.117+-green.svg)](https://fastapi.tiangolo.com/)
[![React](https://img.shields.io/badge/React-19-blue.svg)](https://react.dev/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

---

EduAgent 是一个 AI 驱动的教育平台，利用 **RAG（检索增强生成）** 和 **LangGraph** 智能体，将静态文档转化为个性化 AI 导师。上传课程材料，自动生成测验、闪卡、思维导图和学习计划。

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [前置条件](#前置条件)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [API 文档](#api-文档)

## 功能特性

- **📂 项目管理** — 以项目为单位组织课程，集中管理文档、对话和学习材料
- **🤖 AI 对话导师** — 基于 LangGraph ReAct 智能体，主动生成测验、闪卡、笔记
- **📄 文档智能处理** — 上传 PDF/DOCX/TXT/RTF，Docling + Tesseract 本地提取文字
- **🔍 语义搜索 (RAG)** — 基于 pgvector 向量检索，精确定位文档内容
- **📝 自动生成测验** — 从文档生成选择题，自动评分并追踪进度
- **🎴 闪卡** — 一键将文本转为闪卡，支持主动回忆学习法
- **🗺️ 思维导图** — AI 生成可视化知识图谱
- **🧠 个性化学习计划** — 根据答题表现识别薄弱环节（正确率 < 70%），生成定制计划

## 技术栈

### 后端

- **[FastAPI](https://fastapi.tiangolo.com/)** — Web 框架
- **[LangGraph](https://www.langchain.com/langgraph)** — AI 智能体编排
- **[PostgreSQL](https://www.postgresql.org/) + pgvector** — 数据库 + 向量检索
- **[DeepSeek](https://platform.deepseek.com/)** — 对话 LLM（deepseek-chat）
- **[Gemini Embedding](https://ai.google.dev/)** — 向量嵌入（gemini-embedding-001，免费 1500次/天）
- **[Docling](https://github.com/docling-project/docling)** — 本地文档解析（PDF/DOCX/PPTX 等）
- **[Tesseract OCR](https://github.com/tesseract-ocr/tesseract)** — 扫描件文字识别
- **[Azurite](https://github.com/Azure/Azurite)** — 本地 Azure Storage 模拟器（Blob + Queue）
- **[Supabase](https://supabase.com/)** — 用户认证

### 前端

- **[React 19](https://react.dev/)** + **[TypeScript](https://www.typescriptlang.org/)**
- **[Vite](https://vitejs.dev/)** + **[TailwindCSS](https://tailwindcss.com/)**
- **[TanStack Router](https://tanstack.com/router)** + **[Effect Atom](https://github.com/tim-smart/effect-atom)**
- **[Radix UI](https://www.radix-ui.com/)** + **[shadcn/ui](https://ui.shadcn.com/)**

## 前置条件

- **Python 3.12+** — [下载](https://www.python.org/downloads/)
- **Node.js 18+** — [下载](https://nodejs.org/)
- **pnpm** — `corepack enable && corepack prepare pnpm@latest --activate`
- **uv** — [安装](https://docs.astral.sh/uv/)
- **Docker Desktop** — [下载](https://docs.docker.com/get-docker/)
- **Tesseract OCR** — `winget install UB-Mannheim.TesseractOCR`
- **Poppler** — `winget install oschwartz10612.Poppler`（PDF 渲染）

### API 密钥

- **DeepSeek API Key** — https://platform.deepseek.com/
- **Gemini API Key** — https://aistudio.google.com/apikey（免费 1500次/天）
- **Supabase 项目** — https://supabase.com/（免费层）

## 快速开始

```bash
# 1. 克隆仓库
git clone <your-repo-url>
cd edu-agent

# 2. 安装 Python 依赖
uv sync

# 3. 安装前端依赖
cd src/edu-web && pnpm install && cd ../..

# 4. 创建 .env 文件（参考下方配置说明）

# 5. 启动 Docker 服务（PostgreSQL + Azurite）
docker run -d --name edu-db -p 5432:5432 \
  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
  pgvector/pgvector:pg16

docker run -d --name edu-azurite \
  -p 11000:10000 -p 10001:10001 -p 10002:10002 \
  mcr.microsoft.com/azure-storage/azurite

# ⚠️ Azurite Blob 使用 11000 端口（避免与百度网盘冲突）

# 6. 运行数据库迁移
uv run alembic upgrade head

# 7. 启动后端（两个终端）
# 终端 A — API
uv run --package edu-api python src/edu-api/main.py

# 终端 B — Worker
uv run --package edu-worker python src/edu-worker/main.py

# 8. 启动前端（终端 C）
cd src/edu-web && pnpm dev
```

访问 `http://localhost:3000` 使用前端，`http://localhost:8000` 查看 API 文档。

## 配置说明

项目根目录创建 `.env` 文件：

```env
# 数据库
DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/postgres

# DeepSeek（对话 LLM）
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat

# Gemini Embedding（免费 1500次/天）
GEMINI_API_KEY=your-gemini-key

# Azure Storage（本地 Azurite 模拟器）
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:11000/devstoreaccount1;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;
AZURE_STORAGE_QUEUE_NAME=ai-generation-tasks
AZURE_STORAGE_INPUT_CONTAINER_NAME=input
AZURE_STORAGE_OUTPUT_CONTAINER_NAME=output

# Supabase 认证
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret

# 用量限制
MAX_DOCUMENT_UPLOADS_PER_DAY=999
MAX_QUIZ_GENERATIONS_PER_DAY=100
MAX_FLASHCARD_GENERATIONS_PER_DAY=100
MAX_CHAT_MESSAGES_PER_DAY=100
```

前端 `src/edu-web/.env`：

```env
VITE_SERVER_URL=http://localhost:8000
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
```

> **注意**：前端 `.env` 的 `VITE_*` 变量也会在项目根目录 `.env` 中读取（Vite 配置了 `envDir: '../../'`）。

## 项目结构

```
edu-agent/
├── src/
│   ├── edu-api/            # FastAPI 后端
│   ├── edu-worker/         # 后台 Worker（队列/AI 处理）
│   ├── edu-web/            # React 前端
│   └── shared/
│       ├── ai/             # LangGraph 智能体、工具、提示词
│       ├── core/           # 核心业务逻辑、Schemas、Key Vault
│       ├── db/             # ORM 模型、Alembic 迁移
│       └── queue/          # Azure Queue 消息类型
├── deploy/azure/           # Azure 部署配置（Terraform）
├── docs/                   # 文档
├── alembic.ini             # Alembic 配置
├── pyproject.toml          # uv workspace 定义
├── ruff.toml               # Python Lint/Format 配置
└── .env.example            # 环境变量模板
```

## 开发指南

### 后端

```bash
# 安装依赖
uv sync

# Lint / 格式化
ruff format .
ruff check .
ruff check --fix .

# 数据库迁移
uv run alembic revision --autogenerate -m "描述"
uv run alembic upgrade head

# 启动 API
uv run --package edu-api python src/edu-api/main.py

# 启动 Worker
uv run --package edu-worker python src/edu-worker/main.py
```

### 前端

```bash
cd src/edu-web

pnpm dev          # 开发服务器（:3000）
pnpm build        # 生产构建
pnpm lint         # ESLint
pnpm format       # Prettier
pnpm test         # Vitest
pnpm type-check   # TypeScript 类型检查
pnpm gen:client   # 从 API 生成 TS 类型
```

## API 文档

启动后端后：

- **Scalar UI（OpenAPI）**: `http://localhost:8000/`
- **健康检查**: `http://localhost:8000/health`
- **OpenAPI Schema**: `http://localhost:8000/openapi.json`

## 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

<div align="center">

Made with ❤️ for students and educators

</div>