feat: 重构核心架构，增强类型安全与插件管理

本次提交对核心模块进行了深度重构，引入 Pydantic 增强配置管理的类型安全性，并全面优化了插件管理系统。主要变更详情： 1. 核心架构与配置 - 重构配置加载模块：引入 Pydantic 模型 (`core/config_models.py`)，提供严格的配置项类型检查、验证及默认值管理。 - 统一模块结构：规范化模块导入路径，移除冗余的 `__init__.py` 文件，提升项目结构的清晰度。 - 性能优化：集成 Redis 缓存支持 (`RedisManager`)，有效降低高频 API 调用开销，提升响应速度。 2. 插件系统升级 - 实现热重载机制：新增插件文件变更监听功能，支持开发过程中自动重载插件，提升开发效率。 - 优化生命周期管理：改进插件加载与卸载逻辑，支持精确卸载指定插件及其关联的命令、事件处理器和定时任务。 3. 功能特性增强 - 新增媒体 API：引入 `MediaAPI` 模块，封装图片、语音等富媒体资源的获取与处理接口。 - 完善权限体系：重构权限管理系统，实现管理员与操作员的分级控制，支持更细粒度的命令权限校验。 4. 代码质量与稳定性 - 全面类型修复：解决 `mypy` 静态类型检查发现的大量类型错误（包括 `CommandManager`、`EventFactory` 及 `Bot` API 签名不匹配问题）。 - 增强错误处理：优化消息处理管道的异常捕获机制，完善关键路径的日志记录，提升系统运行稳定性。
2026-01-08 23:42:53 +08:00
parent c2de743098
commit 5d07a84283
35 changed files with 829 additions and 608 deletions
--- a/plugins/init.py
+++ b/plugins/init.py
--- a/plugins/admin.py
+++ b/plugins/admin.py
@@ -1,74 +1,94 @@
-"""
-管理员管理插件
-
-提供通过聊天指令动态添加或移除机器人管理员的功能。
-"""
-from core.bot import Bot
-from core.managers.command_manager import matcher
-from core.managers.admin_manager import admin_manager
+from core.handlers.event_handler import MessageHandler
+from core.managers import command_manager, permission_manager
+from core.permission import Permission
 from models.events.message import MessageEvent

+# 更新插件元信息以包含OP管理
 __plugin_meta__ = {
-    "name": "管理员管理",
-    "description": "管理机器人的全局管理员",
+    "name": "权限管理",
+    "description": "管理机器人的管理员和操作员",
    "usage": (
-        "/admin list - 列出所有管理员\n"
-        "/admin add <QQ号> - 添加管理员\n"
-        "/admin remove <QQ号> - 移除管理员"
+        "/admin list - 列出所有管理员和操作员\n"
+        "/admin add_admin <QQ号> - 添加管理员\n"
+        "/admin remove_admin <QQ号> - 移除管理员\n"
+        "/admin add_op <QQ号> - 添加操作员\n"
+        "/admin remove_op <QQ号> - 移除操作员"
    ),
 }


-@matcher.command("admin", permission=MessageEvent.ADMIN)
-async def admin_command_handler(bot: Bot, event: MessageEvent, args: list[str]):
+@command_manager.command("admin", permission=Permission.ADMIN)
+async def admin_management(event: MessageEvent, args: str):
    """
-    处理 /admin 指令
-
-    :param bot: Bot 实例
-    :param event: 消息事件实例
-    :param args: 指令参数列表
+    处理所有权限管理相关的命令。
    """
-    if not args:
-        await event.reply(__plugin_meta__["usage"])
+    parts = args.split()
+    if not parts:
+        await event.reply(f"用法不正确。\n\n{__plugin_meta__['usage']}")
        return

-    action = args[0].lower()
+    subcommand = parts[0].lower()

-    if action == "list":
-        admins = await admin_manager.get_all_admins()
-        if not admins:
-            await event.reply("当前没有设置任何管理员。")
-            return
-        
-        admin_list_text = "\n".join(str(admin_id) for admin_id in admins)
-        await event.reply(f"当前管理员列表 ({len(admins)}):\n{admin_list_text}")
+    if subcommand == "list":
+        await list_permissions(event)
        return

