plugin_api.py

"""
插件开发API接口
为插件开发者提供统一的主程序功能访问入口

使用示例:
    from plugin_api import PluginAPI

    api = PluginAPI.get_instance()

    # 访问数据
    blueprints = api.data.get_blueprints_paginated(page=1, page_size=10)

    # 访问配置
    theme = api.config.get("UI", "theme", "star lines")

    # 注册生命周期钩子
    def on_ready(main_window):
        print("UI已就绪")
    api.register_hook('on_ui_ready', on_ready)

    # 调用主程序暴露的函数
    result = api.call_function('get_main_window')

    # 接管UI（插件实现 UIPluginBase 后注册主视图）
    api.ui.register_main_view(my_plugin)

    # 订阅数据变更
    api.events.subscribe('index_changed', lambda payload: print("索引已更新"))

    # 资源操作
    api.ops.install_to_game(game_path, resource_path)
"""
import os
import threading
from typing import Any, Dict, List, Optional, Callable, Tuple

from PySide6.QtCore import QObject

from observed_event import ObservedEvent
from resource_metadata import METADATA, ID_TO_MY_CATEGORY, RESOURCE_TYPE_IDS
from resource_operations import TYPE_OPS, ResourceOperations, filter_intro_to_version
from resource_loader import _LOADER_MAP


# ==================== 钩子系统 ====================

class HookRegistry:
    """钩子注册中心 — 管理所有生命周期钩子和暴露函数"""

    def __init__(self):
        self._hooks: Dict[str, List[Callable]] = {}
        self._exposed_functions: Dict[str, Callable] = {}
        self._main_window_ready = False
        self._main_window = None

    # ---- 钩子管理 ----

    def register(self, hook_name: str, callback: Callable):
        """插件注册一个钩子回调。
        若注册 on_ui_ready 时主窗口已就绪，立即调用回调（支持延迟注册）。"""
        if hook_name not in self._hooks:
            self._hooks[hook_name] = []
        if callback not in self._hooks[hook_name]:
            self._hooks[hook_name].append(callback)
        # 延迟钩子：若注册 on_ui_ready 时窗口已就绪，立即触发
        if hook_name == 'on_ui_ready' and self._main_window_ready and self._main_window:
            try:
                callback(self._main_window)
            except Exception as e:
                import logger
                _log = logger.setup_logger(log_dir_path='files/logs', log_filename='plugin.log')
                _log.error(f"钩子 on_ui_ready 延迟回调执行失败: {e}", exc_info=True)

    def set_main_window_ready(self, main_window):
        """标记主窗口就绪，并补调所有已注册的 on_ui_ready 回调。
        由 PluginAPI.set_main_window() 调用。"""
        self._main_window_ready = True
        self._main_window = main_window
        # 补调所有排队中的 on_ui_ready
        for cb in self._hooks.get('on_ui_ready', []):
            try:
                cb(main_window)
            except Exception as e:
                import logger
                _log = logger.setup_logger(log_dir_path='files/logs', log_filename='plugin.log')
                _log.error(f"钩子 on_ui_ready 排队回调执行失败: {e}", exc_info=True)

    def unregister(self, hook_name: str, callback: Callable):
        """插件取消注册钩子回调"""
        if hook_name in self._hooks and callback in self._hooks[hook_name]:
            self._hooks[hook_name].remove(callback)

    def trigger(self, hook_name: str, *args, **kwargs):
        """主程序触发钩子，通知所有已注册的回调"""
        callbacks = self._hooks.get(hook_name, [])
        results = []
        for cb in callbacks:
            try:
                results.append(cb(*args, **kwargs))
            except Exception as e:
                import logger
                _log = logger.setup_logger(log_dir_path='files/logs', log_filename='plugin.log')
                _log.error(f"钩子 {hook_name} 回调执行失败: {e}", exc_info=True)
        return results

    # ---- 函数暴露 ----

    def expose(self, name: str, func: Callable):
        """主程序暴露一个函数供插件调用"""
        self._exposed_functions[name] = func

    def call(self, name: str, *args, **kwargs):
        """插件调用主程序暴露的函数"""
        if name not in self._exposed_functions:
            raise RuntimeError(f"函数未暴露: {name}")
        return self._exposed_functions[name](*args, **kwargs)

    def has_function(self, name: str) -> bool:
        return name in self._exposed_functions

    def call_or_none(self, name: str, *args, **kwargs):
        """调用暴露函数，未注册时返回 None 而不抛异常"""
        if name in self._exposed_functions:
            return self._exposed_functions[name](*args, **kwargs)
        return None


