Eridanus

Appearance

框架消息与事件处理机制 ​

在独立的 SDK 里，我们直接和 WebSocketBot 打交道；而在 Eridanus 完整的框架生态里，派发到每个插件中的 bot 实例，其实是更加智能、身经百战的 ExtendBot 增强型机器人！

它在原生 OneBot v11 事件总线之上，注入了全局黑白名单阻断、双 Bot 跨平台虚拟群协调、慢回调熔断预警以及用户权限过滤等框架级护盾。

1. ExtendBot 核心增强特性 ​

源码位于 framework_common/framework_util/websocket_fix.py 与 main.py：

  1. 三维立体黑白名单拦截： 收到群消息或私聊时，底层自动核对 run/common_config/black_and_white_list.yaml 中的黑名单列表。一旦命中黑名单 QQ 或群号，数据包在最底层被静默丢弃，根本不会占用任何业务插件的 CPU 时间！
  2. 双 Bot 架构 (DualBotManager)：
    • 主 Bot (bot1)：直连 OneBot v11（SnowLuma / NapCat），负责处理真实 QQ 群聊与好友互动；
    • 内部副 Bot (bot2)：直连内置 WebUI（ws://127.0.0.1:5007/api/ws）及 Live2D 桌宠虚拟通道；
    • 两者通过 DualBotManager 在底层自动实现虚拟群（如 879886836）与真实消息的双向路由，让你写一份插件即可同时为 QQ 和 WebUI 提供服务！
  3. 离线与断网容灾模式： 若全局配置中的 WebSocket 链接为空，ExtendBot 自动平滑降级为“离线模式”，避免在单机环境或独立调试 WebUI 时抛出无休止的网络重连错误。
  4. 插件慢回调耗时监控 (HandlerMonitor)： 主循环中内置执行时钟，任何处理超过指定阈值（默认 10 秒）的插件回调都会被抓取并打出黄色预警日志，精准定位卡死协程。

2. 插件事件处理的最佳实践准则 ​

在编写框架级插件时，请务必遵守以下黄金法则：

① 必须全流程非阻塞 (Non-Blocking) ​

避免在插件事件回调中使用阻塞的 time.sleep() 或同步 requests 库！必须采用原生异步方案：

python
import asyncio
import httpx

# 正确：使用异步客户端
async with httpx.AsyncClient() as client:
    res = await client.get("https://api.example.com/data")
    data = res.json()

② 严格且温柔的异常捕获 ​

单个群友的恶性输入绝不能搞崩整个插件：

python
@bot.on(GroupMessageEvent)
async def safe_handler(event: GroupMessageEvent):
    try:
        # 核心业务
        await process_business(event)
    except Exception as e:
        bot.logger.error(f"[我的插件] 执行异常: {e}", exc_info=True)
        # 温柔回复群友，避免现场尴尬
        await bot.send(event, "呜……刚才处理这道指令时走神了，稍后再试一次吧喵~")

③ 指令格式匹配建议 ​

优先使用 event.pure_text.strip() 获取干净纯文本；对于带参数的复杂指令，建议使用前缀切片或标准正则：

python
text = event.pure_text.strip()
if text.startswith("查询 "):
    target = text[3:].strip()
    # 执行后续逻辑...

理解了这套消息与事件生命线，你的插件就能在 Eridanus 庞大的生态体系里如鱼得水、稳健运行啦！