README
¶
AnyBot
AnyBot 是一个 Go 实现的聊天机器人框架，当前内置 OneBot v11 适配器。
安装
go get github.com/tty00a381/anybot
go install github.com/tty00a381/anybot/cmd/anybot@latest
本仓库使用 Go 1.24。
快速开始
本指南假设你已经有一个 OneBot v11 协议端了。如果没有，可以试试 NapCat。
先生成一个最小项目：
anybot init -module example.com/bot -dir ./mybot
cd ./mybot
go mod tidy
anybot doctor
go run .
生成的项目默认使用反向 WebSocket，地址 ws://127.0.0.1:6700。请在协议端启用反向 WebSocket，填入上述地址。
如果启用了访问令牌，AnyBot 和协议端要使用同一个令牌：
export ONEBOT_ACCESS_TOKEN=你的令牌
最小代码
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/tty00a381/anybot"
"github.com/tty00a381/anybot/adapters/onebot11"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
app := anybot.New(
anybot.WithAdapter(onebot11.ReverseWS("127.0.0.1:6700",
onebot11.WithAccessToken(os.Getenv("ONEBOT_ACCESS_TOKEN")),
)),
)
app.Use(anybot.Recover(), anybot.Trace())
app.Command("ping").Handle(func(c *anybot.Context) error {
_, err := c.ReplyText("pong")
return err
})
if err := app.Run(ctx); err != nil && ctx.Err() == nil {
log.Fatal(err)
}
}
一些概念
App：一个机器人进程。适配器、路由、中间件、插件等所有组件，都挂在它上面。Route：一条处理规则。规则匹配后，即执行你编写的处理函数。Context：处理函数的工具箱。事件、接口调用、会话状态、路由结果等都从这里拿。Event：AnyBot 整理过的事件。包含一些常用字段，必要时也能取回原始事件。message.Chain：一条要发送的消息。由message.Segment组成。Plugin：一组可以手动安装的路由、中间件或 hook。
写路由
路由就是「什么事件交给什么函数处理」。常见写法有命令、正则、普通消息规则：
app.Command("echo").Handle(func(c *anybot.Context) error {
_, err := c.ReplyText(c.Args())
return err
})
app.Regex(`^复读\s+(.+)$`).Handle(func(c *anybot.Context) error {
matches := c.Match().Vars["matches"].([]string)
_, err := c.ReplyText(matches[1])
return err
})
app.OnMessage(anybot.ToMe(), anybot.Contains("帮助")).Handle(func(c *anybot.Context) error {
_, err := c.ReplyText("我在")
return err
})
常用规则有 Private、Group、FromUser、InGroup、Mentioned、ToMe、Contains、Prefix、All、AnyOf 和 Not。
处理函数里可以用 c.Stop() 不再让后面的路由处理这条事件，也可以 return c.Pass() 跳过当前路由，让后面的路由继续。
中间件 & 事件顺序
中间件放在处理函数外层，适合做日志、panic 恢复、超时、权限检查、限速等通用功能：
app.Use(
anybot.Recover(),
anybot.Trace(),
anybot.Timeout(10*time.Second),
anybot.RateLimit(5, time.Minute),
)
app.Command("admin").
Use(anybot.OnlyGroup(), anybot.SuperUser("10000")).
Handle(func(c *anybot.Context) error {
_, err := c.ReplyText("权限正常")
return err
})
AnyBot 默认并发处理事件。如果某个会话里的多条消息必须按顺序处理，如多轮问答、表单收集等临时事务，则可以启用会话串行：
app := anybot.New(
anybot.WithAdapter(adapter),
anybot.WithSerialByConversation(),
)
保存会话状态
默认的内存存储，支持过期时间，适合保存短期状态。Context 提供三个常用入口：
c.Session() // 当前会话
c.UserSession() // 当前用户
c.GroupSession() // 当前群或频道
若需要把状态放进数据库，请实现 Store 接口后通过 WithStore 传给 App。
OneBot v11 适配器
adapters/onebot11 支持三种连接方式：
onebot11.ReverseWS("127.0.0.1:6700")
onebot11.WebSocket("ws://127.0.0.1:6701")
onebot11.HTTP("http://127.0.0.1:3000", "127.0.0.1:6702")
推荐优先使用反向 WebSocket，即 AnyBot 监听端口、OneBot v11 协议端主动连进来。WebSocket 连接状态可以通过 hook 观察：
adapter := onebot11.ReverseWS("127.0.0.1:6700",
onebot11.WithConnectionHook(func(ctx context.Context, event onebot11.ConnectionEvent) {
slog.Info("连接状态变化", "state", event.State, "transport", event.Transport)
}),
)
常用 OneBot v11 接口已经封装成 Go 方法，如发送消息、撤回消息、读取登录信息、读取好友和群列表、管理群成员、处理加好友或加群请求、检查媒体能力、读取版本状态、操作群文件等。对于未封装的接口，可以直接用 Call 或 CallRaw。
client := onebot11.MustClient(c)
info, err := client.GetLoginInfo(c.Context)
if err != nil {
return err
}
_, err = c.ReplyText(info.Nickname)
return err
NapCat 额外提供的接口放在
adapters/onebot11/napcat，避免和标准 OneBot v11 方法混在一起。其他协议端如果也有扩展能力，可以按同样思路放在独立包里。api := napcat.New(c.Client()) history, err := api.GetGroupMessageHistory(c.Context, c.GroupID(), 0, 20)
发送消息
业务代码可以先拼一条消息，再让当前事件的自然目标接收它：
chain := message.New(
message.Reply(c.Event().ID),
message.Text("你好"),
message.At(c.UserID()),
message.Image("file:///tmp/a.png"),
)
_, err := c.Reply(chain)
OneBot v11 适配器会把这条消息转成 OneBot 消息段。需要 OneBot v11 特有消息段时，可以使用 onebot11.JSON、onebot11.XML、onebot11.Share、onebot11.Node 等构造器。
插件
插件是一组可以手动安装的路由、中间件或 hook。
CLI 可以生成插件骨架：
anybot new plugin hello
插件就是普通类型，请显式安装到 App 上。
type helloPlugin struct{}
func (helloPlugin) Manifest() anybot.Manifest {
return anybot.Manifest{Name: "hello", Version: "1.0.0"}
}
func (helloPlugin) Install(app *anybot.App) error {
app.Command("hello").Handle(func(c *anybot.Context) error {
_, err := c.ReplyText("world")
return err
})
return nil
}
安装插件：
if err := app.UsePlugins(helloPlugin{}); err != nil {
log.Fatal(err)
}
仓库内置了少量示例插件：
plugins/help、plugins/echo、plugins/admin、plugins/ratelimit。
CLI
anybot init [-module 模块名] [-dir 目录] [-force]
anybot run [go run 参数...]
anybot new plugin <名称> [-dir 目录] [-force]
anybot doctor [-config anybot.yaml] [-connect]
anybot version
示例
examples/ping：最小 ping 机器人。examples/reversews：反向 WebSocket 接入。examples/websocket：正向 WebSocket。examples/httpaction：HTTP 接口调用 & 事件回调。examples/media：登录信息读取 & 图片发送。examples/pluginbot：显式插件。examples/permission：权限控制 & 限速。examples/session：会话状态。
发布
本地开发测试：
make check
发布前检查：
make release-check
Documentation
¶
Overview ¶
anybot 包提供机器人运行时、事件路由、中间件、会话存储、插件生命周期和协议适配核心。
Index ¶
- Variables
- func Configure(opts ...Option)
- func OnError(handler ErrorHandler)
- func OnReady(hook Hook)
- func OnShutdown(hook Hook)
- func OnStart(hook Hook)
- func OnStop(hook Hook)
- func ResetDefault(opts ...Option)
- func Run(ctxs ...context.Context) error
- func Use(middleware ...Middleware)
- func UsePlugin(plugin Plugin) error
- func UsePlugins(plugins ...Plugin) error
- type ActionClient
- type ActionError
- type ActionResponse
- type Adapter
- type App
- func (a *App) Adapter() Adapter
- func (a *App) Client() ActionClient
- func (a *App) Command(names ...string) *Route
- func (a *App) Dispatch(ctx context.Context, event *Event) error
- func (a *App) Group(rules ...Rule) *Router
- func (a *App) Logger() *slog.Logger
- func (a *App) On(rules ...Rule) *Route
- func (a *App) OnError(handler ErrorHandler)
- func (a *App) OnMessage(rules ...Rule) *Route
- func (a *App) OnReady(hook Hook)
- func (a *App) OnShutdown(hook Hook)
- func (a *App) OnStart(hook Hook)
- func (a *App) OnStop(hook Hook)
- func (a *App) Plugins() []Manifest
- func (a *App) Regex(pattern string) *Route
- func (a *App) Router() *Router
- func (a *App) Run(ctx context.Context) error
- func (a *App) Store() Store
- func (a *App) Use(middleware ...Middleware)
- func (a *App) UsePlugin(plugin Plugin) error
- func (a *App) UsePlugins(plugins ...Plugin) error
- type Context
- func (c *Context) Adapter() Adapter
- func (c *Context) App() *App
- func (c *Context) Args() string
- func (c *Context) Argv() []string
- func (c *Context) Client() ActionClient
- func (c *Context) Command() string
- func (c *Context) ConversationID() string
- func (c *Context) Event() *Event
- func (c *Context) Get(key string) (any, bool)
- func (c *Context) GroupID() string
- func (c *Context) GroupSession() *Session
- func (c *Context) IsGroup() bool
- func (c *Context) IsPrivate() bool
- func (c *Context) Logger() *slog.Logger
- func (c *Context) Match() Match
- func (c *Context) Pass() error
- func (c *Context) RawEvent() any
- func (c *Context) Reply(chain message.Chain) (MessageReceipt, error)
- func (c *Context) ReplyText(text string) (MessageReceipt, error)
- func (c *Context) Route() *Route
- func (c *Context) RouteName() string
- func (c *Context) SelfID() string
- func (c *Context) Session() *Session
- func (c *Context) SessionBy(key string) *Session
- func (c *Context) Set(key string, value any)
- func (c *Context) Stop()
- func (c *Context) StopError() error
- func (c *Context) Stopped() bool
- func (c *Context) Store() Store
- func (c *Context) String(key string) string
- func (c *Context) Target() ReplyTarget
- func (c *Context) Text() string
- func (c *Context) UserID() string
- func (c *Context) UserSession() *Session
- type EmitFunc
- type ErrorHandler
- type Event
- type EventKeyFunc
- type Handler
- type Hook
- type Manifest
- type Match
- type MemoryStore
- func (s *MemoryStore) Delete(ctx context.Context, key string) error
- func (s *MemoryStore) Get(ctx context.Context, key string) ([]byte, bool, error)
- func (s *MemoryStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
- func (s *MemoryStore) Sweep(ctx context.Context) error
- type MessageReceipt
- type Middleware
- func OnlyGroup() Middleware
- func OnlyPrivate() Middleware
- func RateLimit(limit int, window time.Duration) Middleware
- func RateLimitBy(limit int, window time.Duration, keyFunc func(*Context) string) Middleware
- func Recover(loggers ...*slog.Logger) Middleware
- func SuperUser(ids ...any) Middleware
- func Timeout(timeout time.Duration) Middleware
- func Trace(loggers ...*slog.Logger) Middleware
- type Option
- func WithAdapter(adapter Adapter) Option
- func WithBuffer(size int) Option
- func WithErrorHandler(handler ErrorHandler) Option
- func WithLogger(logger *slog.Logger) Option
- func WithSerialBy(fn EventKeyFunc) Option
- func WithSerialByConversation() Option
- func WithStore(store Store) Option
- func WithWorkers(workers int) Option
- type PanicError
- type Plugin
- type PluginFunc
- type Protocol
- type ReplyTarget
- type Route
- type Router
- type Rule
- func All(rules ...Rule) Rule
- func Any() Rule
- func AnyOf(rules ...Rule) Rule
- func CommandRule(names ...string) Rule
- func CommandWithPrefixes(prefixes []string, names ...string) Rule
- func Contains(substr string) Rule
- func DetailType(kind string) Rule
- func EventType(kind string) Rule
- func FromSelf() Rule
- func FromUser(ids ...any) Rule
- func Group() Rule
- func InGroup(ids ...any) Rule
- func Mentioned(ids ...any) Rule
- func MessageEvent() Rule
- func Not(rule Rule) Rule
- func NotFromSelf() Rule
- func Prefix(prefix string) Rule
- func Private() Rule
- func RegexRule(pattern string) Rule
- func RegexpRule(re *regexp.Regexp) Rule
- func ToMe() Rule
- type RuleFunc
- type Session
- func (s *Session) Delete(ctx context.Context, name string) error
- func (s *Session) Get(ctx context.Context, name string) ([]byte, bool, error)
- func (s *Session) Key() string
- func (s *Session) LoadJSON(ctx context.Context, name string, out any) (bool, error)
- func (s *Session) SaveJSON(ctx context.Context, name string, value any, ttl time.Duration) error
- func (s *Session) Set(ctx context.Context, name string, value []byte, ttl time.Duration) error
- type Store
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrPass 表示当前路由主动让出处理权，后续路由继续匹配。 ErrPass = errors.New("anybot: pass route") // ErrStop 表示当前事件应停止向后续路由传播。 ErrStop = errors.New("anybot: stop route") ErrUnauthorized = errors.New("anybot: unauthorized") // ErrRateLimited 表示当前限速窗口已被耗尽。 ErrRateLimited = errors.New("anybot: rate limited") )
Functions ¶
Types ¶
type ActionClient ¶
type ActionClient interface {
Call(context.Context, string, any, any) error
CallRaw(context.Context, string, any) (*ActionResponse, error)
Send(context.Context, ReplyTarget, message.Chain) (MessageReceipt, error)
}
ActionClient 定义协议动作调用和消息发送能力。
type ActionError ¶
ActionError 描述一次由协议端明确拒绝或返回失败状态的动作调用。
func (*ActionError) Error ¶
func (e *ActionError) Error() string
type ActionResponse ¶
type ActionResponse struct {
Status string
RetCode int
Message string
Wording string
Echo string
Data json.RawMessage
Raw json.RawMessage
}
ActionResponse 是协议无关的动作响应封套，保留标准字段和原始 data。
func (*ActionResponse) Decode ¶
func (r *ActionResponse) Decode(out any) error
Decode 将动作响应的 data 字段解码到 out；空 data 会被视为成功空值。
type Adapter ¶
type Adapter interface {
Protocol() Protocol
Start(context.Context, EmitFunc) error
Client() ActionClient
}
Adapter 把具体聊天协议接入 AnyBot 运行时。
type App ¶
type App struct {
// contains filtered or unexported fields
}
App 是 AnyBot 的运行时入口，负责连接适配器、调度事件并执行路由链。
func (*App) UsePlugins ¶
UsePlugins 按传入顺序安装多个插件，遇到错误时停止。
type Context ¶
Context 是路由处理函数的工作上下文，聚合事件、运行时能力、匹配结果和局部值。
func NewTestContext ¶
NewTestContext 创建测试用上下文；app 为空时会使用默认配置的新 App。
func (*Context) Client ¶
func (c *Context) Client() ActionClient
Client 返回适配器动作客户端，可用于发送消息或调用协议 API。
func (*Context) ConversationID ¶
ConversationID 返回当前事件对应的会话键，可直接用于会话存储。
func (*Context) GroupSession ¶
GroupSession 返回当前群或频道维度的存储视图。
func (*Context) Reply ¶
func (c *Context) Reply(chain message.Chain) (MessageReceipt, error)
Reply 使用事件的自然目标发送消息。
func (*Context) ReplyText ¶
func (c *Context) ReplyText(text string) (MessageReceipt, error)
ReplyText 使用事件的自然目标发送纯文本回复。
type Event ¶
type Event struct {
ID string
Protocol Protocol
SelfID string
Type string
DetailType string
SubType string
UserID string
GroupID string
GuildID string
ChannelID string
Text string
Message message.Chain
Raw json.RawMessage
Data any
}
Event 是 AnyBot 的协议无关事件封套，保留常用标准字段和原始协议数据。
func (*Event) ConversationID ¶
ConversationID 返回适合会话存储的稳定键，优先按频道、群聊、私聊逐级区分。
func (*Event) GroupSessionID ¶
GroupSessionID 返回按群或频道维度隔离的存储键。
func (*Event) Target ¶
func (e *Event) Target() ReplyTarget
Target 返回该事件的自然回复目标，供 Context.Reply 和适配器发送消息使用。
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore 是 goroutine 安全的进程内 Store，适合短期会话状态。
func (*MemoryStore) Delete ¶
func (s *MemoryStore) Delete(ctx context.Context, key string) error
Delete 删除指定键。
type Middleware ¶
Middleware 包装处理函数，用于实现日志、鉴权、限速等横切能力。
func RateLimit ¶
func RateLimit(limit int, window time.Duration) Middleware
RateLimit 使用当前会话键做简单的进程内限速。
func RateLimitBy ¶
RateLimitBy 使用自定义键做进程内限速；键为空时回退到会话、用户或全局维度。
func Recover ¶
func Recover(loggers ...*slog.Logger) Middleware
Recover 捕获处理链中的 panic，记录调用栈，并把 panic 转成 PanicError。
func SuperUser ¶
func SuperUser(ids ...any) Middleware
SuperUser 仅允许指定用户进入后续处理链，未授权时返回 ErrUnauthorized。
func Timeout ¶
func Timeout(timeout time.Duration) Middleware
Timeout 为后续处理函数派生带超时的 context；timeout 不大于 0 时不生效。
type Option ¶
type Option func(*App)
Option 调整 App 的运行时配置。
func WithErrorHandler ¶
func WithErrorHandler(handler ErrorHandler) Option
WithErrorHandler 注册错误处理器。
func WithSerialBy ¶
func WithSerialBy(fn EventKeyFunc) Option
WithSerialBy 按自定义事件键串行处理同键事件，适合保护会话状态流转。
func WithSerialByConversation ¶
func WithSerialByConversation() Option
WithSerialByConversation 让同一会话内的事件按顺序处理。
func WithWorkers ¶
WithWorkers 配置并发处理事件的 worker 数；不大于 0 时由适配器回调同步处理。
type PanicError ¶
PanicError 包装处理函数或中间件中恢复到的 panic 值和调用栈。
func (*PanicError) Error ¶
func (e *PanicError) Error() string
type PluginFunc ¶
PluginFunc 将普通安装函数适配为 Plugin。
func (PluginFunc) Install ¶
func (p PluginFunc) Install(app *App) error
Install 执行插件安装函数；未提供函数时视为成功。
type Protocol ¶
type Protocol string
Protocol 标识事件和动作所属的协议。
const ( // ProtocolOneBot11 表示 OneBot v11 协议。 ProtocolOneBot11 Protocol = "onebot11" )
type ReplyTarget ¶
type ReplyTarget struct {
Protocol Protocol
SelfID string
UserID string
GroupID string
GuildID string
ChannelID string
EventID string
}
ReplyTarget 描述一次消息回复的自然目标。
type Route ¶
type Route struct {
// contains filtered or unexported fields
}
Route 表示一条可配置的事件路由。
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router 组织路由、中间件和共享基础规则。
type Rule ¶
Rule 判断路由是否应处理当前事件。
func CommandWithPrefixes ¶
CommandWithPrefixes 使用显式前缀集合匹配命令，并写入 prefix、command、args 和 argv。
func RegexpRule ¶
RegexpRule 使用已编译的正则表达式匹配事件文本，并写入 matches 与命名分组变量。
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session 是基于固定键前缀的 Store 视图。
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
onebot11
onebot11 包提供 AnyBot 的 OneBot v11 适配器、消息段构造器和类型化动作客户端。
|
onebot11 包提供 AnyBot 的 OneBot v11 适配器、消息段构造器和类型化动作客户端。 |
|
onebot11/napcat
napcat 包提供 NapCat 专属 OneBot v11 扩展动作的类型化辅助方法。
|
napcat 包提供 NapCat 专属 OneBot v11 扩展动作的类型化辅助方法。 |
|
cmd
|
|
|
anybot
command
|
|
|
examples
|
|
|
httpaction
command
|
|
|
media
command
|
|
|
permission
command
|
|
|
ping
command
|
|
|
pluginbot
command
|
|
|
reversews
command
|
|
|
session
command
|
|
|
websocket
command
|
|
|
internal
|
|
|
message 包定义 AnyBot 的协议中立消息链。
|
message 包定义 AnyBot 的协议中立消息链。 |
|
plugins
|
|
|
admin
admin 包提供一个超级用户命令示例插件。
|
admin 包提供一个超级用户命令示例插件。 |
|
echo
echo 包提供一个复读命令示例插件。
|
echo 包提供一个复读命令示例插件。 |
|
help
help 包提供一个可配置的基础帮助命令插件。
|
help 包提供一个可配置的基础帮助命令插件。 |
|
ratelimit
ratelimit 包提供把会话限速中间件打包后的示例插件。
|
ratelimit 包提供把会话限速中间件打包后的示例插件。 |
Click to show internal directories.
Click to hide internal directories.