remilia

README

Remilia

Remilia 受 wdvxdr1123/ZeroBot 架构启发， 但为 完全独立的实现，不包含 ZeroBot 的任何受版权保护的代码。 ZeroBot 是 GPL-3.0 许可的开源项目。

一个现代化、高性能、易于扩展的 QQ 机器人框架

快速开始 • 文档 • 示例 • 贡献

---

🎉 v1.0.0

✅ Plugin v2 API 正式版

v1 API (BasePlugin) 已完全移除，v2 API 是目前唯一的插件开发方式。

v2 API 优势:

• ✅ 无需继承，函数式设计
• ✅ 自动依赖注入（Require / Optional / MustAs）
• ✅ 后台 goroutine（ctx.Spawn）与并发任务组（ctx.NewTaskGroup）
• ✅ 读写分离权限模型（PluginInfo 只读 / ManagerWriter 写）
• ✅ Smart 注册自动推断依赖图（无需手写 Deps）

快速上手: docs/02-user-guides/PLUGIN_V1_TO_V2_MIGRATION.md
变更日志: CHANGELOG.md

---

✨ 特性

🚀 核心能力

• 高性能引擎 — COW 并发模型，无锁读取，单实例吞吐量 500,000+ msg/s
• 插件系统 — v2 函数式插件，热重载（InPlace / BlueGreen 策略），自动依赖排序
• WASM 插件 — 跨语言插件支持（TinyGo / Rust / C），wazero 沙箱隔离，TLV 序列化
• 中间件机制 — 限流 / 重试 / 降级 / 死信队列 / 去重，支持热更新阈值
• 命令解析 — Trie 树 + commandIndex 双索引，O(1) 命令路由
• 配置管理 — YAML / 环境变量，配置热更新（hotreload.Bridge）

🛡️ 可靠性保障

• 优雅关闭 — 完整的生命周期管理，确保消息不丢失
• 自适应限流 — 根据系统负载自动调整并发限制（每实例独立 Prometheus 指标）
• 熔断降级 — 自动熔断，CPU / 内存阈值热更新
• 死信队列 — 失败消息持久化，支持人工干预
• 自适应 Recover — panic 捕获时自适应堆栈缓冲（4KB → 64KB）

📊 可观测性

• Prometheus 集成 — 完整的 metrics 暴露
• 结构化日志 — 基于 zerolog 的结构化日志
• 健康检查 — HTTP 健康检查端点
• 性能分析 — 内置 pprof 支持

---

📦 安装

go get github.com/KomeiDiSanXian/remilia

要求: Go 1.26+

---

🚀 快速开始

1. 基础示例

package main

import (
    "fmt"

    "github.com/KomeiDiSanXian/remilia"
    "github.com/KomeiDiSanXian/remilia/core/engine"
    eventctx "github.com/KomeiDiSanXian/remilia/core/context"
    "github.com/KomeiDiSanXian/remilia/platform"
    "github.com/KomeiDiSanXian/remilia/platform/qq"
    "github.com/KomeiDiSanXian/remilia/platform/qq/openapi/dto"
)

func main() {
    eng := engine.NewEngine()

    // 注册平台无关的命令处理器
    eng.OnCommand(platform.EventKindGroupMessage, "/echo").
        Handle(func(ctx *eventctx.Context) error {
            return ctx.Reply(platform.TextMessage("你说: " + ctx.GetMessageContent()))
        })

    // 创建 QQ 适配器（Webhook 模式）
    botInfo := &dto.BotInfo{
        AppID:     123456,
        Token:     "your-token",
        AppSecret: "your-secret",
    }
    adapter := qq.NewWebhookServerAdapter(":8080", botInfo)

    bot, err := remilia.NewBotBuilder().
        WithPlatformAdapter(adapter).
        WithEngine(eng).
        Build()
    if err != nil {
        panic(err)
    }

    bot.Start()
    bot.WaitForShutdown()
}

2. 使用中间件

import "github.com/KomeiDiSanXian/remilia/middleware"

eng.Use(
    middleware.Logging(),             // 日志记录
    middleware.Recover(),             // Panic 恢复（自适应堆栈）
    middleware.SimpleRateLimit(20),   // 全局限流：每秒最多 20 个事件
    middleware.Timeout(5*time.Second),// 超时（context deadline 注入）
    middleware.Retry(3),              // 重试
)

注意：ctx.Set(key, nil) 是 no-op，删除 key 请用 ctx.Delete(key)。

3. 插件开发（v2 API）

package myplugin

import (
    "github.com/KomeiDiSanXian/remilia/plugin"
    eventctx "github.com/KomeiDiSanXian/remilia/core/context"
    "github.com/KomeiDiSanXian/remilia/platform"
)

func New() *plugin.Descriptor {
    return &plugin.Descriptor{
        Name:    "myplugin",
        Version: "1.1.0",
        Meta: &plugin.Metadata{
            Description: "我的第一个插件",
            Category:    "工具",
        },
        Setup: func(ctx *plugin.SetupContext) (any, error) {
            ctx.Reg.RegisterCommand(platform.EventKindGroupMessage, "/hello").
                Handle(func(c *eventctx.Context) error {
                    return c.Reply(platform.TextMessage("Hello from plugin!"))
                })
            return nil, nil
        },
    }
}

注册插件：

manager := plugin.NewManager(eng)
manager.Register(myplugin.New())

完整指南: docs/02-user-guides/PLUGIN_V1_TO_V2_MIGRATION.md

4. 使用配置文件

# config.yaml
bot:
  app_id: 123456
  bot_id: 654321
  token: "your-token"
  secret: "your-secret"

server:
  host: "0.0.0.0"
  port: 8080

engine:
  temp_matcher_cleanup_interval: "5m"
  pending_delete_buffer_size: 1000

middleware:
  logging: true
  rate_limit: true
  rate_limit_rate: 100
  degradation_cpu_threshold: 80.0
  degradation_memory_threshold: 85.0

cfg, err := config.Load("config.yaml")
if err != nil { panic(err) }

