MemoryPath 学迹 · AI 伴学与智能体协同平台

面向学生、教师与平台管理员的 AI 学习协同系统

核心能力 · 系统架构 · 快速启动 · 默认账号 · 项目文档

项目定位

MemoryPath（学迹）是一套围绕“学习行为记录、学情记忆、知识库检索、教师智能体协作”构建的全栈系统。它不只是一个聊天应用，而是尝试把 AI Agent 融入学生学习、教师教学和平台运维的日常工作流中。

平台面向自学、学校、培训与实验室等多场景，核心采用“学习行为记录 + 自适应 Memory 机制 + 共享知识库 + 教师 Agent 工作流”，通过长周期陪伴、智能复盘和可追踪教学动作，辅助学习者高效成长。

视觉与 UI 风格

• 原生级淡色与暗色模式支持。
• 统一侧边栏自适应布局，主仪表盘承载全局导航，子页面保持更聚焦的工作视野。
• 采用克制的蓝色主调、清晰的信息层级和细腻的交互反馈，兼顾学习产品的安静感与 Agent 平台的专业感。

系统面向三类用户：

角色	核心价值	关键入口
学生	获得长期陪伴式学习支持，沉淀个人学情记忆	仪表盘、AI 伴学、月历计划、知识库、学习路径、成长全览
教师	观察班级态势，发现需要介入的学生，生成教学动作	工作台、学生列表、任务管理、路径任务、班级学情记忆看板
管理员	管理用户、模型配置、系统运行状态	管理概览、用户管理、模型配置、系统设置

品牌与登录页

• 平台品牌统一为 MemoryPath 学迹（缩写 MP），英文名用于产品标识，中文“学迹”用于中文语境，实现代码、文档与部署配置已同步更新。
• 登录页采用「品牌主视觉 + 登录表单」双栏布局，浅色 / 深色各一套主视觉，随平台主题自动切换；移动端收敛为单列表单。
• 品牌资源位于 web/public/brand/（主视觉与 LOGO），站点图标为 web/public/favicon.png。

浅色模式	深色模式

核心能力

学生端

• AI 伴学助手：支持对话、上下文开关、学情记忆引用、待办/任务/日历/知识库上下文关联。
• 学习行为记录：专注心跳、任务完成、B 站学习、AI 对话均可计入活跃度。
• 个人仪表盘：待办、导师任务、学术便签、学习热力图、模块排序。
• 学习路径：教师发布路径任务，学生按阶段推进并提交成果。
• 成长全览：汇总路径进度、学习趋势、学情记忆卡片。

教师端

• 教学工作台：班级态势驾驶舱，聚合班级指标、路径趋势、学情洞察、需关注学生、待办队列与教师 Agent 动作面板。
• 学生管理：查看学生概况、复盘日志、学情分析与任务状态。
• 任务管理：创建普通任务、查看提交、批改反馈。
• 路径任务：用 AI 把教学目标拆成阶段、节点和资源。
• 班级学情洞察看板：把学情记忆、路径进度和待批改提交转成带证据链的教师洞察。
• 大量学生选择器：创建班级、发布任务、分配路径时支持搜索、筛选、分页和已选名单管理。

管理端

• 用户管理：学生、教师、管理员账号管理。
• 模型配置：按任务类型配置大模型能力，例如学生对话、每日复盘、记忆提取、路径生成等。
• 系统设置：维护平台级运行配置。

系统架构

flowchart LR
  subgraph Client["Web Client"]
    Vue["Vue 3 + TypeScript"]
    Router["Vue Router"]
    UI["Element Plus + Tailwind CSS"]
  end

  subgraph API["FastAPI Backend"]
    Auth["认证与权限"]
    Learning["学习路径与班级"]
    Memory["学情记忆服务"]
    Knowledge["知识库与向量检索"]
    Notification["通知与 WebSocket"]
    LLM["模型网关"]
  end

  subgraph Infra["Infrastructure"]
    Postgres["PostgreSQL"]
    Redis["Redis"]
    Qdrant["Qdrant"]
    MinIO["MinIO"]
    Celery["Celery Worker / Beat"]
  end

  Vue --> Router
  Router --> API
  API --> Postgres
  API --> Redis
  API --> Qdrant
  API --> MinIO
  API --> Celery
  LLM --> SiliconFlow["OpenAI Compatible LLM API"]

Loading

技术栈

层级	技术
前端	Vue 3, TypeScript, Vite, Vue Router, Pinia, Element Plus, Tailwind CSS, lucide-vue-next
后端	FastAPI, SQLAlchemy Async, Alembic, Pydantic, JWT
数据	PostgreSQL, Redis, Qdrant, MinIO
异步任务	Celery Worker, Celery Beat
AI	OpenAI-compatible LLM Gateway, SiliconFlow, Embedding Model
部署	Docker Compose, Nginx, Cloudflare Tunnel

目录结构

studyPartner/
├── web/                         # Vue 3 前端
│   ├── src/api/                 # Axios API 模块
│   ├── src/views/               # 学生端、教师端、管理端页面
│   ├── src/components/          # 通用组件
│   ├── public/brand/            # 品牌主视觉、LOGO 与站点图标
│   └── src/utils/               # 前端展示工具
├── server/                      # FastAPI 后端
│   ├── app/api/                 # API 路由
│   ├── app/models/              # SQLAlchemy 模型
│   ├── app/services/            # 业务服务
│   ├── app/tasks/               # Celery 异步任务
│   └── alembic/                 # 数据库迁移
├── docs/                        # 产品、架构、API、数据库和设计文档
├── docker-compose.yml           # 开发环境编排
├── docker-compose.prod.yml      # 生产环境编排
└── .env.example                 # 环境变量模板

