Metadata-Version: 2.4
Name: luo9-sdk
Version: 0.1.2
Summary: 洛玖机器人 Python 插件 SDK
Author-email: luoy-oss <luoy-oss@qq.com>
License: GPL-3.0
Project-URL: Homepage, https://luo9.drluo.top/
Project-URL: Repository, https://github.com/luoy-oss/luo9_sdk
Project-URL: Documentation, https://luo9.drluo.top/sdk/
Keywords: bot,luo9,sdk,plugin,ffi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Luo9 SDK (Python)

[![许可证: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

一个用于开发洛玖 (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 安装：

```bash
cd sdk/python
pip install .
```

## 快速开始

### 插件入口

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

```python
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
```

### 命令解析

```python
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))
```

### 消息构建

```python
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)
```

### 模式匹配

```python
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"
```

### 事件处理

```python
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
```

### 消息发送

```python
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](https://github.com/luo9-bot)
