ErisPulse 2.4.5.dev2__tar.gz → 2.4.5.dev3__tar.gz

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.4.5.dev2
+Version: 2.4.5.dev3
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: ErisDev <erisdev@88.com>
 Maintainer-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.4.5-dev.2"
+version = "2.4.5-dev.3"
 description = "ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。"
 readme = "README.md"
 requires-python = ">=3.10"

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/CLI/commands/init.py

@@ -84,32 +84,32 @@ class InitCommand(Command):
                 dir_path.mkdir(exist_ok=True)
                 console.print(f"[green]创建目录: {dir_name}[/green]")
             
-            # 创建配置文件
+            # 创建配置文件 (最小必须配置)
             config_file = project_path / "config" / "config.toml"
             if not config_file.exists():
                 with open(config_file, "w", encoding="utf-8") as f:
-                    f.write("# ErisPulse 配置文件\n\n")
-                    f.write("[ErisPulse]\n")
-                    f.write("# 全局配置\n\n")
+                    f.write("# ErisPulse 配置文件\n")
+                    f.write("# 完整配置示例请参考 config.full.example\n\n")
                     f.write("[ErisPulse.server]\n")
                     f.write('host = "0.0.0.0"\n')
                     f.write("port = 8000\n\n")
                     f.write("[ErisPulse.logger]\n")
                     f.write('level = "INFO"\n')
-                    f.write("log_files = [\"logs/app.log\"]\n")
-                    f.write("memory_limit = 1000\n\n")
                     
-                    # 添加适配器配置
                     if adapter_list:
-                        f.write("[ErisPulse.adapters]\n")
-                        f.write("# 适配器配置\n\n")
-                        f.write("[ErisPulse.adapters.status]\n")
+                        f.write("\n[ErisPulse.adapters.status]\n")
                         for adapter in adapter_list:
-                            f.write(f'{adapter} = false  # 默认禁用，需要时启用\n')
-                        f.write("\n")
+                            f.write(f'{adapter} = false\n')
                 
                 console.print("[green]创建配置文件: config/config.toml[/green]")
             
+            # 创建完整配置示例文件
+            example_file = project_path / "config" / "config.full.example"
+            if not example_file.exists():
+                with open(example_file, "w", encoding="utf-8") as f:
+                    f.write(self._get_full_example_config(adapter_list))
+                console.print("[green]创建配置示例: config/config.full.example[/green]")
+            
             # 创建主程序文件
             main_file = project_path / "main.py"
             if not main_file.exists():
@@ -139,6 +139,112 @@ class InitCommand(Command):
             console.print(f"[red]初始化项目失败: {e}[/]")
             return False
     
