StepSage 渐知学伴

面向学生与家长的 AI 学习伙伴产品。每天进步一点点——AI 根据掌握情况安排讲解、练习和复习，家长只看到必要、友好的成长摘要。

项目结构

StepSage/
├─ Companion/   # 渐知学伴：学生与家长完整业务产品
├─ docs/        # 产品设计、架构与实施文档
└─ DeepTutor/   # 上游 AI 教学内核（只读，独立获取）

• Companion/ 是独立的学生/家长学习产品，拥有后端 API、前端 PWA、数据库、课程包和部署配置。
• DeepTutor/ 是上游兼容的通用 AI 内核，只读引入，不纳入本仓库。
• 唯一依赖方向：Companion → DeepTutor，通过 Companion/backend/family_learning/integrations/deeptutor/ 单点适配。

核心功能

• 家庭身份：家长创建家庭、添加孩子，学生不需要手机号
• 渐知学习法：诊断→讲解→练习→反馈→复习，一次只学一个知识点
• 掌握追踪：每个掌握状态可追溯到题目、提示等级和独立作答记录
• 单 Lesson 写控制：租约、心跳、显式接管，防止共用设备冲突
• 家长周报：只使用学习证据，不默认展示孩子逐句对话
• 数据导出/删除：家长可随时导出或删除家庭全部数据
• DeepTutor 隔离：deny-by-default adapter，高风险工具默认拒绝
• PWA：可安装到桌面，离线 shell，私有 API no-store

技术栈

层	技术
后端	Python 3.11+ / FastAPI / SQLAlchemy 2.0 (async) / Alembic
前端	Next.js 16 (App Router) / React 19 / TypeScript 5.8
数据库	SQLite (本地) / PostgreSQL 16 (服务器)
缓存/队列	Redis 7 (服务器) / 本地内存队列 (开发)
对象存储	MinIO / S3 (服务器) / 本地文件 (开发)
打包	PyInstaller (原生二进制)

快速开始

方式一：原生可执行包（零依赖，面向最终用户）

构建者运行：

cd Companion
python scripts/build.py

• Windows 上产出 dist/StepSage-0.1.0-win-x64.zip
• Linux 上产出 dist/StepSage-0.1.0-linux-x64.tar.gz（需在 Linux 机器上构建）

最终用户：解压 → 双击 run.bat（Windows）或 ./run.sh（Linux）→ 浏览器自动打开 http://localhost:4100。无需安装 Python、Node.js 或数据库。

方式二：本地开发

# 后端
cd Companion
pip install -e ".[dev]"
set PYTHONPATH=backend      # Windows; Linux 用 export
alembic upgrade head
family-learning              # 启动 API，端口 4101

# 前端（另一个终端）
cd Companion/frontend
npm install
npm run dev                  # 启动 Web，端口 4100

• API: http://localhost:4101/api/v1/family/health
• Web: http://localhost:4100

方式三：Docker Compose（服务器部署）

cd Companion
docker compose up --build

构建原生可执行包

cd Companion
python scripts/build.py [--clean] [--version 0.1.0]

构建流程：环境检查 → 前端静态导出 → PyInstaller 打包 → 组装发布包 → smoke test 自检。

产物结构：

StepSage-<version>-<platform>/
├─ StepSage          # 可执行后端（Win 为 .exe）
├─ _internal/        # PyInstaller 运行时
├─ web/              # 前端静态文件
├─ content/          # 课程包
├─ .env              # 配置（默认 SQLite 开箱即用）
├─ run.bat / run.sh  # 启动器
└─ README.txt

PyInstaller 不支持交叉编译。Windows 包在 Windows 上构建，Linux 包在 Linux 机器上构建。

文档

• 产品设计与实施蓝图
• 实现状态
• 跨平台打包设计
• 打包实现计划

端口约定

服务	端口
单体包（前后端同源）	4100
开发模式后端 API	4101
开发模式前端 Web	4100

License

私有项目，版权所有。