# NeuroComplete

**Repository Path**: daoos_admin/NeuroComplete

## Basic Information

- **Project Name**: NeuroComplete
- **Description**: 一个基于Rust + egui的可视化神经网络沙盒/编辑器，配备模块化节点系统、支持本地化的用户界面，以及未来的Python/PyTorch后端。
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NeuroComplete

一款教育性神经网络设计游戏，通过可视化节点拖拽的方式让玩家从零开始学习和构建神经网络。

## 🎯 项目概述

NeuroComplete 是一款模仿《Turing Complete》设计理念的教育游戏，旨在通过直观的可视化界面和分层教学法，帮助玩家理解神经网络的底层原理。玩家从最基础的神经元单元开始，逐步构建复杂的神经网络架构，最终生成可执行的 PyTorch 代码。

### 核心特性

- 🧠 **分层教学**：从单个神经元到复杂的 Transformer 模型
- 🎮 **游戏化学习**：通过关卡系统逐步解锁新的网络组件
- 🔧 **可视化设计**：拖拽式节点编辑器，直观构建网络架构
- 🐍 **代码生成**：自动将可视化设计转换为 PyTorch 代码
- 🌐 **多语言支持**：基于 JSON 的本地化系统
- 📚 **教育导向**：每个组件都附带详细的原理解释

## 🏗️ 技术架构

### 前端 (Rust + egui)
- **UI 框架**：eframe + egui，提供跨平台的原生 GUI
- **渲染引擎**：egui_glow，支持 GPU 加速渲染
- **节点系统**：自定义的可视化节点图编辑器
- **状态管理**：基于 Rust 的类型安全状态管理

### 后端 (Python + PyTorch)
- **深度学习框架**：PyTorch，用于执行生成的神经网络代码
- **代码生成**：将可视化设计转换为标准的 PyTorch 模型
- **训练执行**：支持模型训练和推理

### 数据层
- **组件定义**：JSON 格式的神经网络组件库
- **关卡数据**：Markdown 格式的关卡设计和教学内容
- **本地化**：JSON 格式的多语言字符串资源

## 📁 项目结构

```
NeuroComplete/
├── neuro_complete/           # 主程序 (Rust)
│   ├── src/
│   │   ├── main.rs          # 程序入口
│   │   ├── menu.rs          # 主菜单界面
│   │   ├── fog_shader.rs    # GPU 雾化效果
│   │   ├── node_system/     # 节点管理系统
│   │   │   ├── mod.rs       # 节点管理器
│   │   │   ├── loader.rs    # JSON 组件加载器
│   │   │   └── generator.rs # 程序化节点生成器
│   │   └── sandbox_editor/  # 沙盒编辑器
│   │       ├── mod.rs       # 编辑器主模块
│   │       ├── node_graph_advanced.rs # 高级节点图
│   │       ├── node_display.rs        # 节点展示面板
│   │       ├── draggable_node.rs      # 可拖拽节点
│   │       ├── node_generator_ui.rs   # 节点生成器 UI
│   │       └── ...
│   ├── assets/
│   │   ├── strings.json     # 本地化字符串
│   │   └── readme.txt       # 帮助文档
│   └── Cargo.toml           # Rust 依赖配置
├── 元件设计/                 # 组件设计文档
│   ├── 基础元件/            # 基础神经网络组件
│   ├── 常用模块/            # 常用网络层
│   ├── 高级模块/            # 高级网络架构
│   ├── IO元件/              # 输入输出组件
│   └── 模块设计思路          # 设计理念文档
├── 原件JSON实现/            # JSON 格式的组件定义
│   ├── 基础元件/
│   ├── 常用模块/
│   ├── 高级模块/
│   └── IO元件/
└── 关卡设计/                # 游戏关卡设计
    ├── 章节规划.md          # 整体章节规划
    └── 第一章/             # 第一章关卡内容
        ├── 关卡1.md
        ├── 关卡2.md
        └── ...
```

## 🎓 教学体系

### 第一章：神经元与激活函数 (15关)
- 理解神经元的基本计算原理
- 掌握权重、偏置的作用
- 学习激活函数（ReLU、Sigmoid）
- 完成基础回归与分类任务

