Skip to content

简洁、容易上手,适用于QQ官方频道机器人的Python轻量应用级SDK【已支持webhook、ws和远程webhook三种连接方式】

License

Notifications You must be signed in to change notification settings

GLGDLY/qg_botsdk

Repository files navigation

qg_botsdk

Language License Pypi Codacy Badge docs

✨用于QQ官方频道机器人,兼顾实用与容易入门的Python应用级SDK✨

文档 · 例程 · 快速入门

引言

对于使用python进行频道官方机器人开发而言,市面上确实有不同的sdk可以选用,但其很多只提供异步asyncio+类继承的开发方式,对于不会相关技巧的朋友们,尤其新手,会有开发难度。

为此,qg_botsdk相应提供了另一个选择,这一款sdk虽然同样使用asyncio编写sdk底层,但其同时提供了threading和asyncio封装下的应用层调用,以抽象化封装的库编写方式,极大地降低应用层的开发难度。

亮点

- 已支持Websocket、Webhook、Remote Webhook(wh转ws允许本地调试)三种连接方式
- 已支持SDK层面的沙箱处理,允许沙箱过滤外部消息、外部过滤沙箱消息;已支持频道、频道私信、群、QQ私信四种沙箱过滤模式
- 两种应用层开发方式(threading、asyncio),可根据自己的喜好选择,而底层均为asyncio实现,保持高并发能力
- 灵活的构建方式,即使官方删除或新增字段,SDK也不会规范于原来的数据格式,而会把真实数据反馈给你
- 轻量,简洁,统一的代码结构,通过录入回调函数处理不同事件,10行即可构建一个简单的程序
- 容易入门,无需学会asyncio、类继承等编程技巧也可使用,同时保留较高并发能力
- 保留官方http API中Json数据的结构字段,带你学习官方结构,日后可自行开发适合自己的SDK
- 简单易用的plugins编写与加载,使用例子可参阅 example_13(装饰器).py
- 方便多场景(频道+群等)构建机器人的抽象化封装,使用例子可参阅 example_16(Q群简单工作流).py

下载方式

  • pip安装(推荐):
pip install qg-botsdk   # 注意是qg-botsdk(中线),不是qg_botsdk(底线)

一个简单的工作流

  • 注册BOT实例,录入机器人平台获取的ID(BotAppId开发者ID)和token(机器人令牌)
  • 编写接收事件的函数->下方例子:def deliver(data),并可借助model库检查数据格式(data: Model.MESSAGE
  • 绑定接收事件的函数(bind_msg、bind_dm、bind_msg_delete、bind_guild_event、bind_guild_member、bind_reaction、bind_interaction、bind_audit、bind_forum、bind_audio)
  • 开始运行机器人:bot.start()
from qg_botsdk import BOT, Model   # 导入SDK核心类(BOT)、所有数据模型(Model)

bot = BOT(bot_id='xxx', bot_token='xxx', is_private=True, is_sandbox=True)   # 实例化SDK核心类


@bot.bind_msg()   # 绑定接收消息事件的函数
def deliver(data: Model.MESSAGE):   # 创建接收消息事件的函数
    if '你好' in data.treated_msg:   # 判断消息是否存在特定内容
        data.reply('你好,世界')   # 发送被动回复(带message_id直接reply回复)
        # 如需使用如 Embed 等消息模板,可传入相应结构体, 如:
        # data.reply(ApiModel.MessageEmbed(title="你好", content="世界"))


if __name__ == '__main__':
    bot.start()   # 开始运行机器人

指令装饰器

SDK同时已经在内部实现指令装饰器:

from qg_botsdk import BOT, Model 

bot = BOT(bot_id='xxx', bot_token='xxx', is_private=True, is_sandbox=True)

# before_command代表预处理器,将在检查所有commands前执行(要求SDK版本>=2.5.2)
@bot.before_command()
def preprocessor(data: Model.MESSAGE):
    bot.logger.info(f"收到来自{data.author.username}的消息:{data.treated_msg}")


@bot.on_command(
    regex=r"你好(?:机器人)?",  # 正则表达式,匹配用户消息
    is_short_circuit=True,    # is_short_circuit代表短路机制,根据注册顺序,匹配到即停止匹配,但不影响bind_msg()
    is_require_at=True,       # is_require_at代表是否要求检测到用户@了机器人才可触发指令
    is_require_admin=True,    # is_require_admin代表是否要求检测到用户是频道主或频道管理才可触发指令
    admin_error_msg="抱歉,你的权限不足(非频道主或管理员),不能使用此指令",
)
def command(data: Model.MESSAGE):
    data.reply("你好,世界")


if __name__ == '__main__':
    bot.start()

相关链接

About

简洁、容易上手,适用于QQ官方频道机器人的Python轻量应用级SDK【已支持webhook、ws和远程webhook三种连接方式】

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages