refactor: 创建 plugin_sdk 包，重构插件系统架构

- 创建 plugin_sdk 包，将插件开发 API 独立出来
- 移动 config_types、plugin_base、service_registry、server_bridge 到 plugin_sdk
- 移动 shared_types/services 到 plugins/services
- 重构配置系统：create_widget 返回 ConfigWidgetBase
- 添加服务等待机制 wait_for_service
- 重构 history 插件为包形式
- 更新插件管理器 UI：按钮移至工具栏
- 更新 build.bat 和 plugin-dev-tutorial.md

Author: ljzloser

build.bat

@@ -25,6 +25,7 @@ echo.
 echo [3/3] Copy resources to metaminsweeper\
 copy /y "%OUT%\plugin_manager\plugin_manager.exe" "%DEST%\"
 xcopy /e /y /i "%OUT%\plugin_manager\_internal" "%DEST%\_internal" >nul
+xcopy /e /y /i "src\plugin_sdk" "%DEST%\plugin_sdk" >nul
 xcopy /e /y /i "src\plugin_manager" "%DEST%\plugin_manager" >nul
 xcopy /e /y /i "src\plugins" "%DEST%\plugins" >nul
 xcopy /e /y /i "src\shared_types" "%DEST%\shared_types" >nul

plugin-dev-tutorial.md

@@ -63,17 +63,19 @@ Meta-Minesweeper 采用 **ZMQ 多进程插件架构**：
 ├── plugin_manager.exe          # 插件管理器
 ├── plugins/                    # 👈 用户插件放这里！
 │   ├── my_hello.py             # 你的插件（单文件）
-│   └── my_complex/             # 或包形式插件
-│       ├── __init__.py
-│       └── utils.py
-├── shared_types/               # 共享类型定义
-│   ├── events.py               # 事件类型
-│   ├── commands.py             # 指令类型
+│   ├── my_complex/             # 或包形式插件
+│   │   ├── __init__.py
+│   │   └── utils.py
 │   └── services/               # 👈 服务接口定义
 │       └── history.py          # HistoryService 接口
-├── plugin_manager/             # 插件管理器模块
+├── plugin_sdk/                 # 插件开发 SDK
 │   ├── plugin_base.py          # 👈 BasePlugin 基类
-│   └── service_registry.py     # 服务注册表
+│   ├── service_registry.py     # 服务注册表
+│   └── config_types/           # 配置类型
+├── shared_types/               # 共享类型定义
+│   ├── events.py               # 事件类型
+│   └── commands.py             # 指令类型
+├── plugin_manager/             # 插件管理器内部模块
 ├── user_plugins/               # 备用用户插件目录
 ├── data/
 │   ├── logs/                   # 日志输出（自动创建）
@@ -144,6 +146,7 @@ plugins/
 ### 3.3 自动发现规则
 
 - 文件/目录名以 `_` 开头的会被跳过（如 `_template.py`）
+- `services` 目录会被跳过（它是服务接口定义，不是插件）
 - 单个 `.py` 文件中可以定义多个继承 `BasePlugin` 的类，都会被加载
 - 包形式插件中，只有 `__init__.py` 中导出的 `BasePlugin` 子类会被发现
 
@@ -167,7 +170,7 @@ from PyQt5.QtWidgets import QWidget, QVBoxLayout, QLabel, QTextEdit
 from PyQt5.QtCore import Qt, pyqtSignal
 
 # 导入插件基类和辅助类型
-from plugin_manager import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
+from plugin_sdk import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
 
 # 导入可用的事件类型
 from shared_types.events import VideoSaveEvent
@@ -466,7 +469,19 @@ if self.has_service(MyService):
     pass
 
 # ════════════════════════════════════════
-# 3. 获取服务代理（推荐）
+# 3. 等待服务就绪（推荐）
+# ════════════════════════════════════════
+# 如果服务提供者可能在消费者之后初始化，使用 wait_for_service
+service = self.wait_for_service(MyService, timeout=10.0)
+if service:
+    # 服务可用
+    data = service.get_data(123)
+else:
+    # 服务未就绪
+    self.logger.warning("MyService 未就绪")
+
+# ════════════════════════════════════════
+# 4. 获取服务代理（已知服务存在时）
 # ════════════════════════════════════════
 service = self.get_service_proxy(MyService)
 
@@ -475,7 +490,7 @@ data = service.get_data(123)        # 同步调用，阻塞等待结果
 all_data = service.list_data(100)   # 超时默认 10 秒
 
 # ════════════════════════════════════════