+    @staticmethod
+    def _get_full_example_config(adapter_list=None):
+        """
+        生成完整配置示例文件内容
+        
+        :param adapter_list: list 可用适配器列表
+        :return: str 完整配置示例内容
+        
+        {!--< internal-use >!--}
+        {!--< /internal-use >!--}
+        """
+        lines = [
+            "# ErisPulse 完整配置示例",
+            "# 此文件展示所有可用配置项及其默认值",
+            "# 如需使用，将所需配置复制到 config.toml 并按需修改",
+            "",
+            "# ==================== 服务器 ====================",
+            "",
+            "[ErisPulse.server]",
+            'host = "0.0.0.0"              # 监听地址',
+            "port = 8000                   # 监听端口",
+            "ssl_certfile = null           # SSL 证书路径",
+            "ssl_keyfile = null            # SSL 密钥路径",
+            "",
+            "# ==================== 日志 ====================",
+            "",
+            "[ErisPulse.logger]",
+            'level = "INFO"                # 日志级别: DEBUG/INFO/WARNING/ERROR',
+            "log_files = []                # 日志文件列表, 如 [\"logs/app.log\"]",
+            "memory_limit = 1000           # 内存日志条数上限",
+            "",
+            "# ==================== 存储 ====================",
+            "",
+            "[ErisPulse.storage]",
+            "use_global_db = false         # 是否使用全局数据库",
+            "",
+            "# ==================== 事件系统 ====================",
+            "",
+            "[ErisPulse.event.message]",
+            "ignore_self = true            # 忽略自身消息",
+            "",
+            "[ErisPulse.event.command]",
+            'prefix = "/"                  # 命令前缀',
+            "case_sensitive = true         # 区分大小写",
+            "allow_space_prefix = false    # 允许前缀前有空格",
+            "must_at_bot = false           # 必须艾特Bot才触发",
+            "",
+            "# ==================== 框架 ====================",
+            "",
+            "[ErisPulse.framework]",
+            "enable_lazy_loading = true    # 启用模块懒加载",
+            "",
+            "# ==================== 配置审计 ====================",
+            "",
+            "[ErisPulse.config.audit]",
+            "enabled = false               # 是否启用配置审计",
+            "max_entries = 1000            # 审计日志最大条数",
+            "",
+            "# ==================== 指标监控 ====================",
+            "",
+            "[ErisPulse.metrics]",
+            "enabled = false               # 是否启用指标采集",
+            "",
+            "# ==================== 路由增强 ====================",
+            "",
+            "[ErisPulse.router.cors]",
+            "enabled = false",
+            'allow_origins = ["*"]',
+            'allow_methods = ["*"]',
+            'allow_headers = ["*"]',
+            "allow_credentials = false",
+            "max_age = 600",
+            "",
+            "[ErisPulse.router.security]",
+            "enabled = false",
+            "",
+            "[ErisPulse.router.security.headers]",
+            'X-Content-Type-Options = "nosniff"',
+            'X-Frame-Options = "DENY"',
+            "",
+            "# ==================== 适配器状态 ====================",
+            "",
+            "[ErisPulse.adapters.status]",
+        ]
+        
+        if adapter_list:
+            for adapter in adapter_list:
+                lines.append(f"# {adapter} = false")
+        else:
+            lines.extend([
+                "# yunhu = false",
+                "# telegram = false",
+                "# onebot11 = false",
+            ])
+        
+        lines.extend([
+            "",
+            "# ==================== 模块状态 ====================",
+            "",
+            "[ErisPulse.modules.status]",
+            "# MyModule = true",
+            "",
+        ])
+        
+        return "\n".join(lines)
+    
     async def _fetch_available_adapters(self):
         """
         从云端获取可用适配器列表

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/Core/Event/wrapper.py

@@ -1164,12 +1164,15 @@ class Conversation:
     """
     多轮对话上下文
 
-    提供在同一会话中进行多轮交互的便捷方法
+    提供在同一会话中进行多轮交互的便捷方法，支持分支跳转、上下文持久化
 
     {!--< tips >!--}
     1. 通过 event.conversation() 方法创建
     2. 超时后自动标记为非活跃状态
     3. 支持链式调用 say() 方法
+    4. 支持 branch() 定义分支和 goto() 跳转
+    5. 支持 context 字典存储对话状态
+    6. 支持 save()/resume() 持久化到 storage
     {!--< /tips >!--}
     """
 
@@ -1183,6 +1186,10 @@ class Conversation:
         self._event = event
         self._timeout = timeout
         self._alive = True
+        self._branches: dict[str, Callable] = {}
+        self._current_branch: str | None = None
+        self._branch_task: asyncio.Task | None = None
+        self.context: dict[str, Any] = {}
 
     @property
     def is_active(self) -> bool:
@@ -1259,18 +1266,33 @@ class Conversation:
         """
         多步骤收集信息
 
-        :param fields: list[dict] - 字段列表
+        :param fields: list[dict] - 字段列表，支持 condition 字段:
+            - condition: callable - 接收已收集数据 dict, 返回 bool 决定是否收集此字段
         :return: dict|None - 收集到的数据字典或 None
         """
         if not self._alive:
             return None
+
+        filtered_fields = []
+        for f in fields:
+            cond = f.get("condition")
+            if cond is not None:
+                try:
+                    if not cond(self.context):
+                        continue
+                except Exception:
+                    continue
+            filtered_fields.append(f)
+
         result = await self._event.collect(
-            fields,
+            filtered_fields,
             timeout_per_field=kwargs.pop("timeout_per_field", self._timeout),
             **kwargs,
         )
         if result is None:
             self._alive = False
+        else:
+            self.context.update(result)
         return result
 
     def stop(self):
@@ -1278,6 +1300,193 @@ class Conversation:
         结束对话
         """
         self._alive = False
