# python-1-教育助手AI agent

**Repository Path**: sanxiadaer/python1

## Basic Information

- **Project Name**: python-1-教育助手AI agent
- **Description**: 基于 Web 端的教育助手 AI Agent
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教育AI助手（Edu AI Assistant）

一个面向学生的全栈教育 AI 助手平台：围绕“学—练—问—计划”提供知识点总结、习题生成与在线批改、错题本、AI 多轮对话（结合知识库检索增强）、个性化学习计划等功能，包含学生端和管理员端。

## 技术栈

### 前端
- Vue 3 + TypeScript + Vite
- Pinia（状态管理）
- Vue Router（路由）
- Element Plus（UI 组件库）
- markdown-it + KaTeX（Markdown 与公式渲染）
- Axios（HTTP 请求）

### 后端
- Python 3.10+ + FastAPI + Uvicorn
- SQLAlchemy 2.0（ORM，SQLite）
- PyJWT + bcrypt（认证与密码加密）
- DeepSeek API（AI 大模型，openai SDK 接入）
- SQLite FTS5（知识库全文检索，RAG 检索增强）

## 项目结构

```
edu_AI_project/
├── backend/                     # Python 后端
│   ├── app/
│   │   ├── main.py              # 入口：CORS、统一 /api 前缀、错误格式、启动建表
│   │   ├── config.py            # 环境变量配置（.env，pydantic-settings）
│   │   ├── database.py          # SQLAlchemy 引擎、Session、get_db 依赖
│   │   ├── models.py            # 数据模型（12 张表 + EpochMillis 时间类型）
│   │   ├── schemas.py           # Pydantic 请求体校验
│   │   ├── security.py          # bcrypt 密码哈希 + JWT 签发/校验
│   │   ├── deps.py              # get_current_user / require_admin / get_or_404
│   │   ├── serialize.py         # 模型转 dict（时间转 ISO 字符串）
│   │   ├── services/
│   │   │   ├── ai_service.py    # DeepSeek 封装（知识点总结/习题生成/学习计划）
│   │   │   └── rag_service.py   # 文档分片 + FTS5 全文检索
│   │   └── routers/
│   │       ├── auth.py          # 注册/登录/个人中心
│   │       ├── subjects.py      # 学科
│   │       ├── knowledge.py     # 知识点总结
│   │       ├── exercises.py     # 习题生成/批改/错题本
│   │       ├── chat.py          # AI 对话（含 RAG）
│   │       ├── plans.py         # 学习计划
│   │       ├── rag.py           # 知识库文档上传/检索
│   │       └── admin.py         # 管理后台
│   ├── data/dev.db              # SQLite 数据库
│   ├── seed.py                  # 初始化管理员 + 预设学科（幂等）
│   ├── run.py                   # 启动脚本
│   ├── requirements.txt
│   └── .env.example
├── frontend/                    # Vue3 前端
│   ├── dist/                    # 构建产物（需 npm run build 生成）
│   ├── src/
│   │   ├── views/student/       # 学科选择/首页/知识点/在线做题/错题本/AI对话/学习计划/知识库
│   │   ├── views/admin/         # 登录/数据概览/用户/学科/知识点/习题/系统设置
│   │   ├── api/                 # API 接口封装
│   │   ├── stores/              # Pinia 状态（user / exercise）
│   │   ├── router/              # 路由配置 + 导航守卫
│   │   ├── components/          # 公共组件（StudentLayout / UserProfileDialog）
│   │   ├── constants/           # 常量（题型难度映射、协议文案）
│   │   └── utils/               # 工具（公式渲染、时间格式化）
│   ├── package.json
│   └── vite.config.ts           # /api 代理 → localhost:3000
└── README.md
```

## 功能模块

### 学生端
1. **注册登录** — 用户名+密码，bcrypt 加密，JWT 鉴权；支持头像、绑定手机号、修改密码
2. **学科选择** — 10 个预设学科 + 自定义学科
3. **知识点总结** — AI 生成结构化总结（概述/要点/难点/公式/定义/例题），支持历史、删除与导出 Markdown
4. **习题生成与批改** — 按知识点/题型（选择/填空/判断/简答）/难度生成，在线作答自动批改，错题自动进错题本
5. **错题本** — 自动收录、错误次数统计、重做、手动添加/移除、按学科/题型筛选
6. **AI 对话** — 多轮对话，结合学科上下文与知识库检索（RAG），支持重新生成、清空历史
7. **学习计划** — 输入目标/时间/时长，AI 生成分阶段计划，每日打卡，进度跟踪
8. **知识库** — 上传 PDF/TXT/MD/CSV 学习资料，FTS5 全文索引，检索增强问答

### 管理员端
1. **用户管理** — 查看用户、禁用/启用、重置密码、删除（级联清理）
2. **学科管理** — 添加/编辑/删除学科
3. **知识点管理** — 状态管理（草稿/已发布/已审核）、删除
4. **习题管理** — 查看、删除
5. **AI 调用统计** — 调用量、Token 消耗、成功率、模块分布
6. **系统设置** — AI 模型参数、每日调用上限、公告

## 快速开始

### 前置要求
- Python >= 3.10
- Node.js >= 18（仅前端需要）
- DeepSeek API Key（https://platform.deepseek.com 申请）

