docs: 添加项目 README — 架构说明/快速启动/参考资源

README.md

@@ -0,0 +1,118 @@
+# 小学生数学交互系统 🧮
+
+> **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