# ==================== 数据API ====================

class DataAPI:
    """数据访问API - 提供对所有资源数据的读写访问"""

    def __init__(self):
        self._share_data = None
        self._initialized = False

    def initialize(self, share_data_instance):
        self._share_data = share_data_instance
        self._initialized = True

    def _check(self):
        if not self._initialized:
            raise RuntimeError("DataAPI未初始化")

    @property
    def share_data(self):
        """访问底层 RESOURCEREACTOR（高级用途）"""
        self._check()
        return self._share_data

    # ---- 通用数据访问（推荐插件使用 type_id 参数） ----

    def get_index(self, type_id: str) -> Dict[str, Any]:
        self._check(); return self._share_data.get_index(type_id)

    def get_hash_table(self, type_id: str) -> Dict[str, str]:
        self._check(); return self._share_data.get_hash_table(type_id)

    def get_paginated(self, type_id: str, page=1, page_size=5) -> Dict[str, Any]:
        self._check(); return self._share_data.get_paginated(type_id, page, page_size)

    def get_info(self, type_id: str, name: str) -> Optional[Dict[str, Any]]:
        self._check(); return self._share_data.get_info(type_id, name)

    def get_categories(self, type_id: str) -> List[str]:
        self._check(); return self._share_data.get_categories(type_id)

    def get_by_category(self, type_id: str, category: str) -> Dict[str, Any]:
        self._check(); return self._share_data.get_by_category(type_id, category)

    def search(self, type_id: str, keyword: str) -> Dict[str, Dict[str, Any]]:
        self._check(); return self._share_data.search(type_id, keyword)

    def get_intro_path(self, type_id: str, name: str) -> Optional[str]:
        self._check(); return self._share_data.get_intro_path(type_id, name)

    def load_intro_data(self, type_id: str, name: str) -> Optional[Dict[str, Any]]:
        self._check(); return self._share_data.load_intro_data(type_id, name)

    # ---- 写操作 ----

    def save_intro_data(self, type_id: str, name: str, data: dict) -> Tuple[bool, str]:
        """保存资源的简介.json，自动重建索引"""
        self._check()
        import files_operator
        intro_path = self._share_data.get_intro_path(type_id, name)
        if not intro_path:
            return False, f"找不到资源简介路径: {type_id}/{name}"
        success, msg = files_operator.write_json(intro_path, data)
        if success:
            loader = _LOADER_MAP.get(type_id)
            if loader:
                loader.rebuild_index_and_hash_table()
            self._share_data.notify(
                ObservedEvent.INDEX_CHANGED,
                {'type_id': type_id}
            )
        return success, msg

    def delete_resource(self, type_id: str, name: str) -> Tuple[bool, str]:
        """删除资源（目录+索引），不可逆"""
        self._check()
        ops = TYPE_OPS.get(type_id)
        if not ops:
            return False, f"不支持的类型: {type_id}"
        return ops.delete_resource(name)

    def get_metadata(self, type_id: str = None) -> dict:
        """获取资源类型元数据。不传 type_id 返回全部类型的元数据字典。"""
        if type_id:
            return METADATA.get(type_id, {})
        return dict(METADATA)

    def get_my_category(self, type_id: str) -> str:
        """获取资源类型对应的"我的XX"分类名"""
        return ID_TO_MY_CATEGORY.get(type_id, '')

    def get_all_type_ids(self) -> List[str]:
        """获取所有资源类型ID列表"""
        return list(RESOURCE_TYPE_IDS)

    def get_now_playing_game(self) -> str:
        self._check(); return self._share_data.get_now_playing_game()

    def get_game_intro_path(self, name: str) -> Optional[str]:
        return self.get_intro_path('game', name)

    def get_root_path(self) -> str:
        self._check(); return self._share_data.get_root_path()

    def get_font_size(self) -> int:
        self._check(); return self._share_data.get_font_size()

    # ---- 选中资源管理 ----

    def get_selected_resources(self) -> Dict[str, list]:
        self._check(); return self._share_data.get_selected_resources()

    def get_selected_by_type(self, resource_type: str) -> list:
        self._check(); return self._share_data.get_selected_by_type(resource_type)

    def select_resource(self, resource_type: str, resource_name: str) -> bool:
        self._check(); return self._share_data.select_resource(resource_type, resource_name)

    def deselect_resource(self, resource_type: str, resource_name: str) -> bool:
        self._check(); return self._share_data.deselect_resource(resource_type, resource_name)

    def toggle_resource_selection(self, resource_type: str, resource_name: str) -> bool:
        self._check(); return self._share_data.toggle_resource_selection(resource_type, resource_name)

    def deselect_all(self) -> bool:
        self._check(); return self._share_data.deselect_all()

    def is_resource_selected(self, resource_type: str, resource_name: str) -> bool:
        self._check(); return self._share_data.is_resource_selected(resource_type, resource_name)

    def get_total_selected_count(self) -> int:
        self._check(); return self._share_data.get_total_selected_count()

    def has_any_selected(self) -> bool:
        self._check(); return self._share_data.has_any_selected()

    # ---- 待添加资源管理 ----

    def add_pending_import(self, resource_type: str, name: str, source_path: str) -> bool:
        self._check(); return self._share_data.add_pending_import(resource_type, name, source_path)

    def cancel_pending_import(self, resource_type: str, name: str) -> bool:
        self._check(); return self._share_data.cancel_pending_import(resource_type, name)

    def clear_pending_imports(self, resource_type: Optional[str] = None) -> int:
        self._check(); return self._share_data.clear_pending_imports(resource_type)

    def get_pending_imports(self, resource_type: Optional[str] = None) -> Dict[str, list]:
        self._check(); return self._share_data.get_pending_imports(resource_type)

    def get_pending_count(self) -> int:
        self._check(); return self._share_data.get_pending_count()

    def has_pending_imports(self) -> bool:
        self._check(); return self._share_data.has_pending_imports()

    def export_selected_resources(self, export_dir: str, export_name: str = "selected_export"):
        self._check(); return self._share_data.export_selected_resources(export_dir, export_name)


