# 深学星图Agent

**Repository Path**: gzist-iflytek/deep-learning-star-map-agent

## Basic Information

- **Project Name**: 深学星图Agent
- **Description**: 深学星图 Agent v1.0.0 — 面向 K12 教育的 AI 智能学习助手。支持多学科智能问答、流式对话、学习计划自动生成、练习与错题管理、记忆系统、资料库增强检索与可视化分析。前端 React 18 + Ant Design 5 双主题，后端 FastAPI + SQLAlchemy Async + RAG 检索，内置离线评测体系、发布质量门禁与 Docker 容器化部署。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/maniact
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-06-11
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python, Agent, React, Redis, postgre

## README

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

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

<p align="center">
  <a href="README.en.md">English</a> ·
  <a href="docs/quick-start.md">快速开始</a> ·
  <a href="docs/dev/v1-release-quality-gates.md">发布门禁</a> ·
  <a href="%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">后端架构讲解</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/frontend-React%2018%20%2B%20Vite%206-61dafb" alt="frontend" />&nbsp;
  <img src="https://img.shields.io/badge/backend-FastAPI%20%2B%20Python%203.11-009688" alt="backend" />&nbsp;
  <img src="https://img.shields.io/badge/data-PostgreSQL%2016%20%7C%20Redis%207%20%7C%20ES%208.11.3-336791" alt="data" />&nbsp;
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license" />
</p>

---

## 🌟 核心价值

> 深学星图把学科问答、学习计划、练习错题、资料 RAG、长期记忆与固定阶段的 Learning Agent 串成一条**可追踪的学习旅程**，并配套可执行的离线评测与第一版发布质量门禁。

适合教育 AI 原型演示、Agent / RAG 工程教学，以及 FastAPI + React 全栈实践。它仍是**教学型产品**，不等同于学校级生产系统。

**为什么关注它**

- 🧭 **一条可追踪的学习旅程**：从首页、计划、会话、练习到错题与资料库，桌面 / 平板 / 手机三档布局一致。
- 🤖 **固定阶段的 Learning Agent**：ask / plan / practice 共用同一套阶段化 Runtime 与运行账本，行为可解释、可审计。
- 🛡️ **回答最终质量门禁**：唯一 `final` 正文、确定性格式校验与一次受限修复，不让草稿冒充答案。
- 📊 **可执行的评测与发布证据**：Answer / RAG / Agent 离线评测 + 第一版发布门禁，Mock 测试不能替代真实 smoke。

---

## ✨ 核心能力

| 能力 | 已实现内容 |
| --- | --- |
| 🧭 连续学习旅程 | 响应式首页、学习计划、会话、练习、错题、资料库与个人设置；desktop / tablet / mobile 三档布局 |
| 💬 学科问答 | 通用、数学、语文、英语；SSE 流式草稿、唯一 `final` 最终正文、Markdown / KaTeX 与数学可视化 |
| 🛡️ 回答最终质量 | 确定性格式与内容校验、一次受限修复、长度 / 直接回答 / 引用约束、版本化缓存与离线晋级报告 |
| 🤖 Learning Agent | ask / plan / practice 共用固定阶段 Runtime、运行与步骤账本、策略版本、失败终态、学生反馈与结果事件 |
| 📚 教学资料 RAG | txt / docx / pdf / 文本入库、结构化 overlap chunk、DashScope embedding、Elasticsearch 双路召回、RRF、确定性 rerank、阈值过滤、引用落库与历史回放 |
| 🔎 RAG 评测与观测 | committed dataset、冻结 baseline、candidate report、Recall / MRR / nDCG / false-hit / 权限边界门禁，以及 ask / practice / plan 聚合观测 |
| 🗺️ 学习计划与练习 | AI / 模板计划草稿、计划任务进入聊天或练习、逐题反馈、错题本、QA / Practice Trace |
| 🔄 学习数据飞轮基座 | helpful / not_helpful 当前反馈、五类幂等 `LearningOutcomeEvent`、来源 run 归因和隐私安全聚合信号；不自动训练或发布策略 |
| 👤 账号与画像 | local 教学用户、邮箱密码注册登录、JWT 隔离、年级 / 偏好 / 学科目标 / 手动薄弱点 |
| 🚀 生产运行基线 | Alembic one-shot migration、配置 fail-fast、操作族限流、统一错误、JSON 关联日志、liveness / readiness |
| ✅ 发布质量门禁 | 后端全量单测、Answer / RAG / Agent 离线评测、前端质量门、只读 live smoke、隔离数据库演练与同提交 go / no-go |

