ailearning 机构智能学习平台

一个面向线下培训机构的多租户智能学习平台。平台方管理机构、模型和计费策略，机构管理自己的校区，校区管理教师与学生，学生在中文学习空间中完成教材测评、查缺补漏和知识点学习。

• 项目定位
• 功能概览
• 角色与入口
• 学习流程
• 快速启动
• 首次配置
• 配置说明
• 数据与安全
• 项目结构
• 测试与检查
• 开源协议与第三方项目

这个项目把 DeepTutor 的智能对话、问题生成、知识检索和学习能力，组织成培训机构可以运营的业务系统：

平台运营中心
  └── 机构客户
        ├── 校区 A ── 教师 / 学生 / 班级
        ├── 校区 B ── 教师 / 学生 / 班级
        └── 点数分配、设备上限、有效期和使用统计

平台服务端通过 OpenAI 兼容接口连接 New API 或其他中转服务。学生端不会接触服务端 Key，模型由平台管理员统一指定，机构只管理自己的额度和人员。

• 适合本地部署、局域网部署和二次开发。
• 业务功能正在持续完善，生产环境使用前应完成权限、备份、HTTPS、日志和压力测试。
• 项目不附带教材、题库、模型权重或任何 API Key。
• 文档、教材和模型输出可能受第三方版权或服务商条款约束，使用者需要自行确认合规性。

• 机构客户、校区、平台账户和角色权限管理。
• 给机构充值点数，设置设备总上限、有效期和使用限制。
• 模型同步、启用模型、默认模型和业务功能模型分配。
• New API 地址、服务端专用 Key 和连接测试配置。
• 按模型、业务功能、机构和时间统计调用量与点数消耗。
• 可调的上游价格、汇率、功能倍率、机构系数、最低消费和固定点数。
• 教材上传、年级/学科/版本/上下册信息维护和处理状态查看。
• AI 提取教材章节与核心知识点，并生成知识关系图谱。
• 测评题库生成、发布、归档和删除。

• 机构管理员创建多个校区，并向校区分配点数、设备上限和有效期。
• 校区管理员创建、修改和删除学生账号，学号自动生成。
• 管理教师、教务、校区管理员、班级和校区本地档案。
• 学生数据导入、导出和备份。
• 从机构进入校区，再查看学生的教材、测评和知识点掌握度。

• 中文、面向学生的简洁学习主页，不要求学生配置模型。
• 在个人资料中按学科确定教材版本，系统自动关联同版本上下册。
• 数学、语文等学科独立维护学习进度、知识图谱和测评记录。
• 首次测评覆盖教材核心章节，一道题可以关联多个知识点。
• 交卷后分析正确率、题型、难度和相关知识点。
• 对不确定的薄弱点自动安排深入测试，区分当前知识和前置知识问题。
• 根据测评结果生成查缺补漏任务、知识点练习和学习计划。
• 知识地图支持缩放、拖动、全局预览和按节点查看关系。
• AI 对话作为辅助入口；测评、查缺补漏和复习任务由系统自动安排。

• 本地优先提取 PDF 文本和目录书签，减少不必要的多模态调用。
• 优先以教材目录构建章节层级，再生成章节内的核心知识点。
• 避免把定义中的单个例子拆成过细的知识节点。
• 自动生成章节归属、前置关系和递进关系，管理员可以查看和修改。
• 整本分析超时或上游不可用时，支持按章节降级处理。

旧的 /campus 地址保留学生与校区管理的入口选择页；它不是校区管理后台。

产品名和 Python 发行名为 ailearning，前端包名为 ailearning-web。为兼容上游引擎与已有部署，内部 deeptutor 模块、DEEPTUTOR_* 环境变量和本地存储键保持不变，原 deeptutor CLI 命令作为兼容别名保留。开源来源和版权声明不随产品改名而移除。

校区创建学生账号
       ↓
学生登录并完善年级、学科教材
       ↓
选择“从未系统学过 / 学过一部分 / 不确定”
       ↓
进入教材测评或系统安排的学习任务
       ↓
标准测评覆盖教材核心章节和综合知识点
       ↓
