ErisPulse 2.5.2.dev4__tar.gz → 2.5.4__tar.gz

{erispulse-2.5.2.dev4 → erispulse-2.5.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.5.2.dev4
-Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
+Version: 2.5.4
+Summary: Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署
 Project-URL: Homepage, https://github.com/ErisPulse/ErisPulse
 Project-URL: Documentation, https://www.erisdev.com#docs
 Project-URL: Repository, https://github.com/ErisPulse/ErisPulse

{erispulse-2.5.2.dev4 → erispulse-2.5.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.5.2-dev.4"
-description = "ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。"
+version = "2.5.4"
+description = "Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
@@ -105,6 +105,9 @@ project.root = "src"
 [tool.hatch.build.targets.wheel]
 packages = ["src/ErisPulse"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"src/ErisPulse/py.typed" = "ErisPulse/py.typed"
+
 [tool.hatch.build.targets.sdist]
 include = [
     "/src/ErisPulse",

{erispulse-2.5.2.dev4 → erispulse-2.5.4}/src/ErisPulse/CLI/commands/create.py

@@ -62,8 +62,21 @@ dependencies = [
 _MODULE_INIT = """from .Core import Main
 """
 
-_MODULE_CORE = """from ErisPulse.Core.Bases import BaseModule
+_MODULE_CORE = """from dataclasses import dataclass, field
+from ErisPulse.Core.Bases import BaseModule
 from ErisPulse.Core.Event import command, message, notice
+from ErisPulse.runtime.config_schema import BaseConfig
+
+
+@dataclass
+class {name}Config(BaseConfig):
+    \"\"\"{name} 模块配置\"\"\"
+    enabled: bool = field(
+        default=True,
+        metadata={{
+            \"description\": \"是否启用模块\",
+        }},
+    )
 
 
 class Main(BaseModule):
@@ -73,16 +86,17 @@ class Main(BaseModule):
     继承自BaseModule基类，实现了标准化的模块生命周期管理和事件处理
     \"\"\"
 
+    ConfigClass = {name}Config
+
     def __init__(self, sdk=None):
         from ErisPulse import sdk as _sdk
         self.sdk = _sdk if sdk is None else sdk
-        self.logger = self.sdk.logger.get_child("{name}")
+        self.logger = self.sdk.logger.get_child(\"{name}\")
         self.storage = self.sdk.storage
         self.adapter = self.sdk.adapter
         self.client = self.sdk.client
 
-        self.logger.info("{name} 初始化完成")
-        self.config = self._load_config()
+        self.logger.info(\"{name} 初始化完成\")
 
     @staticmethod
     def get_load_strategy():
@@ -101,7 +115,7 @@ class Main(BaseModule):
         \"\"\"
         await self._register_commands()
         await self._register_message_handlers()
-        self.logger.info(f"模块已加载: {{event}}")
+        self.logger.info(f\"模块已加载: {{event}}\")
         return True
 
     async def on_unload(self, event: dict) -> bool:
@@ -111,29 +125,18 @@ class Main(BaseModule):
         :param event: 事件内容
         :return: 处理结果
         \"\"\"
-        self.logger.info(f"模块已卸载: {{event}}")
+        self.logger.info(f\"模块已卸载: {{event}}\")
         return True
 
-    def _load_config(self):
-        config = self.sdk.config.getConfig("{name}")
-        if not config:
-            default_config = {{
-                "enabled": True,
-            }}
-            self.sdk.config.setConfig("{name}", default_config)
-            self.logger.warning("未找到模块配置, 已创建默认配置到config.toml")
-            return default_config
-        return config
-
     async def _register_commands(self):
-        @command("hello", help="发送问候消息")
+        @command(\"hello\", help=\"发送问候消息\")
         async def hello_command(event):
-            await event.reply("Hello from {name}!")
+            await event.reply(\"Hello from {name}!\")
 
     async def _register_message_handlers(self):
         @message.on_private_message()
         async def private_message_handler(event):
-            self.logger.info(f"收到私聊消息: {{event.get_text()}}")
+            self.logger.info(f\"收到私聊消息: {{event.get_text()}}\")
 
         @message.on_group_message()
         async def group_message_handler(event):
@@ -141,7 +144,7 @@ class Main(BaseModule):
 
         @notice.on_friend_add()
         async def friend_add_handler(event):
-            self.logger.info(f"新好友添加: {{event.get_user_nickname()}}")
+            self.logger.info(f\"新好友添加: {{event.get_user_nickname()}}\")
 """
 
 _ADAPTER_PYPROJECT = """[project]
@@ -176,20 +179,29 @@ _ADAPTER_CORE = """import asyncio
 import json
 from dataclasses import dataclass, field
 from ErisPulse.Core import BaseAdapter
-from ErisPulse.runtime.config_schema import AdapterConfig
+from ErisPulse.runtime.config_schema import BaseConfig
 from ErisPulse.Core import router
 
 
 @dataclass
-class {name}Config(AdapterConfig):
+class {name}Config(BaseConfig):
     \"\"\"{name} 适配器配置\"\"\"
     endpoint: str = field(
         default="https://api.example.com",
-        metadata={{"description": "平台 API 地址"}},
+        metadata={{
+            "description": {{"i18n": "adapter.{name}.endpoint", "default": "平台 API 地址"}},
+            "required": False,
+            "ui": {{"widget": "text", "group": "connection", "order": 1}},
+        }},
     )
     token: str = field(
         default="",
-        metadata={{"description": "平台 Token", "required": True, "secret": True}},
+        metadata={{
+            "description": {{"i18n": "adapter.{name}.token", "default": "平台 Token"}},
+            "required": True,
+            "secret": True,
+            "ui": {{"widget": "password", "group": "basic", "order": 2}},
+        }},
     )
 
 
@@ -284,7 +296,7 @@ class {name}(BaseAdapter):
 
     async def start(self):
         \"\"\"启动适配器\"\"\"
-        cfg = self.config
+        cfg = self.cfg
         self.logger.info(f"启动 {{cfg.endpoint}} 适配器")
 
         router.register_websocket(
@@ -322,7 +334,7 @@ class {name}(BaseAdapter):
         \"\"\"调用平台 API\"\"\"
         from ErisPulse.Core import client
 
-        cfg = self.config
+        cfg = self.cfg
         headers = {{"Authorization": "Bearer " + cfg.token}}
         url = cfg.endpoint + endpoint
 

{erispulse-2.5.2.dev4 → erispulse-2.5.4}/src/ErisPulse/Core/Bases/adapter.py

@@ -532,7 +532,7 @@ class BaseAdapter(ABC):
     4. 通过on装饰器注册事件处理器
     5. 支持OneBot12协议的事件处理
     6. 通过 ConfigClass / AccountConfigClass 声明配置类，框架自动管理配置
-    7. 通过 self.config / self.accounts 访问类型安全的配置对象
+    7. 通过 self.cfg / self.accounts 访问类型安全的配置对象（实时读取）
     8. 通过 self.emit_meta() 发送 meta 事件
     9. 通过 self.make_response() / self.make_error() 构造标准化响应
     {!--< /tips >!--}
@@ -672,10 +672,45 @@ class BaseAdapter(ABC):
         self._config_instance = None
         self._accounts_data = None
 
+        # 初始化时确保配置模板存在
         if self.ConfigClass is not None:
-            self._config_instance = self._load_config()
+            self._ensure_config_exists()
+            # 向后兼容：子类可覆写 _load_config() 实现自定义加载
+            custom_cfg = self._load_config()
+            if custom_cfg is not None:
+                self._config_instance = custom_cfg
         if self.AccountConfigClass is not None:
-            self._accounts_data = self._load_accounts()
+            self._ensure_accounts_exist()
+            # 向后兼容：子类可覆写 _load_accounts() 实现自定义加载
+            custom = self._load_accounts()
+            if custom is not None:
+                self._accounts_data = custom
+            else:
+                self._accounts_data = self.accounts
+
+    def _load_accounts(self) -> dict | None:
+        """
+        {!--< internal-use >!--}
+        加载账户配置（可被子类覆写）
+
+        子类可覆写此方法实现自定义账户加载逻辑（如全局配置合并、旧格式迁移等）。
+        返回 None 时使用默认配置存储读取逻辑。
+
+        :return: 账户配置字典，或 None 表示使用默认逻辑
+        """
+        return None
+
+    def _load_config(self):
+        """
+        {!--< internal-use >!--}
+        加载适配器配置（可被子类覆写）
+
+        子类可覆写此方法实现自定义配置加载逻辑（如旧格式迁移等）。
+        返回 None 时使用默认配置存储读取逻辑。
+
+        :return: 配置实例，或 None 表示使用默认逻辑
+        """
+        return None
 
     @abstractmethod
     async def call_api(self, endpoint: str, **params: Any) -> Any:
@@ -708,40 +743,117 @@ class BaseAdapter(ABC):
         raise NotImplementedError("适配器必须实现shutdown方法")
 
     @property
-    def config(self):
+    def cfg(self):
         """
-        类型安全的配置对象
+        类型安全的配置对象（实时读取）
+
+        每次访问都从配置存储读取最新值，确保用户修改配置后立即生效。
+        返回的 dataclass 实例是只读快照，修改它不会回写存储。
 
-        :return: AdapterConfig 实例
+        :return: AdapterConfig / BaseConfig 实例
         :raises AttributeError: 未声明 ConfigClass 时抛出
+
+        {!--< tips >!--}
+        推荐使用 ``self.cfg`` 而非 ``self.config``，
+        后者已弃用且可能被子类属性覆盖产生冲突。
+        {!--< /tips >!--}
         """
-        if self._config_instance is None:
+        if self.ConfigClass is None:
             raise AttributeError(
                 "未声明 ConfigClass，请设置 MyAdapter.ConfigClass = MyConfig"
             )
-        return self._config_instance
+
+        from ...runtime.config_schema import dict_to_dataclass
+        from ..config import config as config_mgr
+
+        data = config_mgr.getConfig(self._get_config_key())
+        if data is None:
+            # 配置不存在时生成默认模板后重试
+            self._ensure_config_exists()
+            data = config_mgr.getConfig(self._get_config_key()) or {}
+        return dict_to_dataclass(self.ConfigClass, data)
+
+    @cfg.setter
+    def cfg(self, value):
+        """设置配置实例，同时同步写入配置存储（保证实时性）"""
+        self._config_instance = value
+        if value is not None:
+            from dataclasses import asdict
+            from ..config import config as config_mgr
+
+            try:
+                config_mgr.setConfig(self._get_config_key(), asdict(value))
+            except Exception:
+                pass
+
+    @property
+    def config(self):
+        """
+        ``self.cfg`` 的兼容别名
+
+        功能与 ``self.cfg`` 完全一致，推荐新代码使用 ``self.cfg``。
+        """
+        return self.cfg
 
     @config.setter
     def config(self, value):
-        self._config_instance = value
+        self.cfg = value
 
     @property
     def accounts(self) -> dict:
         """
-        类型安全的账户配置字典 {name: config_instance}
+        类型安全的账户配置字典（实时读取）
 
-        :return: 账户配置字典
+        每次访问都从配置存储读取最新值，确保用户修改账户配置后立即生效。
+
+        :return: 账户配置字典 {name: config_instance}
         :raises AttributeError: 未声明 AccountConfigClass 时抛出
         """
-        if self._accounts_data is None:
+        if self.AccountConfigClass is None:
             raise AttributeError(
                 "未声明 AccountConfigClass，请设置 MyAdapter.AccountConfigClass = MyBotConfig"
             )
-        return self._accounts_data
+
+        from ...runtime.config_schema import dict_to_dataclass, validate_config
+        from ..config import config as config_mgr
+
+        key = f"{self._get_config_key()}.accounts"
+        data = config_mgr.getConfig(key)
+        if data is None:
+            # 配置不存在时生成默认账户模板后重试
+            self._ensure_accounts_exist()
+            data = config_mgr.getConfig(key) or {}
+
+        accounts = {}
+        for name, account_data in data.items():
+            if not isinstance(account_data, dict):
+                continue
+            instance = dict_to_dataclass(self.AccountConfigClass, account_data)
+            errors = validate_config(instance)
+            if errors:
+                self._get_logger().error(
+                    f"账户 {name} 配置校验失败: {', '.join(errors)}"
+                )
+                continue
+            accounts[name] = instance
+
+        return accounts
 
     @accounts.setter
     def accounts(self, value):
+        """设置账户配置字典，同时同步写入配置存储"""
         self._accounts_data = value
+        if value is not None:
+            from dataclasses import asdict
+            from ..config import config as config_mgr
+
+            key = f"{self._get_config_key()}.accounts"
+            try:
+                config_mgr.setConfig(
+                    key, {name: asdict(cfg) for name, cfg in value.items()}
+                )
+            except Exception:
+                pass
 
     @property
     def enabled_accounts(self) -> dict:
@@ -782,20 +894,18 @@ class BaseAdapter(ABC):
 
             return logging.getLogger(self.__class__.__name__)
 
-    def _load_config(self):
+    def _ensure_config_exists(self):
         """
-        从 TOML 加载全局配置
-
-        1. 读取 {ConfigKey} 键
-        2. 如果不存在，用 dataclass 默认值生成模板并写入
-        3. 用 dict_to_dataclass() 转为类型安全的实例
+        确保全局配置模板存在，不存在则生成默认配置
 
-        :return: AdapterConfig 实例
+        {!--< internal-use >!--}
+        {!--< /internal-use >!--}
         """
+        if self.ConfigClass is None:
+            return
         from ...runtime.config_schema import (
             dataclass_to_defaults_dict,
             dataclass_to_toml_with_comments,
-            dict_to_dataclass,
         )
         from ..config import config as config_mgr
 
@@ -808,24 +918,16 @@ class BaseAdapter(ABC):
             config_mgr.setConfig(key, data, immediate=True)
             self._get_logger().info(f"已生成 {key} 默认配置模板:\n{toml_str}")
 
-        return dict_to_dataclass(self.ConfigClass, data)
-
-    def _load_accounts(self) -> dict:
+    def _ensure_accounts_exist(self):
         """
-        从 TOML 加载多账户配置
+        确保多账户配置模板存在，不存在则生成默认账户配置
 
-        1. 读取 {ConfigKey}.accounts 键
-        2. 如果不存在，创建包含一个 default 账户的模板
-        3. 对每个账户做 validate_config() 校验
-        4. 跳过校验失败的账户并记录错误
-
-        :return: 账户配置字典 {name: config_instance}
+        {!--< internal-use >!--}
+        {!--< /internal-use >!--}
         """
-        from ...runtime.config_schema import (
-            dataclass_to_defaults_dict,
-            dict_to_dataclass,
-            validate_config,
-        )
+        if self.AccountConfigClass is None:
+            return
+        from ...runtime.config_schema import dataclass_to_defaults_dict
         from ..config import config as config_mgr
 
         key = f"{self._get_config_key()}.accounts"
@@ -837,21 +939,6 @@ class BaseAdapter(ABC):
             config_mgr.setConfig(key, data, immediate=True)
             self._get_logger().info(f"已生成 {key} 默认账户配置")
 
-        accounts = {}
-        for name, account_data in data.items():
-            if not isinstance(account_data, dict):
-                continue
-            instance = dict_to_dataclass(self.AccountConfigClass, account_data)
-            errors = validate_config(instance)
-            if errors:
-                self._get_logger().error(
-                    f"账户 {name} 配置校验失败: {', '.join(errors)}"
-                )
-                continue
-            accounts[name] = instance
-
-        return accounts
-
     def _resolve_account(self, account_id: str | None = None) -> tuple:
         """
         解析目标账户
@@ -869,18 +956,21 @@ class BaseAdapter(ABC):
         """
         from dataclasses import fields as dc_fields
 
+        # 单账户适配器（未声明 AccountConfigClass 或未填充 _accounts_data）
         if self._accounts_data is None:
-            raise ValueError("未声明 AccountConfigClass，无法解析账户")
+            return None, None
+
+        accounts = self._accounts_data
 
         if account_id is not None:
-            if account_id in self._accounts_data:
-                return account_id, self._accounts_data[account_id]
+            if account_id in accounts:
+                return account_id, accounts[account_id]
 
-            for name, cfg in self._accounts_data.items():
+            for name, cfg in accounts.items():
                 if hasattr(cfg, "bot_id") and cfg.bot_id == account_id:
                     return name, cfg
 
-            for name, cfg in self._accounts_data.items():
+            for name, cfg in accounts.items():
                 for f in dc_fields(cfg):
                     if f.name in ("enabled", "name"):
                         continue
@@ -888,7 +978,7 @@ class BaseAdapter(ABC):
                     if isinstance(val, str) and val == account_id:
                         return name, cfg
 
-        for name, cfg in self._accounts_data.items():
+        for name, cfg in accounts.items():
             if cfg.enabled:
                 return name, cfg
 

{erispulse-2.5.2.dev4 → erispulse-2.5.4}/src/ErisPulse/Core/Bases/adapter.pyi

@@ -315,7 +315,7 @@ class BaseAdapter(ABC):
     4. 通过on装饰器注册事件处理器
     5. 支持OneBot12协议的事件处理
     6. 通过 ConfigClass / AccountConfigClass 声明配置类，框架自动管理配置
-    7. 通过 self.config / self.accounts 访问类型安全的配置对象
+    7. 通过 self.cfg / self.accounts 访问类型安全的配置对象（实时读取）
     8. 通过 self.emit_meta() 发送 meta 事件
     9. 通过 self.make_response() / self.make_error() 构造标准化响应
     {!--< /tips >!--}
@@ -350,25 +350,50 @@ class BaseAdapter(ABC):
         :raises NotImplementedError: 必须由子类实现
         """
         ...
-    def config(self: object) -> ...:
+    def cfg(self: object) -> ...:
         """
-        类型安全的配置对象
+        类型安全的配置对象（实时读取）
+        
+        每次访问都从配置存储读取最新值，确保用户修改配置后立即生效。
+        返回的 dataclass 实例是只读快照，修改它不会回写存储。
         
-        :return: AdapterConfig 实例
+        :return: AdapterConfig / BaseConfig 实例
         :raises AttributeError: 未声明 ConfigClass 时抛出
+        
+        {!--< tips >!--}
+        推荐使用 ``self.cfg`` 而非 ``self.config``，
+        后者已弃用且可能被子类属性覆盖产生冲突。
+        {!--< /tips >!--}
+        """
+        ...
+    def cfg(self: object, value: ...) -> ...:
+        """
+        设置配置实例，同时同步写入配置存储（保证实时性）
+        """
+        ...
+    def config(self: object) -> ...:
+        """
+        ``self.cfg`` 的兼容别名
+        
+        功能与 ``self.cfg`` 完全一致，推荐新代码使用 ``self.cfg``。
         """
         ...
     def config(self: object, value: ...) -> ...:
         ...
     def accounts(self: object) -> dict:
         """
-        类型安全的账户配置字典 {name: config_instance}
+        类型安全的账户配置字典（实时读取）
+        
+        每次访问都从配置存储读取最新值，确保用户修改账户配置后立即生效。
         
-        :return: 账户配置字典
+        :return: 账户配置字典 {name: config_instance}
         :raises AttributeError: 未声明 AccountConfigClass 时抛出
         """
         ...
     def accounts(self: object, value: ...) -> ...:
+        """
+        设置账户配置字典，同时同步写入配置存储
+        """
         ...
     def enabled_accounts(self: object) -> dict:
         """
@@ -396,29 +421,6 @@ class BaseAdapter(ABC):
         获取 logger，兼容 sdk 未注入的场景
         """
         ...
-    def _load_config(self: object) -> ...:
-        """
-        从 TOML 加载全局配置
-        
-        1. 读取 {ConfigKey} 键
-        2. 如果不存在，用 dataclass 默认值生成模板并写入
-        3. 用 dict_to_dataclass() 转为类型安全的实例
-        
-        :return: AdapterConfig 实例
-        """
-        ...
-    def _load_accounts(self: object) -> dict:
-        """
-        从 TOML 加载多账户配置
-        
-        1. 读取 {ConfigKey}.accounts 键
-        2. 如果不存在，创建包含一个 default 账户的模板
-        3. 对每个账户做 validate_config() 校验
-        4. 跳过校验失败的账户并记录错误
-        
-        :return: 账户配置字典 {name: config_instance}
-        """
-        ...
     def _resolve_account(self: object, account_id: str | None = ...) -> tuple:
         """
         解析目标账户