Skip to content

40800 — 消息正文(MsgBody) ​

40800 是 c2c_msg_table / group_msg_table / dataline_msg_table 中存贮消息正文的列, 内容是 protobuf,结构为可重复的消息段(element)序列 —— 类似富文本:一条消息可包含多个消息段, 按内容顺序排列,部分类型可嵌套。

对应 WeQ 解析实现:

文件职责
packages/codec/src/proto/msg/40800.ts列本身的外壳(MsgBody)
packages/codec/src/proto/msg/element.ts单个消息段的物理 wire 结构(ElementWire),全部 tag 的唯一事实来源
packages/codec/src/element/types.tselementType / 各 subType 的枚举
packages/codec/src/element/registry.tswire → 语义 Element 的分发
packages/codec/src/element/spec.ts每种 element 的 zod schema(哪些字段必有、哪些可选)

一、外壳:列 = 重复的 element ​

40800 这个 BLOB 本身是一个 protobuf 消息,里面只有一个字段:tag 同样为 40800 的重复子消息。 每一个 tag-40800 条目就是一个消息段。

text
40800 (BLOB)
└── 40800  repeated ElementWire   ← 每项 = 一个消息段
    ├── [0] elementType=1  文本
    ├── [1] elementType=6  表情
    └── [2] elementType=1  文本

C2C 与群聊的 40800 结构完全一致,两者的差异(发送者 uid、会话对端 uid…)在行级列上,不在这一列里。

二、扁平信封:elementType 是判别式,不是 oneof ​

这是理解 40800 最关键的一点:

QQ 并没有把各类型的字段包在各自的子消息里,而是把所有类型的字段平铺在同一层, 用 45002 (elementType) 这个判别式告诉你该看哪一批 tag。

也就是说 ElementWire 是一个「大而全」的扁平结构:文本的 45101、图片的 45402、 表情的 47601、商城表情的 80900 全都是同一层的兄弟字段。一个具体的 element 只会填写 其中属于自己类型的那几个,其余留空。

带来的直接后果:

  • 解析简单:一次 decode 就能拿到所有字段,不需要按类型切换 schema。
  • 字段号必须全局唯一:不同类型不能复用同一个 tag 表达不同含义,否则会打架。 这也是 QQ 把 tag 编到 4~5 位数的原因。
  • 共用字段天然复用:图片 / 文件 / 视频 / 语音都是「一个文件」,于是共享同一批 454xx/455xx 文件族 tag(见下文第五节)。

三、tag 分段约定 ​

element.ts 顶部记录的分段规律,按 tag 区间划分归属:

tag 区间归属
40010..40021信封级元数据(发送方标记、原消息 uid…),与消息行的同名列同义
45001..45099element 通用字段(id / type / subType)
45101..45199文本(TEXT)
45201..45299表情(FACE,历史区段)
45401..45599文件族:图片 / 文件 / 视频 / 语音 / 在线文件共用的文件元数据
45801..45899文件族的 URL / 本地缓存路径 / CDN 信息
45901..45999语音(PTT)专属 + 文件缩略图路径
47401..47425回复引用(REPLY)
47501..47502灰条 · 临时会话(GRAY_TIP subType=15)
47601..47622表情(FACE)
47702..47716灰条 · 撤回(GRAY_TIP subType=1)
47901..47904ARK 卡片
48101回复引用(补充)
48151..48157通话记录(CALL)
48172..48193QQ 动态分享卡(QQ_DYNAMIC)
48210..48275灰条 · JSON / XML(GRAY_TIP subType=17 / 12)
48401..48461红包 / 转账(WALLET)
48501..48542灰条 · 群通知(GRAY_TIP subType=4)
48601..48603合并转发(MULTI_MSG)
48701..48722Markdown
49154/49155漫游 / 消息同步标记
52132..52152弹射表情(EMOJI_BOUNCE)、位置共享(SHARE_LOCATION)
80810..80995商城表情(MFACE),完全独立的一段

观测归纳,不是约定

这个规律大多数区段吻合,但也有例外:45004(localPath,本机缓存路径)落在通用段 45001..45099 却被 PIC / FACE 共用;REPLY 用了 40020/40021 这两个信封级 tag。

四、每个 element 都有的通用字段 ​

