洛玖SDK是一个用于开发洛玖机器人插件的综合性开发工具包。本文档将详细介绍SDK的核心功能、事件处理机制以及API接口的使用方法。

概述

洛玖SDK提供了一套完整的接口，使开发者能够轻松创建与洛玖机器人框架交互的插件。SDK基于Tokio运行时设计，支持异步操作，可以高效处理各类消息和事件。

插件结构

一个标准的洛玖插件需要根据你要求的message_types字段：

let metadata = PluginMetadata {
    name: "hello_plugin".to_string(),
    describe: "一个简单的示例插件，用于演示基本功能".to_string(),
    author: "luoy-oss".to_string(),
    version: "0.1.0".to_string(),
    message_types: vec![
        "group_message".to_string(),	// 群消息 
        "private_message".to_string(),	// 私聊消息
        "group_poke".to_string(),		// 群戳一戳
        // ... 其他字段
    ],
};

实现相应的Plugin trait

该trait定义了插件的基本行为和事件处理方法：

#[async_trait]
pub trait Plugin: Send + Sync {
    fn metadata(&self) -> &PluginMetadata;
    
    async fn handle_group_message(&self, message: &GroupMessage) -> Result<()>;
    async fn handle_private_message(&self, message: &PrivateMessage) -> Result<()>;
    async fn handle_group_poke(&self, target_id: &str, user_id: &str, group_id: &str) -> Result<()>;
    // 其他事件处理方法...
}

事件处理函数详解

handle_group_message

1	`async fn handle_group_message(&self, message: &GroupMessage) -> Result<()>;`

功能：处理来自群聊的消息。

参数：

message : 包含群消息详细信息的 GroupMessage 结构体，包括：
- message_id : 消息ID
- content : 消息内容
- sender_id : 发送者ID
- group_id : 群组ID
- raw_data : 原始消息数据

使用场景：

关键词触发回复
指令解析与执行
群聊游戏功能
群管理功能

示例：

async fn handle_group_message(&self, message: &GroupMessage) -> Result<()> {
    if message.content.contains("关键词") {
        self.api.send_group_message(&message.group_id, "回复内容").await?;
    }
    Ok(())
}

handle_private_message

1	`async fn handle_private_message(&self, message: &PrivateMessage) -> Result<()>;`

功能：处理来自私聊的消息。

参数：

message : 包含私聊消息详细信息的 PrivateMessage 结构体，包括：
- message_id : 消息ID
- content : 消息内容
- sender_id : 发送者ID
- raw_data : 原始消息数据

使用场景：

个人助手功能
私聊指令处理
用户个性化设置
隐私数据查询

示例：

async fn handle_private_message(&self, message: &PrivateMessage) -> Result<()> {
    if message.content.contains("帮助") {
        self.api.send_private_msg(&message.sender_id, "这是帮助信息...").await?;
    }
    Ok(())
}

handle_group_poke

1	`async fn handle_group_poke(&self, target_id: &str, user_id: &str, group_id: &str) -> Result<()>;`

功能：处理群内的戳一戳事件。

参数：

target_id : 被戳的目标ID
user_id : 发起戳一戳的用户ID
group_id : 发生戳一戳事件的群组ID

使用场景：

互动娱乐功能
机器人被戳时的反应
特殊触发机制

示例：

async fn handle_group_poke(&self, target_id: &str, user_id: &str, group_id: &str) -> Result<()> {
    if target_id == self.config.bot_id.to_string() {
        self.api.send_group_message(group_id, "别戳我!").await?;
    }
    Ok(())
}

API接口详解

洛玖SDK提供了丰富的API接口，用于与聊天平台进行交互。以下是主要API方法的详细说明：

send_group_message

