概览

约 1299 字大约 4 分钟

2025-09-28

🚀 概述

UnifiedRegistry 是 NCatBot 的现代化插件系统核心，提供统一的命令注册和过滤器管理功能。它采用声明式设计，支持现代化的命令行参数解析，让插件开发变得简单而强大。

✨ 核心特性

🎯 统一注册管理

命令注册: 使用装饰器轻松注册命令
过滤器系统: 灵活的权限控制和消息过滤
参数处理: 智能的参数解析和类型转换

🔧 现代化命令行解析

多种选项格式: 支持 -v, --verbose, --env=prod
引用字符串: 支持 "包含空格的参数"
非文本元素: 智能处理图片、@用户等消息元素

🛡️ 智能过滤器

内置过滤器: 群聊、私聊、管理员权限等
自定义过滤器: 支持自定义过滤逻辑
过滤器组合: 多个过滤器可以组合使用

🚀 最小示例

from ncatbot.plugin_system import NcatBotPlugin
from ncatbot.plugin_system import command_registry
from ncatbot.plugin_system import group_filter, admin_filter
from ncatbot.plugin_system import option, param
from ncatbot.core.event import BaseMessageEvent
from ncatbot.utils import get_log
LOG = get_log(__name__)

class MyPlugin(NcatBotPlugin):
    name = "MyPlugin"
    version = "1.0.0"
    
    async def on_load(self):
        pass

    # 简单命令（注意：除self外的所有参数必须有类型注解）
    @command_registry.command("hello")
    async def hello_cmd(self, event: BaseMessageEvent):
        await event.reply("Hello, World!")
    
    # 带权限的命令
    @group_filter
    @command_registry.command("kick")
    async def kick_cmd(self, event: BaseMessageEvent, user_id: str):
        await event.reply(f"踢出用户: {user_id}")
    
    # 复杂参数命令
    @admin_filter
    @command_registry.command("deploy")
    @option(short_name="v", long_name="verbose", help="详细输出")
    @param(name="env", default="dev", help="部署环境")
    async def deploy_cmd(self, event: BaseMessageEvent, app_name: str, env: str = "dev", verbose: bool = False):
        result = f"部署 {app_name} 到 {env} 环境"
        if verbose:
            result += " (详细模式)"
        await event.reply(result)

结构图

高层组件关系（Component）

要点：

事件由 EventBus 分发到 UnifiedRegistryPlugin，随后按“预处理 → 分词 → 解析 → 过滤 → 绑定 → 执行”的主链路推进。
命令与过滤器均通过注册表统一管理：command_registry 与 filter_registry。
帮助与错误处理贯穿各阶段，确保良好的开发与使用体验。