增强命令系统使用指南

概述

增强命令系统是MoFox-bot插件系统的一个扩展，让命令的定义和使用变得更加简单直观。你不再需要编写复杂的正则表达式，只需要定义命令名、别名和参数处理逻辑即可。

核心特性

无需正则表达式：只需定义命令名和别名
自动参数解析：提供CommandArgs类处理参数
命令别名支持：一个命令可以有多个别名
优先级控制：支持命令优先级设置
聊天类型限制：可限制命令在群聊或私聊中使用
消息拦截：可选择是否拦截消息进行后续处理

快速开始

1. 创建基础命令

python

from src.plugin_system import PlusCommand, CommandArgs, ChatType
from typing import Tuple, Optional

class EchoCommand(PlusCommand):
    """Echo命令示例"""
    
    command_name = "echo"
    command_description = "回显命令"
    command_aliases = ["say", "repeat"]  # 可选：命令别名
    priority = 5  # 可选：优先级，数字越大优先级越高
    chat_type_allow = ChatType.ALL  # 可选：ALL, GROUP, PRIVATE
    intercept_message = True  # 可选：是否拦截消息

    async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
        """执行命令"""
        if args.is_empty():
            await self.send_text("❓ 请提供要回显的内容\\n用法: /echo <内容>")
            return True, "参数不足", True
        
        content = args.get_raw()
        await self.send_text(f"🔊 {content}")
        
        return True, "Echo命令执行成功", True

2. 在插件中注册命令

python

from src.plugin_system import BasePlugin, create_plus_command_adapter, register_plugin

@register_plugin
class MyPlugin(BasePlugin):
    plugin_name = "my_plugin"
    enable_plugin = True
    dependencies = []
    python_dependencies = []
    config_file_name = "config.toml"

    def get_plugin_components(self):
        components = []
        
        # 使用工厂函数创建适配器
        echo_adapter = create_plus_command_adapter(EchoCommand)
        components.append((EchoCommand.get_command_info(), echo_adapter))
        
        return components

CommandArgs 类详解

CommandArgs类提供了丰富的参数处理功能：

基础方法

python

# 获取原始参数字符串
raw_text = args.get_raw()

# 获取解析后的参数列表（按空格分割，支持引号）
arg_list = args.get_args()

# 检查是否有参数
if args.is_empty():
    # 没有参数的处理

# 获取参数数量
count = args.count()

获取特定参数

python

# 获取第一个参数
first_arg = args.get_first("默认值")

# 获取指定索引的参数
second_arg = args.get_arg(1, "默认值")

# 获取从指定位置开始的剩余参数
remaining = args.get_remaining(1)  # 从第2个参数开始

标志参数处理

python

# 检查是否包含标志
if args.has_flag("--verbose"):
    # 处理verbose模式

# 获取标志的值
output_file = args.get_flag_value("--output", "default.txt")
name = args.get_flag_value("--name", "Anonymous")

高级示例

1. 带子命令的复杂命令

python

class TestCommand(PlusCommand):
    command_name = "test"
    command_description = "测试命令，展示参数解析功能"
    command_aliases = ["t"]

    async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
        if args.is_empty():
            await self.send_text("用法: /test <子命令> [参数]")
            return True, "显示帮助", True
        
        subcommand = args.get_first().lower()
        
        if subcommand == "args":
            result = f"""
🔍 参数解析结果:
原始字符串: '{args.get_raw()}'
解析后参数: {args.get_args()}
参数数量: {args.count()}
第一个参数: '{args.get_first()}'
剩余参数: '{args.get_remaining()}'
            """
            await self.send_text(result)
            
        elif subcommand == "flags":
            result = f"""
🏴 标志测试结果:
包含 --verbose: {args.has_flag('--verbose')}
包含 -v: {args.has_flag('-v')}
--output 的值: '{args.get_flag_value('--output', '未设置')}'
--name 的值: '{args.get_flag_value('--name', '未设置')}'
            """
            await self.send_text(result)
            
        else:
            await self.send_text(f"❓ 未知的子命令: {subcommand}")
        
        return True, "Test命令执行成功", True

