platform

type APIProvider interface {
	// PlatformAPI 返回平台特有的 API 句柄。
	PlatformAPI() any
}

type Adapter interface {
	// Platform 返回平台标识符（小写，如 "qq"、"discord"、"telegram"）
	Platform() string

	// Start 启动适配器事件循环（阻塞，直到 ctx 取消或出错）
	//
	// 每收到一个事件，调用 handler(event)。
	// handler 应快速返回（框架内部会在 goroutine 中处理）。
	Start(ctx stdctx.Context, handler func(Event)) error

	// Stop 优雅停止适配器
	Stop(ctx stdctx.Context) error

	// Sender 返回该平台的消息发送接口
	Sender() Sender

	// Capabilities 返回该平台支持的特性集合。
	// 用于 Handler 做跨平台特性检测，实现渐进增强策略。
	Capabilities() Capabilities

	// IsRunning 返回适配器当前是否处于运行状态。
	//
	// 在 Start() 成功启动后返回 true，Stop() 完成后返回 false。
	// 用于健康检查和监控，实现应保证并发安全。
	IsRunning() bool
}

type AdapterObserver interface {
	// OnAdapterStarted 适配器 goroutine 启动时调用（Start 开始阻塞前）。
	OnAdapterStarted(platform string)
	// OnAdapterStopped 适配器 goroutine 退出时调用（无论是否有错误）。
	OnAdapterStopped(platform string)
	// OnAdapterError 适配器以非 context 取消/超时错误退出时调用。
	// errMsg 为 error.Error() 文本，避免直接传递 error 接口引起 alloc。
	OnAdapterError(platform, errMsg string)
	// OnAdapterDisconnect RecoverableAdapter 意外断连时调用。
	OnAdapterDisconnect(platform string, err error)
}

type Announcement struct {
	// ID 公告 ID（用于删除）。
	ID string
	// Content 公告内容。
	Content string
	// PublisherID 发布者用户 ID。
	PublisherID string
	// ImageURL 公告配图 URL（平台不提供时为空）。
	ImageURL string
	// Timestamp Unix 时间戳（秒）。
	Timestamp int64
	// Extra 平台特有扩展字段（key-value 形式）。
	Extra map[string]any
}

type AnnouncementManager interface {
	// SendAnnouncement 发布群公告。
	// imageURL 为可选配图 URL，空字符串表示纯文字公告。
	// 平台不支持时返回 [ErrNotSupported]。
	SendAnnouncement(ctx stdctx.Context, groupID, content, imageURL string) error

	// GetAnnouncements 获取群公告列表。
	// 平台不支持时返回 [ErrNotSupported]。
	GetAnnouncements(ctx stdctx.Context, groupID string) ([]Announcement, error)
}

type Attachment struct {
	// Kind 附件媒体类型（出站必填；入站平台可推断时填充）
	Kind AttachmentKind
	// URL 附件远程 URL（出站发送 / 入站接收）
	URL string
	// Data 本地二进制数据（出站直传，URL 为空时使用；入站为空）
	Data []byte
	// MimeType MIME 类型，如 "image/png"（可选，辅助平台正确处理）
	MimeType string
	// Name 文件名（与 Data 或 URL 配合；平台不支持时可忽略）
	Name string
	// Size 文件大小（字节），入站平台不提供时为 0
	Size int
	// Width 图片/视频宽度（像素），非媒体类型或平台不提供时为 0
	Width int
	// Height 图片/视频高度（像素），非媒体类型或平台不提供时为 0
	Height int
	// Extra 平台专属扩展元数据（key-value 形式），无扩展数据时为 nil。
	//
	// 已知键（见各平台 extra.go 中的常量定义）：
	//   - "voice":  QQ 语音附件的 WAV 链接与 ASR 文本（*qq.VoiceAttachmentMeta）
	//   - "button": QQ 按钮权限控制（*qq.ButtonExtra）
	Extra map[string]any
}

type AttachmentKind string

type AutoModerator interface {
	// DeleteMemberMessage 删除群成员发送的消息（机器人需有管理员权限）。
	DeleteMemberMessage(ctx stdctx.Context, groupID, messageID string) error

	// MuteAll 开启/关闭全体禁言（mute=true 开启，false 解除）。
	// 平台不支持时返回 [ErrNotSupported]。
	MuteAll(ctx stdctx.Context, groupID string, mute bool) error
}