adapter := qq.NewWebhookServerAdapter(
    fmt.Sprintf("%s:%d", cfg.Server.Host, cfg.Server.Port),
    &dto.BotInfo{
        AppID:     cfg.Bot.AppID,
        BotAppID:  cfg.Bot.BotID,
        Token:     cfg.Bot.Token,
        AppSecret: cfg.Bot.Secret,
    },
)

bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(adapter).
    Build()
if err != nil { panic(err) }

bot.Start()
bot.WaitForShutdown()

---

📚 文档

完整文档: 👉 docs/README.md

快速导航

🚀 新手入门

• 快速开始指南 — 10 分钟上手
• 故障排除 — 常见问题解答

🔌 插件开发

• Plugin v2 快速上手 — 从零开始写插件
• 插件接口速查 — API 签名速查
• 插件开发最佳实践 — 规范与模式
• WASM 跨语言插件 — TinyGo/Rust/C 插件开发 🆕

📖 用户指南

• 最佳实践 — 推荐的使用模式
• 配置快速参考 — 配置项速查
• 配置热更新 — Bridge API
• Matcher 链式调用 — 高级模式

🏗️ 架构设计

• 并发事件处理 — COW 并发模型 + 6 路合并
• 插件系统设计 — 插件架构详解
• 命令系统集成 — 命令解析器

📊 质量报告

• Core & Middleware 设计评审 — P0/P1/P2 全部完成

---

💡 示例

查看 examples 目录获取更多示例（完整说明见 examples/README.md）：

• showcase ⭐ — 覆盖所有功能的综合示例，含 WASM 插件演示
• 基础 Bot — 最简单的 bot 示例
• 命令系统 — 完整的命令处理示例
• 插件开发 — 自定义插件示例（v2 API）
• Plugin v2 演示 — v2 插件完整演示
• 中间件使用 — 中间件组合使用
• 配置热更新 — 配置热更新示例
• 配置集成 — Viper 集成
• 错误处理 — errutil 完整演示
• 生产环境 — 生产级最佳实践
• 异步任务 — goroutine 管理与背压控制
• HTTP 客户端 — 重试/超时/中间件链
• 日志系统 — 结构化日志多输出
• 指标监控 — Prometheus 自定义指标
• 分布式追踪 — OpenTelemetry 集成
• SQLite 存储 — 持久化存储示例
• 帮助发现 — Help 插件自动发现
• Debug 子命令 — 运行时诊断
• 性能基准 — 引擎吞吐量压测

---

🏗️ 架构

整体架构

┌─────────────────────────────────────────────────────┐
│                    Application                       │
│                  (Your Bot Logic)                    │
└───────────────────┬─────────────────────────────────┘
                    │
┌───────────────────▼─────────────────────────────────┐
│                      Bot                             │
│              (Lifecycle Manager)                     │
└───────────────────┬─────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────────────────────┐
│    Adapter     │    │     Engine (COW)                 │
│  (接收事件)     │    │  engine.go / matcher_ops.go     │
└───────┬────────┘    │  command.go / query.go           │
        │             └────────┬────────────────────────┘
        │                      │
        │              ┌───────┴────────┐
        │              │                │
        │        ┌─────▼─────┐  ┌──────▼──────┐
        │        │  Matcher  │  │ Middleware  │
        │        │  (路由)    │  │  (中间件链)  │
        │        └─────┬─────┘  └──────┬──────┘
        │              └────────┬───────┘
        │                       │
        │                ┌──────▼──────┐
        │                │   Handler   │
        │                │  (业务逻辑)  │
        │                └──────┬──────┘
        │                ┌──────▼──────┐
        │                │  OpenAPI    │
        │                │ (发送消息)   │
        │                └─────────────┘
        │
┌───────▼─────────────────────────────────────────────┐
│   Plugin System (v2)                                 │
│   descriptor / context / container                   │
│   instance / reload / register                       │
└─────────────────────────────────────────────────────┘
        │
┌───────▼─────────────────────────────────────────────┐
│              QQ Official API / Webhook               │
└─────────────────────────────────────────────────────┘

关键特性

1. COW (Copy-On-Write) 引擎

• 无锁读取: ProcessEvent 完全无锁，atomic.Load() 原子获取快照
• 写时复制: 修改操作创建新状态，不影响正在进行的读取
• 文件拆分: engine.go（核心）/ engine_matcher_ops.go（写操作）/ engine_command.go（命令）/ engine_query.go（只读查询）

2. 智能匹配器路由（6 路合并）

• commandIndex: 消息以 / 开头时 O(1) 直接命中，跳过全量遍历
• 6 路合并: State(perm/cmd) × Specific/Generic + Temp，按优先级线性合并
• Temp 隔离: State 列表跳过已迁移到 TempManager 的 Matcher

3. 插件系统（v2）

• 函数式设计: PluginDescriptor 替代继承，无样板代码
• 读写分离: PluginInfo（只读）/ ManagerWriter（写，需 Privileged: true）
• Smart 注册: DryRun 阶段自动推断依赖图，无需手写 Deps

4. WASM 插件系统（ABI v2）

• 跨语言: TinyGo / Rust / C 均可编写 WASM 插件
• 沙箱隔离: wazero 运行时，宿主内存安全隔离
• TLV 序列化: 零依赖二进制序列化，替代 JSON
• 资源控制: 限流/超时/响应大小上限/导入数量上限

4. 中间件链

• 洋葱模型: Pre-process → Handler → Post-process
• 热更新: hotreload.Bridge 推送配置变更给 DedupFilter / AdaptiveDegradation
• 自适应 Recover: captureStack() 4KB→64KB 自适应堆栈缓冲

---

📊 性能

指标	值	说明
消息吞吐量（空 Handler）	~475,000 msg/s	16 核 CPU 80%，COW 无锁并发
含 1K Matcher (20K msg/s)	100% @ 10% CPU	6 路合并排序，匹配开销可预测
Engine ProcessEvent	~5-6 μs/op	COW 无锁读取 + 6 路合并排序
命令解析	~1-2 μs/op	Trie + commandIndex 双索引 O(1)
Context Pool	0 allocs/op	对象池复用
堆内存（50,000 msg/s）	~12-14 MB	极低内存占用，无泄漏

