rboot

README

Rboot

rboot 是一个使用 golang 写的，简单、高效的聊天机器人框架，易于扩展，它可以工作在不同的聊天服务上，并通过扩展脚本可实现 聊天、工作助手、服务监控、警报触发 等功能。

golang版本需求

golang v1.13+

快速创建自己的机器人

$ go get github.com/ghaoo/rboot
$ cd $GOPATH/github.com/ghaoo/rboot/robot
$ go build
$ ./robot

关于消息转接器

消息转接器是用来监听消息的传入和传出，通过消息转接器可以将聊天客户端的消息发送到机器人，经过脚本处理后返回消息发送给客户端。

rboot 提供了 命令行cli 微信网页版 企业微信 钉钉 倍洽 聊天转接器的简单实现。

关于脚本

Script 脚本并没有提供太多开箱即用的脚本，除了一个help脚本，其他的需要开发者根据自己的需求去开发。

help脚本用法：

!help <script>：查看脚本帮助信息，当命令不带脚本名称时会列出所有脚本帮助信息，带脚本名称只列出此脚本的帮助信息。

使用golang编写脚本

在文件夹 scripts 下有简单的脚本案例，开发者可查看脚本编写方法。

使用其他语言编写脚本

脚本 Script 不仅可以使用golang编写脚本，也可以使用脚本插件来执行系统命令或使用脚本语言编写的脚本文件。

脚本插件是用来解析脚本语言的Script插件，它是rboot脚本的一个扩展。通过yaml配置文件来执行系统命令或脚本。

因为脚本插件是建立在Script基础之上的，每个插件都会被注册到Script之中，所以确保脚本之间名称不要重叠，否则可能先注册的脚本会被后注册的脚本替换！

如何编写脚本插件

配置

• PLUGIN_DIR：脚本插件配置文件存放的文件夹，若不配置默认为plugins

快速开始

我们可以通过创建一个yaml文件来创建一个脚本插件，通过文件中的配置选项来实现对脚本插件的配置。比如我们创建一个 hello.yml 文件，它的内容如下：

name: hello
version: 0.1.0
ruleset:
    hello: "^hello"
usage:
    hi: echo hello world and 你好
description: 脚本插件示例
command:
    -
        cmd:
            - echo hi
            - echo hello world
    -
        dir: plugins
        cmd:
            - echo 你好

这个插件使用的是系统命令 echo。它的意思是：当我们输入“hello”后，脚本会返回 hi，hello world 和 你好 三条信息。

配置中各个字段的含义：

配置	必须	意义
name	是	插件名称
ruleset	是	规则集合
version	否	插件版本
usage	否	插件用法
description	否	插件简介
command	是	插件命令集
---	---	---
dir	否	命令执行文件夹
cmd	是	插件命令

command可配置多个命令集，执行顺序为从上到下依次执行

cmd可配置多条命令，执行顺序为从上到下依次执行

脚本插件支持系统命令和脚本语言。系统命令模式如上面的hello.yml，只需在文件中填写文件夹和系统命令，当你发出命令后，机器人就会从上到下依次执行。

脚本语言是建立在系统命令模式之上的执行方式，我们可以使用系统命令调用语言脚本，从而执行比较复杂的脚本。比如我们使用python输出“hello robot”。

我们的python脚本如下：

#!/usr/bin/env python

print("Hello, robot! i am a python script")

我们的配置文件如下：

name: pyscript
version: 0.1.0
ruleset:
    py: "^hello python"
usage:
    py: execute python script
description: python插件示例
command:
        dir: script
        cmd:
            - ./hello.py

当我们输入 hello python 时，机器人会调用 hello.py 脚本，脚本输出"Hello, robot! i am a python script"并通过机器人展示给我们。

在不同操作系统下请确认 目录分隔符 是否符合当前系统设置。 windows 下请使用 \ unix 下请使用 /

文档

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Index