type AvatarProvider interface {
	// GetUserAvatarURL 获取指定用户的头像 URL。
	// userID 为平台用户唯一 ID。
	// 平台不支持时返回 [ErrNotSupported]。
	GetUserAvatarURL(ctx stdctx.Context, userID string) (string, error)
}

type BotIdentity interface {
	// BotID 返回机器人在当前平台的唯一标识符。
	//
	// 与 event.Sender().ID 对比可判断事件是否由机器人自身触发。
	// 平台未提供或尚未连接时返回空字符串。
	BotID() string

	// BotName 返回机器人的显示名称（昵称/用户名）。
	//
	// 平台未提供时返回空字符串。
	BotName() string
}

type Button struct {
	// ID 按钮回调标识符（如 Discord 的 custom_id、Telegram 的 callback_data）
	ID string
	// Label 按钮显示文字
	Label string
	// URL 链接目标（Style 为 ButtonStyleLink 时有效）
	URL string
	// Command 指令按钮文本（如 "/help"）。
	//
	// 非空时按钮为"指令按钮"：点击后把命令插入输入框（如 QQ 的
	// action.type=2，自动插入 "@bot <Command>"），不产生交互回调事件，
	// 由用户自行发送。平台不支持指令按钮时忽略此字段。
	Command string
	// Style 按钮样式
	Style ButtonStyle
	// Disabled 按钮是否置灰不可点击（Discord/QQ 均支持）
	Disabled bool
	// Row 按钮所在行。
	//
	//   - ButtonRowAuto（0，零值默认）：由平台自动排列，每个此值的按钮独占一行
	//   - 1 ～ 5：显式行号，相同 Row 值的按钮排列在同一行（1 = 第一行）
	//
	// Discord 最多 5 行，每行最多 5 个按钮；超出部分截断。
	Row int
	// Emoji 按钮前展示的 emoji（Discord 原生支持，其他平台忽略）
	Emoji string
	// Extra 平台专属按钮扩展字段（key-value 形式）。
	//
	// 用于携带通用字段无法表达的平台特定配置，各平台 Sender 读取。
	// 不支持此字段的平台可安全忽略。
	//
	// 已知键（见各平台 extra.go 中的常量定义）：
	//   - "button": QQ 按钮权限控制（*qq.ButtonExtra）
	//   - "inline": Telegram switch_inline_query 等扩展字段（*telegram.InlineButtonExtra）
	Extra map[string]any
}

type ButtonStyle string

type Capabilities struct {
	// Markdown 是否支持 Markdown 格式消息
	Markdown bool
	// Buttons 是否支持交互按钮（内联键盘等）
	Buttons bool
	// MultiAttachment 是否支持在一条消息中发送多个附件
	MultiAttachment bool
	// MessageEdit 是否支持编辑已发送消息（实现 MessageEditor）
	MessageEdit bool
	// MessageDelete 是否支持删除/撤回消息（实现 MessageDeleter）
	MessageDelete bool
	// Embeds 是否支持富文本嵌入卡片
	Embeds bool
	// FileUpload 是否支持二进制文件直传（非 URL，Attachment.Data）
	FileUpload bool
	// GuildSupport 是否有服务器/频道层级（ChatInfo.ParentID 有效）
	GuildSupport bool
	// Reactions 是否支持表情回应（Discord/Telegram/QQ 均支持）
	Reactions bool
	// ThreadReply 是否支持消息回复链/引用回复
	ThreadReply bool
	// TypingIndicator 是否支持"正在输入"状态
	TypingIndicator bool
	// MentionAll 是否支持 @全体成员
	MentionAll bool
	// VoiceChannel 是否支持语音频道（Discord Stage/VC）
	VoiceChannel bool
	// Caption 是否支持在同一条消息内同时携带文本与附件（图文同发）。
	// Telegram（媒体 caption）、Discord（content+附件）、OneBot（CQ 码混排）、
	// Satori（元素列表）、QQ（msg_type=7 携带 media+content，单媒体）支持。
	Caption bool
	// Forward 是否支持合并转发（发送与接收）。
	// 例：OneBot/QQ 原生支持；Discord/Telegram 不支持（出站转发时降级）。
	Forward bool

	// MaxTextLength 单条文本消息最大字符数。
	// 例：Discord=2000，Telegram=4096，QQ=0（未公开）。
	MaxTextLength int
	// MaxAttachmentMB 单个附件最大大小（MB）。
	// 例：Discord=8，Telegram=50，QQ=0（未公开）。
	MaxAttachmentMB int
	// MaxButtonsPerRow 每行最多按钮数（0=无已知限制）。
	// 例：Discord/QQ=5。
	MaxButtonsPerRow int
	// MaxButtonRows 最多按钮行数（0=无已知限制）。
	// 例：Discord/QQ=5。
	MaxButtonRows int
	// MaxEmbedFields 单个 Embed 最多字段数（0=无已知限制）。
	// 例：Discord=25。
	MaxEmbedFields int
}