2. 聊天类型限制示例

python

class PrivateOnlyCommand(PlusCommand):
    command_name = "private"
    command_description = "仅私聊可用的命令"
    chat_type_allow = ChatType.PRIVATE

    async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
        await self.send_text("这是一个仅私聊可用的命令")
        return True, "私聊命令执行", True

class GroupOnlyCommand(PlusCommand):
    command_name = "group"
    command_description = "仅群聊可用的命令"
    chat_type_allow = ChatType.GROUP

    async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
        await self.send_text("这是一个仅群聊可用的命令")
        return True, "群聊命令执行", True

3. 配置驱动的命令

python

class ConfigurableCommand(PlusCommand):
    command_name = "config_cmd"
    command_description = "可配置的命令"

    async def execute(self, args: CommandArgs) -> Tuple[bool, Optional[str], bool]:
        # 从插件配置中获取设置
        max_length = self.get_config("commands.max_length", 100)
        enabled_features = self.get_config("commands.features", [])
        
        if args.is_empty():
            await self.send_text("请提供参数")
            return True, "无参数", True
            
        content = args.get_raw()
        if len(content) > max_length:
            await self.send_text(f"内容过长，最大允许 {max_length} 字符")
            return True, "内容过长", True
            
        # 根据配置决定功能
        if "uppercase" in enabled_features:
            content = content.upper()
            
        await self.send_text(f"处理结果: {content}")
        return True, "配置命令执行", True

支持的命令前缀

系统支持以下命令前缀（在config/bot_config.toml中配置）：

/ - 斜杠（默认）
! - 感叹号
. - 点号
# - 井号

例如，对于echo命令，以下调用都是有效的：

/echo Hello
!echo Hello
.echo Hello
#echo Hello

返回值说明

execute方法需要返回一个三元组：

python

return (执行成功标志, 可选消息, 是否拦截后续处理)

执行成功标志 (bool): True表示命令执行成功，False表示失败
可选消息 (Optional[str]): 用于日志记录的消息
是否拦截后续处理 (bool): True表示拦截消息，不进行后续处理

最佳实践

命令命名：使用简短、直观的命令名
别名设置：为常用命令提供简短别名
参数验证：总是检查参数的有效性
错误处理：提供清晰的错误提示和使用说明
配置支持：重要设置应该可配置
聊天类型：根据命令功能选择合适的聊天类型限制

完整示例

完整的插件示例请参考 plugins/echo_example/plugin.py 文件。

与传统BaseCommand的区别

特性	PlusCommand	BaseCommand
正则表达式	自动生成	手动编写
参数解析	CommandArgs类	手动处理
别名支持	内置支持	需要在正则中处理
代码复杂度	简单	复杂
学习曲线	平缓	陡峭

增强命令系统让插件开发变得更加简单和高效，特别适合新手开发者快速上手。

增强命令系统使用指南 ​

概述 ​

核心特性 ​

快速开始 ​

1. 创建基础命令 ​

2. 在插件中注册命令 ​

CommandArgs 类详解 ​

基础方法 ​

获取特定参数 ​

标志参数处理 ​

高级示例 ​

1. 带子命令的复杂命令 ​

2. 聊天类型限制示例 ​

3. 配置驱动的命令 ​

支持的命令前缀 ​

返回值说明 ​

最佳实践 ​

完整示例 ​

与传统BaseCommand的区别 ​

增强命令系统使用指南

概述

核心特性

快速开始

1. 创建基础命令

2. 在插件中注册命令

CommandArgs 类详解

基础方法

获取特定参数

标志参数处理

高级示例

1. 带子命令的复杂命令

2. 聊天类型限制示例

3. 配置驱动的命令

支持的命令前缀

返回值说明

最佳实践

完整示例

与传统BaseCommand的区别