• func DetectAdapter(name string) (adapterF, error)
• func DetectBrain(name string) (func() Brain, error)
• func LoadEnv(filenames ...string) (err error)
• func RegisterAdapter(name string, adp adapterF)
• func RegisterBrain(name string, m func() Brain)
• func RegisterScripts(name string, script Script)
• type Adapter
• type Brain
• type Header
  • func (h Header) Add(key, value string)
  • func (h Header) Del(key string)
  • func (h Header) Get(key string) string
  • func (h Header) GetKey(key string) []string
  • func (h Header) Set(key, value string)
• type Message
  • func NewMessage(content string, to ...string) *Message
  • func NewMessages(content string, to ...string) []*Message
  • func (m *Message) Bytes() []byte
  • func (m *Message) Cc() []string
  • func (m *Message) SetCc(to ...string)
  • func (m *Message) String() string
• type Regex
  • func (reg *Regex) Match(pattern, msg string) ([]string, bool)
• type Robot
  • func New() *Robot
  • func (bot *Robot) Find(bucket, key string) []byte
  • func (bot *Robot) Go()
  • func (bot *Robot) Incoming() chan *Message
  • func (bot *Robot) Outgoing(msg *Message)
  • func (bot *Robot) Remove(bucket, key string) error
  • func (bot *Robot) SendText(text string, to string)
  • func (bot *Robot) SetBrain(brain Brain)
  • func (bot *Robot) Stop()
  • func (bot *Robot) Store(bucket, key string, value []byte) error
  • func (bot *Robot) VerifySign(sign, secret, content, datetime string) error
• type Router
  • func (r *Router) Handle(path string, handler http.Handler) *route
  • func (r *Router) HandleFunc(path string, f func(http.ResponseWriter, *http.Request)) *route
  • func (r *Router) Use(mwf ...func(http.Handler) http.Handler)
• type Rule
• type Script
• type ScriptFunc
  • func DirectiveScript(name string) (ScriptFunc, error)

Functions

func DetectAdapter

func DetectAdapter(name string) (adapterF, error)

DetectAdapter 根据转接器名称获取转接器实例

func DetectBrain

func DetectBrain(name string) (func() Brain, error)

DetectBrain 获取名称为 name 的缓存器

func LoadEnv

func LoadEnv(filenames ...string) (err error)

LoadEnv 加载env配置

func RegisterAdapter

func RegisterAdapter(name string, adp adapterF)

RegisterAdapter 注册转接器，名称不可重复 转接器需实现 Adapter 接口

func RegisterBrain

func RegisterBrain(name string, m func() Brain)

RegisterBrain 注册存储器，名称须唯一 需实现Brain接口

func RegisterScripts

func RegisterScripts(name string, script Script)

RegisterScripts 注册脚本

Types

type Adapter

type Adapter interface {
	Incoming() chan *Message // 接收到的消息
	Outgoing() chan *Message // 回复的消息
}

Adapter 是管理聊天转接器进出消息的接口

type Brain

type Brain interface {
	Set(bucket, key string, value []byte) error
	Get(bucket, key string) []byte
	Remove(bucket, key string) error
}

Brain 是Rboot缓存器实现的接口

type Header

type Header map[string][]string

Header 消息附带的头信息，键-值对

func (Header) Add

func (h Header) Add(key, value string)

Add 将键、值对添加到Header，附加到与键关联的现有值

func (Header) Del

func (h Header) Del(key string)

Del 删除与键关联的值

func (Header) Get

func (h Header) Get(key string) string

Get 从头信息中获取与给定键关联的第一个值

func (Header) GetKey

func (h Header) GetKey(key string) []string

GetKey 从头信息中获取与给定键关联的多个值

func (Header) Set

func (h Header) Set(key, value string)

Set 将key设置为单个值，它替换与key的现有值

type Message

