基础概念

本指南介绍 ErisPulse 的核心概念，帮助你理解框架的设计思想和基本架构。

事件驱动架构

ErisPulse 采用事件驱动架构，所有的交互都通过事件来传递和处理。

事件流程

用户发送消息
      │
      ▼
平台接收
      │
      ▼
适配器接收平台原生事件
      │
      ▼
转换为 OneBot12 标准事件
      │
      ▼
提交到事件系统
      │
      ▼
分发给已注册的处理器
      │
      ▼
模块处理事件
      │
      ▼
通过适配器发送响应
      │
      ▼
平台显示给用户

OneBot12 标准

ErisPulse 使用 OneBot12 作为核心事件标准。OneBot12 是一个通用的聊天机器人应用接口标准，定义了统一的事件格式。

所有适配器都将平台特定的事件转换为 OneBot12 格式，确保代码的一致性。

核心组件

1. SDK 对象

SDK 是所有功能的统一入口点，提供对核心组件的访问。

from ErisPulse import sdk

# 访问核心模块
sdk.storage    # 存储系统
sdk.config     # 配置系统
sdk.logger     # 日志系统
sdk.adapter    # 适配器系统
sdk.module     # 模块系统
sdk.router     # 路由系统
sdk.client     # HTTP 客户端
sdk.lifecycle  # 生命周期系统

2. Event 对象

Event 对象封装了事件数据，提供了便捷的访问方法。

@command("info")
async def info_handler(event):
    # 获取事件信息
    event_id = event.get_id()
    user_id = event.get_user_id()
    platform = event.get_platform()
    text = event.get_text()
    
    # 发送回复
    await event.reply(f"用户: {user_id}, 平台: {platform}")

3. 适配器

适配器是 ErisPulse 与外部平台之间的桥梁。

职责：

• 接收平台原生事件
• 转换为 OneBot12 标准格式
• 将标准格式事件发送到平台

示例适配器：

• Yunhu 适配器：与云湖平台通信
• Telegram 适配器：与 Telegram Bot API 通信
• OneBot11 适配器：与 OneBot11 兼容的应用通信
• Email 适配器：处理邮件收发

4. 模块

模块是功能扩展的基本单位，可以：

• 注册事件处理器
• 实现业务逻辑
• 调用适配器发送消息
• 使用核心模块提供的服务

模块发现机制

ErisPulse 通过 Python 的 importlib.metadata.entry_points 发现已安装的模块。模块在 pyproject.toml 中声明入口点：

[project.entry-points."erispulse.module"]
MyModule = "my_package:Main"

SDK 初始化时会扫描所有 erispulse.module 组的入口点，将模块类注册到 ModuleManager，然后按依赖关系拓扑排序后依次初始化。

最小可用模块

from ErisPulse.Core.Bases import BaseModule
from ErisPulse import sdk

class Main(BaseModule):
    def __init__(self):
        self.sdk = sdk
        self.logger = sdk.logger.get_child("MyModule")

    async def on_load(self, event):
        self.logger.info("模块已加载")

    async def on_unload(self, event):
        self.logger.info("模块已卸载")

模块生命周期

• 注册：SDK 发现模块类并注册到管理器
• 加载：创建模块实例，调用 on_load(event)（event = {"module_name": "MyModule"}）
• 卸载：调用 on_unload(event)，清理资源

加载策略

通过 get_load_strategy() 声明模块的加载行为：

from ErisPulse.loaders import ModuleLoadStrategy

class Main(BaseModule):
    @staticmethod
    def get_load_strategy():
        return ModuleLoadStrategy(
            lazy_load=True,   # 是否懒加载（默认 True）
            priority=0        # 加载优先级，数值越大越先初始化
        )

• lazy_load=True（默认）：模块在首次被 sdk.MyModule 访问时才初始化，减少启动时间
• **lazy_load=False**：SDK 启动时立即初始化，适合需要监听生命周期事件或执行定时任务的模块
• **priority**：同优先级的模块按注册顺序加载；数值越大越先初始化

详细的懒加载机制说明请参考 懒加载系统。

事件类型

ErisPulse 支持 5 类事件：

各事件类型的详细用法和代码示例请参考 事件处理入门。

