# SPytools

**Repository Path**: dreamyuf/SPytools

## Basic Information

- **Project Name**: SPytools
- **Description**: SPyTools 是一个基于 PySide6 的模块化桌面工具框架，采用 框架-工具分离 设计。框架自动发现、加载和管理独立工具，所有工具在主窗口内以标签页形式运行。
- **Primary Language**: Python
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# SPyTools - 模块化Python工具集框架

## 概述

SPyTools 是一个现代化的、可扩展的Python桌面应用程序框架。该框架实现了框架代码与工具集代码的完全分离，支持动态加载工具模块并自动生成相应的用户界面。通过SPyTools，开发者可以专注于工具逻辑的实现，而无需关心底层的框架机制。

## 功能特性

### 核心功能
- **模块化设计**：框架核心与工具模块完全解耦，通过清晰的接口规范实现工具的热插拔
- **自动发现机制**：系统启动时自动扫描tools目录，识别并加载所有有效的工具模块
- **插件系统**：支持运行时动态加载和卸载工具，无需重启应用即可生效

### 用户界面
- **现代化UI设计**：采用PyQt5构建专业的桌面应用界面
- **主题切换**：内置深色/浅色两套主题，支持一键切换
- **标签页管理**：多工具同时运行时采用标签页形式组织，提升操作效率

### 用户管理
- **多角色支持**：内置管理员(ADMIN)、普通用户(USER)和访客(GUEST)三种角色
- **权限控制**：基于角色的细粒度应用访问权限管理
- **用户管理界面**：提供完整的用户添加、删除、角色修改和密码管理功能
- **登录系统**：支持用户登录、注销和自动登录访客账户

### 配置管理
- **持久化存储**：自动保存应用设置和工具配置
- **最近使用**：记录用户最近使用的工具，方便快速访问

## 安装依赖

```bash
# 克隆项目
git clone https://gitee.com/dreamyuf/SPytools.git
cd SPytools

# 安装依赖
pip install -r requirements.txt
```

**依赖环境要求：**
- Python 3.7+
- PyQt5 5.15+

## 项目结构

```
SPyTools/
├── framework/           # 框架核心模块
│   ├── base_tool.py    # 工具基类定义
│   ├── plugin_manager.py # 插件/工具管理
│   ├── config_manager.py # 配置管理
│   ├── style_manager.py  # 主题样式管理
│   ├── user_manager.py   # 用户和权限管理
│   ├── main_window.py    # 主窗口实现
│   ├── login_dialog.py   # 登录对话框
│   └── ...
├── tools/              # 工具模块目录
│   ├── calculator/     # 计算器工具
│   ├── system_info/    # 系统信息工具
│   └── text_editor/    # 文本编辑器工具
├── config/             # 配置文件目录
├── resources/          # 资源文件
│   └── styles/         # 主题样式文件
├── run.sh              # Linux/macOS启动脚本
├── run.bat             # Windows启动脚本
└── HOW_TO_ADD_TOOL.md  # 工具开发指南
```

## 快速开始

### Linux/macOS
```bash
chmod +x run.sh
./run.sh
```

### Windows
```cmd
run.bat
```

首次启动时，系统会自动创建默认配置文件。默认管理员账户为 `admin`，密码为 `admin123`。

## 内置工具

### 计算器 (Calculator)
提供基础算术运算和科学计算功能的桌面计算器工具。

### 系统信息 (System Info)
实时监控系统资源使用情况，包括CPU、内存、磁盘和网络状态。

### 文本编辑器 (Text Editor)
轻量级文本编辑器，支持文件打开、保存和字符统计功能。

## 扩展开发

SPyTools 提供了简单易用的工具开发接口。参考 `HOW_TO_ADD_TOOL.md` 文档，您可以快速创建新的工具模块。

### 创建工具的基本步骤：

1. 在 `tools/` 目录下创建工具目录
2. 编写 `metadata.json` 元数据文件
3. 继承 `BaseTool` 基类实现工具逻辑
4. 使用 PyQt5 构建工具界面
5. 在目录中创建 `__init__.py` 完成模块注册

### 工具类接口：

```python
from framework.base_tool import BaseTool

class MyTool(BaseTool):
    @classmethod
    def metadata(cls):
        return {
            "id": "my_tool",
            "name": "我的工具",
            "version": "1.0.0",
            "description": "工具描述",
            "category": "工具分类"
        }
    
    def create_widget(self):
        # 返回工具的主界面控件
        return MyToolUI(self)
    
    def on_activate(self):
        # 工具被激活时调用
        pass
    
    def on_deactivate(self):
        # 工具被切换离开时调用
        pass
```

## 配置文件说明

### app_config.ini
应用运行时的配置参数，包括窗口设置、默认主题等。

### tools_config.json
工具的配置存储，每个工具可独立保存其运行时配置。

### users.json
用户账户数据，包含用户名、密码哈希、角色和可用应用列表。

### app_permissions.json
应用权限定义，配置各角色对不同工具的访问权限。

## 打包发布

项目提供了 `resources/setup.py` 脚本，可使用 PyInstaller 将应用打包为独立可执行文件：

```bash
python resources/setup.py
```

打包后的文件将生成在 `dist/` 目录下，可直接分发给终端用户使用。

## 许可证

本项目采用 MIT 许可证开源。详情请参阅 LICENSE 文件。

## 贡献指南

欢迎通过以下方式参与项目贡献：
- 提交问题反馈
- 贡献新的工具模块
- 完善文档和示例

## 联系方式

- 项目地址：https://gitee.com/dreamyuf/SPytools
- 问题反馈：请在 Gitee 项目页面提交 Issue