### 1. 后端启动

```bash
cd backend

# 创建并激活虚拟环境（可选但推荐）
python -m venv venv
# Windows: venv\Scripts\activate    Linux/macOS: source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
copy .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

# 创建数据目录（SQLite 不会自动创建父目录，首次运行必需）
mkdir data

# 初始化数据（管理员账号 + 10 个预设学科，幂等可重复执行）
python seed.py

# 启动服务
python run.py
# 或: uvicorn app.main:app --reload --port 3000
```

后端默认运行在 `http://localhost:3000`，所有接口前缀 `/api`。

**默认管理员账号：** `admin` / `admin123`

### 2. 前端启动

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端默认运行在 `http://localhost:5173`，已配置代理将 `/api` 转发到后端。

### 3. 访问

- 学生端：http://localhost:5173
- 管理员登录：http://localhost:5173/#/admin/login

## 环境变量说明（backend/.env）

| 变量 | 说明 | 默认值 |
|------|------|--------|
| PORT | 后端端口 | 3000 |
| DATABASE_URL | SQLite 数据库连接串 | sqlite:///./data/dev.db |
| JWT_SECRET | JWT 签名密钥 | - |
| JWT_EXPIRES_IN | Token 过期时间 | 7d |
| DEEPSEEK_API_KEY | DeepSeek API 密钥 | - |
| DEEPSEEK_BASE_URL | API 地址 | https://api.deepseek.com |
| DEEPSEEK_MODEL | 使用模型 | deepseek-chat |
| DAILY_AI_LIMIT | 每日 AI 调用上限 | 100 |

## API 接口概览

### 认证
- `POST /api/auth/register` — 注册（返回用户信息与 JWT）
- `POST /api/auth/login` — 登录
- `GET /api/auth/me` — 获取当前用户
- `PUT /api/auth/avatar|phone|password` — 头像/手机号/密码

### 学科
- `GET /api/subjects` — 获取学科列表
- `POST /api/subjects/custom` — 创建自定义学科
- `GET /api/subjects/{id}` — 学科详情

### 知识点
- `POST /api/knowledge/summary` — 生成知识点总结
- `GET /api/knowledge/list` — 历史列表
- `GET /api/knowledge/{id}` — 详情
- `PUT /api/knowledge/{id}/favorite` — 收藏/取消收藏
- `DELETE /api/knowledge/{id}` — 删除

### 习题
- `POST /api/exercises/generate` — 生成习题
- `POST /api/exercises/submit` — 提交答案批改
- `GET /api/exercises/wrong` — 错题本
- `POST /api/exercises/wrong/add`、`DELETE /api/exercises/wrong/{id}` — 手动添加/移除错题

### 对话
- `POST /api/chat` — 发送消息（多轮 + RAG 检索增强）
- `GET /api/chat/history`、`DELETE /api/chat/history` — 历史/清空
- `POST /api/chat/regenerate` — 重新生成

### 知识库
- `POST /api/rag/upload` — 上传文档（PDF/TXT/MD/CSV）
- `GET /api/rag/documents`、`DELETE /api/rag/documents/{id}` — 文档列表/删除
- `POST /api/rag/search` — 检索

### 学习计划
- `POST /api/plans/generate` — 生成计划
- `GET /api/plans/current`、`GET /api/plans/list` — 当前/历史计划
- `PUT /api/plans/{id}/progress` — 每日打卡进度
- `DELETE /api/plans/{id}` — 删除计划

### 管理端（需 admin 角色）
- `GET /api/admin/users`、`PUT /api/admin/users/{id}/status|password`、`DELETE /api/admin/users/{id}`
- `GET|POST|PUT|DELETE /api/admin/subjects`
- `GET /api/admin/stats` — AI 调用统计
- `GET|PUT|DELETE /api/admin/knowledge`、`GET|DELETE /api/admin/exercises`
- `GET|PUT /api/admin/settings` — 系统设置

### 其他
- `GET /api/health` — 健康检查

## 生产部署

```bash
# 后端
cd backend
pip install -r requirements.txt
python seed.py
uvicorn app.main:app --host 0.0.0.0 --port 3000 --workers 2

# 前端（需 npm run build 构建 dist）
cd frontend
npm run build
# 将 dist 部署到 Nginx，并将 /api 反向代理到后端 3000 端口
```

## 注意事项

1. **API Key 安全**：`.env` 文件包含密钥，不要提交到 Git 仓库。
2. **FTS5 虚拟表**：`document_chunk_fts` 是 SQLite 原生全文索引表，不属于 ORM 管理，删除文档/用户时需用原生 SQL 同步清理，不要手动删除该表。
3. **错误格式**：接口统一返回 `{statusCode, message, error}`，前端 request 拦截器依赖 `message` 字段提示错误。
4. **AI 输出**：DeepSeek 返回的 JSON 可能偶尔不规范，后端已做容错解析（提取 JSON 块兜底）。
5. **AI 调用**：每次调用记录 AiCallLog（模块/成功/Token），默认每日上限 100 次（DAILY_AI_LIMIT），管理端可查看统计。
6. **功能范围**：当前版本聚焦“学—练—问—计划”闭环，不含思维导图功能；知识点总结输出为结构化文本。