model_team_tools/README.md

# 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**