核心模块说明

Storage（存储）

基于 SQLite 的键值存储系统，用于持久化数据。

# 设置值
sdk.storage.set("key", "value")

# 获取值
value = sdk.storage.get("key", "default_value")

# 批量操作
sdk.storage.set_multi({
    "key1": "value1",
    "key2": "value2"
})

# 事务
with sdk.storage.transaction():
    sdk.storage.set("key1", "value1")
    sdk.storage.set("key2", "value2")

Config（配置）

TOML 格式的配置文件管理。

# 获取配置
config = sdk.config.getConfig("MyModule", {})

# 设置配置
sdk.config.setConfig("MyModule", {"key": "value"})

# 读取嵌套配置
value = sdk.config.getConfig("MyModule.subkey", "default")

Logger（日志）

模块化日志系统。

# 记录日志
sdk.logger.info("这是一条信息")
sdk.logger.warning("这是一条警告")
sdk.logger.error("这是一条错误")

# 获取子日志记录器
child_logger = sdk.logger.get_child("submodule")
child_logger.info("子模块日志")

属性访问语法糖

除了使用 get_child() 方法外，你还可以通过属性访问的方式创建子logger，这是一种更简洁的语法糖写法：

# 通过属性访问创建子logger
sdk.logger.mymodule.info("模块消息")

# 支持嵌套访问
sdk.logger.mymodule.database.info("数据库消息")

Router（路由）

HTTP 和 WebSocket 路由管理，基于 FastAPI + Uvicorn。支持装饰器路由、中间件、分组、限流、CORS。

from ErisPulse.Core import HttpRequest

@sdk.router.get("MyModule", "/api")
async def handler(request: HttpRequest):
    data = await request.json()
    return {"status": "ok"}

完整的路由 API（WebSocket、中间件、速率限制、CORS 等）请参考 路由管理器。

Client（网络客户端）

统一的网络客户端，聚合了 HTTP 请求、WebSocket 连接、连接池管理、自动重试、超时控制、请求统计和生命周期事件集成。

from ErisPulse.Core import client

# HTTP 请求
resp = await client.get("https://api.example.com/users")
data = await resp.json()

# 带重试和超时
resp = await client.get(url, timeout=30, max_retries=3)

# WebSocket 连接
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
    await ws.send_text(f"Echo: {text}")

完整的网络客户端 API 请参考 网络客户端。

SendDSL 消息发送

适配器提供链式调用的消息发送接口。

基础发送

# 获取适配器实例
yunhu = sdk.adapter.get("yunhu")

# 发送消息
await yunhu.Send.To("user", "U1001").Text("Hello")

# 指定发送账号
await yunhu.Send.Using("bot1").To("group", "G1001").Text("群消息")

链式修饰

# @用户
await yunhu.Send.To("group", "G1001").At("U2001").Text("@消息")

# 回复消息
await yunhu.Send.To("group", "G1001").Reply("msg123").Text("回复")

# @全体
await yunhu.Send.To("group", "G1001").AtAll().Text("公告")

Event 回复方法

Event 对象提供了便捷的回复方法：

@command("test")
async def test_handler(event):
    # 简单文本回复
    await event.reply("回复内容")
    
    # 发送图片
    await event.reply("http://example.com/image.jpg", method="Image")
    
    # 发送语音
    await event.reply("http://example.com/voice.mp3", method="Voice")

懒加载系统

ErisPulse 默认启用模块懒加载，模块只在首次被访问（如 sdk.MyModule）时才初始化，显著提高启动速度。

from ErisPulse.loaders import ModuleLoadStrategy

class Main(BaseModule):
    @staticmethod
    def get_load_strategy():
        return ModuleLoadStrategy(
            lazy_load=True,   # 启用懒加载（默认）
            priority=0        # 加载优先级，数值越大越先初始化
        )

需要禁用懒加载的场景（lazy_load=False）：

• 监听生命周期事件的模块（如 core.init.complete）
• 启动定时任务或后台服务的模块
• 需要在其他模块加载前完成初始化的模块

详细的懒加载机制和注意事项请参考 懒加载系统。

下一步

• 事件处理入门 - 学习如何处理各类事件
• 常见任务示例 - 掌握常用功能的实现