# 深学星图Agent **Repository Path**: gzist-iflytek/deep-learning-star-map-agent ## Basic Information - **Project Name**: 深学星图Agent - **Description**: 深学星图 Agent 是一个面向 AI 智能体入门教学的全栈示例项目，包含多学科问答、流式对话、记忆管理、缓存与可视化能力，帮助学生理解 Agent 的数据流、工具调用与系统架构。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 1 - **Created**: 2026-06-11 - **Last Updated**: 2026-07-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: Python, Agent ## 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 React TypeScript PostgreSQL Redis Docker

--- 深学星图是一个面向 K12 教学与 AI 智能体入门课程的教育 AI 问答系统。项目以“账号画像 + K12 知识点 + 学习计划 + 任务进入聊天/练习 + 练习反馈 + 错题本 + learning trace + 学科问答 + 安全质量护栏 + 长期记忆 + 数学可视化 + 流式交互”为核心，帮助学生在真实 AI 产品中理解大模型应用、后端架构、数据流、缓存、记忆、鉴权和前端交互的完整链路。 项目目前已经完成第一版 MVP，适合用于 AI 智能体入门教学、FastAPI + React 全栈课程、教育 AI 产品原型演示，以及大模型应用工程实践。 ## 🖥️ 产品预览

深学星图产品预览

