🚀 快速开始

本指南将帮助你在 5 分钟内完成 AniaBot 的部署和配置。

前置要求

安装步骤

# 克隆群聊部署分支
git clone https://github.com/jeanhua/AniaBot.git
cd AniaBot

bot:
  admin_id: 123456789   # 管理员 QQ 号
  adapter:
    ws:
      address: "ws://localhost:4455"
  store:
    redis:
      address: "localhost:6379"
      password: ""
      db: 0

# 直接运行（开发模式）
go run cmd/main.go

# 编译为 Linux 二进制
scripts/build_linux.bat  # Windows 下运行
# 或手动编译
GOOS=linux GOARCH=amd64 go build -o build/AniaBot ./cmd/

验证安装

启动成功后，在 QQ 群中发送 @Bot /help（PluginSys 系统插件），如果 Bot 回复了插件列表，说明安装成功。

🏗️ 架构概览

AniaBot 采用分层架构设计，各层职责清晰，可灵活扩展。

整体架构

目录结构

AniaBot/
├── bot/
│   ├── adapter/napcat/    # NapCat 协议适配器实现
│   ├── component/         # AI 聊天组件、Function Tool
│   ├── core/              # Bot 核心，插件管理与事件分发
│   ├── plugins/           # 内置插件（log、repeat、AI等）
│   └── utils/             # 工具函数（命令解析、消息提取）
├── common/
│   ├── adapter/           # Adapter 接口定义
│   ├── bot/               # Bot 接口定义
│   ├── model/             # 消息模型（OB11 协议结构体）
│   ├── msgchain/          # 消息链构造器
│   ├── plugin/            # Plugin 接口定义
│   └── storage/           # Storage 接口定义
├── custom/
│   └── plugins/           # 自定义插件（群聊部署分支新增）
│       ├── douyinparser/
│       ├── acgwallpaper/
│       ├── waifupics/
│       ├── githubrepoer/
│       ├── interceptor/
│       ├── groupnewsletter/
│       └── gdmusicplugin/
└── cmd/main.go            # 入口，插件注册

事件流程

当 QQ 消息到达时，框架按以下顺序处理：

⚙️ 配置文件详解

AniaBot 使用 YAML 格式的配置文件，支持 config.yaml（生产）和 config.dev.yaml（开发）两套配置。

Bot 核心配置

bot:
  admin_id: 123456789   # 管理员 QQ 号，部分插件仅管理员可用

  adapter:
    # WebSocket 适配器（推荐）
    ws:
      address: "ws://localhost:4455"
      max_retries: 5           # 连接失败最大重连次数
      worker_count: 0          # 0 = 自动（CPU核数×2）
      worker_queue_size: 1024  # 消息队列大小，超出则丢弃
    # HTTP 适配器（备选）
    http:
      listen_port: 6679        # 本地监听端口
      target_url: "http://localhost:6680"

  store:
    redis:
      address: "localhost:6379"
      password: ""
      db: 0

AI 对话插件配置

plugin:
  ai_chat_bot:
    base_url: "https://api.deepseek.com"
    api_key: "sk-xxxxx"
    model: "deepseek-chat"
    temperature: 1.2
    top_p: 0.9
    top_k: 100
    max_token: 8192
    prompt: |-
      你是一个 AI 对话机器人，在 QQ 上和别人聊天
    search:
      token: "jina_xxxx"  # Jina AI 搜索 Token
    ocr:
      enable: false
      base_url: "https://api.siliconflow.cn/v1"
      api_key: "sk-xxxxx"
      model: "Qwen/Qwen3-VL-8B-Instruct"

拦截器配置

plugin:
  interceptor:
    blacklist:           # 黑名单（拒绝）
      users:
        - 123456        # 屏蔽指定用户
      groups:
        - 654321        # 屏蔽指定群
    whitelist:           # 白名单（放行）
      users:
        - "all"         # 放行所有用户
      groups:
        - "all"         # 放行所有群