# ==================== 配置API ====================

class ConfigAPI:
    """配置访问API"""

    def __init__(self):
        self._config_manager = None
        self._app_settings = None

    def initialize(self, config_manager=None, app_settings=None):
        self._config_manager = config_manager
        self._app_settings = app_settings

    def get(self, config_path: str, key: str, default: Any = None) -> Any:
        if self._config_manager:
            return self._config_manager.get_config_value(config_path, key, default)
        return default

    def load(self, config_path: str, required_keys: Optional[list] = None,
             defaults: Optional[dict] = None) -> Dict[str, Any]:
        if self._config_manager:
            return self._config_manager.load_config(config_path, required_keys, defaults)
        return {}

    @property
    def app_settings(self):
        """直接访问 AppSettings 单例"""
        return self._app_settings


# ==================== 日志API ====================

class LoggerAPI:
    """日志API"""

    def __init__(self):
        self._logger = None

    def initialize(self, logger_module):
        self._logger = logger_module

    def setup_logger(self, log_dir_path: str = "files/logs", log_filename: str = "plugin.log"):
        if not self._logger:
            raise RuntimeError("LoggerAPI未初始化")
        return self._logger.setup_logger(log_dir_path, log_filename)


# ==================== 事件订阅API ====================

class _PluginObserver:
    """内部观察者适配器：将 RESOURCEREACTOR 通知桥接到插件回调"""

    def __init__(self, callback: Callable):
        self._callback = callback

    def refresh(self, event, payload=None):
        self._callback(event.value if hasattr(event, 'value') else str(event), payload)


