feat: 添加状态监控插件和Redis原子操作支持

- 新增 `/status` 指令，展示机器人运行状态和系统指标 - 实现Redis Lua脚本支持原子化计数器操作 - 添加消息收发统计功能 - 完善文档，包括插件开发和性能优化指南 - 重构WebSocket连接池，增加健康检查机制 - 移除旧版编译脚本，优化项目结构
2026-01-23 15:54:45 +08:00
parent 489dd8c77d
commit d458413e4b
28 changed files with 1529 additions and 1177 deletions
--- a/core/api/account.py
+++ b/core/api/account.py
@@ -5,11 +5,35 @@
 状态设置等相关的 OneBot v11 API 封装。
 """
 import orjson
-from typing import Dict, Any
+from typing import Dict, Any, Type, TypeVar
+from dataclasses import is_dataclass, fields
 from .base import BaseAPI
 from models.objects import LoginInfo, VersionInfo, Status
 from ..managers.redis_manager import redis_manager

+T = TypeVar('T')
+
+def _safe_dataclass_from_dict(cls: Type[T], data: Dict[str, Any]) -> T:
+    """
+    安全地从字典创建 dataclass 实例，忽略多余的键。
+    """
+    if not data:
+        try:
+            return cls()
+        except TypeError:
+            raise ValueError(f"无法在没有数据的情况下创建 {cls.__name__} 的实例")
+
+    # 使用官方的 is_dataclass 进行检查，对 MyPyC 更友好
+    if not is_dataclass(cls):
+        raise TypeError(f"{cls.__name__} 不是一个 dataclass")
+
+    # 获取 dataclass 的所有字段名
+    known_fields = {f.name for f in fields(cls)}
+    
+    # 过滤出 dataclass 认识的键值对
+    filtered_data = {k: v for k, v in data.items() if k in known_fields}
+    
+    return cls(**filtered_data)

 class AccountAPI(BaseAPI):
    """
@@ -30,11 +54,11 @@ class AccountAPI(BaseAPI):
        if not no_cache:
            cached_data = await redis_manager.get(cache_key)
            if cached_data:
-                return LoginInfo(**orjson.loads(cached_data))
+                return _safe_dataclass_from_dict(LoginInfo, orjson.loads(cached_data))

        res = await self.call_api("get_login_info")
        await redis_manager.set(cache_key, orjson.dumps(res), ex=3600)  # 缓存 1 小时
-        return LoginInfo(**res)
+        return _safe_dataclass_from_dict(LoginInfo, res)

    async def get_version_info(self) -> VersionInfo:
        """
@@ -43,8 +67,8 @@ class AccountAPI(BaseAPI):
        Returns:
            VersionInfo: 包含 OneBot 实现版本信息的 `VersionInfo` 数据对象。
        """
-        res = await self.call_api("get_friend_list")
-        return VersionInfo(**res)
+        res = await self.call_api("get_version_info")
+        return _safe_dataclass_from_dict(VersionInfo, res)

    async def get_status(self) -> Status:
        """
@@ -54,7 +78,7 @@ class AccountAPI(BaseAPI):
            Status: 包含 OneBot 状态信息的 `Status` 数据对象。
        """
        res = await self.call_api("get_status")
-        return Status(**res)
+        return _safe_dataclass_from_dict(Status, res)

    async def bot_exit(self) -> Dict[str, Any]:
        """
@@ -162,56 +186,25 @@ class AccountAPI(BaseAPI):
        """
        return await self.call_api("clean_cache")

-    async def get_stranger_info(self, user_id: int, no_cache: bool = False) -> Any:
+    async def get_profile_like(self) -> Dict[str, Any]:
        """
-        获取陌生人信息。
+        获取个人资料的点赞信息。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_profile_like")
+
+    async def nc_get_user_status(self, user_id: int) -> Dict[str, Any]:
+        """
+        获取用户的在线状态 (NapCat 特有 API)。

        Args:
            user_id (int): 目标用户的 QQ 号。
-            no_cache (bool, optional): 是否不使用缓存。Defaults to False.

        Returns:
