# pyminer

**Repository Path**: py2cn/pyminer

## Basic Information

- **Project Name**: pyminer
- **Description**: pyminer 是一款基于Python的开源、跨平台数据处理计算解决方案，通过加载各种插件实现不同的需求，用易于操作的形式，在统一的界面中，通过数据计算实现用户所设想的任务。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: http://www.pyminer.com
- **GVP Project**: Yes

## Statistics

- **Stars**: 1088
- **Forks**: 264
- **Created**: 2020-08-07
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: mathlibs

**Tags**: None

## README

# Pyminer - 数据统计分析决策平台

## 项目概述

**Pyminer** 是一个基于 Electron + React 开发的轻量级数据统计分析和建模工具。应用主界面参考 Anaconda Navigator，以卡片形式提供快速访问不同功能模块。

### 核心功能

- **JupyterLab 集成**：一键启动 JupyterLab 服务，支持交互式数据分析
- **Jupyter Notebook 支持**：直接打开和编辑 Jupyter Notebook 文件
- **可视化流程分析**：通过 WeStatFlow 模块实现数据分析工作流可视化
- **代码编辑器**：集成 Monaco Editor 的代码编辑功能（WeStatCode）
- **数据处理**：数据读取、清洗、建模、预测等完整数据科学工作流
- **环境管理**：支持 Python 包管理（pip/conda）和 Kernel 管理
- **终端支持**：集成 xterm.js 提供终端环境

### 设计理念

参考以下专业数据分析工具的设计：
- SAS Enterprise Miner、SAS EG
- FICO Model Build、RapidMiner
- SPSS、Orange、MATLAB

---

## 技术架构

### 技术栈

| 组件 | 版本 |
|------|------|
| Node.js | v22.21.1 |
| Electron | Latest |
| React | 19.2.0 |
| TypeScript | 5.9.3 |
| Ant Design | 6.0.0 |
| Vite | Latest |
| Python | 3.13.9 |
| Monaco Editor | Latest |
| flexlayout-react | Latest |
| xterm.js | Latest |

### 架构组成

```
┌────────────────────────────────────────────────────┐
│         Electron 主进程 & Preload                  │
├────────────────────────────────────────────────────┤
│  React 前端 (Vite 构建)                            │
│  ├─ 标题栏 & 菜单栏                                │
│  ├─ 活动栏 & 工具栏                                │
│  ├─ 主工作区 (Dockview + flexlayout)             │
│  │  ├─ 左侧：文件管理器                            │
│  │  ├─ 中间：主工作面板 + 底部面板                 │
│  │  └─ 右侧：变量查看器、历史记录、属性           │
│  ├─ 设置页面                                      │
│  └─ 状态栏                                        │
├────────────────────────────────────────────────────┤
│  后端服务                                          │
│  ├─ JupyterLab 服务 (Python 环境)                │
│  ├─ IPC 通信层                                    │
│  └─ 文件系统、路径、配置管理                       │
├────────────────────────────────────────────────────┤
│  Python 环境 (extensions/python)                  │
│  ├─ 解释器                                        │
│  ├─ Conda/Pip 包管理                             │
│  └─ 数据科学库                                    │
└────────────────────────────────────────────────────┘
```

---

## 下载与安装

### 前置要求

- **Node.js**: v22.21.1 或更高版本
- **Python**: 3.13.9（推荐）
- **npm**: 10.9.4 或更高版本

### 项目依赖安装

#### 1. Node.js 依赖

```bash
npm install
```

#### 2. Python 环境配置

下载 Python 解释器，放在 `extensions/python` 目录下（如果当前没有则需要手动创建此目录）。

推荐 Python 安装方式：

**方案 A：使用 uv 管理 Python**

```bash
# 下载并安装 uv
uv python install 3.13.9

# uv 会自动将 Python 安装到 extensions/python
```

**方案 B：手动配置**

1. 下载 Python 3.13.9
2. 将 Python 程序放在 `extensions/python` 目录
3. 确保 `extensions/python/python.exe` 存在

#### 3. 安装 Python 包

Python 子环境中需要安装数据科学库：

```bash
cd extensions/python

# 使用 pip（推荐）
pip install -i https://mirrors.aliyun.com/pypi/simple/ \
  numpy pandas scipy scikit-learn matplotlib seaborn plotly statsmodels \
  jupyterlab notebook beautifulsoup4 xgboost lightgbm catboost \
  pymysql sqlalchemy fastapi jupyterlab-language-pack-zh-CN

# 或使用 conda
conda install -c conda-forge \
  numpy pandas scipy scikit-learn matplotlib seaborn plotly statsmodels \
  jupyterlab notebook beautifulsoup4 xgboost lightgbm catboost \
  pymysql sqlalchemy fastapi
```

