数据模型
SDK 使用两种方式表示数据：
- TypedDict / 普通数据类（
botpy.types）— API 请求/响应的数据结构，提供类型提示的字典，通过键访问数据 - 领域模型（
botpy.message.*、botpy.guild.*等）— 事件回调中使用的 Python 对象，通过__slots__封装数据并绑定_api实例，可调用 API 方法
表格约定
- 每个类型单独成节，标题为该类型的名称；对同名（TypedDict 与领域模型）或需补充说明的类型，标题会附加中文注释，如
Message (类型)、Message (领域模型)。 - 每个类型使用三列表格列出全部变量：
变量名称 | 变量类型 | 语义说明。 - 变量类型为 SDK 内部类型时，类型名会链接到对应文档小节。
- 部分
Literal字面量别名（如AuditType、AudioStatus）没有命名变量，使用取值 | 语义说明两列表格说明其合法取值。 - 已声明但无法从源码确定或未初始化的变量，语义标注为 待确认。
类型索引
消息类型（message.md）
| 类型 | 说明 |
|---|---|
| MessagePayload | 基础消息数据结构 |
| DirectMessagePayload | 私信消息数据结构 |
| MessageAuditPayload | 消息审核事件载荷 |
| UserPayload | 用户基础信息（网关） |
| MessageRefPayload | 消息引用信息 |
| MessageAttachPayload | 消息附件信息 |
| Attachment / Thumbnail | 附件 / 缩略图 |
| EmbedField / Embed | Embed 消息 |
| ArkObjKv / ArkObj / ArkKv / Ark | Ark 模板消息 |
| Reference | 消息引用配置 |
| MessageMarkdownParams / MarkdownPayload | Markdown 消息 |
| KeyboardPayload | 内联键盘消息 |
| Media | 富媒体消息 |
| Message | 完整消息类型（继承 MessagePayload） |
| TypesEnum / MessagesPager | 消息分页 |
| DmsPayload | 私信会话响应 |
| DMOriginalAuthor / DeletedMessage / DeletionOperator / DeletedMessageInfo | 消息删除相关 |
领域模型： Message（含内嵌 _User/_Member/_MessageRef/_Attachments）、DirectMessage、MessageAudit、BaseMessage、GroupMessage、C2CMessage
频道类型（guild.md）
| 类型 | 说明 |
|---|---|
| GuildPayload | 频道数据结构 |
| Role | 身份组 |
| GuildRole / GuildRoles | 身份组详情 / 列表 |
| GuildMembers | 频道成员列表 |
领域模型： Guild
子频道类型（channel.md）
| 类型 | 说明 |
|---|---|
| ChannelType / ChannelSubType / PrivateType / SpeakPermission | 子频道相关枚举 |
| ChannelPayload | 子频道数据结构 |
| ChannelPermissions | 子频道权限 |
领域模型： Channel
用户与成员类型（user.md）
| 类型 | 说明 |
|---|---|
| User | 用户信息 |
| Member | 成员信息 |
| GuildMemberPayload | 频道成员信息 |
领域模型： Member（含内嵌 _User）
内联键盘类型（inline.md）
| 类型 | 说明 |
|---|---|
| Keyboard / KeyboardRow | 键盘结构 |
| Button / RenderData / Action / Permission | 按钮及行为 |
论坛类型（forum.md）
| 类型 | 说明 |
|---|---|
| Format | 帖子内容格式 |
| ThreadInfo / Thread | 帖子 |
| PostInfo / Post | 评论 |
| ReplyInfo / Reply | 回复 |
| AuditResult | 发布审核结果 |
| ForumRsp / PostThreadRsp | 响应结构 |
| OpenForumEvent | 开放论坛事件数据 |
领域模型： Thread（含内嵌富文本结构）、OpenThread
富文本类型（rich-text.md）
| 类型 | 说明 |
|---|---|
| AuditType / RichType / AtType / ElemType / Alignment | 字面量别名 |
| RichText / Paragraph / ParagraphProps | 富文本整体结构 |
| Elem / TextElem / TextProps / ImageElem / PlatImage / VideoElem / PlatVideo / URLElem | 元素类型 |
| RichObject / TextInfo / AtInfo / AtUserInfo / AtRoleInfo / AtGuildInfo / URLInfo / EmojiInfo / ChannelInfo | 富文本对象 |
其他类型（other.md）
| 类型 | 说明 |
|---|---|
| WsContext / ReadyEvent / WsUrlPayload | 网关基础类型 |
| RecommendChannel / AnnouncesType / Announce | 公告 |
| AudioStatus / PublicAudioType / AudioControl / AudioAction / AudioLive | 音频控制 |
| EmojiType / Emoji | 表情 |
| APIPermission / APIPermissionDemandIdentify / APIPermissionDemand | API 权限 |
| PinsMessage | 精华消息 |
| ReactionTargetType / ReactionTarget / Reaction / ReactionUsers | 表情表态 |
| RemindType / Schedule | 日程 |
| Robot | 机器人信息 |
| ShardConfig / Session | WebSocket 会话 |
| InteractionData / InteractionPayload / InteractionType / InteractionDataType | 交互 |
领域模型： Robot、Token、Audio、PublicAudio、Reaction（含内嵌 _Emoji/_Target）、Interaction（含内嵌 _Data/_Resolved）、GroupManageEvent、C2CManageEvent
数据流
QQ API 响应 (JSON)
→ BotAPI 方法返回 TypedDict (字典，用于 API 调用方)
→ 或 ConnectionState.parse_* 创建领域模型 (用于事件回调方)类型映射表
| QQ API 数据 | TypedDict 类型 | 领域模型 |
|---|---|---|
| guild | GuildPayload | Guild |
| channel | ChannelPayload | Channel |
| message | MessagePayload / Message | Message |
| member | Member / GuildMemberPayload | Member |
| user | User / UserPayload | Message._User（内嵌） |
| audio | AudioAction / AudioLive | Audio / PublicAudio |
| reaction | Reaction | Reaction |
| forum | Thread | Thread |
| interaction | InteractionPayload | Interaction |