gracybot 1.9.2__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,117 @@
+"""GracyBot 核心模块统一导入文件
+
+此模块提供核心组件的统一导出，简化其他模块的导入路径，提高代码可维护性。
+"""
+
+# 核心管理器
+def _get_plugin_manager():
+    """延迟导入插件管理器，避免循环依赖"""
+    from .plugin_manager import plugin_manager
+    return plugin_manager
+
+def _get_security_manager():
+    """延迟导入安全管理器，避免循环依赖"""
+    from .security_manager import security_manager
+    return security_manager
+
+def _get_config_manager():
+    """延迟导入配置管理器，避免循环依赖"""
+    from .config_manager import config_manager
+    return config_manager
+
+def _get_monitor_manager():
+    """延迟导入监控管理器，避免循环依赖"""
+    from .monitor import monitor_manager
+    return monitor_manager
+
+def _get_logger_manager():
+    """延迟导入日志管理器，避免循环依赖"""
+    from .logger_manager import logger_manager
+    return logger_manager
+
+# 使用属性描述器实现延迟加载
+class LazyLoader:
+    """延迟加载属性描述器"""
+    def __init__(self, loader_func):
+        self.loader_func = loader_func
+        self.__doc__ = loader_func.__doc__
+    
+    def __get__(self, instance, owner):
+        value = self.loader_func()
+        setattr(owner, self.name, value)
+        return value
+    
+    def __set_name__(self, owner, name):
+        self.name = name
+
+class Core:
+    """核心组件容器类，提供统一的核心组件访问入口"""
+    
+    # 延迟加载的核心管理器
+    plugin_manager = LazyLoader(_get_plugin_manager)
+    security_manager = LazyLoader(_get_security_manager)
+    config_manager = LazyLoader(_get_config_manager)
+    monitor_manager = LazyLoader(_get_monitor_manager)
+    logger_manager = LazyLoader(_get_logger_manager)
+
+# 创建核心组件实例
+core = Core()
+
+# 导出核心组件
+def get_plugin_manager():
+    """获取插件管理器实例"""
+    return core.plugin_manager
+
+def get_security_manager():
+    """获取安全管理器实例"""
+    return core.security_manager
+
+def get_config_manager():
+    """获取配置管理器实例"""
+    return core.config_manager
+
+def get_monitor_manager():
+    """获取监控管理器实例"""
+    return core.monitor_manager
+
+def get_logger_manager():
+    """获取日志管理器实例"""
+    return core.logger_manager
+
+# 导出主要工具函数和常量（容错导入，避免缺依赖时崩整个包）
+try:
+    from core.handler import callback_base
+except ImportError:
+    callback_base = None
+
+try:
+    from core.utils import logger, sanitize_log
+except ImportError:
+    logger = None
+    sanitize_log = None
+
+# 版本信息
+from core.config import BOT_VERSION
+__version__ = BOT_VERSION.removeprefix('v')
+__all__ = [
+    # 核心管理器访问函数
+    "get_plugin_manager",
+    "get_security_manager",
+    "get_config_manager",
+    "get_monitor_manager",
+    "get_logger_manager",
+    # 核心组件实例（延迟加载）
+    "core",
+    # 主要函数
+    "callback_base",
+    "sanitize_log",
+    # 日志对象
+    "logger",
+    # 版本信息
+    "__version__"
+]
+
+# 模块加载完成日志（仅子进程打印，避免热重载双重输出）
+import os as _os
+if _os.environ.get("WERKZEUG_RUN_MAIN") == "true":
+    logger.info(f"✅ 核心模块加载完成，版本: v{__version__}")

core/config.py