测试环境: 16 CPU, 32 GB RAM, Go 1.26.1, GOMAXPROCS=16

详细测试报告: examples/benchmark

---

🤝 贡献

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

贡献指南

• 遵循 Go 代码规范和最佳实践
• 添加必要的测试用例
• 更新相关文档
• 确保所有测试通过（go test ./...）

开发环境

# 克隆仓库
git clone https://github.com/KomeiDiSanXian/remilia.git
cd remilia

# 安装依赖
go mod download

# 运行测试
go test ./...

# 运行示例
go run examples/basic-bot/main.go

---

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

---

🙏 致谢

• QQ 官方机器人文档
• Go 社区
• 所有贡献者

---

📮 联系方式

• Issues: GitHub Issues
• 讨论: GitHub Discussions

---

🗺️ 路线图

v2.1.0（规划中）

• WebSocket 模式支持
• 消息队列集成
• 分布式部署支持
• 可视化管理界面

---

⭐ 如果这个项目对你有帮助，请给一个 Star！⭐

Made with ❤️ by KomeiDiSanXian

Documentation

Overview

Package remilia 是对核心引擎的高级封装，提供完整的生命周期管理。

Remilia 受 wdvxdr1123/ZeroBot 架构启发，但为完全独立的实现。 本项目不包含 ZeroBot 的任何受版权保护的代码。 ZeroBot 是 GPL-3.0 许可的开源项目：https://github.com/wdvxdr1123/ZeroBot

Bot 是使用 Remilia 框架构建事件驱动应用的主入口，提供：

• 生命周期管理（启动/停止）
• 健康检查
• 配置管理
• 通过 platform.Adapter 处理多平台事件

平台无关用法（推荐）

使用平台无关的事件匹配注册处理器：

import (
    "context"
    "log"

    "github.com/KomeiDiSanXian/remilia"
    "github.com/KomeiDiSanXian/remilia/core/engine"
    eventctx "github.com/KomeiDiSanXian/remilia/core/context"
    "github.com/KomeiDiSanXian/remilia/platform"
)

eng := engine.NewEngine()

// 注册一个适用于任意平台的命令处理器
eng.OnCommand("", "/hello").
    Handle(func(ctx *eventctx.Context) error {
        return ctx.Reply(platform.TextMessage("Hello!"))
    })

// 通过 platform.Adapter 构建 Bot
bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(qqAdapter). // platform.Adapter
    WithEngine(eng).
    Build()

QQ 用法

对于 QQ 机器人，使用 Bot 凭证创建 [qq.WebhookServerAdapter] 并传入构建器。 适配器内部自动管理 Token 刷新和消息发送：

import "github.com/KomeiDiSanXian/remilia/platform/qq"
import "github.com/KomeiDiSanXian/remilia/platform/qq/openapi/dto"

botInfo := &dto.BotInfo{
    AppID:     123456,
    Token:     "your-token",
    AppSecret: "your-secret",
}
adapter := qq.NewWebhookServerAdapter(":8080", botInfo)

bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(adapter).
    WithEngine(eng).
    Build()

// 平台无关匹配器（推荐用于所有平台）
eng.OnEventKind(platform.EventKindPrivateMessage, eventctx.OnCommand("/ping")).Handle(pingHandler)
eng.OnEventKind(platform.EventKindGroupMessage, eventctx.OnCommand("/hello")).Handle(helloHandler)

多平台

通过 platform.Registry 将多个平台接入同一个 Bot 实例。 每次调用 BotBuilder.WithPlatformAdapter 会覆盖前一个适配器； 若需注册多个平台，请使用 BotBuilder.WithPlatformRegistry：

registry := platform.NewRegistry()
registry.Register(qqAdapter)    // platform.PlatformAdapter
registry.Register(discordAdapter)

bot, err := remilia.NewBotBuilder().
    WithPlatformRegistry(registry).
    WithEngine(eng).
    Build()

适配器接口

支持一种适配器接口：

• platform.Adapter（推荐）：平台无关，处理器接收 platform.Event

健康检查

status := bot.Health()
fmt.Printf("Status: %s, Uptime: %v\n", status.Status, status.Uptime)

生命周期

Bot 使用 lifecycle 包：组件按顺序启动，按逆序停止。 启动失败会触发自动回滚。

Index

• Constants
• func CaptureTrace(ctx context.Context, duration time.Duration, filename string) error
• type AdapterHealthChecker
  • func NewAdapterHealthChecker(adapter platform.Adapter) *AdapterHealthChecker
  • func (c *AdapterHealthChecker) Check(_ context.Context) health.CheckResult
  • func (c *AdapterHealthChecker) Name() string
• type Bot
  • func MustNewBot(adapter platform.Adapter, e *engine.Engine, opts ...Option) *Bot
  • func NewBot(adapter platform.Adapter, e *engine.Engine, opts ...Option) (*Bot, error)
  • func (b *Bot) Config() BotMeta
  • func (b *Bot) Context() context.Context
  • func (b *Bot) Engine() *engine.Engine
  • func (b *Bot) Health() health.CheckResponse
  • func (b *Bot) HealthCheck() *health.Check
  • func (b *Bot) IsRunning() bool
  • func (b *Bot) OnAny(rule ...eventctx.Rule) *engine.Matcher
  • func (b *Bot) OnEventKind(kind platform.EventKind, rule ...eventctx.Rule) *engine.Matcher
  • func (b *Bot) PlatformRegistry() *platform.Registry
  • func (b *Bot) Plugins() *plugin.Manager
  • func (b *Bot) Shutdown() error
  • func (b *Bot) ShutdownAsync() <-chan error
  • func (b *Bot) Start() error
  • func (b *Bot) State() lifecycle.State
  • func (b *Bot) Stop(ctx context.Context) error
  • func (b *Bot) Uptime() time.Duration
  • func (b *Bot) UsePlatformRegistry(r *platform.Registry) *Bot
  • func (b *Bot) UsePlugins(pm *plugin.Manager) *Bot
  • func (b *Bot) UseRouter(r *router.Router) *Bot
  • func (b *Bot) WaitForShutdown(timeout ...time.Duration)
