1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

┌─────────────────────────────────────────────┐
│  宿主 (luo9_bot, Rust)                      │
│  ├── WebSocket 连接 (Napcat)                │
│  ├── 事件路由 (message/event/notice)        │
│  ├── 插件加载器 (DLL/SO)                    │
│  ├── 优先级分发 + 热重载                    │
│  └── Cron 调度器                            │
└─────────────────┬───────────────────────────┘
                  │ FFI 消息总线 (luo9_core)
                  │
┌─────────────────┴───────────────────────────┐
│  插件 (DLL/SO, 任意语言)                     │
│  ├── 独立 OS 线程运行                        │
│  ├── 通过 Bus 订阅/发布消息                  │
│  └── 通过 Bot 发送消息                       │
└─────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use luo9_sdk::bus::Bus;
// 订阅 topic
let sub_id = Bus::topic("luo9_message").subscribe()?;
// 非阻塞取消息（配合 thread::sleep 使用）
if let Some(json) = Bus::topic("luo9_message").pop(sub_id) {
    // 处理消息
}
// 阻塞取消息（线程挂起直到有消息）
let json = Bus::topic("luo9_message").wait_pop(sub_id)?;
// 发布消息（广播给所有 subscriber）
Bus::topic("luo9_send").publish(r#"{"action":"send_group_msg","group_id":123,"message":"hello"}"#)?;
// 定向推送给指定 subscriber
Bus::topic("luo9_message").publish_to(&payload, &[0, 2])?;
// 取消订阅
Bus::topic("luo9_message").unsubscribe(sub_id)?;

1
2
3
4
5
6
7
8
9
10

pub enum BusError {
    InitFailed,         // 总线初始化失败
    PublishFailed,      // 发布失败
    SubscribeFailed,    // 订阅失败
    WaitPopFailed,      // 阻塞取消息失败
    NotInitialized,     // 总线未初始化
    InvalidString,      // 字符串转换失败
    UnsubscribeFailed,  // 取消订阅失败
    Unsubscribed,       // subscriber 已被取消订阅（热重载哨兵）
}

1
2
3
4
5

use luo9_sdk::command::{Command, PrefixMode};
if let Some(cmd) = Command::parse(msg, "echo", PrefixMode::Required('/')) {
    Bot::send_group_msg(group_id, CString::new(cmd.args().join(" ")).unwrap());
}

1
2
3
4
5
6
7
8

if let Some(cmd) = Command::parse(msg, "task", PrefixMode::Required('/')) {
    cmd.on("start", |args| {
        // 处理 "/task start ..."
    })
    .on("end", |args| {
        // 处理 "/task end ..."
    });
}

1
2
3
4
5
6
7
8
9
10
11
12

if let Some(cmd) = Command::parse(msg, "epic", PrefixMode::None) {
    cmd.handle(|| {
        // 无参数的 "epic" → 查询免费游戏
        epic_free_games(group_id);
    })
    .on("提醒开启", |_| {
        task_start(group_id);
    })
    .on("提醒关闭", |_| {
        task_end(group_id);
    });
}

1
2
3
4
5
6
7
8
9

if let Some(cmd) = Command::parse(msg, "doro", PrefixMode::None) {
    cmd.on("add", |args| { /* doro add ... */ })
        .on("remove", |args| { /* doro remove ... */ })
        .on("list", |_| { /* doro list */ })
        .otherwise(|| {
            // 无匹配子命令时的默认行为
            send_today(group_id, &uid);
        });
}

1
2
3
4
5

cmd.on_pattern("[CQ:at,qq={qq}]{content}", |caps, _args| {
    let qq = caps.get("qq").unwrap();
    let content = caps.get("content").unwrap();
    // 处理 @消息
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use luo9_sdk::Msg;
// 纯文本
let msg = Msg::txt("你好").build();
Bot::send_group_msg(group_id, msg);
// 图片（自动检测 URL / 本地文件）
let msg = Msg::image("https://example.com/img.png").build();
// 复合消息：文本 + 换行 + 文本 + 图片
let msg = Msg::txt("游戏名称: Epic Game").endl()
    .txt("描述: 一款好游戏").endl()
    .txt("预览图片：").image(game.preview_image)
    .build();
Bot::send_group_msg(group_id, msg);

1
2
3
4
5

use luo9_sdk::Bot;
use std::ffi::CString;
Bot::send_group_msg(group_id, CString::new("你好").unwrap());
Bot::send_private_msg(user_id, CString::new("你好").unwrap());

1
2
3
4

use luo9_sdk::send;
send::send_group_msg(group_id, "你好");
send::send_private_msg(user_id, "你好");

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use luo9_sdk::payload::*;
if let Some(BusPayload::Message(msg)) = BusPayload::parse(&json) {
    match msg.message_type {
        MsgType::Group => {
            let group_id = msg.group_id.unwrap_or(0);
            let user_id = msg.user_id;
            let content = &msg.message;
        }
        MsgType::Private => {
            let user_id = msg.user_id;
            let content = &msg.message;
        }
        _ => {}
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

pub enum MsgType { Private, Group, Other }
pub struct MessagePayload {
    pub message_type: MsgType,
    pub user_id: u64,
    pub group_id: Option<u64>,
    pub message: String,
}
pub enum MetaEventType { Lifecycle, Heartbeat, Unknown }
pub struct MetaEventPayload {
    pub interval: Option<u64>,
    pub meta_event_type: MetaEventType,
    pub sub_type: SubType,
    pub self_id: u64,
    pub status: Option<Status>,
    pub time: u64,
}
pub enum NoticeType {
    FriendAdd, FriendRecall, GroupAdmin, GroupBan,
    GroupIncrease, GroupDecrease, GroupCard, GroupRecall,
    GroupUpload, Essence, Notify, Unknown,
}
pub struct NoticePayload {
    pub notice_type: NoticeType,
    pub sub_type: SubType,
    pub status: String,
    pub user_id: u64,
    pub group_id: Option<u64>,
    pub time: u64,
}

1
2
3
4
5
6
7

use luo9_sdk::pattern::Pattern;
let pat = Pattern::new("[CQ:at,qq={qq}]{content}");
if let Some(caps) = pat.match_str("[CQ:at,qq=123456]你好呀") {
    let qq = caps.get("qq").unwrap();          // "123456"
    let content = caps.get("content").unwrap(); // "你好呀"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use luo9_sdk::bus::Bus;
use serde_json::json;
// 注册定时任务（发布到 luo9_task_miso）
let req = json!({
    "action": "schedule",
    "task_name": "my_task",
    "cron": "0 0 8 * * *",   // 每天 8:00
    "payload": group_id.to_string()
});
Bus::topic("luo9_task_miso").publish(&req.to_string())?;
// 取消定时任务
let cancel = json!({
    "action": "cancel",
    "task_name": "my_task"
});
Bus::topic("luo9_task_miso").publish(&cancel.to_string())?;
// 接收定时事件（订阅 luo9_task 后）
// 收到的 JSON: {"event": "tick", "task_name": "my_task", "payload": "..."}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use luo9_sdk::version;
use luo9_sdk::bus::Bus;
let ver_sub = Bus::topic("luo9_version").subscribe()?;
let ver_topic = Bus::topic("luo9_version");
loop {
    if let Some(json) = ver_topic.pop(ver_sub) {
        if version::is_version_query(&json) {
            version::reply_version(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
        }
    }
    std::thread::sleep(std::time::Duration::from_millis(1));
}

1
2
3
4
5
6
7
8
9
10
11

[package]
name = "my_plugin"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib"]
[dependencies]
luo9_sdk = "0.6.0"
serde_json = "1"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

mod core;
use luo9_sdk::Bot;
use luo9_sdk::bus::Bus;
use luo9_sdk::command::{Command, PrefixMode};
use luo9_sdk::payload::*;
use std::ffi::CString;
#[unsafe(no_mangle)]
pub extern "C" fn plugin_main() {
    // 订阅需要的 topic
    let msg_sub = Bus::topic("luo9_message").subscribe().unwrap();
    let ver_sub = Bus::topic("luo9_version").subscribe().unwrap();
    // 缓存 Topic 句柄（避免重复创建 CString）
    let msg_topic = Bus::topic("luo9_message");
    let ver_topic = Bus::topic("luo9_version");
    println!("[my_plugin] 插件已启动");
    loop {
        // 消息处理
        if let Some(json) = msg_topic.pop(msg_sub) {
            if let Some(BusPayload::Message(msg)) = BusPayload::parse(&json) {
                match msg.message_type {
                    MsgType::Group => {
                        handle_group_msg(msg.group_id.unwrap_or(0), msg.user_id, &msg.message);
                    }
                    MsgType::Private => {
                        handle_private_msg(msg.user_id, &msg.message);
                    }
                    _ => {}
                }
            }
        }
        // 版本查询
        if let Some(json) = ver_topic.pop(ver_sub) {
            if luo9_sdk::version::is_version_query(&json) {
                luo9_sdk::version::reply_version(
                    env!("CARGO_PKG_NAME"),
                    env!("CARGO_PKG_VERSION"),
                );
            }
        }
        // 短暂让出 CPU，避免空转
        std::thread::sleep(std::time::Duration::from_millis(1));
    }
}
fn handle_group_msg(group_id: u64, _user_id: u64, msg: &str) {
    if let Some(cmd) = Command::parse(msg, "echo", PrefixMode::Required('/')) {
        Bot::send_group_msg(group_id, CString::new(cmd.args().join(" ")).unwrap());
    }
}
fn handle_private_msg(user_id: u64, msg: &str) {
    if let Some(cmd) = Command::parse(msg, "echo", PrefixMode::Required('/')) {
        Bot::send_private_msg(user_id, CString::new(cmd.args().join(" ")).unwrap());
    }
}

1
2
3

cargo build --release
# 产物：target/release/my_plugin.dll (Windows) / libmy_plugin.so (Linux)
# 将产物放入宿主的 plugins/ 目录即可

1

extern "C" fn plugin_main();  // 在独立线程中运行

1
2
3
4
5
6
7
8

#[repr(C)]
pub struct PluginSubscribers {
    pub message_sub_id: i32,
    pub meta_event_sub_id: i32,
    pub notice_sub_id: i32,
    pub task_sub_id: i32,
    pub send_sub_id: i32,
}