class EventAPI:
    """事件订阅API — 插件可订阅数据变更事件（基于 ObserverToken 组合模式）"""

    def __init__(self):
        self._share_data = None
        self._tokens: Dict[str, 'ObserverToken'] = {}
        self._counter = 0

    def initialize(self, share_data):
        self._share_data = share_data

    def _check(self):
        if self._share_data is None:
            raise RuntimeError("EventAPI未初始化")

    def subscribe(self, event_name: str, callback: Callable[[str, Optional[dict]], None]) -> str:
        """
        订阅数据变更事件。返回订阅ID，可用于取消订阅。

        event_name 可选值:
            'index_changed'        — 资源索引变更
            'paths_changed'        — 路径变更
            'font_changed'         — 字体变更
            'home_page_changed'    — 主页变更
            'selection_changed'    — 选中资源变更
            'pending_imports_changed' — 待导入资源变更

        callback 签名: def on_event(event_name: str, payload: dict | None)
        """
        self._check()

        observer = _PluginObserver(callback)
        event_map = {
            'index_changed': ObservedEvent.INDEX_CHANGED,
            'paths_changed': ObservedEvent.PATHS_CHANGED,
            'font_changed': ObservedEvent.FONT_CHANGED,
            'home_page_changed': ObservedEvent.HOME_PAGE_CHANGED,
            'selection_changed': ObservedEvent.SELECTION_CHANGED,
            'pending_imports_changed': ObservedEvent.PENDING_IMPORTS_CHANGED,
        }
        evt = event_map.get(event_name)
        if evt is None:
            raise ValueError(f"未知事件: {event_name}。可选: {list(event_map.keys())}")

        token = self._share_data.attach(observer, [evt])
        sub_id = f"plugin_evt_{self._counter}"
        self._counter += 1
        self._tokens[sub_id] = token
        return sub_id

    def unsubscribe(self, subscription_id: str):
        """取消事件订阅"""
        token = self._tokens.pop(subscription_id, None)
        if token:
            token.detach()

    def unsubscribe_all(self):
        """取消所有订阅"""
        for token in list(self._tokens.values()):
            token.detach()
        self._tokens.clear()


# ==================== UI API ====================