• type BotBuilder
  • func NewBotBuilder() *BotBuilder
  • func (b *BotBuilder) Build() (*Bot, error)
  • func (b *BotBuilder) MustBuild() *Bot
  • func (b *BotBuilder) WithDebug(debug bool) *BotBuilder
  • func (b *BotBuilder) WithEngine(eng *engine.Engine) *BotBuilder
  • func (b *BotBuilder) WithEngineOptions(opts ...engine.Option) *BotBuilder
  • func (b *BotBuilder) WithName(name string) *BotBuilder
  • func (b *BotBuilder) WithOption(opt Option) *BotBuilder
  • func (b *BotBuilder) WithPlatformAdapter(adapter platform.Adapter) *BotBuilder
  • func (b *BotBuilder) WithPlatformRegistry(r *platform.Registry) *BotBuilder
  • func (b *BotBuilder) WithPluginManager(pm *plugin.Manager) *BotBuilder
  • func (b *BotBuilder) WithPlugins(descriptors ...*plugin.Descriptor) *BotBuilder
  • func (b *BotBuilder) WithVersion(version string) *BotBuilder
• type BotError
  • func (e *BotError) Error() string
  • func (e *BotError) Unwrap() error
• type BotHealthResult
• type BotManager
  • func NewBotManager() *BotManager
  • func (m *BotManager) Add(name string, bot *Bot) error
  • func (m *BotManager) Get(name string) (*Bot, bool)
  • func (m *BotManager) HealthAll() map[string]BotHealthResult
  • func (m *BotManager) Len() int
  • func (m *BotManager) MustAdd(name string, bot *Bot) *BotManager
  • func (m *BotManager) MustGet(name string) *Bot
  • func (m *BotManager) Names() []string
  • func (m *BotManager) Remove(name string) bool
  • func (m *BotManager) RunningBots() []string
  • func (m *BotManager) Shutdown() error
  • func (m *BotManager) ShutdownAsync() <-chan error
  • func (m *BotManager) StartAll() error
  • func (m *BotManager) Status() BotManagerStatus
  • func (m *BotManager) StopAll(ctx context.Context) error
  • func (m *BotManager) WaitForShutdown(timeout ...time.Duration)
• type BotManagerBuilder
  • func NewBotManagerBuilder() *BotManagerBuilder
  • func (b *BotManagerBuilder) AddBot(name string, bot *Bot) *BotManagerBuilder
  • func (b *BotManagerBuilder) AddBuilder(name string, builder *BotBuilder) *BotManagerBuilder
  • func (b *BotManagerBuilder) Build() (*BotManager, error)
  • func (b *BotManagerBuilder) MustBuild() *BotManager
• type BotManagerError
  • func (e *BotManagerError) Error() string
  • func (e *BotManagerError) FailedBots() []string
• type BotManagerStatus
• type BotMeta
• type BotStatusChecker
  • func NewBotStatusChecker(bot *Bot) *BotStatusChecker
  • func (c *BotStatusChecker) Check(_ context.Context) health.CheckResult
  • func (c *BotStatusChecker) Name() string
• type DLQHealthAdapter
  • func NewDLQHealthAdapter(q dlqStater) *DLQHealthAdapter
  • func (a *DLQHealthAdapter) Stats() health.DLQStatsSnapshot
• type Option
  • func WithAdapter(adapter platform.Adapter) Option
  • func WithConfig(config *BotMeta) Option
  • func WithDebug(debug bool) Option
  • func WithEngine(engine *engine.Engine) Option
  • func WithName(name string) Option
  • func WithPprof(cfg PprofConfig) Option
  • func WithVersion(version string) Option
• type PprofConfig
  • func DefaultPprofConfig() PprofConfig
• type PprofServer
  • func NewPprofServer(config PprofConfig) *PprofServer
  • func (p *PprofServer) AddHandler(path string, handler http.HandlerFunc)
  • func (p *PprofServer) Start() error
  • func (p *PprofServer) Stop(ctx context.Context) error

Constants

const (
	DefaultShutdownTimeout = 30 * time.Second
	DefaultStartTimeout    = 30 * time.Second
)

const Version = "1.4.0"

Version 是 Remilia 框架的当前版本号。 此文件是版本号的唯一来源。 如需更新版本，仅修改此常量即可。

Functions

func CaptureTrace

func CaptureTrace(ctx context.Context, duration time.Duration, filename string) error

CaptureTrace 捕获执行追踪

ctx 可用于提前中止追踪（例如收到停止信号时）。 传入 context.Background() 则等待完整的 duration。

Types

type AdapterHealthChecker

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

AdapterHealthChecker 检查 Adapter 运行状态

func NewAdapterHealthChecker

func NewAdapterHealthChecker(adapter platform.Adapter) *AdapterHealthChecker

NewAdapterHealthChecker 创建 Adapter 健康检查器

func (*AdapterHealthChecker) Check

func (c *AdapterHealthChecker) Check(_ context.Context) health.CheckResult

Check 执行健康检查，通过 IsRunning() 判断适配器实际运行状态

func (*AdapterHealthChecker) Name

func (c *AdapterHealthChecker) Name() string

Name 返回检查器名称

type Bot

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

Bot 是对 Engine 的高级封装，提供完整的生命周期管理。

生命周期完全委托给 lifecycle.Manager，Bot 只存储配置和组件引用。 Bot.Start() 创建最外层 context 并交给 lifecycle，Bot.Stop() 委托给 lifecycle.Stop()。 lifecycle 管理双层 context：parentCtx（bot 根）→ runCtx（组件运行时）。

D3：Bot 内部统一使用 platformRegistry 作为唯一的平台适配器来源， 不再维护单独的 adapter 字段，消除双路径冗余逻辑。

func MustNewBot

func MustNewBot(adapter platform.Adapter, e *engine.Engine, opts ...Option) *Bot

MustNewBot 同 NewBot，但失败时 panic。适用于初始化阶段且参数已确认合法的场景。

func NewBot

func NewBot(adapter platform.Adapter, e *engine.Engine, opts ...Option) (*Bot, error)