-# 4. 异步调用（非阻塞）
+# 5. 异步调用（非阻塞）
 # ════════════════════════════════════════
 future = self.call_service_async(MyService, "get_data", 123)
 # 做其他事情...
@@ -488,7 +503,8 @@ result = future.result(timeout=5.0)  # 阻塞等待结果
 |------|------|
 | `register_service(self, protocol=MyService)` | 注册服务（在 `on_initialized` 中调用） |
 | `has_service(MyService)` | 检查服务是否可用 |
-| `get_service_proxy(MyService)` | 获取服务代理对象（推荐） |
+| `wait_for_service(MyService, timeout=10.0)` | 等待服务就绪并获取代理（推荐） |
+| `get_service_proxy(MyService)` | 获取服务代理对象（已知存在时） |
 | `call_service_async(MyService, "method", *args)` | 异步调用，返回 Future |
 
 **注意事项：**
@@ -566,7 +582,7 @@ class PluginInfo:
 继承 `OtherInfoBase` 并声明配置字段：
 
 ```python
-from plugin_manager.config_types import (
+from plugin_sdk import (
     OtherInfoBase, BoolConfig, IntConfig, FloatConfig,
     ChoiceConfig, TextConfig, ColorConfig, FileConfig,
     PathConfig, LongTextConfig, RangeConfig,
@@ -742,9 +758,9 @@ data/plugin_data/<plugin_name>/config.json
 如果预定义的配置类型不满足需求，可以继承 `BaseConfig` 创建自定义类型：
 
 ```python
-from plugin_manager.config_types.base_config import BaseConfig
-from PyQt5.QtWidgets import QWidget, QVBoxLayout, QLabel, QDial
-from PyQt5.QtCore import Qt
+from plugin_sdk.config_types import BaseConfig, ConfigWidgetBase, ConfigWidgetWrapper
+from PyQt5.QtWidgets import QDial
+from typing import Any
 
 class DialConfig(BaseConfig[int]):
     """旋钮配置 → QDial 控件"""
@@ -762,8 +778,8 @@ class DialConfig(BaseConfig[int]):
         self.min_value = min_value
         self.max_value = max_value
 
-    def create_widget(self):
-        """创建自定义 UI 控件，返回 (控件, getter, setter, 信号)"""
+    def create_widget(self) -> ConfigWidgetBase:
+        """创建自定义 UI 控件，返回 ConfigWidgetBase 实例"""
         widget = QDial()
         widget.setRange(self.min_value, self.max_value)
         widget.setValue(int(self.default))
@@ -772,14 +788,23 @@ class DialConfig(BaseConfig[int]):
         if self.description:
             widget.setToolTip(self.description)
 
-        # 返回控件、getter、setter、以及 valueChanged 信号
-        return widget, widget.value, widget.setValue, widget.valueChanged
+        # 使用 ConfigWidgetWrapper 包装控件
+        # 参数：控件, getter, setter, 信号
+        return ConfigWidgetWrapper(
+            widget,
+            widget.value,      # getter
+            widget.setValue,   # setter
+            widget.valueChanged  # 信号
+        )
 
     def to_storage(self, value: int) -> int:
         return int(value)
 
-    def from_storage(self, data) -> int:
-        return int(data)
+    def from_storage(self, data: Any) -> int:
+        try:
+            return int(data)
+        except (ValueError, TypeError):
+            return int(self.default)
 
 # 使用自定义配置类型
 class MyConfig(OtherInfoBase):
@@ -792,29 +817,53 @@ class MyConfig(OtherInfoBase):
 | 方法/属性 | 说明 |
 |-----------|------|
 | `widget_type` | 控件类型标识 |
-| `create_widget()` | 返回 `(控件, getter, setter, 信号)` 四元组 |
+| `create_widget()` | 返回 `ConfigWidgetBase` 实例 |
 | `to_storage(value)` | 将值转换为 JSON 可序列化格式 |
 | `from_storage(data)` | 从 JSON 数据恢复值 |
 
-**信号对象说明：**
+**ConfigWidgetBase 接口：**
+
+`create_widget()` 必须返回一个实现了以下接口的对象：
+
+| 方法/信号 | 说明 |
+|-----------|------|
+| `get_value() -> Any` | 获取当前值 |
+| `set_value(value: Any)` | 设置当前值 |
+| `value_change` | `pyqtSignal(object)` 值变化信号 |
 
