5f16c288bf
* 滚木 * feat: 重构核心架构，增强类型安全与插件管理 本次提交对核心模块进行了深度重构，引入 Pydantic 增强配置管理的类型安全性，并全面优化了插件管理系统。 主要变更详情： 1. 核心架构与配置 - 重构配置加载模块：引入 Pydantic 模型 (`core/config_models.py`)，提供严格的配置项类型检查、验证及默认值管理。 - 统一模块结构：规范化模块导入路径，移除冗余的 `__init__.py` 文件，提升项目结构的清晰度。 - 性能优化：集成 Redis 缓存支持 (`RedisManager`)，有效降低高频 API 调用开销，提升响应速度。 2. 插件系统升级 - 实现热重载机制：新增插件文件变更监听功能，支持开发过程中自动重载插件，提升开发效率。 - 优化生命周期管理：改进插件加载与卸载逻辑，支持精确卸载指定插件及其关联的命令、事件处理器和定时任务。 3. 功能特性增强 - 新增媒体 API：引入 `MediaAPI` 模块，封装图片、语音等富媒体资源的获取与处理接口。 - 完善权限体系：重构权限管理系统，实现管理员与操作员的分级控制，支持更细粒度的命令权限校验。 4. 代码质量与稳定性 - 全面类型修复：解决 `mypy` 静态类型检查发现的大量类型错误（包括 `CommandManager`、`EventFactory` 及 `Bot` API 签名不匹配问题）。 - 增强错误处理：优化消息处理管道的异常捕获机制，完善关键路径的日志记录，提升系统运行稳定性。 * feat: 添加测试用例并优化代码结构 refactor(permission_manager): 调整初始化顺序和逻辑 fix(admin_manager): 修复初始化逻辑和目录创建问题 feat(ws): 优化Bot实例初始化条件 feat(message): 增强MessageSegment功能并添加测试 feat(events): 支持字符串格式的消息解析 test: 添加核心功能测试用例 refactor(plugin_manager): 改进插件路径处理 style: 清理无用导入和代码 chore: 更新依赖项 * refactor(handler): 移除TYPE_CHECKING并直接导入Bot类 简化类型注解，直接导入Bot类而非使用TYPE_CHECKING条件导入，提高代码可读性和维护性 * fix(command_manager): 修复插件卸载时元信息移除不精确的问题 修复 CommandManager 中 unload_plugin 方法移除插件元信息时使用 startswith 导致可能误删其他插件的问题，改为精确匹配 同时调整相关测试用例验证精确匹配行为 * refactor: 清理未使用的导入和更新文档结构 docs: 添加config_models.py到项目结构文档 docs: 调整数据目录位置到core/data下 docs: 更新权限管理器文档描述 * 文档更新 * 更新thpic插件 支持一次返回多张图 --------- Co-authored-by: baby20162016 <2185823427@qq.com>
4.7 KiB
4.7 KiB
核心概念：单例管理器
在 core/managers/ 目录下，存放着一系列全局唯一的管理器（Managers）。它们是 NEO Bot Framework 功能的核心实现，负责处理事件、管理权限、加载插件等关键任务。
理解这些管理器的职责，有助于您更好地利用框架提供的能力，并进行更高级的开发。
设计模式：单例 (Singleton)
框架中所有的管理器都采用了单例设计模式。这意味着在整个应用程序的生命周期中，每个管理器类只会存在一个实例。
为什么使用单例？
- 全局访问点: 任何模块（尤其是插件）都可以方便地导入并使用同一个管理器实例，无需手动传递。
- 状态共享: 管理器内部维护的状态（如已注册的命令、用户权限列表）是全局共享和一致的。
- 资源统一管理: 对于像 Redis 连接这样的资源，单例模式确保了全局只有一个连接池，避免了资源的浪费和冲突。
框架在 core/utils/singleton.py 中提供了一个 Singleton 基类，所有管理器都继承自它，以轻松实现单例模式。
核心管理器介绍
1. CommandManager (全局实例: matcher)
- 文件:
core/managers/command_manager.py - 全局实例:
from core.managers.command_manager import matcher - 核心职责:
- 事件处理中枢: 它是事件流转的核心，负责接收所有类型的事件，并将其分发给相应的底层处理器。
- 装饰器提供者: 为插件提供了
@matcher.command(),@matcher.on_notice()等一系列装饰器，用于注册事件处理器。 - 指令匹配: 内部维护了一个指令注册表，能够根据消息内容匹配到对应的处理函数。
matcher 是插件开发者最常打交道的管理器。
2. PermissionManager (全局实例: permission_manager)
- 文件:
core/managers/permission_manager.py - 全局实例:
from core.managers.permission_manager import permission_manager - 核心职责:
- 权限定义与检查: 定义了
ADMIN,OP,USER等权限等级，并提供了check_permission方法来验证用户权限。 - 数据持久化: 负责从
core/data/permissions.json文件中加载和保存用户权限设置。 - 与
AdminManager联动: 在检查权限和获取所有用户权限时，会自动合并机器人管理员（来自AdminManager）的数据，将其识别为最高权限ADMIN。
- 权限定义与检查: 定义了
3. AdminManager (全局实例: admin_manager)
- 文件:
core/managers/admin_manager.py - 全局实例:
from core.managers.admin_manager import admin_manager - 核心职责:
- 管理员管理: 提供
add_admin,remove_admin,is_admin等接口，用于管理机器人的超级管理员列表。 - 数据同步: 实现了内存、
core/data/admin.json文件以及 Redis 缓存之间的数据同步，确保管理员列表的一致性和高效查询。
- 管理员管理: 提供
4. PluginManager
- 文件:
core/managers/plugin_manager.py - 核心职责:
- 插件加载: 负责扫描
plugins/目录，导入所有合法的插件模块。 - 元数据提取: 读取插件文件中定义的
__plugin_meta__字典，用于/help指令等功能。 - 热重载支持:
load_all_plugins函数被main.py中的文件监控服务调用，以实现插件的热重载。
- 插件加载: 负责扫描
此管理器通常在后台工作，开发者较少直接与其交互。
5. RedisManager (全局实例: redis_manager)
- 文件:
core/managers/redis_manager.py - 全局实例:
from core.managers.redis_manager import redis_manager - 核心职责:
- 连接管理: 负责初始化和管理与 Redis 服务器的异步连接。
- 提供实例: 通过
redis_manager.redis属性，为其他模块提供一个可用的redis客户端实例。
如何在插件中使用管理器
在您的插件中，只需通过 import 语句导入相应管理器的全局实例即可使用。
示例: 在插件中检查用户是否为管理员。
# plugins/my_plugin.py
from core.managers.command_manager import matcher
from core.managers.permission_manager import permission_manager, ADMIN
from models.events.message import MessageEvent
@matcher.command("secret")
async def secret_command(event: MessageEvent):
# 使用 permission_manager 检查用户权限
is_admin = await permission_manager.check_permission(event.user_id, ADMIN)
if is_admin:
await event.reply("这是一个只有管理员能看到的秘密。")
else:
await event.reply("抱歉，您没有权限执行此命令。")