butterbot-python 3.1.0.dev1__py3-none-any.whl

butterbot/sources/napcat/filters/filters.py

@@ -0,0 +1,202 @@
+"""Napcat 预置过滤器.
+
+提供一组可直接组合使用的 ``BaseFilter`` 子类：
+
+- ``GroupFilter`` — 按群号过滤
+- ``UserFilter`` — 按用户 ID 过滤
+- ``SenderRoleFilter`` — 按发送者角色过滤（owner / admin / member）
+- ``TextFilter`` — 按消息文本关键词过滤
+- ``CommandFilter`` — 按完整命令精确匹配
+- ``PrefixFilter`` — 按消息前缀匹配
+
+所有过滤器遵循"安全"原则：事件不包含目标字段时默认拦截，
+确保只处理明确匹配的事件类型。
+"""
+
+from logging import getLogger
+from typing import TYPE_CHECKING, Literal
+
+from butterbot.core.filter import BaseFilter
+
+if TYPE_CHECKING:
+    from butterbot.core.event import Event
+
+_log = getLogger(__name__)
+
+
+class GroupFilter(BaseFilter):
+    """仅允许指定群组的事件通过。
+
+    对不包含 ``group_id`` 字段的事件类型（如私聊、元事件），默认拦截。
+
+    Usage:
+        ``GroupFilter(123456)`` — 仅 group_id=123456 的事件
+        ``GroupFilter(123456, 789012)`` — group_id 为 123456 **或** 789012 的事件
+    """
+
+    def __init__(self, *group_ids: int) -> None:
+        self.filters = list(group_ids)
+
+    def check(self, event: "Event") -> bool:
+        group_id = getattr(event.data, "group_id", None)
+        if group_id is None:
+            return False  # 非群聊事件，安全拦截
+        result = group_id in self.filters
+        if not result:
+            _log.debug("事件 %s 被 GroupFilter 拦截: group_id=%s", event.id, group_id)
+        return result
+
+
+class UserFilter(BaseFilter):
+    """仅允许指定用户的事件通过。
+
+    对不包含 ``user_id`` 字段的事件类型，默认拦截。
+
+    Usage:
+        ``UserFilter(10001)`` — 仅 user_id=10001 的事件
+        ``UserFilter(10001, 10002)`` — user_id 为 10001 **或** 10002 的事件
+    """
+
+    def __init__(self, *user_ids: int) -> None:
+        self.filters = list(user_ids)
+
+    def check(self, event: "Event") -> bool:
+        user_id = getattr(event.data, "user_id", None)
+        if user_id is None:
+            return False
+        result = user_id in self.filters
+        if not result:
+            _log.debug("事件 %s 被 UserFilter 拦截: user_id=%s", event.id, user_id)
+        return result
+
+
+class SenderRoleFilter(BaseFilter):
+    """仅允许指定发送者角色的群消息通过。
+
+    通过 ``group_id`` 字段的存在判断是否为群聊事件，
+    确认后检查 ``sender.role`` 的值。
+
+    非群聊事件或缺少必要字段时默认拦截。
+
+    Usage:
+        ``SenderRoleFilter("owner", "admin")`` — 仅群主或管理员消息
+    """
+
+    def __init__(self, *roles: Literal["owner", "admin", "member"]) -> None:
+        self.filters = list(roles)
+
+    def check(self, event: "Event") -> bool:
+        data = event.data
+        # 通过 group_id 判断是否为群聊事件
+        if getattr(data, "group_id", None) is None:
+            return False
+        sender = getattr(data, "sender", None)
+        if sender is None:
+            return False
+        role = getattr(sender, "role", None)
+        if role is None:
+            return False
+        result = role in self.filters
+        if not result:
+            _log.debug("事件 %s 被 SenderRoleFilter 拦截: role=%s", event.id, role)
+        return result
+
+
+class TextFilter(BaseFilter):
+    """仅允许消息文本包含指定关键词的事件通过。
+
+    非消息事件（通知、请求等）默认拦截。
+
+    Args:
+        *keywords: 关键词列表，任一匹配即通过
+        case_sensitive: 是否大小写敏感，默认 ``False``
+
+    Usage:
+        ``TextFilter("help")`` — 消息包含 "help"（大小写不敏感）
+        ``TextFilter("hello", case_sensitive=True)`` — 消息包含 "hello"（精确大小写）
+    """
+
+    def __init__(self, *keywords: str, case_sensitive: bool = False) -> None:
+        self.filters = list(keywords)
+        self._case_sensitive = case_sensitive
+
+    def check(self, event: "Event") -> bool:
+        data = event.data
+        message = getattr(data, "message", None)
+        if message is None:
+            return False  # 非消息事件，安全拦截
+
+        text = getattr(message, "plain_text", "")
+        if not self._case_sensitive:
+            text_lower = text.lower()
+            return any(k.lower() in text_lower for k in self.filters)
+
+        return any(k in text for k in self.filters)
+
+
+class CommandFilter(BaseFilter):
+    """仅允许消息以指定**完整命令**开头的事件通过。
+
+    使用 ``text.split()[0]`` 提取命令部分进行精确匹配。
+    适用于路由如 ``/help``、``/ban`` 等 bot 命令。
+
+    非消息事件默认拦截。
+
+    Usage:
+        ``CommandFilter("/help")`` — 匹配 ``/help`` 和 ``/help args``，**不**匹配 ``/helpme``
+        ``CommandFilter("/help", "/status")`` — 匹配 ``/help`` **或** ``/status``
+
+    See Also:
+        ``PrefixFilter`` — 如需按前缀（如所有 ``/`` 开头的消息）匹配
+    """
+
+    def __init__(self, *commands: str) -> None:
+        self.filters = list(commands)
+
+    def check(self, event: "Event") -> bool:
+        data = event.data
+        message = getattr(data, "message", None)
+        if message is None:
+            return False  # 非消息事件，安全拦截
+
+        text = getattr(message, "plain_text", "")
+        # 先取列表再判空：`"   ".split(maxsplit=1)` 返回 []，
+        # 直接 [0] 会在纯空白消息上抛 IndexError，导致回调 task 异常、事件被吞。
+        parts = text.split(maxsplit=1)
+        command = parts[0] if parts else ""
+        result = command in self.filters
+        if not result:
+            _log.debug("事件 %s 被 CommandFilter 拦截: command=%s", event.id, command)
+        return result
+
+
+class PrefixFilter(BaseFilter):
+    """仅允许消息以指定前缀开头的事件通过。
+
+    适合需要捕获所有以某字符开头的消息的场景，
+    如所有 ``/`` 开头的 bot 命令。
+
+    非消息事件默认拦截。
+
+    Usage:
+        ``PrefixFilter("/")`` — 匹配任何 ``/`` 开头的消息
+        ``PrefixFilter("!", ".")`` — 匹配 ``!`` **或** ``.`` 开头的消息
+
+    See Also:
+        ``CommandFilter`` — 如需精确匹配完整命令
+    """
+
+    def __init__(self, *prefixes: str) -> None:
+        self.filters = list(prefixes)
+
+    def check(self, event: "Event") -> bool:
+        data = event.data
+        message = getattr(data, "message", None)
+        if message is None:
+            return False  # 非消息事件，安全拦截
+
+        text = getattr(message, "plain_text", "")
+        result = any(text.startswith(prefix) for prefix in self.filters)
+        if not result:
+            _log.debug("事件 %s 被 PrefixFilter 拦截: text=%s", event.id, text)
+        return result