AI 判卷并分析知识点、题型、难度与错误思路
       ↓
对不确定的薄弱点进行深入测评
       ↓
区分当前知识问题与前置知识问题
       ↓
自动生成查缺补漏、复习和提前学任务

学习情况用于安排测评起点、难度与前置知识检查范围。这部分流程仍在完善，正式运营前需要验证不同选择下的测评入口和后续任务。

计费简化公式：

消费点数 = max(
  最低消费点数,
  ceil(上游成本 × 每元点数 × 全局倍率 × 模型倍率 × 功能倍率 × 机构系数)
  + 固定功能点数
)

价格调整会产生新的价格版本，历史调用保留当时的价格快照。

安装 Python 3.11、3.12 或 3.13、Node.js 20 或更高版本及 npm，并确保可以访问 New API（如果使用 AI 功能）。然后在项目根目录双击：

启动ailearning.bat

启动脚本会创建或检查 .venv、安装后端和前端依赖、启动前后端、检查服务状态并打开平台运营中心。

默认地址：

平台运营中心：http://localhost:3782/admin/commercial
机构管理中心：http://localhost:3782/organization
校区管理中心：http://localhost:3782/campus-admin
学生登录：http://localhost:3782/student/login
后端 API：http://localhost:8001

如果 3782 被占用或被 Windows 保留，启动脚本会选择可用端口，并在命令行打印实际地址。启动窗口会持续显示日志；关闭窗口或按 Ctrl+C 会停止本次启动的服务。

启动器会让前端绑定 0.0.0.0。同一局域网手机可以访问运行电脑的局域网 IP，例如：

http://192.168.1.100:3782/student/login

实际端口以启动命令行输出为准。Windows 防火墙需要允许对应端口，生产环境不要直接把管理后台暴露到公网。

平台管理员打开“API 与模型”页面：

1. 填写 New API 基础地址和服务端专用 Key。
2. 保存配置并测试连接。
3. 同步模型，指定默认模型和业务功能模型。
4. 配置模型价格和各 AI 功能的点数倍率。
5. 创建机构、充值并设置有效期、设备上限。
6. 创建机构管理员，机构管理员再创建校区并分配额度。
7. 校区管理员创建教师和学生账号。

服务端 Key 不会下发给学生或校区浏览器。管理后台保存的 Key 会加密写入商业数据库；如果同时设置了环境变量，环境变量优先。推荐使用 New API 管理员创建的专用服务 Key，并在 New API 侧限制来源 IP、允许模型和访问范围。

上传教材时填写年级、学科、教材名称、出版社/版本、上下册或学期以及 PDF 文件。处理完成后应抽查章节、核心知识点和关系，再发布给学生。

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Push-Location web
npm ci
Pop-Location

分别启动后端和前端：

# 终端一：后端
.\.venv\Scripts\python.exe -u -m deeptutor.api.run_server

# 终端二：前端
Push-Location web
npm run dev -- --hostname 0.0.0.0 --port 3782
Pop-Location

容器化部署请先阅读 CONTAINERIZATION.md 和对应的 compose*.yaml。优先从本仓库源码构建；使用 docker-compose.ghcr.yml 时必须设置 AILEARNING_IMAGE 为自己的镜像，不要拉取上游 DeepTutor 镜像代替本项目。镜像发布工作流仅支持手动触发，未预设 PyPI 自动发布。

可以使用后台保存 New API 配置，也可以在服务端环境中提供配置：

NEW_API_BASE_URL=https://your-new-api.example.com
NEW_API_SERVICE_KEY=sk-server-only-key
NEW_API_TIMEOUT_SECONDS=180
DEEPTUTOR_COMMERCIAL_JWT_SECRET=replace-with-a-long-random-secret
# 可选：DEEPTUTOR_COMMERCIAL_MASTER_KEY=<Fernet key>
# 可选：DEEPTUTOR_COMMERCIAL_DB=E:\ailearningData\commercial.db

模板见 .env.example 和 config/commercial.ps1.example。真实配置、数据库、密钥和运行日志不要提交到 Git。