tag字段名类型含义置信度
40010isSenderbool本机是否发出者。注意语义很窄:只有「这台设备按下发送」才为 true;别人发来的、以及本账号其它端发的都不带此字段已验证
45001elementIduint64消息段序号已验证
45002elementTypeuint32类型判别式,取值见下表已验证
45003subTypeuint32子类型,语义取决于 elementType(同一个数字在不同类型下含义完全不同)已验证

另有两个「读出来只为完整性」的信封级 tag,不属于任何 element:

tag字段名类型含义
49154roamingbytes漫游标记
49155msgSyncFlaguint64消息同步时间戳

elementType 全表 ​

值来自 QQ NT 自身的 NTMsgElementType 枚举。标注「未观测」的表示本地样本库中从未出现, 声明出来只是为了将来遇到时有名字可对,而不是一个裸数字。

值名称说明文档
0UNKNOWN占位(未观测)—
1TEXT文本 / @text
2PIC图片pic
3FILE文件file
4PTT语音ptt
5VIDEO视频video
6FACE系统表情face
7REPLY回复引用reply
8GRAY_TIP小灰条(撤回 / 拍一拍 / 入群…),语义由 subType 决定gray-tip
9WALLET红包 / 转账wallet
10ARKARK 卡片ark
11MFACE商城表情mface
12LIVE_GIFT直播礼物(未观测)—
13STRUCT_LONG_MSG结构化长消息(未观测)—
14MARKDOWNMarkdownmarkdown
15GIPHYGiphy 动图(未观测)—
16MULTI_MSG合并转发(QQ 内部名 MULTIFORWARD)multi-msg
17INLINE_KEYBOARD内联键盘 / 机器人按钮(未观测)—
18IN_TEXT_GIFT文字内嵌礼物(未观测)—
19CALENDAR日程(未观测)—
20YOLO_GAME_RESULTYOLO 小游戏结果(未观测)—
21CALL音视频通话记录(QQ 内部名 AVRECORD)call
22FEED动态 Feed(未观测)—
23ONLINE_FILE在线文件(QQ 内部名 TOFURECORD)online-file
24ACE_BUBBLE气泡(未观测)—
25ACTIVITY活动卡片(未观测)—
26QQ_DYNAMICQQ 动态分享卡(QQ 内部名 TOFU)qq-dynamic
27EMOJI_BOUNCE表情弹射(QQ 内部名 FACEBUBBLE)emoji-bounce
28SHARE_LOCATION位置共享见下方
29TASK_TOP_MSG任务置顶消息(未观测)—
30ONLINE_FOLDER在线文件夹online-folder
43RECOMMENDED_MSG推荐消息(未观测)—
44ACTION_BAR操作栏(未观测)—

elementType=28(位置共享) 字段极少,不单独成篇:

tag字段名类型必有含义
52152shareLocationTextstring✅展示文案,如「发起了位置共享」

五、跨类型共用的「文件族」字段 ​

图片 / 文件 / 视频 / 语音 / 在线文件在 QQ 眼里都是「一个待传输的文件」, 因此共用同一批 tag。理解这一批,五种类型就都懂了一半。

基本元数据 ​

tag字段名类型含义用于
45402fileNamestring文件名PIC / FILE / VIDEO / PTT / ONLINE_FILE
45403filePathstring本地文件路径PTT / FILE / ONLINE_FILE
45405fileSizeuint32字节数全部
45406md5Bytesbytes二进制 MD5全部
45407md5Bytes2bytes第二份 MD5,作用与 45406 相同FILE
45408contentHashbytes内容校验 hash全部
45424md5string大写十六进制 MD5 字符串PIC / PTT
45411 / 45412imgWidth / imgHeightuint32宽 / 高(像素)PIC / FILE / VIDEO / ONLINE_FILE
45418isOriginalbool是否原图 / 原画质PIC / VIDEO / PTT

传输与下载 ​

tag字段名类型含义
45503fileTokenstring下载凭据
45505uploadTimeuint32上传 / 处理时间戳
45510videoTokenstring下载 token(VIDEO / FILE)
45511picTransferStateuint32传输状态
45513transferVersionuint32传输版本
45517uploadTimestampuint32上传时间戳
45518fileTTLuint32有效期(秒)
45550transferStateuint32传输状态(PTT / FILE)
45554transferErrorTextstring传输失败文案,如「传输失败,请稍后重试」

