# eduai-engine

**Repository Path**: skingway/eduai-engine

## Basic Information

- **Project Name**: eduai-engine
- **Description**: ���������������� AI �������������������������������������������������������������������������������������������������� 5 ���� 1081 ����
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# eduai-engine — 面向教育者的开源 AI 辅导引擎

一套**学科无关**的 AI 一对一辅导引擎：苏格拉底式引导（不直接给答案）、三级判题、防偷答案护栏、学习动力系统、艾宾浩斯复习与错题本。引擎与学科内容彻底分离——换一个学科，只需要按契约放一个插件目录，引擎一行不改。

内置 5 个学科、1081 道题，全部可运行。在线演示：https://teach.tybbtech.com

> **我们为什么开源它：找老师。**
> 这套系统是工程师做的。引擎我们有信心，但题库是用人工智能生成、由工程师逐题校验的——**我们不是老师**。题目是否贴合真实课堂、难度分层是否符合学生认知规律、知识点拆分是否符合教学法，这些是我们的知识盲点。与其闭门造车，不如把整套系统开源出来，邀请真正懂教学的人一起把它做好。如果你是老师、教研员或教育行业从业者，这个仓库就是为你准备的。

---

## 对学生有什么用

这不是"把题目喂给大模型"的套壳。引擎围绕"学生怎样才真正学会"做了一整套机制：

**1. 引导而不是告知。** 学生答错时，AI 不给答案，而是分层引导（最多三轮，界面上有 ●○○ 进度提示），引导语由知识点的分层提示驱动，逼近但不揭晓。四层护栏（答案泄漏检测 / 轮次上限 / 主题边界 / 长度限制）保证学生没法从对话里把答案套出来——包括在自由提问的"讲解抽屉"里。

**2. 判题不迷信大模型。** 三级判题调度：能用规则判的（选择、数值容差、化学方程式原子守恒）绝不调用 AI；关键词层带数字边界正则，避免"15"误命中"5"这类经典误判；只有开放式简答才落到 AI 兜底判。省钱，更重要的是**稳定可复现**。

**3. 学习动力是一等公民。** 基于多巴胺期待 / 即时反馈 / 心流难度 / 自主感四个维度设计：距离掌握"又近了 N 步"的实时反馈、突破动画、知识点趣味冷知识、可选的 AI 人格、勋章体系（24 枚 11 类）、每次学习结束的成长报告卡。目标是让孩子愿意回来，而不是靠家长押着。

**4. 遗忘曲线抓复习。** 按艾宾浩斯间隔（3/7/15/30 天）自动排复习，通过升级、四次稳固退出；错题本独立运行，连对移除。中断恢复精确到题——关掉浏览器再打开，"欢迎回来，上次学到某某第 3 题，正在引导中"。

**5. 时长有节制。** 内置软性时长管控：顶栏计时、超时友好提醒不强制打断。给孩子用的东西，防沉迷是设计的一部分。

## 架构：引擎与学科的硬隔离

```
┌─────────────────────────────────────────┐
│  Subject Plugins（学科插件, 按契约交付）      │
│  chemistry_junior / math_grade10 / ...    │
├─────────────────────────────────────────┤
│  Subject Plugin Contract（9 个契约文件）    │
│  metadata / knowledge_tree / question_bank │
│  prompts / validator / narrative_frame ... │
├─────────────────────────────────────────┤
│  Core Engine（学科无关核心）                │
│  状态机 / 判题调度 / 护栏 / 动力引擎          │
│  进度追踪 / 复习调度 / Prompt 编排 / 模型网关 │
└─────────────────────────────────────────┘
```

"学科无关"不是口号，是 CI 门禁：`npm run lint:engine` 对引擎核心目录做静态扫描，出现任何学科字面量（学科名、题目 ID、"化学"这样的词）直接失败。集成测试 T1-T8 用一个假想学科（`subjects/dummy_english`，测试专用 fixture）验证：不看任何现有学科源码，仅凭契约就能接入新学科——这一点我们用模板派生真实学科实测过。

其他工程事实：Node.js 20 + Fastify + React，无数据库（JSON 文件存储，隐私数据全在本地）；多用户账号（scrypt 加密，登录后端可插拔）；模型网关统一收口全部大模型调用，主备双通道自动降级，每个场景带数据合规策略标注；测试 300+ 项。

## 内置学科与题库现状