class UIAPI:
    """UI注入API — 供插件操作主程序界面，支持部分或完全接管UI"""

    def __init__(self):
        self._main_window = None
        self._central_widget = None
        self._builtin_visible = True
        self._main_views: list = []

    def initialize(self, main_window):
        self._main_window = main_window

    @property
    def main_window(self):
        """获取主窗口实例（SFSMainWindow）"""
        if self._main_window is None:
            raise RuntimeError("UI API未初始化，主窗口尚未创建")
        return self._main_window

    def find_widget(self, name: str, widget_type=None):
        """在主窗口中按objectName查找控件"""
        if widget_type is not None:
            return self.main_window.findChild(widget_type, name)
        return self.main_window.findChild(type(None), name)

    def inject_to_layout(self, layout, widget, stretch: int = 0):
        """向布局中注入控件"""
        if hasattr(layout, 'addWidget'):
            layout.addWidget(widget, stretch)
        elif hasattr(layout, 'addLayout'):
            layout.addLayout(widget, stretch)

    def auto_fit_scroll_area(self, scroll):
        """
        自动根据内容布局的高度调整 QScrollArea 大小，不超过其 maxHeight。
        适用于内容为 QLabel 等文本控件的滚动区域。

        :param scroll: QScrollArea 实例或其 objectName（字符串）
        """
        from resource_loader.ui_utils import auto_fit_scroll_area as _auto_fit
        if isinstance(scroll, str):
            scroll = self.find_widget(scroll)
        _auto_fit(scroll)

    def create_window(self, widget, title: str = "",
                      use_global_theme: bool = True,
                      modal: bool = False):
        """
        为插件创建一个独立的QDialog窗口。
        返回dialog实例，插件可进一步配置后调用 show()/exec()。
        """
        from PySide6.QtWidgets import QDialog, QVBoxLayout
        from UI.window_manager import WindowManager

        dialog = QDialog(self.main_window)
        dialog.setWindowTitle(title)

        layout = QVBoxLayout(dialog)
        layout.setContentsMargins(0, 0, 0, 0)
        layout.addWidget(widget)

        if use_global_theme:
            WindowManager.get_instance().configure(dialog, {
                'center': True, 'no_maximize': True, 'no_minimize': False,
                'borderless': False, 'rounded_corner': 0,
            })

        return dialog

    # ---- UI接管 ----

    def register_main_view(self, ui_plugin) -> bool:
        """
        注册一个 UIPluginBase 插件作为主视图。
        在主窗口 on_ui_ready 后，主程序会调用 get_widget() 并替换主内容区。

        :param ui_plugin: UIPluginBase 实例
        :return: 是否注册成功
        """
        from plugin_base import UIPluginBase
        if not isinstance(ui_plugin, UIPluginBase):
            raise TypeError("register_main_view 需要一个 UIPluginBase 实例")
        if ui_plugin not in self._main_views:
            self._main_views.append(ui_plugin)
        return True

    def unregister_main_view(self, ui_plugin) -> bool:
        """取消注册主视图插件"""
        if ui_plugin in self._main_views:
            self._main_views.remove(ui_plugin)
            return True
        return False

    def get_main_views(self) -> list:
        """获取所有已注册的主视图插件列表"""
        return list(self._main_views)

    def hide_builtin_ui(self):
        """隐藏内置UI（资源浏览器、侧边栏、主页等）"""
        if self._main_window is None:
            return
        if hasattr(self._main_window, 'resource_browser'):
            w = self._main_window.resource_browser
            if hasattr(w, 'hide'):
                w.hide()
        # 隐藏主窗口的中央部件
        if hasattr(self._main_window, 'centralWidget'):
            cw = self._main_window.centralWidget()
            if cw is not None:
                cw.hide()
        self._builtin_visible = False

    def show_builtin_ui(self):
        """恢复显示内置UI"""
        if self._main_window is None:
            return
        if hasattr(self._main_window, 'resource_browser'):
            w = self._main_window.resource_browser
            if hasattr(w, 'show'):
                w.show()
        if hasattr(self._main_window, 'centralWidget'):
            cw = self._main_window.centralWidget()
            if cw is not None:
                cw.show()
        self._builtin_visible = True

    def is_builtin_visible(self) -> bool:
        """内置UI是否可见"""
        return self._builtin_visible

    def get_resource_browser(self):
        """获取资源浏览器实例"""
        if self._main_window and hasattr(self._main_window, 'resource_browser'):
            return self._main_window.resource_browser
        return None

    def get_home_game_info(self) -> dict:
        """获取主页当前游玩的游戏/整合包信息"""
        if self._main_window and hasattr(self._main_window, '_get_home_game_info_dict'):
            return self._main_window._get_home_game_info_dict()
        return {}

    def refresh_ui(self):
        """强制刷新整个UI"""
        if self._main_window and hasattr(self._main_window, 'resource_browser'):
            browser = self._main_window.resource_browser
            if hasattr(browser, '_on_refresh_clicked'):
                browser._on_refresh_clicked()

    # ---- 上下文菜单 ----

    def register_context_menu(self, identity_or_pattern: str, items: list):
        """
        注册上下文菜单项。支持精确身份标识和通配符模式（*匹配任意单段）。

        items: [(label, callback, enabled), ...]
          - callback(widget, identity) — widget为被右击的控件, identity为身份标识
          - label为'---'时创建分隔线
          - enabled控制该项是否可选

        身份标识格式: domain:res_type:identifier
        示例:
            api.ui.register_context_menu("resource:mod:*", [
                ("导出", lambda w, i: export_mod(i), True),
                ("---", None, True),
                ("删除", lambda w, i: delete_mod(i), True),
            ])
        """
        from context_menu_manager import ContextMenuRegistry
        registry = ContextMenuRegistry.get_instance()
        if '*' in identity_or_pattern:
            registry.register_pattern(identity_or_pattern, items)
        else:
            registry.register(identity_or_pattern, items)

    def bind_context_menu(self, widget, identity: str):
        """为控件绑定上下文菜单（设置策略、连接信号、登记身份标识）"""
        from context_menu_manager import bind
        bind(widget, identity)

    def unbind_context_menu(self, widget):
        """解除控件的上下文菜单绑定"""
        from context_menu_manager import unbind
        unbind(widget)

    def get_context_menu_identity(self, widget) -> str:
        """读取控件的上下文菜单身份标识"""
        from context_menu_manager import get_identity
        return get_identity(widget)


# ==================== 资源操作API ====================