-信号对象可以是：
-- Qt 控件的内置信号（如 `widget.valueChanged`、`widget.textChanged`）
-- 自定义 `pyqtSignal`（需要通过 QObject 子类定义）
+**使用 ConfigWidgetWrapper：**
+
+对于简单的包装需求，可以使用 `ConfigWidgetWrapper`：
 
 ```python
-# 方式一：使用控件的内置信号
-return widget, widget.value, widget.setValue, widget.valueChanged
+return ConfigWidgetWrapper(widget, getter, setter, signal)
+```
+
+**创建自定义 ConfigWidgetBase 子类：**
 
-# 方式二：自定义信号（复杂控件）
-from PyQt5.QtCore import QObject, pyqtSignal
+对于复杂控件，可以创建 `ConfigWidgetBase` 的子类：
 
-class MySignal(QObject):
-    changed = pyqtSignal()
+```python
+from plugin_sdk.config_types import ConfigWidgetBase
+from PyQt5.QtCore import pyqtSignal
 
-signal_emitter = MySignal(parent=container)  # parent 防止垃圾回收
-# ... 控件变化时调用 signal_emitter.changed.emit()
-return container, get_value, set_value, signal_emitter.changed
+class MyCustomWidget(ConfigWidgetBase):
+    """自定义配置控件"""
+    
+    # 子类会继承 value_change = pyqtSignal(object) 信号
+    
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        # 创建内部控件...
+    
+    def get_value(self) -> Any:
+        """获取当前值"""
+        return self._internal_widget.value()
+    
+    def set_value(self, value: Any) -> None:
+        """设置当前值"""
+        self._internal_widget.setValue(value)
+        self.value_change.emit(value)  # 发射信号
 ```
 
 ---