NewBot 创建新的 Bot 实例。

adapter 可以为 nil（仅使用多平台注册表时），非 nil 时会自动包装进内部 Registry。 推荐使用 BotBuilder.Build() 代替直接调用。

若 engine 为 nil，返回错误。编写测试或确信参数合法时可使用 MustNewBot。

func (*Bot) Config

func (b *Bot) Config() BotMeta

Config 获取 Bot 元数据副本。

func (*Bot) Context

func (b *Bot) Context() context.Context

Context 返回 Bot 的根 context。

等价于 lifecycle.ParentContext()，是 Bot 生命周期的最外层 context：

• Start() 期间创建，Stop() 中 OnStop 全部完成后取消
• 可用于创建与 Bot 生命周期绑定的后台 goroutine、初始化 AdaptiveRateLimiter 等

Start() 之前调用返回 context.Background()。

func (*Bot) Engine

func (b *Bot) Engine() *engine.Engine

Engine 返回 Bot 的 Engine 实例

无需加锁：b.engine 在 NewBot 中设置一次且永不修改。 与 Config()/Plugins() 不同，这些字段通过 Use* 方法支持运行时注入。

func (*Bot) Health

func (b *Bot) Health() health.CheckResponse

Health 健康检查

func (*Bot) HealthCheck

func (b *Bot) HealthCheck() *health.Check

HealthCheck 返回 health.Check 实例

func (*Bot) IsRunning

func (b *Bot) IsRunning() bool

IsRunning 返回 Bot 是否正在运行。 委托给 lifecycle.State()，等价于 lifecycle.StateRunning。

func (*Bot) OnAny

func (b *Bot) OnAny(rule ...eventctx.Rule) *engine.Matcher

OnAny 注册处理所有事件的规则

func (*Bot) OnEventKind

func (b *Bot) OnEventKind(kind platform.EventKind, rule ...eventctx.Rule) *engine.Matcher

OnEventKind 注册处理指定平台事件类别的规则（平台无关，推荐）

func (*Bot) PlatformRegistry

func (b *Bot) PlatformRegistry() *platform.Registry

PlatformRegistry 返回已注入的多平台注册表，未注入时返回 nil

func (*Bot) Plugins

func (b *Bot) Plugins() *plugin.Manager

Plugins 返回已注入的插件管理器

func (*Bot) Shutdown

func (b *Bot) Shutdown() error

Shutdown 使用默认超时时间优雅关闭 Bot

func (*Bot) ShutdownAsync

func (b *Bot) ShutdownAsync() <-chan error

ShutdownAsync 在后台 goroutine 中发起优雅关闭，立即返回。

返回一个只读 channel，关闭完成后会写入最终错误（nil 表示成功）。 调用方可选择是否等待结果：

// 触发后不等待（fire-and-forget）
bot.ShutdownAsync()

// 触发后等待结果
if err := <-bot.ShutdownAsync(); err != nil {
    log.Println("shutdown error:", err)
}

适用于以下场景：

• HTTP handler 需要先响应客户端再关闭（同步 Shutdown 会阻塞响应）
• 插件回调内部触发关闭（同步调用会在 lifecycle 链上死锁）
• 与外部框架集成时，对方不允许阻塞其事件循环

注意：多次调用是安全的，后续调用会直接返回已关闭的 channel（Bot.Stop 本身幂等）。

func (*Bot) Start

func (b *Bot) Start() error

Start 启动 Bot。

生命周期由 lifecycle.Manager 管理，Bot 只负责：

1. 构建 adapter snapshot 和注册 lifecycle 组件
2. 创建最外层 context（作为 lifecycle.Start 的入参——lifecycle 内部剥离超时后存储为 parentCtx）
3. 委托 lifecycle.Start

func (*Bot) State

func (b *Bot) State() lifecycle.State

State 返回生命周期状态

func (*Bot) Stop

func (b *Bot) Stop(ctx context.Context) error

Stop 优雅停止 Bot。

生命周期完全委托给 lifecycle.Stop()，其内部顺序为：

1. 取消 runCtx → 通知所有 OnRun goroutine 退出
2. 逆序调用各组件的 OnStop： a. plugin-manager → 所有插件 Teardown（parentCtx 仍有效，可访问平台 API） b. platform adapters → 平台连接断开 c. engine shutdown
3. 取消 parentCtx（Bot 根 context）

注意：已注册为 lifecycle.Component 的组件（含 pluginManager）由 lifecycle 自动管理， 无需手动调用 pm.StopAll()。

func (*Bot) Uptime

func (b *Bot) Uptime() time.Duration

Uptime 返回 Bot 运行时间。 委托给 lifecycle.Uptime()，该函数正确处理运行/停止两种状态的时长计算。

func (*Bot) UsePlatformRegistry

func (b *Bot) UsePlatformRegistry(r *platform.Registry) *Bot

UsePlatformRegistry 注入多平台适配器注册表。

必须在 Bot.Start() 之前调用。

func (*Bot) UsePlugins

func (b *Bot) UsePlugins(pm *plugin.Manager) *Bot

UsePlugins 注入插件管理器

func (*Bot) UseRouter

func (b *Bot) UseRouter(r *router.Router) *Bot

UseRouter 注入策略路由层。

func (*Bot) WaitForShutdown

func (b *Bot) WaitForShutdown(timeout ...time.Duration)

WaitForShutdown 等待系统信号并优雅关闭。

收到第一个 SIGINT（Ctrl+C）或 SIGTERM 时，开始优雅关闭（等待后台清理完成）。 若在优雅关闭期间再次收到 SIGINT，立即强制退出（os.Exit(1)）， 不再等待剩余清理工作——这与大多数 CLI 工具的行为一致。

timeout 为可选参数，指定优雅关闭的超时时间；省略时使用 DefaultShutdownTimeout（30s）。 若同一进程已有另一个 WaitForShutdown 处于监听状态，此次调用会直接返回并打印 Warn 日志。

若需要完全自定义 context（如携带 trace），请直接调用 Bot.Stop。

多 Bot 场景请统一使用 BotManager.WaitForShutdown。

type BotBuilder

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

