# 学习agent **Repository Path**: zrt-cmd/learning-agent ## Basic Information - **Project Name**: 学习agent - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-07-30 - **Last Updated**: 2026-09-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 深学星图 · Shenxue Star Map

深学星图

既懂知识又懂你 — 从被动答疑到主动引导的自适应学习伴学智能体

**[English](README.en.md) · [快速开始](docs/quick-start.md) · [画像指南](docs/user/learner-profile.md) · [学习计划指南](docs/user/learning-plan.md) · [后端代码讲解](%E6%B7%B1%E5%AD%A6AI%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%B2%E8%A7%A3.md)**

Python FastAPI LangGraph React TypeScript PostgreSQL BGE Docker

--- 深学星图是一个面向 K12 中学生（初一至高一）的 **AI 自适应学习伴学智能体**，覆盖数学、语文、英语三大学科。项目基于 **四Agent协同架构**（答疑Agent + 诊断规划Agent + 伴学Agent + 自适应服务），实现学情诊断 → 路径规划 → 实时干预 → 记忆反思的完整闭环，配合 **五阶段混合RAG管线** 和 **知识图谱驱动的6种自适应动作**，让每个学生拥有专属的、实时演进的学习路径。 **核心理念**：从"被动答疑"到"主动引导" — 不是等学生问问题，而是主动诊断薄弱点、规划学习路径、脚手架式辅导、持续记忆反思。 --- ## 🏆 核心架构优势 ### 为什么不是"对话套壳"？ | 能力维度 | 深学星图（四Agent协同） | 对话套壳产品 | |---------|----------------------|-------------| | **规划** | 三阶段诊断流程 + StateGraph状态机 + 多步推理链 | 单轮问答 | | **记忆** | 长期画像 + 掌握度地图 + LangGraph checkpoint + 跨会话持久化 | 仅对话上下文 | | **工具使用** | 6+专业工具（RAG检索、掌握度查询、依赖链查询、错题查询等） | 无工具 | | **自适应** | 6种动态调整动作，实时响应学情变化 | 静态计划或无 | | **知识驱动** | 知识图谱依赖关系驱动路径规划+RAG扩展+根因诊断 | 无知识图谱 | ### 四Agent协同架构 ``` 感知层 ──→ 决策层 ──→ 执行层 ──→ 反馈层 │ │ │ │ ▼ ▼ ▼ ▼ Answer Adaptive Adaptive Frontend Agent + Plan Plan 轮询展示 Companion Service Service "路径已更新" Agent ``` - **Answer Agent**：感知学生问题 → RAG检索 → 推理回答 → 评估掌握度 - **Planner Agent**：三阶段诊断（基础数据→深入分析→冲突检测）→ 生成个性化路径 - **Companion Agent**：StateGraph状态机（greet→diagnose→plan→practice→evaluate→reflect） - **Adaptive Plan Service**：6种自适应动作实时调整学习路径 ### 6种自适应动作 | 动作 | 触发条件 | 效果 | |------|---------|------| | `auto_complete` | 知识点已掌握 | 对应任务自动完成 | | `unlock_next` | 前置知识已掌握 | 解锁后续任务 | | `insert_prerequisite` | 知识点困难 | 沿依赖链插入前置复习任务 | | `demote_to_review` | 知识点困难 | 任务降级为需复习 | | `reorder_path` | 掌握度变化 | 按优先级重排路径（struggling优先） | | `suggest_scaffold` | 知识点困难 | 切换脚手架引导模式 | ### 五阶段混合RAG管线 ``` 文档上传 → 解析提取 → 智能分块 → 语义向量化 → 三路并行检索 + 精排重排 ``` - **向量检索**：pgvector余弦相似度（语义匹配） - **关键词检索**：bigram分词+ILIKE（精确匹配术语/公式） - **知识图谱扩展**：沿prerequisites依赖链扩展（补充相关上下文） - **精排重排**：BGE-reranker-v2-m3 模型精排，解决跨通道排序不一致 --- ## 🖥️ 产品预览

深学星图产品预览