## ✨ 功能特性 | 能力 | 覆盖内容 | | --- | --- | | AI 学科问答 | 通用、数学、语文、英语；按学科切换首页文案、示例题和输入体验 | | 用户账号与画像 | 邮箱密码注册登录、JWT 用户解析、年级/学科/回答风格/学习目标画像偏好，支持按学科维护当前目标和手动薄弱点，薄弱点可选绑定知识点 | | K12 课程 Taxonomy | 后端提供课程单元与知识点只读 API，启动时幂等写入最小种子数据 | | 学习计划闭环 | 按账号和学科创建、AI 生成草稿、编辑、清空、续订学习计划，展示任务、标记完成并持久化进度；计划任务可直接进入聊天学习或生成练习；首页会展示草稿规划态和练习生成态 | | 练习生成、反馈与错题本 | 围绕知识点或计划任务生成练习，优先走 AI 结构化生成，兼容嵌套结果解析；AI 不可用时降级目标感知模板；学生提交后返回逐题反馈，错误或部分正确题会沉淀到错题本 | | K12 安全与质量护栏 | 问答、学习计划生成和练习生成共享确定性护栏：高风险内容前置拦截，保分/代写/只要答案类诉求改写为学习辅导，泛化 AI 输出回退目标感知模板 | | Learning Trace | 成功会话问答自动沉淀为 QA trace，练习提交自动沉淀为 Practice trace，并继承计划任务和知识点上下文，供后续掌握度和报告复用 | | 分步讲解工作台 | 支持流式回答、结构化步骤、最终答案、数学公式渲染和右侧辅助信息 | | 长期学习记忆 | 全局记忆、学科记忆、会话记忆；回答时自动检索并注入上下文 | | 历史会话管理 | 新建会话、历史会话列表、继续对话、删除会话、消息持久化和账号级隔离 | | 数学可视化 | 针对函数、几何、图像理解等数学题生成辅助图示 | | LaTeX 兜底 | 首页示例、后端输出、前端展示均做公式格式规范化 | | 缓存观测 | Redis 答案缓存、图片缓存；默认学生 UI 隐藏，开发模式可调试 | | 教学资料 | 快速启动说明、后端代码详解教案，适合课堂拆解和学生自学 | > 功能细节、接口契约和本地启动方式见 [快速开始跑起项目](docs/quick-start.md)。 ## 🧱 技术栈与服务组件 | 类型 | 支持 | | --- | --- | | 前端工作台 | React 18、TypeScript、Vite、Ant Design、Valtio、Axios、KaTeX | | 后端 API | Python、FastAPI、Pydantic、SQLAlchemy Async、DashScope SDK | | AI 模型 | 阿里云百炼 DashScope / 通义千问，兼容 OpenAI 风格调用方式 | | 数据存储 | PostgreSQL 16：用户、登录凭证、学习画像、学习计划、任务、课程单元、知识点、会话、会话来源、消息、learning trace、练习、作答、逐题反馈、错题、记忆、记忆引用 | | 性能缓存 | Redis 7：答案缓存、图片缓存、缓存观测与清理 | | 可视化服务 | 独立 `viz-service`，负责数学可视化需求判断和图片生成 | | 部署运行 | Docker Compose 一键启动后端、可视化服务、PostgreSQL、Redis | | 测试验证 | 后端 API 契约测试、前端 lint/build、手工 smoke 清单 | > 后端架构、数据流、服务层与 API 代码讲解见 [后端代码详解教案](%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)。 ## 🧭 系统架构 ```mermaid flowchart LR Browser["浏览器前端
React + TypeScript + Vite"] Answer["answer-service
FastAPI :8000"] Viz["viz-service
FastAPI :8001"] Postgres["PostgreSQL
用户 / 凭证 / 画像 / 计划 / 任务 / 课程单元 / 知识点 / 会话 / 来源 / 消息 / Trace / 练习 / 作答 / 反馈 / 错题 / 记忆"] Redis["Redis
答案缓存 / 图片缓存"] LLM["DashScope LLM
通义千问"] Static["Static Images
可视化图片"] Browser --> Answer Answer --> Postgres Answer --> Redis Answer --> LLM Answer --> Viz Viz --> Static Answer --> Static ``` ## 🚀 快速开始 完整启动说明见：[快速开始跑起项目](docs/quick-start.md)。 最短路径如下： ```bash # 1. 启动后端 cd shenxue_backend/shenxue-ai cp env.example .env # 编辑 .env，填入 DASHSCOPE_API_KEY # 默认 AUTH_MODE=local 方便课堂演示；要测试真实登录注册可切到 AUTH_MODE=jwt 并配置 JWT_SECRET_KEY docker compose up -d --build # 2. 启动前端 cd ../../shenxue_frontend npm install npm run dev ``` 访问地址： | 服务 | 地址 | | --- | --- | | 前端 | `http://127.0.0.1:5181` | | 后端 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 ├── 深学AI后端架构讲解.md ├── docs/ │ ├── assets/ │ │ └── product-preview.gif │ └── quick-start.md ├── shenxue_frontend/ │ ├── src/ │ ├── package.json │ └── vite.config.ts └── shenxue_backend/ └── shenxue-ai/ ├── docker-compose.yml ├── env.example ├── shared/ ├── answer-service/ └── viz-service/ ``` ## 🔌 API 概览 | 模块 | 接口 | 说明 | | --- | --- | --- | | 健康检查 | `GET /health` | 检查主服务与 Redis 状态 | | 认证 | `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，并在模型调用前执行 K12 安全与质量护栏 | | 同步问答 | `POST /v1/ask/sync` | 一次性返回完整答案，返回体可带护栏 warnings | | 会话问答 | `POST /v1/sessions/{session_id}/ask` | 在指定历史会话中提问，高风险拦截也会保存可追踪 assistant 消息 | | 会话 | `GET /v1/sessions` | 查询历史会话 | | 会话 | `POST /v1/sessions` | 创建新会话；可选携带学习计划任务来源 | | 会话 | `GET /v1/sessions/{session_id}/messages` | 查询会话消息 | | 会话 | `PATCH /v1/sessions/{session_id}` | 更新标题或归档状态 | | 会话 | `DELETE /v1/sessions/{session_id}` | 删除会话 | | 学习计划 | `GET /v1/learning-plans` | 查询当前用户的 active 学科学习计划 | | 学习计划 | `POST /v1/learning-plans` | 创建学习计划和任务 | | 学习计划 | `POST /v1/learning-plans/generate` | 基于目标、画像和 taxonomy 生成可编辑学习计划草稿，内置安全拦截和质量兜底 | | 学习计划 | `PATCH /v1/learning-plans/{plan_id}` | 编辑当前 active 学习计划的标题、目标和任务 | | 学习计划 | `DELETE /v1/learning-plans/{plan_id}` | 清空首页当前 active 计划，后端归档为 archived | | 学习计划 | `POST /v1/learning-plans/{plan_id}/renew` | 当前计划完成后开启下一轮计划，旧计划转为 completed | | 学习计划 | `PATCH /v1/learning-plans/{plan_id}/items/{item_id}` | 更新 active 计划任务完成状态 | | 练习 | `POST /v1/practice-sets/generate` | 围绕知识点或计划任务生成练习，支持 AI 辅助、安全拦截和目标感知模板兜底 | | 练习 | `GET /v1/practice-sets` | 查询当前用户练习集合，可按学科和计划任务筛选 | | 练习 | `GET /v1/practice-sets/{practice_set_id}` | 查询当前用户练习详情，不返回答案要点 | | 练习 | `POST /v1/practice-sets/{practice_set_id}/submissions` | 提交作答，返回逐题反馈、提交结果、错题列表并写入 Practice Trace | | 错题本 | `GET /v1/wrong-questions` | 查询当前用户错题，可按学科和状态筛选 | | 错题本 | `PATCH /v1/wrong-questions/{wrong_question_id}` | 更新错题状态为待复习、已复习或暂不复习 | | Learning Trace | `GET /v1/learning-traces` | 查询当前用户学习事实，可按学科、会话、计划、任务、练习题组和提交筛选 | | 记忆 | `GET /v1/memories` | 查询长期记忆 | | 记忆 | `POST /v1/memories` | 新增长期记忆 | | 记忆 | `PATCH /v1/memories/{memory_id}` | 更新长期记忆 | | 记忆 | `DELETE /v1/memories/{memory_id}` | 删除长期记忆 | | 缓存 | `GET /v1/cache/stats` | 查看 Redis 缓存状态 | | 缓存 | `DELETE /v1/cache/clear?scope=all` | 清理缓存 | ## 🌊 流式事件 问答接口使用 SSE 返回结构化事件： | 事件 | 说明 | | --- | --- | | `start` | 请求开始，返回 request/session/message 信息 | | `memory` | 本次回答使用的长期记忆 | | `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) | 从计划任务生成练习、查看生成中状态卡、识别 AI 提示 / 降级提示、完成作答提交并查看逐题反馈 | | [错题本使用指南](docs/user/wrong-questions.md) | 从侧栏一级入口进入错题本，筛选待复习、已复习、暂不复习并更新状态 | | [账号与学习画像 API 开发指南](docs/dev/auth-profile-api.md) | 认证、当前用户、画像 v2 字段和 metadata 存储约定 | | [K12 Taxonomy API 开发指南](docs/dev/k12-taxonomy-api.md) | 课程单元、知识点只读接口、种子数据和画像绑定方式 | | [K12 学习安全与质量护栏开发指南](docs/dev/learning-guardrails.md) | 问答、学习计划和练习生成共用护栏的规则、响应语义、质量兜底和测试范围 | | [学习计划 API 开发指南](docs/dev/learning-plan-api.md) | 学习计划接口、任务进入聊天的 source 契约、生命周期、错误语义和验证命令 | | [Practice API 开发指南](docs/dev/practice-api.md) | 练习生成、AI 结果兼容解析、目标感知模板兜底、逐题反馈、错题本、Practice Trace 和边界 | | [Learning Trace API 开发指南](docs/dev/learning-trace-api.md) | 成功会话问答与练习作答生成 learning trace、查询接口、账号边界和限制 | | [Git 提交约定](docs/dev/git-workflow.md) | 提交类型、提交范围和 CodeStable 目录边界 | | [后端代码详解教案](%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 ``` ## 📌 当前边界 当前版本是教学 MVP，不等同于生产级学校系统。 已实现： - 本地教学用户 fallback。 - 邮箱密码注册登录。 - JWT 用户解析。 - 学习画像偏好、学科目标和手动薄弱点。 - K12 课程单元和知识点 taxonomy，薄弱点可选绑定知识点。 - 学科学习计划和任务进度。 - 学习计划 AI 草稿生成与目标感知模板兜底。 - 从学习计划任务进入聊天工作台，并在 session 上保存来源计划项。 - 从学习计划任务生成练习并进入作答页。 - 练习生成、作答记录、逐题反馈和错题本。 - 问答、学习计划和练习生成共享 K12 安全与质量护栏。 - 成功会话问答自动生成 QA learning trace，练习作答自动生成 Practice Trace，并继承计划任务和知识点上下文。 - completed 学习计划只读保留，当前首页只展示 active 计划。 - 账号级会话与长期记忆隔离。 - 学科问答。 - 历史会话。 - 长期记忆。 - 问答存储。 - Redis 缓存。 - 数学可视化。 - 前后端基础验收。 暂未实现： - 密码找回、邮箱验证、refresh token 和第三方登录。 - 老师、学生、班级、学校等多角色权限模型。 - Alembic 等完整数据库迁移工具。 - 生产级审计、监控和限流。 - 完整教学后台和班级管理。 - 计划历史时间线、学习报告、计划达成率和 AI 自动生成下一轮计划。 - 完整教材库、taxonomy 后台编辑、导入审核、地区版本教材模型。 - 错题回写画像、掌握度和学习进度 dashboard。 ## 🗺️ 路线图 | 阶段 | 方向 | | --- | --- | | 账号体系 | 密码找回、邮箱验证、第三方登录、老师/学生/班级/学校组织结构 | | 教师端 | 课程配置、记忆模板、班级知识库 | | 学生端 | 错题复习增强、学习报告、收藏夹、学习进度 | | 智能体教学 | 展示观察、记忆、规划、执行、反馈的 Agent 循环 | | 数据治理 | 迁移脚本、备份、审计日志和权限边界 | | 可视化增强 | 更多数学图像类型和更严格的代码执行沙箱 | ## ⚠️ 免责声明 本项目主要用于 AI 智能体、教育 AI 和全栈工程教学。AI 回答可能存在错误，不能替代教师判断或正式教学评价。用于真实教学场景前，请增加内容审核、权限控制、日志审计和数据合规处理。 当前仓库尚未指定开源许可证。如需公开发布，请先补充 `LICENSE` 文件。