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.ts | elementType / 各 subType 的枚举 |
packages/codec/src/element/registry.ts | wire → 语义 Element 的分发 |
packages/codec/src/element/spec.ts | 每种 element 的 zod schema(哪些字段必有、哪些可选) |
一、外壳:列 = 重复的 element
40800 这个 BLOB 本身是一个 protobuf 消息,里面只有一个字段:tag 同样为 40800 的重复子消息。 每一个 tag-40800 条目就是一个消息段。
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..45099 | element 通用字段(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..47904 | ARK 卡片 |
48101 | 回复引用(补充) |
48151..48157 | 通话记录(CALL) |
48172..48193 | QQ 动态分享卡(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..48722 | Markdown |
49154/49155 | 漫游 / 消息同步标记 |
52132..52152 | 弹射表情(EMOJI_BOUNCE)、位置共享(SHARE_LOCATION) |
80810..80995 | 商城表情(MFACE),完全独立的一段 |
观测归纳,不是约定
这个规律大多数区段吻合,但也有例外:45004(localPath,本机缓存路径)落在通用段 45001..45099 却被 PIC / FACE 共用;REPLY 用了 40020/40021 这两个信封级 tag。
四、每个 element 都有的通用字段
| tag | 字段名 | 类型 | 含义 | 置信度 |
|---|---|---|---|---|
| 40010 | isSender | bool | 本机是否发出者。注意语义很窄:只有「这台设备按下发送」才为 true;别人发来的、以及本账号其它端发的都不带此字段 | 已验证 |
| 45001 | elementId | uint64 | 消息段序号 | 已验证 |
| 45002 | elementType | uint32 | 类型判别式,取值见下表 | 已验证 |
| 45003 | subType | uint32 | 子类型,语义取决于 elementType(同一个数字在不同类型下含义完全不同) | 已验证 |
另有两个「读出来只为完整性」的信封级 tag,不属于任何 element:
| tag | 字段名 | 类型 | 含义 |
|---|---|---|---|
| 49154 | roaming | bytes | 漫游标记 |
| 49155 | msgSyncFlag | uint64 | 消息同步时间戳 |
elementType 全表
值来自 QQ NT 自身的 NTMsgElementType 枚举。标注「未观测」的表示本地样本库中从未出现, 声明出来只是为了将来遇到时有名字可对,而不是一个裸数字。
| 值 | 名称 | 说明 | 文档 |
|---|---|---|---|
| 0 | UNKNOWN | 占位(未观测) | — |
| 1 | TEXT | 文本 / @ | text |
| 2 | PIC | 图片 | pic |
| 3 | FILE | 文件 | file |
| 4 | PTT | 语音 | ptt |
| 5 | VIDEO | 视频 | video |
| 6 | FACE | 系统表情 | face |
| 7 | REPLY | 回复引用 | reply |
| 8 | GRAY_TIP | 小灰条(撤回 / 拍一拍 / 入群…),语义由 subType 决定 | gray-tip |
| 9 | WALLET | 红包 / 转账 | wallet |
| 10 | ARK | ARK 卡片 | ark |
| 11 | MFACE | 商城表情 | mface |
| 12 | LIVE_GIFT | 直播礼物(未观测) | — |
| 13 | STRUCT_LONG_MSG | 结构化长消息(未观测) | — |
| 14 | MARKDOWN | Markdown | markdown |
| 15 | GIPHY | Giphy 动图(未观测) | — |
| 16 | MULTI_MSG | 合并转发(QQ 内部名 MULTIFORWARD) | multi-msg |
| 17 | INLINE_KEYBOARD | 内联键盘 / 机器人按钮(未观测) | — |
| 18 | IN_TEXT_GIFT | 文字内嵌礼物(未观测) | — |
| 19 | CALENDAR | 日程(未观测) | — |
| 20 | YOLO_GAME_RESULT | YOLO 小游戏结果(未观测) | — |
| 21 | CALL | 音视频通话记录(QQ 内部名 AVRECORD) | call |
| 22 | FEED | 动态 Feed(未观测) | — |
| 23 | ONLINE_FILE | 在线文件(QQ 内部名 TOFURECORD) | online-file |
| 24 | ACE_BUBBLE | 气泡(未观测) | — |
| 25 | ACTIVITY | 活动卡片(未观测) | — |
| 26 | QQ_DYNAMIC | QQ 动态分享卡(QQ 内部名 TOFU) | qq-dynamic |
| 27 | EMOJI_BOUNCE | 表情弹射(QQ 内部名 FACEBUBBLE) | emoji-bounce |
| 28 | SHARE_LOCATION | 位置共享 | 见下方 |
| 29 | TASK_TOP_MSG | 任务置顶消息(未观测) | — |
| 30 | ONLINE_FOLDER | 在线文件夹 | online-folder |
| 43 | RECOMMENDED_MSG | 推荐消息(未观测) | — |
| 44 | ACTION_BAR | 操作栏(未观测) | — |
elementType=28(位置共享) 字段极少,不单独成篇:
| tag | 字段名 | 类型 | 必有 | 含义 |
|---|---|---|---|---|
| 52152 | shareLocationText | string | ✅ | 展示文案,如「发起了位置共享」 |
五、跨类型共用的「文件族」字段
图片 / 文件 / 视频 / 语音 / 在线文件在 QQ 眼里都是「一个待传输的文件」, 因此共用同一批 tag。理解这一批,五种类型就都懂了一半。
基本元数据
| tag | 字段名 | 类型 | 含义 | 用于 |
|---|---|---|---|---|
| 45402 | fileName | string | 文件名 | PIC / FILE / VIDEO / PTT / ONLINE_FILE |
| 45403 | filePath | string | 本地文件路径 | PTT / FILE / ONLINE_FILE |
| 45405 | fileSize | uint32 | 字节数 | 全部 |
| 45406 | md5Bytes | bytes | 二进制 MD5 | 全部 |
| 45407 | md5Bytes2 | bytes | 第二份 MD5,作用与 45406 相同 | FILE |
| 45408 | contentHash | bytes | 内容校验 hash | 全部 |
| 45424 | md5 | string | 大写十六进制 MD5 字符串 | PIC / PTT |
| 45411 / 45412 | imgWidth / imgHeight | uint32 | 宽 / 高(像素) | PIC / FILE / VIDEO / ONLINE_FILE |
| 45418 | isOriginal | bool | 是否原图 / 原画质 | PIC / VIDEO / PTT |
传输与下载
| tag | 字段名 | 类型 | 含义 |
|---|---|---|---|
| 45503 | fileToken | string | 下载凭据 |
| 45505 | uploadTime | uint32 | 上传 / 处理时间戳 |
| 45510 | videoToken | string | 下载 token(VIDEO / FILE) |
| 45511 | picTransferState | uint32 | 传输状态 |
| 45513 | transferVersion | uint32 | 传输版本 |
| 45517 | uploadTimestamp | uint32 | 上传时间戳 |
| 45518 | fileTTL | uint32 | 有效期(秒) |
| 45550 | transferState | uint32 | 传输状态(PTT / FILE) |
| 45554 | transferErrorText | string | 传输失败文案,如「传输失败,请稍后重试」 |
URL / 本地缓存路径
QQ 对同一张图存了三档尺寸,每档都有一个远端 URL 和一个本地缓存路径,两两对应:
| 档位 | 远端 URL | 本地缓存路径 | 本地文件名后缀 |
|---|---|---|---|
| 缩略图 | 45802 thumbnailUrl | 45812 thumbnailLocalPath | …_0.jpg |
| 预览图 | 45803 previewUrl | 45813 previewLocalPath | …_198.jpg |
| 大图 | 45804 originalUrl | 45814 originalLocalPath | …_720.jpg |
| tag | 字段名 | 类型 | 含义 |
|---|---|---|---|
| 45806 | cdnServerIp | uint32 | CDN 服务器地址,大端打包的 IPv4(如 3082863821 → 183.192.196.205)。为 0 时表示应由客户端自行解析 cdnHost |
| 45807 | cdnServerPort | uint32 | CDN 端口。观测到 80 / 443 / 8080 / 14000 / 57897 / 0 |
| 45815 | summary | string(repeated) | 摘要 / 描述文案 |
| 45816 | cdnHost | string | CDN 域名 |
近似常量的传输标记
| tag | 字段名 | 说明 |
|---|---|---|
| 45507 | transferFlag45507 | 只有按有符号 int64 解释才有意义:几乎恒为 18446744073704048574(即 -5503042)。声明成 INT64 是为了让 varint 能原样回写,而不被截断成 32 位 |
| 45509 | transferFlag45509 | 只要 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):
- 纯 wire 级遍历 buffer(始终按真实 wire type 走,因此不可能读错);
- 逐字段比对「实际 wire type」与「schema 声明类型」,冲突就丢弃该字段;
- 声明为
string但字节不是合法 UTF-8 的也丢弃 —— protobuf-ts 用的是 fatal 的TextDecoder, 否则同样会炸掉整条消息; - 嵌套消息递归处理;未知 tag 原样保留(protobuf-ts 会安全跳过);
- 尾部损坏 / 截断时,保留已累积的合法前缀。
结果是:猜错类型的字段只会「消失」,而不会让整条消息渲染失败。
注意范围:只丢弃真正的 wire type 冲突。varint 数值超出声明范围的不动它 —— protobuf-ts 会无害地截断,丢掉反而会损失调用方可能需要的数据。
七、语义化:从 wire 到 Element
registry.ts 里的 decodeElement 把扁平 wire 结构映射成带 kind 的语义对象。由于 element 接口的字段名与 wire schema 的字段名完全一致,这层薄到只剩分发:
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的表示语义未知,仅为往返保真而解析
