gonebot

gonebot

A Golang chatbot, currently support onebotv11. 中文文档

Catalog

• gonebot
  • Catalog
  • Why gonebot?
  • How to create a bot
  • How to create a plugin
  • How to create an adapter
  • The logic of gonebot
  • TODO

Why gonebot?

• Easy to use. You can easily load plugins or create them with less than 10 lines of code!
• High Performance. Powered by golang, we use minimum CPU and memory resource.
• Portable. Static compilation means you can compile the bot into an excutable file.

How to create a bot

You can refer to gonedemo

package main
import (
	"github.com/gonebot-dev/gonebot"
	"github.com/gonebot-dev/goneplugin-echo"
	"github.com/gonebot-dev/goneadapter-onebotv11"
)
func main() {
	gonebot.LoadPlugin(&echo.Echo)
	gonebot.StartAdapter(&onebotv11.OneBotV11)
	gonebot.Run()
}

Done. Three lines, one bot.

How to create a plugin

To create a plugin, you need to implement a GonePlugin struct.

// GoneHandler discribes a handler for a plugin.
type GoneHandler struct {
	// What type of message should trigger the handler?
	//
	// The filter results are ORed together.
	Rules []rule.FilterBundle
	// The handler function of the Handler. Will be triggerd by []Command
	//
	// The handlers will be triggered according to the loading order(plugin first, then the handler)
	//
	// Return true if you want to block the propagation, false if you want other plugins to handle it too.
	Handler func(a *adapter.Adapter, msg message.Message) bool
}

// Use this to create your own plugin.
type GonePlugin struct {
	// The name of the plugin.
	Name string
	// The description of the plugin.
	Description string
	// The version of the plugin
	Version string
	// Handlers of the plugin.
	Handlers []GoneHandler
}

For example, the echo plugin, which detects message with /echo as prefix and with Message.IsToMe as true, and replies with the same message By the way, we are using our builtin rules to filter messages, Details:

package echo

import (
	"github.com/gonebot-dev/gonebot/adapter"
	"github.com/gonebot-dev/gonebot/message"
	"github.com/gonebot-dev/gonebot/plugin"
	"github.com/gonebot-dev/gonebot/plugin/rule"
)

var Echo plugin.GonePlugin

func init() {
	Echo.Name = "Echo"
	Echo.Version = "v0.0.1"
	Echo.Description = "Reply the same message of what you have sent"

	Echo.Handlers = append(Echo.Handlers, plugin.GoneHandler{
		Rules: rule.NewRules(rule.ToMe()).And(rule.Command("echo")),
		Handler: func(a *adapter.Adapter, msg message.Message) bool {
			reply := message.NewReply(msg).Join(msg)
			a.SendMessage(reply)
			return true
		},
	})
}

For the GoneHandler.Rules part, you shall use FilterBundle to get the results of the filters ANDed together. For example, a message must both satisfies rule.ToMe() and rule.Command([]string{"echo"}) to be parsed in this handler above. And the Rules can contain a bunch of FilterBundles, which results are ORed together. For the GoneHandler.Handler part, you will receive an Adapter and a Message. You can parse the message and send one or multiple reply by calling the Adapter.SendChannel.Push() method. You may notice that there is also an Adapter.ActionChannel, that is the channel to call the custom actions provided by the adapters, refer to action.go for how to create an action call. After calling the actions, the result will be pushed into the ActionCall.ResultChannel. We only support text, image, voice, video and file type of message currently, but don't be worry, the Adapters may provide some custom message types! After the Handler is done, it should return a boolean value to indicate whether the deliver process should continue. That means, if the handler returns false, the message will not be delivered to other handlers. And the order of the handlers depends on the order which you call gonebot.LoadPlugin to load the plugins

How to create an adapter

Creating an adapter is more than complicated, before that, you may need to read all the codes of gonebot to get a better understanding of how it works. And you can refer to OneBotV11 adapter to get an idea of how the adapters are written.

The logic of gonebot

How does gonebot work?

1. gonebot initialize: loading configuations and builtin message types.
2. First, the Adaptors will start their own goroutine in the background and push messages into their ReceiveChannels
3. Then gonebot will use a goroutine for each of the Adapters to automatically pull messages from ReceiveChannel and deliver them to plugins for processing.
4. Plugins will then process those messages and push some results into the SendChannels and ActionChannels
5. The Adaptors will fetch results from their own SendChannel and ActionChannel and send the results

TODO

• Docs about how to create a plugin.
• Docs about how to create an adapter.
• Dotenv configuation file support.
• Images message support.
• README_CN.
• Multiple adaptor support.
• Advanced context support.
• Plugin & Adapter repository.
• Project creater
• Make it perform better