-            Any: 包含陌生人信息的字典或对象。
+            Dict[str, Any]: OneBot API 的响应数据。
        """
-        return await self.call_api("get_stranger_info", {"user_id": user_id, "no_cache": no_cache})
+        return await self.call_api("nc_get_user_status", {"user_id": user_id})

-    async def get_friend_list(self, no_cache: bool = False) -> list:
-        """
-        获取好友列表。
-
-        Args:
-            no_cache (bool, optional): 是否不使用缓存。Defaults to False.
-
-        Returns:
-            list: 好友列表。
-        """
-        cache_key = f"neobot:cache:get_friend_list:{self.self_id}"
-        if not no_cache:
-            cached_data = await redis_manager.get(cache_key)
-            if cached_data:
-                return orjson.loads(cached_data)
-
-        res = await self.call_api("get_friend_list")
-        await redis_manager.set(cache_key, orjson.dumps(res), ex=3600)  # 缓存 1 小时
-        return res
-
-    async def get_group_list(self, no_cache: bool = False) -> list:
-        """
-        获取群列表。
-
-        Args:
-            no_cache (bool, optional): 是否不使用缓存。Defaults to False.
-
-        Returns:
-            list: 群列表。
-        """
-        cache_key = f"neobot:cache:get_group_list:{self.self_id}"
-        if not no_cache:
-            cached_data = await redis_manager.get(cache_key)
-            if cached_data:
-                return orjson.loads(cached_data)
-
-        res = await self.call_api("get_group_list")
-        await redis_manager.set(cache_key, orjson.dumps(res), ex=3600)  # 缓存 1 小时
-        return res

--- a/core/api/base.py
+++ b/core/api/base.py
@@ -3,6 +3,7 @@ API 基础模块

 定义了 API 调用的基础接口和统一处理逻辑。
 """
+import copy
 from typing import Any, Dict, Optional, TYPE_CHECKING

 from ..utils.logger import logger
@@ -35,7 +36,32 @@ class BaseAPI:
            params = {}
        
        try:
-            logger.debug(f"调用API -> action: {action}, params: {params}")
+            # 日志记录前，对敏感或过长的参数进行处理
+            log_params = copy.deepcopy(params)
+            if 'message' in log_params:
+                if isinstance(log_params['message'], list):
+                    for segment in log_params['message']:
+                        if segment.get('type') == 'image' and 'file' in segment.get('data', {}):
+                            file_data = segment['data']['file']
+                            if file_data.startswith('data:image/'):
+                                segment['data']['file'] = f"{file_data[:50]}... (base64 truncated)"
+                elif isinstance(log_params['message'], str) and log_params['message'].startswith('data:image/'):
+                    log_params['message'] = f"{log_params['message'][:50]}... (base64 truncated)"
+
+            # 如果是发送消息的动作，则原子化地增加发送消息总数
+            if action in ["send_private_msg", "send_group_msg", "send_msg"]:
+                from ..managers.redis_manager import redis_manager
+                try:
+                    lua_script = "return redis.call('INCR', KEYS[1])"
+                    await redis_manager.execute_lua_script(
+                        script=lua_script,
+                        keys=["neobot:stats:messages_sent"],
+                        args=[]
+                    )
+                except Exception as e:
+                    logger.error(f"发送消息计数失败: {e}")
+
+            logger.debug(f"调用API -> action: {action}, params: {log_params}")
            response = await self._ws.call_api(action, params)
            logger.debug(f"API响应 <- {response}")

--- a/core/api/friend.py
+++ b/core/api/friend.py
@@ -84,3 +84,76 @@ class FriendAPI(BaseAPI):
        """
        return await self.call_api("set_friend_add_request", {"flag": flag, "approve": approve, "remark": remark})

+    async def get_friends_with_category(self) -> Dict[str, Any]:
+        """
+        获取带分类的好友列表。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_friends_with_category")
+
+    async def get_unidirectional_friend_list(self) -> Dict[str, Any]:
+        """
+        获取单向好友列表。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_unidirectional_friend_list")
+
+    async def friend_poke(self, user_id: int) -> Dict[str, Any]:
+        """
+        发送好友戳一戳。
+
+        Args:
+            user_id (int): 目标用户的 QQ 号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("friend_poke", {"user_id": user_id})
+
+    async def mark_private_msg_as_read(self, user_id: int, time: int = 0) -> Dict[str, Any]:
+        """
+        标记私聊消息为已读。
+
+        Args:
+            user_id (int): 目标用户的 QQ 号。
+            time (int, optional): 标记此时间戳之前的消息为已读。Defaults to 0 (全部标记)。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        params = {"user_id": user_id}
+        if time > 0:
+            params["time"] = time
+        return await self.call_api("mark_private_msg_as_read", params)
+
+    async def get_friend_msg_history(self, user_id: int, count: int = 20) -> Dict[str, Any]:
+        """
+        获取私聊消息历史记录。
+
+        Args:
+            user_id (int): 目标用户的 QQ 号。
+            count (int, optional): 要获取的消息数量。Defaults to 20.
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_friend_msg_history", {"user_id": user_id, "count": count})
+
+    async def forward_friend_single_msg(self, user_id: int, message_id: str) -> Dict[str, Any]:
+        """
+        转发单条好友消息。
+
+        Args:
+            user_id (int): 目标用户的 QQ 号。
+            message_id (str): 要转发的消息 ID。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("forward_friend_single_msg", {"user_id": user_id, "message_id": message_id})
+
+
--- a/core/api/group.py
+++ b/core/api/group.py
@@ -282,3 +282,183 @@ class GroupAPI(BaseAPI):
        """
        return await self.call_api("set_group_add_request", {"flag": flag, "sub_type": sub_type, "approve": approve, "reason": reason})