### 第二章：全连接层与多层感知器 (15关)
- 组合神经元构建全连接层
- 理解多层感知器（MLP）架构
- 解决非线性问题（如 XOR）

### 第三章：损失函数与优化器 (15关)
- 掌握损失函数（MSE、BCE）
- 学习优化器（SGD、Adam）
- 体验完整的训练过程

### 第四章：卷积与池化层 (15关)
- 理解卷积层在图像处理中的作用
- 学习池化层的降维原理
- 构建基础 CNN 模型

### 第五章：高级模块与残差结构 (15关)
- 拼装高级组件（残差块、跳跃连接）
- 解决深层网络训练难题

### 第六章：Transformer与注意力机制 (15关)
- 探索序列建模原理
- 理解注意力机制
- 构建基础 Transformer 模型

## 🚀 快速开始

### 环境要求

- **Rust**: 1.70+ (推荐使用 rustup 安装)
- **Python**: 3.8+ (用于后端代码生成和执行)
- **PyTorch**: 1.12+ (深度学习框架)
- **操作系统**: Windows 10+, macOS 10.15+, Linux

### 安装步骤

1. **克隆仓库**
   ```bash
   git clone https://github.com/your-username/NeuroComplete.git
   cd NeuroComplete
   ```

2. **构建 Rust 程序**
   ```bash
   cd neuro_complete
   cargo build --release
   ```

3. **安装 Python 依赖**
   ```bash
   pip install torch torchvision torchaudio
   ```

4. **运行程序**
   ```bash
   cargo run
   ```

### 开发模式

```bash
# 开发模式运行（支持热重载）
cargo run

# 检查代码质量
cargo check
cargo clippy

# 运行测试
cargo test
```

## 🎮 使用指南

### 主界面
- **开始游戏**：进入关卡模式，按章节学习
- **沙盒模式**：自由设计神经网络
- **设置**：调整语言、主题等选项

### 沙盒编辑器
1. **节点面板**：右侧展示可用的神经网络组件
2. **画布区域**：中央的节点图编辑区域
3. **属性面板**：调整选中节点的参数
4. **代码生成**：将设计转换为 PyTorch 代码

### 节点操作
- **拖拽**：从右侧面板拖拽节点到画布
- **连接**：点击节点的输入/输出端口建立连接
- **编辑**：双击节点编辑参数
- **删除**：选中节点后按 Delete 键

## 🔧 开发指南

### 代码规范
- 遵循 Rust 官方代码风格
- 使用 `cargo fmt` 格式化代码
- 使用 `cargo clippy` 检查代码质量
- 目标：0 warnings, 0 errors

### 添加新组件
1. 在 `原件JSON实现/` 目录下创建 JSON 定义
2. 在 `元件设计/` 目录下添加设计文档
3. 更新节点加载器以支持新组件
4. 添加相应的 PyTorch 代码生成逻辑

### 本地化
- 所有 UI 文本存储在 `assets/strings.json`
- 支持多语言切换
- 添加新语言需要创建对应的 JSON 文件

## 🤝 贡献指南

我们欢迎各种形式的贡献！

### 如何贡献
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献类型
- 🐛 **Bug 修复**：修复现有功能的问题
- ✨ **新功能**：添加新的神经网络组件或编辑器功能
- 📚 **文档**：改进文档、添加教程
- 🌐 **本地化**：添加新语言支持
- 🎨 **UI/UX**：改进用户界面和体验
- 🧪 **测试**：添加或改进测试用例

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- 感谢 [Turing Complete](https://turingcomplete.game/) 提供的设计灵感
- 感谢 [egui](https://github.com/emilk/egui) 提供优秀的 GUI 框架
- 感谢 [PyTorch](https://pytorch.org/) 提供强大的深度学习框架

## 📞 联系我们

- **项目主页**：[GitHub Repository](https://github.com/your-username/NeuroComplete)
- **问题反馈**：[Issues](https://github.com/your-username/NeuroComplete/issues)
- **讨论交流**：[Discussions](https://github.com/your-username/NeuroComplete/discussions)

---

**NeuroComplete** - 让神经网络学习变得简单有趣！ 🧠✨