DEVELOPMENT_CHECKLIST.md

# TeachAgent 新前端迁移开发清单

> 本文档记录从旧版 Flask 模板前端迁移到新版 React 前端的完整开发任务。
> 更新日期：2026-04-13

---

## 一、项目架构概览

| 层级 | 技术栈 | 端口 |
|------|--------|------|
| 新前端 | React 19 + Vite + Ant Design + TailwindCSS + Redux | 3000 |
| 旧前端 | Flask Jinja2 + Bootstrap 5 + 原生JS | 7860（与后端同源） |
| 后端 API | Flask + Blueprint | 7860 |
| 数据库 | Elasticsearch 9.3.3 (向量+文档) + SQLite (用户) | 9200 |
| AI 服务 | SiliconFlow (Embedding/Rerank) + DeepSeek (Chat) | 外部API |

---

## 二、迁移状态总览

### 已完成模块

| 模块 | 新前端文件 | 状态 | 备注 |
|------|-----------|------|------|
| 登录 | `LoginPage.jsx` | ✅ 完成 | 邮箱/手机/密码三种方式 |
| 注册 | `RegisterPage.jsx` | ✅ 完成 | 用户名+密码 |
| 路由保护 | `ProtectedRoute.jsx` | ✅ 完成 | JWT + 角色校验 |
| 教师 Dashboard | `teacher/Dashboard.jsx` | ✅ 完成 | 统计卡片、快速入门 |
| Agent 列表 | `teacher/AgentList.jsx` | ✅ 完成 | CRUD、分发链接、详情查看 |
| Agent 创建 | `teacher/CreateAgent.jsx` | ✅ 完成 | 4步向导、AI工作流生成 |
| 工作流编辑器 | `components/common/WorkflowEditor.jsx` | ✅ 完成 | React Flow 可视化 |
| 知识库管理 | `teacher/KnowledgeBase.jsx` | ⚠️ 基本完成 | 缺批量上传、拖拽 |
| 学生管理 | `teacher/StudentManagement.jsx` | ✅ 完成 | CRUD、密码重置、进度 |
| 学生门户 | `student/StudentPortal.jsx` | ✅ 完成 | Agent列表、Token验证、活动记录 |
| Agent 对话 | `student/AgentChat.jsx` | ⚠️ 部分完成 | 流式对话可用，插件系统缺失 |
| 打字机 Hook | `hooks/useTypewriter.js` | ✅ 已实现 | 未接入使用 |

### 未实现模块

| 模块 | 旧版位置 | 优先级 |
|------|----------|--------|
| 代码执行插件（对话内嵌） | `student.html` 侧面板 | P0 |
| 3D 可视化插件（对话内嵌） | `student.html` 侧面板 | P1 |
| 思维导图插件（对话内嵌） | `student.html` 侧面板 | P1 |
| 独立代码执行页 | `code_execution.html` | P1 |
| Token 直接访问入口（登录页） | `login.html` | P2 |

---

## 三、关键 BUG 与问题

### 3.1 流式输出 SSE 实现问题（P0）

**当前实现**: `AgentChat.jsx` 使用 `fetch` + `ReadableStream reader` 手动解析 SSE

**后端发送格式**:
```
data: {"type": "start", "plugins": [...], "references": [...]}
data: {"type": "content", "content": "文本片段"}
data: {"type": "metadata", "content": {...}}
data: {"type": "done"}
```

**问题清单**:

| # | 问题 | 严重度 | 说明 |
|---|------|--------|------|
| 1 | `metadata` 事件未处理 | 中 | 前端只处理 start/content/done，metadata 被忽略 |
| 2 | 无 `error` 事件类型 | 高 | 后端出错时直接断流，前端会一直卡在"思考中" |
| 3 | `[DONE]` 哨兵检测无效 | 低 | 前端检查 `[DONE]` 但后端从不发送此标记 |
| 4 | 流结束时 buffer 未清空 | 中 | 如果流在 `\n\n` 结尾，最后一个事件可能丢失 |
| 5 | 断流时无 JSON 恢复 | 中 | 连接中断时 partial JSON 直接丢失 |
| 6 | 无超时/重连机制 | 中 | 网络波动时前端无法恢复 |

**建议重构方向**:
- 后端增加 `type: "error"` 事件
- 前端增加 metadata 事件处理
- 添加流超时检测（如 30s 无数据则提示）
- 清理无用的 `[DONE]` 检查