优先级：黑名单 > 白名单 > 默认拒绝

群刊插件配置

plugin:
  group_newsletter:
    model:
      base_url: "https://api.openai.com/v1"
      api_key: "sk-xxxxx"
      model: "gpt-4"
      prompt: ""          # 留空使用内置 Prompt
    max_token: 4000
    msg_threshold: 100   # 达到此条数触发自动生成
    max_messages: 500    # 最大缓存消息数
    enabled_groups:       # 留空 = 所有群
      - 123456789

GD 音乐插件配置

plugin:
  gdmusic:
    base_url: "https://music-api.gdstudio.xyz/api.php"  # 留空使用默认

URL 解析插件配置

plugin:
  url_parser:
    token: "your_token"
    llm:
      base_url: "https://api.openai.com/v1"
      api_key: "your_api_key"
      model: "gpt-4o"

💡 核心 Core

bot/core 包是整个框架的大脑，负责插件管理、事件分发和生命周期控制。

AniaBot 结构体

type AniaBot struct {
    ctx    context.Context
    cancel context.CancelFunc
    adapter adapter.Adapter
    plugins []plugin.Plugin
    cfg     *viper.Viper
    storage     storage.Storage
    restyClient *resty.Client
    pluginSet map[string]struct{}
}

创建和运行

func main() {
    // 1. 创建适配器
    adapter := napcat.NewNapcatWebSocketAdapter()

    // 2. 创建 Bot（可选传入配置、存储、HTTP Client）
    bot := core.NewAniaBot(adapter,
        core.WithConfig(cfg),      // 可选：自定义配置
        core.WithStorage(storage),  // 可选：自定义存储
    )

    // 3. 注册插件（顺序不影响执行，由 Order 字段决定）
    bot.AddPlugin(pluginlog.NewPlugin())
    bot.AddPlugin(pluginaichat.NewAIChatPlugin())
    bot.AddPlugin(douyinparser.Newplugin())

    // 4. 运行（阻塞）
    bot.Run()
}

插件执行顺序

框架通过 plugin.Meta.Order 字段控制执行顺序，内置常量如下：

超时配置

🧩 插件开发指南

插件是 AniaBot 的核心扩展机制。只需实现 plugin.Plugin 接口即可创建自己的插件。

插件接口

所有插件需实现以下接口，通常直接嵌入 plugin.Meta 来获取默认实现：

type Plugin interface {
    GetMeta() *Meta          // 获取插件元数据
    DI                       // 依赖注入：SetStorage、SetRestyClient
    BasicEvent               // OnGroupMsg、OnFriendMsg
    StartupEvent             // Start、StartCron、Awake
    NoticeEvent              // OnGroupRecall、OnPoke 等通知事件
}

最小插件示例

package myplugin

import (
    "context"
    "github.com/jeanhua/AniaBot/common/bot"
    "github.com/jeanhua/AniaBot/common/model/command"
    "github.com/jeanhua/AniaBot/common/model/message"
    "github.com/jeanhua/AniaBot/common/msgchain"
    "github.com/jeanhua/AniaBot/common/plugin"
    "github.com/spf13/viper"
)

type MyPlugin struct {
    plugin.Meta   // 嵌入 Meta，自动实现所有默认接口
}

func NewMyPlugin() *MyPlugin {
    return &MyPlugin{
        Meta: plugin.Meta{
            Name:      "我的插件",
            HelpWords: "@我 /hello 打招呼",
            AdminOnly: false,
            ShowFor:   plugininfo.ShowForGroup | plugininfo.ShowForFriend,
            Author:    "jeanhua",
            Version:   "1.0.0",
            Order:     plugin.LevelNormal,
        },
    }
}

// Start 插件初始化，读取配置
func (p *MyPlugin) Start(ctx context.Context, cfg *viper.Viper) error {
    return nil
}