+        if self._branch_task and not self._branch_task.done():
+            self._branch_task.cancel()
+
+    # 分支系统
+
+    def branch(self, name: str):
+        """
+        注册分支处理器
+
+        :param name: str 分支名称
+        :return: Callable 装饰器
+
+        :example:
+        >>> conv = event.conversation()
+        >>>
+        >>> @conv.branch("menu")
+        ... async def menu_branch(conv, event):
+        ...     await conv.say("1.饮品 2.主食")
+        ...     resp = await conv.wait()
+        ...     if resp and resp.get_text() == "1":
+        ...         conv.goto("drink")
+        ...
+        >>> @conv.branch("drink")
+        ... async def drink_branch(conv, event):
+        ...     await conv.say("请选择饮品")
+        ...     resp = await conv.wait()
+        ...     conv.context["drink"] = resp.get_text()
+        ...     conv.goto("confirm")
+        ...
+        >>> conv.start("menu")
+        """
+        def decorator(func: Callable):
+            self._branches[name] = func
+            return func
+        return decorator
+
+    def goto(self, branch_name: str, event: "Event" = None):
+        """
+        跳转到指定分支
+
+        :param branch_name: str 目标分支名称
+        :param event: Event 传递给分支的事件对象 (可选)
+
+        :raises ValueError: 当目标分支不存在时
+
+        :example:
+        >>> conv.goto("drink")
+        """
+        if branch_name not in self._branches:
+            raise ValueError(f"分支 '{branch_name}' 未定义")
+        self._current_branch = branch_name
+
+        evt = event or self._event
+
+        if self._branch_task and not self._branch_task.done():
+            self._branch_task.cancel()
+
+        async def _run_branch():
+            handler = self._branches[branch_name]
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    await handler(self, evt)
+                else:
+                    handler(self, evt)
+            except asyncio.CancelledError:
+                pass
+            except Exception as e:
+                from ..logger import logger as _logger
+                _logger.warning(f"分支 '{branch_name}' 执行异常: {e}")
+                self._alive = False
+
+        try:
+            loop = asyncio.get_running_loop()
+            self._branch_task = loop.create_task(_run_branch())
+        except RuntimeError:
+            pass
+
+    def start(self, branch_name: str, event: "Event" = None):
+        """
+        启动对话，从指定分支开始
+
+        :param branch_name: str 起始分支名称
+        :param event: Event 初始事件对象 (可选)
+
+        :raises ValueError: 当起始分支不存在时
+
+        :example:
+        >>> conv.start("menu")
+        """
+        self._alive = True
+        self.goto(branch_name, event)
+
+    def get_current_branch(self) -> str | None:
+        """
+        获取当前分支名称
+
+        :return: str|None 当前分支名, 未在分支中时返回 None
+        """
+        return self._current_branch
+
+    def has_branch(self, name: str) -> bool:
+        """
+        检查分支是否存在
+
+        :param name: str 分支名称
+        :return: bool 是否存在
+        """
+        return name in self._branches
+
+    # ==================== 持久化 ====================
+
+    async def save(self):
+        """
+        保存对话状态到 storage
+
+        :example:
+        >>> await conv.save()
+
+        {!--< tips >!--}
+        保存内容包括: 当前分支、上下文数据、活跃状态
+        可用于重启后恢复对话
+        {!--< /tips >!--}
+        """
+        try:
+            from ..storage import storage
+            user_id = self._event.get_user_id()
+            platform = self._event.get_platform()
+            key = f"conversation:{platform}:{user_id}"
+            storage.set(key, {
+                "branch": self._current_branch,
+                "context": self.context,
+                "alive": self._alive,
+                "timeout": self._timeout,
+            })
+        except Exception:
+            pass
+
+    async def resume(self, event: "Event" = None) -> bool:
+        """
+        从 storage 恢复对话状态
+
+        :param event: Event 新的事件对象 (可选, 不传则使用原事件)
+        :return: bool 是否恢复成功
+
+        :example:
+        >>> conv = event.conversation()
+        >>> # ... 注册分支 ...
+        >>> if await conv.resume():
+        ...     conv.goto(conv.get_current_branch())
+
+        {!--< tips >!--}
+        需要在 resume() 之前先注册好所有分支
+        {!--< /tips >!--}
+        """
+        try:
+            from ..storage import storage
+            evt = event or self._event
+            user_id = evt.get_user_id()
+            platform = evt.get_platform()
+            key = f"conversation:{platform}:{user_id}"
+            data = storage.get(key)
+            if data and isinstance(data, dict):
+                self.context = data.get("context", {})
+                self._current_branch = data.get("branch")
+                self._alive = data.get("alive", False)
+                if event:
+                    self._event = event
+                return True
+        except Exception:
+            pass
+        return False
+
+    async def clear_saved(self):
+        """
+        清除保存的对话状态
+
+        :example:
+        >>> await conv.clear_saved()
+        """
+        try:
+            from ..storage import storage
+            user_id = self._event.get_user_id()
+            platform = self._event.get_platform()
+            key = f"conversation:{platform}:{user_id}"
+            storage.delete(key)
+        except Exception:
+            pass
 
 
 __all__ = [

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/Core/Event/wrapper.pyi

@@ -678,12 +678,15 @@ class Conversation:
     """
     多轮对话上下文
     
-    提供在同一会话中进行多轮交互的便捷方法
+    提供在同一会话中进行多轮交互的便捷方法，支持分支跳转、上下文持久化
     
     {!--< tips >!--}
     1. 通过 event.conversation() 方法创建
     2. 超时后自动标记为非活跃状态
     3. 支持链式调用 say() 方法
+    4. 支持 branch() 定义分支和 goto() 跳转
+    5. 支持 context 字典存储对话状态
+    6. 支持 save()/resume() 持久化到 storage
     {!--< /tips >!--}
     """
     def __init__(self: None, event: Event, timeout: float = ...) -> ...:
@@ -739,7 +742,8 @@ class Conversation:
         """
         多步骤收集信息
         
-        :param fields: list[dict] - 字段列表
+        :param fields: list[dict] - 字段列表，支持 condition 字段:
+            - condition: callable - 接收已收集数据 dict, 返回 bool 决定是否收集此字段
         :return: dict|None - 收集到的数据字典或 None
         """
         ...
@@ -748,3 +752,110 @@ class Conversation:
         结束对话
         """
         ...
+    def branch(self: object, name: str) -> ...:
+        """
+        注册分支处理器
+        
+        :param name: str 分支名称
+        :return: Callable 装饰器
+        
+        :example:
+        >>> conv = event.conversation()
+        >>>
+        >>> @conv.branch("menu")
+        ... async def menu_branch(conv, event):
+        ...     await conv.say("1.饮品 2.主食")
+        ...     resp = await conv.wait()
+        ...     if resp and resp.get_text() == "1":
+        ...         conv.goto("drink")
+        ...
+        >>> @conv.branch("drink")
+        ... async def drink_branch(conv, event):
+        ...     await conv.say("请选择饮品")
+        ...     resp = await conv.wait()
+        ...     conv.context["drink"] = resp.get_text()
+        ...     conv.goto("confirm")
+        ...
+        >>> conv.start("menu")
+        """
+        ...
+    def goto(self: object, branch_name: str, event: Event = ...) -> ...:
+        """
+        跳转到指定分支
+        
+        :param branch_name: str 目标分支名称
+        :param event: Event 传递给分支的事件对象 (可选)
+        
+        :raises ValueError: 当目标分支不存在时
+        
+        :example:
+        >>> conv.goto("drink")
+        """
+        ...
+    def start(self: object, branch_name: str, event: Event = ...) -> ...:
+        """
+        启动对话，从指定分支开始
+        
+        :param branch_name: str 起始分支名称
+        :param event: Event 初始事件对象 (可选)
+        
+        :raises ValueError: 当起始分支不存在时
+        
+        :example:
+        >>> conv.start("menu")
+        """
+        ...
+    def get_current_branch(self: object) -> str | None:
+        """
+        获取当前分支名称
+        
+        :return: str|None 当前分支名, 未在分支中时返回 None
+        """
+        ...
+    def has_branch(self: object, name: str) -> bool:
+        """
+        检查分支是否存在
+        
+        :param name: str 分支名称
+        :return: bool 是否存在
+        """
+        ...
+    async def save(self: object) -> ...:
+        """
+        保存对话状态到 storage
+        
+        :example:
+        >>> await conv.save()
+        
+        {!--< tips >!--}
+        保存内容包括: 当前分支、上下文数据、活跃状态
+        可用于重启后恢复对话
+        {!--< /tips >!--}
+        """
+        ...
+    async def resume(self: object, event: Event = ...) -> bool:
+        """
+        从 storage 恢复对话状态
+        
+        :param event: Event 新的事件对象 (可选, 不传则使用原事件)
+        :return: bool 是否恢复成功
+        
+        :example:
+        >>> conv = event.conversation()
+        >>> # ... 注册分支 ...
+        >>> if await conv.resume():
+        ...     conv.goto(conv.get_current_branch())
+        
+        {!--< tips >!--}
+        需要在 resume() 之前先注册好所有分支
+        {!--< /tips >!--}
+        """
+        ...
+    async def clear_saved(self: object) -> ...:
+        """
+        清除保存的对话状态
+        
+        :example:
+        >>> await conv.clear_saved()
+        """
+        ...

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/Core/__init__.py

@@ -1,7 +1,7 @@
 """
 ErisPulse 核心模块
 
-提供了一系列用于构建和管理应用的核心组件，包括适配器、模块、存储、配置、路由和生命周期管理等。
+提供了一系列用于构建和管理应用的核心组件，包括适配器、模块、存储、配置、路由、指标监控和生命周期管理等。
 """
 
 from .lifecycle import lifecycle, LifecycleManager
@@ -10,8 +10,9 @@ from .Bases import BaseAdapter, BaseModule, SendDSL, BaseStorage, BaseQueryBuild
 from .storage import storage, StorageManager
 from .logger import logger, Logger, LoggerChild
 from .module import module, ModuleManager
-from .router import router, RouterManager
-from .config import config, ConfigManager
+from .router import router, RouterManager, RouteGroup
+from .config import config, ConfigManager, AuditEntry
+from .metrics import metrics, MetricsManager, Counter, Gauge, Histogram
 from . import Event
 from .Event.message_builder import MessageBuilder
 
@@ -37,13 +38,21 @@ __all__ = [
     'config',           # 配置模块单例
     'env',              # 配置管理器别名
     'ConfigManager',    # 配置管理器类
+    'AuditEntry',       # 审计条目类
 
     'router',           # 路由模块单例
     'RouterManager',    # 路由管理器类
+    'RouteGroup',       # 路由组类
 
     'logger',           # 日志模块单例
     'Logger',           # 日志类
     'LoggerChild',      # 日志子类
     'lifecycle',        # 生命周期模块单例
     'LifecycleManager', # 生命周期管理器类
+
+    'metrics',          # 指标模块单例
+    'MetricsManager',   # 指标管理器类
+    'Counter',          # 计数器类
+    'Gauge',            # 仪表类
+    'Histogram',        # 直方图类
 ]

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/Core/__init__.pyi

@@ -7,7 +7,7 @@
 """
 ErisPulse 核心模块
 
-提供了一系列用于构建和管理应用的核心组件，包括适配器、模块、存储、配置、路由和生命周期管理等。
+提供了一系列用于构建和管理应用的核心组件，包括适配器、模块、存储、配置、路由、指标监控和生命周期管理等。
 """
 
 from .lifecycle import lifecycle, LifecycleManager
@@ -16,7 +16,8 @@ from .Bases import BaseAdapter, BaseModule, SendDSL, BaseStorage, BaseQueryBuild
 from .storage import storage, StorageManager
 from .logger import logger, Logger, LoggerChild
 from .module import module, ModuleManager
-from .router import router, RouterManager
-from .config import config, ConfigManager
+from .router import router, RouterManager, RouteGroup
+from .config import config, ConfigManager, AuditEntry
+from .metrics import metrics, MetricsManager, Counter, Gauge, Histogram
 from . import Event
 from .Event.message_builder import MessageBuilder

{erispulse-2.4.5.dev2 → erispulse-2.4.5.dev3}/src/ErisPulse/Core/adapter.py

@@ -721,7 +721,11 @@ class AdapterManager(ManagerBase):
         # 先执行OneBot12中间件
         processed_data = data
         for middleware in self._onebot_middlewares:
-            processed_data = await middleware(processed_data)
+            result = await middleware(processed_data)
+            if result is not None:
+                processed_data = result
+            else:
+                logger.warning(f"中间件 {middleware.__qualname__} 返回 None，已忽略并保留原数据")
 
         # 分发到OneBot12事件处理器
         handlers_to_call = []