英语 | 简体中文

Kovi

一个在 Rust 中开发的 OneBot V11 机器人插件框架。

更多文档可以在 Kovi Doc 中找到。

该项目目前处于测试阶段。

未来更新将添加更多功能。

注意⚠️：该项目处于测试阶段，以下内容可能会更改。

注意⚠️：该项目目前仅支持 OneBot V11 前向 WebSocket 协议。

该项目的初衷是增强群组活动，方便群组管理，仅限个人娱乐、学习和交流使用。 禁止任何人将此项目用于任何非法活动。

为什么叫 Kovi？

机器人插件开发方法来源于 Kivi。由于 Kivi 仓库不再可用，但您可以查看其作者 Viki。如果您之前为 Kivi 框架开发过插件，那么使用这个框架将很容易入门。

入门

该项目是用 Rust 编写的，插件也需要用 Rust 编写。请确保已在本机安装 Rust。

1. 创建一个基本的 Rust 项目并添加框架。

cargo install kovi-cli
cargo kovi new my-kovi-bot
cd ./my-kovi-bot

2. 您将在 src/main.rs 中看到一个机器人实例已被生成。

use kovi::build_bot;

fn main() {
    let a = build_bot!();
    a.run()
}

如果您是首次运行，在 build_bot 期间，系统会提示您输入一些信息以创建所需的 kovi.conf.json 文件。

✔ What is the IP of the OneBot server? · 127.0.0.1
(Default: 127.0.0.1)

✔ What is the port of the OneBot server? · 8081
(Default: 8081)

✔ What is the access_token of the OneBot server? · 
(Default: Null)

✔ What is the ID of the main administrator? 
(No default value)

插件开发

创建插件

按照以下步骤操作。

cargo kovi create hi

kovi-cli 和 cargo 将为您处理一切。

您会看到一个名为 plugins/hi 的新目录已被创建。这也是推荐的开发插件的方式，因为将它们管理在一个目录中总是好的。

编写插件

将您新创建的插件写入 plugins/hi/src/lib.rs。

以下是一个最小示例

// Import the plugin builder structure
use kovi::PluginBuilder;

#[kovi::plugin] // Build the plugin
pub fn main(mut plugin: PluginBuilder) {
    // The main function must accept PluginBuilder, as it is the foundation of the plugin.

    plugin.on_msg(move |event| {
        // on_msg() listens for messages, and event contains all the information of the current message.
        if event.borrow_text() == Some("Hi Bot") {
            event.reply("Hi!") // Quick reply
        }
    });
}

主函数写在 lib.rs 中，因为它将被导出以挂载到机器人实例。

插件通常不需要 main.rs。

挂载插件

cargo kovi add hi

或者，您可以直接使用 cargo；两者是相同的。这将在根项目的 Cargo.toml 中添加一个本地依赖。

cargo add --path plugins/hi

use kovi::build_bot;

fn main() {
    let bot = build_bot!(hi,hi2,plugin123);
    bot.run()
}

更多插件示例

机器人主动发送消息

use kovi::PluginBuilder;

#[kovi::plugin]
pub fn main(mut plugin: PluginBuilder) {
    // Build a RuntimeBot
    let bot = plugin.build_runtime_bot();
    let user_id = bot.main_admin;

    bot.send_private_msg(user_id, "bot online")
}

main() 函数在 KoviBot 启动时只运行一次。

传递给 plugin.on_msg() 的闭包每次接收到消息时都会运行。

Kovi 封装了所有可用的 OneBot 标准API。要扩展API，您可以使用 RuntimeBot 的 send_api() 自行发送API。

更多文档可以在 Kovi Doc 中找到。