---

## 🖼️ 产品预览

**学习工作台首页** — 学科切换、学习计划入口、最近会话与快捷动作。

<p align="center">
  <img src="./docs/assets/preview-home.png" alt="深学星图 · 学习工作台首页" width="920" />
</p>

**学科问答会话页** — SSE 流式回答、Markdown / KaTeX 渲染、会话历史与反馈入口。

<p align="center">
  <img src="./docs/assets/preview-chat.png" alt="深学星图 · 学科问答会话页" width="920" />
</p>

> 截图由 Playwright 从当前前端构建自动生成，反映最新界面状态。运行 `npm run test:screenshots` 即可刷新。

---

## 🏗️ 系统架构

```mermaid
flowchart LR
    Browser["React 前端<br/>连续学习旅程"] --> API["answer-service<br/>FastAPI :8000"]
    API --> Runtime["Learning Agent Runtime<br/>ask / plan / practice"]
    Runtime --> Quality["Guardrail + Answer Finalizer"]
    Runtime --> PG["PostgreSQL 16<br/>用户 / 学习事实 / Agent 账本"]
    Runtime --> ES["Elasticsearch 8.11.3<br/>lexical + vector candidates"]
    Runtime --> Redis["Redis 7<br/>answer / image cache"]
    Runtime --> LLM["DashScope<br/>Qwen + Embedding"]
    Runtime --> Viz["viz-service<br/>数学可视化"]
    ES --> Fuse["RRF + rerank + threshold"]
    Fuse --> Runtime
```

**运行边界**

- PostgreSQL 是业务事实层；Elasticsearch 只保存可重建的检索索引，命中返回前必须回表校验账号、状态和范围。
- Redis 只承担答案与图片性能缓存，不保存会话、记忆或学习事实的唯一副本。
- `migrate` 与 `answer-service` 复用同一自包含镜像；镜像同时包含 `app` 与 `shared`，避免迁移和运行时契约漂移。
- Agent 使用固定阶段编排，不允许模型自由选择工具；离线报告只提供人工晋级资格，不自动修改默认策略。

---

## 🛠️ 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | React 18、TypeScript 5、Vite 6、Ant Design、Valtio、Axios、KaTeX |
| API 与编排 | Python 3.11、FastAPI、Pydantic 2、SQLAlchemy Async、Alembic |
| 模型 | 阿里云百炼 DashScope / 通义千问、`text-embedding-v3` |
| 数据 | PostgreSQL 16、Redis 7、Elasticsearch 8.11.3 |
| 测试 | unittest、Vitest、Playwright、axe、确定性 Answer / RAG / Agent eval runners |
| 运行 | Docker Compose；前端本地使用 Vite，发布证据由 release CLI 统一编排 |

---

## 🚀 快速开始

完整说明见 [快速开始跑起项目](docs/quick-start.md)。推荐用统一刷新命令拉取兼容镜像、重建应用、执行迁移并校验健康状态：

**1 · 启动后端**

```bash
cd shenxue_backend/shenxue-ai
cp env.example .env
# 编辑 .env，至少填写 DASHSCOPE_API_KEY
make refresh
```

**2 · 启动前端**

```bash
cd ../../shenxue_frontend
npm install
npm run dev
```

**3 · 本地访问**

| 服务 | 地址 |
| --- | --- |
| 前端 | `http://127.0.0.1:5181` |
| 后端 API | `http://127.0.0.1:8000/v1` |
| Swagger | `http://127.0.0.1:8000/docs` |
| 存活探针 | `http://127.0.0.1:8000/health` |
| 就绪探针 | `http://127.0.0.1:8000/ready` |

> `make refresh` 保留 PostgreSQL、Redis 和 Elasticsearch volumes，会把数据库升级到当前 Alembic head 并幂等补齐 taxonomy 种子。不要用 `make clean` 做普通更新——该命令会删除数据卷。

默认镜像策略：应用跟随 `python:3.11-slim-bookworm` 兼容安全补丁线，PostgreSQL / Redis 跟随 `16-alpine` / `7-alpine`，Elasticsearch 固定为已验证的 `8.11.3`。所有镜像地址和 PyPI 源都可通过 `env.example` 覆盖。

---

## 📂 项目结构

