目标

将论文《基于大模型的高中数学个性化学习智能体系统设计》从概念方案推进到可运行的代码实现，采用分阶段增量构建策略。

技术栈

• 后端：Python FastAPI + LangChain + ChromaDB
• 前端：Next.js 14 + Tailwind CSS + KaTeX
• 模型：DeepSeek v4 Flash（API）
• 数据库：MySQL + ChromaDB（向量）

Phase 1 完成项

• 后端 API — POST /api/chat 对话接口，支持四级引导策略（Socratic / Scaffolding / Coaching / Direct）
• RAG 知识库 — ChromaDB 向量检索（高中数学知识点：函数、导数等），当前 DeepSeek 不支持 embedding，已做异常降级
• 对话管理 — 内存会话，支持 conversation_id 续接历史
• 前端界面 — 对话气泡、LaTeX 数学公式渲染、四级引导选择器、流式加载状态
• MySQL 数据库 — math_agent 库已创建

踩坑记录

1. API Key 被覆盖 — 系统环境变量中有过期的 OPENAI_API_KEY，load_dotenv() 默认不覆盖已存在的环境变量，需加 override=True
2. DeepSeek 不支持 OpenAI Embedding — RAG 搜索直接报 500，加 try/except 降级返回空结果，后续需换用本地 embedding 模型（如 sentence-transformers）
3. Windows 端口僵尸 — 进程被杀后端口仍 LISTENING，需 taskkill /F /PID pid /T 或换端口
4. npm install 超时 — 默认 registry 极慢，换 https://registry.npmmirror.com 解决
5. Next.js SWC 二进制异常 — 重新安装 node_modules 后恢复

运行状态

• 后端：http://localhost:8002 ✅ /api/health 正常，/api/chat 正常应答
• 前端：http://localhost:3000 ✅ Next.js 14 正常渲染

待办

• 构建知识库向量索引（需 embedding 模型就绪后）
• 迁移到本地 embedding 模型（sentence-transformers）
• Phase 2：错题本 Agent + 知识图谱 Agent