注册命令解析

接下来你需要为你的插件配置命令解析

Madoka 使用 Arclet Alconna (opens new window) 作为命令解析器，建议先阅读 Arclet Alconna (opens new window) 文档。下面给出一些常用写法。

from arclet.alconna import Alconna  # 导入命令解析器
from app.core.commander import CommandDelegateManager  # 导入命令委托管理器


manager: CommandDelegateManager = CommandDelegateManager()  # 获取命令委托管理器实例

@manager.register(
    entry='<命令头>',
    brief_help='<主菜单介绍>",
    alc=<Alconna 实例>
)

Alconna 简单介绍:

Alconna 命令结构类似与 Linux 的命令, 由 <前缀> <父命令> <子命令> <可选命令> 组成.

其中 <子命令> 中可嵌套 <可选命令>, 具体请查阅 Alconna 官方文档.

• <子命令>: from arclet.alconna import Subcommand
• <可选命令>: from arclet.alconna import Option
• <参数>: from arclet.alconna import Args

假设有命令: .pip install --upgrade <package>, 其中 upgrade 为可选命令.

from arclet.alconna import Alconna, Subcommand, Option, Args

@manager.register(
    entry='<命令头>',
    brief_help='<主菜单介绍>",
    alc=Alconna(
        headers=manager.headers,  # 命令前缀(固定写法, 直接使用manager.headers)
        command='<命令头 同上>',  # 父命令, 入口命令
        options=[
            Subcommand('install', help_text='安装pip包', args=Args['package', str], options[
                Option('--upgrade|-u', help_text='更新')
            ])
        ],
        help_text='pip管理'
    )
)

• help_text: 帮助文本
• Args: [*参数名, *参数类型, (默认值)]

提示

该部分内容具体用法请查看: https://arcletproject.github.io/docs/alconna/constructs/typical (opens new window)

配置插件主体函数

接下来你需要写一个函数作为该插件的主体函数, 并选择性的接受一些你需要的参数

······
from arclet.alconna import Alconna, ······, Arpamar
from graia.ariadne.model import Friend

······

@manager.register(
    ······
)
async def process(friend: Friend, cmd: Arpamar, alc: Alconna):
    pass

如果你的插件需要处理好友消息和群消息，那么可以这样写:

······
from graia.ariadne.model import Friend, Member, Group


async def process(target: Union[Friend, Member], sender: Union[Friend, Group], ······):
    pass

判断 target 或 sender 就可以知道消息来源。

可接受的参数

你可以选择接受下列参数

• graia.ariadne.Ariadne: Ariadne 主体
• graia.ariadne.model.Friend: 好友标识
• graia.ariadne.model.Member: 群成员标识
• graia.ariadne.model.Group: 群标识
• graia.ariadne.message.chain.MessageChain: 原始消息
• graia.ariadne.message.element.Source: 消息 ID
• graia.broadcast.interrupt.InterruptControl: 中断控制（不推荐使用，具体见后文）
• arclet.alconna.Arpamar: 解析结果
• arclet.alconna.Alconna: 命令解析器（主要用于获取帮助菜单）

完整示例

from typing import Union

from arclet.alconna import Alconna, Subcommand, Option, Args, Arpamar
from graia.ariadne.model import Friend, Member, Group

from app.core.commander import CommandDelegateManager  # 导入命令委托管理器


manager: CommandDelegateManager = CommandDelegateManager()  # 获取命令委托管理器实例

@manager.register(
    entry='<命令头>',
    brief_help='<主菜单介绍>",
    alc=Alconna(
        headers=manager.headers,  # 命令前缀(固定写法, 直接使用manager.headers)
        command='<命令头 同上>',  # 父命令, 入口命令
        options=[
            Subcommand('install', help_text='安装pip包', args=Args['package', str], options[
                Option('--upgrade|-u', help_text='更新')
            ])
        ],
        help_text='pip管理'
    )
)
async def process(target: Union[Friend, Member], sender: Union[Friend, Group], cmd: Arpamar, alc: Alconna):
    pass

至此, 一个插件的基本构造已经完成, 接下来你需要自由完成该插件的功能.

说明: Alconna

Alconna 是一个优秀的命令解析器, 它采用类似与 Linux Shell 的命令方式.

• Arpamar基本方法
• 1. Arpamar.find: 判断解析结果中有无指定命令
• 2. Arpamar.query: 查询解析结果中的指定参数，若存在返回对应结果

真的真的建议在使用 Alconna 之前先完整阅读一遍官方文档

https://arcletproject.github.io/docs/alconna/tutorial/ (opens new window)