BotBuilder 提供流畅的Bot构建接口。

平台无关：不直接依赖任何具体平台（QQ、Discord 等）。 平台适配器由调用方创建后通过 BotBuilder.WithPlatformAdapter 或 BotBuilder.WithPlatformRegistry 注入，适配器自行管理其认证和发送逻辑。

使用示例（QQ Webhook）:

adapter := qq.NewWebhookServerAdapter(":8080", botInfo)
bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(adapter).
    WithPlugins(plugin1.New(), plugin2.New()).
    Build()

func NewBotBuilder

func NewBotBuilder() *BotBuilder

NewBotBuilder 创建Bot构建器

func (*BotBuilder) Build

func (b *BotBuilder) Build() (*Bot, error)

Build 构建Bot实例。

D3：内部统一使用 registry 模式。若只设置了单个适配器（WithPlatformAdapter）， Build() 会自动将其注册到 Registry 中，两种使用方式完全透明。

func (*BotBuilder) MustBuild

func (b *BotBuilder) MustBuild() *Bot

MustBuild 构建Bot，如果失败则panic。 适用于确信配置正确的场景，简化错误处理。

func (*BotBuilder) WithDebug

func (b *BotBuilder) WithDebug(debug bool) *BotBuilder

WithDebug 启用调试模式

func (*BotBuilder) WithEngine

func (b *BotBuilder) WithEngine(eng *engine.Engine) *BotBuilder

WithEngine 设置自定义Engine

传入 nil 会被忽略并触发 warning，Build() 将创建默认 Engine。

func (*BotBuilder) WithEngineOptions

func (b *BotBuilder) WithEngineOptions(opts ...engine.Option) *BotBuilder

WithEngineOptions 传递 engine.Option 给 Build() 内部创建的 Engine。

这允许在不绕过 BotBuilder 的情况下自定义 Engine 行为，例如调整清理间隔：

bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(adapter).
    WithEngineOptions(engine.WithCleanupInterval(10 * time.Minute)).
    Build()

注意：若已通过 BotBuilder.WithEngine 传入外部 Engine 实例， 此方法设置的选项将被忽略（外部实例已完成初始化）。

func (*BotBuilder) WithName

func (b *BotBuilder) WithName(name string) *BotBuilder

WithName 设置Bot名称

func (*BotBuilder) WithOption

func (b *BotBuilder) WithOption(opt Option) *BotBuilder

WithOption 添加自定义选项

func (*BotBuilder) WithPlatformAdapter

func (b *BotBuilder) WithPlatformAdapter(adapter platform.Adapter) *BotBuilder

WithPlatformAdapter 设置单平台适配器。

每次调用会覆盖上一次设置的适配器；若需要同时运行多个平台， 请改用 BotBuilder.WithPlatformRegistry。

func (*BotBuilder) WithPlatformRegistry

func (b *BotBuilder) WithPlatformRegistry(r *platform.Registry) *BotBuilder

WithPlatformRegistry 注入多平台适配器注册表。

若此前已通过 WithPlatformAdapter 注册了单个适配器，此方法会先将其迁移到新注册表中， 避免覆盖丢失。也支持多次调用——后调用的注册表会继承前一个的所有适配器：

// 方式一：仅注册表
bot, err := remilia.NewBotBuilder().
    WithPlatformRegistry(platform.NewRegistry().Register(qqAdapter)).
    Build()

// 方式二：单适配器扩充为注册表（自动合并）
bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(discordAdapter).
    WithPlatformRegistry(registry.WithAdapter(qqAdapter)).  // registry 继承 discord
    Build()

func (*BotBuilder) WithPluginManager

func (b *BotBuilder) WithPluginManager(pm *plugin.Manager) *BotBuilder

WithPluginManager 注入插件管理器，将其生命周期与 Bot 绑定。

Build() 后，Bot.Start() 会自动触发所有插件的 Setup， Bot.Stop() 会自动按逆序触发所有插件的 Teardown。

注意：WithPluginManager 与 WithPlugins 可同时使用； WithPlugins 注册的描述符会追加到此 Manager 中。

func (*BotBuilder) WithPlugins

func (b *BotBuilder) WithPlugins(descriptors ...*plugin.Descriptor) *BotBuilder

WithPlugins 一步注册多个插件描述符，无需手动创建 plugin.Manager。

Build() 阶段自动创建（或复用已有的）plugin.Manager 并批量注册， 注册顺序自动按依赖拓扑排序（等同于 RegisterMultipleSmart）。

这是框架推荐的最简洁插件集成方式：

adapter := qq.NewWebhookServerAdapter(":8080", botInfo)
bot, err := remilia.NewBotBuilder().
    WithPlatformAdapter(adapter).
    WithPlugins(myPlugin.New(), anotherPlugin.New()).
    Build()

func (*BotBuilder) WithVersion

func (b *BotBuilder) WithVersion(version string) *BotBuilder

WithVersion 设置Bot版本

type BotError

type BotError struct {
	Name string
	Err  error
}

BotError 代表 BotManager 中单个 Bot 的操作失败。

通过 errors.Is / errors.As 可以检查具体哪个 Bot 失败了：

var be remilia.BotError
if errors.As(err, &be) {
    log.Printf("bot %s failed: %v", be.Name, be.Err)
}

func (*BotError) Error

func (e *BotError) Error() string

func (*BotError) Unwrap

func (e *BotError) Unwrap() error

type BotHealthResult

type BotHealthResult struct {
	Name      string
	IsRunning bool
	Health    health.CheckResponse
}

BotHealthResult 包含单个 Bot 的名称、运行状态和健康检查结果。

type BotManager

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

BotManager 管理多个 Bot 实例的生命周期。

每个 Bot 独立持有自己的 Engine、Adapter 和 lifecycle， BotManager 仅负责统一的启停调度和命名查找。

典型使用场景：

• 同一进程运行多个 QQ Bot 账号（测试账号 + 生产账号）
• 同一逻辑服务的多个机器人实例（分担消息负载）
• 灰度发布：旧 Bot 继续运行，新 Bot 逐步接入

示例：

