English | 简体中文

Kovi

Kovi is a simple and extensible chat bot development framework. If you want to develop Milky / OneBot V11 bots using Rust, Kovi is a great choice.

🎯 The goal is to create the simplest chat bot framework in Rust! Simplifying complex Rust syntax? Kovi has done its best.

🤔 Let me count — the quick start in the documentation only requires 10 lines of code to create the simplest plugin.

🥁 There’s also a CLI tool to make project development easier.

🖥️ Just for fun? Or customized? Kovi is competent

🛍️ The plugin shop provides an excellent Kovi shopping experience, allowing you to easily access packages from plugin developers 📦.

😍 The project documentation is very simple and easy to understand. Follow it and you’ll be good to go.

↓ Documentation is here

Kovi Docs

↓ The shop is here

Kovi Shop

Protocol Support

Kovi crate is basically an "event bus" plugin runner. You can adapt it to integrate with other services as needed, but its current focus is the two protocols above.

Milky WebSocket protocol
OneBot V11 forward WebSocket protocol

Getting Started

It's recommended to use kovi-cli to manage your Kovi bot project.

cargo install kovi-cli

Create a basic Rust project and add the framework.

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

You will see that a bot instance has been generated in src/main.rs.

use kovi::build_bot;

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

On your first run, during build_bot, you'll be prompted to enter some information to create the kovi.conf.toml file, which is required for Kovi to run.

✔ What is the type of the host of the OneBot server? · IPv4

✔ 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? (Optional) ·
(Default: empty)

✔ What is the ID of the main administrator? (Not used yet)
(Optional)

✔ Do you want to view more optional options? · No

Plugin Development

Creating a Plugin

Follow the steps below.

cargo kovi create hi

kovi-cli and cargo will take care of everything for you.

You will see that a new plugins/hi directory has been created. This is also the recommended way to develop plugins, as it’s always good to manage them in a directory.

Writing a Plugin

Edit your newly created plugin in plugins/hi/src/lib.rs.

Here's a minimal example:

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

#[kovi::plugin] // Build the plugin
async fn main() {
    plugin::on_msg(|event| async move {
        // 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
        }
    });
}

The main function is written in lib.rs because it will be exported later to be mounted to the bot instance.

Plugins generally don't need a main.rs.

Mounting the Plugin

cargo kovi add hi

Alternatively, you can use cargo directly; both are the same. This will add a local dependency in the root project’s Cargo.toml.

cargo add --path plugins/hi

use kovi::build_bot;

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

More Plugin Examples

Bot Taking Initiative to Send Messages

use kovi::PluginBuilder as plugin;

#[kovi::plugin]
async fn main() {
    // get a RuntimeBot
    let bot = plugin::get_runtime_bot();
    let user_id = bot.main_admin;

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

The main() function runs only once when plugin starts.

The closure passed to plugin::on_msg() runs every time a message is received.

Kovi has encapsulated all available OneBot standard APIs. To extend the API, you can use RuntimeBot's send_api() to send APIs yourself. You can check out the API extension plugins available for your needs at Kovi Plugin Shop.

You can find more documentation in the Kovi Doc.

kovi 0.13.0-rc1