type CapabilityFlag uint64

type ChatInfo struct {
	// ID 会话/群组/频道唯一标识
	// 私聊：用户 ID；群组：群 ID；频道/话题：channel_id
	ID string
	// ParentID 父容器唯一标识（服务器/频道层级时使用）。
	//
	// 频道消息：guild_id / 服务器 ID
	// Discord: guild_id；QQ 频道: guild_id
	// 私聊和普通群组为空字符串。
	ParentID string
	// Name 会话名称（可选，部分平台不提供）
	Name string
	// IsGroup 是否为群组/频道消息（false = 私聊）
	IsGroup bool
	// IsDM 是否为私信（Direct Message）会话。
	//
	// 与 IsGroup=true、ParentID 非空同时成立时，
	// 表示这是一条频道私信（如 QQ DIRECT_MESSAGE_CREATE），
	// 发送回复时应使用 DM 专属接口而非普通频道消息接口。
	IsDM bool

	// Tokens 平台专属授权令牌，用于平台内部路由或被动回复授权。
	//
	// 各平台适配器在解析事件时写入，平台 Sender 在发送时读取。
	// 框架层 handler 通常无需直接访问此字段。
	//
	// 已知 token 键（见各平台 extra.go 中的常量定义）：
	//   - QQ: TokenMsgID ("msg_id")、TokenEventID ("event_id")
	//
	// 读取 nil map 是安全的（返回空字符串），写入前须先初始化。
	Tokens map[string]string
}

type DegradePolicy func(s Segment, samePlatform bool) []Segment

type DirectedAtBotEvent interface {
	// DirectedAtBot 返回本条消息在平台语义上是否直接发给机器人。
	DirectedAtBot() bool
}

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

type EditableEvent interface {
	// IsEdited 返回此事件是否为消息编辑事件
	IsEdited() bool
	// OriginalTimestamp 返回原始消息的发送时间戳（零值表示不可用）
	OriginalTimestamp() time.Time
}

type Embed struct {
	// Title 标题
	Title string
	// Description 正文描述（支持 Markdown，平台不支持时降级为纯文本）
	Description string
	// URL 标题跳转链接（可选）
	URL string
	// Color 边框/主题颜色，RGB 十六进制无符号整数，如 0x5865F2（Discord 蓝）
	Color uint32
	// Fields 字段列表
	Fields []EmbedField
	// ImageURL 正文大图 URL
	ImageURL string
	// ThumbnailURL 右上角缩略图 URL
	ThumbnailURL string
	// FooterText 页脚文本
	FooterText string
	// Timestamp 时间戳（显示在页脚，零值表示不展示）
	Timestamp time.Time
}

type EmbedField struct {
	// Name 字段标题
	Name string
	// Value 字段内容
	Value string
	// Inline 是否与相邻字段同行展示（Discord 支持，其他平台忽略）
	Inline bool
}

type Emoji struct {
	// Kind 表情种类
	Kind EmojiKind
	// ID 平台内部 emoji ID。
	// 标准 Unicode 表情此字段为空，直接使用 Value。
	ID string
	// Value emoji 字面量或名称。
	// Unicode 表情填字符本身（如 "👍"）；自定义表情填显示名称（如 "myEmoji"）。
	Value string
}

type EmojiKind string