mgr := remilia.NewBotManager()
mgr.Add("prod", prodBot)
mgr.Add("test", testBot)
if err := mgr.StartAll(ctx); err != nil {
    log.Fatal(err)
}
mgr.WaitForShutdown()

func NewBotManager

func NewBotManager() *BotManager

NewBotManager 创建一个空的 BotManager。

func (*BotManager) Add

func (m *BotManager) Add(name string, bot *Bot) error

Add 注册一个命名 Bot 实例。 若同名 Bot 已存在，返回错误；若 bot 为 nil，同样返回错误。

func (*BotManager) Get

func (m *BotManager) Get(name string) (*Bot, bool)

Get 按名称获取 Bot 实例。若不存在，返回 nil, false。

func (*BotManager) HealthAll

func (m *BotManager) HealthAll() map[string]BotHealthResult

HealthAll 并发执行所有 Bot 的健康检查，以 map[name]CheckResponse 返回。

func (*BotManager) Len

func (m *BotManager) Len() int

Len 返回已注册 Bot 的数量。

func (*BotManager) MustAdd

func (m *BotManager) MustAdd(name string, bot *Bot) *BotManager

MustAdd 注册 Bot，失败时 panic。

此方法仅适用于程序 main() 初始化阶段，在配置已确认正确的前提下使用， 目的是减少样板错误处理代码。

警告：请勿在运行时（如插件回调、HTTP handler、goroutine 中）调用此方法， 否则 panic 将导致整个进程崩溃。运行时场景请使用 BotManager.Add。

func (*BotManager) MustGet

func (m *BotManager) MustGet(name string) *Bot

MustGet 按名称获取 Bot 实例，若不存在则 panic。

此方法仅适用于程序 main() 初始化阶段，在确信目标 Bot 已通过 Add/MustAdd 注册的前提下使用。

警告：请勿在运行时（如插件回调、HTTP handler、goroutine 中）调用此方法， 否则 panic 将导致整个进程崩溃。运行时场景请使用 BotManager.Get。

func (*BotManager) Names

func (m *BotManager) Names() []string

Names 返回所有已注册 Bot 的名称，按注册顺序排列。

func (*BotManager) Remove

func (m *BotManager) Remove(name string) bool

Remove 从管理器中移除 Bot。 注意：Remove 不会自动停止 Bot，请在 Remove 前先调用 bot.Stop()。

func (*BotManager) RunningBots

func (m *BotManager) RunningBots() []string

RunningBots 返回当前处于运行状态的 Bot 名称列表。

func (*BotManager) Shutdown

func (m *BotManager) Shutdown() error

Shutdown 使用默认超时时间停止所有 Bot（DefaultShutdownTimeout）。

func (*BotManager) ShutdownAsync

func (m *BotManager) ShutdownAsync() <-chan error

ShutdownAsync 在后台 goroutine 中发起优雅关闭，立即返回。

返回一个只读 channel，所有 Bot 关闭完成后会写入最终错误（nil 表示全部成功）。 调用方可选择是否等待结果：

// 触发后不等待（fire-and-forget）
mgr.ShutdownAsync()

// 触发后等待结果
if err := <-mgr.ShutdownAsync(); err != nil {
    log.Println("shutdown error:", err)
}

适用于以下场景：

• HTTP handler 收到 /shutdown 请求，需先响应 200 再后台关闭
• 插件回调内部触发关闭（同步调用会在 lifecycle 链上死锁）
• 与外部框架集成时对方不允许阻塞其事件循环

注意：多次调用是安全的，StopAll 对每个 Bot 的 Stop 调用均幂等。

func (*BotManager) StartAll

func (m *BotManager) StartAll() error

StartAll 并发启动所有已注册的 Bot。 任何一个 Bot 启动失败都会记录错误，但不会阻止其他 Bot 的启动。 若所有 Bot 均启动失败，返回聚合错误；若部分失败，同样返回聚合错误， 调用方可通过 errors.Is / errors.As 检查具体失败项。

func (*BotManager) Status

func (m *BotManager) Status() BotManagerStatus

Status 返回所有 Bot 的当前状态摘要。

func (*BotManager) StopAll

func (m *BotManager) StopAll(ctx context.Context) error

StopAll 并发停止所有正在运行的 Bot，使用给定的 context 作为超时控制。 即使部分 Bot 停止失败，也会继续停止其他 Bot，最终返回聚合错误（如有）。

func (*BotManager) WaitForShutdown

func (m *BotManager) WaitForShutdown(timeout ...time.Duration)

WaitForShutdown 阻塞直到收到 SIGINT/SIGTERM 信号，然后优雅停止所有 Bot。 这是生产环境启动多 Bot 后的标准收尾调用。

收到第一个 SIGINT（Ctrl+C）或 SIGTERM 时，开始优雅关闭（等待后台清理完成）。 若在优雅关闭期间再次收到 SIGINT，立即强制退出（os.Exit(1)）， 不再等待剩余清理工作——这与大多数 CLI 工具的行为一致。

timeout 为可选参数，指定优雅关闭的超时时间；省略时使用 DefaultShutdownTimeout（30s）。 若同一进程已有另一个 WaitForShutdown 处于监听状态，此次调用会直接返回并打印 Warn 日志。

若需要完全自定义 context（如携带 trace），请直接调用 BotManager.StopAll。

示例：

mgr.StartAll()
mgr.WaitForShutdown()                    // 使用默认 30s 超时
mgr.WaitForShutdown(60 * time.Second)    // 自定义超时

type BotManagerBuilder

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

BotManagerBuilder 提供流畅的 BotManager 构建接口。

示例：

mgr, err := remilia.NewBotManagerBuilder().
    Add("prod", prodAdapter, &prodBotInfo).
    Add("test", testAdapter, &testBotInfo).
    Build()

func NewBotManagerBuilder

func NewBotManagerBuilder() *BotManagerBuilder

NewBotManagerBuilder 创建 BotManager 构建器。

func (*BotManagerBuilder) AddBot

func (b *BotManagerBuilder) AddBot(name string, bot *Bot) *BotManagerBuilder

AddBot 向构建器中添加一个已构建的 Bot 实例。