class ResourceOpsAPI:
    """资源操作API — 安装、链接、导入、导出、版本切换"""

    def __init__(self):
        self._share_data = None
        self._initialized = False

    def initialize(self, share_data):
        self._share_data = share_data
        self._initialized = True

    def _check(self):
        if not self._initialized:
            raise RuntimeError("ResourceOpsAPI未初始化")

    def install_to_game(self, game_intro_path: str, resource_intro_path: str,
                        force: bool = False) -> Tuple[bool, str]:
        """将资源安装到游戏目录（整合包用，复制文件）"""
        self._check()
        res_type = self._detect_type(resource_intro_path)
        ops = TYPE_OPS.get(res_type)
        if not ops:
            return False, f"不支持的类型: {res_type}"
        return ops.install_to_game(game_intro_path, resource_intro_path, force)

    def link_to_game(self, game_intro_path: str, resource_intro_path: str) -> Tuple[bool, str]:
        """将资源链接到游戏目录（真游戏用，junction链接）"""
        self._check()
        res_type = self._detect_type(resource_intro_path)
        ops = TYPE_OPS.get(res_type)
        if not ops:
            return False, f"不支持的类型: {res_type}"
        return ops.link_to_game(game_intro_path, resource_intro_path)

    def switch_version(self, game_intro_path: str, resource_intro_path: str,
                       new_version: str) -> Tuple[bool, str]:
        """切换已链接资源的版本"""
        self._check()
        res_type = self._detect_type(resource_intro_path)
        ops = TYPE_OPS.get(res_type)
        if not ops:
            return False, f"不支持的类型: {res_type}"
        return ops.switch_resource_version(game_intro_path, resource_intro_path, new_version)

    def find_compatible_version(self, resource_intro: dict, game_version: str) -> Optional[str]:
        """在资源简介的版本列表中查找支持指定游戏版本的最新版本号"""
        self._check()
        # 从资源数据推导 type_id
        for tid, meta in METADATA.items():
            vf = meta.get('version_field', '')
            if vf and vf in resource_intro:
                ops = TYPE_OPS.get(tid)
                if ops:
                    return ops._find_compatible_version(resource_intro, game_version)
        return None

    def import_from_archive(self, archive_path: str, target_category: str = None) -> Tuple[bool, str]:
        """从压缩包导入资源到仓库"""
        self._check()
        from resource_operations.resource_importer import ResourceImportScanner
        scanner = ResourceImportScanner(self._share_data.get_root_path())
        scanner.set_share_data(self._share_data)
        return scanner.import_from_archive(archive_path, target_category)

    def export_as_archive(self, res_type: str, res_name: str, output_path: str) -> Tuple[bool, str]:
        """导出资源为压缩包"""
        self._check()
        ops = TYPE_OPS.get(res_type)
        if not ops:
            return False, f"不支持的类型: {res_type}"
        intro_path = self._share_data.get_intro_path(res_type, res_name)
        if not intro_path:
            return False, f"找不到资源: {res_type}/{res_name}"
        return ops.export_as_archive(intro_path, output_path)

    def _detect_type(self, intro_path: str) -> str:
        """从简介路径反推资源类型"""
        import files_operator
        success, data = files_operator.read_json(intro_path)
        if not success:
            return ''
        res_type = data.get('类型', '')
        if res_type in METADATA:
            return res_type
        # 回退：遍历 METADATA 找匹配的 version_field
        for tid, meta in METADATA.items():
            if meta.get('version_field', '') in data:
                return tid
        return res_type

    def get_game_version(self, game_intro: dict) -> str:
        """从游戏/整合包简介中提取游戏版本号"""
        return ResourceOperations._get_game_version(game_intro)

    def filter_intro_to_version(self, intro: dict, version: str, version_field: str) -> dict:
        """过滤简介.json，只保留指定版本条目"""
        return filter_intro_to_version(intro, version, version_field)


# ==================== 系统API ====================