URL / 本地缓存路径 ​

QQ 对同一张图存了三档尺寸,每档都有一个远端 URL 和一个本地缓存路径,两两对应:

档位远端 URL本地缓存路径本地文件名后缀
缩略图45802 thumbnailUrl45812 thumbnailLocalPath…_0.jpg
预览图45803 previewUrl45813 previewLocalPath…_198.jpg
大图45804 originalUrl45814 originalLocalPath…_720.jpg
tag字段名类型含义
45806cdnServerIpuint32CDN 服务器地址,大端打包的 IPv4(如 3082863821 → 183.192.196.205)。为 0 时表示应由客户端自行解析 cdnHost
45807cdnServerPortuint32CDN 端口。观测到 80 / 443 / 8080 / 14000 / 57897 / 0
45815summarystring(repeated)摘要 / 描述文案
45816cdnHoststringCDN 域名

近似常量的传输标记 ​

tag字段名说明
45507transferFlag45507只有按有符号 int64 解释才有意义:几乎恒为 18446744073704048574(即 -5503042)。声明成 INT64 是为了让 varint 能原样回写,而不被截断成 32 位
45509transferFlag45509只要 45507 存在就恒为 1

45507 / 45509 总是成对出现,PIC、FILE、VIDEO 上都能看到。

六、容错解码:sanitizeBytes ​

40800 里有大量 tag 的类型是逆向猜出来的,猜错会有真实代价:

protobuf-ts 解码一个「已知」字段时,只按 schema 里声明的类型读,不校验实际 wire type。 所以若某个 tag 被声明成了 uint32(varint),实际却是长度分隔的 blob, 解码器就会读错字节数、游标错位,进而整条消息 decode 抛异常 —— 丢的不是一个字段,是整条消息。

WeQ 的解法是在 decode 前加一道 sanitizeBytes(packages/codec/src/raw/sanitize.ts):

  1. 纯 wire 级遍历 buffer(始终按真实 wire type 走,因此不可能读错);
  2. 逐字段比对「实际 wire type」与「schema 声明类型」,冲突就丢弃该字段;
  3. 声明为 string 但字节不是合法 UTF-8 的也丢弃 —— protobuf-ts 用的是 fatal 的 TextDecoder, 否则同样会炸掉整条消息;
  4. 嵌套消息递归处理;未知 tag 原样保留(protobuf-ts 会安全跳过);
  5. 尾部损坏 / 截断时,保留已累积的合法前缀。

结果是:猜错类型的字段只会「消失」,而不会让整条消息渲染失败。

注意范围:只丢弃真正的 wire type 冲突。varint 数值超出声明范围的不动它 —— protobuf-ts 会无害地截断,丢掉反而会损失调用方可能需要的数据。

七、语义化:从 wire 到 Element ​

registry.ts 里的 decodeElement 把扁平 wire 结构映射成带 kind 的语义对象。由于 element 接口的字段名与 wire schema 的字段名完全一致,这层薄到只剩分发:

text
decode: 按 elementType 查出 kind → 展开 wire 全部字段 + 补一个 kind
encode: 去掉 kind → 展开字段 + 由 kind 反推回 elementType

两处例外值得注意:

  • text 与 at 共用 elementType=1。区分方式是看 45105 (bubbleId) 有没有值: 有值即为 @,其中 bubbleId 装的是被 @ 者的 uid、45103 (textEncodingFlag) 装 uin。 (字段名是历史遗留,与聊天「气泡」无关。)
  • GRAY_TIP 一个 elementType 对应 6 种 kind,靠 subType 再分一次(见 gray-tip)。

无法识别的 elementType 会被包成 UnknownElement,原始 wire 完整保留在 raw 里, 保证「读出来再写回去」字节不丢。


字段表约定 ​

各消息段文档的字段表统一使用以下列:

  • tag — protobuf 字段号
  • 字段名 — element.ts 中的名字(同时也是 Element 对象上的属性名)
  • 类型 — wire 类型
  • 必有 — 该类型的 element 是否必带此字段(依据 spec.ts 的 zod schema)
  • 含义 — 名字里带 flagNNNNN 的表示语义未知,仅为往返保真而解析

← 返回消息体解析

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准