type Event interface {
	EventIdentity

	// Segments 返回有序消息段（唯一真相源）。
	//
	// 正文/附件便捷视图由帮助函数派生：
	//   - Content(e)      = TrimSpace(SegmentsContent(e.Segments()))
	//   - Attachments(e)  = SegmentsAttachments(e.Segments())
	Segments() []Segment

	// Sender 返回消息发送者信息
	Sender() UserInfo

	// Chat 返回消息所在会话信息
	Chat() ChatInfo

	// Timestamp 返回事件时间戳（尽力而为，平台不提供时返回零值）
	Timestamp() time.Time
}

type EventIdentity interface {
	// Platform 返回平台标识符（如 "qq"、"discord"、"telegram"）
	Platform() string

	// Kind 返回平台无关的事件类别
	Kind() EventKind

	// ID 返回平台级别的唯一事件标识符。
	//
	// 用途：去重、追踪、死信队列等需要唯一标识的场景。
	// 平台不提供时返回空字符串；调用方应对空字符串做兼容处理。
	ID() string
}

type EventKind string

type ForwardNode struct {
	// Sender 子消息发送者（多数平台仅能提供昵称，ID 可能不可得）。
	Sender UserInfo
	// Segments 子消息内容段（text/image/audio/video/file，保序）。
	Segments []Segment
	// Kind 条目语义类型：""（普通消息）或 ForwardKindQuote / ForwardKindRecord。
	Kind ForwardNodeKind
	// Related 关联子条目：Kind=ForwardKindQuote 时为被引用消息的渲染
	// （通常 1 条），Kind=ForwardKindRecord 时为嵌套转发记录的消息列表。
	Related []ForwardNode
}

type ForwardNodeKind string

type ForwardOption func(*forwardConfig)

type ForwardRecord struct {
	// Title 记录标题（如 "XX和YY的聊天记录"），可能为空。
	Title string
	// Nodes 按原始顺序排列的子消息。
	Nodes []ForwardNode
}

type GroupInfo struct {
	// ID 群组唯一标识
	ID string
	// Name 群组名称
	Name string
	// MemberCount 成员数量（平台不提供时为 0）
	MemberCount int
	// Description 群组简介（平台不提供时为空字符串）
	Description string
}

type GroupInfoProvider interface {
	// GetGroupInfo 查询群组基本信息（名称、成员数等）。
	//
	// 平台不支持时返回 [ErrNotSupported]。
	GetGroupInfo(ctx stdctx.Context, groupID string) (GroupInfo, error)

	// GetGroupMemberList 获取群所有成员的基本信息列表。
	//
	// 大型群组下列表可能很长，各平台可能有分页限制。
	// 平台不支持时返回 [ErrNotSupported]。
	GetGroupMemberList(ctx stdctx.Context, groupID string) ([]GroupMemberInfo, error)

	// GetGroupMember 查询指定群成员的详细信息。
	//
	// 成员不存在或被踢出时返回错误；平台不支持时返回 [ErrNotSupported]。
	GetGroupMember(ctx stdctx.Context, groupID, userID string) (GroupMemberInfo, error)

	// GetJoinedGroups 返回机器人当前已加入的群组 ID 列表。
	//
	// 用于定时推送（整点报时、每日新闻）等需要枚举目标群的场景。
	// 平台不支持时返回 [ErrNotSupported]。
	GetJoinedGroups(ctx stdctx.Context) ([]GroupInfo, error)
}

type GroupManager interface {
	// KickMember 将指定用户踢出群组。
	//
	// permanent=true 时拉黑（禁止重新加入），false 时仅踢出。
	// 平台不支持 permanent 时应忽略并返回 nil。
	KickMember(ctx stdctx.Context, groupID, userID string, permanent bool) error

	// BanMember 禁言/解禁指定用户。
	//
	// duration 为禁言时长；传入 0 表示解除禁言。
	BanMember(ctx stdctx.Context, groupID, userID string, duration time.Duration) error

	// SetAdmin 授予/撤销群内管理员身份。
	//
	// isAdmin=true 授予管理员；isAdmin=false 撤销。
	// 平台不支持时返回 [ErrNotSupported]。
	SetAdmin(ctx stdctx.Context, groupID, userID string, isAdmin bool) error
}