// OnGroupMsg 处理群聊消息，返回 (是否继续, 错误)
func (p *MyPlugin) OnGroupMsg(
    ctx context.Context, bot bot.Bot,
    cmd command.Command, msg message.Message,
) (bool, error) {
    // 判断：@Bot 且命令为 /hello
    if cmd.Mention && cmd.Name == "hello" {
        builder := msgchain.Builder().Group()
        builder.Mention(msg.Sender.UserId)
        builder.Text(" 你好！")
        bot.SendGroupMsg(msg.GroupId, builder.Build())
        return false, nil  // 消费此消息，不传递
    }
    return true, nil       // 继续传递给下一插件
}

插件生命周期

Meta 字段说明

ShowFor 取值

const (
    ShowForNone   ShowFor = 1                // 不显示
    ShowForGroup  ShowFor = 1 << 1          // 仅在群聊中显示
    ShowForFriend ShowFor = 1 << 2          // 仅在私聊中显示
)

// 组合示例：群聊和私聊都显示
ShowFor: plugininfo.ShowForGroup | plugininfo.ShowForFriend

使用存储

通过注入的 p.Storage 进行持久化存储，存储已自动按插件名隔离前缀：

// 保存字符串
p.Storage.SetString(ctx, "key", "value")

// 读取字符串
val, ok := p.Storage.GetString(ctx, "key")

// 保存 JSON 对象
p.Storage.Set(ctx, "user:123", userStruct)

// 带 TTL 的键
p.Storage.SetString(ctx, "lock", "1",
    storage.WithTTL(time.Minute * 10),
    storage.WithCheckExist(),  // 不存在时才写入（原子锁）
)

注册到 main.go

import myplugin "github.com/jeanhua/AniaBot/custom/plugins/myplugin"

func main() {
    // ... 其他代码
    bot.AddPlugin(myplugin.NewMyPlugin())
    bot.Run()
}

💬 消息链构造器

msgchain 提供了流畅的链式 API，用于构造各种类型的 QQ 消息。

基础用法

builder := msgchain.Builder().Group()
builder.Mention(userId)        // @某人
builder.Text(" 你好！")         // 文本
builder.Face(14)               // QQ 表情（微笑）
builder.ImageUrl("https://...") // 网络图片
bot.SendGroupMsg(groupId, builder.Build())

builder := msgchain.Builder().Friend()
builder.Text("私聊回复")
builder.FileUrl("report.md", "https://...")
bot.SendFriendMsg(userId, builder.Build())

支持的消息类型

合并转发消息

fbuilder := msgchain.Builder().GroupForward()

// 每条消息单独构建
for _, m := range messages {
    inner := msgchain.Builder().Group()
    inner.Text(m.Content)
    fbuilder.Message(m.UserId, m.Nickname, inner.Build())
}

bot.SendGroupForwardMsg(groupId, fbuilder.Build())

📦 插件一览

AniaBot 包含内置插件和群聊部署分支的自定义插件两类。

内置插件

自定义插件（群聊部署分支）

📋 日志打印插件

日志插件在所有插件中最先执行，将收到的群聊和私聊消息实时打印到控制台，同时记录上次启动时间。

功能说明

• 打印 [收<-群:xxx 昵称:xxx]: 消息内容 格式的群聊日志
• 打印 [收<-好友:xxx 昵称:xxx]: 消息内容 格式的私聊日志
• 启动时读取上次重启时间并写入新时间

消息内容提取

使用 utils.ExtraMessage() 函数，会将消息段转换为可读文本，包括 QQ 表情名、@某人、回复引用等。

🔁 复读机插件

当同一群中连续3条相同消息时，Bot 自动复读。管理员可通过命令控制开关。

指令

实现原理

使用 sync.Map 为每个群维护一个 repeatCount 结构体，记录当前最新消息和连续次数。当连续次数达到 3 且未复读过时，触发复读并标记已复读。消息变化时重置计数器。

🛡️ 防撤回插件

在内存中维护每个群最近 100 条消息的环形队列，支持查看历史消息和处理图片链接过期问题。

