From 5b68c7ca97cdc4656f07f0300fe06764defcb8c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A4=A7=E5=B8=88?= Date: Fri, 22 May 2026 02:18:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE=20?= =?UTF-8?q?README=20=E2=80=94=20=E6=9E=B6=E6=9E=84=E8=AF=B4=E6=98=8E/?= =?UTF-8?q?=E5=BF=AB=E9=80=9F=E5=90=AF=E5=8A=A8/=E5=8F=82=E8=80=83?= =?UTF-8?q?=E8=B5=84=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2b7a970 --- /dev/null +++ b/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