# 小学生数学交互系统 🧮

> **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"
```

---

## 🧠 知识追踪 — LLM Wiki 参考

基于 [Karpathy 的 LLM Wiki 构想](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)（⭐5000+）：

> 不是 RAG 的每次重新发现，而是增量构建持久复利的 wiki

| 参考项目 | ⭐ | 借鉴点 |
|:-----|:---|:-----|
| [lucasastorian/llmwiki](https://github.com/lucasastorian/llmwiki) | 737 | SQLite schema · MCP 三层架构 |
| [Luc1104/Understand-Anything](https://github.com/Luc1104/Understand-Anything) | 9,513 | 知识图谱可视化 |
| [agricidaniel/claude-obsidian](https://github.com/agricidaniel/claude-obsidian) | 3,720 | 持久化知识编辑 |
| [THU-MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) | 17.8k | 清华多Agent互动课堂·多模型热切换 |
| [karpathy/nanochat](https://github.com/karpathy/nanochat) | — | 最小代码·最深道理·全程hackable |
| 收藏笔记 [[2026-05-21_微信_Karpathy加入Anthropic-5个开源项目|Karpathy 5大开源项目]] | — | 含 LLM Wiki / llm-council / nanochat / autoresearch / jobs |

---

## 📚 参考资源

- [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)
- [TapXWorld/ChinaTextbook](https://github.com/TapXWorld/ChinaTextbook) (⭐71.1k) — 小初高+大学全部 PDF 教材开源库
- [wuwangzhang1216/ChinaTextbookStudyFree](https://github.com/wuwangzhang1216/ChinaTextbookStudyFree) (⭐16) — 🔥 小学全科 AI 学习平台（最接近本项目的开源参考）
  - Web+iOS 双端 | TTS 全站语音 | AI 出题 | 课本原页 | SRS 学习追踪
  - [📋 详细分析](docs/references/2026-05-22_ChinaTextbookStudyFree.md)

---

## 📄 License

MIT