# 小学生数学交互系统 🧮

> **Math Tutor** — 基于 Hermes Agent 的苏格拉底式数学学习系统

小学生通过网址访问，输入数学问题，获得**可量化、可图形化**的苏格拉底式引导回答。

---

## 🎯 设计理念

| 原则 | 说明 |
|:-----|:-----|
| **苏格拉底教学法** | 不直接给答案，通过提问引导学生自己发现 |
| **可视化优先** | 每个数学概念配合 SVG 图形（数轴/饼图/格子阵/柱状图） |
| **知识追踪** | LLM Wiki 三层架构追踪学生知识掌握状态 |
| **全年级覆盖** | 小学 1-6 年级全部知识点 |

---

## 🏗️ 技术架构

```
浏览器 (HTML/CSS/JS)
    ↕ HTTP
Flask Web 服务器 (app.py)
    ↕ CLI 调用
Hermes Agent (推理引擎)
    ↕
├── tutor/socratic.py   ← 苏格拉底引导引擎
├── tutor/visualize.py  ← SVG 可视化生成
├── tutor/wiki.py       ← 学生知识追踪 (LLM Wiki)
└── tutor/hermes_bridge.py ← Hermes 桥接层
```

### 前端三栏布局
- **📝 对话区**：苏格拉底式问答
- **🎨 SVG 区**：数学图形实时渲染
- **✏️ 涂鸦画布**：学生自由书写

### 降级策略（三级）
1. Hermes API → 完整推理
2. 本地规则引擎 → 基础问答
3. 预设回复 → 兜底

---

## 📦 项目结构

```
math-tutor/
├── app.py                  # Flask 主入口
├── requirements.txt        # Python 依赖
├── Dockerfile              # 容器部署
├── tutor/
│   ├── __init__.py
│   ├── socratic.py         # 苏格拉底引导（三级难度·追问链）
│   ├── visualize.py        # SVG 生成（数轴/饼图/格子阵/柱状图）
│   ├── wiki.py             # 知识追踪（sources→knowledge→schema）
│   └── hermes_bridge.py    # Hermes CLI 桥接
├── templates/
│   └── index.html          # 前端三栏界面 + 涂鸦画布
├── data/
│   └── student_be3d928d/
│       └── schema.json     # 学生知识状态
└── static/                 # CSS/JS 静态资源
```

---

## 🚀 快速启动

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务
python app.py

# 3. 浏览器访问
# http://localhost:5000
```

### Docker 部署

```bash
docker build -t math-tutor .
docker run -p 5000:5000 math-tutor
```

---

## 🌐 部署

目标：香港 ECS (43.255.30.205) — `math.arabiancloud.online`

```bash
# 待部署步骤
scp -r math-tutor/ root@43.255.30.205:/opt/
ssh root@43.255.30.205 "cd /opt/math-tutor && docker build -t math-tutor . && docker run -d -p 5000:5000 math-tutor"
```

---

## 📚 参考资源

- [PhET Interactive Simulations](https://phet.colorado.edu) — 理科仿真可视化
- [Desmos](https://www.desmos.com) — 公式→实时图形
- [GeoGebra](https://www.geogebra.org) — 动态几何画板
- [Mathigon](https://mathigon.org) — 交互式数学教科书
- [Manim](https://github.com/3b1b/manim) — 数学动画引擎
- [牛津儿童数学](https://home.oxfordowl.co.uk/maths/)
- [NRICH 剑桥数学](https://nrich.maths.org)

---

## 📄 License

MIT