• 欢迎来到小可 · Wiki,人人可编辑的,多平台聊天机器人“小可”的官方文档资源。
  • 小可很可爱,请给我们打钱
  • 原 MkDocs 已迁入本站。若发现 404 属正常现象,请点击左上角搜索您想要的模块。

新建模块指南

来自小可 · Wiki,人人可编辑的,QQ机器人“小可”的官方文档资源
Dianliang233讨论 | 贡献2021年11月27日 (六) 13:41的版本 →‎处理消息:​ fk

不会吧不会吧,真的会有人来给屎山写模块吗(


说明

我们将所有模块储存在了modules文件夹。如果你想编写新的模块,请在里面新建一个文件夹。

文件夹的名字并不用于区分模块名,仅用于分类。

机器人在加载的时候会遍历modules文件夹,并加载每个模块文件夹里的__init__.py,请将想要加入的模块定义编写在__init__.py中或确保其能够被引用。

当前可用的模块类型有Command(一般命令类型)、Regex(正则表达式类型)、Schedule(计划任务类型)、StartUp(自启类型)。


编写

我们假设你现在写好了具体的业务代码,现在你想把其做成一个可以给机器人使用的功能:

定义模块

编写模块之前,我们需要先定义一个模块类型。

此定义方式目前仅支持CommandRegex模块,ScheduleStartUp请见下文的“旧版”

注:Regex同理。

Command

from core.component import on_command

test = on_command(
    bind_prefix='test', # 定义模块名
    desc='啊吧啊吧啊吧', # 此模块的简介
    alias='m', # 此模块的别名,用法请见下文
    developers=['OasisAkari', 'Dianliang233'], # 开发者的名字
    recommend_modules=['mcbv', 'mcdv']), # 推荐打开的其他模块,用于在打开此模块时进行一并提示
    required_admin = False, # 将此模块标记为仅群组管理员可执行,覆盖下文所述的子命令设定,默认为False
    base = False, # 将此模块标记为基础模块,无需打开即可使用,默认为False
    required_superuser = False # 将此模块标记为仅机器人超级管理员可使用,覆盖下文所述的子命令设定,默认为False
)

绑定模块

现在你已经定义好了一个模块,现在你需要将你想要的东西绑定上去了。

在前文中,我们给test变量声明了定义,我们将围绕这个定义进行绑定子命令,为了使代码简洁,我们使用了装饰器:

Command

from core.elements import MessageSession

@test.handle(help_doc='<args1>', # 设置此命令的语法,前缀匹配模块名,此处忽略。可为list或tuple来经手多条命令。可为空。
             required_admin = False, # 将此命令标记为仅群组管理员可使用。
             required_superuser = False, # 将此命令标记为进机器人超级管理员可使用。
             available_for = '*' # 控制此命令可被使用的消息来源,默认为 '*'(所有)
             )
async def _(msg: MessageSession):
    ...

当help_doc为空时,则代表此模块允许无需语法命令即可执行。如:使用~test命令(后面不带任何东西),即可触发装饰器下面的函数,否则会出现“语法错误”的提示。

与语法匹配的命令将会被切割存储于msg.parsed_msg(dict类型)

如:{'<args1>': 'xxx'}

Regex

from core.elements import MessageSession

@test.handle(pattern=r'\[\[(.*?)]]', # 正则表达式语法
             mode='M', # 正则模式,设为'M'为匹配模式,'A'为匹配所有模式
             flags=0, # 设置正则的flags,如Re.M|Re.I
             show_typing=False #设置命令执行时是否展示输入提示(如戳一戳),默认为True
             )
async def _(msg: MessageSession):
    ...

与表达式匹配的命令结果将会存储于msg.matched_msg中。

当你输入的命令匹配help_doc内的语法时,机器人将会把消息传入装饰器下方的函数,然后你就可以进行发挥了。

处理消息

我们在装饰器下方的函数定义了一个msg参数,发送消息将围绕它进行。 我们在此处仅展示基础方法,具体可用的操作请借助ide查看。

...
send = await msg.sendMessage('你好') # 向发送对象发送一条消息
send.delete() # 将这条消息删除
...
confirm = await msg.waitConfirm('真的要这么做吗?') # 在发送此消息后将暂停执行,等待用户的下一条消息
if confirm: # 用户发送了确认的词语
    ...

发送的消息可以为str或装有消息组件的list,如:[Plain('今日份的LittleC'), Image('https://github.com/komeiji-satori/Dress/raw/master/XxLittleCxX/0x01.jpg')](被打

消息来源

目前可用的有QQ|Group(QQ群)、QQ(QQ好友)、QQ|Guild(QQ频道)、Discord|Channel(Discord频道)、Discord|DM|Channel(Discord私聊频道)、Telegram|private(Telegram私聊)、Telegram|group(Telegram群组)、Telegram|supergroup(Telegram supergroup(?))、Telegram|channel(Telegram频道)、TEST|Console(控制台)

消息组件

目前可用的有Plain(文本)、Image(图片)、Voice(语音)

别名

主要用于快捷触发命令,或是兼容老的命令语法。 当为strList[str]Tuple[str]时,别名将会指向模块名。

如上文,alias='m',则使用~m xxx = ~test xxx

当为dict时则可自定义别名映射到的东西,如{'enable': 'module enable'},则~enable xxx = ~module enable xxx

旧版声明

我们在旧版命令未引入“handle”特性,使得一个装饰器只能对应一个模块,不存在绑定子命令的特性。

此处介绍是由于时间关系,Schedule(计划任务类型)、StartUp(自启类型)尚未支持新版。

Schedule

from core.component import on_schedule
from core.elements import CronTrigger

@on_schedule(
        bind_prefix='test', # 定义模块名
        trigger=CronTrigger.from_crontab('30 8 * * MON'), # 触发器
        desc='啊吧啊吧', # 模块简介
        alias=None, # 命令别名
        recommend_modules=None, # 推荐打开模块
        developers=None, # 开发者列表
        required_superuser=False, # 是否需要超级管理员才能打开
)
async def weekly_rss(bot: FetchTarget):
    ...


FetchTarget

主要用于从数据库中获取用户推送内容。

await bot.post_message('test', '啊吧啊吧') # 向所有已开启<code>test</code>模块的用户推送消息。
sender = 'QQ|123456' # QQ号为123456的好友
fetch = bot.fetch_target(sender) # 获取信息
if fetch: #如获取到
    await fetch.sendMessage('xxx') # 发送消息
Cookie帮助我们提供我们的服务。通过使用我们的服务,您同意我们使用cookie。