快速启动

环境要求

• Node.js 20+
• Python 3.11+
• Docker Desktop 或 Docker Engine
• PostgreSQL / Redis 可由 Docker Compose 自动拉起

Windows 一键启动

本仓库提供一组 Windows 脚本，方便在本地开发和演示时启动系统。公开仓库只包含通用脚本和配置模板，不包含任何 Cloudflare Tunnel 的真实域名、Tunnel ID、凭据路径或 API Key。

脚本	用途
start-dev.bat	启动开发依赖容器、后端 8001、前端 5173
stop-dev.bat	关闭由脚本启动的前端和后端进程，保留数据库等容器
start-tunnel.bat	按本机私有 local.tunnel.env 启动 Cloudflare Tunnel
stop-tunnel.bat	只关闭匹配当前项目私有配置的 Cloudflare Tunnel 进程
deploy.bat	使用 docker-compose.prod.yml 构建并启动生产编排

首次在自己的电脑使用隧道脚本时，复制模板并填入本机私有信息：

Copy-Item local.tunnel.env.example local.tunnel.env

local.tunnel.env 已被 .gitignore 排除，请只在本机维护真实域名、cloudflared 配置路径和端口。正常演示流程：

.\start-dev.bat
.\start-tunnel.bat

结束演示：

.\stop-tunnel.bat
.\stop-dev.bat

1. 准备环境变量

cp .env.example .env

至少建议配置：

JWT_SECRET_KEY=change_me_generate_with_openssl_rand_hex_32
SILICONFLOW_API_KEY=
SMTP_HOST=
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM_EMAIL=

2. Docker Compose 启动全套基础设施

docker compose up -d

服务默认端口：

服务	地址
前端开发服务	http://localhost:5173
后端 API	http://localhost:8000
API 文档	http://localhost:8000/api/docs
PostgreSQL	localhost:15432
Redis	localhost:6379
Qdrant	http://localhost:6333
MinIO Console	http://localhost:9001

3. 初始化种子数据

docker compose exec backend python -m app.seed

4. 本地前端开发

cd web
npm install
npm run dev

5. 本地后端开发

cd server
pip install -r requirements.txt
uvicorn app.main:app --reload

6. 本地异步任务

cd server
celery -A app.core.celery_app:celery_app worker --loglevel=info -P threads
celery -A app.core.celery_app:celery_app beat --loglevel=info

默认账号

种子脚本会创建以下测试账号：

角色	用户名	密码
学生	student	student123
教师	teacher	teacher123
管理员	admin	admin123

常用命令

# 前端构建
cd web && npm run build

# 开发环境容器
docker compose up -d
docker compose ps
docker compose logs -f backend

# 停止环境
docker compose down

# 生产部署脚本
chmod +x deploy.sh
./deploy.sh

产品路线图

已完成或已具备基础能力

• 学生端 AI 伴学对话与学情记忆管理。
• 学习路径生成、发布与提交。
• 教师端任务、学生、班级看板。
• LearningInsight 班级洞察引擎与证据链。
• 教师工作台首屏重构为班级态势驾驶舱。
• 教师 Agent 工作台首版：支持生成班级简报、干预计划、分层任务草稿和反馈话术。
• 教师端大量学生选择器。
• 管理端模型配置。
• WebSocket 通知、Celery 定时复盘、知识库基础能力。
• 学生个人信息与显示姓名口径统一。
• MemoryPath 学迹品牌升级与全新登录页：浅色 / 深色主视觉、品牌 LOGO、favicon 与主题持久化。

下一阶段重点

• 洞察动作闭环：把洞察建议动作接入任务生成、提醒草稿、简报生成和干预计划。
• 大量学生选择器增强：增加按班级筛选、导入学号名单、保存常用分组。
• Agent 审计与工具调用：所有 AI 建议和动作需要可追溯、可确认、可回滚。

项目文档

文档	说明
教师端与 Agent 平台重构设计方案	教师仪表盘、班级洞察、Agent 工作台和大量学生选择器设计
LearningInsight 洞察引擎设计	洞察模型、生成来源、API、状态闭环
StudentPickerDialog 设计说明	大量学生选择器的组件合同、接口和协议边界
学习路径规划器设计	教学设计框架、场景模板、节点产出与完成标准
UI 设计与界面交互规范	视觉系统、页面规范、交互状态
系统架构设计	平台整体架构与模块划分
API 设计	后端接口设计文档
数据库设计	数据表、索引、关系说明
AI Memory 设计	学情记忆机制与数据流
学习路径与班级记忆设计	路径任务、班级看板、记忆聚合设计
部署指南	生产部署、容器、运维说明

设计原则

• 以行动为中心：老师看到的不是指标堆叠，而是可执行建议。
• 证据优先：Agent 结论必须能追溯到对话、复盘、任务提交或学习行为。
• 人在回路：发布任务、发送通知、删除记忆、批量改动都需要人工确认。
• 长期陪伴：学生端围绕长期学习画像和持续复盘设计，不做一次性问答工具。
• 大规模可用：所有班级、学生、任务选择器必须能承载真实班级规模。

许可证

本项目采用 Apache License 2.0 开源协议。

当前新增的 StudentPickerDialog 与教师端洞察组件均为项目内自研实现，未复制第三方组件站源码。后续如引入外部开源组件，请在合并前确认许可证兼容性，并在 README、NOTICE 或第三方声明文档中补充归属信息。