Golang跨平台聊天机器人开发框架插件库go-sarah的使用

介绍

Sarah是一个通用机器人框架，以作者第一个女儿的名字命名。它提供了"有状态命令"等独特功能，以及命令和定时任务等基本功能。此外，该项目还提供丰富的生命周期管理功能，包括实时配置更新、可定制的警报机制、自动命令/任务(重新)构建和防panic的并发命令/任务执行。

重要通知

v4版本发布

这是go-sarah的第四个主要版本，包含一些架构变更：

• sarah.NewBot现在返回单个值：sarah.Bot
• 包括logger、retry和worker在内的实用包现在由github.com/oklahomer/go-kasumi托管

支持的聊天服务/协议

虽然开发者可以实现sarah.Adapter来集成所需的聊天服务，但项目提供了一些适配器作为参考实现：

• Slack
• Gitter
• XMPP
• LINE

快速入门

一般命令执行

上图展示了go-sarah的一般用法。注册的命令会检查用户输入，匹配的命令会被执行；当用户输入".hello"时，hello命令执行并返回"Hello, 世界"消息。

有状态命令执行

下图展示了带有用户对话上下文的命令如何工作。"用户对话上下文"的想法和实现是go-sarah的标志性功能，使机器人命令具有"状态感知"能力。

示例代码

以下是实现上述一般命令和有状态命令的最小代码示例。这个例子展示了两种实现sarah.Command的方式：一种是直接实现sarah.Command接口；另一种使用sarah.CommandPropsBuilder进行延迟构造。

主程序

package main

import (
	"context"
	"fmt"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	
	"os"
	"os/signal"
	"syscall"
	
	// 下面的包在init()中注册命令
	// 使用空白标识符导入即可实现
	_ "guess"
	_ "hello"
)

func main() {
	// 设置Slack适配器
	setupSlack()
	
	// 准备Sarah的核心上下文
	ctx, cancel := context.WithCancel(context.Background())

	// 运行
	config := sarah.NewConfig()
	err := sarah.Run(ctx, config)
	if err != nil {
		panic(fmt.Errorf("failed to run: %s", err.Error()))
	}
	
	// 当收到信号时停止
	c := make(chan os.Signal, 1)
   	signal.Notify(c, syscall.SIGTERM)
   	select {
   	case <-c:
   		cancel()
   	}
}

func setupSlack() {
	// 设置slack适配器
	slackConfig := slack.NewConfig()
	slackConfig.Token = "REPLACE THIS"
	adapter, err := slack.NewAdapter(slackConfig, slack.WithRTMPayloadHandler(slack.DefaultRTMPayloadHandler))
	if err != nil {
		panic(fmt.Errorf("faileld to setup Slack Adapter: %s", err.Error()))
	}

	// 设置可选存储，以便存储对话上下文
	cacheConfig := sarah.NewCacheConfig()
	storage := sarah.NewUserContextStorage(cacheConfig)

	// 使用Slack适配器和默认存储设置机器人
	bot := sarah.NewBot(adapter, sarah.BotWithStorage(storage))
	
	sarah.RegisterBot(bot)
}

猜数字命令实现

package guess

import (
	"context"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	"math/rand"
	"strconv"
	"strings"
	"time"
)

func init() {
	sarah.RegisterCommandProps(props)
}

var props = sarah.NewCommandPropsBuilder().
	BotType(slack.SLACK).
	Identifier("guess").
	Instruction("Input .guess to start a game.").
	MatchFunc(func(input sarah.Input) bool {
		return strings.HasPrefix(strings.TrimSpace(input.Message()), ".guess")
	}).
	Func(func(ctx context.Context, input sarah.Input) (*sarah.CommandResponse, error) {
		// 在开始时生成答案值
		rand.Seed(time.Now().UnixNano())
		answer := rand.Intn(10)

		// 让用户猜测正确答案
		return slack.NewResponse(input, "Input number.", slack.RespWithNext(func(c context.Context, i sarah.Input) (*sarah.CommandResponse, error){
			return guessFunc(c, i, answer)
		}))
	}).
	MustBuild()

func guessFunc(_ context.Context, input sarah.Input, answer int) (*sarah.CommandResponse, error) {
	// 为了方便，创建一个递归调用guessFunc的函数，直到用户输入正确答案
	retry := func(c context.Context, i sarah.Input) (*sarah.CommandResponse, error) {
		return guessFunc(c, i, answer)
	}

	// 检查用户是否输入了有效数字
	guess, err := strconv.Atoi(strings.TrimSpace(input.Message()))
	if err != nil {
		return slack.NewResponse(input, "Invalid input format.", slack.RespWithNext(retry))
	}

	// 如果猜对了，告诉用户并结束当前用户上下文
	// 否则，让用户输入下一个猜测并给出提示
	if guess == answer {
		return slack.NewResponse(input, "Correct!")
	} else if guess > answer {
		return slack.NewResponse(input, "Smaller!", slack.RespWithNext(retry))
	} else {
		return slack.NewResponse(input, "Bigger!", slack.RespWithNext(retry))
	}
}

Hello命令实现

package hello

import (
	"context"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	"strings"
)

func init() {
    sarah.RegisterCommand(slack.SLACK, &command{})	
}

type command struct {
}

var _ sarah.Command = (*command)(nil)

func (hello *command) Identifier() string {
	return "hello"
}

func (hello *command) Execute(_ context.Context, i sarah.Input) (*sarah.CommandResponse, error) {
	return slack.NewResponse(i, "Hello!")
}

func (hello *command) Instruction(input *sarah.HelpInput) string {
	if 12 < input.SentAt().Hour() {
		// 此命令仅在上午活动
		// 下午不显示指令
		return ""
	}
	return "Input .hello to greet"
}

func (hello *command) Match(input sarah.Input) bool {
	return strings.TrimSpace(input.Message()) == ".hello"
}

支持的Golang版本

官方发布策略规定"每个主要的Go版本支持到有两个更新的主要版本发布为止"。遵循这一策略有助于本项目享受后续版本中的改进。然而，并非所有项目都能立即切换到新环境。特别是当本项目在新的主要Go版本发布后立即切断对旧版本的支持时，迁移可能会特别困难。

作为过渡期，本项目比Go项目多支持一个旧版本。这样的版本保证会列在.travis.ci中。换句话说，1.10中引入的新功能/接口只有等到1.12发布后才能在本项目中使用。