| 学科 | 题量 | 覆盖 | 说明 |
| --- | --- | --- | --- |
| 初中化学（人教九年级） | 681 | 11 单元 59 知识点 | 最完整；含化学式工具栏、方程式原子守恒判题、装置 SVG 配图 |
| 高中数学（必修一函数） | 100 | 10 知识点 | 含数值容差判题 |
| 高中物理（匀变速运动） | 100 | 10 知识点 | 同上 |
| 高中语文 | 100 | 10 知识点 | 默写 / 鉴赏多关键词匹配 |
| 高中英语 | 100 | 10 知识点 | — |

**题库的诚实说明**：所有题目由人工智能按知识点大纲生成，经硬校验（schema / 答案自查 / 去重）+ 工程师逐题人工复核后入库。数学物理每题都手工验算过。但"没有错误"和"适合教学"是两回事——难度梯度、题型分布、与教材和考纲的贴合度，需要专业教师的判断。**这正是我们最需要帮助的地方。**

## 写给老师

题库是我们持续打磨的东西，也是我们最没底气的部分——如前所说，题目由人工智能生成、工程师逐题校验，但"没有错误"和"适合教学"是两回事：难度梯度、题型分布、与教材考纲的贴合，需要真正的教学判断。

我们没有做公开征稿的流水线（题目的版权和质量都需要严肃把关）。但门一直开着：如果你是资深老师或教研员，认可这套系统，愿意就某个学科深度合作、或者想指出我们哪里做得不对，欢迎邮件 **service@tybbtech.com**，我们私下聊。比起收一堆题，我们更想找到几位真正懂教学、愿意一起把一条学科线做扎实的人。

> 如果你或你的团队想基于这套引擎自建内容：一条命令生成新学科骨架（`node scripts/new-subject.mjs`，见 `docs/SUBJECT_AUTHORING.md`），内置 AI 出题流水线（`scripts/gen-questions.mjs`）——全程不需要读引擎源码。

## 快速开始

```bash
# 要求 Node.js >= 20
npm install
cp .env.example .env        # 填入智谱或 DeepSeek 的 API Key（至少一个）

npm run dev                  # 启动服务端 http://localhost:3000
cd app/frontend && npm install && npm run dev   # 前端开发服 http://localhost:5173

npm test                     # 全量测试
npm run lint:engine          # 引擎纯度静态扫描
```

打开前端后：注册账号 / 登录 → 选学科 → 选 AI 人格 → 开始学习。所有学习数据存在本地 `data/` 目录的 JSON 文件里，不上传任何地方。

## 登录方式（自带账号 / 可选接入 AIHEY）

登录后端是可插拔的，由环境变量 `AUTH_PROVIDER` 决定，默认无需任何外部依赖：

- **`local`（默认）**：内置账号密码登录（scrypt 加密，用户库落在本地 `data/users.json`）。克隆即用，自己包一套产品、自己做账号与合规管理。
- **`aihey`（可选）**：把账号体系委托给 [AIHEY](https://www.tybbtech.com) —— 手机号登录、统一额度与计费、内容安全与合规链路开箱即用。你不必自建这一整套，接上即可，把精力放在题目和教学上。开启方式：

  ```bash
  AUTH_PROVIDER=aihey
  AIHEY_AUTH_BASE=https://<你申请到的 AIHEY 开放接口地址>
  ```

  > 说明：接入 AIHEY 能**显著降低合规成本**（上游模型已备案、账号与内容安全现成），但如果你把它包装成面向公众的产品，**生成式 AI 服务的登记义务仍属于你这个服务提供者本身**，接入不等于免登记。请按自己的运营形态履行相应手续。

## 边界与合规

- 本项目是**学习辅导工具**，AI 生成的题目和讲解可能存在错误，入库前应经人工审核；请勿在无成人监督的场景下让低龄儿童单独使用大模型对话功能。
- 大模型调用需要你自己的 API Key，对话内容会发送至对应模型服务商，选择服务商时请自行评估其数据政策（`config/models.yaml` 中每个场景标注了数据合规策略字段，可按需路由）。
- 界面内置"内容由 AI 生成，仅供学习参考"合规横条，请保留。

## 关于我们

这套引擎驱动着我们的在线演示站 [teach.tybbtech.com](https://teach.tybbtech.com)。想看我们的其他作品（AI 助理艾嘿 AIHEY、更多开源仓库），欢迎访问官网 [www.tybbtech.com](https://www.tybbtech.com) 与[开源社区页](https://www.tybbtech.com/zh/opensource)。

License: MIT —— 代码随便用；期待的回报只有一种：如果你是老师，告诉我们哪里做得不对。

---

## 关注公众号

关注微信公众号「天怡数智」，获取更新与优惠信息：

<img src="docs/qrcode_wechat.jpg" width="160" alt="公众号「天怡数智」二维码">

（图片加载不出来？微信搜索"天怡数智"即可）