https://github.com/datawhalechina/whale-tutor
🐳 AI 驱动的开源交互式学习引擎
https://github.com/datawhalechina/whale-tutor
ai course-authoring datawhale deepseek education interactive-learning llm markdown mastery-learning nestjs typescript vue
Last synced: 4 days ago
JSON representation
🐳 AI 驱动的开源交互式学习引擎
- Host: GitHub
- URL: https://github.com/datawhalechina/whale-tutor
- Owner: datawhalechina
- License: agpl-3.0
- Created: 2026-05-08T02:00:53.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-19T02:58:27.000Z (about 2 months ago)
- Last Synced: 2026-05-19T04:38:15.762Z (about 2 months ago)
- Topics: ai, course-authoring, datawhale, deepseek, education, interactive-learning, llm, markdown, mastery-learning, nestjs, typescript, vue
- Language: TypeScript
- Homepage:
- Size: 2.9 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/datawhalechina/whale-tutor/actions/workflows/ci.yml)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://nodejs.org/)
[](https://github.com/datawhalechina/whale-tutor/stargazers)
[](CONTRIBUTING.md)
[](https://github.com/datawhalechina/whale-tutor/discussions)
## ⚡ 三秒钟看懂
| 你是谁 | 你能做什么 | 看哪里 |
| ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| 🎓 **学生 / 学习者** | 跟着已有课程交互式学习,卡住时 AI 出"换说法"题 + 求提示 | 找一个 [部署版](#-试一试)直接学 |
| ✍️ **课程作者**(老师/教研/内容编辑) | 写 markdown 讲稿 → AI 一键生成完整可交互课程 | [AUTHORING.md](AUTHORING.md) |
| 🛠️ **开发者** | 加新 pattern / 新 endpoint / 新 UI / 改架构 | [CONTRIBUTING.md](CONTRIBUTING.md) + [CLAUDE.md](CLAUDE.md) |
## 📸 看看长什么样
CLI 生成的课程 (`whale-tutor` 启动 + 运行中):
课程的若干交互模式：
## 它和 ChatGPT 直接对话有什么区别?
**ChatGPT 是开放对话**,没有路径设计、没有 mastery 跟踪、没有系统性推进。学完不知道学了什么,卡住没有兜底机制。
**Whale Tutor 是教学引擎**:
- 📐 **课程作者用 YAML 预设学习路径**(LO + 必做题 + adaptive 题型集),AI 在路径内动态出题 / 评估 / 兜底
- 🎯 **每个学习目标(LO, Learning Objective)有 mastery 状态机**(untouched → exposed → practicing → mastered)
- 🔁 **答错自动触发 AI 出"换说法"题**(同一概念换场景),连续错 3 次强制回 LO 讲解兜底
- 💡 **梯度提示(StuckProtocol)**:作者写 1-5 级 hint,没写则 AI 自动生成 3 级缓存
- 💬 **侧支 QA 提问**:答题时随时 drawer 提问 / 嵌套追问,不影响主路径
- 📊 **完整事件流**:每次学习者行为入 `events` 表,支持后续个体化档案 / 班级分析 / 群体智能
适合**我有教学体系,要帮学生系统学习**场景,不是"零散问问题"。
## 🎬 试一试
> **共同前置(三种方式都需要)**:
>
> - **Node.js ≥ 22**:[官网下载](https://nodejs.org/zh-cn/download)(LTS 版本即可),装完跑 `node --version` 看到 `v22.x` 就 OK
> - **MySQL ≥ 8.0**:可以直接装 [MySQL 官方版](https://dev.mysql.com/downloads/installer/)(Windows/Mac/Linux 都有);或者装 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 用容器跑(开发期推荐)
> - **DeepSeek API Key**(可选,但强烈推荐):去 [DeepSeek 平台](https://platform.deepseek.com/api_keys) 申一个,没有的话 AI 评估走 fallback 文案,但 `whale-tutor build` 不可用
### 路径 A:用 CLI(课程作者 / 试用学习者)⭐️ 推荐
#### 第一步(共同):创工作目录 + 装 CLI + 初始化
```bash
# 1. 装 CLI(全局,一次性) — 之后想升级到最新版重跑同一条命令即可:`npm install -g whale-tutor@latest`
npm install -g whale-tutor
# 2. 创工作目录(后续所有 whale-tutor 命令都在这里跑)
mkdir whale-workspace && cd whale-workspace
# 3. scaffold 完整 python-basics 示例 + whale-tutor.config.yaml 配置模板
whale-tutor init
# 4. 编辑 whale-tutor.config.yaml(填 mysql 连接 + 可选 DeepSeek key)
# 用任意编辑器打开都行,例如:
# Windows: notepad whale-tutor.config.yaml
# macOS: open -e whale-tutor.config.yaml
# Linux: nano / vim whale-tutor.config.yaml
# 或者直接用 VSCode 打开 whale-workspace/ 目录
# 5. 健康检查(强烈推荐第一次跑)
whale-tutor doctor # 检查 node / mysql / API key
```
完成共同步骤后,**留在 `whale-workspace/` 目录里**,二选一:
#### 选项 1 — 跑内置 python-basics 示例
```bash
whale-tutor start # 浏览器自动打开 http://localhost:3000
```
学完想加自己的课程?复制 `courses/python-basics/` 当模板手改,或者上选项 2。
#### 选项 2 — 用 AI 一键生成你自己的课程(交互式向导)
```bash
whale-tutor generate
```
这是个**交互式命令**,问几个问题就完事:
```
? 课程名字(中文 OK,如 "Pandas 数据分析入门"): Pandas 数据分析入门
? 生成方式 ([ai]=AI 自动写讲稿(推荐) / manual=我自己写 markdown): ai
? 课程主题/范围(可选,留空 AI 从课程名推断): pandas 读 csv / 筛选 / 聚合 / 简单可视化
? 目标受众(可选,如 "数据分析新手"): 有 Python 基础但没用过 pandas 的新手
? 章节数(留空 AI 自己定;一般 3-7): [auto]
```
回答完几分钟后,**完整可学的课程已经生成**。AI 干了三件事:
1. **写课程大纲** — 决定 course id / subject / 几个章节 / 每章主题
2. **逐章扩写 markdown 讲稿** — 每章 2000-3500 字,含代码示例 + 易错点段落
3. **自动跑 build pipeline** — 从 markdown 拆 LO + 出题 + 章末测试 → 完整 yaml/md 课程
跑完直接 `whale-tutor lint && whale-tutor start` 试学。AI 写的 markdown 讲稿留在 `-source/` 目录,**不满意可以手改后重跑 `whale-tutor build`**。
> 想自己写 markdown(不用 AI 写讲稿,只让 AI 拆 LO + 出题)?选 `manual` 模式 — 会 scaffold 一个最小源目录骨架,你写完讲稿后手工跑 `whale-tutor build` 即可。
详见 [AUTHORING.md §10](AUTHORING.md#10-whale-tutor-generate--build-ai-辅助生成课程)。完整课程作者教程见 [AUTHORING.md](AUTHORING.md)。
---
### 路径 B:clone 仓库 dev 模式(开发者)
适合**想给项目贡献代码、改架构、加新 pattern** 的开发者。需要额外装 [pnpm 8](https://pnpm.io/installation)(`corepack enable && corepack prepare pnpm@8.15.9 --activate`)+ 已经准备好 [Docker Desktop](https://www.docker.com/products/docker-desktop/):
```bash
# 1. 确认前置
node --version # ≥ v22
pnpm --version # ≥ 8
docker --version # 任意版本
# 2. clone + install
git clone https://github.com/datawhalechina/whale-tutor.git
cd whale-tutor
pnpm install
cp .env.example .env # 编辑填 DEEPSEEK_API_KEY(可选)
# 3. 起 mysql + build types + 并行跑前后端
pnpm db:up # docker compose 起 mysql:13306
pnpm build:types # 共享类型先 build 一次
pnpm dev # 并行起 web (5173) + server (3000)
# 浏览器开 http://localhost:5173
```
完整开发指南、scripts 列表、调试技巧 → [CONTRIBUTING.md §5](CONTRIBUTING.md#5-开发环境搭建)。
## ✨ 现有特性
**学习者体验**
- LO Intro 教学开场页(进入新 LO 先看核心讲解,点"开始练习"才进题)
- 4 种交互模式(`patternId`)覆盖大部分教学场景:
- `concept_check` — 概念辨析 4 选 1
- `code_sandbox` — 浏览器内 Pyodide 跑 Python,按测试用例 stdout 比对
- `spot_the_bug` — 给一段含 bug 的代码,选错误行号 + 写解释,AI hybrid 评估
- `free_recall` — 开放回忆,AI 按 rubric 关键点判覆盖度
- **梯度提示(StuckProtocol)** — 题目上方"求提示",作者写 1-5 级 hint,缺省走 AI 3 级 + cache
- **智能 PathOrchestrator** — 答错触发 AI 出同 LO 换说法题(`source='adaptive'`);连续错 3 次自动 review_lo 兜底回讲解;hint > 0 答对计入必做但不增 mastery
- **mastery 状态机**(untouched → exposed → practicing → mastered),mastered 连续错 2 次回归
- **多 LO 自动推进 + 章末测试解锁**(章末测试不进 retry)
- **多课程 / 多章节切换** — HomeView 课程卡片选课,LearnView 左侧 sidebar 列全部章节并允许跨章浏览
- **侧支 QA**(右侧 drawer 提问 + 多轮追问 + 结束回到原位)
**课程作者体验**
- **YAML + Markdown** 内容存储,`$ref` 长文外置;**修改内容不需要懂代码**
- **学科参数化** — `course.yaml` 的 `subject` 字段灌进所有 prompt,加新课程(SQL / Java / Pandas)无需改 prompt 模板
- **CLI(npm 包)** — `init / start / doctor / lint / build / generate` 6 个命令
- **`whale-tutor build`** — 写 markdown 讲稿(每章一份 md)→ AI 4 阶段生成完整 yaml/md 课程骨架
- **`whale-tutor lint`** — 5 秒校验所有 yaml/$ref/pattern 结构
**工程基建**
- **AI Gateway** — 唯一 LLM 调用入口,DeepSeek 兼容(可切其他 OpenAI 兼容服务),ajv schema 校验 + 重试 + fallback + 成本日志
- **Event Bus** — 学习者每次行为先写 events 表(事实表,不可变),其他派生表理论上可重建
- **完整事件流** — session / lo / interaction / mastery / chapter / qa / hint 全打点
**内置示例课程**(给你看怎么写,也可直接拿来给学习者跑)
| 课程 | 章节 | LO 数 |
| ----------- | --------------------------- | ----- |
| Python 基础 | 列表与迭代 / 字符串与格式化 | 6 |
| SQL 入门 | 查询与过滤 / 连接 | 3 |
**架构**:Vue 3 (web) + NestJS (server) + MySQL + DeepSeek (AI Gateway,可换) + Pyodide (浏览器 Python 沙盒)。完整模块边界、命名约定、5 条核心原则见 [CLAUDE.md](CLAUDE.md)。
## 🗺️ 计划中
按教学价值与实现难度排序,接受社区 PR 实现:
- **诊断 / Onboarding** — 进新 learner 先做 3-5 道诊断,定起始 LO 状态(避免 mastered 学习者从 untouched 重新走)
- **学习档案 Archive Generator** — 从事件流派生学习者个人 markdown 档案(章末由 AI 改写为漂亮的"我学了什么"),含 QA 内容
- **多 learner + 简单认证** — 邮箱登录,demo learner 当前硬编码 id=1
- **Educator Dashboard** — 班级 / 班主任 / 学员名单 CSV 上传,LO 级 mastery 汇总 + 班级薄弱点
- **延迟检验调度** — 1 周/1 月后的 mini quiz,需要 cron + Notification
- **课程作者工具增强** — `whale-tutor build --watch` 增量再生 / 课程模板市场 / hot reload
- **代码沙盒服务端 re-run** — 现在前端 Pyodide 结果可被伪造;v1 上 docker python sandbox 复跑校验
- **多模态** — 白板 / 视觉化 / 录屏分析
- **群体智能** — 基于事件流分析"哪种路径效果好",反向优化作者 yaml
完整待办与已知技术债见 [CLAUDE.md "路线图"](CLAUDE.md#v03-路线图)。
## 🤝 参与社区
- 🐛 **报 bug / 提 feature** → [GitHub Issues](https://github.com/datawhalechina/whale-tutor/issues)
- 💻 **贡献代码** → [CONTRIBUTING.md](CONTRIBUTING.md)
- ✍️ **贡献课程内容** → [AUTHORING.md](AUTHORING.md) +[CONTRIBUTING.md §3](CONTRIBUTING.md#3-贡献课程内容)
- 🌟 **觉得有意思** → 给个 star 帮项目被更多课程作者看见
- 💬 **讨论** → [GitHub Discussions](https://github.com/datawhalechina/whale-tutor/discussions) / Datawhale 微信群(待开)
新人想入手不知从哪下手,看 [`good first issue`](https://github.com/datawhalechina/whale-tutor/labels/good%20first%20issue) 标签。
## 📜 许可
[AGPL-3.0-or-later](LICENSE) — 强 copyleft。
- 任何人可以自由使用 / 修改 / 分发,但**修改版必须开源**
- 关键不同于 GPL:**网络部署也算分发** — 把 fork 部署成 SaaS 也必须公开源码
需要闭源商用许可的场景,联系 maintainer 讨论。
### Contributors
感谢每一位贡献者(代码 / 课程 / 文档 / bug 报告 / 设计讨论):
[](https://github.com/datawhalechina/whale-tutor/graphs/contributors)
### Star History
[](https://star-history.com/#datawhalechina/whale-tutor&Date)