@@ -842,7 +891,7 @@ from PyQt5.QtWidgets import (
 from PyQt5.QtCore import Qt, pyqtSignal, QTimer
 from PyQt5.QtGui import QFont
 
-from plugin_manager import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
+from plugin_sdk import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
 from shared_types.events import VideoSaveEvent, BoardUpdateEvent
 
 
@@ -1103,10 +1152,10 @@ def on_initialized(self):
 
 #### 1. 定义服务接口
 
-在 `shared_types/services/` 目录下创建接口定义文件：
+在 `plugins/services/` 目录下创建接口定义文件：
 
 ```python
-# shared_types/services/my_service.py
+# plugins/services/my_service.py
 from typing import Protocol, runtime_checkable
 from dataclasses import dataclass
 
@@ -1126,6 +1175,8 @@ class MyService(Protocol):
 #### 2. 服务提供者
 
 ```python
+from plugins.services.my_service import MyService, MyData
+
 class ProviderPlugin(BasePlugin):
     def on_initialized(self):
         # 注册服务（显式指定 protocol）
@@ -1142,16 +1193,36 @@ class ProviderPlugin(BasePlugin):
 #### 3. 服务使用者
 
 ```python
+from plugins.services.my_service import MyService, MyData
+
 class ConsumerPlugin(BasePlugin):
     def on_initialized(self):
-        if self.has_service(MyService):
-            # 获取服务代理（推荐）
-            self._service = self.get_service_proxy(MyService)
+        # 方式一：等待服务就绪（推荐）
+        self._service = self.wait_for_service(MyService, timeout=10.0)
+        if self._service is None:
+            self.logger.warning("MyService 未就绪")
 
     def _do_something(self):
-        # 调用服务方法（IDE 完整补全，在服务提供者线程执行）
-        data = self._service.get_data(123)
-        all_data = self._service.list_data(100)
+        if self._service:
+            # 调用服务方法（IDE 完整补全，在服务提供者线程执行）
+            data = self._service.get_data(123)
+            all_data = self._service.list_data(100)
+```
+
+#### 4. 等待服务就绪
+
+如果服务提供者可能在消费者之后初始化，可以使用 `wait_for_service`：
+
+```python
+def on_initialized(self):
+    # 等待服务就绪，最多 10 秒
+    service = self.wait_for_service(MyService, timeout=10.0)
+    if service:
+        # 服务可用
+        data = service.get_data(123)
+    else:
+        # 服务未就绪，可以稍后重试或降级处理
+        self.logger.warning("MyService 未就绪")
 ```
 
 #### 服务调用方式
@@ -1221,10 +1292,10 @@ class ConsumerPlugin(BasePlugin):
 ```python
 # ═══ 最小可行插件模板 ═══
 
-from plugin_manager import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
-from plugin_manager.config_types import OtherInfoBase, BoolConfig, IntConfig  # 可选
+from plugin_sdk import BasePlugin, PluginInfo, make_plugin_icon, WindowMode
+from plugin_sdk import OtherInfoBase, BoolConfig, IntConfig  # 配置类型（可选）
 from shared_types.events import VideoSaveEvent  # 按需导入
-from shared_types.services.my_service import MyService  # 服务接口（可选）
+from plugins.services.my_service import MyService  # 服务接口（可选）
 
 # ═══ 配置类定义（可选） ═══
 class MyConfig(OtherInfoBase):

src/main.py

@@ -16,7 +16,7 @@
 from utils import get_paths, patch_env
 
 # 插件系统（新）
-from plugin_manager import GameServerBridge
+from plugin_sdk import GameServerBridge
 from plugin_manager.app_paths import get_env_for_subprocess
 import subprocess
 
@@ -56,7 +56,8 @@ def cli_check_file(file_path: str) -> int:
             for root, _, files in os.walk(file_path):
                 for file in files:
                     if file.endswith((".evf", ".evfs")):
-                        evf_evfs_files.append(os.path.abspath(os.path.join(root, file)))
+                        evf_evfs_files.append(
+                            os.path.abspath(os.path.join(root, file)))
 
         if not evf_evfs_files:
             result["error"] = "must be evf or evfs files or directory"
@@ -80,7 +81,8 @@ def cli_check_file(file_path: str) -> int:
                         checksum = ui.checksum_guard.get_checksum(
                             video.raw_data[: -(len(video.checksum) + 2)]
                         )
-                        evf_evfs_files[ide] = (e, 0 if list(video.checksum) == list(checksum) else 1)
+                        evf_evfs_files[ide] = (e, 0 if list(
+                            video.checksum) == list(checksum) else 1)
                 elif e.endswith(".evfs"):
                     videos = ms.Evfs(e)
                     try:
@@ -92,14 +94,16 @@ def cli_check_file(file_path: str) -> int:
                             evf_evfs_files[ide] = (e, 2)
                             continue
 
-                        checksum = ui.checksum_guard.get_checksum(videos[0].evf_video.raw_data)
+                        checksum = ui.checksum_guard.get_checksum(
+                            videos[0].evf_video.raw_data)
                         if list(videos[0].checksum) != list(checksum):
                             evf_evfs_files[ide] = (e, 1)
                             continue
 
                         for idcell, cell in enumerate(videos[1:]):
                             checksum = ui.checksum_guard.get_checksum(
-                                cell.evf_video.raw_data + videos[idcell - 1].checksum
+                                cell.evf_video.raw_data +
+                                videos[idcell - 1].checksum
                             )
                             if list(cell.evf_video.checksum) != list(checksum):
                                 evf_evfs_files[ide] = (e, 1)
@@ -114,7 +118,8 @@ def cli_check_file(file_path: str) -> int:
                     if isinstance(item, tuple) and len(item) == 2
                 ]
 
-    output_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "out.json")
+    output_file = os.path.join(os.path.dirname(
+        os.path.abspath(__file__)), "out.json")
     with open(output_file, "w", encoding="utf-8") as f:
         json.dump(result, f, ensure_ascii=False, indent=2)
 
@@ -155,8 +160,6 @@ def cli_check_file(file_path: str) -> int:
         ui.mainWindow.show()
 
         # ── 启动 ZMQ Server + 插件管理器 ──
-        game_server = GameServerBridge(ui)
-        ui.gameServerBridge = game_server
 
         # 打包后直接调用 plugin_manager.exe，开发模式用 python -m
         if getattr(sys, 'frozen', False):
@@ -194,10 +197,7 @@ def cli_check_file(file_path: str) -> int:
 
         ui._plugin_process = plugin_process  # 保存引用，防止被 GC
 
-        # 连接信号：插件发来的新游戏指令 → 主线程处理
-        game_server.signals.new_game_requested.connect(lambda r, c, m: None)  # TODO: 接入游戏逻辑
-
-        game_server.start()
+        GameServerBridge.instance().start()
 
         # _translate = QtCore.QCoreApplication.translate
         hwnd = int(ui.mainWindow.winId())
@@ -210,7 +210,7 @@ def cli_check_file(file_path: str) -> int:
         )
 
         def _cleanup():
-            game_server.stop()
+            GameServerBridge.instance().stop()
             if plugin_process is not None and plugin_process.poll() is None:
                 plugin_process.terminate()
                 plugin_process.wait(timeout=5)