**主要 Python 依赖包：**

| 包名 | 描述 |
|------|------|
| numpy | 数值计算 |
| pandas | 数据处理 |
| scipy | 科学计算 |
| scikit-learn | 机器学习 |
| matplotlib, seaborn, plotly | 数据可视化 |
| statsmodels | 统计建模 |
| jupyterlab, notebook | 交互式计算环境 |
| beautifulsoup4 | 网页解析 |
| xgboost, lightgbm, catboost | 梯度提升算法 |
| pymysql, sqlalchemy | 数据库连接 |
| fastapi | 宗旨 API 开发 |
| jupyterlab-language-pack-zh-CN | 中文语言包 |

#### 4. 其他子工具

Python 子环境中已预置：
- **Conda**：`extensions/python/condabin/conda.bat`
- **Pip**：`extensions/python/Scripts/pip.exe`

Node.js 环境中需要：
- **uv**：需要不仅安装 Python，也会用于创建新项目

---

## 开发环境配置

### 项目结构

```
pyminer/
├─ src/                    # 前端源代码
│  ├─ main/                # Electron 主进程
│  │  ├─ index.js       # 主进程入口
│  │  ├─ ipc/           # IPC 事件处理
│  │  ├─ menu/          # 菜单定义
│  │  ├─ windows/       # 窗口管理
│  │  └─ utils/         # 工具函数
│  ├─ components/           # React 组件
│  │  ├─ RibbonBar/     # 菜单栏
│  │  ├─ ActivityBar/   # 活动栏
│  │  ├─ FileExplorer/  # 文件管理器
│  │  ├─ CodeEditor/    # 代码编辑器
│  │  ├─ SqlEditor/     # SQL 编辑器
│  │  └─ ...
│  ├─ pages/                 # 页面组件
│  │  ├─ Home/          # 首页
│  │  ├─ Environment/   # 环境管理
│  │  ├─ Settings/      # 设置页面
│  │  └─ ...
│  ├─ layouts/               # 布局组件
│  │  ├─ GlobalLayout/  # 全局布局
│  │  ├─ StatusBar/     # 状态栏
│  │  └─ ...
│  ├─ stores/                # 全局状态
│  ├─ hooks/                 # 自定义 Hooks
│  ├─ theme/                 # 主题配置
│  ├─ locales/               # 国际化配置
│  ├─ assets/                # 静态资源
│  ├─ App.tsx                # 根组件
│  └─ main.tsx               # 应用入口
│
├─ public/                   # 公共资源
│  ├─ preload.js            # Preload 脚本
│  ├─ logos/                # 应用 LOGO
│  └─ ...
│
├─ extensions/              # 程序扩展
│  ├─ python/               # Python 环境
│  │  ├─ python.exe
│  │  ├─ Scripts/
│  │  ├─ condabin/
│  │  └─ Lib/
│  ├─ notebooks/            # Jupyter 上作目录
│  ├─ uv/                   # uv 工具
│  └─ ...
│
├─ vite.config.ts           # Vite 配置
├─ tsconfig.json            # TypeScript 配置
├─ package.json             # 项目配置
└─ README.md                # 本文档
```

### 开发上手

#### 1. 安装依赖

```bash
npm install
```

#### 2. 启动开发服务器

```bash
# 终端 1：启动 Vite 开发服务器（支持热更新）
npm run dev

# 终端 2：启动 Electron 开发应用
npm run electron-dev
```

应用启动后自动打开并支持热改写。在 Electron 开发者工具（F12）中可查看日志和配置信息。

---

## 运行与打包

### 运行应用

#### 开发模式

```bash
# 终端 启动 Electron 开发应用
npm run electron-dev
```

应用启动后自动打开并支持热改写。在 Electron 开发者工具（F12）中可查看日志和配置信息。

#### 生产模式

```bash
# 编译 TypeScript 并打包应用
npm run electron-pack
```

输出路径：`release/` 目录，Windows 环境下生成 NSIS 安装包。

### 打包配置注意事项

- **资源加载**：生产环境需正确配置 `publicPath` 和 `file://` 协议处理
- **extensions 目录**：确保 Python 环境和扩展工具随安装包一起发布
- **IPC 通信**：生产环境下 IPC 消息传递需确保 Preload 脚本正常加载

---

## 默认配置项

