{"id":50148651,"url":"https://github.com/tytsxai/lab-virtualchem","last_synced_at":"2026-05-24T07:02:33.508Z","repository":{"id":358704632,"uuid":"1099206201","full_name":"tytsxai/lab-virtualchem","owner":"tytsxai","description":"🧪 VirtualChemLab — 游戏化虚拟化学实验室，用于教学与模拟实验","archived":false,"fork":false,"pushed_at":"2026-05-18T17:09:28.000Z","size":16398,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T19:14:15.826Z","etag":null,"topics":["chemistry","desktop-app","education","gamification","physics-engine","python","simulation","stem","teaching","virtual-lab"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tytsxai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY_GUIDE.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T17:48:59.000Z","updated_at":"2026-05-18T17:09:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tytsxai/lab-virtualchem","commit_stats":null,"previous_names":["tytsxai/lab-virtualchem"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tytsxai/lab-virtualchem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Flab-virtualchem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Flab-virtualchem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Flab-virtualchem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Flab-virtualchem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tytsxai","download_url":"https://codeload.github.com/tytsxai/lab-virtualchem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Flab-virtualchem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33424573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chemistry","desktop-app","education","gamification","physics-engine","python","simulation","stem","teaching","virtual-lab"],"created_at":"2026-05-24T07:02:28.432Z","updated_at":"2026-05-24T07:02:33.501Z","avatar_url":"https://github.com/tytsxai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VirtualChemLab · 游戏化虚拟化学实验室\n\n[![Release](https://img.shields.io/github/v/release/tytsxai/lab-virtualchem)](https://github.com/tytsxai/lab-virtualchem/releases) · [llms.txt](llms.txt) · [Changelog](CHANGELOG.md) · [Quick Start (EN)](QUICK_START.md) · [快速开始 (中)](README_快速开始.md) · [Issues](https://github.com/tytsxai/lab-virtualchem/issues)\n\n\u003e **关键词**:虚拟化学实验室 · 化学实验模拟器 · 化学游戏化教学 · 滴定模拟 · 晶体生长模拟 · 电化学实验模拟 · 化学课堂工具 · 化学游戏化 60 FPS 物理 · 五级稀有度粒子系统 · macOS 化学实验 .app\n\u003e\n\u003e **Keywords**: virtual chemistry lab · gamified chemistry simulator · titration simulator open source · crystal growth simulation · electrochemistry simulator · classroom chemistry app · science teaching gamification · 60 FPS physics chemistry · cross-platform desktop chem lab\n\nVirtualChemLab · 游戏化虚拟化学实验室 | Gamified virtual chemistry lab for teaching \u0026 simulation.\n\n\u003e 📘 想要最短路径？使用 `QUICK_START.md`（English）或 `README_快速开始.md`（中文），并在完成后按照 `QUICK_START_COMPLETION.md` 检查剩余事项。需要更完整的引导可参考 `QUICK_START_GUIDE.md`。\n\n## 使用场景与推荐部署\n\n- ✅ **推荐**：本地桌面单机（教学/实验室/内网环境），macOS/Windows/Linux 均可。\n- ✅ **macOS 兼容**：支持打包为 `.app` 并分发给本机用户（见 `DEPLOY.md` 与 `build_macos.sh`）。\n- ⚠️ **API/管理后台可选**：用于内网集成或运维辅助，默认仅绑定回环地址；不建议直接对公网暴露。\n\n## 快速导航\n\n- [功能特性](#功能特性)\n- [最新功能](#最新功能)\n- [安装说明](#安装说明)\n- [使用指南](#使用指南)\n- [项目结构](#项目结构)\n- [技术栈](#技术栈)\n- [开发文档](#开发文档)\n- [版本号同步](#版本号同步)\n- [贡献指南](#贡献指南)\n- [许可证](#许可证)\n- [联系方式](#联系方式)\n- [更新日志](#更新日志)\n\n## 功能特性\n\n### 🧪 实验功能\n\n- **多种实验类型**: 滴定、合成、晶体生长、电化学等\n- **实时物理模拟**: 重力、摩擦力、碰撞检测\n- **交互式操作**: 拖拽、点击、滑动手势\n- **步骤引导**: 详细的实验步骤和验证\n\n### 🎮 游戏化体验\n\n- **物理引擎**: 60 FPS 物理更新\n- **粒子效果**: 8种不同类型的粒子效果\n- **稀有度系统**: 普通、罕见、稀有、史诗、传说\n- **分数系统**: 实时分数和连击计数\n- **成就系统**: 实验完成度和经验值\n\n### 🎨 用户界面\n\n- **现代化设计**: 暗色主题和发光效果\n- **响应式布局**: 适配不同屏幕尺寸\n- **主题切换**: 支持多种主题模式\n- **动画效果**: 流畅的过渡和反馈\n\n### ⚙️ 配置管理\n\n- **灵活配置**: 支持多种配置选项\n- **导入导出**: 配置文件的备份和恢复\n- **实时更新**: 配置更改即时生效\n- **错误处理**: 完善的异常管理\n\n## 最新功能\n\n### 🚀 开发者启动面板 (v2.0.0 新增)\n\n统一的图形化开发工具管理界面，整合所有启动脚本：\n\n- ✅ **一键启动** - 运行 `python tools/developer_panel.py`\n- ✅ **标签页分类** - 主应用、管理工具、许可证、开发工具、系统工具\n- ✅ **实时日志** - 所有输出实时显示，带时间戳\n- ✅ **进程管理** - 支持并行运行多个工具，一键停止\n- ✅ **功能整合** - 12+ 个启动脚本统一管理\n- ✅ **友好界面** - 现代化 GUI，操作简单直观\n\n📖 [查看完整文档](docs/DEVELOPER_PANEL.md)\n\n### 🔧 系统稳定性与性能优化 (v2.0.0 新增)\n\n全面的系统完善和优化，提升项目质量和性能：\n\n- ✅ **内存泄漏修复** - 优化内存管理，防止内存泄漏\n- ✅ **线程安全增强** - 统一锁机制，确保线程安全\n- ✅ **异常处理完善** - 智能错误恢复和降级处理\n- ✅ **缓存性能优化** - O(1) LRU/LFU算法，提升缓存效率\n- ✅ **事件总线优化** - 缓存正则表达式，优化事件处理\n- ✅ **懒加载改进** - 并行预加载，重试机制\n- ✅ **代码质量提升** - 减少重复，统一接口\n- ✅ **测试覆盖增强** - 新增150+测试用例\n\n📖 [查看完善报告](完善功能完成报告.md)\n\n### 🎯 用户操作流程优化 (v2.0.0 新增)\n\n- ✅ **统一流程管理器** - 清晰的用户操作流程\n- ✅ **智能启动向导** - 首次使用引导体验\n- ✅ **统一启动器** - 图形化菜单选择模式\n- ✅ **流程检查工具** - 自动化质量保证\n- ✅ **完整流程文档** - 详细的操作指南\n- ✅ **会话管理** - 自动保存和恢复进度\n\n### 实验模板创建向导\n\n- ✅ 图形化模板编辑器\n- ✅ 拖拽式步骤管理\n- ✅ 实时预览和验证\n- ✅ 一键生成YAML模板\n\n### 实验数据分析器\n\n- ✅ 详细的统计分析\n- ✅ 趋势图表可视化\n- ✅ 成绩分布分析\n- ✅ 错误模式识别\n\n### 智能缓存系统\n\n- ✅ LRU淘汰策略\n- ✅ 自动过期管理\n- ✅ 性能监控工具\n- ✅ 缓存调试器\n\n## 安装说明\n\n### 系统要求\n\n- Python 3.10+（推荐 3.11）\n- Windows 10/11, macOS 10.15+, 或 Linux\n- 4GB RAM (推荐 8GB)\n- 1GB 可用磁盘空间\n\n### 安装步骤\n\n1. **克隆仓库**\n\n   ```bash\n   git clone https://github.com/tytsxai/virtualchemlab.git\n   cd virtualchemlab\n   ```\n\n2. **创建并激活 Python 3.11 虚拟环境**\n\n   ```bash\n   python3.11 -m venv venv311\n   source venv311/bin/activate          # Linux/macOS\n   # 或\n   venv311\\\\Scripts\\\\activate           # Windows\n   ```\n\n3. **安装依赖（锁定文件优先）**\n\n   ```bash\n   pip install -r requirements.lock\n   # 如需刷新依赖，请更新 pyproject.toml 并重新生成锁定文件:\n   # pip-compile --extra=dev --extra=docs --extra=redis --extra=performance --extra=admin --extra=ops --extra=plugins --generate-hashes --output-file=requirements.lock pyproject.toml\n   ```\n   CI/发布流程同样使用 `requirements.lock` 安装，确保依赖可重复。\n\n4. **初始化环境变量和配置**\n\n   ```bash\n   cp env.example .env\n   python tools/validate_config.py\n   ```\n\n   上述脚本会按当前实现验证配置/密钥/目录，并在缺失时自动创建必要目录。\n\n5. **运行应用与测试**\n\n   ```bash\n   python main.py --env development\n   pytest -q\n   ```\n\n   \u003e 💡 在无显示环境（CI/纯终端）运行测试如遇 Qt 崩溃，可使用：`QT_QPA_PLATFORM=offscreen pytest -q` 或直接执行 `make test-fast`。\n\n6. **可选：开发者启动面板**\n\n   ```bash\n   python tools/developer_panel.py\n   ```\n\n   用于集中启动核心工具、测试和诊断程序。\n\n\u003e 💡 更多细节和扩展安装指引，请查看 `README_快速开始.md`、`QUICK_START_GUIDE.md`、`INSTALL.md`。\n\n### 开发环境设置\n\n1. **安装开发依赖**\n\n```bash\npip install -r requirements.lock\npip install --no-deps -e .\n# requirements-dev.txt 仅作为兼容入口，内部同样引用锁定文件\n```\n\n2. **安装预提交钩子**\n\n```bash\npre-commit install\n```\n\n3. **运行测试**\n\n```bash\npytest\n```\n\n\u003e Note: CI 与默认测试命令会生成覆盖率报告并执行 18% 覆盖率门禁（后续目标逐步提升到 30%，产出 `coverage.xml` 与 `htmlcov/`）。如需快速运行跳过覆盖率，可执行 `pytest --no-cov` 或 `make test-fast`。\n\u003e 💡 提示：`tests/ui/test_refactored_main_window.py` 依赖真实的 Qt 图形界面环境。在无显示服务器（例如 CI 或纯终端）中，它会自动跳过。若要完整验证 UI 行为，请在本地具备 GUI 的环境执行 `pytest tests/ui/test_refactored_main_window.py`。\n\n4. **代码格式化**\n\n```bash\nruff format src tests\nruff check src tests --fix\n```\n\n### 系统就绪检查与运维准备\n\n- 运行 `python scripts/readiness_check.py`，快速验证依赖、配置、安全与监控是否达标。\n- 更多上线、监控、回滚与性能调优细节见 `docs/OPERATIONS_READINESS.md`。\n\n### 环境变量与安全配置\n\n- `JWT_SECRET_KEY`：JWT 密钥，至少 32 个字符，生产环境必须外部提供。\n- `SESSION_SECRET_KEY`：会话密钥，至少 32 个字符，生产环境必须外部提供。\n- `DEVELOPER_SECRET_KEY`：开发者模式密钥（仅在开启开发者模式时需要），建议至少 32 个字符。\n- `VCL_ADMIN_SECRET_KEY`：管理后台/Flask 的 SECRET_KEY（**仅在启动 Admin API 时需要**），建议与 JWT/会话密钥不同。\n- `VCL_API_HOST`：API 服务监听地址，默认 `127.0.0.1`；如需对外提供服务请显式设置为 `0.0.0.0` 并配合认证/限流/防火墙。\n- `VCL_API_KEYS`：REST API 访问密钥（逗号分隔，可配置多把，**仅在启动 REST API 时需要**）。未配置时会在首次启动时自动生成并写入 `~/.virtualchemlab/api_key.txt`（以及 `~/.virtualchemlab/config.json`），用于本机开发调试；生产环境**必须**显式配置该变量（避免容器/多副本因自动生成导致密钥漂移）。\n- `VCL_API_CORS_ORIGINS`：REST API 的 CORS 允许列表（逗号分隔）。默认仅允许本机回环（`localhost/127.0.0.1/::1`）；当你将 API 暴露到局域网/容器时，建议显式配置允许的前端域名。\n- `VCL_ADMIN_CORS_ORIGINS`：管理后台 API 的 CORS 允许列表（逗号分隔，或 `*` 仅用于开发环境）。默认不启用 CORS；当你需要浏览器跨域访问或绑定到非本地主机时，请显式配置。\n- `ENVIRONMENT`：`development` / `staging` / `production`，控制默认安全策略。\n- `VCL_CONFIG_PATH`：指定用户配置文件路径（默认 `~/.virtualchemlab/config.json`），用于容器/系统服务固定挂载路径。\n\n写入 `.env` 或系统环境，例如：\n\n```bash\nexport JWT_SECRET_KEY=\"please_change_me_to_a_secure_value\"\nexport SESSION_SECRET_KEY=\"please_change_me_to_a_secure_value\"\nexport VCL_ADMIN_SECRET_KEY=\"admin_panel_secret\"\nexport ENVIRONMENT=\"production\"\n```\n\n生产环境缺少必需密钥会导致程序拒绝启动；仅在启用 Admin API/REST API 时才要求各自的密钥。\n\n## 使用指南\n\n### 快速开始\n\n**方式1：开发者面板（推荐）✨**\n\n```bash\npython tools/developer_panel.py\n```\n\n**统一的图形化管理界面**，整合所有启动脚本和工具：\n\n- 🚀 主应用启动（标准、快速、热加载、许可证模式）\n- 👨‍💼 管理工具（教师控制台、管理后台、实验管理）\n- 🔐 许可证管理（检查、备份、工具箱）\n- 🛠️ 开发工具（构建、部署、测试、工具箱）\n- 🔧 系统工具（维护、诊断、流程检查）\n\n📖 [查看完整文档](docs/DEVELOPER_PANEL.md)\n\n**方式2：命令行启动**\n\n```bash\n# 标准模式（含欢迎向导）\npython main.py\n\n# 快速模式（跳过向导）\npython main.py --skip-welcome\n\n# 热加载模式（开发调试，代码修改自动重启）\npython tools/hot_reload_launcher.py\n```\n\n**方式3：许可证验证启动**\n\n```bash\npython -m src.main_with_license\n```\n\n### 基本操作\n\n1. **启动应用**: 使用上述任一方式启动\n2. **首次使用**: 按照欢迎向导完成5步设置\n3. **选择实验**: 从实验模板库中选择\n4. **进行实验**: 按照步骤指导完成操作\n5. **查看结果**: 生成报告并查看得分\n6. **游戏模式**: 按 `Ctrl+G` 切换游戏模式\n7. **物理控制**:\n   - 空格键：震动所有物品\n   - G键：切换重力\n   - R键：重置所有物品\n\n### 配置设置\n\n1. **打开配置**: 菜单 → 设置 → 配置\n2. **调整参数**: 修改物理、UI、游戏等设置\n3. **保存配置**: 点击确定保存更改\n\n### 实验操作\n\n1. **拖拽器材**: 鼠标左键拖拽实验器材\n2. **点击交互**: 点击试剂瓶等物品\n3. **观察效果**: 查看粒子效果和物理模拟\n4. **完成步骤**: 按照提示完成实验步骤\n\n## 项目结构\n\n```\nVirtualChemLab/\n├── src/                    # 源代码\n│   ├── core/              # 核心模块\n│   │   ├── config_manager.py    # 配置管理\n│   │   ├── error_handler.py     # 错误处理\n│   │   └── experiment_controller.py  # 实验控制\n│   ├── models/            # 数据模型\n│   ├── ui/                # 用户界面\n│   │   ├── game_interaction.py  # 游戏交互\n│   │   ├── particle_system.py   # 粒子系统\n│   │   ├── config_dialog.py     # 配置对话框\n│   │   └── main_window.py       # 主窗口\n│   └── utils/             # 工具函数\n├── tests/                 # 测试代码\n├── docs/                  # 文档\n├── requirements.txt       # 依赖列表\n├── requirements-dev.txt   # 开发依赖\n├── pyproject.toml        # 项目配置\n└── README.md            # 说明文档\n```\n\n## 技术栈\n\n- **GUI框架**: PySide6 (Qt6)\n- **物理引擎**: 自定义物理模拟\n- **粒子系统**: 自定义粒子效果\n- **配置管理**: JSON配置文件\n- **错误处理**: 统一异常管理\n- **测试框架**: pytest（pytest-qt 可选；CI 默认禁用以降低 GUI/平台差异导致的波动）\n- **代码质量**: ruff（lint + format）+ mypy（可选门禁）\n\n## 开发文档\n\n### 核心文档\n\n- 📖 [开发者文档索引](docs/DEVELOPER_DOCS_INDEX.md) - 所有文档的导航中心\n- 📝 [代码风格规范](docs/CODE_STYLE_GUIDE.md) - 统一的代码和注释规范\n- 💻 [API使用示例](docs/API_USAGE_EXAMPLES.md) - 实际代码示例和最佳实践\n- 🔧 [故障排除指南](docs/TROUBLESHOOTING.md) - 常见问题和解决方案\n- 🎨 [UI组件指南](docs/UI_COMPONENTS_GUIDE.md) - UI组件使用说明\n\n### 快速链接\n\n- [架构设计](docs/ARCHITECTURE.md) - 系统架构说明\n- [配置/环境变量参考](docs/CONFIGURATION_REFERENCE.md) - 配置与安全默认值（维护安全）\n- [API参考](docs/API_REFERENCE.md) - 完整API文档\n- [性能优化](docs/PERFORMANCE_OPTIMIZATION.md) - 性能优化指南\n- [部署指南](DEPLOY.md) - 生产环境部署\n\n## 版本号同步\n\n- 单一来源：`src/__init__.py` 中的 `__version__`\n- 同步脚本：`python tools/bump_version.py 2.0.0`，省略版本号则按当前值同步 `pyproject.toml`、`config.json`、`version_info.txt`、`installer_windows.iss`\n- 便捷命令：`make bump-version VERSION=2.0.1`\n- 打包脚本：`build.sh` / `build_macos.sh` / `build_windows.bat` 读取同一版本号\n\n## 贡献指南\n\n1. Fork 项目\n2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 打开 Pull Request\n\n### 代码规范\n\n- 遵循 [代码风格规范](docs/CODE_STYLE_GUIDE.md)\n- 使用 `ruff format` 格式化代码\n- 使用 `ruff check` 检查代码质量（必要时 `--fix`）\n- 使用 `mypy` 进行类型检查（当前默认非阻塞，可按需启用严格门禁）\n- 编写单元测试\n- 更新文档\n\n详细信息请参考 [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## 许可证\n\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n\n## 联系方式\n\n- 项目主页: [https://github.com/tytsxai/virtualchemlab](https://github.com/tytsxai/virtualchemlab)\n- 问题反馈: [Issues](https://github.com/tytsxai/virtualchemlab/issues)\n- 邮箱: \u003cteam@virtualchemlab.com\u003e\n\n## 更新日志\n\n### v2.0.0 (2025-10-07) 🎉\n\n- 🎯 **用户操作流程全面优化**\n- 🚀 **新增开发者启动面板** - 统一的图形化工具管理界面\n  - 整合所有启动脚本和开发工具\n  - 实时日志输出和进程管理\n  - 标签页式界面，功能分类清晰\n  - 支持并行运行多个工具\n- ✨ 新增统一流程管理器\n- ✨ 新增智能启动向导\n- ✨ 新增统一启动器\n- ✨ 新增流程检查工具\n- ✨ 完善会话管理和状态恢复\n- 📚 新增完整的流程文档\n- 🐛 修复多项用户体验问题\n\n### v1.0.0 (2024-01-01)\n\n- 🎉 首次发布\n- ✨ 游戏化交互系统\n- ✨ 物理模拟引擎\n- ✨ 粒子效果系统\n- ✨ 配置管理系统\n- ✨ 错误处理系统\n- ✨ 单元测试框架\n\n## 致谢\n\n感谢所有贡献者和开源社区的支持！\n\n---\n\n**VirtualChemLab** - 让化学实验变得更有趣！ 🧪✨\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=tytsxai/lab-virtualchem\u0026type=Date)](https://www.star-history.com/#tytsxai/lab-virtualchem\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Flab-virtualchem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftytsxai%2Flab-virtualchem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Flab-virtualchem/lists"}