Files
NexusLauncher/docs/README.md
2025-11-23 21:03:42 +08:00

555 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# NexusLauncher
一个现代化的 Windows 桌面应用启动器,使用 Python 3.11 和 CustomTkinter 构建。支持系统托盘、图标缩放、多项目管理等强大功能。
## 功能特性
### 主要功能
1. **项目管理**
- 支持多项目配置
- 通过下拉菜单快速切换项目
- 每个项目可配置独立的应用列表
- 项目重命名和删除功能
2. **应用启动**
- 美观的圆角方形按钮
- **自动提取并显示应用图标** 🎨
- 显示应用名称和版本号
- 一键启动配置的应用程序
- 按钮自适应排列每行3个
- 图标缓存机制,提高加载速度
- **Ctrl + 鼠标滚轮缩放图标** 🔍
3. **系统托盘集成** 🎯
- 最小化到系统托盘
- 右键菜单快速访问
- 显示主窗口、打开设置、退出应用
- 窗口定位在屏幕右下角(任务栏上方)
4. **任务管理** 📦
- 任务类型配置Character、Weapon、Prop 等)
- 可视化文件夹结构编辑器
- 节点拖拽、复制、粘贴
- 任务名称自动建议
- 自定义子文件夹结构
- 任务类型动态更新
5. **配置管理**
- 现代化的深色主题设置界面
- 添加/编辑/删除项目
- 添加/编辑/删除应用
- 支持浏览文件选择应用路径
- 配置自动保存到 JSON 文件
- **多选、复制、剪切、粘贴应用** 📋
- **拖拽排序应用顺序** 🔄
- **深色标题栏Windows 10/11** 🌙
- **预设图标选择** 🎨
- **智能图标路径** 🖼️
6. **插件系统** 🔌
- **Maya 插件集成**
- 自动设置 Maya 环境变量MAYA_SHELF_PATH、MAYA_PLUG_IN_PATH 等)
- 临时工具架加载(不保存到用户配置)
- 智能清理机制(退出时自动清理)
- 支持多版本 Maya2023、2025+
- 工具架重载脚本(开发调试用)
- **Nexus 插件包**
- 完整的 Maya 插件模板
- 三个专业工具架Modeling、Rigging、Animation
- 模块化工具包结构
- 批量挤出工具Batch Extrusion
- **Substance Painter 插件支持**
- **可扩展架构**BasePlugin 基类)
7. **高级功能**
- 应用卡片多选Ctrl、Shift
- 右键菜单(复制、剪切、粘贴、删除)
- 键盘快捷键支持
- 智能去重粘贴
- 自定义对话框(统一图标和主题)
- 模块化架构config、ui 分离)
- 跨电脑配置兼容
### 界面布局
- **主窗口**: 右下角定位,任务栏上方
- **顶部菜单栏**: 显示应用标题和设置按钮
- **项目栏**: 下拉菜单用于切换当前项目
- **按钮盘**: 显示当前项目的所有应用按钮
- **系统托盘**: 最小化后停靠在托盘区
## 系统要求
- Windows 10/11
- Python 3.11 或更高版本
## 安装依赖
```bash
python -m pip install -r requirements.txt
```
## 运行应用
### 开发模式
使用提供的脚本:
```bash
Run.bat # 正常运行(无控制台)
RunDebug.bat # 调试运行(显示控制台输出)
```
或手动运行:
```bash
pythonw main.py # 无控制台
python main.py # 显示控制台
```
### 构建 EXE
使用提供的构建脚本:
```bash
build.bat
```
**构建脚本功能:**
- 自动检查 Python 版本
- 安装/更新依赖
- 自动关闭运行中的应用
- 清理旧的构建文件
- 使用 PyInstaller 打包
或手动构建:
```bash
pyinstaller --noconfirm --onefile --windowed --name "NexusLauncher" --icon="icons/NexusLauncher.ico" --add-data "icons;icons" main.py
```
构建完成后,可执行文件位于 `dist\NexusLauncher.exe`
### 其他工具
```bash
CleanCache.bat # 清理所有 Python 缓存
TestImports.bat # 测试模块导入是否正常
```
## 使用说明
### 首次使用
1. 启动 NexusLauncher
2. 主窗口会出现在屏幕右下角(任务栏上方)
3. 点击右上角的"⚙ 设置"按钮
4. 创建新项目或使用默认的"示例项目"
5. 添加应用:
- 点击"+ 添加应用"按钮
- 填写应用名称、路径和版本号
- 可以点击"浏览"按钮选择应用程序
- 点击"保存"
### 主窗口操作
- **启动应用**: 点击应用按钮
- **缩放图标**: 按住 `Ctrl` + 鼠标滚轮
- **切换项目**: 使用顶部下拉菜单
- **最小化**: 点击关闭按钮,窗口会最小化到系统托盘
### 系统托盘
右键点击托盘图标可以:
- **显示主窗口**: 恢复主窗口
- **设置**: 打开设置界面
- **退出**: 完全退出应用
### 设置界面操作
#### 项目管理
- **新建项目**: 点击"+ 新建项目"按钮
- **重命名项目**: 点击"重命名项目"按钮
- **删除项目**: 点击"删除项目"按钮
#### 应用管理
- **添加应用**: 点击"+ 添加应用"按钮
- **编辑应用**: 点击应用卡片上的"编辑"按钮
- **删除应用**: 点击应用卡片上的"删除"按钮
#### 高级操作
- **多选应用**:
- `Ctrl + 左键`: 多选/取消选择
- `Shift + 左键`: 范围选择
- **复制应用**: `Ctrl + C` 或右键菜单
- **剪切应用**: `Ctrl + X` 或右键菜单
- **粘贴应用**: `Ctrl + V` 或右键菜单(空白处)
- **删除应用**: `Delete` 键或右键菜单
- **拖拽排序**: 拖动应用卡片左侧的手柄图标
- **取消选择**: `Esc`
### 键盘快捷键
| 快捷键 | 功能 |
|--------|------|
| `Ctrl + 鼠标滚轮` | 缩放主窗口图标 |
| `Ctrl + C` | 复制选中的应用 |
| `Ctrl + X` | 剪切选中的应用 |
| `Ctrl + V` | 粘贴应用 |
| `Delete` | 删除选中的应用 |
| `Esc` | 取消所有选择 |
## Maya 插件系统
### 功能特性
NexusLauncher 为 Maya 提供了完整的插件集成系统:
1. **自动环境配置**
- 自动设置 `MAYA_SHELF_PATH`(工具架路径)
- 自动设置 `MAYA_PLUG_IN_PATH`(插件路径)
- 自动设置 `MAYA_SCRIPT_PATH`(脚本路径)
- 自动设置 `XBMLANGPATH`(图标路径)
2. **临时工具架**
- 工具架只在 NexusLauncher 启动的 Maya 中显示
- 不保存到用户配置文件
- 退出时自动清理
- 不影响外部启动的 Maya
3. **多版本支持**
- Maya 2023
- Maya 2025
- 可扩展到其他版本
### 配置方法
`config.json` 中配置 Maya 插件:
```json
{
"app_plugins": {
"C:/Program Files/Autodesk/Maya2023/bin/maya.exe": {
"maya_plugin_path": "E:/NexusLauncher/template_plugins/maya"
}
}
}
```
### 插件目录结构
```bash
template_plugins/maya/
└── 2023/
├── scripts/
│ └── userSetup.py # Maya 启动脚本
├── shelves/
│ └── shelf_*.mel # 工具架定义
├── plug-ins/
│ └── *.py # 插件文件
└── icons/
└── *.png # 工具架图标
```
### 开发调试
在 Maya Script Editor 中运行重载脚本:
```python
import sys
sys.path.append("E:/NexusLauncher/template_plugins/maya/2023")
import RELOAD_SHELF
reload(RELOAD_SHELF)
RELOAD_SHELF.reload_shelf()
```
### 工作原理
1. **启动时**
- NexusLauncher 设置环境变量
- Maya 启动并执行 `userSetup.py`
- 禁用工具架自动保存
- 手动创建临时工具架
- 执行工具架脚本添加按钮
- 立即删除可能创建的配置文件
2. **运行时**
- 工具架正常使用
- 配置文件不存在
3. **退出时**
- 检查是否由 NexusLauncher 启动
- 删除配置文件(如果存在)
- 清理完成
4. **外部启动**
- 没有环境变量
- 没有配置文件
- 不显示 NexusLauncher 工具架
## 配置文件
配置保存在 `config.json` 文件中,格式如下:
```json
{
"projects": {
"项目名称": {
"apps": [
{
"name": "应用名称",
"path": "应用路径",
"version": "版本号"
}
]
}
},
"current_project": "当前选中的项目",
"window_size": {
"width": 400,
"height": 400
}
}
```
## 项目结构
```
NexusLauncher/
├── main.py # 主程序入口 (984 行)
├── requirements.txt # Python 依赖
├── config.json # 配置文件(自动生成)
├── config/ # 配置模块
│ ├── __init__.py
│ ├── config_manager.py # 配置管理器 (546 行)
│ └── icon_config.py # 图标配置管理器 (332 行) 🆕
├── ui/ # UI 模块
│ ├── __init__.py
│ ├── constants.py # UI 常量定义 (118 行) 🆕
│ ├── utils.py # UI 工具函数
│ ├── base_dialog.py # 对话框基类 (64 行) 🆕
│ ├── icon_manager.py # 图标管理器 (199 行) 🆕
│ ├── settings_window.py # 设置窗口 (2000+ 行)
│ ├── custom_dialogs.py # 自定义对话框 (148 行)
│ └── task/ # 任务面板模块
│ ├── __init__.py
│ ├── task_panel.py # 任务面板
│ ├── node.py # 节点类
│ └── subfolder_editor.py # 子文件夹编辑器
├── plugins/ # 插件系统
│ ├── __init__.py
│ ├── base_plugin.py # 插件基类
│ ├── plugin_manager.py # 插件管理器
│ ├── maya_plugin.py # Maya 插件
│ └── substance_painter_plugin.py # SP 插件
├── template_plugins/ # 插件模板
│ └── maya/ # Maya 插件模板
│ └── 2023/
├── icons/ # 图标资源
│ ├── NexusLauncher.ico # 应用图标
│ └── *.png # 预设图标
├── docs/ # 文档
│ ├── INDEX.md # 文档索引 🆕
│ ├── README.md # 项目说明
│ ├── CHANGELOG.md # 更新日志
│ ├── OPTIMIZATION_COMPLETE.md # 优化总结 🆕
│ ├── OPTIMIZATION_PLAN.md # 优化计划 🆕
│ ├── BUG_FIX_LOG.md # Bug 修复日志 🆕
│ ├── TROUBLESHOOTING.md # 故障排查指南 🆕
│ ├── APP_MANAGEMENT_FEATURES.md # 功能清单 🆕
│ ├── TESTING_GUIDE.md # 测试指南 🆕
│ └── CODE_STATISTICS.md # 代码统计 🆕
├── build.bat # Windows 构建脚本
├── Run.bat # 运行脚本
├── RunDebug.bat # 调试运行脚本
├── CleanCache.bat # 清理缓存脚本
└── TestImports.bat # 测试导入脚本
```
## 技术栈
- **Python 3.11**: 编程语言
- **CustomTkinter**: 现代化的 UI 框架
- **Pillow**: 图像处理库(图标加载和处理)
- **pywin32**: Windows API 调用(图标提取)
- **pystray**: 系统托盘集成
- **ctypes**: Windows DWM API深色标题栏
- **PyInstaller**: 打包工具
- **functools.lru_cache**: 图标缓存优化(性能提升 30-50%
## 开发说明
### 修改主题
`main.py` 中修改:
```python
ctk.set_appearance_mode("dark") # 可选: "dark", "light", "system"
ctk.set_default_color_theme("blue") # 可选: "blue", "green", "dark-blue"
```
### 自定义窗口大小
默认窗口大小为 400x400可在首次运行后调整程序会自动记住窗口大小。
### 自定义按钮布局
`main.py``_create_app_button` 方法中修改按钮样式和大小。
## 常见问题
### Q: 应用无法启动?
A: 请检查应用路径是否正确,确保路径指向有效的可执行文件。
### Q: 如何备份配置?
A: 复制 `config.json` 文件即可备份所有配置。
### Q: 构建的 EXE 文件很大?
A: 这是正常的,因为 PyInstaller 会打包 Python 解释器和所有依赖。如需减小体积,可以使用 `--onedir` 模式。
### Q: 应用按钮上的图标是如何显示的?
A: NexusLauncher 会自动从 .exe 文件中提取图标并显示。如果提取失败,会显示默认图标。详见 `ICON_FEATURE.md`
### Q: 图标不显示怎么办?
A: 确保已安装 pywin32 库:`pip install pywin32`。如果问题仍然存在,请检查应用路径是否正确。
### Q: 如何为 NexusLauncher 本身添加图标?
A: 可以在构建时指定图标文件:
```bash
pyinstaller --icon=icon.ico main.py
```
### Q: 多选、复制、粘贴功能不工作?
A: 请查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 获取详细的故障排查指南。
### Q: 想了解代码优化的详细信息?
A: 请查看以下文档:
- [OPTIMIZATION_COMPLETE.md](OPTIMIZATION_COMPLETE.md) - 完整的优化总结
- [CODE_STATISTICS.md](CODE_STATISTICS.md) - 详细的代码统计
- [OPTIMIZATION_PLAN.md](OPTIMIZATION_PLAN.md) - 优化实施计划
## 许可证
本项目仅供学习和个人使用。
## 更新日志
### v2.2.0 (2025-11-23) - 当前版本 ⭐
- 🎨 **Nexus 插件包**: 全新的 Maya 插件模板
- 三个专业工具架Nexus_Modeling、Nexus_Rigging、Nexus_Animation
- 模块化工具包结构modeling_tools、rigging_tools、animation_tools
- 批量挤出工具Batch Extrusion集成
- 完整的插件系统nexus_plugin.py
- 详细的文档和重载脚本
- 🔧 **插件系统增强**:
- 支持多插件包共存
- 统一的环境变量配置
- 改进的工具架加载机制
- 📝 **文档更新**:
- 更新 README.md 添加 Nexus 插件包说明
- 完善插件配置方法
- 添加开发调试指南
### v2.1.0 (2025-11-22)
- 🔌 **Maya 插件系统**: 完整的 Maya 插件集成
- 自动设置环境变量MAYA_SHELF_PATH、MAYA_PLUG_IN_PATH、XBMLANGPATH 等)
- 临时工具架加载(不保存到用户配置文件)
- 智能清理机制(启动时和退出时自动清理)
- 支持多版本 Maya2023、2025+
- 工具架重载脚本RELOAD_SHELF.py
- 🎯 **插件架构优化**:
- BasePlugin 抽象基类
- PluginManager 插件管理器
- MayaPlugin、SubstancePainterPlugin 实现
- 可扩展的插件系统
- 📝 **代码优化**:
- userSetup.py 从 348 行优化到 216 行(-38%
- 清理逻辑从 ~160 行简化到 ~30 行(-81%
- 移除复杂的路径检测,只使用 MAYA_APP_DIR
- 🐛 **Bug 修复**:
- 修复 Maya 2023 不支持 `-save` 参数的问题
- 修复工具架按钮不显示的问题
- 修复配置文件残留导致的空工具架问题
### v2.0.9 (2025-11-19) - 当前版本 ⭐
- 🚀 **代码优化**: 完成 5 个重大优化项目
- ✅ 优化 1: 使用常量替换硬编码(-50 行)
- ✅ 优化 2: 创建 BaseDialog 基类(-52 行重复代码)
- ✅ 优化 3: 使用常量优化对话框12 处替换)
- ✅ 优化 4: 创建 IconManager 类(-71 行,+30-50% 性能)
- ✅ 优化 5: 创建 IconConfigManager 类(-141 行逻辑)
- 📊 **代码质量提升**:
- 减少重复代码 83%-314 行)
- 消除硬编码 100%50+ 处)
- main.py 精简 11%1105 → 984 行)
- config_manager.py 精简 21%687 → 546 行)
- 🎯 **性能提升**:
- 图标加载性能 +30-50%LRU 缓存)
- 启动速度 +10-15%
- 缓存命中率 0% → 85%
- 🏗️ **架构改进**:
- 新增 4 个基础类IconManager, IconConfigManager, BaseDialog, constants
- 职责分离清晰,可维护性显著提升
- 代码结构更清晰,易于测试和扩展
- 🐛 **Bug 修复**:
- 修复 _darken_color 引用错误
- 修复 icon_cache 引用错误
- 📝 **文档完善**:
- 新增 9 个详细文档(优化报告、故障排查、测试指南等)
- 文档清理优化16 → 9 个核心文档)
### v2.0.8 (2025-11-18)
- 🏗️ **代码重构**: 模块化架构,分离 config 和 ui 模块
- 📦 **任务管理系统**: 新增任务面板,支持任务类型和文件夹结构管理
- 🎨 **节点编辑器**: 可视化的文件夹结构编辑器
- 🔧 **统一工具函数**: 图标路径处理统一化,支持开发和打包环境
- 🖼️ **智能图标路径**: 预设图标使用相对路径,跨电脑兼容
- 🔄 **自动关闭进程**: build.bat 自动关闭运行中的应用
- 📝 **完善文档**: 添加批处理脚本说明和重构总结
-**子窗口图标修复**: 所有子窗口正确显示应用图标
- 🎯 **任务类型动态更新**: 任务名称根据类型自动更新
- 🔍 **预设图标选择**: 编译后的应用支持预设图标显示
### v2.0.0 (2025-11-16)
- 🎯 **系统托盘集成**: 最小化到托盘,右键菜单快速访问
- 🔍 **图标缩放**: Ctrl + 鼠标滚轮动态缩放应用图标
- 📍 **窗口定位**: 主窗口自动定位在屏幕右下角(任务栏上方)
- 🌙 **深色标题栏**: 所有对话框支持 Windows 10/11 深色标题栏
- 📋 **多选操作**: 支持 Ctrl/Shift 多选应用卡片
- ✂️ **复制粘贴**: 完整的复制、剪切、粘贴功能
- 🔄 **拖拽排序**: 拖动手柄重新排列应用顺序
- 🎨 **自定义对话框**: 统一的深色主题对话框(图标、标题栏)
- ⌨️ **键盘快捷键**: 完整的快捷键支持Ctrl+C/X/V, Delete, Esc
- 🎭 **右键菜单**: 应用卡片和空白区域的上下文菜单
- 🔧 **智能去重**: 粘贴时自动去除重复应用
### v1.1.0 (2024-11-15)
- 🎨 **超高清图标**: 提取分辨率提升到 128x128源尺寸 256x256
-**图标质量**: 清晰度接近桌面图标,细节丰富,边缘平滑
- 🔧 **算法优化**: LANCZOS 高质量重采样 + 100% PNG 质量
- 📈 **视觉效果**: 图标清晰度提升 100%+
### v1.0.3 (2024-11-15)
- 🎨 **界面优化**: 按钮尺寸从 120x120 减小到 100x100
- 📈 **图标增强**: 图标分辨率从 48x48 提升到 64x64显示尺寸增加到 56x56
- ✨ 图标更清晰,细节更丰富,更易识别
- 🎯 布局更紧凑,可显示更多应用
### v1.0.1 (2024-11-15)
-**新增自动图标提取功能**
- 从 .exe 文件中自动提取并显示应用图标
- 实现图标缓存机制,提高加载速度
- 添加默认图标支持
- 优化按钮显示效果
### v1.0.0 (2024-11-15)
- 初始版本
- 支持多项目管理
- 应用启动功能
- 现代化配置界面
- 自适应按钮布局
详细更新日志请查看 [CHANGELOG.md](CHANGELOG.md)