# SmartStudyAgent **Repository Path**: Mr_niceday/smart-study-agent ## Basic Information - **Project Name**: SmartStudyAgent - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 7 - **Forks**: 6 - **Created**: 2026-08-12 - **Last Updated**: 2026-08-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 灵语寻涯：个性化资源生成与学习多智能体系统 ![项目前端效果](util/figure.png) > A3 赛道：基于大模型的个性化资源生成与学习多智能体系统 > 面向 408 计算机统考学习场景，围绕“问答讲解、真题检索、视频推荐、思维导图、代码实操、学习画像、学习规划、质量评估”构建可并行协作的学习智能体。 ## 在线访问 学习画像与评估页面已部署到演示环境，可通过以下地址访问： ```text https://187-77-129-149.sslip.io/icebreaker ``` Gitee 仓库继续整理前后端结构、Hermes 多智能体调度和部署说明，方便在本地运行与线上演示之间保持一致。 ## 1. 项目简介 灵语寻涯是一个面向计算机考研 408 学习过程的多智能体系统。项目把学生的自然语言需求、刷题入口、题库 RAG、知识图谱、虚拟数字人和学习画像连接起来，让系统可以根据用户当前问题自动选择合适的 Agent 组合，并将不同 Agent 的结果异步返回到前端。 系统支持两类入口： - 对话式学习入口：用户直接输入“帮我讲解这道题”“生成算法复杂度思维导图”“三个月冲刺 408，给我学习计划”等需求。 - 刷题式入口：用户在题库或练习页面点击某道题后，系统跳过意图路由，直接并行启动题目讲解、RAG、视频推荐、导图和质量评估。 核心目标是让学习资源生成更贴近真实备考流程：先识别学习意图，再并发调用不同能力模块，最后根据质量评估结果进行隐式优化或补充。 ## 2. 核心能力 ### 2.1 Hermes Orchestrator 调度 `backend/hermes_runtime.py` 与 `backend/hermes_loop.py` 实现 Hermes 学习智能体的运行入口。Orchestrator 会根据 query 快速判断应调用的子 Agent，并输出结构化路由结果。 典型路由包括： - `question.deep_explain`：题目深度讲解 Agent - `rag.questions`：题库 RAG 检索 Agent - `resource.video`：讲解视频推荐 Agent - `resource.mindmap`：Markdown / Mermaid 思维导图 Agent - `resource.code`：代码实操 Agent - `learning.progress`：学习画像与规划 Agent - `learning.companion`：泛学习需求陪伴 Agent - `quality.verify`：质量评估 Agent 系统强调“谁先完成谁先展示”。RAG 和视频推荐通常可快速返回，题目讲解可流式渲染，导图类结果完整生成后再渲染，评估 Agent 在后台检查结果质量。 ### 2.2 Agent Loop Engineering 项目在 `backend/hermes_core/` 中封装了 Agent Loop 相关能力，包括： - `conversation_loop.py`：多轮 Agent 执行循环 - `iteration_budget.py`：迭代次数与时间预算 - `tool_result_classification.py`：工具结果归类 - `turn_retry_state.py`：重试状态管理 Loop 的设计思想是：一次学习任务可以由多个 Agent 同时推进；系统会持续接收 Agent 增量，如果仍有有效输出就继续等待，如果长时间无增量再判定静默超时。这样可以避免正常流式讲解被硬性时间上限截断。 ### 2.3 质量评估与隐式优化 质量评估由 `QualityAgent` 与 LoopEvaluator 共同承担。它会检查： - 用户需求是否被覆盖 - 题目讲解是否复述题干、拆解条件、逐步推导 - RAG 和视频是否提供有效资源 - 学习规划是否包含阶段目标、时间预算、薄弱点优先级和动态调整规则 - 生成结果是否适合前端分块渲染 当评估结果较低时，系统不删除已有内容，而是在后台尝试生成更完整的补充版本。若补充结果更好，前端可提示用户查看“更加详细的解答”。 ### 2.4 题库 RAG 与向量库 本仓库保留了轻量版 RAG 示例索引： - `backend/data/rag/questions.json` - `backend/data/rag/questions.faiss` - `backend/data/rag/meta.json` RAG 模块位于 `backend/rag.py`。题库向量库用于匹配真题、相似题、知识点和讲解视频索引。项目当前采用本地字符 n-gram 与 FAISS 检索方式，便于离线运行和轻量部署，也方便后续替换为外部 embedding 模型。 ### 2.5 学习画像与知识掌握度 `backend/mastery_engine.py` 与 `backend/learning_memory.py` 负责学习记忆和掌握度计算。系统会根据用户练习记录、正确率、提示依赖、复习时间、薄弱知识点等信息更新学习画像。 前端的 `ProfileWorkspace`、`EvaluationWorkspace`、`CognitiveRadar` 会展示画像、雷达图与知识点掌握情况。画像可用于后续学习规划、题目推荐和数字人个性化提示。 ### 2.6 虚拟数字人 Sophia 项目接入了科大讯飞在线虚拟人 SDK，前端组件位于： - `src/components/shared/VirtualLearningGuide.tsx` 后端配置与签名能力位于： - `backend/xfyun_virtual_human.py` - `backend/main.py` 中的 `/virtual-human/*` 接口 数字人的定位是学习界面的轻量交互助手。系统生成回答后，前端通过 `avatar.writeText(answer, { nlp: false })` 让虚拟人负责播报、口型和动作。问答理解、画像分析和个性化建议仍由项目后端与大模型完成。 ## 3. 架构概览 ```text 用户 query / 刷题入口 | v Hermes Orchestrator | +--> QuestionTutorAgent 流式题目讲解 +--> QuestionRAGAgent 真题/相似题检索 +--> VideoAgent 讲解视频匹配 +--> MindmapAgent 思维导图生成 +--> CodeLabAgent 代码实操与可视化输出 +--> ProgressAgent 学习画像与规划 +--> LearningCompanionAgent 泛学习陪伴与焦虑缓解 | v LoopEvaluator / QualityAgent | v 前端分块渲染 + 虚拟数字人播报 + 学习记忆更新 ``` 配套架构图可见： - `docs/latex_assets/hermes_agent_loop.png` - `docs/latex_assets/query_orchestrator_async_agents.png` ## 4. 目录说明 ```text . ├── src/ # Next.js 前端源码 │ ├── app/ # 页面路由 │ ├── components/shared/ # Hermes、画像、导图、数字人等核心组件 │ ├── components/layout/ # 页面布局 │ ├── lib/ # 知识图谱、API、资源适配工具 │ └── data/408-kg/ # 408 知识图谱节点与边 ├── backend/ # FastAPI 后端 │ ├── hermes_core/ # Agent Loop 工程化封装 │ ├── hermes_prompts/ # 各 Agent 提示词 │ ├── hermes_skills/ # 各 Agent Skill 定义 │ ├── agents/ # 学习 Agent 基础抽象 │ ├── data/rag/ # 轻量题库 RAG 示例索引 │ ├── tests/ # 场景测试与模型测速脚本 │ └── main.py # API 入口 ├── public/ # 静态资源与虚拟人 SDK ├── docs/ # 集成说明与架构图 ├── deploy/ # systemd / nginx / logrotate 示例 ├── util/ # README 展示图目录，请放置 figure.png └── README.md ``` ## 5. 本地启动 ### 5.1 后端 ```bash cd backend python -m venv .venv source .venv/bin/activate pip install -r requirements.txt uvicorn main:app --reload --host 127.0.0.1 --port 8000 ``` ### 5.2 前端 ```bash npm install npm run dev ``` 默认访问： ```text http://127.0.0.1:3000 ``` Hermes 学习智能体页面： ```text http://127.0.0.1:3000/hermes ``` 学习画像与评估页面： ```text http://127.0.0.1:3000/icebreaker ``` ## 6. 环境变量 请基于 `.env.example` 创建本地 `.env` 或部署环境变量。展示版仓库不包含真实密钥。 ```bash cp .env.example .env ``` 常见变量： - `QHAIGC_API_KEY`：OpenAI 兼容模型接口密钥 - `QHAIGC_BASE_URL`：模型 API 地址 - `QHAIGC_DEFAULT_MODEL`：默认模型 - `XFYUN_APP_ID`：讯飞 APPID - `XFYUN_API_KEY`：讯飞 APIKey - `XFYUN_API_SECRET`：讯飞 APISecret - `XFYUN_VMS_SERVICE_ID`：在线虚拟人服务 ID - `XFYUN_VMS_AVATAR_ID`：虚拟人形象 ID - `XFYUN_VMS_VCN`：发音人 ID ## 7. 可测试问题示例 可以在 Hermes 页面尝试： - 分析数据结构选择题的常见题型，匹配真题并给我练习入口。 - 深度拆解一道线性表真题，结合答案逐步讲解。 - 生成算法复杂度思维导图，并配套推荐讲解视频。 - 生成线性表代码实操，要求可复制、可视化输出和逐行注释。 - 我 90 天准备 408，目标 120 分，请根据薄弱点制定冲刺计划并找入门题。 - 我现在感到焦虑，不知道从哪里开始学，帮我安排今天的学习任务。 - 请把某道题作为主讲题，调用教学 Agent 逐步拆解题干、选项和答案。 ## 8. 开源展示说明 这个目录是轻量展示版，重点体现项目架构、核心逻辑与关键代码。为了便于上传 GitHub，已过滤： - `node_modules` - `.next` - Python 虚拟环境 - 大体积 vendor 包 - 本地 sqlite 实例库 - 用户学习记忆 - 真实 API 密钥 - 历史 LaTeX 编译产物 请将前端展示图命名为 `figure.png` 并放入 `util/` 目录，README 顶部会自动显示该图片。