docs: 完善README文档与架构图，修复全量注释与日志问题

- README: 补充项目概述、技术栈、架构图(Mermaid)、插件生命周期时序图 - build.py: 补充模块和函数 docstring - core/__init__.py: 修正模块说明（工具箱→插件系统） - log.py: 修复过时注释，清理死代码，抑制第三方库日志刷屏 - plugin_registry.py: 修正矛盾注释，补充缺失日志，隐藏远程路径 - plugins.py: 修正过时注释，清理死代码和无用导入 - plugins_card.py: 修正错误类名注释，补充全量 docstring - main.py: 修正错误注释，补充启动/退出/插件加载日志
2026-07-21 17:04:34 +08:00
parent 0efaf2946b
commit 1b6796ec43
8 changed files with 282 additions and 138 deletions
@@ -1 +1,154 @@
-# Model_Team_Tools
+# 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**