@@ -0,0 +1,166 @@
+import os
+import time
+from core.config_manager import config_manager, ConfigItem
+
+# ═══════════════ 框架配置版本与默认值 ═══════════════
+
+CONFIG_VERSION = 3
+"""当前框架配置版本号，用于自动更新检测。"""
+
+DEFAULT_CONFIG = {
+    "_config_version": CONFIG_VERSION,
+    "robot_id": "不要填，填根目录的config.json",
+    "callback_port": 3002,
+    "master_id": "填写ID(默认，不用改，直接改根目录的config.json)",
+    "connection_mode": "http",
+    "bot_version": "v1.9.2",
+    "log_encoding": "utf-8",
+    "log_level": "WARNING",
+    "debug_mode": False,
+    "auto_replies": {
+        "你好": "哈喽～ 我是 GracyBot，有什么可以帮你呀？",
+        "在吗": "在呢在呢～ 随时在线为你服务！",
+        "谢谢": "不客气呀～ 能帮到你我也很开心！",
+        "再见": "拜拜～ 下次见啦，祝你生活愉快！",
+        "早上好": "早上好呀～ 新的一天也要元气满满哦！",
+        "晚上好": "晚上好～ 记得早点休息，不要熬夜呀！",
+        "吃了吗": "哈哈，已经吃过啦～ 你也要按时吃饭呀！",
+        "天气怎么样": "抱歉呀，我暂时没法查询天气，记得关注天气预报哦～",
+        "你是谁": "我是 GracyBot，一款基于 Napcat 的 QQ 机器人，很高兴认识你！",
+        "加油": "谢谢鼓励～ 你也超棒的，一起加油呀！"
+    }
+}
+"""完整默认配置字典（包含框架级所有键的默认值）。"""
+
+# ═══════════════ 框架级配置（存储在 config.json）═══════════════
+
+# 启动路由（决定加载哪个适配器，属于框架级决策）
+config_manager.register_config(ConfigItem(
+    key="connection_mode",
+    default="http",
+    description="连接模式: http(http_reverse), ws_forward, ws_reverse",
+    validate_func=lambda x: x in ["http", "http_reverse", "ws_forward", "ws_reverse"]
+))
+
+config_manager.register_config(ConfigItem(
+    key="robot_id", 
+    default="不要填，填根目录的config.json", 
+    description="机器人ID", 
+    required=True
+))
+config_manager.register_config(ConfigItem(
+    key="callback_port", 
+    default=3002, 
+    description="回调服务端口",
+    validate_func=lambda x: isinstance(x, int) and 1024 <= x <= 65535
+))
+config_manager.register_config(ConfigItem(
+    key="master_id", 
+    default="填写ID(默认，不用改，直接改根目录的config.json)", 
+    description="主人ID", 
+    required=True
+))
+config_manager.register_config(ConfigItem(
+    key="bot_version", 
+    default="v1.9.2", 
+    description="机器人版本"
+))
+config_manager.register_config(ConfigItem(
+    key="log_encoding", 
+    default="utf-8", 
+    description="日志编码格式"
+))
+config_manager.register_config(ConfigItem(
+    key="auto_replies", 
+    default={
+        "你好": "哈喽～ 我是 GracyBot，有什么可以帮你呀？",
+        "在吗": "在呢在呢～ 随时在线为你服务！",
+        "谢谢": "不客气呀～ 能帮到你我也很开心！",
+        "再见": "拜拜～ 下次见啦，祝你生活愉快！",
+        "早上好": "早上好呀～ 新的一天也要元气满满哦！",
+        "晚上好": "晚上好～ 记得早点休息，不要熬夜呀！",
+        "吃了吗": "哈哈，已经吃过啦～ 你也要按时吃饭呀！",
+        "天气怎么样": "抱歉呀，我暂时没法查询天气，记得关注天气预报哦～",
+        "你是谁": "我是 GracyBot，一款基于 Napcat 的 QQ 机器人，很高兴认识你！",
+        "加油": "谢谢鼓励～ 你也超棒的，一起加油呀！"
+    },
+    description="自动回复配置"
+))
+config_manager.register_config(ConfigItem(
+    key="debug_mode", 
+    default=False, 
+    description="调试模式"
+))
+config_manager.register_config(ConfigItem(
+    key="log_level", 
+    default="WARNING", 
+    description="日志级别",
+    validate_func=lambda x: x in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+))
+
+# ═══════════════ OneBot 适配器专属配置（存储在 onebot_config.json）═══════════════
+# 这些配置项由 OneBot 适配器使用，从独立配置文件加载，
+# 未来新增适配器各自维护自己的配置文件，不污染框架 config.json
+
+config_manager.register_config(ConfigItem(
+    key="napcat_http_url",
+    default="http://localhost:3000",
+    description="NapCat HTTP API 地址"
+))
+config_manager.register_config(ConfigItem(
+    key="ws_host",
+    default="127.0.0.1",
+    description="WebSocket 地址(正向=OneBot地址, 反向=监听地址)"
+))
+config_manager.register_config(ConfigItem(
+    key="ws_port",
+    default=3001,
+    description="WebSocket 端口",
+    validate_func=lambda x: isinstance(x, int) and 1024 <= x <= 65535
+))
+config_manager.register_config(ConfigItem(
+    key="access_token",
+    default="",
+    description="OneBot access_token（留空=不使用token连接）"
+))
+
+# ═══════════════ 加载配置（仅在首次访问配置值时触发文件读取） ═══════════════
+
+# OneBot 配置路径：优先 GRACYBOT_HOME，否则回退模块路径
+_gracy_home = os.environ.get("GRACYBOT_HOME", "")
+if _gracy_home:
+    _ONEBOT_CONFIG_PATH = os.path.join(_gracy_home, "core", "gracy_adapter", "onebot", "onebot_config.json")
+else:
+    _ONEBOT_CONFIG_PATH = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "gracy_adapter", "onebot", "onebot_config.json"
+    )
+
+# 延迟加载，不阻塞模块导入
+if not config_manager.load():
+    # 配置不存在时静默处理，不抛异常
+    pass
+else:
+    # 加载成功后检查配置文件版本，自动合并更新
+    config_manager._auto_update_config(DEFAULT_CONFIG, CONFIG_VERSION)
+
+config_manager.load_from(_ONEBOT_CONFIG_PATH)
+
+# 为兼容旧代码，提供直接访问方式
+ROBOT_ID = config_manager.get("robot_id")
+CALLBACK_PORT = config_manager.get("callback_port")
+MASTER_ID = config_manager.get("master_id")
+BOT_VERSION = config_manager.get("bot_version")
+LOG_ENCODING = config_manager.get("log_encoding")
+AUTO_REPLIES = config_manager.get("auto_replies")
+DEBUG_MODE = config_manager.get("debug_mode")
+LOG_LEVEL = config_manager.get("log_level")
+
+# 非配置项常量
+ROBOT_START_TIME = time.time()
+
+# 连接模式（框架启动路由，保留为模块常量）
+CONNECTION_MODE = config_manager.get("connection_mode")
+
+# OneBot 适配器配置不再作为模块常量，
+# 使用方通过 config_manager.get("ws_host") 等方式获取