+    async def get_group_info_ex(self, group_id: int) -> Dict[str, Any]:
+        """
+        获取群扩展信息 (NapCat 特有 API)。
+
+        Args:
+            group_id (int): 目标群组的群号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_group_info_ex", {"group_id": group_id})
+
+    async def delete_essence_msg(self, message_id: int) -> Dict[str, Any]:
+        """
+        删除精华消息。
+
+        Args:
+            message_id (int): 目标消息的 ID。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("delete_essence_msg", {"message_id": message_id})
+
+    async def group_poke(self, group_id: int, user_id: int) -> Dict[str, Any]:
+        """
+        在群内发送 "戳一戳"。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            user_id (int): 目标成员的 QQ 号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("group_poke", {"group_id": group_id, "user_id": user_id})
+
+    async def mark_group_msg_as_read(self, group_id: int, time: int = 0) -> Dict[str, Any]:
+        """
+        标记群消息为已读。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            time (int, optional): 标记此时间戳之前的消息为已读。Defaults to 0 (全部标记)。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        params = {"group_id": group_id}
+        if time > 0:
+            params["time"] = time
+        return await self.call_api("mark_group_msg_as_read", params)
+
+    async def forward_group_single_msg(self, group_id: int, message_id: str) -> Dict[str, Any]:
+        """
+        转发单条群消息。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            message_id (str): 要转发的消息 ID。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("forward_group_single_msg", {"group_id": group_id, "message_id": message_id})
+
+    async def set_group_portrait(self, group_id: int, file: str, cache: int = 1) -> Dict[str, Any]:
+        """
+        设置群头像。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            file (str): 图片文件的路径或 URL 或 Base64。
+            cache (int, optional): 是否使用缓存 (1: 是, 0: 否)。Defaults to 1.
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("set_group_portrait", {"group_id": group_id, "file": file, "cache": cache})
+
+    async def _send_group_notice(self, group_id: int, content: str, **kwargs) -> Dict[str, Any]:
+        """
+        发送群公告。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            content (str): 公告内容。
+            **kwargs: 其他可选参数 (如 image)。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        params = {"group_id": group_id, "content": content}
+        params.update(kwargs)
+        return await self.call_api("_send_group_notice", params)
+
+    async def _get_group_notice(self, group_id: int) -> Dict[str, Any]:
+        """
+        获取群公告。
+
+        Args:
+            group_id (int): 目标群组的群号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("_get_group_notice", {"group_id": group_id})
+
+    async def _del_group_notice(self, group_id: int, notice_id: str) -> Dict[str, Any]:
+        """
+        删除群公告。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            notice_id (str): 公告 ID。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("_del_group_notice", {"group_id": group_id, "notice_id": notice_id})
+
+    async def get_group_at_all_remain(self, group_id: int) -> Dict[str, Any]:
+        """
+        获取 @全体成员 的剩余次数。
+
+        Args:
+            group_id (int): 目标群组的群号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_group_at_all_remain", {"group_id": group_id})
+
+    async def get_group_system_msg(self) -> Dict[str, Any]:
+        """
+        获取群系统消息。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_group_system_msg")
+
+    async def get_group_shut_list(self, group_id: int) -> Dict[str, Any]:
+        """
+        获取群禁言列表。
+
+        Args:
+            group_id (int): 目标群组的群号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("get_group_shut_list", {"group_id": group_id})
+
+    async def set_group_remark(self, group_id: int, remark: str) -> Dict[str, Any]:
+        """
+        设置群备注。
+
+        Args:
+            group_id (int): 目标群组的群号。
+            remark (str): 要设置的备注。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("set_group_remark", {"group_id": group_id, "remark": remark})
+
+    async def set_group_sign(self, group_id: int) -> Dict[str, Any]:
+        """
+        设置群签到。
+
+        Args:
+            group_id (int): 目标群组的群号。
+
+        Returns:
+            Dict[str, Any]: OneBot API 的响应数据。
+        """
+        return await self.call_api("set_group_sign", {"group_id": group_id})
+
+
--- a/core/api/media.py
+++ b/core/api/media.py
@@ -37,3 +37,13 @@ class MediaAPI(BaseAPI):
        :return: OneBot v11标准响应
        """
        return await self.call_api(action="get_image", params={"file": file})
+
+    async def get_file(self, file_id: str) -> Dict[str, Any]:
+        """
+        获取文件信息
+
+        :param file_id: 文件ID
+        :return: OneBot v11标准响应
+        """
+        return await self.call_api(action="get_file", params={"file_id": file_id})
+