指令

图片链接处理

3分钟内的图片/文件直接转发；超过3分钟时，若能获取到 NCrkey（NapCat 鉴权 Key），则替换 rkey 参数刷新链接；否则提示已过期。

消息队列实现

使用泛型实现的 MessageQueue[T] 环形队列，容量100，Get(n) 方法取最近n条消息，线程安全。

🤖 AI 对话插件

基于 langchaingo 构建的多轮对话插件，支持 Function Calling、联网搜索、图片 OCR 等高级功能。

使用方式

内置 Function Tools

并发锁机制

每个群/用户维护一个 Redis 分布式锁（10分钟TTL），防止同一对话同时触发多次 AI 请求。等待期间回复"正在等待响应中"。

OCR 功能

当消息中包含图片时，若启用 OCR，会调用专用视觉模型（如 Qwen-VL）描述图片内容，将结果注入到对话上下文中，实现"看图聊天"。

📰 每日新闻插件

通过 Cron 表达式定时向指定群发送每日新闻图片，也支持手动触发。

指令

配置示例

plugin:
  dailyNews:
    api: "https://uapis.cn/api/v1/daily/news-image"
    cron: "0 12 * * *"  # 每天12点
    groups:
      - 123456789
      - 987654321

⭐ 高级篇：自定义插件

本节介绍群聊部署分支中新增的全部自定义插件，这些插件可以作为高级插件开发的参考案例。

技术特性速览

🎵 抖音解析插件

通过正则表达式提取分享文本中的抖音短链，调用第三方解析 API 获取视频直链、作者信息。

指令

使用示例

用户: @Bot /douyin 7.38 分享内容... https://v.douyin.com/xxxxx/
Bot:  @用户 🍔 解析成功
      博主: 某某某
      标题: 视频标题
      视频直链: https://.....

实现原理

🖼️ 二次元壁纸插件

获取随机二次元壁纸图片，内置任务队列防止并发过载，展示了 Worker Pool 模式的实现。

指令

架构模式：任务队列

这是一个经典的生产者-消费者模式：

type AcgWallpaperPlugin struct {
    plugin.Meta
    pendding chan work   // 有界 Channel 作为任务队列
}

// Awake：启动后台 Worker Goroutine
func (p *AcgWallpaperPlugin) Awake(ctx context.Context, bot bot.Bot) error {
    go p.workFunc(bot)   // 永久运行的 Worker
    return nil
}

// 消息处理：将任务推入队列
func (p *AcgWallpaperPlugin) OnGroupMsg(...) (bool, error) {
    if cmd.Mention && cmd.Name == "acg" {
        select {
        case p.pendding <- work{...}:  // 成功入队
        default:                       // 队列满时告知用户
            bot.SendGroupMsg(groupId, "任务队列已满...")
        }
    }
}

🌸 waifu.pics 插件

接入 waifu.pics API，提供 30+ 分类的二次元图片和表情包。

指令

支持的分类

人像类：

waifunekoshinobumegumin

表情包类（部分）：

bullycuddlecryhugawookisslickpatsmugbonkyeetdance...

共 31 个分类，发送 /waifu help 查看全部。

分类验证

插件内置分类白名单，用户输入不存在的分类时会提示错误，防止无效请求：

var categories = []string{
    "waifu", "neko", "shinobu", "megumin",
    "bully", "cuddle", "cry", "hug", "awoo",
    // ... 31 个分类
}

func validateCate(category string) bool {
    for _, c := range categories {
        if category == c { return true }
    }
    return false
}

🔬 GithubRepoer 插件

调用 Repomix API 打包 GitHub 项目代码，再由 LLM 生成专业的质量分析报告，以 Markdown 文件形式发送。

指令

高级参数

工作流程

配置

plugin:
  github_repoer:
    max_token: 100000
    model:
      base_url: "https://api.deepseek.com"
      api_key: "sk-xxxxx"
      model: "deepseek-chat"
      prompt: |-
        你是Github项目专业分析师，负责分析用户提供的代码项目质量