-    if action in ("add", "remove"):
-        if len(args) < 2 or not args[1].isdigit():
-            await event.reply("参数错误，请提供一个有效的 QQ 号。\n示例: /admin add 123456")
-            return
+    # 处理需要QQ号的命令
+    if len(parts) < 2 or not parts[1].isdigit():
+        await event.reply(f"请提供有效的用户QQ号。\n用法: /admin {subcommand} <QQ号>")
+        return

-        try:
-            user_id = int(args[1])
-        except ValueError:
-            await event.reply("无效的 QQ 号，请输入纯数字。")
-            return
+    try:
+        target_user_id = int(parts[1])
+    except ValueError:
+        await event.reply("无效的QQ号。")
+        return

-        if action == "add":
-            success = await admin_manager.add_admin(user_id)
-            if success:
-                await event.reply(f"成功添加管理员: {user_id}")
-            else:
-                await event.reply(f"管理员 {user_id} 已存在，无需重复添加。")
-            return
-        
-        elif action == "remove":
-            success = await admin_manager.remove_admin(user_id)
-            if success:
-                await event.reply(f"成功移除管理员: {user_id}")
-            else:
-                await event.reply(f"管理员 {user_id} 不存在。")
-            return
+    # 安全检查
+    if target_user_id == event.user_id:
+        await event.reply("你不能操作自己的权限。")
+        return
+    if target_user_id == event.self_id:
+        await event.reply("你不能操作机器人自身的权限。")
+        return

-    await event.reply(f"未知的指令: {action}\n\n{__plugin_meta__['usage']}")
+    # 根据子命令分发
+    if subcommand == "add_admin":
+        permission_manager.set_user_permission(target_user_id, Permission.ADMIN)
+        await event.reply(f"已成功添加管理员：{target_user_id}")
+    elif subcommand == "remove_admin":
+        permission_manager.set_user_permission(target_user_id, Permission.USER)
+        await event.reply(f"已成功移除管理员：{target_user_id}")
+    elif subcommand == "add_op":
+        permission_manager.set_user_permission(target_user_id, Permission.OP)
+        await event.reply(f"已成功添加操作员：{target_user_id}")
+    elif subcommand == "remove_op":
+        permission_manager.set_user_permission(target_user_id, Permission.USER)
+        await event.reply(f"已成功移除操作员：{target_user_id}")
+    else:
+        await event.reply(f"未知的子命令 '{subcommand}'。\n\n{__plugin_meta__['usage']}")
+
+
+async def list_permissions(event: MessageEvent):
+    """
+    列出所有具有特殊权限（管理员和操作员）的用户。
+    """
+    permissions = permission_manager.get_all_user_permissions()
+    if not permissions:
+        await event.reply("当前没有配置任何特殊权限的用户。")
+        return
+
+    admins = {uid for uid, p in permissions.items() if p == 'admin'}
+    ops = {uid for uid, p in permissions.items() if p == 'op'}
+
+    reply_msg = "当前权限列表：\n"
+    if admins:
+        reply_msg += "--- 管理员 ---\n"
+        for user_id in admins:
+            reply_msg += f"- {user_id}\n"
+    if ops:
+        reply_msg += "--- 操作员 ---\n"
+        for user_id in ops:
+            reply_msg += f"- {user_id}\n"
+
+    await event.reply(reply_msg.strip())
--- a/plugins/bili_parser.py
+++ b/plugins/bili_parser.py
@@ -1,13 +1,17 @@
 # -*- coding: utf-8 -*-
 import re
 import json
-import requests
+import httpx
 from bs4 import BeautifulSoup
 from typing import Optional, Dict, Any
+from cachetools import TTLCache

 from core.utils.logger import logger
 from core.managers.command_manager import matcher
-from models import MessageEvent, MessageSegment
+from models.events.message import MessageEvent, MessageSegment
+
+# 创建一个TTL缓存，最大容量100，缓存时间60秒
+processed_messages: TTLCache[Any, bool] = TTLCache(maxsize=100, ttl=60)

 __plugin_meta__ = {
    "name": "bili_parser",
@@ -19,6 +23,9 @@ HEADERS = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
 }