• 不要提交 .env、config/commercial.ps1 中的真实值、SQLite 数据库、.master.key、运行日志、学生资料或教材文件。
• 生产环境必须设置强随机的 DEEPTUTOR_COMMERCIAL_JWT_SECRET，并备份商业数据库和加密主密钥。
• New API Key 只存在服务端；客户端请求必须经过服务端身份、权限、余额和限额检查。
• 管理后台、机构后台和校区后台应使用 HTTPS、强密码和最小权限账户。
• SQLite 适合单机和小规模部署；多实例部署前应评估共享存储、锁竞争、备份和数据库迁移方案。
• 学生学习记录、联系方式、教材和答题内容属于敏感业务数据，应按适用的隐私和数据保护要求处理。
• 上传教材前确认拥有使用、存储、解析和展示该教材的权利。AI 生成内容和自动判卷应允许教师复核。

deeptutor/                  # Python 核心、API、Agent、解析和商业业务
  api/                      # FastAPI 应用和统一 API
  commercial/               # 机构、校区、学生、教材、测评、计费
  capabilities/             # 多阶段能力，如 chat、deep_solve、deep_question
  tools/                    # 可调用工具注册与实现
  services/                 # LLM、解析、RAG、配置和运行时服务
deeptutor_cli/              # CLI 入口
web/                        # Next.js + React 前端
  app/                      # 平台、机构、校区和学生页面
  features/commercial/      # 商业平台组件和知识图谱视图
  lib/                      # API 客户端、类型和前端工具
scripts/                    # 启动、健康检查和开发脚本
docs/                       # 部署、交互和业务说明
tests/                      # Python/API 测试
LICENSE                     # Apache License 2.0
THIRD_PARTY_NOTICES.md      # 第三方声明

.\.venv\Scripts\python.exe -m compileall deeptutor deeptutor_cli
.\.venv\Scripts\python.exe -m pytest

Push-Location web
npm run build
npm run test:node
npm run lint
Pop-Location

商业平台改动至少验证 /admin/commercial、/organization、/campus-admin、/student/login、/student、/student/papers、/student/knowledge 和 /student/followups。

欢迎提交 Issue、文档改进和 Pull Request。提交前请从最新代码创建分支，不提交密钥、数据库、学生数据、教材文件或构建产物；涉及权限、计费、教材处理和学生流程的改动应补充回归测试，并说明配置、接口和数据迁移影响。

详细贡献约定见 CONTRIBUTING.md。

本项目按 Apache License 2.0 发布。重新分发或修改时，请保留许可证、版权和第三方声明，并遵守 Apache 2.0 对修改文件标注、专利授权和免责声明的要求。Apache 2.0 不会自动授予教材、题库、模型、品牌、商标、用户数据或外部 API 的使用权。

下表是主要上游和直接使用的开源项目，不是完整依赖清单；完整版本以 pyproject.toml 和 web/package.json 为准。

项目还使用 OpenAI、Anthropic、DashScope、New API 等外部模型或中转服务的 SDK/兼容接口。它们不是本仓库内置的模型，也不代表这些服务商对本项目的背书。调用费用、内容政策和数据规则以对应服务商为准。

新增依赖或复制第三方代码时，请同时更新依赖清单、许可证说明和 THIRD_PARTY_NOTICES.md。

本仓库沿用了 DeepTutor 的研究和工程基础。引用上游研究时请参考 CITATION.cff：

@article{zhao2026deeptutor,
  title   = {DeepTutor: Towards Agentic Personalized Tutoring},
  author  = {Zhao, Bingxi and Zhang, Jiahao and Ren, Xubin and Guo, Zirui
             and Chu, Tianzhe and Ma, Yi and Huang, Chao},
  journal = {arXiv preprint arXiv:2604.26962},
  year    = {2026}
}

本软件按现状提供，不承诺适用于特定教学、商业或合规场景。部署者需要自行负责 API Key、账户、点数和个人数据安全，教材和题库的合法来源，AI 生成内容与自动判卷的人工复核，以及生产环境的备份、监控、升级、故障恢复和法律合规。使用本项目即表示你理解并接受 Apache License 2.0 中的免责声明和责任限制。