```text
.
├── README.md / README.en.md      # 项目总入口（中 / 英）
├── AGENTS.md                     # 协作约定与验证矩阵
├── 深学AI后端架构讲解.md          # 面向课堂的后端架构教案
├── docs/                         # 用户、开发、API、归档与启动文档
│   ├── api/                      # 稳定接口参考与 manifest
│   ├── dev/                      # 工程文档：运行时、Agent、质量门禁
│   ├── user/                     # 学习者视角操作说明
│   ├── archive/rag/              # RAG 开发与检索质量归档文档
│   └── assets/                   # README 产品预览截图
├── evals/                        # Answer、RAG、Agent 离线数据集与报告
├── release/                      # 第一版候选清单、缺陷登记与发布门禁
├── shenxue_frontend/             # React 学习工作台
│   ├── src/                      # 页面、组件、状态与 API 客户端
│   ├── e2e/                      # Playwright 旅程、无障碍与截图用例
│   └── scripts/                  # 契约校验、体积预算与质量门编排
└── shenxue_backend/shenxue-ai/
    ├── docker-compose.yml
    ├── Makefile                  # refresh / health / ready / release-* 目标
    ├── answer-service/           # 主 API 与 Agent/RAG 编排
    ├── viz-service/              # 数学可视化
    └── shared/                   # 跨服务契约模型
```

---

## 🔌 关键 API

所有业务接口位于 `/v1`：

| 模块 | 代表接口 |
| --- | --- |
| 运行状态 | `GET /health`、`GET /ready` |
| 账号画像 | `POST /v1/auth/register`、`POST /v1/auth/login`、`GET /v1/auth/me`、`PATCH /v1/auth/me/profile` |
| 会话问答 | `POST /v1/sessions/{session_id}/ask`、`GET /v1/sessions/{session_id}/messages` |
| Agent 反馈 | `POST /v1/agent-runs/{run_id}/feedback` |
| 学习计划 | `GET/POST /v1/learning-plans`、`POST /v1/learning-plans/generate`、`POST /v1/learning-plans/{plan_id}/renew` |
| 练习与错题 | `POST /v1/practice-sets/generate`、`POST /v1/practice-sets/{id}/submissions`、`GET/PATCH /v1/wrong-questions*` |
| 教学资料 | `POST /v1/knowledge-sources`、`POST /v1/knowledge-sources/uploads`、`GET /v1/knowledge-sources/{id}/chunks`、`GET/PATCH /v1/knowledge-sources*` |
| RAG 观测 | `GET /v1/retrieval/stats` |
| 缓存观测 | `GET /v1/cache/stats`、`DELETE /v1/cache/clear`（调试面板用，默认前端不展示） |
| 学习事实 | `GET /v1/learning-traces` |
| 学科与知识点 | `GET /v1/subjects`、`GET /v1/taxonomy` |
| 长期记忆 | `GET/POST/PATCH/DELETE /v1/memories*` |

产品主问答路径是 session ask。兼容 `/v1/ask` 与 `/v1/ask/sync` 保留调试价值，但不会创建完整的 session Agent 运行事实。

### SSE 事件

正常会话问答按以下语义交付：

`start → memory? → retrieval? → cache? → text* → final → visualization? → done`

`text` 是未通过最终质量门的草稿；`final` 最多一次，客户端必须用其原子替换草稿。失败以 `error` 结束，不得把未最终化文本保存为成功回答。

---

## ✅ 验证

```bash
# 后端全量测试
cd shenxue_backend/shenxue-ai/answer-service
python -m unittest discover -s tests -p 'test_*.py'

# 前端完整质量门：契约、单元/组件、构建、体积、旅程与无障碍
cd ../../../shenxue_frontend
npm run test:quality

# Compose 与运行状态
cd ../shenxue_backend/shenxue-ai
docker compose config --quiet
make migration-check
make health
make ready
make data-status
```

> 发布候选必须在目标提交的干净工作树执行 [第一版发布质量门禁](docs/dev/v1-release-quality-gates.md)。Mock 浏览器测试不能替代真实服务 smoke 和数据库演练。

---

## 📚 文档中心

### 入门与运行

| 文档 | 用途 |
| --- | --- |
| [快速开始](docs/quick-start.md) | 首次启动、完整刷新、镜像源覆盖、验收与故障排查 |
| [前端项目说明](shenxue_frontend/README.md) | 前端路由、状态边界和质量命令 |
| [后端服务说明](shenxue_backend/shenxue-ai/README.md) | Compose 服务、配置、迁移和后端开发入口 |
| [后端架构讲解](%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) | 面向课堂的服务、数据与请求链路讲解 |
| [生产运行加固](docs/dev/production-runtime-hardening.md) | migration、配置门禁、限流、探针、错误与日志 |