type GroupMemberInfo struct {
	// UserID 用户唯一标识
	UserID string
	// DisplayName 群内昵称（优先于用户昵称）；若平台不提供则为用户全局昵称
	DisplayName string
	// GroupRole 成员角色（普通/管理/群主）
	GroupRole GroupRole
	// JoinedAt 加入群组的时间（平台不提供时为零值）
	JoinedAt time.Time
	// AvatarURL 用户头像 URL（平台不提供时为空字符串）
	AvatarURL string
}

type GroupRole int

type GroupSettings interface {
	// SetGroupName 修改群名称。
	// 平台不支持时返回 [ErrNotSupported]。
	SetGroupName(ctx stdctx.Context, groupID, name string) error

	// SetGroupCard 设置群成员名片（备注名）。
	// card 为空字符串时清除名片。
	// 平台不支持时返回 [ErrNotSupported]。
	SetGroupCard(ctx stdctx.Context, groupID, userID, card string) error

	// SetGroupSpecialTitle 设置群成员专属头衔。
	// title 为空字符串时清除头衔。
	// 平台不支持时返回 [ErrNotSupported]。
	SetGroupSpecialTitle(ctx stdctx.Context, groupID, userID, title string) error

	// LeaveGroup 退出群组；dismiss 为 true 时尝试解散群（仅群主）。
	// 平台不支持时返回 [ErrNotSupported]。
	LeaveGroup(ctx stdctx.Context, groupID string, dismiss bool) error
}

type HealthDetailer interface {
	HealthDetail() map[string]any
}

type InvitationHandler interface {
	// AcceptGroupInvite 接受群组邀请（inviteID 来自群邀请事件）。
	AcceptGroupInvite(ctx stdctx.Context, inviteID string) error

	// RejectGroupInvite 拒绝群组邀请（reason 不支持时忽略）。
	RejectGroupInvite(ctx stdctx.Context, inviteID, reason string) error

	// AcceptFriendRequest 接受好友申请（requestID 来自好友申请事件）。
	AcceptFriendRequest(ctx stdctx.Context, requestID string) error

	// RejectFriendRequest 拒绝好友申请。
	RejectFriendRequest(ctx stdctx.Context, requestID, reason string) error
}

type MentionsEvent interface {
	// Mentions 返回消息中 @ 的用户列表。
	// 包含被 @ 的机器人自身（IsSelf=true 标记，OnMentionedBot 依赖此语义）；
	// 无 @ 用户时返回 nil。
	Mentions() []UserInfo
}

type Message struct {
	// ID 平台消息 ID（可用于撤回/编辑）。
	ID string
	// Platform 消息来源平台 ID（= EventIdentity.Platform()，MessageFromEvent 填充；
	// 转发判定用，见 MessageToOutbound）。
	Platform string
	// Sender 发送者信息。
	Sender UserInfo
	// Chat 消息所在会话。
	Chat ChatInfo
	// Segments 有序消息段（唯一真相源）。
	Segments []Segment
	// Content 消息文本内容（纯文本，不含平台特定格式；= SegmentsContent(Segments())）。
	Content string
	// Timestamp 消息发送时间（平台不提供时为零值）。
	Timestamp time.Time
	// Attachments 消息携带的附件列表（= SegmentsAttachments(Segments())）。
	Attachments []Attachment
	// Mentions 消息中 @ 的用户列表。
	Mentions []UserInfo
	// ReplyToID 被回复消息的平台原生 ID（非回复时为空）。
	ReplyToID string
	// Extra 平台特有扩展字段（key-value 形式）。
	Extra map[string]any
}

type MessageDeleter interface {
	// Delete 删除/撤回已发送的消息。
	// chatID 为目标会话 ID，messageID 为平台原生消息 ID。
	Delete(ctx stdctx.Context, chatID, messageID string) error
}

type MessageEditor interface {
	// Edit 编辑已发送的消息。
	// chatID 为目标会话 ID（频道/群/私聊），messageID 为平台原生消息 ID。
	Edit(ctx stdctx.Context, chatID, messageID string, msg OutboundMessage) error
}