core/config_manager.py

@@ -0,0 +1,300 @@
+import os
+import json
+import logging
+from typing import Dict, Any, Optional, TypeVar, Generic
+
+# 配置文件路径
+_gracy_home = os.environ.get("GRACYBOT_HOME", "")
+if _gracy_home:
+    CONFIG_FILE_PATH = os.path.join(_gracy_home, 'config.json')
+else:
+    CONFIG_FILE_PATH = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'config.json')
+
+
+# 配置类型定义
+T = TypeVar('T')
+
+
+def deep_merge_config(base: dict, override: dict) -> dict:
+    """递归合并两个配置字典
+
+    规则：
+      - override 中已有的键，保留 override 的值（用户设置优先）
+      - base 中存在但 override 中不存在的键，从 base 补入
+      - 如果某个键在两个 dict 中都是 dict 类型，则递归合并
+
+    Args:
+        base: 默认配置字典
+        override: 用户当前配置字典
+
+    Returns:
+        合并后的新字典
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge_config(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+class ConfigItem(Generic[T]):
+    """配置项类，支持类型转换和验证"""
+    def __init__(self, key: str, default: T, description: str = '', required: bool = False, 
+                 env_var: Optional[str] = None, validate_func=None):
+        self.key = key
+        self.default = default
+        self.description = description
+        self.required = required
+        self.env_var = env_var or f"GRACY_{key.upper()}"
+        self.validate_func = validate_func
+        self.value: Optional[T] = None
+    
+    def validate(self, value: Any) -> bool:
+        """验证配置值是否合法"""
+        if self.validate_func:
+            return self.validate_func(value)
+        return True
+
+class ConfigManager:
+    """企业级配置管理器，支持环境变量、配置文件和默认值"""
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+            cls._instance._config_items = {}
+            cls._instance._file_config = {}
+            cls._instance._logger = logging.getLogger("GracyBot-Config")
+        return cls._instance
+    
+    def register_config(self, config_item: ConfigItem) -> None:
+        """注册配置项"""
+        self._config_items[config_item.key] = config_item
+    
+    def load(self) -> bool:
+        """加载配置，优先级：环境变量 > 配置文件 > 默认值"""
+        try:
+            # 加载配置文件
+            if os.path.exists(CONFIG_FILE_PATH):
+                try:
+                    with open(CONFIG_FILE_PATH, 'r', encoding='utf-8') as f:
+                        self._file_config = json.load(f)
+                    self._logger.info(f"✅ 配置文件加载成功: {CONFIG_FILE_PATH}")
+                except json.JSONDecodeError as e:
+                    self._logger.error(f"❌ 配置文件格式错误: {str(e)}")
+                    return False
+            else:
+                self._logger.warning(f"⚠️ 配置文件不存在: {CONFIG_FILE_PATH}，将使用默认值和环境变量")
+            
+            # 处理每个配置项
+            for key, item in self._config_items.items():
+                # 1. 尝试从环境变量获取
+                env_value = os.environ.get(item.env_var)
+                if env_value is not None:
+                    # 根据默认值类型进行转换
+                    if isinstance(item.default, bool):
+                        item.value = env_value.lower() in ('true', '1', 'yes', 'y')
+                    elif isinstance(item.default, int):
+                        try:
+                            item.value = int(env_value)
+                        except ValueError:
+                            self._logger.error(f"❌ 环境变量 {item.env_var} 不是有效的整数")
+                            item.value = item.default
+                    else:
+                        item.value = env_value
+                    self._logger.debug(f"🔧 从环境变量加载配置 {key}: {item.env_var}")
+                # 2. 尝试从配置文件获取
+                elif key in self._file_config:
+                    item.value = self._file_config[key]
+                    self._logger.debug(f"📄 从配置文件加载配置 {key}")
+                # 3. 使用默认值
+                else:
+                    item.value = item.default
+                    self._logger.debug(f"📌 使用默认配置 {key}: {item.default}")
+                
+                # 验证配置
+                if not item.validate(item.value):
+                    self._logger.error(f"❌ 配置 {key} 的值 {item.value} 无效")
+                    if item.required:
+                        return False
+                    # 无效时回退到默认值
+                    item.value = item.default
+                
+                # 检查必填项
+                if item.required and item.value is None:
+                    self._logger.error(f"❌ 缺少必填配置 {key}")
+                    return False
+            
+            self._initialized = True
+            self._logger.info("✅ 所有配置加载完成")
+            return True
+        except Exception as e:
+            self._logger.error(f"❌ 配置加载异常: {str(e)}", exc_info=True)
+            return False
+    
+    def load_from(self, filepath: str) -> bool:
+        """从指定路径加载配置文件，将值合并到已注册的配置项中
+
+        用于适配器独立配置文件（如 onebot_config.json），
+        只更新已注册的 ConfigItem，不会自动注册新项。
+
+        Args:
+            filepath: 配置文件的绝对路径
+
+        Returns:
+            加载成功返回 True
+        """
+        try:
+            if not os.path.exists(filepath):
+                self._logger.warning(f"⚠️ 配置文件不存在: {filepath}，将使用默认值")
+                return False
+
+            with open(filepath, 'r', encoding='utf-8') as f:
+                file_data = json.load(f)
+
+            loaded_keys = []
+            for key, value in file_data.items():
+                item = self._config_items.get(key)
+                if item:
+                    # 环境变量优先级仍高于文件
+                    if item.env_var in os.environ:
+                        continue
+                    item.value = value
+                    loaded_keys.append(key)
+                else:
+                    self._logger.debug(f"⏭️ 忽略未注册的配置项: {key}（来自 {os.path.basename(filepath)}）")
+
+            self._logger.info(f"✅ 适配器配置加载成功: {filepath}（{len(loaded_keys)} 项）")
+            return True
+        except json.JSONDecodeError as e:
+            self._logger.error(f"❌ 配置文件格式错误: {filepath}: {str(e)}")
+            return False
+        except Exception as e:
+            self._logger.error(f"❌ 配置文件加载异常: {filepath}: {str(e)}", exc_info=True)
+            return False
+
+    def save_to_file_at(self, filepath: str, keys: list = None) -> bool:
+        """将指定配置项保存到指定文件路径
+
+        Args:
+            filepath: 目标文件路径
+            keys: 要保存的配置项键列表，None 表示全部
+
+        Returns:
+            保存成功返回 True
+        """
+        try:
+            data = {}
+            target_keys = keys or list(self._config_items.keys())
+            for key in target_keys:
+                item = self._config_items.get(key)
+                if item and item.value is not None:
+                    data[key] = item.value
+
+            with open(filepath, 'w', encoding='utf-8') as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+
+            self._logger.info(f"✅ 配置已保存到: {filepath}")
+            return True
+        except Exception as e:
+            self._logger.error(f"❌ 保存配置文件失败: {filepath}: {str(e)}")
+            return False
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """获取配置值"""
+        if not self._initialized:
+            if not self.load():
+                return default
+        
+        item = self._config_items.get(key)
+        if item:
+            return item.value
+        return default
+    
+    def set(self, key: str, value: Any) -> bool:
+        """动态设置配置值"""
+        item = self._config_items.get(key)
+        if item:
+            if item.validate(value):
+                item.value = value
+                self._logger.info(f"🔄 动态更新配置 {key}: {value}")
+                return True
+            else:
+                self._logger.error(f"❌ 无法设置配置 {key}: 无效值 {value}")
+        return False
+    
+    def missing_in_file(self, *keys) -> list:
+        "检查哪些配置项在 config.json 中缺失（用于首次运行引导）"
+        if not self._file_config:
+            return list(keys)
+        return [k for k in keys if k not in self._file_config]
+
+    def save_to_file(self) -> bool:
+        """保存当前配置到文件（不包含环境变量覆盖的值）"""
+        try:
+            # 只保存非环境变量覆盖的配置
+            config_to_save = self._file_config.copy()
+            for key, item in self._config_items.items():
+                if item.env_var not in os.environ and key not in os.environ:
+                    config_to_save[key] = item.value
+            
+            with open(CONFIG_FILE_PATH, 'w', encoding='utf-8') as f:
+                json.dump(config_to_save, f, ensure_ascii=False, indent=2)
+            
+            self._logger.info(f"✅ 配置已保存到: {CONFIG_FILE_PATH}")
+            return True
+        except Exception as e:
+            self._logger.error(f"❌ 保存配置文件失败: {str(e)}")
+            return False
+    
+    def generate_default_config(self) -> Dict[str, Any]:
+        """生成默认配置字典"""
+        default_config = {}
+        for key, item in self._config_items.items():
+            default_config[key] = {
+                'value': item.default,
+                'description': item.description,
+                'env_var': item.env_var,
+                'required': item.required
+            }
+        return default_config
+
+    def _auto_update_config(self, default_config: dict, config_version: int) -> None:
+        """自动更新配置文件：检查版本号，低版本则合并默认配置并写回
+
+        Args:
+            default_config: 完整默认配置字典（来自 core/config.py 的 DEFAULT_CONFIG）
+            config_version: 当前框架配置版本号（来自 core/config.py 的 CONFIG_VERSION）
+        """
+        # 读取当前配置文件中的版本号
+        current_version = self._file_config.get("_config_version", 0)
+        if current_version >= config_version:
+            return
+
+        self._logger.info(
+            f"🔄 检测到配置版本 {current_version} → {config_version}，正在自动更新..."
+        )
+
+        # 合并：新增键追加、已有键保留用户值、嵌套 dict 递归合并
+        merged = deep_merge_config(default_config, self._file_config)
+        merged["_config_version"] = config_version
+
+        # bot_version 始终从 DEFAULT_CONFIG 同步，标记框架真实版本
+        if "bot_version" in default_config:
+            merged["bot_version"] = default_config["bot_version"]
+
+        # 更新内存中的文件配置
+        self._file_config = merged
+
+        # 写回 config.json
+        try:
+            with open(CONFIG_FILE_PATH, 'w', encoding='utf-8') as f:
+                json.dump(merged, f, ensure_ascii=False, indent=2)
+            self._logger.info(f"✅ 配置文件已自动更新至 v{config_version}")
+        except Exception as e:
+            self._logger.error(f"❌ 自动更新配置文件失败: {str(e)}", exc_info=True)
+
+# 创建全局配置管理器实例
+config_manager = ConfigManager()

core/decorators/__init__.py

@@ -0,0 +1,31 @@
+"""GracyBot 装饰器体系 — 声明式插件开发
+
+装饰器加载顺序（从下往上/从内到外）:
+    @on_command("/cmd")
+    @require_permission("all")
+    @plugin_handler
+    async def handler(ctx): ...
+
+执行顺序（从上往下/从外到内）：
+
+    1. @on_command → 注册到全局命令池
+    2. @require_permission → 权限校验
+    3. @plugin_handler → 参数注入 + 计时 + 异常捕获
+    4. handler() → 业务逻辑
+"""
+
+from .context import PluginContext
+from .registration import on_command, on_regex, on_keyword, gracy_plugin, DECORATOR_COMMAND_REGISTRY
+from .security import require_permission, require_master, rate_limit, cooldown
+from .handler import plugin_handler
+from .session import with_session
+from .async_utils import async_retry, background
+
+__all__ = [
+    "PluginContext",
+    "on_command", "on_regex", "on_keyword", "gracy_plugin", "DECORATOR_COMMAND_REGISTRY",
+    "require_permission", "require_master", "rate_limit", "cooldown",
+    "plugin_handler",
+    "with_session",
+    "async_retry", "background",
+]