botgo

README

BotGo Plus

基于 github.com/WindowsSov8forUs/botgo-plus 的增强版 SDK。

本库最初作为 WindowsSov8forUs/GlycCat 的内部库使用，现已独立维护，并补充了富媒体格式适配能力（image/mp4/silk）。

改动来源

本项目中的以下能力，来源于 WindowsSov8forUs/GlycCat（pkg/botgo）的内部实现沉淀：

• OpenAPI v1 + v2 双版本实现
• WebhookManager 与 webhook server 实现
• 新版 token 结构（token.BotToken(appID, appSecret, token, token.TypeQQBot)）
• 本地/多实例会话管理能力（默认本地，不依赖 Redis）

快速开始

1. 创建 Token 与 OpenAPI 客户端

package main

import (
    "context"
    "log"
    "time"

    "github.com/WindowsSov8forUs/botgo-plus"
    "github.com/WindowsSov8forUs/botgo-plus/openapi"
    "github.com/WindowsSov8forUs/botgo-plus/token"
)

func main() {
    ctx := context.Background()

    tk := token.BotToken(
        1234567890,          // appID
        "app-secret",       // appSecret
        "bot-token",        // bot token
        token.TypeQQBot,
    )
    if err := tk.InitToken(ctx); err != nil {
        log.Fatal(err)
    }

    if err := botgo.SelectOpenAPIVersion(openapi.APIv2); err != nil {
        log.Fatal(err)
    }

    api := botgo.NewOpenAPI(tk).WithTimeout(10 * time.Second)
    me, err := api.Me(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("bot user: %+v", me)
}

2. WebSocket 模式

package main

import (
    "context"
    "log"

    "github.com/WindowsSov8forUs/botgo-plus"
    "github.com/WindowsSov8forUs/botgo-plus/dto"
    "github.com/WindowsSov8forUs/botgo-plus/event"
    "github.com/WindowsSov8forUs/botgo-plus/token"
    "github.com/WindowsSov8forUs/botgo-plus/websocket"
)

func main() {
    ctx := context.Background()
    tk := token.BotToken(1234567890, "app-secret", "bot-token", token.TypeQQBot)
    _ = tk.InitToken(ctx)

    api := botgo.NewOpenAPI(tk)
    wsInfo, err := api.WS(ctx, nil, "")
    if err != nil {
        log.Fatal(err)
    }

    var atHandler event.ATMessageEventHandler = func(evt *dto.Payload, data *dto.ATMessageData) error {
        log.Printf("AT message: %s", data.Content)
        return nil
    }

    intent := websocket.RegisterHandlers(atHandler)
    if err := botgo.NewSessionManager().Start(wsInfo, tk, &intent); err != nil {
        log.Fatal(err)
    }
}

Webhook 使用（重点）

WebhookManager.Start 是阻塞调用，通常建议在 goroutine 中启动。

package main

import (
    "log"

    "github.com/WindowsSov8forUs/botgo-plus"
    "github.com/WindowsSov8forUs/botgo-plus/dto"
    "github.com/WindowsSov8forUs/botgo-plus/event"
    "github.com/WindowsSov8forUs/botgo-plus/webhook"
)

func main() {
    var groupHandler event.GroupATMessageEventHandler = func(evt *dto.Payload, data *dto.GroupATMessageData) error {
        log.Printf("group at message: %s", data.Content)
        return nil
    }

    // 兼容入口，内部等价于 event.RegisterHandlers(...)
    webhook.RegisterHandlers(groupHandler)

    cfg := &dto.Config{
        Host:      "0.0.0.0",
        Port:      9000,
        Path:      "/qqbot/callback",
        AppId:     1234567890,
        BotSecret: "app-secret",
    }

    go func() {
        if err := botgo.NewWebhookManager().Start(cfg); err != nil {
            log.Printf("webhook stopped: %v", err)
        }
    }()

    select {}
}

Webhook 配置要点

• 必须先注册事件处理器，再启动 WebhookManager。
• 平台配置的回调地址要与 Host/Port/Path 对应。
• 对外建议通过 HTTPS 反向代理暴露 webhook（SDK 内置 HTTP 服务，不直接处理 TLS 证书）。
• SDK 会校验回调签名和 X-Bot-Appid。

富媒体格式适配扩展

本仓库新增了文件类型适配层，已接入：

• openapi/v1 和 openapi/v2 的 PostGroupMessage / PostC2CMessage

行为说明：

• 仅当消息类型为 RichMediaMessage 且包含 file_data 时触发。
• 按 file_type 自动适配：
• 1 图片：转为平台支持的图片格式（png/jpg/gif）
• 2 视频：转为 mp4（H264/AAC）
• 3 语音：转为 silk（已支持 amr/silk 直传）
• 若源文件已是支持格式，不会重复转换。

依赖说明：

• 视频/音频转换依赖本机 ffmpeg
• silk 编解码器位于 pkg/silk/exec/

Redis 说明

• 默认 SessionManager 为本地实现，不依赖 Redis。
• Redis 仅用于 sessions/remote 分布式场景。
• Redis 相关测试默认跳过；设置 BOTGO_REDIS_TEST=1 才会执行。

开发

• 开发说明见 DEVELOP.md
• 基础自测命令：

go test ./...

Documentation

Overview

Package botgo 是一个QQ频道机器人 sdk 的 golang 实现

Index

• func NewOpenAPI(token *token.Token) openapi.OpenAPI
• func NewSandboxOpenAPI(token *token.Token) openapi.OpenAPI
• func SelectOpenAPIVersion(version openapi.APIVersion) error
• func SetLogger(logger log.Logger)
• func SetOpenAPIClient(v openapi.APIVersion, c openapi.OpenAPI)
• func SetSessionManager(m SessionManager)
• func SetWebhookServer(s webhook.WebHook)
• func SetWebsocketClient(c websocket.WebSocket)
• type SessionManager
  • func NewSessionManager() SessionManager
• type WebhookManager
  • func NewWebhookManager() WebhookManager

Functions

func NewOpenAPI

func NewOpenAPI(token *token.Token) openapi.OpenAPI

NewOpenAPI 创建新的 openapi 实例，会返回当前的 openapi 实现的实例 如果需要使用其他版本的实现，需要在调用这个方法之前调用 SelectOpenAPIVersion 方法

func NewSandboxOpenAPI

func NewSandboxOpenAPI(token *token.Token) openapi.OpenAPI

NewSandboxOpenAPI 创建测试环境的 openapi 实例

func SelectOpenAPIVersion

func SelectOpenAPIVersion(version openapi.APIVersion) error

SelectOpenAPIVersion 指定使用哪个版本的 api 实现，如果不指定，sdk将默认使用第一个 setup 的 api 实现

func SetLogger

func SetLogger(logger log.Logger)

SetLogger 设置 logger，需要实现 sdk 的 log.Logger 接口

func SetOpenAPIClient

func SetOpenAPIClient(v openapi.APIVersion, c openapi.OpenAPI)

SetOpenAPIClient 注册 openapi 的不同实现，需要设置版本

func SetSessionManager

func SetSessionManager(m SessionManager)

SetSessionManager 注册自己实现的 session manager

func SetWebhookServer

func SetWebhookServer(s webhook.WebHook)

SetWebhookServer 替换 webhook 实现

func SetWebsocketClient

func SetWebsocketClient(c websocket.WebSocket)

SetWebsocketClient 替换 websocket 实现

Types

type SessionManager

type SessionManager interface {
	// Start 启动连接，默认使用 apInfo 中的 shards 作为 shard 数量，如果有需要自己指定 shard 数，请修 apInfo 中的信息
	Start(apInfo *dto.WebsocketAP, token *token.Token, intents *dto.Intent) error
	// 自己指定具体的shard
	StartSingle(apInfo *dto.WebsocketAPSingle, token *token.Token, intents *dto.Intent) error
}

SessionManager 接口，管理session

func NewSessionManager

func NewSessionManager() SessionManager

NewSessionManager 获得 session manager 实例

type WebhookManager

type WebhookManager interface {
	// Start 启动 webhook
	Start(config *dto.Config) error
}

WebhookManager 接口，管理 webhook

func NewWebhookManager

func NewWebhookManager() WebhookManager

NewWebhookManager 获得 webhook manager 实例