🚧 消息拦截器插件

精细化的消息过滤器，支持群和用户维度的黑白名单管理。插件执行顺序仅次于日志，可在所有业务插件之前拦截消息。

优先级规则

配置示例

plugin:
  interceptor:
    blacklist:
      groups:  [123456]     # 屏蔽这些群
      users:   [999999]     # 屏蔽这些用户
    whitelist:
      groups:  ["all"]     # 放行所有群
      users:   ["all"]     # 放行所有用户

实现逻辑

func (p *InterceptorPlugin) check(target int, msg message.Message) bool {
    // 1. 黑名单检查（最高优先级）
    for _, id := range p.interceptGroup {
        if id == "all" || ieqs(msg.GroupId, id) {
            return false   // 拒绝
        }
    }
    // 2. 白名单检查
    for _, id := range p.permitGroup {
        if id == "all" || ieqs(msg.GroupId, id) {
            return true   // 放行
        }
    }
    return false   // 3. 默认拒绝
}

📜 群刊插件

自动收集群聊消息，当达到阈值时由 AI 生成有趣的群刊文档，以 Markdown 文件发送。内置持久化存储，重启后消息不丢失。

指令

自动触发流程

并发安全设计

插件使用了多层并发保护：

• 消息缓冲区：每个群独立的 sync.RWMutex
• Map 访问：sync.RWMutex msgsMutex 保护 groupMsgs Map
• 防重入锁：generating map + generateMu 防止同一群并发生成
• 生命周期：使用独立的 pluginCtx（非框架传入的短生命周期 ctx），确保 goroutine 可正常退出

AI Prompt 设计

默认内置了详细的群刊 Prompt，包括：标题风格、内容要求、Markdown 格式要求、特色栏目（今日之星、神回复、迷惑行为大赏）等。也可在配置中自定义。

消息格式化

// 距上一条消息超过30分钟，插入时间分隔
if msg.Time - cTime > 60*30 {
    fmtData.WriteString("\n" + time.Unix(msg.Time, 0).Format("2006-01-02 15:04:05") + "\n")
}
fmtData.WriteString(fmt.Sprintf(
    "[UserID]:%d\n[Username]:%s\n[Content]:%s\n",
    msg.UserId, msg.Nickname, msg.Content,
))

🎶 GD 音乐插件

基于 GD Music API 的多平台音乐搜索插件，支持搜索、翻页、发送音频文件。内置会话状态管理，用户可以浏览搜索结果并下载。

指令

支持平台

会话状态设计

插件为每个群和每个私聊用户维护独立的 searchSession，记录上次搜索的关键词、平台、当前页和结果：

type searchSession struct {
    keyword string
    source  gdmusic.Source
    count   int             // 每页条数
    page    int             // 当前页码（从 1 开始）
    results []gdmusic.SearchResult
}

type MusicPlugin struct {
    plugin.Meta
    client      *gdmusic.Client
    groupCache  sync.Map    // map[uint]*searchSession
    friendCache sync.Map    // map[uint]*searchSession
}

参数解析

支持 -n、-s、-p 标志参数，未被标志消费的部分自动拼接为搜索关键词：

// 输入：周杰伦 晴天 -n 3 -s kuwo -p 2
keyword = "周杰伦 晴天"
count = 3
source = "kuwo"
page = 2

🔗 URL 解析插件

自动解析群聊中的 URL 并提取相关信息，基于 AI 的内容分析插件。使用 LLM 分析 URL 对应页面的内容，提取关键信息并返回。

工作原理

配置

plugin:
  # URL 解析插件配置
  url_parser:
    token: "your_token"
    llm:
      base_url: "https://api.openai.com/v1"
      api_key: "your_api_key"
      model: "gpt-4o"

实现要点

