消息事件

消息位于事件帧的 data 中，按 post_type 区分群聊、好友和群临时会话。

公共字段

字段	类型	说明
self_id	integer	所属 QQ
protocol_id	integer	协议配置 ID
post_type	string	group_message、friend_message 或 group_temp_message
message_id	integer	本地消息编号；成功缓存后提供，用于要求该编号的接口
msg	object	原始消息标识
sender	object	发送者信息
message	array	结构化消息段；无可用消息段时可能省略
alt_message	string	可读消息摘要，可能省略
source	string	关联的发送插件名称标记，可能省略；不是消息渠道枚举或发送成功凭据

群消息

含 red_packet 消息段的事件：Free 不推送；Plus 按当前 QQ 最新等级核对，至少需要 32 级；Pro 不设这项等级门槛。含红包的混合消息、引用及撤回原消息整体遵守此条件；普通文字提到“红包”不受影响。权限不足或校验失败不会推送红包内容和领取材料。此规则同样适用于好友、群临时及发送确认事件。

post_type: "group_message"，需要 group_message 权限。group_id 为群号，group_name 可能省略；sender 描述发送者。解析消息内容应使用 message 消息段，不能仅按 alt_message 还原图片、引用等内容。

好友消息

post_type: "friend_message"，需要 friend_message 权限。sender 和 receiver 分别描述发送方与接收方；结合 self_id 判断当前账号，不能总把 sender 当作好友。

群临时消息

post_type: "group_temp_message"，同样需要 friend_message 权限。group_known 表示是否已确认来源群。群来源未确认时不要补造 group_id，也不要依赖本地 message_id 调用引用、撤回等接口；此类消息不会分配本地消息编号。

会话字段

类别	字段	说明
群消息	group_id、group_name	群号与名称；名称可能省略
好友消息	receiver	接收者信息
群临时消息	receiver、group_known、group_id	group_known 表示是否已确认群来源；未知时 group_id 可能省略

消息与发送者

msg.uid 是字符串，msg.seq、msg.random 与 msg.time 是数字。发送者包含 user_id、nickname，按推送内容可能包含 remark、card、role、title、level。不要将 uid 转为 JavaScript Number。

message 中每个元素使用 { "type": "text", "data": { "text": "你好" } } 形式，类型见消息段。

引用与撤回

回复当前消息使用事件顶层数字 message_id。引用段内的 source_msg_uid 和旧兼容字段 message_id 是 QQ MsgUID 字符串，不能直接作为发送接口的引用编号；引用更早的原文应使用非 null 的 reply_reference_id。完整规则见引用回复。

消息编号只能用于对应账号、协议与会话。下载地址中的临时 rkey 不属于永久消息标识。接口调用结果与事件推送可能先后到达，不能假定固定顺序，也不能用消息事件代替发送接口结果。

发送确认

post_type: "message_sent" 表示框架发送请求的成功响应与当前账号的原生消息推送精确匹配。只有接口成功、没有匹配推送时不会产生此事件；未匹配的本账号同步消息仍按原群消息、好友消息或群临时消息处理。

字段	类型	说明
self_id、protocol_id	integer	所属账号与协议，协议 ID 0 有效
post_type	string	固定为 message_sent
message_type	string	group、friend 或 group_temp
source	string	固定为 framework_native_confirmed，不表示具体插件名称
msg	object	uid 为字符串，seq、random、time 为数字
sender	object	原生推送的发送者
receiver	object	好友或群临时会话的接收者
group_id	integer	群聊或群临时会话的群号
group_known	boolean	已确认来源的群临时会话为 true
message_id	integer	本地消息编号，可能省略
group_name、alt_message	string	可选群名与消息摘要
message	array	可选消息段

group 使用 group_message 权限；friend 和 group_temp 使用 friend_message 权限，仅向当前框架中获授权的订阅者推送。原生推送先到时最多暂存 30 秒等待响应；失败、未匹配或超过等待时间的消息按原接收事件处理。此机制不保证所有发送接口和所有原生同步路径都产生发送确认，插件仍须处理接口结果及连接中断，不能因为缺少事件自动重复发送。