feifei.xu
1b6796ec43
- README: 补充项目概述、技术栈、架构图(Mermaid)、插件生命周期时序图 - build.py: 补充模块和函数 docstring - core/__init__.py: 修正模块说明（工具箱→插件系统） - log.py: 修复过时注释，清理死代码，抑制第三方库日志刷屏 - plugin_registry.py: 修正矛盾注释，补充缺失日志，隐藏远程路径 - plugins.py: 修正过时注释，清理死代码和无用导入 - plugins_card.py: 修正错误类名注释，补充全量 docstring - main.py: 修正错误注释，补充启动/退出/插件加载日志
155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# Model Team Tools
|
||
|
||
面向模型团队的桌面插件化工具平台，基于 PySide6 + Nuitka 构建。
|
||
|
||
## 功能特性
|
||
|
||
- **插件热管理**：自动发现本地/远程插件，支持一键安装、更新、卸载，重启即生效
|
||
- **统一日志系统**：三路输出（文件、控制台、UI 面板），实时查看运行状态
|
||
- **暗色主题**：基于 qt-material dark_teal 主题，支持自定义 QSS 样式
|
||
- **独立分发**：Nuitka 编译为 Windows 独立可执行文件，无需安装 Python 环境
|
||
|
||
## 软件架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph UI["GUI 层 (PySide6)"]
|
||
MW[MainWindow<br/>主窗口]
|
||
PLUG[Plugins<br/>插件管理窗口]
|
||
CARD[PluginsCard<br/>插件卡片]
|
||
LOG[FrameLog<br/>日志面板]
|
||
end
|
||
|
||
subgraph CORE["Core 层"]
|
||
REG[PluginRegistry<br/>插件注册中心<br/>主线程]
|
||
WK[PluginWorker<br/>I/O 工作线程]
|
||
LH[LogHandler<br/>日志处理器]
|
||
end
|
||
|
||
subgraph HOOK["启动层"]
|
||
RH[runtime_hook<br/>sys.path 注入]
|
||
end
|
||
|
||
subgraph EXT["外部资源"]
|
||
LOCAL[本地 plugins/]
|
||
REMOTE[远程 Y:/.../plugins/*.zip]
|
||
WS[workspace/ 配置]
|
||
end
|
||
|
||
RH -->|1.注入路径| LOCAL
|
||
MW -->|2.初始化| REG
|
||
MW --> PLUG
|
||
MW --> LOG
|
||
PLUG --> CARD
|
||
CARD -->|Event| REG
|
||
REG -->|信号槽| WK
|
||
WK -->|扫描/下载| LOCAL
|
||
WK -->|扫描| REMOTE
|
||
REG -->|create_plugin| LOCAL
|
||
LH -->|写入| LOG
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 选型 |
|
||
|------|------|
|
||
| GUI | PySide6 (Qt6) |
|
||
| 主题 | qt-material |
|
||
| 打包 | Nuitka standalone (mingw64) |
|
||
| 插件格式 | .pyd + manifest.json (.zip 分发) |
|
||
| Python | 3.11 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Model_Team_Tools/
|
||
├── main.py # 程序入口，主窗口
|
||
├── main.ui / main_ui.py # 主界面定义
|
||
├── runtime_hook.py # 启动钩子：将 plugins/ 注入 sys.path
|
||
├── build.py # Nuitka 打包脚本
|
||
├── requirements.txt # 依赖清单
|
||
├── resources/ # 图标、QSS 样式
|
||
├── core/
|
||
│ ├── logging/ # 日志系统（文件+控制台+UI）
|
||
│ └── plugin/ # 插件注册中心 + 管理窗口 + 卡片组件
|
||
├── plugins/ # 本地已安装插件目录
|
||
└── workspace/ # 插件工作区配置文件
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 运行（开发模式）
|
||
python main.py
|
||
|
||
# 打包（发布模式）
|
||
python build.py
|
||
# 产物位于 output/windows-amd64/main.dist/main.exe
|
||
```
|
||
|
||
## 插件系统
|
||
|
||
### 架构
|
||
|
||
- **PluginRegistry**（主线程）：管理插件实例、QWidget 创建、信号转发
|
||
- **PluginWorker**（QThread）：扫描本地/远程插件、下载解压、读写清单文件
|
||
- **PluginsCard**（UI 组件）：展示插件信息，提供安装/更新/卸载按钮
|
||
|
||
### 生命周期
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant App as 应用启动
|
||
participant RH as runtime_hook
|
||
participant REG as PluginRegistry
|
||
participant WK as PluginWorker
|
||
participant UI as Plugins/PluginsCard
|
||
|
||
App->>RH: 启动时注入 sys.path
|
||
App->>REG: 创建 PluginRegistry
|
||
REG->>REG: 处理 .uninstall_pending 清单
|
||
REG->>WK: 启动 Worker 线程
|
||
REG->>WK: 扫描本地 plugins/
|
||
WK->>WK: 加载 .pyd → 读元数据
|
||
WK-->>REG: local_discovered
|
||
REG->>REG: import_module + create_plugin
|
||
REG-->>UI: plugins_loader_signal
|
||
REG->>WK: 扫描远程 *.zip
|
||
WK->>WK: 读 manifest.json
|
||
WK-->>REG: remote_discovered
|
||
REG-->>UI: update_plugins_card_signal
|
||
UI->>UI: 刷新卡片列表
|
||
```
|
||
|
||
### 远程插件源
|
||
|
||
默认路径：`Y:/SE/xufeifei/plugins`
|
||
|
||
远程插件以 `.zip` 格式分发，内含：
|
||
- `<tool_name>.pyd`：Nuitka 编译的插件主体
|
||
- `manifest.json`：元数据（名称、版本、描述）
|
||
- 插件依赖的 C 扩展和 stdlib 子包
|
||
|
||
### 安装/更新/卸载
|
||
|
||
| 操作 | 运行时行为 | 重启后行为 |
|
||
|------|-----------|-----------|
|
||
| 安装 | 下载 zip → 解压到 `plugins/` | 自动发现并加载 |
|
||
| 更新 | 写入 `.uninstall_pending` 清单 | 删旧目录 → 解压新版本 |
|
||
| 卸载 | 写入 `.uninstall_pending` 清单 | 删除插件目录 |
|
||
|
||
## 配置
|
||
|
||
| 配置项 | 位置 | 说明 |
|
||
|--------|------|------|
|
||
| 远程插件源 | `core/plugin/plugin_registry.py` | `REMOTE_PLUGINS_PATH` |
|
||
| 日志级别 | `core/logging/log.py` | 默认 DEBUG |
|
||
| 延迟启动间隔 | `PluginRegistry._PENDING_CLEANUP_DELAY` | 默认 1500ms |
|
||
|
||
## 版本
|
||
|
||
当前版本：**0.0.1**
|