VirtualChemLab · 游戏化虚拟化学实验室 | Gamified virtual chemistry lab for teaching & simulation.
📘 想要最短路径？使用
QUICK_START.md（English）或README_快速开始.md（中文），并在完成后按照QUICK_START_COMPLETION.md检查剩余事项。需要更完整的引导可参考QUICK_START_GUIDE.md。
- ✅ 推荐：本地桌面单机（教学/实验室/内网环境），macOS/Windows/Linux 均可。
- ✅ macOS 兼容：支持打包为
.app并分发给本机用户（见DEPLOY.md与build_macos.sh）。 ⚠️ API/管理后台可选：用于内网集成或运维辅助，默认仅绑定回环地址；不建议直接对公网暴露。
- 多种实验类型: 滴定、合成、晶体生长、电化学等
- 实时物理模拟: 重力、摩擦力、碰撞检测
- 交互式操作: 拖拽、点击、滑动手势
- 步骤引导: 详细的实验步骤和验证
- 物理引擎: 60 FPS 物理更新
- 粒子效果: 8种不同类型的粒子效果
- 稀有度系统: 普通、罕见、稀有、史诗、传说
- 分数系统: 实时分数和连击计数
- 成就系统: 实验完成度和经验值
- 现代化设计: 暗色主题和发光效果
- 响应式布局: 适配不同屏幕尺寸
- 主题切换: 支持多种主题模式
- 动画效果: 流畅的过渡和反馈
- 灵活配置: 支持多种配置选项
- 导入导出: 配置文件的备份和恢复
- 实时更新: 配置更改即时生效
- 错误处理: 完善的异常管理
统一的图形化开发工具管理界面，整合所有启动脚本：
- ✅ 一键启动 - 运行
python tools/developer_panel.py - ✅ 标签页分类 - 主应用、管理工具、许可证、开发工具、系统工具
- ✅ 实时日志 - 所有输出实时显示，带时间戳
- ✅ 进程管理 - 支持并行运行多个工具，一键停止
- ✅ 功能整合 - 12+ 个启动脚本统一管理
- ✅ 友好界面 - 现代化 GUI，操作简单直观
📖 查看完整文档
全面的系统完善和优化，提升项目质量和性能：
- ✅ 内存泄漏修复 - 优化内存管理，防止内存泄漏
- ✅ 线程安全增强 - 统一锁机制，确保线程安全
- ✅ 异常处理完善 - 智能错误恢复和降级处理
- ✅ 缓存性能优化 - O(1) LRU/LFU算法，提升缓存效率
- ✅ 事件总线优化 - 缓存正则表达式，优化事件处理
- ✅ 懒加载改进 - 并行预加载，重试机制
- ✅ 代码质量提升 - 减少重复，统一接口
- ✅ 测试覆盖增强 - 新增150+测试用例
📖 查看完善报告
- ✅ 统一流程管理器 - 清晰的用户操作流程
- ✅ 智能启动向导 - 首次使用引导体验
- ✅ 统一启动器 - 图形化菜单选择模式
- ✅ 流程检查工具 - 自动化质量保证
- ✅ 完整流程文档 - 详细的操作指南
- ✅ 会话管理 - 自动保存和恢复进度
- ✅ 图形化模板编辑器
- ✅ 拖拽式步骤管理
- ✅ 实时预览和验证
- ✅ 一键生成YAML模板
- ✅ 详细的统计分析
- ✅ 趋势图表可视化
- ✅ 成绩分布分析
- ✅ 错误模式识别
- ✅ LRU淘汰策略
- ✅ 自动过期管理
- ✅ 性能监控工具
- ✅ 缓存调试器
- Python 3.10+（推荐 3.11）
- Windows 10/11, macOS 10.15+, 或 Linux
- 4GB RAM (推荐 8GB)
- 1GB 可用磁盘空间
-
克隆仓库
git clone https://github.com/tytsxai/virtualchemlab.git cd virtualchemlab -
创建并激活 Python 3.11 虚拟环境
python3.11 -m venv venv311 source venv311/bin/activate # Linux/macOS # 或 venv311\\Scripts\\activate # Windows
-
安装依赖（锁定文件优先）
pip install -r requirements.lock # 如需刷新依赖，请更新 pyproject.toml 并重新生成锁定文件: # pip-compile --extra=dev --extra=docs --extra=redis --extra=performance --extra=admin --extra=ops --extra=plugins --generate-hashes --output-file=requirements.lock pyproject.toml
CI/发布流程同样使用
requirements.lock安装，确保依赖可重复。 -
初始化环境变量和配置
cp env.example .env python tools/validate_config.py
上述脚本会按当前实现验证配置/密钥/目录，并在缺失时自动创建必要目录。
-
运行应用与测试
python main.py --env development pytest -q
💡 在无显示环境（CI/纯终端）运行测试如遇 Qt 崩溃，可使用：
QT_QPA_PLATFORM=offscreen pytest -q或直接执行make test-fast。 -
可选：开发者启动面板
python tools/developer_panel.py
用于集中启动核心工具、测试和诊断程序。
💡 更多细节和扩展安装指引，请查看
README_快速开始.md、QUICK_START_GUIDE.md、INSTALL.md。
- 安装开发依赖
pip install -r requirements.lock
pip install --no-deps -e .
# requirements-dev.txt 仅作为兼容入口，内部同样引用锁定文件- 安装预提交钩子
pre-commit install- 运行测试
pytestNote: CI 与默认测试命令会生成覆盖率报告并执行 18% 覆盖率门禁（后续目标逐步提升到 30%，产出
coverage.xml与htmlcov/）。如需快速运行跳过覆盖率，可执行pytest --no-cov或make test-fast。 💡 提示：tests/ui/test_refactored_main_window.py依赖真实的 Qt 图形界面环境。在无显示服务器（例如 CI 或纯终端）中，它会自动跳过。若要完整验证 UI 行为，请在本地具备 GUI 的环境执行pytest tests/ui/test_refactored_main_window.py。
- 代码格式化
ruff format src tests
ruff check src tests --fix- 运行
python scripts/readiness_check.py，快速验证依赖、配置、安全与监控是否达标。 - 更多上线、监控、回滚与性能调优细节见
docs/OPERATIONS_READINESS.md。
JWT_SECRET_KEY：JWT 密钥，至少 32 个字符，生产环境必须外部提供。SESSION_SECRET_KEY：会话密钥，至少 32 个字符，生产环境必须外部提供。DEVELOPER_SECRET_KEY：开发者模式密钥（仅在开启开发者模式时需要），建议至少 32 个字符。VCL_ADMIN_SECRET_KEY：管理后台/Flask 的 SECRET_KEY（仅在启动 Admin API 时需要），建议与 JWT/会话密钥不同。VCL_API_HOST：API 服务监听地址，默认127.0.0.1；如需对外提供服务请显式设置为0.0.0.0并配合认证/限流/防火墙。VCL_API_KEYS：REST API 访问密钥（逗号分隔，可配置多把，仅在启动 REST API 时需要）。未配置时会在首次启动时自动生成并写入~/.virtualchemlab/api_key.txt（以及~/.virtualchemlab/config.json），用于本机开发调试；生产环境必须显式配置该变量（避免容器/多副本因自动生成导致密钥漂移）。VCL_API_CORS_ORIGINS：REST API 的 CORS 允许列表（逗号分隔）。默认仅允许本机回环（localhost/127.0.0.1/::1）；当你将 API 暴露到局域网/容器时，建议显式配置允许的前端域名。VCL_ADMIN_CORS_ORIGINS：管理后台 API 的 CORS 允许列表（逗号分隔，或*仅用于开发环境）。默认不启用 CORS；当你需要浏览器跨域访问或绑定到非本地主机时，请显式配置。ENVIRONMENT：development/staging/production，控制默认安全策略。VCL_CONFIG_PATH：指定用户配置文件路径（默认~/.virtualchemlab/config.json），用于容器/系统服务固定挂载路径。
写入 .env 或系统环境，例如：
export JWT_SECRET_KEY="please_change_me_to_a_secure_value"
export SESSION_SECRET_KEY="please_change_me_to_a_secure_value"
export VCL_ADMIN_SECRET_KEY="admin_panel_secret"
export ENVIRONMENT="production"生产环境缺少必需密钥会导致程序拒绝启动；仅在启用 Admin API/REST API 时才要求各自的密钥。
方式1：开发者面板（推荐）✨
python tools/developer_panel.py统一的图形化管理界面，整合所有启动脚本和工具：
- 🚀 主应用启动（标准、快速、热加载、许可证模式）
- 👨💼 管理工具（教师控制台、管理后台、实验管理）
- 🔐 许可证管理（检查、备份、工具箱）
- 🛠️ 开发工具（构建、部署、测试、工具箱）
- 🔧 系统工具（维护、诊断、流程检查）
📖 查看完整文档
方式2：命令行启动
# 标准模式（含欢迎向导）
python main.py
# 快速模式（跳过向导）
python main.py --skip-welcome
# 热加载模式（开发调试，代码修改自动重启）
python tools/hot_reload_launcher.py方式3：许可证验证启动
python -m src.main_with_license- 启动应用: 使用上述任一方式启动
- 首次使用: 按照欢迎向导完成5步设置
- 选择实验: 从实验模板库中选择
- 进行实验: 按照步骤指导完成操作
- 查看结果: 生成报告并查看得分
- 游戏模式: 按
Ctrl+G切换游戏模式 - 物理控制:
- 空格键：震动所有物品
- G键：切换重力
- R键：重置所有物品
- 打开配置: 菜单 → 设置 → 配置
- 调整参数: 修改物理、UI、游戏等设置
- 保存配置: 点击确定保存更改
- 拖拽器材: 鼠标左键拖拽实验器材
- 点击交互: 点击试剂瓶等物品
- 观察效果: 查看粒子效果和物理模拟
- 完成步骤: 按照提示完成实验步骤
VirtualChemLab/
├── src/ # 源代码
│ ├── core/ # 核心模块
│ │ ├── config_manager.py # 配置管理
│ │ ├── error_handler.py # 错误处理
│ │ └── experiment_controller.py # 实验控制
│ ├── models/ # 数据模型
│ ├── ui/ # 用户界面
│ │ ├── game_interaction.py # 游戏交互
│ │ ├── particle_system.py # 粒子系统
│ │ ├── config_dialog.py # 配置对话框
│ │ └── main_window.py # 主窗口
│ └── utils/ # 工具函数
├── tests/ # 测试代码
├── docs/ # 文档
├── requirements.txt # 依赖列表
├── requirements-dev.txt # 开发依赖
├── pyproject.toml # 项目配置
└── README.md # 说明文档
- GUI框架: PySide6 (Qt6)
- 物理引擎: 自定义物理模拟
- 粒子系统: 自定义粒子效果
- 配置管理: JSON配置文件
- 错误处理: 统一异常管理
- 测试框架: pytest（pytest-qt 可选；CI 默认禁用以降低 GUI/平台差异导致的波动）
- 代码质量: ruff（lint + format）+ mypy（可选门禁）
- 📖 开发者文档索引 - 所有文档的导航中心
- 📝 代码风格规范 - 统一的代码和注释规范
- 💻 API使用示例 - 实际代码示例和最佳实践
- 🔧 故障排除指南 - 常见问题和解决方案
- 🎨 UI组件指南 - UI组件使用说明
- 单一来源：
src/__init__.py中的__version__ - 同步脚本：
python tools/bump_version.py 2.0.0，省略版本号则按当前值同步pyproject.toml、config.json、version_info.txt、installer_windows.iss - 便捷命令：
make bump-version VERSION=2.0.1 - 打包脚本：
build.sh/build_macos.sh/build_windows.bat读取同一版本号
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开 Pull Request
- 遵循 代码风格规范
- 使用
ruff format格式化代码 - 使用
ruff check检查代码质量（必要时--fix） - 使用
mypy进行类型检查（当前默认非阻塞，可按需启用严格门禁） - 编写单元测试
- 更新文档
详细信息请参考 CONTRIBUTING.md
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
- 项目主页: https://github.com/tytsxai/virtualchemlab
- 问题反馈: Issues
- 邮箱: team@virtualchemlab.com
- 🎯 用户操作流程全面优化
- 🚀 新增开发者启动面板 - 统一的图形化工具管理界面
- 整合所有启动脚本和开发工具
- 实时日志输出和进程管理
- 标签页式界面，功能分类清晰
- 支持并行运行多个工具
- ✨ 新增统一流程管理器
- ✨ 新增智能启动向导
- ✨ 新增统一启动器
- ✨ 新增流程检查工具
- ✨ 完善会话管理和状态恢复
- 📚 新增完整的流程文档
- 🐛 修复多项用户体验问题
- 🎉 首次发布
- ✨ 游戏化交互系统
- ✨ 物理模拟引擎
- ✨ 粒子效果系统
- ✨ 配置管理系统
- ✨ 错误处理系统
- ✨ 单元测试框架
感谢所有贡献者和开源社区的支持！
VirtualChemLab - 让化学实验变得更有趣！ 🧪✨