# 深学星图Agent

**Repository Path**: seyuan/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**: 0
- **Forks**: 1
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 深学星图 · Shenxue Star Map

<p align="center">
  <img src="./shenxue_frontend/src/assets/brand/shenxue-star-map-logo.png" alt="深学星图" width="420" />
</p>

<p align="center">
  <strong>看见进步，构建你的专属学习星图。</strong>
</p>

**[English](README.en.md) · [快速开始](docs/quick-start.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)**

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" />
  <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-0.104.1-009688?style=flat-square&logo=fastapi&logoColor=white" />
  <img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=111827" />
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white" />
  <img alt="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-16-4169E1?style=flat-square&logo=postgresql&logoColor=white" />
  <img alt="Redis" src="https://img.shields.io/badge/Redis-7-DC382D?style=flat-square&logo=redis&logoColor=white" />
  <img alt="Docker" src="https://img.shields.io/badge/Docker-Compose-2496ED?style=flat-square&logo=docker&logoColor=white" />
</p>

---

深学星图是一个面向 K12 教学与 AI 智能体入门课程的教育 AI 问答系统。项目以“学科问答 + 长期记忆 + 数学可视化 + 流式交互”为核心，帮助学生在真实 AI 产品中理解大模型应用、后端架构、数据流、缓存、记忆和前端交互的完整链路。

项目目前已经完成第一版 MVP，适合用于 AI 智能体入门教学、FastAPI + React 全栈课程、教育 AI 产品原型演示，以及大模型应用工程实践。

## 🖥️ 产品预览

<p align="center">
  <img src="./docs/assets/product-preview.gif" alt="深学星图产品预览" width="920" />
</p>

## ✨ 功能特性

| 能力 | 覆盖内容 |
| --- | --- |
| AI 学科问答 | 通用、数学、语文、英语；按学科切换首页文案、示例题和输入体验 |
| 分步讲解工作台 | 支持流式回答、结构化步骤、最终答案、数学公式渲染和右侧辅助信息 |
| 长期学习记忆 | 全局记忆、学科记忆、会话记忆；回答时自动检索并注入上下文 |
| 历史会话管理 | 新建会话、历史会话列表、继续对话、删除会话、消息持久化 |
| 数学可视化 | 针对函数、几何、图像理解等数学题生成辅助图示 |
| 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：用户、会话、消息、记忆、记忆引用 |
| 性能缓存 | 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["浏览器前端<br/>React + TypeScript + Vite"]
    Answer["answer-service<br/>FastAPI :8000"]
    Viz["viz-service<br/>FastAPI :8001"]
    Postgres["PostgreSQL<br/>用户 / 会话 / 消息 / 记忆"]
    Redis["Redis<br/>答案缓存 / 图片缓存"]
    LLM["DashScope LLM<br/>通义千问"]
    Static["Static Images<br/>可视化图片"]

    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
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 状态 |
| 学科 | `GET /v1/subjects` | 获取通用、数学、语文、英语配置 |
| 问答 | `POST /v1/ask` | 普通问答，支持 JSON / FormData |
| 同步问答 | `POST /v1/ask/sync` | 一次性返回完整答案 |
| 会话问答 | `POST /v1/sessions/{session_id}/ask` | 在指定历史会话中提问 |
| 会话 | `GET /v1/sessions` | 查询历史会话 |
| 会话 | `POST /v1/sessions` | 创建新会话 |
| 会话 | `GET /v1/sessions/{session_id}/messages` | 查询会话消息 |
| 会话 | `PATCH /v1/sessions/{session_id}` | 更新标题或归档状态 |
| 会话 | `DELETE /v1/sessions/{session_id}` | 删除会话 |
| 记忆 | `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) | 从环境准备到前后端启动的最短操作路径 |
| [后端代码详解教案](%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 --no-deps answer-service python -m unittest discover tests

# 前端检查
cd ../../shenxue_frontend
npm run lint
npm run build
```

## 📌 当前边界

当前版本是教学 MVP，不等同于生产级学校系统。

已实现：

- 本地教学用户。
- 学科问答。
- 历史会话。
- 长期记忆。
- 问答存储。
- Redis 缓存。
- 数学可视化。
- 前后端基础验收。

暂未实现：

- 正式登录注册。
- 老师、学生、班级、学校等多用户权限模型。
- 数据库迁移工具。
- 生产级鉴权、审计、监控和限流。
- 完整教学后台和班级管理。

## 🗺️ 路线图

| 阶段 | 方向 |
| --- | --- |
| 账号体系 | 老师、学生、班级、学校组织结构 |
| 教师端 | 课程配置、记忆模板、班级知识库 |
| 学生端 | 错题本、学习报告、收藏夹、学习进度 |
| 智能体教学 | 展示观察、记忆、规划、执行、反馈的 Agent 循环 |
| 数据治理 | 迁移脚本、备份、审计日志和权限边界 |
| 可视化增强 | 更多数学图像类型和更严格的代码执行沙箱 |

## ⚠️ 免责声明

本项目主要用于 AI 智能体、教育 AI 和全栈工程教学。AI 回答可能存在错误，不能替代教师判断或正式教学评价。用于真实教学场景前，请增加内容审核、权限控制、日志审计和数据合规处理。

当前仓库尚未指定开源许可证。如需公开发布，请先补充 `LICENSE` 文件。