### 3.2 API 路径不一致（P0）

| 前端调用 | 后端实际路径 | 问题 |
|----------|-------------|------|
| `axios.post('/api/verify_token')` (AgentChat.jsx:84) | `/api/verify_token` | axios baseURL 是 `/api`，实际请求变成 `/api/api/verify_token`（双重前缀）|
| `getProgress(taskId)` → `/knowledge/progress/${taskId}` | `/api/progress/${taskId}`（在 app.py 主路由） | 路径不在 knowledge blueprint 下 |
| `getDistributions(agentId)` → `/agent/${agentId}/distributions` | 后端未实现此端点 | 404 |
| `authService.refreshToken()` → `/auth/refresh` | 后端未实现 | 404 |
| `authService.getCurrentUser()` → `/auth/me` | 后端未实现 | 404 |
| `authService.changePassword()` → `/auth/change_password` | 后端未实现 | 404 |

### 3.3 其他前端问题

| # | 问题 | 位置 | 说明 |
|---|------|------|------|
| 1 | Agent 编辑路由缺失 | `CreateAgent.jsx` | 编辑模式通过 localStorage 传参，无独立路由 |
| 2 | 知识库进度轮询路径错误 | `knowledgeService.js` | 应直接调 `/api/progress/` 而非通过 knowledge 前缀 |
| 3 | 学生 Dashboard 是空壳 | `StudentDashboard.jsx` | 只是路由容器，无独立内容 |

---

## 四、完整 API 端点对照表

### 4.1 认证模块 `/api/auth/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/auth/login` | POST | ✅ 旧版密码登录 | ❌ 未使用 | 可废弃 |
| `/api/auth/login-password` | POST | ✅ | ✅ | 正常 |
| `/api/auth/login-email` | POST | ✅ | ✅ | 正常 |
| `/api/auth/login-phone` | POST | ✅ | ✅ | 正常 |
| `/api/auth/send-email-code` | POST | ✅ | ✅ | 正常（邮件服务不可用） |
| `/api/auth/send-phone-code` | POST | ✅ | ✅ | 正常（开发模式模拟） |
| `/api/auth/register` | POST | ✅ | ✅ | 正常 |
| `/api/auth/verify` | GET | ✅ | ❌ 未使用 | - |
| `/api/auth/logout` | POST | ✅ | ✅ | 正常 |
| `/api/auth/refresh` | POST | ❌ 未实现 | ✅ 有调用 | **需实现** |
| `/api/auth/me` | GET | ❌ 未实现 | ✅ 有调用 | **需实现** |
| `/api/auth/change_password` | POST | ❌ 未实现 | ✅ 有调用 | **需实现** |
| `/api/auth/check` | GET | ✅ session检查 | ❌ 未使用 | 旧版遗留 |

### 4.2 知识库模块 `/api/knowledge/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/knowledge/` | GET | ✅ | ✅ | 正常 |
| `/api/knowledge/` | POST | ✅ 文件上传创建 | ✅ | 正常 |
| `/api/knowledge/<id>` | DELETE | ✅ | ✅ | 正常 |
| `/api/knowledge/<id>/documents` | GET | ✅ | ✅ | 正常 |
| `/api/knowledge/<id>/documents` | POST | ✅ | ✅ | 正常 |
| `/api/knowledge/<id>/documents/<file>` | DELETE | ✅ | ✅ | 正常 |
| `/api/progress/<task_id>` | GET | ✅（app.py主路由） | ⚠️ 路径可能错 | **需核实** |

### 4.3 Agent 模块 `/api/agent/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/agent/create` | POST | ✅ | ✅ | 正常 |
| `/api/agent/list` | GET | ✅ | ✅ | 正常 |
| `/api/agent/<id>` | GET | ✅ | ✅ | 正常 |
| `/api/agent/<id>` | PUT | ✅ | ✅ | 正常 |
| `/api/agent/<id>` | DELETE | ✅ | ✅ | 正常 |
| `/api/agent/<id>/distribute` | POST | ✅ | ✅ | 正常 |
| `/api/agent/<id>/distributions` | GET | ❌ 未实现 | ✅ 有调用 | **需实现** |
| `/api/agent/ai-assist` | POST | ✅ | ✅ | 正常 |