class SystemAPI:
    """系统级API — 用户配置、游戏管理、文件I/O、插件间通信"""

    def __init__(self):
        self._user_profile = None
        self._game_manager = None
        self._plugin_manager = None

    def initialize(self, user_profile=None, game_manager=None, plugin_manager=None):
        self._user_profile = user_profile
        self._game_manager = game_manager
        self._plugin_manager = plugin_manager

    # ---- 用户配置 ----

    @property
    def user_profile(self):
        """UserProfile 单例 — 用户身份和编辑权限"""
        if self._user_profile is None:
            from user_profile import UserProfile
            self._user_profile = UserProfile()
        return self._user_profile

    # ---- 游戏管理 ----

    @property
    def game_manager(self):
        """GameManager 单例 — 游戏的启动/停止/监控"""
        if self._game_manager is None:
            from game_manager import GameManager
            self._game_manager = GameManager.get_instance()
        return self._game_manager

    # ---- 文件I/O ----

    def read_json(self, path: str) -> Tuple[bool, dict]:
        """读取JSON文件，返回 (成功, 数据)"""
        import files_operator
        return files_operator.read_json(path)

    def write_json(self, path: str, data: dict) -> Tuple[bool, str]:
        """写入JSON文件，返回 (成功, 消息)"""
        import files_operator
        return files_operator.write_json(path, data)

    def read_text(self, path: str) -> Tuple[bool, str]:
        """读取文本文件"""
        import files_operator
        return files_operator.read_text(path)

    def write_text(self, path: str, content: str) -> Tuple[bool, str]:
        """写入文本文件"""
        import files_operator
        return files_operator.write_text(path, content)

    def copy_dir(self, src: str, dst: str) -> Tuple[bool, str]:
        """复制目录"""
        import files_operator
        return files_operator.copy_dir(src, dst)

    def copy_file(self, src: str, dst: str) -> Tuple[bool, str]:
        """复制文件"""
        import files_operator
        return files_operator.copy_file(src, dst)

    def delete_dir(self, path: str) -> Tuple[bool, str]:
        """删除目录"""
        import files_operator
        return files_operator.delete_dir(path)

    def move_file(self, src: str, dst: str, overwrite: bool = False) -> Tuple[bool, str]:
        """移动文件/目录"""
        import files_operator
        return files_operator.move_file(src, dst, overwrite)

    # ---- 插件间通信 ----

    def get_plugin(self, name: str) -> Optional[dict]:
        """获取指定插件的信息，返回 {name, version, author, description, dir, enabled}"""
        if self._plugin_manager is None:
            return None
        info = self._plugin_manager.get_plugin(name)
        return info.to_dict() if info else None

    def list_plugins(self) -> List[dict]:
        """列出所有已加载的插件"""
        if self._plugin_manager is None:
            return []
        return self._plugin_manager.list_plugins()

    def call_plugin_function(self, function_name: str, *args, **kwargs):
        """调用其他插件暴露的函数"""
        from plugin_api import PluginAPI
        return PluginAPI.get_instance().call_function_or_none(function_name, *args, **kwargs)

    # ---- 主窗口 ----

    def get_main_window(self):
        """获取主窗口实例"""
        from plugin_api import PluginAPI
        api = PluginAPI.get_instance()
        return api._main_window


# ==================== 插件API单例 ====================

