# open-edu-lab

**Repository Path**: cnt-code/open-edu-lab

## Basic Information

- **Project Name**: open-edu-lab
- **Description**: 【开源虚拟仿真实验室】 重写教育数字化规则。聚焦K12理化教学，打破商业化付费围墙（拒绝198元“钓鱼”模式）。基于Apache-2.0，社区委员会共治，支持AI动态生成交互代码。诚邀教师与开发者共建，让数字实验资源回归公共属性。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ⚛️ OpenEduLab · 开源虚拟仿真实验室

[![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![版本](https://img.shields.io/badge/版本-v0.4.0-green)](CHANGELOG.md)
[![Gitee](https://img.shields.io/badge/Gitee-OpenEduLab-orange)](https://gitee.com/zhangborui_2026/open-edu-lab)
[![状态](https://img.shields.io/badge/状态-开发中-yellow)](https://gitee.com/zhangborui_2026/open-edu-lab)

> **实验室的门，为所有人而开。**

OpenEduLab 是一个开源的 K12 虚拟仿真实验平台，致力于打破商业化付费围墙，让优质的数字化实验资源回归公共属性。

---

## 🚀 快速开始

> 🌐 **在线体验**：http://121.43.129.84:8505

**三行命令，5 分钟跑起来：**

```bash
git clone https://gitee.com/zhangborui_2026/open-edu-lab.git
cd open-edu-lab
python -m src.common.lab_server
```

然后打开浏览器访问 **http://localhost:8000**

> **注意**：当前项目无外部依赖，纯 Python 标准库实现，无需安装额外包。

选择实验 → 调节参数 → 点击“开始实验” → 观看小球运动动画
http://localhost:8000/chemistry.html

**化学模块**：服务器启动后，访问 `http://localhost:8000/chemistry.html`

---

## 🖥️ 效果预览

![运行界面](docs/api/file%20(1).webp)

*（自由落体实验交互界面，小球沿轨迹实时运动）*

---

## 🎯 产品功能

| 功能 | 状态 | 说明 |
|------|------|------|
| 物理引擎 | ✅ 可用 | 自由落体、斜抛运动 |
| 逐帧动画 | ✅ 可用 | 小球沿轨迹实时运动 |
| 动态实验加载 | ✅ 可用 | JSON 定义实验，无需改代码 |
| 纯 Web 交互 | ✅ 可用 | 浏览器即可运行，无需安装 |
| AI 实验助手 | ✅ 可用 | 基于 DeepSeek API，自动分析物理/化学原理，移动端支持多轮对话 |
| 化学模块 | ✅ 可用 | 电解水 3D 微观演示（移动端 SPA 内直接渲染） |
| **移动端 SPA** | ✅ 可用 | `m.html` 单页应用：首页/实验/AI 对话/文档/我的 |
| **中英双语** | ✅ 可用 | 界面文案、实验名称/描述、Canvas 与化学提示均支持中英切换 |
| 更多实验 | 🚧 待扩展 | 单摆、弹簧振子等 |

---

## 👥 适合谁

| 角色 | 能做什么 | 门槛 |
|------|---------|------|
| 👨‍🏫 教师 | 编写实验 JSON、反馈教学需求、在课堂上试用 | 无需编程 |
| 💻 开发者 | 改进物理引擎、优化前端、修复 Bug、完善测试 | 需要编程 |
| 🎨 设计师 | 优化界面交互、设计项目视觉 | 无需编程 |
| 📖 学生 | 免费使用、提建议、学习开源协作 | 无需编程 |

> **不写代码也能贡献**：详见 [贡献指南](CONTRIBUTING.md)。

---

## 📁 项目结构

```text
open-edu-lab/
├── src/                    # 源代码
│   ├── physics/            # 物理实验模块
│   │   ├── engine.py       # 物理引擎
│   │   └── mechanics.py    # 力学实验
│   ├── chemistry/          # 化学实验模块（规划中）
│   ├── common/             # 通用组件
│   │   ├── lab_server.py   # HTTP 服务器
│   │   ├── loader.py       # 实验加载器
│   │   └── utils.py        # 工具函数
│   └── ai/                 # AI 模块（DeepSeek API 集成）
│       ├── __init__.py
│       └── deepseek_client.py
├── frontend/               # 前端页面
│   ├── index.html          # 物理实验主界面（含 AI 解释按钮）
│   ├── m.html              # 移动端 SPA（中英双语，Vue 3 + Hash 路由）
│   ├── chemistry.html      # 化学模块（电解水 3D 微观演示）
│   └── assets/js/chemistry-renderer.js  # 化学渲染器（SPA 集成用）
├── simulations/            # 实验定义（JSON，含 name_en/description_en 双语字段）
│   ├── free_fall.json      # 自由落体
│   ├── projectile.json     # 斜抛运动
│   └── electrolysis.json   # 电解水
├── docs/                   # 文档中心
│   ├── index.md            # 文档入口
│   ├── getting-started.md  # 快速开始指南
│   ├── user-guide.md       # 用户使用手册
│   ├── experiment-protocol.md  # 实验定义协议
│   ├── ai-assistant.md     # AI 助手指南
│   ├── deployment.md       # 部署指南
│   ├── troubleshooting.md  # 常见问题排查
│   ├── architecture.md     # 架构设计
│   └── api/                # API 文档
├── tests/                  # 单元测试
├── scripts/                # 构建脚本
├── examples/               # 示例代码
│   └── run_ai_assistant.py # AI 助手示例
├── .env.example            # 环境变量模板
└── requirements.txt        # 依赖（含 openai, python-dotenv）
```

---

## 📱 移动端 SPA

移动端入口为单页应用 **`http://服务器IP:8000/m.html`**，支持手机、平板流畅使用。

**特性**：
- 六大页面：首页 / 实验列表 / 实验操作 / AI 对话 / 文档中心 / 我的（Hash 路由，无需安装 App）
- 化学实验在 SPA 内直接渲染（Three.js），非 iframe 嵌套
- **中英双语**：顶栏一键切换，界面文案、实验名称/描述、Canvas 与化学提示同步更新，偏好自动记忆
- 触控优化：按钮和滑块针对触屏操作进行尺寸与间距优化

---

## 🤖 AI 实验助手

OpenEduLab 集成了 DeepSeek API，为物理和化学实验提供智能化的原理解释。

**使用方法**：
1. 完成实验后，点击控制面板中的 **“🤖 AI 解释”** 按钮
2. 系统自动收集当前实验参数和结果
3. 调用 DeepSeek 大模型生成针对性的原理分析
4. 分析内容包括：物理/化学规律、参数影响、生活类比

**配置**：
- 在项目根目录创建 `.env` 文件，填入 `DEEPSEEK_API_KEY=你的密钥`
- 默认模型为 `deepseek-v4-flash`（经济高效）
- 详细配置请参考 `src/ai/deepseek_client.py`

---

## 📚 文档

完整的教程文档请查看 [docs/](docs/index.md) 目录：

- [快速开始](docs/getting-started.md) — 5 分钟跑起来
- [用户手册](docs/user-guide.md) — 详细使用说明
- [实验定义协议](docs/experiment-protocol.md) — 如何编写实验
- [AI 助手使用指南](docs/ai-assistant.md) — DeepSeek API 集成
- [部署指南](docs/deployment.md) — 服务器部署
- [常见问题](docs/troubleshooting.md) — 问题排查

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！无论你是教师、开发者、设计师还是学生。

**快速参与：**
1. Star 本项目
2. 在 [Issues](https://gitee.com/zhangborui_2026/open-edu-lab/issues) 中认领任务
3. Fork → 开发 → Pull Request

详细指南请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 协议。

这意味着你可以：
- ✅ 自由使用、复制、修改、分发
- ✅ 用于商业目的
- ✅ 申请专利（需遵守协议）

唯一要求：保留版权声明和免责声明。

---

## 📌 相关链接

- [Gitee 仓库](https://gitee.com/zhangborui_2026/open-edu-lab)
- [问题反馈](https://gitee.com/zhangborui_2026/open-edu-lab/issues)
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [文档中心](docs/index.md)

---

## 🙏 致谢

感谢每一位为教育公平付出努力的贡献者。

**这扇门，不为资本开，不为权力开——只为下一个 Fork 这个仓库的人而开。**

---

## 📖 背景故事

市面上某主流虚拟实验平台，免费版仅开放 **20% 实验资源**，完整版需 **198 元/年**。全国 3 万+ 公立学校在使用，大量学生被挡在付费墙外。

**教育数字化应该降低门槛，而不是筑高围墙。**

OpenEduLab 正是为此而生。

---

*最后更新：2026年9月6日*
```