{"id":51599920,"url":"https://github.com/datawhalechina/whale-tutor","last_synced_at":"2026-07-11T21:02:04.138Z","repository":{"id":356837678,"uuid":"1232502928","full_name":"datawhalechina/whale-tutor","owner":"datawhalechina","description":"🐳 AI 驱动的开源交互式学习引擎","archived":false,"fork":false,"pushed_at":"2026-05-19T02:58:27.000Z","size":3039,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T04:38:15.762Z","etag":null,"topics":["ai","course-authoring","datawhale","deepseek","education","interactive-learning","llm","markdown","mastery-learning","nestjs","typescript","vue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datawhalechina.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T02:00:53.000Z","updated_at":"2026-05-19T02:58:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/datawhalechina/whale-tutor","commit_stats":null,"previous_names":["datawhalechina/whale-tutor"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/datawhalechina/whale-tutor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datawhalechina%2Fwhale-tutor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datawhalechina%2Fwhale-tutor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datawhalechina%2Fwhale-tutor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datawhalechina%2Fwhale-tutor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datawhalechina","download_url":"https://codeload.github.com/datawhalechina/whale-tutor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datawhalechina%2Fwhale-tutor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35375153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","course-authoring","datawhale","deepseek","education","interactive-learning","llm","markdown","mastery-learning","nestjs","typescript","vue"],"created_at":"2026-07-11T21:02:03.556Z","updated_at":"2026-07-11T21:02:04.130Z","avatar_url":"https://github.com/datawhalechina.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./static/whale-tutor-banner.jpg)\n\n[![CI](https://github.com/datawhalechina/whale-tutor/actions/workflows/ci.yml/badge.svg)](https://github.com/datawhalechina/whale-tutor/actions/workflows/ci.yml)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Node](https://img.shields.io/badge/Node-≥22-green)](https://nodejs.org/)\n[![GitHub Stars](https://img.shields.io/github/stars/datawhalechina/whale-tutor)](https://github.com/datawhalechina/whale-tutor/stargazers)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Discussions](https://img.shields.io/github/discussions/datawhalechina/whale-tutor)](https://github.com/datawhalechina/whale-tutor/discussions)\n\n## ⚡ 三秒钟看懂\n\n| 你是谁                              | 你能做什么                                             | 看哪里                                                      |\n| ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |\n| 🎓 **学生 / 学习者**                | 跟着已有课程交互式学习,卡住时 AI 出\"换说法\"题 + 求提示 | 找一个 [部署版](#-试一试)直接学                             |\n| ✍️ **课程作者**(老师/教研/内容编辑) | 写 markdown 讲稿 → AI 一键生成完整可交互课程           | [AUTHORING.md](AUTHORING.md)                                |\n| 🛠️ **开发者**                       | 加新 pattern / 新 endpoint / 新 UI / 改架构            | [CONTRIBUTING.md](CONTRIBUTING.md) + [CLAUDE.md](CLAUDE.md) |\n\n## 📸 看看长什么样\n\nCLI 生成的课程 (`whale-tutor` 启动 + 运行中):\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/cli-shot-1.png\" alt=\"whale-tutor CLI\" /\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/cli-result.png\" alt=\"whale-tutor 运行结果\" /\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n课程的若干交互模式：\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/course-example-1.png\" alt=\"generate 交互向导\" /\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/course-example-2.png\" alt=\"生成完成的课程\" /\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/course-example-3.png\" alt=\"学习模式示例 1\" /\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"./static/course-example-4.png\" alt=\"学习模式示例 2\" /\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 它和 ChatGPT 直接对话有什么区别?\n\n**ChatGPT 是开放对话**,没有路径设计、没有 mastery 跟踪、没有系统性推进。学完不知道学了什么,卡住没有兜底机制。\n\n**Whale Tutor 是教学引擎**:\n\n- 📐 **课程作者用 YAML 预设学习路径**(LO + 必做题 + adaptive 题型集),AI 在路径内动态出题 / 评估 / 兜底\n- 🎯 **每个学习目标(LO, Learning Objective)有 mastery 状态机**(untouched → exposed → practicing → mastered)\n- 🔁 **答错自动触发 AI 出\"换说法\"题**(同一概念换场景),连续错 3 次强制回 LO 讲解兜底\n- 💡 **梯度提示(StuckProtocol)**:作者写 1-5 级 hint,没写则 AI 自动生成 3 级缓存\n- 💬 **侧支 QA 提问**:答题时随时 drawer 提问 / 嵌套追问,不影响主路径\n- 📊 **完整事件流**:每次学习者行为入 `events` 表,支持后续个体化档案 / 班级分析 / 群体智能\n\n适合**我有教学体系,要帮学生系统学习**场景,不是\"零散问问题\"。\n\n## 🎬 试一试\n\n\u003e **共同前置(三种方式都需要)**:\n\u003e\n\u003e - **Node.js ≥ 22**:[官网下载](https://nodejs.org/zh-cn/download)(LTS 版本即可),装完跑 `node --version` 看到 `v22.x` 就 OK\n\u003e - **MySQL ≥ 8.0**:可以直接装 [MySQL 官方版](https://dev.mysql.com/downloads/installer/)(Windows/Mac/Linux 都有);或者装 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 用容器跑(开发期推荐)\n\u003e - **DeepSeek API Key**(可选,但强烈推荐):去 [DeepSeek 平台](https://platform.deepseek.com/api_keys) 申一个,没有的话 AI 评估走 fallback 文案,但 `whale-tutor build` 不可用\n\n### 路径 A:用 CLI(课程作者 / 试用学习者)⭐️ 推荐\n\n#### 第一步(共同):创工作目录 + 装 CLI + 初始化\n\n```bash\n# 1. 装 CLI(全局,一次性) — 之后想升级到最新版重跑同一条命令即可:`npm install -g whale-tutor@latest`\nnpm install -g whale-tutor\n\n# 2. 创工作目录(后续所有 whale-tutor 命令都在这里跑)\nmkdir whale-workspace \u0026\u0026 cd whale-workspace\n\n# 3. scaffold 完整 python-basics 示例 + whale-tutor.config.yaml 配置模板\nwhale-tutor init\n\n# 4. 编辑 whale-tutor.config.yaml(填 mysql 连接 + 可选 DeepSeek key)\n#    用任意编辑器打开都行,例如:\n#      Windows:  notepad whale-tutor.config.yaml\n#      macOS:    open -e whale-tutor.config.yaml\n#      Linux:    nano / vim whale-tutor.config.yaml\n#    或者直接用 VSCode 打开 whale-workspace/ 目录\n\n# 5. 健康检查(强烈推荐第一次跑)\nwhale-tutor doctor                          # 检查 node / mysql / API key\n```\n\n完成共同步骤后,**留在 `whale-workspace/` 目录里**,二选一:\n\n#### 选项 1 — 跑内置 python-basics 示例\n\n```bash\nwhale-tutor start                           # 浏览器自动打开 http://localhost:3000\n```\n\n学完想加自己的课程?复制 `courses/python-basics/` 当模板手改,或者上选项 2。\n\n#### 选项 2 — 用 AI 一键生成你自己的课程(交互式向导)\n\n```bash\nwhale-tutor generate\n```\n\n这是个**交互式命令**,问几个问题就完事:\n\n```\n? 课程名字(中文 OK,如 \"Pandas 数据分析入门\"): Pandas 数据分析入门\n? 生成方式  ([ai]=AI 自动写讲稿(推荐) / manual=我自己写 markdown): ai\n? 课程主题/范围(可选,留空 AI 从课程名推断): pandas 读 csv / 筛选 / 聚合 / 简单可视化\n? 目标受众(可选,如 \"数据分析新手\"): 有 Python 基础但没用过 pandas 的新手\n? 章节数(留空 AI 自己定;一般 3-7): [auto]\n```\n\n回答完几分钟后,**完整可学的课程已经生成**。AI 干了三件事:\n\n1. **写课程大纲** — 决定 course id / subject / 几个章节 / 每章主题\n2. **逐章扩写 markdown 讲稿** — 每章 2000-3500 字,含代码示例 + 易错点段落\n3. **自动跑 build pipeline** — 从 markdown 拆 LO + 出题 + 章末测试 → 完整 yaml/md 课程\n\n跑完直接 `whale-tutor lint \u0026\u0026 whale-tutor start` 试学。AI 写的 markdown 讲稿留在 `\u003ccourse-id\u003e-source/` 目录,**不满意可以手改后重跑 `whale-tutor build`**。\n\n\u003e 想自己写 markdown(不用 AI 写讲稿,只让 AI 拆 LO + 出题)?选 `manual` 模式 — 会 scaffold 一个最小源目录骨架,你写完讲稿后手工跑 `whale-tutor build` 即可。\n\n详见 [AUTHORING.md §10](AUTHORING.md#10-whale-tutor-generate--build-ai-辅助生成课程)。完整课程作者教程见 [AUTHORING.md](AUTHORING.md)。\n\n---\n\n### 路径 B:clone 仓库 dev 模式(开发者)\n\n适合**想给项目贡献代码、改架构、加新 pattern** 的开发者。需要额外装 [pnpm 8](https://pnpm.io/installation)(`corepack enable \u0026\u0026 corepack prepare pnpm@8.15.9 --activate`)+ 已经准备好 [Docker Desktop](https://www.docker.com/products/docker-desktop/):\n\n```bash\n# 1. 确认前置\nnode --version              # ≥ v22\npnpm --version              # ≥ 8\ndocker --version            # 任意版本\n\n# 2. clone + install\ngit clone https://github.com/datawhalechina/whale-tutor.git\ncd whale-tutor\npnpm install\ncp .env.example .env        # 编辑填 DEEPSEEK_API_KEY(可选)\n\n# 3. 起 mysql + build types + 并行跑前后端\npnpm db:up                  # docker compose 起 mysql:13306\npnpm build:types            # 共享类型先 build 一次\npnpm dev                    # 并行起 web (5173) + server (3000)\n\n# 浏览器开 http://localhost:5173\n```\n\n完整开发指南、scripts 列表、调试技巧 → [CONTRIBUTING.md §5](CONTRIBUTING.md#5-开发环境搭建)。\n\n## ✨ 现有特性\n\n**学习者体验**\n\n- LO Intro 教学开场页(进入新 LO 先看核心讲解,点\"开始练习\"才进题)\n- 4 种交互模式(`patternId`)覆盖大部分教学场景:\n  - `concept_check` — 概念辨析 4 选 1\n  - `code_sandbox` — 浏览器内 Pyodide 跑 Python,按测试用例 stdout 比对\n  - `spot_the_bug` — 给一段含 bug 的代码,选错误行号 + 写解释,AI hybrid 评估\n  - `free_recall` — 开放回忆,AI 按 rubric 关键点判覆盖度\n- **梯度提示(StuckProtocol)** — 题目上方\"求提示\",作者写 1-5 级 hint,缺省走 AI 3 级 + cache\n- **智能 PathOrchestrator** — 答错触发 AI 出同 LO 换说法题(`source='adaptive'`);连续错 3 次自动 review_lo 兜底回讲解;hint \u003e 0 答对计入必做但不增 mastery\n- **mastery 状态机**(untouched → exposed → practicing → mastered),mastered 连续错 2 次回归\n- **多 LO 自动推进 + 章末测试解锁**(章末测试不进 retry)\n- **多课程 / 多章节切换** — HomeView 课程卡片选课,LearnView 左侧 sidebar 列全部章节并允许跨章浏览\n- **侧支 QA**(右侧 drawer 提问 + 多轮追问 + 结束回到原位)\n\n**课程作者体验**\n\n- **YAML + Markdown** 内容存储,`$ref` 长文外置;**修改内容不需要懂代码**\n- **学科参数化** — `course.yaml` 的 `subject` 字段灌进所有 prompt,加新课程(SQL / Java / Pandas)无需改 prompt 模板\n- **CLI(npm 包)** — `init / start / doctor / lint / build / generate` 6 个命令\n- **`whale-tutor build`** — 写 markdown 讲稿(每章一份 md)→ AI 4 阶段生成完整 yaml/md 课程骨架\n- **`whale-tutor lint`** — 5 秒校验所有 yaml/$ref/pattern 结构\n\n**工程基建**\n\n- **AI Gateway** — 唯一 LLM 调用入口,DeepSeek 兼容(可切其他 OpenAI 兼容服务),ajv schema 校验 + 重试 + fallback + 成本日志\n- **Event Bus** — 学习者每次行为先写 events 表(事实表,不可变),其他派生表理论上可重建\n- **完整事件流** — session / lo / interaction / mastery / chapter / qa / hint 全打点\n\n**内置示例课程**(给你看怎么写,也可直接拿来给学习者跑)\n\n| 课程        | 章节                        | LO 数 |\n| ----------- | --------------------------- | ----- |\n| Python 基础 | 列表与迭代 / 字符串与格式化 | 6     |\n| SQL 入门    | 查询与过滤 / 连接           | 3     |\n\n**架构**:Vue 3 (web) + NestJS (server) + MySQL + DeepSeek (AI Gateway,可换) + Pyodide (浏览器 Python 沙盒)。完整模块边界、命名约定、5 条核心原则见 [CLAUDE.md](CLAUDE.md)。\n\n## 🗺️ 计划中\n\n按教学价值与实现难度排序,接受社区 PR 实现:\n\n- **诊断 / Onboarding** — 进新 learner 先做 3-5 道诊断,定起始 LO 状态(避免 mastered 学习者从 untouched 重新走)\n- **学习档案 Archive Generator** — 从事件流派生学习者个人 markdown 档案(章末由 AI 改写为漂亮的\"我学了什么\"),含 QA 内容\n- **多 learner + 简单认证** — 邮箱登录,demo learner 当前硬编码 id=1\n- **Educator Dashboard** — 班级 / 班主任 / 学员名单 CSV 上传,LO 级 mastery 汇总 + 班级薄弱点\n- **延迟检验调度** — 1 周/1 月后的 mini quiz,需要 cron + Notification\n- **课程作者工具增强** — `whale-tutor build --watch` 增量再生 / 课程模板市场 / hot reload\n- **代码沙盒服务端 re-run** — 现在前端 Pyodide 结果可被伪造;v1 上 docker python sandbox 复跑校验\n- **多模态** — 白板 / 视觉化 / 录屏分析\n- **群体智能** — 基于事件流分析\"哪种路径效果好\",反向优化作者 yaml\n\n完整待办与已知技术债见 [CLAUDE.md \"路线图\"](CLAUDE.md#v03-路线图)。\n\n## 🤝 参与社区\n\n- 🐛 **报 bug / 提 feature** → [GitHub Issues](https://github.com/datawhalechina/whale-tutor/issues)\n- 💻 **贡献代码** → [CONTRIBUTING.md](CONTRIBUTING.md)\n- ✍️ **贡献课程内容** → [AUTHORING.md](AUTHORING.md) +[CONTRIBUTING.md §3](CONTRIBUTING.md#3-贡献课程内容)\n- 🌟 **觉得有意思** → 给个 star 帮项目被更多课程作者看见\n- 💬 **讨论** → [GitHub Discussions](https://github.com/datawhalechina/whale-tutor/discussions) / Datawhale 微信群(待开)\n\n新人想入手不知从哪下手,看 [`good first issue`](https://github.com/datawhalechina/whale-tutor/labels/good%20first%20issue) 标签。\n\n## 📜 许可\n\n[AGPL-3.0-or-later](LICENSE) — 强 copyleft。\n\n- 任何人可以自由使用 / 修改 / 分发,但**修改版必须开源**\n- 关键不同于 GPL:**网络部署也算分发** — 把 fork 部署成 SaaS 也必须公开源码\n\n需要闭源商用许可的场景,联系 maintainer 讨论。\n\n### Contributors\n\n感谢每一位贡献者(代码 / 课程 / 文档 / bug 报告 / 设计讨论):\n\n[![Contributors](https://stg.contrib.rocks/image?repo=datawhalechina/whale-tutor)](https://github.com/datawhalechina/whale-tutor/graphs/contributors)\n\n### Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=datawhalechina/whale-tutor\u0026type=Date)](https://star-history.com/#datawhalechina/whale-tutor\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatawhalechina%2Fwhale-tutor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatawhalechina%2Fwhale-tutor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatawhalechina%2Fwhale-tutor/lists"}