# edurag-plus

**Repository Path**: enough-words/edurag-plus

## Basic Information

- **Project Name**: edurag-plus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduAgent 教育智能体

AI 原生教学辅助系统，面向 IT 教育培训机构，由四个专业 Agent 协同工作。

## 功能特性

### 四大核心 Agent

1. **智能问答 Agent** - 7x24 小时专属助教
   - RAG 链路：Query 理解、检索、重排、生成
   - 默认 BM25 关键词检索；开启 `PUBLIC_KB_EMBEDDING_ENABLED=true` 后可使用 Milvus 向量检索
   - 可选 BGE-Reranker 精排
   - 置信度感知回答
   - 20 条消息上下文窗口
   - 当前对话私有附件问答

2. **试卷批改 Agent** - AI 预批改，教师把关
   - 选择题、填空题、编程题三轨并行批改
   - asyncio.gather 并行执行
   - 知识薄弱点分析
   - 教师确认后发布

3. **简历审查 Agent** - 六维度精准诊断
   - 工作经历、技能匹配、项目描述、量化数据、格式排版、表达规范
   - 三组并行评审
   - 能力雷达图
   - 带原文定位的修改建议

4. **模拟面试 Agent** - 真实面试场景模拟
   - 五阶段状态机：INTRO -> TECH -> PROJECT -> REPORT -> ENDED
   - 动态题目生成
   - 双轨评估：技术深度 + 表达能力
   - 结构化报告

### 多 Agent 串联

- 自动识别复杂意图
- 复杂度评分 1-5 分
- 多 Agent 协作 Pipeline

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | FastAPI |
| Agent 框架 | LangChain + LangGraph 依赖已安装；当前业务主流程由 `backend/app/agents` 直接实现 |
| 大模型 | DeepSeek 兼容 OpenAI Chat Completions API，默认模型 `deepseek-chat` |
| 向量数据库 | Milvus，可通过环境变量启用 |
| 关键词检索 | BM25 |
| 关系数据库 | PostgreSQL |
| 缓存 | Redis 容器已配置，当前业务代码暂未直接连接 Redis |
| 文件存储 | MinIO |
| 前端 | Vue 3 + Element Plus |
| 部署 | Docker Compose |

## 快速开始

### 1. 环境准备

```bash
git clone <repo-url>
cd eduagent
```

后端配置文件从 `backend/.env` 读取。可以先复制根目录模板：

```bash
cp .env.example backend/.env
```

然后编辑 `backend/.env`，至少填入有效的 `DEEPSEEK_API_KEY`。

如果使用 Docker Compose，根目录 `.env` 会被 `docker-compose.yml` 用来展开服务配置，建议也保留一份：

```bash
cp .env.example .env
```

### 2. 启动方式

#### 开发模式

后端：

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

前端：

```bash
cd frontend
npm install
npm run dev
```

开发模式访问地址：

- 前端界面: http://localhost:3000
- 后端 API: http://localhost:8000
- API 文档: http://localhost:8000/docs

#### Docker Compose

当前 `docker-compose.yml` 引用了以下配置文件：

- `docker/nginx/nginx.conf`
- `docker/postgres/init.sql`

当前仓库没有包含 `docker/` 目录时，直接执行 `docker compose up -d` 会失败或导致 Nginx/PostgreSQL 初始化挂载异常。请先补齐这两个文件，或临时移除 `nginx` 服务和 PostgreSQL 初始化挂载后再启动。

```bash
docker compose up -d
```

完整 Compose 部署访问地址：

- Nginx 入口: http://localhost
- 前端容器调试端口: http://localhost:3000
- 后端 API: http://localhost:8000
- API 文档: http://localhost:8000/docs
- MinIO 控制台: http://localhost:9001

### 3. 注册账号

访问前端登录页，切换到“注册”页签，可选择学生或教师角色：

- 开发模式: http://localhost:3000/login
- 完整 Nginx 部署: http://localhost/login

## 项目结构

```text
eduagent/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/             # API 路由
│   │   ├── models/          # 数据库模型
│   │   ├── schemas/         # Pydantic 模型
│   │   ├── services/        # 业务服务
│   │   ├── agents/          # Agent 实现
│   │   ├── graphs/          # 预留 LangGraph 状态图目录
│   │   └── utils/           # 工具函数
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                # 前端应用
│   ├── src/
│   │   ├── api/             # API 调用
│   │   ├── components/      # 组件
│   │   ├── stores/          # 状态管理
│   │   ├── views/           # 页面
│   │   └── router/          # 路由
│   ├── Dockerfile
│   └── package.json
│
├── docs/                    # 项目文档
├── docker-compose.yml       # Docker Compose 编排
└── .env.example             # 环境变量模板
```

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/register` | 用户注册，设置 HttpOnly 认证 Cookie |
| POST | `/api/auth/login` | 用户登录，设置 HttpOnly 认证 Cookie |
| GET | `/api/auth/me` | 当前用户信息 |
| POST | `/api/auth/logout` | 退出登录 |
| POST | `/api/chat/conversations` | 创建对话 |
| POST | `/api/chat/stream` | SSE 流式聊天 |
| POST | `/api/chat/conversations/{id}/attachments` | 上传当前对话附件 |
| POST | `/api/knowledge/documents` | 上传知识库文档，教师/管理员权限 |
| POST | `/api/knowledge/search` | 知识库检索 |
| POST | `/api/exams/submit` | 提交试卷 |
| POST | `/api/resumes/upload` | 上传简历 |
| POST | `/api/interviews/start` | 开始面试 |
| POST | `/api/interviews/{id}/message` | 发送面试回答 |
| GET | `/api/dashboard/overview` | 数据看板 |

## 注意事项

1. **DeepSeek API Key**: 必须在 `backend/.env` 中配置有效的 API Key。
2. **认证方式**: 登录/注册接口返回体中的 `access_token` 为空字符串，真实认证凭据写入 HttpOnly Cookie；前端会自动携带 Cookie，并为非 GET 请求附加 CSRF Token。
3. **检索模式**: 默认 `QA_RETRIEVAL_MODE=keyword`，公共知识库不写 Milvus；如需向量检索，开启 `PUBLIC_KB_EMBEDDING_ENABLED=true` 并确保本地模型和 Milvus 可用。
4. **模型下载**: 首次启用 embedding 或 reranker 时会下载模型，需要网络连接或提前准备本地缓存。
5. **生产部署**: 请修改 `JWT_SECRET_KEY`、数据库密码、MinIO 密钥，并设置 `APP_ENV=production`、`AUTH_COOKIE_SECURE=true`。

## License

MIT