luo9-sdk 0.1.2

洛玖机器人 Python 插件 SDK

Luo9 SDK (Python)

一个用于开发洛玖 (Luo9) 机器人插件的 Python SDK。

功能特性

• 命令解析：灵活的命令解析系统，支持前缀模式和链式匹配
• 消息构建：流式 API 构建复杂消息（文本、@用户、图片）
• 消息总线：发布/订阅模式的消息系统，支持多订阅者
• 事件处理：完整的 OneBot v11 标准事件解析（消息、通知、元事件、请求）
• 消息发送：基于总线的异步消息发送
• 模式匹配：支持 {name} 模板变量捕获
• 直接 FFI 调用：通过 ctypes 直接调用 luo9_core.dll，与 Rust/C++ 插件共享同一 Bus 实例

环境要求

• Python 3.10+
• 宿主已启用 python-plugin feature（cargo build --features python-plugin）

安装

将 sdk/python/ 目录添加到 Python 路径，或使用 pip 安装：

cd sdk/python
pip install .

快速开始

插件入口

每个插件需要定义 plugin_main() 函数：

from luo9_sdk import Bus, Bot, Command, PrefixMode, BusPayload, PayloadType

def plugin_main():
    msg_sub = Bus.topic("luo9_message").subscribe()

    while True:
        json_str = Bus.topic("luo9_message").pop(msg_sub)
        if json_str is None:
            break
        if json_str:
            payload = BusPayload.parse(json_str)
            if payload and payload.type == PayloadType.MESSAGE:
                # 处理消息...
                pass

命令解析

from luo9_sdk import Command, PrefixMode, Bot

def handle_msg(group_id, msg):
    # 解析命令（前缀模式）
    cmd = Command.parse(msg, "echo", PrefixMode.Required('/'))
    if cmd and not cmd.empty():
        Bot.send_group_msg(group_id, cmd.args_raw())
        return

    # 链式子命令匹配
    cmd = Command.parse(msg, "task", PrefixMode.Required('/'))
    if cmd and not cmd.empty():
        cmd.on("start", lambda args: handle_task_start(args)) \
           .on("end", lambda args: handle_task_end(args))

消息构建

from luo9_sdk import Msg, Bot

# 流式构建 CQ 码消息
msg = Msg.txt("Hello ") \
    .then_at(123456) \
    .endl() \
    .then_txt("这是一条消息") \
    .then_image("https://example.com/img.png") \
    .build()

Bot.send_group_msg(987654, msg)

模式匹配

from luo9_sdk import Pattern

pat = Pattern("[CQ:at,qq={qq}]{content}")
caps = pat.match("[CQ:at,qq=123456]hello")
if caps:
    qq = caps["qq"]         # "123456"
    content = caps["content"]  # "hello"

事件处理

from luo9_sdk import BusPayload, PayloadType, MsgType

def handle_event(json_str):
    payload = BusPayload.parse(json_str)
    if not payload:
        return
    if payload.type == PayloadType.MESSAGE:
        if payload.message.message_type == MsgType.GROUP:
            # 群消息处理
            pass
        elif payload.message.message_type == MsgType.PRIVATE:
            # 私聊消息处理
            pass
    elif payload.type == PayloadType.NOTICE:
        # 通知处理
        pass
    elif payload.type == PayloadType.META_EVENT:
        # 元事件处理
        pass

消息发送

from luo9_sdk import Bot

Bot.send_group_msg(987654, "Hello!")
Bot.send_private_msg(123456, "私聊消息")

API 概览

模块	类/函数	说明
luo9_sdk.bus	Bus, Topic, init_subscribers()	总线通信
luo9_sdk.topic	Topic.subscribe(), .pop(), .wait_pop(), .publish()	Topic 操作
luo9_sdk.command	Command, CommandMatcher, PrefixMode	命令解析
luo9_sdk.message	Msg	消息构建
luo9_sdk.payload	BusPayload, MessagePayload, NoticePayload, ...	事件载荷
luo9_sdk.pattern	Pattern	模式匹配
luo9_sdk.bot	Bot	消息发送
luo9_sdk.version	is_version_query(), reply_version()	版本协议

事件类型

消息事件

• MsgType.PRIVATE - 私聊消息
• MsgType.GROUP - 群消息

通知事件

• NoticeType.FRIEND_ADD - 好友添加
• NoticeType.GROUP_ADMIN - 群管理员变更
• NoticeType.GROUP_BAN - 群禁言
• NoticeType.GROUP_INCREASE - 群成员增加
• NoticeType.GROUP_DECREASE - 群成员减少
• NoticeType.POKE - 戳一戳
• 更多...

元事件

• MetaEventType.LIFECYCLE - 生命周期事件
• MetaEventType.HEARTBEAT - 心跳事件

运行方式

Python 插件由宿主的嵌入式运行时（PyO3）加载执行，无需手动启动。将 .py 文件放入宿主的插件目录即可。

相关链接

• GitHub