butterbot/sources/napcat/source/__init__.py

@@ -0,0 +1,5 @@
+from .napcat_source import NapcatSource
+
+__all__ = [
+    "NapcatSource",
+]

butterbot/sources/napcat/source/napcat_source.py

@@ -0,0 +1,58 @@
+from logging import getLogger
+from typing import Any
+
+from butterbot.core.event import Event
+from butterbot.core.source import BaseSource
+
+from ..api import (
+    NapcatApi,
+)
+from ..data import NapcatData
+from ..types import (
+    NapcatType,
+)
+
+_log = getLogger("NapcatSource")
+
+
+class NapcatSource(BaseSource):
+    """Napcat 事件源.
+
+    使用ws协议连接napcat服务器，接收并发布事件。
+    """
+
+    supported_types = NapcatType
+    config_key = "napcat"
+
+    async def on_start(self) -> None:
+        self.api.set_handler(self._process_messages)
+        await self.api.start()
+
+    async def on_stop(self) -> None:
+        await self.api.stop()
+
+    async def _process_messages(self, message: dict[str, Any]) -> None:
+        """处理接收到的消息."""
+        event: Event[NapcatData] | None = None
+
+        try:
+            # 使用 BaseDataModel 的自动分发构造
+            napcat_event = NapcatData.from_dict(message)
+            # 状态由已完成 discriminator 分发的 Data 类型提供。
+            # 这样生产路径不再同时维护一套 raw dict 分支路由。
+            napcat_type = napcat_event.event_type
+
+            if napcat_type.matches(NapcatType.ALL):
+                event = Event(data=napcat_event, status=napcat_type)
+            else:
+                _log.warning("未处理的消息类型: %s", napcat_type)
+        except Exception as e:
+            _log.error("解析消息失败: %s, 原始消息: %s", e, message)
+            return
+
+        if event is not None:
+            await self.ctx.bus.publish(self.uuid, event)
+
+    @property
+    def api(self) -> NapcatApi:
+        return self.ctx.api_ctx.get(NapcatApi, self.config_key)

butterbot/sources/napcat/types/__init__.py

@@ -0,0 +1,5 @@
+from .napcat_type import NapcatType
+
+__all__ = [
+    "NapcatType",
+]

butterbot/sources/napcat/types/napcat_type.py

@@ -0,0 +1,61 @@
+from butterbot.core.types import BaseType
+
+
+class NapcatType(BaseType):
+    """NapCat 事件类型枚举.
+
+    按 OneBot 协议 `post_type` → 二级字段组织层级结构：
+
+    - ``napcat.meta``: 元事件（lifecycle / heartbeat）
+    - ``napcat.message``: 消息事件（group / private）
+    - ``napcat.sent``: 自身消息事件（group / private）
+    - ``napcat.request``: 请求事件（friend / group）
+    - ``napcat.notice``: 通知事件（group_upload / poke / …）
+
+    大类（如 ``MESSAGE``）可匹配下属所有子类，
+    子类（如 ``GROUP_MESSAGE``）只匹配自身。
+    """
+
+    # ── 通配 ──
+    ALL = "napcat.all"
+    UNKNOWN = "napcat.unknown"
+
+    # ── 元事件 ──
+    META = "napcat.meta"
+    LIFECYCLE_META = "napcat.meta.lifecycle"
+    HEARTBEAT_META = "napcat.meta.heartbeat"
+
+    # ── 消息事件 ──
+    MESSAGE = "napcat.message"
+    GROUP_MESSAGE = "napcat.message.group"
+    PRIVATE_MESSAGE = "napcat.message.private"
+
+    # ── 自身消息 ──
+    SENT = "napcat.sent"
+    GROUP_SENT = "napcat.sent.group"
+    PRIVATE_SENT = "napcat.sent.private"
+
+    # ── 请求事件 ──
+    REQUEST = "napcat.request"
+    FRIEND_REQUEST = "napcat.request.friend"
+    GROUP_REQUEST = "napcat.request.group"
+
+    # ── 通知事件 ──
+    NOTICE = "napcat.notice"
+    GROUP_UPLOAD_NOTICE = "napcat.notice.group_upload"
+    GROUP_ADMIN_NOTICE = "napcat.notice.group_admin"
+    GROUP_DECREASE_NOTICE = "napcat.notice.group_decrease"
+    GROUP_INCREASE_NOTICE = "napcat.notice.group_increase"
+    GROUP_BAN_NOTICE = "napcat.notice.group_ban"
+    FRIEND_ADD_NOTICE = "napcat.notice.friend_add"
+    GROUP_RECALL_NOTICE = "napcat.notice.group_recall"
+    FRIEND_RECALL_NOTICE = "napcat.notice.friend_recall"
+    GROUP_EMOJI_LIKE_NOTICE = "napcat.notice.group_msg_emoji_like"
+    REACTION_NOTICE = "napcat.notice.reaction"
+    GROUP_ESSENCE_NOTICE = "napcat.notice.essence"
+    GROUP_CARD_NOTICE = "napcat.notice.group_card"
+
+    # 三级分发：notice_type=notify → sub_type
+    POKE_NOTIFY = "napcat.notice.poke"
+    LUCKY_KING_NOTIFY = "napcat.notice.lucky_king"
+    HONOR_NOTIFY = "napcat.notice.honor"

butterbot/utils/README.md

@@ -0,0 +1,15 @@
+# 工具模块
+
+## 日志初始化
+
+导入 `butterbot.utils` 不会修改根记录器或创建日志文件。应用入口需要显式调用：
+
+```python
+from butterbot.utils import setup_logging
+
+setup_logging()
+```
+
+重复调用 `setup_logging()` 会关闭并替换上一次由该函数创建的 handler，不会累积文件句柄。
+日志文件名和 `LOG_REDIRECT_RULES` 中的重定向文件名必须位于 `LOG_FILE_PATH`
+目录内；绝对路径或包含 `..` 的目录逃逸路径会直接报错。

butterbot/utils/__init__.py

@@ -0,0 +1,11 @@
+from .data_pair import DataPair
+from .logging_config import setup_logging
+from .websocket import AsyncWebSocketClient, ListenerId, MessageType
+
+__all__ = [
+    "AsyncWebSocketClient",
+    "DataPair",
+    "ListenerId",
+    "MessageType",
+    "setup_logging",
+]

butterbot/utils/data_pair.py

@@ -0,0 +1,27 @@
+from copy import copy
+from dataclasses import dataclass
+from typing import Generic, Literal
+
+from butterbot.core.data import BaseDataT
+
+
+@dataclass
+class DataPair(Generic[BaseDataT]):
+    """存储新旧数据对"""
+
+    old: BaseDataT | None = None
+    new: BaseDataT | None = None
+
+    def update(self, new_data: BaseDataT):
+        """更新数据"""
+        if self.old is None:
+            self.old = new_data
+            self.new = new_data
+        else:
+            self.old = self.new
+            self.new = new_data
+
+    def get_data(self, value: Literal["old", "new"]) -> BaseDataT:
+        """获取数据浅拷贝"""
+        data = getattr(self, value)
+        return copy(data)