class PluginAPI:
    """
    插件开发统一API入口（单例）

    子模块:
        - api.data      数据访问（读写资源数据、元数据）
        - api.config    配置访问
        - api.logger    日志工具
        - api.events    事件订阅（监听数据变更）
        - api.ui        UI操作（注入、窗口创建、主窗口访问、UI接管）
        - api.ops       资源操作（安装、链接、导入、导出、版本切换）
        - api.system    系统接口（用户配置、游戏管理、文件I/O、插件通信）
        - api.hooks     钩子系统（注册/触发/暴露函数）

    使用示例:
        from plugin_api import PluginAPI
        api = PluginAPI.get_instance()

        # 注册生命周期钩子
        api.register_hook('on_ui_ready', lambda win: print("UI就绪"))

        # 访问数据
        games = api.data.get_games_paginated(page=1, page_size=10)

        # 资源操作
        api.ops.install_to_game(game_path, resource_path)

        # 订阅事件
        api.events.subscribe('index_changed', lambda evt, payload: print("索引已更新"))

        # 文件操作
        ok, data = api.system.read_json('path/to/file.json')

        # 注入UI
        btn = QPushButton("插件按钮")
        api.ui.inject_to_layout(some_layout, btn)
    """
    _instance = None

    @classmethod
    def get_instance(cls) -> 'PluginAPI':
        if cls._instance is None:
            cls._instance = cls()
        return cls._instance

    def __init__(self):
        if PluginAPI._instance is not None:
            raise RuntimeError("PluginAPI是单例，请使用 get_instance() 获取实例")

        self.data = DataAPI()
        self.config = ConfigAPI()
        self.logger = LoggerAPI()
        self.events = EventAPI()
        self.ui = UIAPI()
        self.ops = ResourceOpsAPI()
        self.system = SystemAPI()
        self._hooks = HookRegistry()

        self._main_window = None
        self._app_settings = None
        self._share_data = None
        self._type_manager = None
        self._current_plugin_dir = threading.local()
        self._initialized = False

    # ---- 主程序初始化 ----

    def initialize(self, share_data, config_manager, logger_module,
                   app_settings=None, type_manager=None):
        """由 main.py 在启动时调用"""
        if self._initialized:
            return

        self._share_data = share_data
        self._app_settings = app_settings
        self._type_manager = type_manager

        self.data.initialize(share_data)
        self.config.initialize(config_manager, app_settings)
        self.logger.initialize(logger_module)
        self.events.initialize(share_data)
        self.ops.initialize(share_data)

        self._initialized = True

    def set_main_window(self, main_window):
        """由 SFSMainWindow.__init__ 调用，注册主窗口"""
        self._main_window = main_window
        self.ui.initialize(main_window)
        self._hooks.set_main_window_ready(main_window)

    def set_game_manager(self, game_manager):
        """由 SFSMainWindow.__init__ 调用，注册游戏管理器"""
        self.system._game_manager = game_manager

    def set_plugin_manager(self, plugin_manager):
        """由 main.py 调用，注册插件管理器（用于插件间通信）"""
        self.system._plugin_manager = plugin_manager

    # ---- 钩子代理 ----

    def register_hook(self, hook_name: str, callback: Callable):
        """注册生命周期钩子回调

        可用钩子:
            on_before_ui_build(main_window)       — UI构建前，插件可返回 True 表示接管
            on_after_ui_build(main_window)         — UI构建后
            on_ui_ready(main_window)               — 主窗口就绪（UI已显示）
            on_resource_browser_ready(browser)      — 资源浏览器就绪
            on_page_changed(res_type, category)     — 资源浏览器分类页切换
            on_resource_selected(res_type, name)    — 资源被选中
            on_context_menu_show(widget, identity, items) — 右键菜单弹出
            on_font_changed(new_size)               — 字体大小变更
            on_app_exit()                           — 程序退出
        """
        self._hooks.register(hook_name, callback)

    def unregister_hook(self, hook_name: str, callback: Callable):
        """取消注册钩子回调"""
        self._hooks.unregister(hook_name, callback)

    def trigger_hook(self, hook_name: str, *args, **kwargs):
        """触发钩子（由主程序调用）"""
        return self._hooks.trigger(hook_name, *args, **kwargs)

    def expose_function(self, name: str, func: Callable):
        """暴露函数供插件调用"""
        self._hooks.expose(name, func)

    def call_function(self, name: str, *args, **kwargs):
        """调用主程序暴露的函数"""
        return self._hooks.call(name, *args, **kwargs)

    def call_function_or_none(self, name: str, *args, **kwargs):
        """调用暴露函数，未注册时返回 None 而不抛异常"""
        return self._hooks.call_or_none(name, *args, **kwargs)

    def has_function(self, name: str) -> bool:
        """检查是否有插件暴露了指定函数"""
        return self._hooks.has_function(name)

    def enhance_mod_intro(self, intro_data: dict, res_dir: str) -> dict:
        """
        调用插件增强模组简介数据。
        插件可基于 res_dir 中的 DLL 提取信息，补充 intro_data 中缺失的字段。
        返回增强后的 intro_data（插件未注册时原样返回）。
        """
        result = self._hooks.call_or_none('enhance_mod_intro', intro_data, res_dir)
        return result if result is not None else intro_data

    # ---- 便捷访问 ----

    @property
    def plugin_dir(self) -> Optional[str]:
        """当前正在加载的插件目录路径（线程安全）。
        仅在 initialize(api) 调用期间有效，用于插件获取自身资源文件路径。
        示例: icon_path = os.path.join(api.plugin_dir, 'icons', 'logo.png')
        """
        return getattr(self._current_plugin_dir, 'value', None)

    def get_main_window(self):
        """获取主窗口实例"""
        return self._main_window

    def get_app_settings(self):
        """获取 AppSettings 单例"""
        return self._app_settings

    def get_share_data(self):
        """获取 RESOURCEREACTOR 单例"""
        return self._share_data

    def get_type_manager(self):
        """获取 RESOURCE_TYPE_MANAGER"""
        return self._type_manager

    def is_initialized(self) -> bool:
        return self._initialized