type MessageHistoryProvider interface {
	// GetGroupHistory 获取群历史消息。
	// chatID 为群会话 ID（取事件 Chat().ID 原样传入）；limit 为最大返回条数（0 使用平台默认值）。
	// 返回按时间从新到旧排列的消息快照列表。
	// 平台不支持时返回 [ErrNotSupported]。
	GetGroupHistory(ctx stdctx.Context, chatID string, limit int) ([]Message, error)

	// GetFriendHistory 获取好友（私聊）历史消息。
	// chatID 为用户会话 ID；limit 为最大返回条数（0 使用平台默认值）。
	// 平台不支持时返回 [ErrNotSupported]。
	GetFriendHistory(ctx stdctx.Context, chatID string, limit int) ([]Message, error)
}

type NoopSender struct{}

type OutboundMessage struct {
	// Segments 有序消息段（主字段，新增）。
	// 非空时 Sender 按段顺序发送，忽略下方扁平字段（唯一真相源）。
	// 为空时走下方便捷字段路径（兼容旧调用方）。
	Segments []Segment

	// Text 纯文本内容
	Text string

	// Markdown Markdown 格式内容（平台不支持时降级为 Text）
	Markdown string

	// Attachments 附件列表（图片/音频/视频/文件，支持多附件）
	//
	// 不支持多附件的平台（如 QQ）只处理第一个匹配当前能力的附件。
	Attachments []Attachment

	// Embeds 富文本嵌入卡片列表（Discord 原生、其他平台降级处理）
	Embeds []Embed

	// Mentions 被 @ 用户的 ID 列表（平台内唯一标识符）
	//
	// QQ 平台：member_openid；Discord/Telegram：user_id。
	// 各平台 Sender 负责将其转换为平台特定的 @ 格式。
	Mentions []string

	// Buttons 交互按钮列表（Discord 组件、Telegram 内联键盘等）
	//
	// 不支持按钮的平台可安全忽略此字段。
	Buttons []Button

	// ReplyToID 回复的目标消息 ID（平台原生消息 ID）
	ReplyToID string

	// QuoteTrigger 引用"触发本条会话的那条消息"（平台渲染引用气泡/回复）。
	//
	// 供插件在发送时按条选择：需要引用触发消息时设置，不需要则不设置
	// （默认关闭，无任何全局/启动配置）。目标 ID 由 Sender 从事件上下文解析，
	// 调用方无需知道平台原生 ID：
	//   - QQ C2C/群聊：message_reference.message_id = 事件 msg_idx（REFIDX）
	//   - QQ 频道：message_reference.message_id = 事件消息 ID
	//   - 其它平台：暂未实现，标记被安全忽略
	// 与 ReplyToID 的关系：显式 ReplyToID 优先；两者都未提供时不产生引用。
	// 事件无可引用消息（如主动 Notify）时该标记静默不生效。
	QuoteTrigger bool

	// Extra 平台特定扩展字段（key-value 形式）
	//
	// 示例（QQ 平台传递 msg_seq）：
	//   msg.Extra = map[string]any{"msg_seq": 1}
	Extra map[string]any
}

type RawEvent interface {
	// RawType 返回平台原始事件类型字符串（如 QQ 的 "C2C_MESSAGE_CREATE"）
	RawType() string

	// RawPayload 返回原始平台 payload（类型断言后可访问平台特定字段）
	//
	// 示例（QQ 平台）:
	//   if payload, ok := e.RawPayload().(*dto.Payload); ok { ... }
	RawPayload() any
}

type ReactionSender interface {
	// AddReaction 为指定消息添加表情回应。
	// chatID 为目标会话 ID，messageID 为平台原生消息 ID，emoji 为平台无关表情标识。
	AddReaction(ctx stdctx.Context, chatID, messageID string, emoji Emoji) error
	// RemoveReaction 移除指定消息上的表情回应。
	RemoveReaction(ctx stdctx.Context, chatID, messageID string, emoji Emoji) error
}

type RecoverableAdapter interface {
	Adapter
	// OnDisconnect 注册断连回调，返回注销函数。
	//
	// fn 在适配器每次意外断连时被调用，err 为断连原因。
	// 多次调用将追加（而非覆盖）回调，互不影响。
	// 调用返回的 unregister 函数可注销该特定回调；传入 nil 时为空操作。
	OnDisconnect(fn func(err error)) (unregister func())
}

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

type ReplyEvent interface {
	// ReplyToID 返回被回复消息的平台原生 ID。
	// 若此消息不是回复，或平台不提供此信息，返回空字符串。
	ReplyToID() string
}