+# 创建可复用的异步HTTP客户端
+async_client = httpx.AsyncClient(headers=HEADERS, follow_redirects=False, timeout=10)
+

 def format_count(num: int) -> str:
    if not isinstance(num, int):
@@ -36,18 +43,18 @@ def format_duration(seconds: int) -> str:
    return f"{minutes:02d}:{seconds:02d}"


-def get_real_url(short_url: str) -> Optional[str]:
+async def get_real_url(short_url: str) -> Optional[str]:
    try:
-        response = requests.head(short_url, headers=HEADERS, allow_redirects=False, timeout=5)
+        response = await async_client.head(short_url)
        if response.status_code == 302:
            return response.headers.get('Location')
-    except requests.RequestException as e:
-        print(f"获取真实URL失败: {e}")
+    except httpx.RequestError as e:
+        logger.error(f"获取真实URL失败: {e}")
    return None

-def parse_video_info(video_url: str) -> Optional[Dict[str, Any]]:
+async def parse_video_info(video_url: str) -> Optional[Dict[str, Any]]:
    try:
-        response = requests.get(video_url, headers=HEADERS, timeout=5)
+        response = await async_client.get(video_url, follow_redirects=True)
        response.raise_for_status()
        soup = BeautifulSoup(response.text, 'html.parser')

@@ -55,7 +62,14 @@ def parse_video_info(video_url: str) -> Optional[Dict[str, Any]]:
        if not script_tag:
            return None
            
-        json_str = re.search(r'window\.__INITIAL_STATE__\s*=\s*(\{.*?\});', script_tag.string).group(1)
+        script_tag_content = script_tag.string
+        if not script_tag_content:
+            return None
+
+        match = re.search(r'window\.__INITIAL_STATE__\s*=\s*(\{.*?\});', script_tag_content)
+        if not match:
+            return None
+        json_str = match.group(1)
        data = json.loads(json_str)
        
        video_data = data.get('videoData', {})
@@ -90,12 +104,12 @@ def parse_video_info(video_url: str) -> Optional[Dict[str, Any]]:
            "followers": up_data.get('fans', 0),
        }

-    except (requests.RequestException, KeyError, AttributeError, json.JSONDecodeError) as e:
-        print(f"解析视频信息失败: {e}")
+    except (httpx.RequestError, KeyError, AttributeError, json.JSONDecodeError) as e:
+        logger.error(f"解析视频信息失败: {e}")
    
    return None

-def get_direct_video_url(video_url: str) -> Optional[str]:
+async def get_direct_video_url(video_url: str) -> Optional[str]:
    """
    调用第三方API解析B站视频直链
    :param video_url: B站视频的完整URL
@@ -103,12 +117,12 @@ def get_direct_video_url(video_url: str) -> Optional[str]:
    """
    api_url = f"https://api.mir6.com/api/bzjiexi?url={video_url}&type=json"
    try:
-        response = requests.get(api_url, headers=HEADERS, timeout=10)
+        response = await async_client.get(api_url)
        response.raise_for_status()
        data = response.json()
        if data.get("code") == 200 and data.get("data"):
            return data["data"][0].get("video_url")
-    except (requests.RequestException, json.JSONDecodeError, KeyError, IndexError) as e:
+    except (httpx.RequestError, json.JSONDecodeError, KeyError, IndexError) as e:
        logger.error(f"[bili_parser] 调用第三方API解析视频失败: {e}")
    return None

@@ -121,6 +135,15 @@ async def handle_bili_share(event: MessageEvent):
    处理消息，检测B站分享链接（JSON卡片或文本链接）并进行解析。
    :param event: 消息事件对象
    """
+    # 消息去重
+    if event.message_id in processed_messages:
+        return
+    processed_messages[event.message_id] = True
+    
+    # 忽略机器人自己发送的消息，防止无限循环
+    if event.user_id == event.self_id:
+        return
+        
    url_to_process = None
    
    # 1. 优先解析JSON卡片中的短链接
@@ -161,7 +184,7 @@ async def process_bili_link(event: MessageEvent, url: str):
    :param url: 待处理的B站链接
    """
    if "b23.tv" in url:
-        real_url = get_real_url(url)
+        real_url = await get_real_url(url)
        if not real_url:
            logger.error(f"[bili_parser] 无法从 {url} 获取真实URL。")
            await event.reply("无法解析B站短链接。")
@@ -169,58 +192,28 @@ async def process_bili_link(event: MessageEvent, url: str):
    else:
        real_url = url.split('?')[0]

-    video_info = parse_video_info(real_url)
+    video_info = await parse_video_info(real_url)
    if not video_info:
        logger.error(f"[bili_parser] 无法从 {real_url} 解析视频信息。")
        await event.reply("无法获取视频信息，可能是B站接口变动或视频不存在。")
        return

-    # 检查视频时长
-    if video_info['duration'] > 300:  # 5分钟 = 300秒
-        video_message = "视频时长超过5分钟，不进行解析。"
-    else:
-        direct_url = get_direct_video_url(real_url)
-        if direct_url:
-            video_message = MessageSegment.video(direct_url)
-        else:
-            video_message = "视频解析失败，无法获取直链。"
+    title = video_info.get("title", "未知标题")
+    owner_name = video_info.get("owner_name", "未知UP主")
+    cover_url = video_info.get("cover_url")
+    bvid = video_info.get("bvid", "N/A")
+    play_count = format_count(video_info.get("play", 0))
+    like_count = format_count(video_info.get("like", 0))