• 异步处理：使用 channel 作为任务队列，workLoop 协程异步处理
• 并发控制：channel 带缓冲大小（100），防止任务堆积
• LLM 集成：基于 langchaingo 的 OpenAI LLM，灵活切换模型和 API

📖 Bot API 参考

bot.Bot 接口提供了插件与 QQ 交互的所有方法。

发送消息

获取信息

获取信息

🗄️ 存储 API 参考

每个插件通过 p.Storage 访问 Redis 存储，存储键名自动加上插件名的 Base64 前缀，实现天然隔离。

接口定义

type Storage interface {
    GetString(ctx context.Context, key string) (string, bool)
    SetString(ctx context.Context, key, val string, option ...Option) bool

    Get(ctx context.Context, key string, out any) bool
    Set(ctx context.Context, key string, val any, option ...Option) bool

    ScanKeys(ctx context.Context, pattern string, count int64) ([]string, error)
    Del(ctx context.Context, key string) bool
    Clear(ctx context.Context) bool
    Clone(prefix string) Storage

    LPush(ctx context.Context, key string, values ...any) int64
    RPush(ctx context.Context, key string, values ...any) int64
    LPop(ctx context.Context, key string) (any, bool)
    RPop(ctx context.Context, key string) (any, bool)
    LRange(ctx context.Context, key string, start, stop int64) ([]any, bool)
    LLen(ctx context.Context, key string) int64
    LRem(ctx context.Context, key string, count int64, value any) int64
    LSet(ctx context.Context, key string, index int64, value any) bool
    LIndex(ctx context.Context, key string, index int64) (any, bool)
    LTrim(ctx context.Context, key string, start, stop int64) bool
}

配置选项

List 操作

使用示例

// 简单读写
p.Storage.SetString(ctx, "key", "value")
val, ok := p.Storage.GetString(ctx, "key")

// JSON 对象存储
type UserData struct { Score int; Level string }
p.Storage.Set(ctx, "user:123", UserData{Score: 100})
var data UserData
p.Storage.Get(ctx, "user:123", &data)

// 带 TTL 的分布式锁（NX操作）
locked := p.Storage.SetString(ctx, "lock:group:123", "1",
    storage.WithCheckExist(),
    storage.WithTTL(time.Minute * 10),
)
if !locked {
    // 锁已被占用
}

// 子存储（多级隔离）
subStore := p.Storage.Clone("cache")
subStore.Set(ctx, "key", data)

// 模糊扫描 key
keys, err := p.Storage.ScanKeys(ctx, "group_*", 100)

// List：队列操作
p.Storage.RPush(ctx, "job_queue", "task-1", "task-2")
item, ok := p.Storage.LPop(ctx, "job_queue")
size := p.Storage.LLen(ctx, "job_queue")
items, ok := p.Storage.LRange(ctx, "job_queue", 0, -1)

// 清空当前前缀下所有键
p.Storage.Clear(ctx)

🔌 适配器

AniaBot 提供两种 NapCat 适配器，均实现了相同的 adapter.Adapter 接口。

WebSocket 适配器（推荐）

WebSocket 适配器提供实时双向通信，内置 Worker Pool 和自动重连机制：

• 自动重连：指数退避策略，最大重试次数可配置
• Worker Pool：可配置 worker 数量和队列大小，防止消息堆积
• ACK 机制：每个请求带 echo ID，通过 Channel 异步等待响应，超时 10s
• 并发安全：写操作通过 sync.Mutex 保护

bot:
  adapter:
    ws:
      address: "ws://localhost:4455"
      max_retries: 5
      worker_count: 8        # 0 = CPU * 2
      worker_queue_size: 512

HTTP 适配器

HTTP 适配器通过本地监听接收 NapCat 事件推送，并通过 HTTP 请求发送消息：

• 适合无法使用 WebSocket 的场景
• 每个请求独立超时（5s）

// cmd/main.go
// adapter := napcat.NewNapcatWebSocketAdapter()
adapter := napcat.NewNapcatHttpAdapter()  // 取消注释