type Segment struct {
	// Type 段类型
	Type SegmentType
	// Text text 段内容 / at 段的显示文本（平台提供时）
	Text string
	// UserID at 段的目标用户 ID
	UserID string
	// ReplyToID reply 段的目标消息 ID
	ReplyToID string
	// Attachment image/audio/video/file 段载荷（复用统一附件类型）
	Attachment Attachment
	// FaceID face 段的表情 ID
	FaceID string
	// Extra 平台特有段数据（forward id、button 结构、ARK payload 等），
	// 通用键见 SegmentExtraKey 常量。
	Extra map[string]any
}

type SegmentType string

type SendError struct {
	// Code 标准错误码
	Code SendErrorCode
	// Platform 来源平台（如 "qq"、"discord"）
	Platform string
	// ChatID 目标会话 ID（便于日志定位）
	ChatID string
	// Message 人可读的错误描述（可含平台原始错误信息）
	Message string
	// RetryAfter 建议重试等待时间（仅 SendErrRateLimit 有意义，0 表示未知）
	RetryAfter int // 秒
	// Cause 底层原始错误（平台 SDK 返回的 error）
	Cause error
}

type SendErrorCode int

type SendRequest struct {
	// Target 目标会话信息（ID、IsGroup、Tokens 等路由与回复字段）。
	// Target.ID 为空时，Sender 实现应返回 errutil.ErrNoChatInfo。
	Target ChatInfo

	// Message 要发送的消息内容。
	Message OutboundMessage
}

type SendResult struct {
	// MessageID 平台返回的已发送消息唯一 ID。
	// 用于后续撤回/编辑等操作。富媒体上传且 srv_send_msg=false 时为空字符串。
	MessageID string

	// Timestamp 平台确认的消息发送时间（零值表示平台未返回）。
	Timestamp time.Time

	// Platform 来源平台标识符（如 "qq"、"discord"、"telegram"）。
	Platform string

	// Raw 平台专属响应的完整原始数据，由各平台适配器负责填充。
	// 调用方通过类型断言获取平台特定字段；不需要平台特定字段时可忽略。
	Raw any
}

type Sender interface {
	// Send 发送消息，返回平台响应摘要与错误。
	//
	// 成功时 SendResult.MessageID 包含平台分配的消息 ID（可用于撤回/编辑）；
	// 平台未返回 ID 时 MessageID 为空字符串（不影响发送本身的成功状态）。
	// 路由信息由 req 显式传入，ctx 仅用于取消/超时/tracing。
	//
	// 若 req.Target.ID 为空，实现者应返回 errutil.ErrNoChatInfo。
	Send(ctx stdctx.Context, req SendRequest) (SendResult, error)
}

type SessionNotifier interface {
	// NotifyUser 向指定用户（私聊会话）主动推送一条消息。
	// userID 为平台用户唯一 ID（如 QQ 号字符串）。
	// 平台不支持主动私信时返回 [ErrNotSupported]。
	NotifyUser(ctx stdctx.Context, userID string, msg OutboundMessage) error

	// NotifyGroup 向指定群组主动推送一条消息。
	// groupID 为平台群组唯一 ID。
	// 机器人不在该群时应返回错误。
	NotifyGroup(ctx stdctx.Context, groupID string, msg OutboundMessage) error
}

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

type SyntheticOption func(*SyntheticEvent)

type TypingNotifier interface {
	// SendTyping 向指定会话发送"正在输入"状态指示。
	SendTyping(ctx stdctx.Context, chatID string) error
}

type UserInfo struct {
	// ID 平台内唯一用户标识（QQ openID、Telegram userID 等）
	ID string
	// DisplayName 用户显示名（昵称/用户名）
	DisplayName string
	// GroupRole 发送者在当前群/频道中的角色等级。
	// 私聊场景或平台未提供时为 GroupRoleUnknown。
	GroupRole GroupRole
	// IsBot 是否为机器人账号
	IsBot bool
	// IsSelf 此用户信息是否指向机器人自身（如 @ 列表中的机器人自身）。
	// 主要用于 MentionsEvent，方便插件快速判断机器人是否被 @。
	IsSelf bool
}

type VoiceTranscript interface {
	// Transcript 返回语音转写文本；为空表示无转写结果。
	Transcript() string
}