type Message struct {
	To         string    // 消息接收者
	From       string    // 消息来源
	Sender     string    // 发送者
	Header     Header    // 头信息
	KeepHeader bool      // 如果为true则传入消息的Header在一次会话结束之前不会清除
	Body       io.Reader // 消息主体
}

Message 表示一个消息的结构

func NewMessage

func NewMessage(content string, to ...string) *Message

NewMessage 新建一条消息

func NewMessages

func NewMessages(content string, to ...string) []*Message

NewMessages 新建一组消息

func (*Message) Bytes

func (m *Message) Bytes() []byte

Bytes 读取消息内容为 []byte

func (*Message) Cc

func (m *Message) Cc() []string

Cc 返回消息抄送信息

func (*Message) SetCc

func (m *Message) SetCc(to ...string)

SetCc 为消息设置抄送

func (*Message) String

func (m *Message) String() string

String 读取消息内容为 string

type Regex

type Regex struct{}

Regex 正则消息处理器

func (*Regex) Match

func (reg *Regex) Match(pattern, msg string) ([]string, bool)

Match 当匹配失败时返回 false，返回true证明匹配成功并返回消息的匹配文本和子表达式的匹配

type Robot

type Robot struct {
	Router *Router
	Brain  Brain
	// contains filtered or unexported fields
}

Robot 是 rboot 的一个实例，它包含了聊天转接器，规则处理器，缓存器，路由适配器和消息的进出通道

func New

func New() *Robot

New 获取一个Robot实例，

func (*Robot) Find

func (bot *Robot) Find(bucket, key string) []byte

Find 从储存器中获取指定的bucket和key对应的信息

func (*Robot) Go

func (bot *Robot) Go()

Go 皮皮虾，我们走~~~~~~~~~

func (*Robot) Incoming

func (bot *Robot) Incoming() chan *Message

Incoming 获取传入消息通道

func (*Robot) Outgoing

func (bot *Robot) Outgoing(msg *Message)

Outgoing 发送消息

func (*Robot) Remove

func (bot *Robot) Remove(bucket, key string) error

Remove 从储存器中移除指定的bucket和key对应的信息

func (*Robot) SendText

func (bot *Robot) SendText(text string, to string)

SendText 发送文本消息

func (*Robot) SetBrain

func (bot *Robot) SetBrain(brain Brain)

SetBrain 设置储存器

func (*Robot) Stop

func (bot *Robot) Stop()

Stop 皮皮虾，快停下~~~~~~~~~

func (*Robot) Store

func (bot *Robot) Store(bucket, key string, value []byte) error

Store 向储存器中存入信息

func (*Robot) VerifySign

func (bot *Robot) VerifySign(sign, secret, content, datetime string) error

验证签名

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router 包含了路由处理器 mux 和已经注册的所有路由集合，支持中间件

func (*Router) Handle

func (r *Router) Handle(path string, handler http.Handler) *route

Handle 为路径 path 注册一个新路由

func (*Router) HandleFunc

func (r *Router) HandleFunc(path string, f func(http.ResponseWriter, *http.Request)) *route

HandleFunc 为路径 path 注册一个新的路由处理函数

func (*Router) Use

func (r *Router) Use(mwf ...func(http.Handler) http.Handler)

Use 注册中间件，和 *mux.Router.Use 用法相同

type Rule

type Rule interface {
	Match(pattern, msg string) ([]string, bool)
}

Rule 消息处理器接口，暂时只支持正则

type Script

type Script struct {
	Action      ScriptFunc        // 执行解析或一些必要加载
	Ruleset     map[string]string // 脚本规则集合
	Usage       map[string]string // 帮助信息
	Description string            // 简介
}

Script 脚本结构体

type ScriptFunc

type ScriptFunc func(bot *Robot, incoming *Message) []*Message

SetupFunc 脚本执行或解析函数 - bot: A Robot instance - incoming: The incoming message

func DirectiveScript

func DirectiveScript(name string) (ScriptFunc, error)

DirectiveScript 根据脚本名称获取脚本执行函数