cellbot/internal/protocol/interface.go

package protocol

import (
	"context"
)

// Protocol 通用协议接口
// 参考OneBot12协议核心设计理念，定义统一的机器人协议接口
type Protocol interface {
	// Name 获取协议名称
	Name() string
	// Version 获取协议版本
	Version() string
	// Connect 建立连接
	Connect(ctx context.Context) error
	// Disconnect 断开连接
	Disconnect(ctx context.Context) error
	// IsConnected 检查连接状态
	IsConnected() bool
	// SendAction 发送动作
	SendAction(ctx context.Context, action Action) (map[string]interface{}, error)
	// HandleEvent 处理事件
	HandleEvent(ctx context.Context, event Event) error
	// GetSelfID 获取机器人自身ID
	GetSelfID() string
}

// Adapter 协议适配器接口
// 实现具体协议的接入逻辑
type Adapter interface {
	Protocol
	// ParseMessage 解析原始消息为Event
	ParseMessage(raw []byte) (Event, error)
	// SerializeAction 序列化Action为协议格式
	SerializeAction(action Action) ([]byte, error)
}

// BotInstance 机器人实例接口
// 管理单个机器人实例的生命周期
type BotInstance interface {
	Protocol
	// GetID 获取实例ID
	GetID() string
	// Start 启动实例
	Start(ctx context.Context) error
	// Stop 停止实例
	Stop(ctx context.Context) error
	// GetStatus 获取实例状态
	GetStatus() BotStatus
}

// BotStatus 机器人状态
type BotStatus string

const (
	BotStatusStarting BotStatus = "starting"
	BotStatusRunning  BotStatus = "running"
	BotStatusStopping BotStatus = "stopping"
	BotStatusStopped  BotStatus = "stopped"
	BotStatusError    BotStatus = "error"
)

// EventHandler 事件处理器接口
type EventHandler interface {
	// Handle 处理事件
	Handle(ctx context.Context, event Event) error
	// Priority 获取处理器优先级(数值越小优先级越高)
	Priority() int
	// Match 判断是否匹配事件
	Match(event Event) bool
	// Name 获取处理器名称
	Name() string
	// Description 获取处理器描述
	Description() string
}

// Middleware 中间件接口
type Middleware interface {
	// Process 处理事件
	Process(ctx context.Context, event Event, next func(ctx context.Context, event Event) error) error
}