Update

2025-11-23 20:41:50 +08:00
commit f7d5b7be07
65 changed files with 14986 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,531 @@
+# 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 等）
+     - 临时工具架加载（不保存到用户配置）
+     - 智能清理机制（退出时自动清理）
+     - 支持多版本 Maya（2023、2025+）
+     - 工具架重载脚本（开发调试用）
+   - **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/2023/plug-ins",
+      "maya_shelf_path": "E:/NexusLauncher/template/plugins/maya/2023/shelves"
+    }
+  }
+}
+```
+
+### 插件目录结构
+
+```bash
+template/plugins/maya/
+├── 2023/
+│   ├── scripts/
+│   │   └── userSetup.py          # Maya 启动脚本
+│   ├── shelves/
+│   │   └── shelf_NexusLauncher.mel  # 工具架定义
+│   ├── plug-ins/
+│   │   └── nexus_example_plugin.py  # 示例插件
+│   ├── icons/
+│   │   └── *.png                 # 工具架图标
+│   └── RELOAD_SHELF.py           # 工具架重载脚本（开发用）
+└── 2025/
+    └── (相同结构)
+```
+
+### 开发调试
+
+在 Maya Script Editor 中运行重载脚本：
+
+```python
+# 方法 1: 导入并运行
+import sys
+sys.path.append("E:/NexusLauncher/template/plugins/maya/2023")
+import RELOAD_SHELF
+RELOAD_SHELF.reload_shelf()
+
+# 方法 2: 直接执行
+exec(open("E:/NexusLauncher/template/plugins/maya/2023/RELOAD_SHELF.py").read())
+```
+
+### 工作原理
+
+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  # 子文件夹编辑器
+├── 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.1.0 (2025-11-22)
+- 🔌 **Maya 插件系统**: 完整的 Maya 插件集成
+  - 自动设置环境变量（MAYA_SHELF_PATH、MAYA_PLUG_IN_PATH、XBMLANGPATH 等）
+  - 临时工具架加载（不保存到用户配置文件）
+  - 智能清理机制（启动时和退出时自动清理）
+  - 支持多版本 Maya（2023、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)