func (*BotManagerBuilder) AddBuilder

func (b *BotManagerBuilder) AddBuilder(name string, builder *BotBuilder) *BotManagerBuilder

AddBuilder 向构建器中添加一个 BotBuilder，Build() 时自动构建。 这允许延迟构建，统一处理错误。

func (*BotManagerBuilder) Build

func (b *BotManagerBuilder) Build() (*BotManager, error)

Build 构建 BotManager，返回错误（如有）。

func (*BotManagerBuilder) MustBuild

func (b *BotManagerBuilder) MustBuild() *BotManager

MustBuild 构建 BotManager，失败时 panic。

type BotManagerError

type BotManagerError struct {
	Op     string
	Errors []BotError
}

BotManagerError 代表 BotManager 批量操作（StartAll / StopAll）中的聚合错误。

通过 BotManagerError.FailedBots() 可获取所有失败 Bot 的名称列表。 支持 errors.Is / errors.As 提取具体 Bot 的错误。

func (*BotManagerError) Error

func (e *BotManagerError) Error() string

func (*BotManagerError) FailedBots

func (e *BotManagerError) FailedBots() []string

FailedBots 返回所有失败的 Bot 名称列表

type BotManagerStatus

type BotManagerStatus struct {
	Total   int
	Running int
	Stopped int
	Uptime  map[string]time.Duration
}

BotManagerStatus 描述 BotManager 当前整体状态

type BotMeta

type BotMeta struct {
	Name    string
	Version string
	Debug   bool
}

BotMeta Bot 元数据配置（区别于 config.Config 全量配置）。

type BotStatusChecker

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

BotStatusChecker 检查 Bot 的基本状态

func NewBotStatusChecker

func NewBotStatusChecker(bot *Bot) *BotStatusChecker

NewBotStatusChecker 创建 Bot 状态检查器

func (*BotStatusChecker) Check

func (c *BotStatusChecker) Check(_ context.Context) health.CheckResult

Check 执行健康检查

func (*BotStatusChecker) Name

func (c *BotStatusChecker) Name() string

Name 返回检查器名称

type DLQHealthAdapter

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

DLQHealthAdapter 将任意 dlq.Queue[T] 适配为 health.DLQStats 接口。

这是解决 infra/health 不应直接依赖 infra/dlq 的适配器（Adapter Pattern）。 infra/health 只知道 health.DLQStats 接口，实际的 DLQ 类型在上层（bot 层）注入。

使用示例：

q := dlq.NewPayloadQueue(dlq.PayloadConfig{...})
adapter := remilia.NewDLQHealthAdapter(q)
botHealth.AddChecker(health.NewDeadLetterQueueHealthChecker(adapter, 1000, 0.1))

func NewDLQHealthAdapter

func NewDLQHealthAdapter(q dlqStater) *DLQHealthAdapter

NewDLQHealthAdapter 创建 DLQ 健康检查适配器。 接受任意实现了 Stats() dlq.Stats 的队列，例如 *dlq.PayloadQueue 或 *dlq.PlatformEventQueue。

func (*DLQHealthAdapter) Stats

func (a *DLQHealthAdapter) Stats() health.DLQStatsSnapshot

Stats 实现 health.DLQStats 接口，将 dlq.Stats 转换为 health.DLQStatsSnapshot

type Option

type Option func(*Bot)

Option Bot 配置选项函数类型

func WithAdapter

func WithAdapter(adapter platform.Adapter) Option

WithAdapter 将平台适配器注册到 Bot 的内部 Registry。

D3：Bot 不再有独立的 adapter 字段，所有适配器统一通过 platformRegistry 管理。 若 Bot 尚未初始化 Registry，此方法会自动创建。

func WithConfig

func WithConfig(config *BotMeta) Option

WithConfig 设置 Bot 元数据

func WithDebug

func WithDebug(debug bool) Option

WithDebug 设置调试模式

func WithEngine

func WithEngine(engine *engine.Engine) Option

WithEngine 设置自定义 engine

func WithName

func WithName(name string) Option

WithName 设置 Bot 名称

func WithPprof

func WithPprof(cfg PprofConfig) Option

WithPprof 注入 pprof 服务器，使其生命周期与 Bot 绑定（Start 时启动，Stop 时关闭）。

使用示例：

bot := remilia.NewBotBuilder().
    WithOption(remilia.WithPprof(remilia.DefaultPprofConfig())).
    Build()

func WithVersion

func WithVersion(version string) Option

WithVersion 设置 Bot 版本

type PprofConfig

type PprofConfig struct {
	// Enabled 是否启用 pprof
	Enabled bool

	// Addr 监听地址
	Addr string

	// AutoProfile 是否启用自动性能分析
	AutoProfile bool

	// ProfileInterval 自动分析间隔
	ProfileInterval time.Duration

	// ProfileDuration 每次分析持续时间
	ProfileDuration time.Duration

	// OutputDir 性能分析文件输出目录
	OutputDir string

	// EnableMutex 是否启用互斥锁分析
	EnableMutex bool

	// EnableBlock 是否启用阻塞分析
	EnableBlock bool

	// MutexProfileFraction 互斥锁分析采样率
	MutexProfileFraction int

	// BlockProfileRate 阻塞分析采样率
	BlockProfileRate int
}

PprofConfig pprof 配置

func DefaultPprofConfig

func DefaultPprofConfig() PprofConfig

DefaultPprofConfig 返回默认配置

type PprofServer

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

PprofServer pprof 服务器

func NewPprofServer

func NewPprofServer(config PprofConfig) *PprofServer

NewPprofServer 创建 pprof 服务器

func (*PprofServer) AddHandler

func (p *PprofServer) AddHandler(path string, handler http.HandlerFunc)

AddHandler 注册一个额外的 HTTP handler 到 pprof 服务器的 mux。 必须在 Start() 之前调用。可用于注入 /health 等管理端点。

func (*PprofServer) Start

func (p *PprofServer) Start() error

Start 启动 pprof 服务器

func (*PprofServer) Stop

func (p *PprofServer) Stop(ctx context.Context) error

Stop 停止 pprof 服务器