qqbot

README

qqbot

qqbot 是一个的 QQ Bot Go 库，目标是嵌入其他 Go 服务并支持：

• 主动发送消息
• 接收消息并分发 slash 命令
• 在同一会话内按被动回复语义连续回消息

当前版本提供这几个稳定入口：

• App.Send
• App.Command
• App.OnText
• App.Run
• Conversation.Respond / RespondText

最小发送示例

app, err := qqbot.New(qqbot.Settings{
    AppID:        "你的 AppID",
    AppSecret:    "你的 AppSecret",
})
if err != nil {
    panic(err)
}

_, err = app.Send(context.Background(), qqbot.Delivery{
    To: qqbot.Recipient{
        Kind: qqbot.DirectRecipient,
        ID:   "user_openid",
    },
    Kind: qqbot.PlainText,
    Body: "hello",
})

命令机器人示例

app, _ := qqbot.New(qqbot.Settings{
    AppID:        "你的 AppID",
    AppSecret:    "你的 AppSecret",
})

app.Command("status", func(ctx context.Context, c qqbot.Conversation, cmd qqbot.ParsedCommand) error {
    _, err := c.RespondText(ctx, "服务正常")
    return err
})

app.OnText(func(ctx context.Context, c qqbot.Conversation) error {
    _, err := c.RespondText(ctx, "请使用 /status")
    return err
})

_ = app.Run(context.Background())

Documentation

Index

• type App
  • func New(settings Settings, opts ...Option) (*App, error)
  • func (a *App) Close() error
  • func (a *App) Command(name string, handler CommandHandler)
  • func (a *App) OnText(handler TextHandler)
  • func (a *App) Run(ctx context.Context) error
  • func (a *App) Send(ctx context.Context, delivery Delivery) (Receipt, error)
• type CommandHandler
• type Conversation
• type Delivery
• type Incoming
• type IncomingKind
• type MessageKind
• type Option
  • func WithDedupWindow(window time.Duration) Option
  • func WithIntents(intents int) Option
  • func WithPrefix(prefix string) Option
  • func WithRetry(count int, delay time.Duration) Option
  • func WithUnknownCommand(handler CommandHandler) Option
• type ParsedCommand
• type Receipt
• type Recipient
• type RecipientKind
• type ReplyContext
• type Settings
• type TextHandler

Types

type App

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

func New

func New(settings Settings, opts ...Option) (*App, error)

func (*App) Close

func (a *App) Close() error

func (*App) Command

func (a *App) Command(name string, handler CommandHandler)

func (*App) OnText

func (a *App) OnText(handler TextHandler)

func (*App) Run

func (a *App) Run(ctx context.Context) error

func (*App) Send

func (a *App) Send(ctx context.Context, delivery Delivery) (Receipt, error)

type CommandHandler

type CommandHandler func(context.Context, Conversation, ParsedCommand) error

type Conversation

type Conversation interface {
	Incoming() Incoming
	Respond(ctx context.Context, delivery Delivery) (Receipt, error)
	RespondText(ctx context.Context, text string) (Receipt, error)
}

type Delivery

type Delivery struct {
	To    Recipient
	Kind  MessageKind
	Body  string
	Reply *ReplyContext
}

type Incoming

type Incoming struct {
	ID   string
	Kind IncomingKind
	From string
	To   Recipient
	Text string
	At   time.Time
	Raw  json.RawMessage
}

type IncomingKind

type IncomingKind string

const (
	DirectMessage IncomingKind = "direct_message"
	GroupMention  IncomingKind = "group_mention"
)

type MessageKind

type MessageKind string

const (
	PlainText MessageKind = "text"
	Markdown  MessageKind = "markdown"
)

type Option

type Option func(*options)

func WithDedupWindow

func WithDedupWindow(window time.Duration) Option

func WithIntents

func WithIntents(intents int) Option

func WithPrefix

func WithPrefix(prefix string) Option

func WithRetry

func WithRetry(count int, delay time.Duration) Option

func WithUnknownCommand

func WithUnknownCommand(handler CommandHandler) Option

type ParsedCommand

type ParsedCommand struct {
	Name     string
	Params   []string
	Original string
}

type Receipt

type Receipt struct {
	ID string
	At time.Time
}

type Recipient

type Recipient struct {
	Kind RecipientKind
	ID   string
}

type RecipientKind

type RecipientKind string

const (
	DirectRecipient  RecipientKind = "direct"
	GroupRecipient   RecipientKind = "group"
	ChannelRecipient RecipientKind = "channel"
)

type ReplyContext

type ReplyContext struct {
	MessageID string
	Sequence  int
	EventID   string
}

type Settings

type Settings struct {
	AppID         string
	AppSecret     string
	TokenEndpoint string
	BaseEndpoint  string
	Timeout       time.Duration
	DefaultKind   MessageKind
	HTTPClient    *http.Client
	Logger        *slog.Logger
}

type TextHandler

type TextHandler func(context.Context, Conversation) error