<details>
<summary>🤖 Agent、检索与回答质量</summary>

| 文档 | 用途 |
| --- | --- |
| [Learning Agent Runtime](docs/dev/learning-agent-runtime.md) | 固定阶段 Runtime、账本、失败终态与策略身份 |
| [Agent 评测与策略晋级](docs/dev/agent-evaluation-policy-promotion.md) | 总体评测、组件证据、聚合信号与人工晋级 |
| [回答最终质量](docs/dev/answer-quality-finalization.md) | 最终化策略、长度格式、引用与离线门禁 |
| [学习护栏](docs/dev/learning-guardrails.md) | 输入输出护栏、学科边界与安全拒答 |
| [教学资料入库](docs/dev/knowledge-source-ingestion.md) | 上传、解析、切块、向量化与状态机 |
| [RAG 开发指南](docs/archive/rag/rag-development-guide.md) | 资料入库、检索、引用、grounding 和边界 |
| [RAG 检索质量与观测](docs/archive/rag/rag-retrieval-quality-observability.md) | chunk、双路召回、RRF、rerank、阈值、离线评测与观测口径 |
| [学习结果事件闭环](docs/dev/learning-outcome-event-loop.md) | 五类事件、幂等、归因和隐私边界 |

</details>

<details>
<summary>🔌 接口参考</summary>

| 文档 | 用途 |
| --- | --- |
| [接口清单 manifest](docs/api/manifest.yaml) | 稳定接口索引与版本状态 |
| [Agent 运行反馈接口](docs/api/agent-run-feedback.md) | `POST /v1/agent-runs/{run_id}/feedback` 契约 |
| [回答最终质量接口](docs/api/answer-quality-finalization.md) | final 事件与质量字段契约 |
| [账号与画像接口](docs/dev/auth-profile-api.md) | 注册、登录、JWT 与画像字段 |
| [学习计划接口](docs/dev/learning-plan-api.md) | 计划生成、续期与任务流转 |
| [练习接口](docs/dev/practice-api.md) | 练习生成、提交、逐题反馈与错题 |
| [学习事实接口](docs/dev/learning-trace-api.md) | QA / Practice Trace 查询口径 |
| [K12 Taxonomy 接口](docs/dev/k12-taxonomy-api.md) | 学段学科知识点树与种子数据 |

</details>

<details>
<summary>🛡️ 质量与协作</summary>

| 文档 | 用途 |
| --- | --- |
| [第一版发布质量门禁](docs/dev/v1-release-quality-gates.md) | preflight、live smoke、数据库演练与 go/no-go |
| [前端质量自动化](docs/dev/frontend-quality-automation.md) | Playwright、axe、bundle budget 与统一入口 |
| [前端响应式外壳](docs/dev/frontend-responsive-shell.md) | desktop/tablet/mobile 布局契约与 shell 校验 |
| [Git 提交约定](docs/dev/git-workflow.md) | 英文类型/scope、中文摘要/说明及范围边界 |
| [协作约定 AGENTS.md](AGENTS.md) | CodeStable 工作流、验证矩阵与提交边界 |

</details>

学习者视角的操作说明位于 [`docs/user/`](docs/user/)：[学习计划](docs/user/learning-plan.md)、[练习](docs/user/practice.md)、[错题本](docs/user/wrong-questions.md)、[回答反馈](docs/user/answer-feedback.md)、[学习画像](docs/user/learner-profile.md)。

---

## 🚧 当前边界

第一版仍未覆盖：

- 密码找回、邮箱验证、refresh token、第三方登录及学校 / 班级 / 多角色权限。
- 教材与 taxonomy 管理后台、OCR / 图片教材理解、外部语义 reranker、资料原文定位阅读器。
- 自动掌握度、自动画像回写、学习报告与教师 dashboard。
- 自动训练、自动策略发布和在线内容自动标注；当前数据飞轮只提供可审计事实与人工评测输入。
- 集中 secret manager、WAF、定时自动备份、跨区域灾备和独立 telemetry 平台。

---

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源。

---

## ⚠️ 免责声明

AI 回答可能存在错误，不能替代教师判断或正式教学评价。用于真实教学场景前，请完成内容审核、权限、审计、隐私与数据合规评估。