feat: BREAKING CHANGES

Co-authored-by: 白咕咕 <baimianxiao@users.noreply.github.com>
Co-authored-by: kenichiLyon <kenichiLyon@users.noreply.github.com>

9 files changed, 530 insertions, 0 deletions

diff --git a/src/hydrorollcore/__init__.py b/src/hydrorollcore/__init__.py
index e69de29b..48f904b0 100644
--- a/src/hydrorollcore/__init__.py
+++ b/src/hydrorollcore/__init__.py
@@ -0,0 +1,7 @@
+name = "HydroRollCore"
+
+from HydroRollCore.core import Core
+from HydroRollCore.rule import Rule, RuleLoadType
+from HydroRollCore.config import ConfigModel
+
+__all__ = ['Core', 'Rule', 'ConfigModel', 'RuleLoadType']
\ No newline at end of file
diff --git a/src/hydrorollcore/cli.py b/src/hydrorollcore/cli.py
new file mode 100644
index 00000000..548f5925
--- /dev/null
+++ b/src/hydrorollcore/cli.py
@@ -0,0 +1,24 @@
+import argparse
+from tkinter import messagebox
+
+class Cli(object):
+    def parse_args():
+        # 创建解析器对象
+        parser = argparse.ArgumentParser(description='HydroRoll 命令行工具')
+
+        # 添加命令行参数
+        parser.add_argument('--gui', action='store_true', help='显示弹窗')
+        parser.add_argument('--path', help='指定路径')
+
+        # 解析命令行参数
+        args = parser.parse_args()
+
+        # 处理命令行参数
+        if args.gui:
+            messagebox.showinfo('提示', '这是一个弹窗！')
+
+        if args.path:
+            print('输入的路径:', args.path)
+
+    if __name__ == '__main__':
+        main()
diff --git a/src/hydrorollcore/config.py b/src/hydrorollcore/config.py
new file mode 100644
index 00000000..4bee29df
--- /dev/null
+++ b/src/hydrorollcore/config.py
@@ -0,0 +1,76 @@
+"""HydroRollCore 配置。
+
+HydroRollCore 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 来读取配置。
+"""
+from typing import Set, Union
+
+from pydantic import Extra, Field, BaseModel, DirectoryPath
+
+__all__ = [
+    "ConfigModel",
+    "LogConfig",
+    "CoreConfig",
+    "RuleConfig",
+    "MainConfig",
+]
+
+
+class ConfigModel(BaseModel):
+    """HydroRollCore 配置模型。
+
+    Attributes:
+        __config_name__: 配置名称。
+    """
+
+    __config_name__: str
+
+    class Config:
+        extra = Extra.allow
+
+
+class LogConfig(ConfigModel):
+    """HydroRollCore 日志相关设置。
+
+    Attributes:
+        level: 日志级别。
+        verbose_exception: 详细的异常记录，设置为 True 时会在日志中添加异常的 Traceback。
+    """
+
+    level: Union[str, int] = "DEBUG"
+    verbose_exception: bool = False
+
+
+class CoreConfig(ConfigModel):
+    """Core 配置。
+
+    Attributes:
+        rules: 将被加载的规则书列表，将被 `Core` 类的 `load_rules()` 方法加载。
+        rule_dirs: 将被加载的规则书目录列表，将被 `Core` 类的 `load_rules_from_dirs()` 方法加载。
+        log: HydroRollCore 日志相关设置。
+    """
+
+    rules: Set[str] = Field(default_factory=set)
+    rule_dirs: Set[DirectoryPath] = Field(default_factory=set)
+    log: LogConfig = LogConfig() # type: ignore
+
+
+class RuleConfig(ConfigModel):
+    """规则书配置。"""
+
+
+class DebugConfig(ConfigModel):
+    """是否打印事件配置。"""
+
+
+class MainConfig(ConfigModel):
+    """HydroRollCore 配置。
+
+    Attributes:
+        core: HydroRollCore 的主要配置。
+    """
+
+    core: CoreConfig = CoreConfig() # type: ignore
+    rule: RuleConfig = RuleConfig() # type: ignore
+
+    class Config:
+        extra = Extra.allow
\ No newline at end of file
diff --git a/src/hydrorollcore/core.py b/src/hydrorollcore/core.py
new file mode 100644
index 00000000..9016eda8
--- /dev/null
+++ b/src/hydrorollcore/core.py
@@ -0,0 +1,76 @@
+"""HydroRollCore 核心程序"""
+
+import asyncio
+from collections import defaultdict
+import sys
+
+from typing import Any, List, Optional, Type, Dict
+
+from HydroRollCore.config import MainConfig
+from HydroRollCore.rule import Rule, RuleLoadType
+
+__all__ = ['Core']
+
+class Core:
+    """HydroRollCore 核心对象，定义了核心的基本方法。
+        读取并储存配置 `Config`，加载规则包 `Rule`，并进行事件分发。
+
+    Attributes:
+        config: 核心配置。
+        should_exit: 核心是否应该进入准备退出状态。
+        rules: 当前已经加载的规则包的列表。
+        rules_priority_dict: 规则包优先级字典。
+        rule_state: 规则包状态。
+        global_state: 全局状态。
+    """
+
+    config: MainConfig
+    should_exit: asyncio.Event
+    rules: List[Rule]
+    rules_priority_dict: Dict[int, List[Type[Rule]]]
+    rule_state: Dict[str, Any]
+    global_state: Dict[Any, Any]
+    
+    def __init__(
+        self,
+        *,
+        config_file: Optional[str] = "config.toml",
+        config_dict: Optional[Dict] = None,
+        hot_reload: bool = False,
+    ):
+        """初始化 iamai ，读取配置文件，创建配置，加载规则包。
+
+        Args:
+            config_file: 配置文件，如不指定则使用默认的 `config.toml`。
+                若指定为 None，则不加载配置文件。
+            config_dict: 配置字典，默认为 None。
+                若指定字典，则会忽略 config_file 配置，不再读取配置文件。
+            hot_reload: 热重载。
+                启用后将自动检查 `rule_dir` 中的规则包文件更新，并在更新时自动重新加载。
+        """
+        self.config = MainConfig()  # type: ignore[assignment]
+        self.plugins_priority_dict = defaultdict(list)
+        self.plugin_state = defaultdict(type(None))  # type: ignore[assignment]
+        self.global_state = {}
+
+        self.adapters = []
+        self._restart_flag = False
+        self._module_path_finder = ModulePathFinder()
+        self._raw_config_dict = {}
+
+        self._config_file = config_file
+        self._config_dict = config_dict
+        self._hot_reload = hot_reload
+
+        self._extend_plugins = []
+        self._extend_plugin_dirs = []
+        self._extend_adapters = []
+        self._bot_run_hooks = []
+        self._bot_exit_hooks = []
+        self._adapter_startup_hooks = []
+        self._adapter_run_hooks = []
+        self._adapter_shutdown_hooks = []
+        self._event_preprocessor_hooks = []
+        self._event_postprocessor_hooks = []
+
+        sys.meta_path.insert(0, self._module_path_finder)
\ No newline at end of file
diff --git a/src/hydrorollcore/exceptions.py b/src/hydrorollcore/exceptions.py
new file mode 100644
index 00000000..ae49fed2
--- /dev/null
+++ b/src/hydrorollcore/exceptions.py
@@ -0,0 +1,32 @@
+"""HydroRollCore 异常。
+
+下列是 HydroRollCore 运行过程中可能会抛出的异常。这些异常大部分不需要用户处理，HydroRollCore 会自动捕获并处理。
+"""
+
+
+class EventException(BaseException):
+    """事件处理过程中由插件抛出的异常，用于控制事件的传播，会被 iamai 自动捕获并处理。"""
+
+
+class SkipException(EventException):
+    """跳过当前插件继续当前事件传播。"""
+
+
+class StopException(EventException):
+    """停止当前事件传播。"""
+
+
+class iamaiException(Exception):
+    """所有 iamai 发生的异常的基类。"""
+
+
+class GetEventTimeout(iamaiException):
+    """当 get 方法超时使被抛出。"""
+
+
+class AdapterException(iamaiException):
+    """由适配器抛出的异常基类，所有适配器抛出的异常都应该继承自此类。"""
+
+
+class LoadModuleError(iamaiException):
+    """加载模块错误，在指定模块中找不到特定类型的类或模块中存在多个符合条件的类时抛出。"""
\ No newline at end of file
diff --git a/src/hydrorollcore/log.py b/src/hydrorollcore/log.py
new file mode 100644
index 00000000..19073fc3
--- /dev/null
+++ b/src/hydrorollcore/log.py
@@ -0,0 +1,30 @@
+"""HydroRollCore 日志。
+
+HydroRollCore 使用 [loguru](https://github.com/Delgan/loguru) 来记录日志信息。
+自定义 logger 请参考 [loguru](https://github.com/Delgan/loguru) 文档。
+"""
+import os
+import sys
+from datetime import datetime
+
+from loguru import logger as _logger
+
+logger = _logger
+
+current_path = os.path.dirname(os.path.abspath("__file__"))
+log_path = os.path.join(
+    current_path, "logs", datetime.now().strftime("%Y-%m-%d") + ".log"
+)
+
+
+def error_or_exception(message: str, exception: Exception, verbose: bool):
+    logger.remove()
+    logger.add(
+        sys.stderr,
+        format="<magenta>{time:YYYY-MM-DD HH:mm:ss.SSS}</magenta> <level>[{level}]</level> > <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+    )
+    logger.add(sink=log_path, level="INFO", rotation="10 MB")  # 每个日志文件最大为 10MB
+    if verbose:
+        logger.exception(message)
+    else:
+        logger.critical(f"{message} {exception!r}")
\ No newline at end of file
diff --git a/src/hydrorollcore/rule.py b/src/hydrorollcore/rule.py
new file mode 100644
index 00000000..54eaf48e
--- /dev/null
+++ b/src/hydrorollcore/rule.py
@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+import os, os.path
+from enum import Enum
+from iamai.config import ConfigModel
+from iamai.utils import is_config_class
+from typing import Generic, NoReturn, Optional, Type, TYPE_CHECKING
+from HydroRoll.typing import T_Event, T_Config
+
+if TYPE_CHECKING:
+    from iamai.bot import Bot
+
+class RuleLoadType(Enum):
+    """插件加载类型。"""
+
+    DIR = "dir"
+    NAME = "name"
+    FILE = "file"
+    CLASS = "class"
+    
+
+class Rule(ABC, Generic[T_Event, T_Config]):
+    """所有 iamai 插件的基类。
+
+    Attributes:
+        event: 当前正在被此插件处理的事件。
+        priority: 插件的优先级，数字越小表示优先级越高，默认为 0。
+        block: 插件执行结束后是否阻止事件的传播。True 表示阻止。
+        __rule_load_type__: 插件加载类型，由 iamai 自动设置，反映了此插件是如何被加载的。
+        __rule_file_path__: 当插件加载类型为 `RuleLoadType.CLASS` 时为 `None`，
+            否则为定义插件在的 Python 模块的位置。
+    """
+
+    event: T_Event
+    priority: int = 0
+    Config: Type[ConfigModel]
+
+    __rule_load_type__: RuleLoadType
+    __rule_file_path__: Optional[str]
+
+    def __init__(self, event: T_Event):
+        self.event = event
+
+        if not hasattr(self, "priority"):
+            self.priority = 0
+
+        self.get = self.bot.get
+
+        self.__post_init__()
+
+    def __post_init__(self):
+        """用于初始化后处理，被 `__init__()` 方法调用。"""
+        pass
+
+    @property
+    def name(self) -> str:
+        """规则类名称。"""
+        return self.__class__.__name__
+
+    @property
+    def bot(self) -> "Bot":
+        """机器人对象。"""
+        return self.event.adapter.bot
+    
+    @property
+    def config(self) -> Optional[T_Config]:
+        """规则包配置。"""
+        config_class: ConfigModel = getattr(self, "Rule", None)
+        if is_config_class(config_class):
+            return getattr(self.config.rule, config_class.__config_name__, None)
+        return None
diff --git a/src/hydrorollcore/typing.py b/src/hydrorollcore/typing.py
new file mode 100644
index 00000000..0b4a78ba
--- /dev/null
+++ b/src/hydrorollcore/typing.py
@@ -0,0 +1,23 @@
+"""HydroRollCore 类型提示支持。
+
+此模块定义了部分 HydroRollCore 使用的类型。
+"""
+
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from HydroRollCore.core import Core  # noqa
+    from HydroRollCore.rule import Rule  # noqa
+    from HydroRollCore.config import ConfigModel  # noqa
+
+__all__ = [
+    "T_State",
+    "T_Core",
+    "T_Rule",
+    "T_Config"
+]
+
+T_State = TypeVar("T_State")
+T_Core = TypeVar("T_Core", bound="Core")
+T_Rule = TypeVar("T_Rule", bound="Rule")
+T_Config = TypeVar("T_Config", bound="ConfigModel")
\ No newline at end of file
diff --git a/src/hydrorollcore/utils.py b/src/hydrorollcore/utils.py
new file mode 100644
index 00000000..c69fdd48
--- /dev/null
+++ b/src/hydrorollcore/utils.py
@@ -0,0 +1,192 @@
+import os
+import json
+import asyncio
+import inspect
+import os.path
+import pkgutil
+import importlib
+import traceback
+import dataclasses
+from abc import ABC
+from types import ModuleType
+from functools import partial
+from typing_extensions import ParamSpec
+from importlib.abc import MetaPathFinder
+from importlib.machinery import PathFinder
+from typing import Any, List, Type, Tuple, TypeVar, Callable, Iterable, Coroutine
+
+from HydroRollCore.config import ConfigModel
+
+__all__ = [
+    "ModulePathFinder",
+    "is_config_class",
+    "get_classes_from_module",
+    "get_classes_from_module_name",
+    "get_classes_from_dir",
+    "DataclassEncoder",
+    "samefile",
+    "sync_func_wrapper",
+]
+
+_T = TypeVar("_T")
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+class ModulePathFinder(MetaPathFinder):
+    """用于查找 HydroRollCore 组件的元路径查找器。"""
+
+    path: List[str] = []
+
+    def find_spec(self, fullname, path=None, target=None):
+        if path is None:
+            path = []
+        return PathFinder.find_spec(fullname, self.path + list(path), target)
+
+
+def is_config_class(config_class: Any) -> bool:
+    """判断一个对象是否是配置类。
+
+    Args:
+        config_class: 待判断的对象。
+
+    Returns:
+        返回是否是配置类。
+    """
+    return (
+        inspect.isclass(config_class)
+        and issubclass(config_class, ConfigModel)
+        and isinstance(getattr(config_class, "__config_name__", None), str)
+        and ABC not in config_class.__bases__
+        and not inspect.isabstract(config_class)
+    )
+
+
+def get_classes_from_module(
+    module: ModuleType, super_class: Type[_T]
+) -> List[Type[_T]]:
+    """从模块中查找指定类型的类。
+
+    Args:
+        module: Python 模块。
+        super_class: 要查找的类的超类。
+
+    Returns:
+        返回符合条件的类的列表。
+    """
+    classes: List[Type[_T]] = []
+    for _, module_attr in inspect.getmembers(module, inspect.isclass):
+        module_attr: type
+        if (
+            (inspect.getmodule(module_attr) or module) is module
+            and issubclass(module_attr, super_class)
+            and module_attr != super_class
+            and ABC not in module_attr.__bases__
+            and not inspect.isabstract(module_attr)
+        ):
+            classes.append(module_attr)
+    return classes
+
+
+def get_classes_from_module_name(
+    name: str, super_class: Type[_T]
+) -> List[Tuple[Type[_T], ModuleType]]:
+    """从指定名称的模块中查找指定类型的类。
+
+    Args:
+        name: 模块名称，格式和 Python `import` 语句相同。
+        super_class: 要查找的类的超类。
+
+    Returns:
+        返回由符合条件的类和模块组成的元组的列表。
+
+    Raises:
+        ImportError: 当导入模块过程中出现错误。
+    """
+    try:
+        importlib.invalidate_caches()
+        module = importlib.import_module(name)
+        importlib.reload(module)
+        return list(
+            map(lambda x: (x, module), get_classes_from_module(module, super_class))
+        )
+    except BaseException as e:
+        # 不捕获 KeyboardInterrupt
+        # 捕获 KeyboardInterrupt 会阻止用户关闭 Python 当正在导入的模块陷入死循环时
+        if isinstance(e, KeyboardInterrupt):
+            raise e
+        raise ImportError(e, traceback.format_exc()) from e
+
+
+def get_classes_from_dir(
+    dirs: Iterable[str], super_class: Type[_T]
+) -> List[Tuple[Type[_T], ModuleType]]:
+    """从指定路径列表中的所有模块中查找指定类型的类，以 `_` 开头的插件不会被导入。路径可以是相对路径或绝对路径。
+
+    Args:
+        dirs: 储存模块的路径的列表。
+        super_class: 要查找的类的超类。
+
+    Returns:
+        返回由符合条件的类和模块组成的元组的列表。
+    """
+    classes: List[Tuple[Type[_T], ModuleType]] = []
+    for module_info in pkgutil.iter_modules(dirs):
+        if not module_info.name.startswith("_"):
+            try:
+                classes.extend(
+                    get_classes_from_module_name(module_info.name, super_class)
+                )
+            except ImportError:
+                continue
+    return classes
+
+
+class DataclassEncoder(json.JSONEncoder):
+    """用于解析 MessageSegment 的 JSONEncoder 类。"""
+
+    def default(self, o):
+        return o.as_dict() if dataclasses.is_dataclass(o) else super().default(o)
+
+
+def samefile(path1: str, path2: str) -> bool:
+    """一个 `os.path.samefile` 的简单包装。
+
+    Args:
+        path1: 路径1。
+        path2: 路径2。
+
+    Returns:
+        如果两个路径是否指向相同的文件或目录。
+    """
+    try:
+        return path1 == path2 or os.path.samefile(path1, path2)
+    except OSError:
+        return False
+
+
+def sync_func_wrapper(
+    func: Callable[_P, _R], to_thread: bool = False
+) -> Callable[_P, Coroutine[None, None, _R]]:
+    """包装一个同步函数为异步函数
+
+    Args:
+        func: 待包装的同步函数。
+        to_thread: 在独立的线程中运行同步函数。
+
+    Returns:
+        异步函数。
+    """
+    if to_thread:
+
+        async def _wrapper(*args: _P.args, **kwargs: _P.kwargs):
+            loop = asyncio.get_running_loop()
+            func_call = partial(func, *args, **kwargs)
+            return await loop.run_in_executor(None, func_call)
+
+    else:
+
+        async def _wrapper(*args: _P.args, **kwargs: _P.kwargs):
+            return func(*args, **kwargs)
+
+    return _wrapper
\ No newline at end of file