### 应用默认设置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| Python 路径 | `extensions/python/python.exe` | 项目相对路径，启动时转换为绝对路径 |
| Conda 路径 | `extensions/python/condabin/conda.bat` | 项目相对路径 |
| Pip 路径 | `extensions/python/Scripts/pip.exe` | 项目相对路径 |
| UV 路径 | `extensions/uv/uv.exe` | 项目相对路径 |
| Jupyter 工作目录 | `extensions/notebooks` | 项目相对路径，启动时转换为绝对路径 |
| Jupyter 端口 | 8888 | 默认通信端口 |
| 主题色 | 蓝色 | 应用主色调 |
| 语言 | 中文 | 应用界面语言 |
| 窗口外观 | 亮色 | light/dark |

### 路径配置规则

应用启动时，根据运行模式自动配置路径：

**开发模式** (`npm run electron-dev`)：
- 在项目根目录下寻找 `extensions` 目录
- 所有相对路径转换为项目绝对路径

**生产模式** (打包后应用)：
- 在应用根目录下寻找 `extensions` 目录
- 所有相对路径转换为应用绝对路径

---

## 核心功能指引

### 应用卡片机制

- **首页展示**：以卡片形式展示已安装的应用和功能
- **自定义应用**：支持添加、编辑、删除、收藏应用卡片
- **启动逻辑**：
  - 网页类：调用系统默认浏览器打开 URL
  - 应用类：启动本地程序或 JupyterLab 服务

### 设置页面功能

**左侧分类导航：**
- 通用设置（主题、语言、字体、开机自启）
- Python 配置（路径设置）
- Jupyter 配置（工作目录、端口）
- 应用卡片（导入/导出、管理）

**右侧设置项：**
- 对应分类的详细配置
- 支持搜索功能
- 支持恢复默认值

### 状态栏功能

状态栏显示以下信息：

| 区域 | 内容 |
|------|------|
| 左侧 | Python 版本、环保管理工具版本、Jupyter Kernel 状态 |
| 右侧 | 通知图标（铃铛）和未读通知数 |

**功能说明：**
- 点击 Python 版本号：打开 Python 版本切换窗口
- 点击 Kernel 状态：打开 Kernel 选择窗口
- 点击通知图标：展开通知面板

### 文件关联行为

| 文件类型 | 处理方式 |
|--------|--------|
| `.ipynb` | 自动启动 JupyterLab，工作目录设置为文件所在目录 |
| `.py` | 在 WeStatCode（Monaco Editor）中打开，自动进行代码着色 |
| `.csv` | 通过数据导入对话框打开，支持数据预览和导入参数设置 |

---

## 功能开发清单

### 已完成功能

- ✅ 应用主框架（Electron + React + TypeScript）
- ✅ 全局布局（标题栏、活动栏、工作区、状态栏）
- ✅ JupyterLab 集成（启动、通信、Kernel 管理）
- ✅ 代码编辑器（Monaco Editor 集成）
- ✅ 设置页面（配置管理）
- ✅ 文件管理器（基础文件浏览）
- ✅ 国际化支持（中英文切换）

### 功能规划

- 🔄 完善数据导入界面（CSV/Excel 导入）
- 🔄 数据查看器（导入数据预览）
- 🔄 环境管理页面（包管理）
- 🔄 变量查看器优化
- 🔄 历史记录查看器
- 🔄 终端组件（xterm.js）
- 🔄 应用卡片导入/导出
- 🔄 主题定制（浅色/深色）
- 🔄 Splash 启动屏

---

## 常见问题

### 关于 Python 路径

**Q: Python 路径应该如何配置？**

A: 在设置页面的 "Python 配置" 中配置绝对路径。建议使用项目自带的 Python（`extensions/python/python.exe`）。修改后重启应用生效。

### 关于 JupyterLab 服务

**Q: 点击 JupyterLab 应用卡片没有反应？**

A: 
1. 检查设置页面中的 Python 路径是否正确
2. 检查 Jupyter 工作目录是否存在
3. 查看 Electron 开发工具（F12）中的错误信息

### 关于文件关联

**Q: 打开 .py 文件后没有代码着色？**

A: 检查文件是否被正确识别，可以在 WeStatCode 的设置中手动选择语言类型。

---

## 获取帮助

- **项目源码**：[GitHub 仓库]（待补充）
- **问题反馈**：提交 Issue 或 Pull Request
- **开发文档**：查看 `src/` 目录下各模块的 README 文件

---

**最后更新**：2025 年 12 月 3 日

**版本**：3.0.1