# TeachAgent - 智能教育助手平台

AI 驱动的个性化学习平台，支持教师创建 AI Agent、管理知识库，学生通过对话式交互进行学习。

## 功能特性

- **教师端**：创建/管理 AI Agent、知识库管理、学生管理、分发链接、工作流编辑
- **学生端**：与 AI Agent 对话、代码执行、3D 可视化、思维导图
- **RAG 系统**：基于 Elasticsearch 的向量检索 + 重排序
- **流式对话**：SSE 实时流式输出
- **插件系统**：代码执行（CodeMirror）、3D 可视化（Plotly）、思维导图（markmap）

## 项目结构

```
teachagent/
├── ELASTIC/                   # Elasticsearch 容器（独立部署）
│   └── Dockerfile
├── teachagent-app/            # 主应用
│   ├── app.py                 # Flask 入口
│   ├── config.py              # 配置
│   ├── requirements.txt       # Python 依赖
│   ├── Dockerfile             # 应用容器
│   ├── .env                   # 环境变量
│   ├── modules/               # 后端模块
│   │   ├── auth/              # 认证（JWT + 密码/邮箱/手机登录）
│   │   ├── agent_builder/     # Agent 构建
│   │   ├── code_executor/     # Python 代码执行
│   │   ├── knowledge_base/    # RAG 知识库（检索/重排/生成）
│   │   └── visualization/     # 3D 可视化 + 思维导图
│   ├── frontend/              # React 源码（开发用）
│   │   ├── src/
│   │   ├── package.json
│   │   └── vite.config.js
│   ├── static/dist/           # React 构建产物（生产环境前端）
│   ├── agents/                # Agent JSON 配置存储
│   ├── uploads/               # 用户上传文件
│   └── _archive/              # 旧版 Flask 模板归档
└── docker-compose.yml         # 两容器编排
```

## 部署方式

### 方式一：本地开发

适合开发调试，前后端分离运行。

```bash
# 1. 启动 Elasticsearch（Docker 或本地安装）
docker run -d --name es -p 9200:9200 \
  -e discovery.type=single-node \
  -e xpack.security.enabled=false \
  elasticsearch:9.3.3

# 2. 启动 Flask 后端
cd teachagent-app
pip install -r requirements.txt
FLASK_ENV=development python app.py
# 后端运行在 http://localhost:7860

# 3. 启动 React 前端（开发模式，带热更新）
cd frontend
npm install
npm run dev
# 前端运行在 http://localhost:3000，API 请求代理到 7860
```

**本地开发特点**：
- 前端 `localhost:3000`，后端 `localhost:7860`，通过 Vite 代理转发 API
- SSE 流式输出需要直连后端（绕过 Vite 代理）
- `FLASK_ENV=development` 开启 debug 模式和热重载
- 修改前端代码即时生效（HMR）

### 方式二：云端容器部署（生产环境）

两个容器，一个端口。

```bash
# 在项目根目录（包含 docker-compose.yml 的目录）
docker-compose up -d

# 或分别构建
docker-compose build
docker-compose up -d
```

**生产环境特点**：
- 单端口 `7860`：Flask 同时托管 API 和 React 静态文件
- 无跨域问题：前端和 API 同源
- SSE 流式直连：不经过代理，实时输出
- gunicorn 多 worker 运行，性能更好
- ES 通过 Docker 网络互通（`http://elasticsearch:9200`）

### 方式三：HuggingFace Spaces 部署

适用于 HuggingFace Spaces 平台。

1. 将 `teachagent-app/` 作为 Space 仓库
2. ES 单独部署为另一个 Space（`ELASTIC/`）
3. `.env` 中配置 `ELASTICSEARCH_URL=https://your-es-space.hf.space`

## 环境变量说明

| 变量 | 说明 | 示例 |
|------|------|------|
| `ELASTICSEARCH_URL` | Elasticsearch 地址 | `http://localhost:9200` 或 `https://xxx.hf.space` |
| `API_KEY` | SiliconFlow API Key（Embedding/Rerank） | `sk-xxx` |
| `BASE_URL` | SiliconFlow API 地址 | `https://api.siliconflow.cn/v1` |
| `STREAM_API_KEY` | DeepSeek API Key（对话生成） | `sk-xxx` |
| `STREAM_BASE_URL` | DeepSeek API 地址 | `https://api.deepseek.com/v1` |
| `STREAM_MODEL` | 对话模型 | `deepseek-chat` |
| `SECRET_KEY` | Flask Session 密钥 | 随机字符串 |
| `JWT_SECRET` | JWT 签名密钥 | 随机字符串 |
| `FLASK_ENV` | 运行环境 | `development` 或 `production` |

## 跨域与 HTTPS

### 生产环境（推荐）

- **无跨域问题**：前端构建产物由 Flask 直接托管，前端和 API 同源（同一个端口 7860）
- **HTTPS**：由反向代理（Nginx/Cloudflare/HuggingFace Spaces）统一处理 SSL 终止，Flask 本身只需 HTTP
- **SSE 流式**：同源直连，无需代理，数据实时到达

### 本地开发

- **跨域**：Vite 代理 (`localhost:3000` → `localhost:7860`) 处理 API 请求，SSE 直连后端
- **HTTPS**：本地开发无需 HTTPS，全部 HTTP
- **注意**：HTML 中不要加 `upgrade-insecure-requests` meta 标签（已移除）

### 带 HTTPS 反向代理部署

如果在自有服务器上通过 Nginx 反向代理：

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # SSE 流式输出必须的配置
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        chunked_transfer_encoding on;
    }
}
```

关键配置：`proxy_buffering off` 确保 SSE 数据不被 Nginx 缓冲。

## 演示账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 教师 | teacher | 123456 |
| 学生 | student1 | 123456 |

也可通过注册页面创建新账号。

## 技术栈

| 层 | 技术 |
|----|------|
| 前端 | React 19 + Vite + Ant Design 5 + TailwindCSS + Redux Toolkit |
| 后端 | Flask + gunicorn |
| 数据库 | Elasticsearch 9.x（向量检索） + SQLite（用户管理） |
| AI | DeepSeek（对话） + SiliconFlow（Embedding/Rerank） |
| 部署 | Docker + docker-compose |