1	`async fn send_group_message(&self, group_id: &str, message: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：向指定群组发送文本消息。

参数：

group_id : 目标群组ID
message : 要发送的消息内容
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_message(&group_id, "Hello, world!").await {
    Ok(_) => println!("消息发送成功"),
    Err(e) => println!("消息发送失败: {}", e),
}

send_private_msg

1	`async fn send_private_msg(&self, user_id: &str, message: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：向指定用户发送私聊消息。

参数：

user_id : 目标用户ID
message : 要发送的消息内容
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_private_msg(&user_id, "这是一条私聊消息").await {
    Ok(_) => println!("私聊消息发送成功"),
    Err(e) => println!("私聊消息发送失败: {}", e),
}

send_group_ai_record

1	`async fn send_group_ai_record(&self, group_id: &str, voice: &str, message: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：向指定群组发送AI生成的语音消息。

参数：

group_id : 目标群组ID
voice : 语音类型或模型标识
message : 要转换为语音的文本内容
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_ai_record(&group_id, "normal", "这是AI生成的语音消息").await {
    Ok(_) => println!("AI语音发送成功"),
    Err(e) => println!("AI语音发送失败: {}", e),
}

send_group_at

1	`async fn send_group_at(&self, group_id: &str, qq: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：在群组中@指定用户。

参数：

group_id : 目标群组ID
qq : 要@的用户QQ号
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_at(&group_id, &user_id).await {
    Ok(_) => println!("@用户成功"),
    Err(e) => println!("@用户失败: {}", e),
}

send_group_image

1	`async fn send_group_image(&self, group_id: &str, file: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：向指定群组发送图片。

参数：

group_id : 目标群组ID
file : 图片文件路径或URL
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_image(&group_id, "path/to/image.jpg").await {
    Ok(_) => println!("图片发送成功"),
    Err(e) => println!("图片发送失败: {}", e),
}

send_group_file

1	`async fn send_group_file(&self, group_id: &str, file: &str, name: &str, folder_id: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：向指定群组发送文件。

参数：

group_id : 目标群组ID
file : 文件路径
name : 文件名称
folder_id : 群文件夹ID，空字符串表示根目录
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_file(&group_id, "path/to/file.pdf", "文档.pdf", "").await {
    Ok(_) => println!("文件发送成功"),
    Err(e) => println!("文件发送失败: {}", e),
}

send_group_poke

1	`async fn send_group_poke(&self, group_id: &str, user_id: &str) -> Result<(), Box<dyn std::error::Error>>;`

功能：在群组中戳一戳指定用户。

参数：

group_id : 目标群组ID
user_id : 要戳的用户ID
返回值：成功返回 Ok(()) ，失败返回包含错误信息的 Err

示例：

match self.api.send_group_poke(&group_id, &user_id).await {
    Ok(_) => println!("戳一戳发送成功"),
    Err(e) => println!("戳一戳发送失败: {}", e),
}

get_group_files_by_folder

1	`async fn get_group_files_by_folder(&self, group_id: &str, folder_id: &str, file_count: i32) -> Result<String, Box<dyn std::error::Error>>;`

功能：获取群文件夹中的文件列表。

参数：

group_id : 目标群组ID
folder_id : 文件夹ID
file_count : 要获取的文件数量
返回值：成功返回包含文件信息的JSON字符串，失败返回包含错误信息的 Err

示例：

match self.api.get_group_files_by_folder(&group_id, &folder_id, 10).await {
    Ok(files) => println!("获取到的文件: {}", files),
    Err(e) => println!("获取文件失败: {}", e),
}

get_group_root_files

1	`async fn get_group_root_files(&self, group_id: &str) -> Result<String, Box<dyn std::error::Error>>;`

功能：获取群根目录文件列表。

参数：

group_id : 目标群组ID
返回值：成功返回包含文件信息的JSON字符串，失败返回包含错误信息的 Err

示例：

match self.api.get_group_root_files(&group_id).await {
    Ok(files) => println!("根目录文件: {}", files),
    Err(e) => println!("获取根目录文件失败: {}", e),
}

插件开发流程

创建插件结构体

pub struct MyPlugin {
    metadata: PluginMetadata,
    config: Arc<Value>,
    api: ApiManager,
}

实现初始化方法

impl MyPlugin {
    pub fn new(config: Arc<Value>) -> Result<Self> {
        let metadata = PluginMetadata {
            name: "my_plugin".to_string(),
            describe: "我的插件描述".to_string(),
            author: "作者名".to_string(),
            version: "0.1.0".to_string(),
            message_types: vec![
                "group_message".to_string(),
                "private_message".to_string(),
            ],
        };
        
        let api = match ApiManager::new(config.clone()) {
            Ok(api) => api,
            Err(e) => return Err(anyhow!("API初始化失败: {}", e)),
        };
        
        Ok(Self {
            metadata,
            config,
            api,
        })
    }
}

实现Plugin trait

#[async_trait]
impl Plugin for MyPlugin {
    fn metadata(&self) -> &PluginMetadata {
        &self.metadata
    }
    
    async fn handle_group_message(&self, message: &GroupMessage) -> Result<()> {
        // group_message字段=>群消息处理逻辑
        Ok(())
    }
    
    async fn handle_private_message(&self, message: &PrivateMessage) -> Result<()> {
        // private_message字段=>私聊消息处理逻辑
        Ok(())
    }
    
    async fn handle_group_poke(&self, target_id: &str, user_id: &str, group_id: &str) -> Result<()> {
        // group_poke字段=>戳一戳事件处理逻辑
        Ok(())
    }
}

导出插件创建函数

async fn create(config: Arc<Value>) -> Result<Box<dyn Plugin>> {
    println!("开始创建插件实例...");
    let plugin = MyPlugin::new(config)?;
    println!("插件实例创建成功: {}", plugin.metadata().name);
    Ok(Box::new(plugin))
}

export_plugin!(create);