## ✨ 功能特性 ### 🤖 智能体核心能力 | 能力 | 覆盖内容 | | --- | --- | | **学情诊断** | Planner Agent 三阶段诊断：基础数据收集→深入分析（依赖链+错题+学习历史）→冲突检测；输出诊断报告+个性化路径推荐 | | **路径规划** | AI辅助生成+模板生成双模式；基于学生画像（成绩水平/学习风格/时间投入/薄弱点/学习目标）差异化规划；AI超时自动降级目标感知模板 | | **自适应调整** | 6种动态调整动作：掌握知识点→自动完成+解锁后续；遇到困难→插入前置复习+降级+脚手架引导；任意变化→路径重排 | | **脚手架式辅导** | 困难时切换引导模式，一步步提示而非直接给答案；安全护栏拦截"只要答案"类诉求并改写为学习辅导 | | **长期记忆与反思** | 全局记忆+学科记忆+会话记忆+LangGraph checkpoint跨会话持久化；掌握度地图持续演进 | | **RAG知识增强** | 五阶段管线：文档解析→500字滑动窗口分块→BGE-large-zh-v1.5向量化→三路并行检索→BGE-reranker-v2-m3精排 | ### 📚 学习闭环 | 能力 | 覆盖内容 | | --- | --- | | AI 学科问答 | 通用、数学、语文、英语；按学科切换首页文案、示例题和输入体验 | | 用户账号与画像 | 邮箱密码注册登录、JWT 用户解析、年级/学科/回答风格/学习目标画像偏好，支持按学科维护当前目标和手动薄弱点，薄弱点可选绑定知识点 | | K12 课程 Taxonomy | 后端提供课程单元与知识点只读 API，启动时幂等写入最小种子数据 | | 学习计划闭环 | 按账号和学科创建、AI 生成草稿、编辑、归档、续订学习计划；**支持多计划共存（同科目最多 3 个 active 计划）**；归档计划可展开查看历史内容并支持回看学习/练习；计划任务可直接进入聊天学习或生成练习 | | 练习生成、反馈与错题本 | 围绕知识点或计划任务生成练习，优先走 AI 结构化生成，兼容嵌套结果解析；AI 不可用时降级目标感知模板；学生提交后返回逐题反馈，错误或部分正确题会沉淀到错题本 | | 错题本分科管理 | 错题本按语文、数学、英语、通用分类展示，支持按科目筛选待复习/已复习/暂不复习 | | 学习报告 | 全维度学习画像与报告：KPI 概览、待办事项、学习画像、科目评估雷达图、活跃趋势图、**知识掌握地图**、错题深度分析、薄弱点变化趋势、进度日志（含归档事件，支持无限回溯加载更多） | | K12 安全与质量护栏 | 问答、学习计划生成和练习生成共享确定性护栏：高风险内容前置拦截，保分/代写/只要答案类诉求改写为学习辅导，泛化 AI 输出回退目标感知模板 | | Learning Trace | 成功会话问答自动沉淀为 QA trace，练习提交自动沉淀为 Practice trace，并继承计划任务和知识点上下文，供后续掌握度和报告复用 | ### 🎨 交互与可视化 | 能力 | 覆盖内容 | | --- | --- | | 分步讲解工作台 | 支持流式回答、结构化步骤、最终答案、数学公式渲染和右侧辅助信息 | | 数学可视化 | 针对函数、几何、图像理解等数学题生成辅助图示 | | 伴学面板 | 数学：3D几何体可视化、函数图像绘制、公式卡片；语文：知识卡片、写作框架；英语：词汇卡片、语法树 | | 历史会话管理 | 新建会话、历史会话列表、继续对话、删除会话、消息持久化和账号级隔离 | | LaTeX 兜底 | 首页示例、后端输出、前端展示均做公式格式规范化 | | 异步生成与持久化 | 学习路线生成过程与 UI 组件解耦（全局 Valtio store），用户离开页面后生成继续进行，回来后自动恢复状态 | | 自动刷新 | 学习报告支持定时轮询（30s）+ 页面可见性监听自动刷新 + 手动刷新按钮 | ### 🔧 管理端 | 能力 | 覆盖内容 | | --- | --- | | 知识库管理 | 上传文档（PDF/DOCX/TXT/MD）→ 自动解析分块向量化；知识块列表查看、知识点标注、chunk_type分类 | | 向量空间 | 2D散点图可视化向量分布；按知识点着色；知识点筛选 | | 学习轨迹 | 查看学生学习记录、问答trace、练习trace | | 错题管理 | 查看全部学生错题，按学科/状态筛选 | | 系统设置 | 系统配置查看与修改 | > 功能细节、接口契约和本地启动方式见 [快速开始跑起项目](docs/quick-start.md)。 ## 🧱 技术栈与服务组件 | 类型 | 支持 | | --- | --- | | 前端工作台 | React 18、TypeScript、Vite、Ant Design、Valtio（全局状态管理）、Axios、KaTeX | | 管理端 | React 19、TypeScript、Vite 8、Ant Design 6、React Router 7 | | 后端 API | Python、FastAPI、Pydantic、SQLAlchemy Async、DashScope SDK | | **Agent 框架** | **LangGraph + LangChain（多Agent状态机、AsyncPostgresSaver检查点持久化）** | | **AI 模型** | **DashScope (DeepSeek/Qwen)，兼容 OpenAI 风格调用方式** | | **Embedding** | **BGE-large-zh-v1.5（1024维中文语义向量，SiliconFlow推理）** | | **Reranker** | **BGE-reranker-v2-m3（检索精排）** | | **向量存储** | **PostgreSQL 16 + pgvector 扩展（余弦距离索引）** | | 数据存储 | PostgreSQL 16：用户、凭证、画像、计划、任务、课程单元、知识点、会话、消息、trace、练习、错题、记忆、**知识块+向量、掌握度、自适应动作** | | 性能缓存 | Redis 7：答案缓存、图片缓存、缓存观测与清理 | | 可视化服务 | 独立 `viz-service`，负责数学可视化需求判断和图片生成 | | 部署运行 | Docker Compose 一键启动后端、可视化服务、PostgreSQL、Redis | | 测试验证 | 后端 API 契约测试、前端 lint/build、手工 smoke 清单 | ## 🧭 系统架构 ```mermaid flowchart TB subgraph Client["客户端"] Frontend["学生端
React 18 + TS + Vite"] Admin["管理端
React 19 + Ant Design 6"] end subgraph Backend["FastAPI 后端服务集群"] Answer["Answer Agent
答疑辅导"] Planner["Planner Agent
诊断规划"] Companion["Companion Agent
伴学对话"] Adaptive["Adaptive Service
路径调整"] end subgraph Services["共享服务层"] RAG["RAG Service
三路混合检索+精排"] Embed["Embedding Service
BGE-large-zh-v1.5"] Guard["Guardrail
安全护栏"] Mastery["Mastery Service
掌握度"] Profile["Profile Service
学生画像"] LLM["LLM
DashScope"] end subgraph Data["数据层"] PG["PostgreSQL + pgvector
画像/图谱/掌握度/计划/知识块+向量"] Redis["Redis
缓存"] end Client --> Backend Backend --> Services Services --> Data Answer --> RAG Answer --> Mastery Planner --> Profile Planner --> Mastery Companion --> Adaptive Adaptive --> Mastery RAG --> Embed ``` ## 🚀 快速开始 完整启动说明见：[快速开始跑起项目](docs/quick-start.md)。 最短路径如下： ```bash # 1. 启动后端 cd shenxue_backend/shenxue-ai cp env.example .env # 编辑 .env，填入 DASHSCOPE_API_KEY、EMBEDDING_API_KEY 等 docker compose up -d --build # 2. 启动前端 cd ../../shenxue_frontend npm install npm run dev # 3. 启动管理端 cd ../../shenxue_admin npm install npm run dev ``` 访问地址： | 服务 | 地址 | | --- | --- | | 学生端 | `http://127.0.0.1:5181` | | 管理端 | `http://127.0.0.1:5174` | | 后端 API | `http://127.0.0.1:8000/v1` | | Swagger Docs | `http://127.0.0.1:8000/docs` | | 健康检查 | `http://127.0.0.1:8000/health` | ## 📁 项目结构 ```text 深学AI/ ├── README.md ├── README.en.md ├── docs/ ├── shenxue_frontend/ # 学生端 │ ├── src/ │ │ ├── api/ # API 封装 │ │ ├── pages/ │ │ │ ├── report/ # 学习报告（画像+报告+进度日志） │ │ │ ├── plan/ # 学习计划（多计划共存+归档+自适应） │ │ │ ├── wrong-questions/ # 错题本（分科管理） │ │ │ └── chat/ # 问答工作台+伴学面板 │ │ ├── store/ │ │ └── components/ │ └── package.json ├── shenxue_admin/ # 管理端 │ ├── src/ │ │ ├── pages/ │ │ │ ├── KnowledgeBase.tsx # 知识库管理+文档上传 │ │ │ ├── VectorSpace.tsx # 向量空间可视化 │ │ │ ├── LearningTraces.tsx # 学习轨迹 │ │ │ ├── WrongQuestions.tsx # 错题管理 │ │ │ └── SystemSettings.tsx # 系统设置 │ │ └── layouts/ │ └── package.json └── shenxue_backend/ └── shenxue-ai/ ├── docker-compose.yml ├── answer-service/ │ └── app/ │ ├── agents/ # 🤖 四大智能体 │ │ ├── answer_tools.py # Answer Agent 工具 │ │ ├── planner_graph.py # Planner Agent 状态图 │ │ ├── planner_prompts.py # Planner 系统提示词 │ │ ├── planner_tools.py # Planner 工具集 │ │ └── companion_graph.py # Companion Agent 状态图 │ ├── services/ # 共享服务层 │ │ ├── rag_service.py # 五阶段混合RAG │ │ ├── embedding_service.py # 向量化服务 │ │ ├── adaptive_plan_service.py # 自适应路径调整 │ │ ├── document_parser.py # 文档解析+分块 │ │ ├── learning_plan_generation_service.py # 学习计划生成 │ │ ├── learning_guardrail_service.py # 安全护栏 │ │ └── profile_insight_service.py # 学生画像 │ ├── repositories/ # 数据层 │ │ ├── mastery.py # 掌握度 │ │ └── taxonomy.py # 知识图谱 │ └── api/ # API 路由 └── viz-service/ # 可视化服务 ``` ## 🔌 API 概览 ### 智能体与自适应 | 模块 | 接口 | 说明 | | --- | --- | --- | | 诊断规划 | `POST /v1/planner` | Planner Agent 三阶段诊断，输出诊断报告+推荐路径+执行计划 | | 伴学对话 | `POST /v1/companion` | Companion Agent 多轮对话引导（greet→diagnose→plan→practice→evaluate→reflect） | | 自适应动作 | `GET /v1/learning-plans/adaptive-actions` | 获取路径调整记录，支持按学科和时间筛选 | ### 知识库与RAG | 模块 | 接口 | 说明 | | --- | --- | --- | | 知识块查询 | `GET /v1/knowledge-chunks` | 查询知识块，支持按知识点、类型、来源筛选 | | 文档上传 | `POST /v1/knowledge-chunks/upload` | 上传文档（PDF/DOCX/TXT/MD），自动解析分块向量化 | | 向量空间 | `GET /v1/vector-space` | 获取向量2D投影数据（UMAP降维），用于散点图可视化 | ### 学习闭环 | 模块 | 接口 | 说明 | | --- | --- | --- | | 认证 | `POST /v1/auth/register` | 邮箱密码注册，返回 token、用户和默认画像 | | 认证 | `POST /v1/auth/login` | 邮箱密码登录 | | 认证 | `GET /v1/auth/me` | 恢复当前用户和学习画像 | | 认证 | `PATCH /v1/auth/me/profile` | 更新年级、偏好学科、回答风格、学习目标、学科目标和薄弱点 | | 学科 | `GET /v1/subjects` | 获取通用、数学、语文、英语配置 | | K12 Taxonomy | `GET /v1/taxonomy` | 查询课程单元和知识点，可按学科和年级筛选 | | 问答 | `POST /v1/ask` | 普通问答，支持 JSON / FormData，执行安全护栏+RAG检索+掌握度评估 | | 会话问答 | `POST /v1/sessions/{session_id}/ask` | 在指定历史会话中提问 | | 会话 | `GET /v1/sessions` | 查询历史会话 | | 会话 | `POST /v1/sessions` | 创建新会话；可选携带学习计划任务来源 | | 会话 | `GET /v1/sessions/{session_id}/messages` | 查询会话消息 | | 学习计划 | `GET /v1/learning-plans` | 查询当前用户学习计划，可按学科和状态筛选 | | 学习计划 | `POST /v1/learning-plans/generate` | AI 生成学习计划草稿，内置安全拦截和质量兜底 | | 学习计划 | `PATCH /v1/learning-plans/{plan_id}` | 编辑学习计划 | | 学习计划 | `POST /v1/learning-plans/{plan_id}/renew` | 续订下一轮计划 | | 学习计划 | `PATCH /v1/learning-plans/{plan_id}/items/{item_id}` | 更新任务完成状态 | | 练习 | `POST /v1/practice-sets/generate` | 围绕知识点或计划任务生成练习 | | 练习 | `POST /v1/practice-sets/{practice_set_id}/submissions` | 提交作答，返回逐题反馈并写入错题本+Trace | | 错题本 | `GET /v1/wrong-questions` | 查询当前用户错题，可按学科和状态筛选 | | 学习报告 | `GET /v1/learning-report` | 获取全维度学习报告（画像洞察、掌握地图、错题分析、薄弱点趋势） | | Learning Trace | `GET /v1/learning-traces` | 查询学习事实 | | 记忆 | `GET /v1/memories` | 查询长期记忆 | | 缓存 | `GET /v1/cache/stats` | 查看 Redis 缓存状态 | ## 🌊 流式事件 问答接口使用 SSE 返回结构化事件： | 事件 | 说明 | | --- | --- | | `start` | 请求开始，返回 request/session/message 信息 | | `memory` | 本次回答使用的长期记忆 | | `rag` | RAG 检索结果（检索通道、命中数量、引用的知识块） | | `mastery` | 掌握度评估结果（知识点、mastered/struggling、置信度） | | `adaptive` | 自适应动作触发通知（动作类型、影响的知识点/任务） | | `cache` | 是否命中缓存 | | `text` | 文本增量 | | `visualization` | 可视化检查、生成、成功、失败或跳过 | | `warning` | 非致命警告 | | `error` | 错误事件 | | `done` | 回答完成 | ## 📚 文档中心 | 文档 | 说明 | | --- | --- | | [快速开始跑起项目](docs/quick-start.md) | 从环境准备到前后端启动的最短操作路径 | | [学习者画像使用指南](docs/user/learner-profile.md) | 维护画像偏好、学科目标和薄弱点的测试步骤 | | [学习计划使用指南](docs/user/learning-plan.md) | 创建、AI 生成、从任务学习、归档、完成和开启下一轮计划的测试步骤 | | [练习作答使用指南](docs/user/practice.md) | 从计划任务生成练习、完成作答提交并查看逐题反馈 | | [错题本使用指南](docs/user/wrong-questions.md) | 从侧栏一级入口进入错题本，按科目筛选并更新状态 | | [后端代码详解教案](%E6%B7%B1%E5%AD%A6AI%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%B2%E8%A7%A3.md) | 面向课堂的后端架构、数据流、服务层、API 代码讲解 | ## ✅ 测试与验证 ```bash # 后端 API 契约测试 cd shenxue_backend/shenxue-ai docker compose run --rm \ -v "$PWD/answer-service:/app" \ -v "$PWD/shared:/app/shared" \ answer-service python -m unittest tests.test_api_contract # 前端检查 cd ../../shenxue_frontend npm run lint npm run build # 管理端检查 cd ../../shenxue_admin npm run lint npm run build ``` ## 📌 当前边界 当前版本是 **v3 自适应伴学智能体原型**，核心Agent架构和RAG管线已完整实现。 ### ✅ 已实现 **智能体核心**： - 四Agent协同架构（Answer / Planner / Companion / Adaptive） - Planner Agent 三阶段诊断流程（基础数据→深入分析→冲突检测） - Companion Agent StateGraph 状态机（greet→diagnose→plan→practice→evaluate→reflect） - 6种自适应动作（auto_complete / unlock_next / insert_prerequisite / demote_to_review / reorder_path / suggest_scaffold） - LangGraph AsyncPostgresSaver 检查点持久化，跨会话恢复状态 **RAG与知识库**： - 五阶段混合RAG管线（解析→分块→向量化→三路检索→精排） - BGE-large-zh-v1.5 语义向量化（1024维） - BGE-reranker-v2-m3 检索精排 - pgvector 余弦距离索引 - 知识图谱（前置依赖关系驱动路径规划+RAG扩展+根因诊断） - 管理端文档上传+自动解析分块向量化 **学习闭环**： - 邮箱密码注册登录、JWT 用户解析 - 学习画像偏好、学科目标和手动薄弱点 - K12 课程单元和知识点 taxonomy - 学科学习计划和任务进度；多计划共存（同科目最多3个active计划） - 归档计划可展开查看历史内容，支持回看学习/练习 - 学习计划 AI 草稿生成与目标感知模板兜底（双模式降级） - 练习生成、作答记录、逐题反馈和错题本（分科管理） - 学习报告（KPI概览+掌握地图+错题分析+薄弱点趋势+进度日志） - 掌握度地图持续演进，驱动自适应调整 - K12 安全与质量护栏 - Learning Trace（QA trace + Practice trace） - 长期记忆（全局+学科+会话三级） - 数学可视化 + 伴学面板（3D/函数图/知识卡片） - 管理端（知识库管理+向量空间+学习轨迹+错题管理+系统设置） - Docker Compose 容器化部署 ### ⚠️ 部分实现 - 语文/英语知识图谱深度依赖关系（基础体系已有，深度依赖待补充） - 伴学面板语文/英语多模态内容（基础卡片已有，写作框架/语法树待完善） ### ❌ 暂未实现 - 密码找回、邮箱验证、refresh token 和第三方登录 - 老师、学生、班级、学校等多角色权限模型 - Alembic 等完整数据库迁移工具 - 生产级审计、监控和限流 - 学生手动修正掌握度入口 - 错题申诉人工复核通道 - 管理端上传版权授权确认 ## 🗺️ 路线图 | 阶段 | 方向 | 状态 | | --- | --- | --- | | **四Agent协同架构** | Answer/Planner/Companion/Adaptive 四Agent分工协作 | ✅ 已完成 | | **6种自适应动作** | auto_complete/unlock/insert/demote/reorder/scaffold | ✅ 已完成 | | **五阶段混合RAG** | 解析→分块→向量化→三路检索→精排 | ✅ 已完成 | | **知识图谱驱动** | 前置依赖关系驱动路径规划+RAG扩展+根因诊断 | ✅ 已完成 | | 账号体系增强 | 密码找回、邮箱验证、第三方登录 | 规划中 | | 学科深度拓展 | 语文/英语知识图谱深度补全；物理/化学等理科 | 规划中 | | 学生端增强 | 手动修正掌握度、错题申诉复核、收藏夹 | 规划中 | | 多模态输入 | 手写识别、语音交互 | 规划中 | | B端功能 | 老师/班级/学校组织结构、班级管理、教研数据服务 | 规划中 | | 生产化 | 数据库迁移、审计日志、监控告警、限流 | 规划中 | ## ⚠️ 免责声明 本项目主要用于 AI 智能体、教育 AI 和全栈工程实践。AI 回答可能存在错误，不能替代教师判断或正式教学评价。用于真实教学场景前，请增加内容审核、权限控制、日志审计和数据合规处理。 当前仓库尚未指定开源许可证。如需公开发布，请先补充 `LICENSE` 文件。