-    text_message = (
-        f"BiliBili 视频解析\n"
-        f"--------------------\n"
-        f" UP主: {video_info['owner_name']}\n"
-        f" 粉丝: {format_count(video_info['followers'])}\n"
-        f"--------------------\n"
-        f" 标题: {video_info['title']}\n"
-        f" BV号: {video_info['bvid']}\n"
-        f" 时长: {format_duration(video_info['duration'])}\n"
-        f"--------------------\n"
-        f" 数据:\n"
-        f"   播放: {format_count(video_info['play'])}\n"
-        f"   点赞: {format_count(video_info['like'])}\n"
-        f"   投币: {format_count(video_info['coin'])}\n"
-        f"   收藏: {format_count(video_info['favorite'])}\n"
-        f"   转发: {format_count(video_info['share'])}\n"
-        f"   B站链接: {url}"
+    text_part = (
+        f"标题: {title}\n"
+        f"UP主: {owner_name}\n"
+        f"BV: {bvid} | ▶️ {play_count} | 👍 {like_count}"
    )
-    
-    image_message_segment = [
-        MessageSegment.text("B站封面："),
-        MessageSegment.image(video_info['cover_url'])
-    ]

-    up_info_segment = [
-        MessageSegment.text("UP主头像："),
-        MessageSegment.image(video_info['owner_avatar'])
-    ]
-
-    nodes = [
-        event.bot.build_forward_node(user_id=event.self_id, nickname="B站视频解析", message=text_message),
-        event.bot.build_forward_node(user_id=event.self_id, nickname="B站视频解析", message=image_message_segment),
-        event.bot.build_forward_node(user_id=event.self_id, nickname="B站视频解析", message=up_info_segment),
-        event.bot.build_forward_node(user_id=event.self_id, nickname="B站视频解析", message=video_message)
-    ]
+    reply_message = [MessageSegment.from_text(text_part)]
+    if cover_url:
+        reply_message.append(MessageSegment.image(cover_url))
    
-    logger.success(f"[bili_parser] 成功解析视频信息并准备以聊天记录形式回复: {video_info['title']}")
-    # 使用更通用的 send_forwarded_messages 方法，自动判断私聊或群聊
-    await event.bot.send_forwarded_messages(target=event, nodes=nodes)
+    logger.success(f"[bili_parser] 成功解析视频信息并准备回复: {title}")
+    await event.reply(reply_message)
--- a/plugins/broadcast.py
+++ b/plugins/broadcast.py
@@ -8,8 +8,8 @@
 """
 import asyncio
 from core.managers.command_manager import matcher
-from models import MessageEvent, PrivateMessageEvent
-from core.managers.permission_manager import ADMIN
+from models.events.message import MessageEvent, PrivateMessageEvent
+from core.permission import Permission
 from core.utils.logger import logger

 # --- 会话状态管理 ---
@@ -24,7 +24,7 @@ def cleanup_session(user_id: int):
        del broadcast_sessions[user_id]
        logger.info(f"[Broadcast] 会话 {user_id} 已超时，自动取消。")

-@matcher.command("broadcast", "广播", permission=ADMIN)
+@matcher.command("broadcast", "广播", permission=Permission.ADMIN)
 async def broadcast_start(event: MessageEvent):
    """
    广播指令的入口，启动一个等待用户消息的会话。
@@ -92,7 +92,7 @@ async def handle_broadcast_content(event: MessageEvent):
        nodes_to_send = [
            bot.build_forward_node(
                user_id=event.user_id,
-                nickname=event.sender.nickname,
+                nickname=event.sender.nickname if event.sender else "未知用户",
                message=message_to_broadcast
            )
        ]
--- a/plugins/code_py.py
+++ b/plugins/code_py.py
@@ -5,8 +5,8 @@ import asyncio
 from typing import Dict

 from core.managers.command_manager import matcher
-from models import MessageEvent
-from core.managers.permission_manager import ADMIN
+from models.events.message import MessageEvent
+from core.permission import Permission
 from core.utils.logger import logger

 __plugin_meta__ = {
@@ -30,7 +30,7 @@ async def reply_as_forward(event: MessageEvent, input_code: str, output_result:
    nodes = [
        bot.build_forward_node(
            user_id=event.user_id, 
-            nickname=event.sender.nickname or str(event.user_id), 
+            nickname=event.sender.nickname if event.sender else str(event.user_id), 
            message=f"--- Your Code ---\n{input_code}"
        ),
        bot.build_forward_node(
@@ -97,7 +97,7 @@ def normalize_code(code: str) -> str:
    return code.strip()


-@matcher.command("py", "python", "code_py", permission=ADMIN)
+@matcher.command("py", "python", "code_py", permission=Permission.ADMIN)
 async def code_py_main(event: MessageEvent, args: list[str]):
    """
    /py 命令的主入口。
--- a/plugins/echo.py
+++ b/plugins/echo.py
@@ -5,7 +5,7 @@ Echo 与交互插件
 """
 from core.managers.command_manager import matcher
 from core.bot import Bot
-from models import MessageEvent
+from models.events.message import MessageEvent

 __plugin_meta__ = {
    "name": "echo",
--- a/plugins/forward_test.py
+++ b/plugins/forward_test.py
@@ -3,7 +3,7 @@
 """
 from core.managers.command_manager import matcher
 from core.bot import Bot
-from models import MessageEvent
+from models.events.message import MessageEvent
 from models.message import MessageSegment

 __plugin_meta__ = {
@@ -22,14 +22,15 @@ async def handle_forward_test(bot: Bot, event: MessageEvent, args: list[str]):
    :param args: 指令参数
    """
    # 1. 构建消息节点列表
+    nickname = event.sender.nickname if event.sender else "未知用户"
    nodes = [
        bot.build_forward_node(user_id=event.self_id, nickname="机器人", message="你要的furry来了"),
-        bot.build_forward_node(user_id=event.user_id, nickname=event.sender.nickname, message="让我看看"),
+        bot.build_forward_node(user_id=event.user_id, nickname=nickname, message="让我看看"),
        bot.build_forward_node(
            user_id=event.self_id, 
            nickname="机器人", 
            message=[
-                MessageSegment.text("你要的福瑞图"),
+                MessageSegment.from_text("你要的福瑞图"),
                MessageSegment.image("https://api.furry.ist/furry-img/")
            ]
        )
--- a/plugins/jrcd.py
+++ b/plugins/jrcd.py
@@ -10,7 +10,7 @@ from datetime import datetime
 from core.bot import Bot
 from core.managers.command_manager import matcher
 from core.utils.executor import run_in_thread_pool
-from models import MessageEvent, MessageSegment
+from models.events.message import MessageEvent, MessageSegment

 __plugin_meta__ = {
    "name": "jrcd",
@@ -79,14 +79,17 @@ async def handle_jrcd(bot: Bot, event: MessageEvent, args: list[str]):
    """
    user_id = event.user_id
    jrcd = await run_in_thread_pool(get_jrcd, user_id)
-    msg = [MessageSegment.at(user_id)]
+    
+    msg_text = ""
    if jrcd <= 9:
-        msg.append(MessageSegment.text(random.choice(JRCDMSG_1) % jrcd))
+        msg_text = random.choice(JRCDMSG_1) % jrcd
    elif jrcd <= 19:
-        msg.append(MessageSegment.text(random.choice(JRCDMSG_2) % jrcd))
+        msg_text = random.choice(JRCDMSG_2) % jrcd
    else:
-        msg.append(MessageSegment.text(random.choice(JRCDMSG_3) % jrcd))
-    await event.reply(msg)
+        msg_text = random.choice(JRCDMSG_3) % jrcd
+        
+    reply_segments = [MessageSegment.at(user_id), MessageSegment.from_text(msg_text)]
+    await event.reply(reply_segments)


@matcher.command("bbcd")
@@ -118,29 +121,31 @@ async def handle_bbcd(bot: Bot, event: MessageEvent, args: list[str]):

    jrcz = jrcd1 - jrcd2

-    msg = [
-        MessageSegment.at(user_id1),
-        MessageSegment.text("你的长度比"),
-        MessageSegment.at(user_id2),
-    ]
-
+    text_part = ""
    if jrcz == 0:
-        msg.append(MessageSegment.text("一样长。"))
-        msg.append(MessageSegment.text(random.choice(BBCDMSG7)))
+        text_part = f" 一样长。{random.choice(BBCDMSG7)}"
    elif jrcz > 0:
-        msg.append(MessageSegment.text("长" + str(jrcz) + "cm。"))
+        text_part = f" 长{jrcz}cm。"
        if jrcz <= 9:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG1)))
+            text_part += random.choice(BBCDMSG1)
        elif jrcz <= 19:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG2)))
+            text_part += random.choice(BBCDMSG2)
        else:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG3)))
-    elif jrcz < 0:
-        msg.append(MessageSegment.text("短" + str(abs(jrcz)) + "cm。"))
+            text_part += random.choice(BBCDMSG3)
+    else:  # jrcz < 0
+        text_part = f" 短{abs(jrcz)}cm。"
        if jrcz >= -9:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG4)))
+            text_part += random.choice(BBCDMSG4)
        elif jrcz >= -19:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG5)))
+            text_part += random.choice(BBCDMSG5)
        else:
-            msg.append(MessageSegment.text(random.choice(BBCDMSG6)))
-    await event.reply(msg)
+            text_part += random.choice(BBCDMSG6)
+
+    segments = [
+        MessageSegment.at(user_id1),
+        MessageSegment.from_text(" 你的长度比 "),
+        MessageSegment.at(user_id2),
+        MessageSegment.from_text(text_part),
+    ]
+            
+    await event.reply(segments)
--- a/plugins/thpic.py
+++ b/plugins/thpic.py
@@ -7,7 +7,7 @@ thpic 插件

 from core.bot import Bot
 from core.managers.command_manager import matcher
-from models import MessageEvent, MessageSegment
+from models.events.message import MessageEvent, MessageSegment

 __plugin_meta__ = {
    "name": "thpic",
@@ -26,6 +26,6 @@ async def handle_echo(bot: Bot, event: MessageEvent, args: list[str]):
    :param args: 指令参数列表（未使用）。
    """
    try:
-        await event.reply(MessageSegment.image("https://img.paulzzh.com/touhou/random"))
+        await event.reply(str(MessageSegment.image("https://img.paulzzh.com/touhou/random")))
    except Exception as e:
-        await event.reply("报错了。。。" + e)
+        await event.reply(f"报错了。。。{e}")