### 4.4 代码执行模块 `/api/code/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/code/execute` | POST | ✅ | ❌ 未接入 | **需前端实现** |
| `/api/code/input` | POST | ✅ | ❌ 未接入 | **需前端实现** |
| `/api/code/stop` | POST | ✅ | ❌ 未接入 | **需前端实现** |
| `/api/code/generate` | POST | ✅ | ❌ 未接入 | **需前端实现** |

### 4.5 可视化模块 `/api/visualization/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/visualization/mindmap` | POST | ✅ | ❌ 未接入 | **需前端实现** |
| `/api/visualization/3d-surface` | POST | ✅ | ❌ 未接入 | **需前端实现** |

### 4.6 学生模块

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/student/agents` | GET | ✅ | ✅ | 正常 |
| `/api/student/activities` | GET | ✅ | ✅ | 正常 |
| `/api/student/chat/<id>` | POST (SSE) | ✅ | ✅ | ⚠️ 有解析问题 |
| `/api/verify_token` | POST | ✅ (app.py) | ⚠️ 路径双重前缀 | **需修复** |

### 4.7 学生管理模块 `/api/teacher/students/*`

| 端点 | 方法 | 后端 | 前端调用 | 状态 |
|------|------|------|---------|------|
| `/api/teacher/students` | GET | ✅ | ✅ | 正常 |
| `/api/teacher/students` | POST | ✅ | ✅ | 正常 |
| `/api/teacher/students/<id>` | PUT | ✅ | ✅ | 正常 |
| `/api/teacher/students/<id>` | DELETE | ✅ | ✅ | 正常 |
| `/api/teacher/students/<id>/reset-password` | POST | ✅ | ✅ | 正常 |
| `/api/teacher/students/<id>/progress` | GET | ✅ | ✅ | 正常 |

---

## 五、分阶段开发计划

### 第一阶段：基础修复（让现有功能跑通）

- [ ] **修复 API 路径双重前缀问题**
  - `AgentChat.jsx` 中 `axios.post('/api/verify_token')` 改为用 api 实例或去掉 `/api` 前缀
  - 排查所有直接使用 `axios` 而非 `api` 实例的调用

- [ ] **修复知识库进度轮询路径**
  - `knowledgeService.js` 中 `getProgress()` 路径对齐后端 `/api/progress/<task_id>`

- [ ] **修复 SSE 流式输出**
  - 前端增加 `metadata` 事件处理（至少不报错）
  - 后端增加 `type: "error"` 事件，出错时通知前端
  - 移除前端无用的 `[DONE]` 检查
  - 添加流超时检测（30s 无数据提示用户）
  - 修复流结束时 buffer 未清空问题

- [ ] **实现缺失的后端端点**
  - `GET /api/agent/<id>/distributions` — 获取 Agent 的分发链接列表
  - `GET /api/auth/me` — 返回当前登录用户信息
  - `POST /api/auth/refresh` — JWT token 刷新（或前端去掉此调用）
  - `POST /api/auth/change_password` — 修改密码（或前端暂时隐藏入口）

### 第二阶段：插件系统迁移（核心差异）

- [ ] **AgentChat 插件框架设计**
  - 在对话界面右侧增加可展开的插件面板（Ant Design Drawer 或自定义侧栏）
  - 根据后端 SSE `start` 事件返回的 `plugins` 字段决定显示哪些插件 Tab
  - 插件自动激活：后端检测到关键词后在 `start` 事件中标记 `suggested_plugins`
  - 插件面板状态：折叠/展开/全屏
  - 布局：左侧对话区 + 右侧插件面板，移动端改为底部抽屉

- [ ] **代码执行插件**
  - 使用 CodeMirror 6 (`@uiw/react-codemirror` + `@codemirror/lang-python`)
  - 上半区：代码编辑器（Python语法高亮、行号）
  - 下半区：终端输出面板（深色背景、绿色提示符、支持 ANSI 颜色）
  - 交互式输入：检测到 `input()` 时显示输入框
  - 控制按钮：运行 / 停止 / 清除
  - 对接 API：
    - `POST /api/code/execute` → 发送代码，轮询输出
    - `POST /api/code/input` → 发送用户输入
    - `POST /api/code/stop` → 终止执行
  - AI 回复中的代码块可一键复制到编辑器
  - AI 代码生成按钮 → `POST /api/code/generate`

- [ ] **3D 可视化插件**（保持旧版 Plotly iframe 方案）
  - 从 AI 回复中提取 Python 代码（包含 `create_3d_plot` 函数）
  - `POST /api/visualization/3d-surface` 发送代码
  - 返回 `html_url` 后在插件面板中用 `<iframe>` 加载
  - 支持全屏查看（Ant Design Modal 全屏模式）
  - 加载中显示 Spin 组件
  - Plotly 原生交互：旋转、缩放、平移、悬浮提示、导出

- [ ] **思维导图插件**（markmap 前端渲染，替代旧版 PlantUML）
  - 安装 `markmap-lib` + `markmap-view`
  - 从 AI 回复中提取 Markdown 层级结构
  - 使用 `Transformer.transform()` 解析为树结构
  - 使用 `Markmap.create()` 渲染到 SVG 容器
  - 交互支持：缩放、平移、节点展开/折叠
  - 支持全屏查看和导出为 SVG/PNG
  - 后端修改：让 LLM prompt 输出 Markdown 标题格式而非 PlantUML 语法

### 第三阶段：独立功能页面

- [ ] **独立代码执行页 `/code`**
  - 完整的 Python IDE 界面（编辑器 + 终端）
  - 语法高亮、行号、Tab 缩进
  - 运行/停止/清除控制按钮
  - 从旧版 `code_execution.html` 迁移逻辑

- [ ] **Token 直接访问入口**
  - 登录页增加"使用 Token 直接访问"选项
  - 输入 Token → 验证 → 跳转到对应 Agent 对话页

### 第四阶段：体验优化

- [ ] **打字机效果**
  - 将 `useTypewriter.js` hook 接入 AgentChat 的流式渲染
  - 支持暂停/继续/加速控制
  - 或直接在流式输出时模拟打字效果（当前逐 chunk 渲染已有类似效果，评估是否需要）

- [ ] **知识库批量上传**
  - 支持多文件选择和拖拽上传
  - 批量进度追踪

- [ ] **Agent 编辑流程优化**
  - 为编辑模式添加独立路由 `/teacher/agent/edit/:id`
  - 替换 localStorage 传参方式为 URL 参数 + API 获取

- [ ] **学生 Dashboard 充实内容**
  - 学习统计、最近活动、推荐 Agent 等

- [ ] **LaTeX 公式渲染**
  - 旧版使用 KaTeX，新版 AgentChat 的 Markdown 渲染中需集成
  - 支持行内公式 `$...$` 和块级公式 `$$...$$`

- [ ] **消息中的引用源展示优化**
  - 旧版有可折叠的引用卡片，显示文件名+摘要
  - 新版已有基础实现，但样式和交互可优化

### 第五阶段：后端优化

- [ ] **统一认证机制**
  - 旧版 app.py 中的硬编码用户和 session 装饰器与新版 JWT 并存，需要统一
  - 决策：全部迁移到 JWT，废弃 session 方式
  - 更新 `@login_required`、`@teacher_required`、`@student_required` 装饰器为 JWT 验证

- [ ] **密码哈希升级**
  - 当前使用 SHA256 直接哈希，建议升级为 bcrypt 或 argon2
  - 需要兼容迁移方案（登录时自动升级哈希）

- [ ] **插件检测逻辑优化**
  - 当前基于消息关键词匹配（如包含"代码"就触发代码插件），过于粗糙
  - 考虑让 LLM 在回复中标记是否需要插件，或使用更精确的意图识别

---

## 六、旧版功能对照清单

### 教师端功能

| 功能 | 旧版 | 新版 | 差距 |
|------|------|------|------|
| 统计面板 | 知识库数/Agent数/分发数 | ✅ 相同 | - |
| 知识库创建 | 多文件上传+进度条 | ⚠️ 单文件 | 缺批量 |
| 知识库文件管理 | 添加/删除文件 | ✅ | - |
| Agent 创建 | 基本信息+插件+知识库+工作流 | ✅ 4步向导 | - |
| Agent 工作流 | jsPlumb 可视化 | ✅ React Flow | 升级 |
| Agent 管理 | 列表+详情+编辑+删除 | ✅ | 编辑入口可优化 |
| 分发链接 | 创建+复制+过期设置 | ✅ | - |
| 学生管理 | CRUD+密码重置+进度 | ✅ | - |

### 学生端功能

| 功能 | 旧版 | 新版 | 差距 |
|------|------|------|------|
| 学生门户 | Agent列表+Token验证+活动记录 | ✅ | - |
| Agent 对话 | SSE流式+Markdown+代码高亮 | ✅ 基本可用 | SSE有bug |
| 打字机效果 | 暂停/加速控制 | ❌ Hook已写未接入 | 需接入 |
| LaTeX 公式 | KaTeX 渲染 | ❌ | 需集成 |
| 代码执行插件 | 侧面板内嵌 IDE | ❌ | **核心缺失** |
| 3D 可视化插件 | Plotly 侧面板 | ❌ | **核心缺失** |
| 思维导图插件 | PlantUML 侧面板 | ❌ | **核心缺失** |
| 引用源展示 | 可折叠卡片 | ⚠️ 基础实现 | 可优化 |
| 独立代码页 | 完整Python IDE | ❌ | 需新建页面 |

---

## 七、技术选型

### 7.1 思维导图：markmap（推荐）

**废弃旧方案**：旧版使用 PlantUML 语法 → 发送到外部 HuggingFace Space API → 返回 PNG 图片。问题：依赖外部服务、不可交互、渲染慢。

**新方案**：使用 markmap 在前端直接从 Markdown 生成交互式 SVG 思维导图。

| 对比项 | 旧方案 (PlantUML) | 新方案 (markmap) |
|--------|-------------------|------------------|
| 渲染位置 | 后端调外部API | 前端本地渲染 |
| 输出格式 | 静态 PNG | 交互式 SVG |
| 交互能力 | 无 | 缩放/平移/展开折叠 |
| 外部依赖 | HuggingFace Space | 无 |
| 延迟 | 3-10秒 | 毫秒级 |
| 输入格式 | PlantUML 专有语法 | Markdown 标题层级 |

**安装**：
```bash
npm install markmap-lib markmap-view d3@7
```

**核心用法**：
```jsx
import { Transformer } from 'markmap-lib';
import { Markmap } from 'markmap-view';

// Markdown → 思维导图数据
const transformer = new Transformer();
const { root } = transformer.transform(markdownText);

// 渲染到 SVG 元素
Markmap.create(svgElement, null, root);
```

**后端改动**：
- 让 LLM 在回复中直接输出 Markdown 层级结构（而非 PlantUML 语法）
- 或者保留后端端点，改为返回 Markdown 文本而非图片 URL
- 前端从 AI 回复中提取 Markdown 标题结构，直接渲染

**备选库对比**：

| 库 | Stars | 特点 | 适合场景 |
|-----|-------|------|---------|
| markmap | 9k+ | Markdown原生、SVG交互、轻量 | ✅ 本项目（AI输出Markdown） |
| simple-mind-map | 11k+ | 功能最全、主题丰富、插件多 | 需要完整思维导图编辑器 |
| mind-elixir | 3k | 零依赖、有React组件 | 需要拖拽编辑节点 |
| React Flow | 24k+ | 项目已在用、高度可定制 | 已用于工作流，可复用 |

选择 markmap 的理由：
1. AI 天然输出 Markdown，无需格式转换
2. 纯前端渲染，不依赖外部服务
3. 交互体验远超静态图片
4. 包体积小，集成简单

---

### 7.2 3D 可视化：保持 Plotly iframe 方案

旧版方案已经很成熟，保持不变：

```
前端提取代码 → POST /api/visualization/3d-surface → 后端沙箱执行 Python
→ 生成 Plotly HTML（内嵌 plotly.js） → 返回 HTML 文件 URL → 前端 iframe 加载
```

**交互能力**（Plotly 原生支持）：
- 3D 旋转（鼠标拖拽）
- 缩放（滚轮）
- 平移（Shift+拖拽）
- 悬浮提示（坐标值）
- 图例切换
- 导出 PNG
- 双击重置视角

**React 迁移要点**：
- 不需要安装 `react-plotly.js`（图表在 iframe 中独立运行）
- 只需在 AgentChat 插件面板中嵌入 `<iframe src={htmlUrl} />`
- 添加全屏按钮和关闭按钮

**后端数据流**：
```
输入: { code: "def create_3d_plot():\n  return {'x':[], 'y':[], 'z':[], 'type':'surface'}" }
输出: { success: true, html_url: "/static/3d_plot_1713012345.html" }
```

---

### 7.3 代码编辑器：CodeMirror 6（推荐）

| 对比项 | Monaco Editor | CodeMirror 6 |
|--------|--------------|--------------|
| 包体积 | ~2.5MB (gzip) | ~150KB (gzip) |
| 加载速度 | 较慢 | 快 |
| 移动端 | 差 | 好 |
| Python 支持 | 完整 | 完整 |
| React 集成 | @monaco-editor/react | @uiw/react-codemirror |
| 适合场景 | 完整 IDE | 轻量代码片段编辑 |

选择 CodeMirror 的理由：
1. 本项目只需要 Python 代码编辑，不需要完整 IDE 功能
2. 包体积小 15 倍，对教育平台的加载速度至关重要
3. 移动端适配更好（学生可能用手机访问）

**安装**：
```bash
npm install @uiw/react-codemirror @codemirror/lang-python
```

---

### 7.4 LaTeX 公式：rehype-katex（推荐）

当前 AgentChat 已使用 `react-markdown` + `remark-gfm`，集成 KaTeX 只需加两个插件：

```bash
npm install remark-math rehype-katex katex
```

```jsx
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
import 'katex/dist/katex.min.css';

<ReactMarkdown remarkPlugins={[remarkGfm, remarkMath]} rehypePlugins={[rehypeKatex]}>
  {content}
</ReactMarkdown>
```

---

### 7.5 技术选型汇总

| 组件 | 选型 | npm 包 | 理由 |
|------|------|--------|------|
| 思维导图 | **markmap** | `markmap-lib` + `markmap-view` | Markdown原生、前端渲染、交互式 |
| 3D 可视化 | **Plotly iframe** | 无需前端安装 | 保持旧版成熟方案，后端生成HTML |
| 代码编辑器 | **CodeMirror 6** | `@uiw/react-codemirror` | 轻量、移动端友好 |
| LaTeX 公式 | **KaTeX** | `remark-math` + `rehype-katex` | 与现有 react-markdown 无缝集成 |
| 代码高亮 | **react-syntax-highlighter** | 已安装 | 项目已在用 |
| 工作流编辑 | **React Flow** | 已安装 | 项目已在用 |

---

## 八、文件结构参考

```
frontend/src/
├── App.jsx                          # 路由配置
├── index.css                        # 全局样式
├── services/
│   ├── api.js                       # axios 实例 + 拦截器
│   ├── authService.js               # 认证 API
│   ├── agentService.js              # Agent API
│   └── knowledgeService.js          # 知识库 API
├── store/
│   ├── store.js                     # Redux store
│   └── slices/
│       ├── authSlice.js             # 认证状态
│       ├── agentSlice.js            # Agent 状态
│       ├── chatSlice.js             # 对话状态
│       ├── workflowSlice.js         # 工作流状态
│       └── uiSlice.js               # UI 状态
├── pages/
│   ├── LoginPage.jsx                # 登录页
│   ├── RegisterPage.jsx             # 注册页
│   ├── teacher/
│   │   ├── TeacherDashboard.jsx     # 教师端框架
│   │   ├── Dashboard.jsx            # 概览页
│   │   ├── AgentList.jsx            # Agent 列表
│   │   ├── CreateAgent.jsx          # Agent 创建向导
│   │   ├── KnowledgeBase.jsx        # 知识库管理
│   │   └── StudentManagement.jsx    # 学生管理
│   └── student/
│       ├── StudentDashboard.jsx     # 学生端框架
│       ├── StudentPortal.jsx        # 学生门户
│       └── AgentChat.jsx            # Agent 对话
├── components/
│   └── common/
│       ├── ProtectedRoute.jsx       # 路由保护
│       └── WorkflowEditor.jsx       # 工作流编辑器
└── hooks/
    └── useTypewriter.js             # 打字机效果 hook

agent/                               # 后端
├── app.py                           # Flask 主应用 + 路由
├── config.py                        # 配置
├── auth.db                          # SQLite 用户库
├── student_management.py            # 学生管理路由
├── modules/
│   ├── auth/routes.py               # 认证路由
│   ├── knowledge_base/
│   │   ├── routes.py                # 知识库路由
│   │   ├── retriever.py             # ES 检索器
│   │   ├── reranker.py              # 重排序器
│   │   ├── generator.py             # LLM 生成器
│   │   ├── processor.py             # 文档处理器
│   │   └── vector_store.py          # ES 向量存储
│   ├── agent_builder/routes.py      # Agent 构建路由
│   ├── code_executor/routes.py      # 代码执行路由
│   └── visualization/routes.py      # 可视化路由
├── agents/                          # Agent JSON 配置存储
├── uploads/                         # 上传文件存储
└── templates/                       # 旧版 HTML 模板（待废弃）
```