发消息(MessageSvc.PbSendMsg + 富媒体上传 + 文件)
实现:
packages/protocol/src/msg/send*.ts(协议层)、packages/protocol/src/highway/*(媒体与文件上传)、packages/protocol/src/file/*(文件管线)、packages/service/src/account/message_send.ts(MessageSendService)、apps/desktop/src/main/mcp/tools.ts(MCP 工具send_text_message/send_media_message/send_file_message/send_rich_message)。相邻的轻互动(戳一戳 / 贴表情)不走这条管线,见
packages/protocol/src/oidb/send-poke.ts、set-reaction.ts、packages/service/src/account/interaction.ts与 MCP 的send_poke/set_message_reaction。
一、它是什么
发消息走原始 SSO 命令 MessageSvc.PbSendMsg(没有 OIDB 信封),以下场景共用同一条 命令,只差 routingHead / contentHead:
| 场景 | routingHead | contentHead | 备注 |
|---|---|---|---|
| 群聊 | grp.groupCode | { type: 1 } | 不带 c2cCmd / subType,也不带时间戳 |
| 私聊 | c2c.{uin, uid} | { type: 1, c2cCmd: 11 } | 带 ctrl.msgFlag(Request field 12,Unix 秒) |
| 群临时会话 | grpTmp.{groupUin, toUid} | { type: 1, subType: 0, c2cCmd: 0 }(两个 0 显式上 wire) | 带 syncCookie.msgFlag(Request field 6,Unix 秒) |
| 我的设备文本 | trans0x211.{toUin: 本人QQ号, ccCmd: 7, uid: 本人真实UID} | { type: 1, subType: 0 } | 文本在 messageBody.msgContent,带 ctrl.msgFlag,不走好友 c2c 路由 |
| 我的设备文件 | trans0x211.{ccCmd: 7, devices, uid: 本人真实UID} | { type: 1, subType: 0, c2cCmd: 0 }(零值显式编码) | FTN 通知在 msgContent,不带 ctrl;devices 分别描述目的和本机终端 |
群临时会话那两格是按真机抓包对齐的(2026-09-29,QQ NT 在群里发起临时会话):同一份请求里 grpTmp 的字段号是 3 / 4(不是网上常见的 1 / 2)、contentHead 把 subType=0 与 c2cCmd=0 都写出来、时间戳落在 field 6(内容是 08 <varint 秒> 这么一小段 { msgFlag })。 私聊那条仍是既有形状(c2cCmd=11 + ctrl@12):那是验证过能发出去的字节,且没有再抓过 私聊包,所以两边故意不一致。实现见 send-schemas.ts 的 SEND_CONTENT_HEAD_TEMP / SEND_SYNC_COOKIE / SEND_MESSAGE_REQUEST_TEMP,以及 send.ts 的 RoutingPlan.timestampField。
除设备会话外,消息体是 messageBody.richText.elems[] —— 一个 Elem 数组。
空白正文与仅引用
普通聊天正文按输入原样发送,不使用 trim() 裁剪或判空:空格、换行和其他空白字符 均是正文,首尾空白也保留。发送按钮、回车提交、草稿内存、恢复快照与写回采用同一语义, 只有空串表示没有文本;空编辑器的浏览器占位 br 不算用户换行。
仅引用、没有正文或其他消息元素时,在发送载荷补一个普通空格 U+0020,不改动输入框 或草稿。引用已有空白正文、表情或媒体时不额外补空格;完全没有内容和引用仍拒绝发送。 服务层的文本与元素发送入口沿用相同规则。
离线浏览器回归可运行 node apps/desktop/test/browser/run-composer-whitespace.mjs, 覆盖 Chromium/WebKit、桌面/窄屏、深浅主题、真实换行与删除、仅引用及展开输入。 Playwright 入口和截图目录分别沿用 WEQ_PLAYWRIGHT_IMPORT、WEQ_COMPOSER_ARTIFACTS。
我的设备文本
设备会话不使用好友资料或好友 UID 目录,联系人名称和头像按固定设备伪 UID 解析。 发送目标始终保留设备伪 UID;会话快照中的 targetUin 即使是本人 QQ 号,也不能拿它 替换设备目标。外层 trans0x211.uid 则使用 session.selfUid 中的本人真实 UID, 不是设备伪 UID;本人 UID 缺失时拒绝发送,不从好友目录猜测。联系人详情只展示设备及 消息入口,不补全本人的资料卡。
设备文本使用 trans0x211 命令 7,msgContent 内为数据线 subCmd=4:header 带本人 源/目的 QQ 号、源终端 PC(1)、目的终端 PC/手机/平板(1/2/3),移动端 appId 为 1001,PC appId 为 1;generic 带毫秒 sessionId、单片信息和 UTF-8 文本列表。 文本元素路径不混发媒体或文件,也不发送好友装扮。设备文件走下述独立上传路径;设备消息 不写入普通私聊的漫游缓存,本地消息由 dataline_msg_table 的现有同步链路接管。
协议字段与发送形状核对自 SnowLuma 固定版本的 发送实现、 数据线编码 和字段定义。 上述参考实现的设备伪 UID 路由已被真机反例推翻:2026-11-06,同一条手机文本仅替换 trans0x211.uid,设备伪 UID 返回 result=15,本人真实 UID 返回 result=0, 并经本地数据线同步及手机实际接收确认。离线回归覆盖正文黄金字节、本人真实 UID 路由、 三种目的终端、本人 UID 缺失和非文本拒绝;电脑/平板目的终端尚未做真实接收验收。
我的设备文件
sendDatalineFile 使用 OfflineFilleHandleSvr.pb_ftn_CMD_REQ_APPLY_UPLOAD_V3-1700, 业务号 38、客户端类型 104、源和目的均为本人 UIN;它不是普通私聊的 0xE37_1700 / NTV2 / Highway 95,也不发送私聊 FileExtra。
申请携带文件大小、名称、完整 SHA-1 和前 FILE_MD5_HEAD_LIMIT(0x98A000)字节 MD5。设备通知的原件摘要也使用这一分段 MD5;不能只拿小文件测完整 MD5,否则发现不了差异。 未命中时按响应的整包限额流式读取,POST /ftn_handler?bmd5=<当前文件块MD5>:
16B 头:magic=0xABCD9876 / command=1007 / reserved=0 / bodyLength
u16 ticketLength / ticket / u16 sha1Length / sha1
u32 fileSizeLow / offsetLow / chunkLength / fileSizeHigh / offsetHigh
文件块回执必须有合法头及成功状态;停止标记或确认偏移决定下一块,偏移不前进、HTTP 失败、 损坏或过大回执都中止且不发布通知,文件句柄由 finally 关闭。长上传期间继续核对当前 账号及数据源,不把已经上传到旧账号的文件通知发到新账号。
上传完成后发送 subCmd=1 的 FTN 文件通知,携带 /UUID 索引、文件名、大小和分段摘要。 文件消息保留设备伪 UID 作为会话身份,SSO 路由仍使用本人真实 UID;目的 instance 为 0, 本机 instance 为 1,单文件不复用原生 SDK 的历史传输组。
这条实现是云端文件分支,先完整上传再提交消息。QQ 原生 SDK 的 NFC/RFC 直连、反向连接 及上传未结束时就接收的会话过程尚未接入,不能把服务端接受通知等同于手机已经下载。
自动跟随当前聊天字体
「设置 → 基础功能 → 互动与防撤回」的 sendWithQqFont 默认开启,两个账号初始化路径均动态读取。 关闭时跳过字体查找并从常规发送的 dress 中去掉字体字段,气泡/挂件不受影响。 各端提交后先在本端建立消息预览,再执行目录、媒体读取及网络请求;Remote 不需要电脑响应就能回显。 装扮查询、图片解码和字体文件加载不阻塞任何消息正文,已缓存资源直接复用,缺失资源异步补齐。 实际发送由服务端读取当前账号字体原值,保留账号/数据源/PID 校验,不为本地预览增加准备接口往返。 Web/Remote 的发送圈在完整请求尚未收到电脑回执时含小电脑图标,回执到达后恢复普通发送圈; 此回执不代表 QQ 接收成功。传输、准备或发送失败均保留失败消息并显示失败横幅,不自动重发; 超时结果可能尚未确认,保留错误详情供核对。本地使用中的个性字体按作用范围优先覆盖 消息字体(含普通款与炫彩款),仅影响本地显示。消息气泡与消息字体分别开关,自己和对方的消息均遵循; 消息中的 widgetId 就是头像挂件,与本地挂件和自己账号的静态挂件统一由「聊天头像挂件」开关控制。 本地使用中的气泡、字体、头像挂件按各自作用范围优先覆盖消息装扮。 气泡在发送中和本地发送缓存阶段使用 homeDress.bubbleId,不把预览 ID 写入请求, 不声称该快照就是服务端最终结果;回读后整条记录(包括零值气泡)优先于本地发送缓存。 气泡、字体与挂件按种类独立查询和持有,不因另外一种装扮补齐而退回默认样式; 乐观消息、发送缓存与正式记录同轮交接时复用样式节点和已加载字体,不重启动画。 真实消息读回按原有对账链路替换整条记录,不保留请求字体覆盖读回字体。
2026-10-24 已确认显式携带当前字体原值的请求在接收端显示正确字形;不带字段和指定 其他款的服务器历史也会回填当前字体,但用户反馈普通发送仍显示默认字形。历史回读 不能代替实时收端验收,因此不能仅依赖服务端回填,也不能只补本地回显。
桌面两个账号初始化路径均注入 accountConfig.homeDress.fontId。MessageSendService 先从当前会话最近 50 条中找本人、且 41531 解出的 itemId 与当前字体一致的原值;没有时 再有界读取私聊/群聊各最近 50 条。不取其他人的同款、不把本人旧款当当前款,也不从 itemId 猜类型高位。找到后通过 dress.fontId2Raw 显式写入请求 tag 37.19.15, 同时补本地回显;不读取本地装扮预览选择,不改 QQ 账号设置,不增加联网查询。
同款原值短时缓存 30 秒,并发查询合并,当前字体 ID 变化时重新查找。找不到可靠原值时 按普通字体发送,并在成功结果 hint 中说明;快照缺失、无有效 ID 或读取失败不阻断发送。 字体查询后再核对账号/PID,切换后不发到旧会话。后续正式消息同步可覆盖本地回显。 当前真实字形验收仅覆盖已测试的普通字体,不能扩展为所有 DIY/魔法效果均已验证。
历史 dress 参数只保留为实验接口,不是任意字体选择器。官方 Android 定义的 GeneralFlags tag 19 是扩展 bytes,内部 tag 15 为 packed mobile_custom_font,tag 56 为铭牌;不能把“字节交换后的 itemId”当成完整字体值,也不能将 tag 56 当成另一个字体。
二、元素:收侧解码器的镜像
发送端没有另写一份 schema:msg/send-elements.ts 产出的就是收侧 msg/decode.ts 解出来的同一批结构,编码交给同一个 protobuf.encode。
decode: bytes --decode(ELEM)--> proto 树 --lift--> { kind, ... }
encode: { kind, ... } --build--> proto 树 --encode(ELEM)--> bytes好处:decodeMessage() 的 elements 可以直接再发出去(搬运、转发),不需要中间结构。 测试里有一条自解码往返就是钉这个性质。
已有的类型:
| kind | wire 形态 | 需要上传 |
|---|---|---|
text | elem.text.str | 否 |
at | elem.text + pbReserve(3=type/4=uin/9=uid) | 否 |
face | 老 elem.face / commonElem svc 33 / svc 37 | 否 |
mface | elem.marketFace(16 字节 GUID) | 否 |
reply | elem.replyElement(嵌套 origElementsRaw) | 否 |
ark | elem.lightApp.data(deflate + 0x01 头) | 否 |
xml | elem.richMsg.template1(同上) | 否 |
markdown | commonElem svc 45 + MarkdownData | 否 |
poke | commonElem svc 2 + PbElem | 否 |
forward | elem.lightApp(com.tencent.multimsg 卡片,只引用一个已有 resId) | 否 |
image | commonElem(48, 20).pbElem = msgInfo | 是 |
record | commonElem(48, 22).pbElem = msgInfo | 是 |
video | commonElem(48, 21).pbElem = msgInfo | 是 |
raw | 直接给 Elem proto 对象(逃生舱) | — |
forward 卡片本身只是「指向一段已存在的长消息」的引用;要让它指向的内容是自己新发的, 得先走下面第三节之二的上传(SsoSendLongMsg,返回 resId),再发这张卡。
三、媒体上传:0xE37_100 申请 + highway TCP 传字节
媒体元素不能直接拼出来 —— 得先把文件传到 QQ 的富媒体服务,拿回 msgInfo, 那份 msgInfo 字节就是 commonElem.pbElem(收侧 PIC_COMMON_PB / PTT_COMMON_PB / VIDEO_COMMON_PB 解的是同一个结构)。
┌─ 0xE37_100(OidbSvcTrpcTcp.0x11c4_100 等,uin-form)
│ fileInfo(尺寸/md5/sha1/类型) + extBizInfo(场景/文案)
│ → 回 uKey / ipv4s / msgInfo / subFileInfos
上传一张图 ──────┤
└─ 有 uKey 时:highway TCP PUT
POST /cgi-bin/httpconn?htcmd=0x6FF0087&uin=<自己>
帧:0x28 | headLen | bodyLen | head | body | 0x29
每 1 MiB 一块,串行 + keep-alive;失败重连重发同一块
→ finalizeMediaMsgInfo() → commonElem.pbElem → PbSendMsg命令号 / cmdId 对照(群 / 私聊):
| 类型 | OIDB 申请 | highway cmdId(群 / 私聊) | requestId | businessType(场景) | commonElem businessType |
|---|---|---|---|---|---|
| 图片 | 0x11c4 / 0x11c5 | 1004 / 1003 | 1 | 1 | 20 |
| 语音 | 0x126e / 0x126d | 1008 / 1007 | 1 / 4 | 3 | 22 |
| 视频 | 0x11ea / 0x11e9 | 1005 / 1001(封面 1006 / 1002) | 3 | 2 | 21 |
几个必须照抄的细节
tryFastUploadCompleted: true:资源已在服务端时响应里没有 uKey,就不必传字节 (秒传)。有 uKey 却没有字节时按fastOnlyError抛错,而不是发一条空消息。compatQmsgSceneType:图片 / 语音是群 2 / 私聊 1(旧版兼容元素分场景), 视频固定 2(连私聊也是 —— 老videoFile元素没有场景之分,给 1 会让旧客户端 显示「视频已过期」)。- 语音的
bytesReserve分场景,形状不同(真机抓包 2026-09-24):- 群聊:4 字节
08 00 38 00,并带bytesGeneralFlags(照抄 NapCat)。 - 私聊:33 字节容器(见下)。
- 群聊:4 字节
- 私聊的
bytesGeneralFlags一个字节都不能带(2026-09-30 单变量 A/B 定位):带上 NapCat 的 14 字节 private 那条,收端 QQ 就不画波形;去掉即恢复,与bytesReserve的形状无关。 详见「私聊语音波形」。 - 视频尺寸:群聊必须带真实宽高(0×0 会让 QQ-NT 安卓端显示「文件已过期」), 私聊固定 0(服务端 schema 会拒非 0)。
- 视频分块 sha1:
hash.fileSha1是「每个完整 1 MiB 块一条中间态 + 末条整文件 sha1」。 注意它与闪传sha1StateV的差别:文件大小正好是 1 MiB 整数倍时条数不同,不要复用。 - 波形只是装饰:时长走
pttDuration。有 WAV/PCM 就算真振幅,没有就给一条 30 字节 合成条(官方静音底 25),不引任何音频解码依赖、也不因为波形失败而让整条消息失败。
两个「不报错但收端说已过期」的真机坑
这两个都不会让 PbSendMsg 或 highway 回错(result=0、error_code=0),只在收端表现为 「图片/语音/视频已过期」:
- IP 必须小端解:
ServerAddr.ip/IPv4.outIP是FIXED32(线上小端),数字里 最低字节才是点分串的第一个八位组。写成大端(>>> 24开头)会把地址字节序整个反过来,NTV2RichMediaHighwayExt.network.ipv4s[].domain.ip于是带着一个不存在的节点地址 —— 上传帧照样拿到error_code=0,但文件不会落到该 uKey 上。参考实现都取小端: NapCatpacket/highway/utils.ts:int32ip2str、Lagrange.CoreUtility/ProtocolHelper.cs。 - 图片必须带
extBizInfo.pic的 reserve:群聊bytesPbReserveTroop(tag 12)、 私聊bytesPbReserveC2c(tag 11),内容都是{ subType }(照抄 NapCat 的UploadGroupImage/UploadPrivateImage)。漏了服务端不会把文件真正落到该子类型的 存储桶里。finalizeMediaMsgInfo把服务端响应里的 pic 按 key 补齐而不是重建, 就是为了不把这两个字段丢掉。
私聊语音波形(2026-09-24 抓包 → 2026-09-30 单变量定位)
现象:我们自己发的群聊语音 QQ 端有波形,私聊语音是平的。
结论(2026-09-30 更新):私聊不能带 extBizInfo.ptt.bytesGeneralFlags。 在另一份实现上 把「同一段音频、同一版本、只有这一个字段不同」的四种组合都跑了一遍:
私聊 bytesGeneralFlags | bytesReserve | 收端波形 |
|---|---|---|
| 14 字节(NapCat private) | 33 字节容器 | 平的 |
| 14 字节(NapCat private) | 裸 4 字节 | 平的 |
| 缺席 | 33 字节容器 | 有波形 |
| 缺席 | 裸 4 字节 | 有波形 |
也就是说 bytesReserve 的形状不是决定因素(发裸 4 字节照样能画),commonElem.businessType 的 12 / 22 也不是(flags 在场时两种都平、去掉后两种都有波形)。群聊那条 10 字节 flags 一直 照发,群聊波形一直正常。
历史结论(2026-09-24):用安卓真机抓包(0x126d_100)逐字段对出来,私聊的 reserve 是 33 字节容器:
05 02 00 01 00 ← 固定头
04 00 04 <clientRandomId BE32> ← 该消息的 random(与 upload.clientRandomId / 消息 random 同值)
08 00 04 00 00 00 01
09 00 04 00 00 00 03
0A 00 04 08 00 38 00 ← 尾部恰好就是群聊那 4 字节即 0A 项的内容 = 08 00 38 00;NapCat / SL 当时只发了这一格(连长度前缀一并丢),于是把 「私聊波形不渲染」归因于形状 —— 按上面的 A/B 这是误判(当年这次改动是否只动了容器,已 无法回溯)。容器继续按抓包发:真机就是这样,发它不报错也不影响波形。实现见 buildPttReserve()(src/highway/media-upload.ts):私聊走 33 字节容器、群聊照旧 4 字节, 且因为容器内嵌 clientRandomId,私聊语音的 clientRandomId 必须与 upload.clientRandomId用同一个值(makeClientRandomId() 已提为可注入参数)。
顺带排除的(都不是原因):ptt.waveform 的振幅字节(服务端把发送端的波形原样带到 收端元素 45925,我们群聊/服务端漫游缓存里都能看到真波形)、收端元素缺 45909/45911/45922 (群聊也缺,但群聊能画)。
变声标记(2026-09-27 抓包对比)
发一条原声、一条变声的群聊语音(同样是 0x126e_100 + PbSendMsg),逐字段对比后只有两处不同:
extBizInfo.ptt.changeVoice (tag 4) 原声:字段缺席(=0) 变声:1
extBizInfo.ptt.bytesReserve (tag 12) 原声:08 00 38 00 变声:08 01 38 00两处是同一个标记的两份镜像(bytesReserve 内嵌 {1:0|1, 7:0} 的 1 就是它)。其余差异 只是「换了一份重新编码的音频」:fileSize / fileHash / fileSha1 / fileUuid / waveform / uploadTime 全跟着变。
实现:UploadPttParams.voiceChanged(缺省 false = 原声)。协议层同时写 changeVoice: 1 与 bytesReserve 的那一字节;finalizeMediaMsgInfo 显式覆盖,保证服务端 不回该字段时也不会丢(它纯属客户端意图)。
秒传(fast-upload)的实测结论
tryFastUploadCompleted: true 下,命中与否由服务端按「资源是不是真的在」决定:命中 = 响应里 没有 uKey = 不用传字节,pbElem 直接用响应回的 msgInfo(与 NapCat / Lagrange 的处理完全相同, 两边也都是靠「无 uKey 就不传」来判定的)。
真机验证(2026-09-24)——结论是秒传本身可靠,不会把失败掩盖成永久 404:
| 动作 | native 日志 | CDN 探针 |
|---|---|---|
| 修复 IP bug 前,同一份文件反复重发 | 每次都申请了 HttpConn.0x6ff_501 会话(= 服务端每次都给了 uKey) | 每次 404 file does not exist |
| 修好后再发那份文件(内容没变) | 同样申请了会话(没有因为「见过这个 md5」而跳过) | 200 + 字节与本地逐字节一致 |
| 紧接着再发一次同一份文件 | 0x11c4 之后直接 MessageSvc.PbSendMsg,没有会话申请 | 200 + 字节一致(秒传的 msgInfo 是可用的) |
也就是说:上传失败表现为「给了 uKey 但字节没落盘」,不会在服务端留下一个假的「已有」索引, 所以「下次遇到还是 404」的情形并没有出现。
要看某一条到底传没传字节,不用再靠推断:
- 回执自带
uploads[]({ kind, fileName, fileSize, md5Hex, fastUpload })——fastUpload: true就是秒传,一个字节没传;服务层与 MCP 都会带这个字段; - 账号日志里
media-upload(上传链路)/media-upload-summary(每个媒体一行,含fastUpload)两个事件; - 命中秒传时还会额外记一条
fileExist=…(响应 msgInfoBody 的fileExist)。它的语义 (尤其「为 false 是否正常」)还没验证过,所以只记不报错;等有实测样本再考虑拿它当防护。
联调时的素材选择:验「真上传」必须用内容不同的新文件(同 md5 会走秒传、字节一个不传; 新文件才能验到 highway 那一段),而验秒传正好相反 —— 就用刚刚成功过的同一份文件再发一次。
验尸手法(不依赖任何客户端):从本地库把该消息的元素挖出来,取出 pic 元素里的 fileid, 再用 get_download_rkeys 的群图 rkey 直连 CDN —— 上传成功是 200 + 图片字节, 没落盘是 404 {"retmsg":"file does not exist"}:
SELECT "40800" FROM group_msg_table WHERE "40001"=<msgId> -- decode_db_blob
https://multimedia.nt.qq.com.cn/download?appid=1407&fileid=<fileid>&spec=720&rkey=<群 rkey>appid 与 rkey 都是「场景 × 媒体类型」绑定的:群 1407 / 私聊 1406;rkey 类型 10/20 = 私聊图/群图、12/22 = 视频、14/24 = 语音(见 account/media_download)。 注意 get_download_rkeys 的 OIDB(0x9067_202)只下发图片那三档,传语音 / 视频的 类型会 170019002 Service Failure —— 要验语音 / 视频得走 media_url 的 OIDB 解析。
三之二、文件(群文件 / 私聊文件)
文件不是富媒体那条 NTV2 管线的分支,而是「老 OIDB 申请 + highway 裸帧 PUT + 发布/发送」,两条场景各不相同:
| 步骤 | 群文件 | 私聊文件 |
|---|---|---|
| 申请 | 0x6D6_0 | 0xE37_1700 |
| highway cmdId | 71 | 95 |
| 额外一步 | 0x6D9_4 发布成群聊气泡 | 0xE37_800 finalize(拿下载路由) |
| 发出 | (就是那条 OIDB) | MessageSvc.PbSendMsg(trans0x211 路由 + msgContent) |
代码:packages/protocol/src/file/file-send.ts(sendGroupFile / sendPrivateFile), schema 在 src/oidb/file-upload-schemas.ts,highway 扩展在 src/highway/file-upload-ext.ts。
四个必须照抄的地方
- 群文件发布不能走
PbSendMsg:带transElem(elemType=24)的发消息会被服务端直接result=79拒收。发布是独立的 OIDB0x6D9_4(body在 tag 5),info.field5=true是服务端反序列化器认这条分支的判别位、info.field3是 31 位随机数。 - 私聊文件的路由是
trans0x211 { ccCmd: 4, uid },内容也不在richText.elems里, 而是在messageBody.msgContent—— 一段FileExtra { file: NotOnlineFile, field6 }。 用常规 c2c 路由 + 元素送文件会被拒收。 FileUploadExt.busiBuff只带senderUin(群文件再带群号),不要带旧busId:102: 带了会让离线文件服务端收下 highway 字节却永远 finalize 不成可下载的文件(大文件必现)。- 私聊「前 10 MiB」md5 的上限是
0x98A000(10002432),不是10*1024*1024、 也不是10^7(hash-file.ts的FILE_MD5_HEAD_LIMIT)。用错会让超过该长度的文件 的前段校验失败:字节传上去了,但永远 finalize 不成可下载的离线文件。
秒传与回执(2026-09-24 真机实测)
两条管线都有 boolFileExist:为 true 时服务端已按 md5 持有该文件,跳过 highway PUT (一个字节不传)。MCP 回执里的 fastUpload 就是它,fileId / fileHash / fileName / fileSize / md5Hex 一并返回,便于事后排查。
| 场景 | 申请响应 | native 日志 | 结果 |
|---|---|---|---|
| 群文件首发(3 MiB) | boolFileExist=false | 1750_0 → HttpConn.0x6ff_501 → 1753_4 | 真传字节(3 MiB 用 2.5s) |
| 群文件重发同一份 | boolFileExist=true | 1750_0 → 直接 1753_4(无会话申请) | 秒传命中,换了个新 fileId |
| 私聊文件首发 | boolFileExist=false | 3639_1700 → 会话 → 3639_800 → PbSendMsg | 真传字节 |
| 私聊文件重发同一份 | boolFileExist=false | 同上(又申请了一次会话) | 未命中,又真传了一遍 |
也就是说:群文件会按 md5 去重,私聊(离线文件)不会 —— 服务端每次都发一个新 uuid。 两个分支的代码是同一条(都只看 boolFileExist),所以这是服务端行为,不是我们漏做了什么。
(群文件那张表的 1750 = 0x6D6、1753 = 0x6D9,is_uid=true 只有群文件申请是; HttpConn.0x6ff_501 就是 highway 会话申请,它在不在=有没有真传字节。)
私聊的 0xE37_800 finalize 是尽力而为:file 本身已够收端下载,field6 只是加强项。 失败只记日志并照发(回执 finalized: false),不让整条发送跟着失败。
大文件是流式上传(FileChunkSource + 1 MiB 分块),不会把整文件读进内存。
与闪传的关系
闪传走的是 multimedia.qfile.qq.com/sliceupload(HTTPS + rkey),媒体上传走 highway TCP。 两者只共享哈希层(highway/hash-file.ts、sha1-stream.ts),传输层不共用。
三之三、闪照:OffPicUp 申请 + 老式 highway
闪照不走 NTV2,而是老式图片通道,两跳:
1. LongConn.OffPicUp(原始 SSO,body 是纯 protobuf;SSO 帧由 native 组)
→ 回 serviceTicket(336B)+ 服务端签发的 downloadPath(/uin-<编号>-<MD5 大写>)
2. PicUp.DataUp(highway,appId=16 / cmdId=1 / extend 空)
→ errorCode=0 即成功
3. 拼 commonElem{serviceType:3}.pbElem = { pic(2) = NotOnlineImage },后面再补一条兜底文本秒传:第 1 跳的响应里可能没有 serviceTicket(实测 field1=1 field4=1, body 里只有 downloadPath / resId)。这说明服务端已按 md5 持有这张图,第 2 跳整段 跳过 —— 与 NTV2 用「响应里没有 uKey」判定秒传是同一个语义,产物(downloadPath 与 元素字节)完全一样。实现见 uploadLegacyImage 的 fastUpload,它会一路透传到 SendMediaUploadReport.fastUpload 与服务层日志。
代码:packages/protocol/src/highway/legacy-image-upload.ts(编排)+ offpic-schemas.ts(OffPicUp 请求/响应)。元素侧是 msg/send-elements.ts 的 flashPhoto:给 source 就走上传并自动拼 pic,给现成的 pic 就不上传。
与 NTV2 的差别(不要混用参数):
| NTV2 | 老式(闪照) | |
|---|---|---|
| 申请 | 0xE37_100 OIDB | LongConn.OffPicUp |
| highway appId | 1600001604 | 16 |
| highway commandId | 1003/1004… | 1 |
bytesReqExtendInfo | NTV2RichMediaHighwayExt | 空 |
serviceTicket | 会话的 sig_session | OffPicUp 响应 field9 |
| 产物 | commonElem{48}.pbElem | NotOnlineImage 记录 |
五个容易写错的地方
serviceTicket缺失不等于失败。它是秒传信号(见上);只有downloadPath也 没有时才是真的失败。早先把缺 ticket 直接当错误,导致「同一张图发第二次」必定报错。不要在 body 前面补长度前缀。 抓包里
00 00 00 80 | body那 4 字节是 native 组好的 SSO 帧长度(钩子挂在 Socket 层才录进来),sendPacket交纯 protobuf 就行。 补上去会让服务端当成畸形 protobuf 直接不回包:真机实测 100% 卡满REPLY_TIMEOUT(30s)后报sso_request_outcome_unknown_timeout;去掉后稳定 500~600ms 回 515 字节。NotOnlineImage的 tag 8 是高、tag 9 是宽。早先的记录写反过;2026-10-28 用 JPEG SOF 核对真实像素(1080×505)确认:picHeight(8)=505、picWidth(9)=1080。OffPicUp 请求里的 0 值字段要显式写(field10 / 13 / 22),抓包是
50 00/68 00/b0 01 00,靠 schema 上的force。请求里的 uin / selfUid 必须是当前登录账号。拿抓包账号的参数发到别的账号上, 服务端回
para error(08 01 12 11 … "para error")。
已知未解
pbRes.md5Str(31) 这个值两跳响应里都没有,本地也推不出(不是文件 md5、不是它 的再哈希、也不是响应里的 field27)。目前退回文件 md5 大写,收端是否忽略它未验证。 抓包:qqhook-20261028-051613.txt + v6.htdata.qq.com_2026_10_28_05_14_53.har。
三之四、合并转发(SsoSendLongMsg)
发「聊天记录」是两步,协议实现在 packages/protocol/src/msg/send-forward.ts (读侧是同目录的 get-forward.ts,两个方向的 schema 字段号不同):
- 上传内容:把每条子消息编码成
PushMsgBody,包进LongMsgResult{ action[{ actionCommand: 'MultiMsg', actionData: { msgBody } }] }, gzip 后作为SendLongMsgReq.info.payload发给trpc.group.long_msg_interface.MsgService.SsoSendLongMsg,拿回resId。 群聊info.type=3且uid.uid/groupUin都是群号;私聊type=1且uid.uid是自己 uid;settings固定{4,1,7,0}(与读侧的{2,0,0,0}不同)。 - 发卡片:用
{ kind: 'forward', resId }元素走普通MessageSvc.PbSendMsg, 收端点开卡片才会按 resId 拉内容。两步都要做 —— 只发卡片会指向一段不存在的内容。
搬自 SnowLuma packages/core/src/bridge/apis/forward.ts,字段与 NapCatQQ 的 UploadForwardMsg、Lagrange.Core 的 LongMsgSendService 三边核对过。三个要点:
嵌套转发 piggyback:节点给
innerForward时递归先把内层传完,把「内层 resId 卡片 + 内层 msgBody(actionCommand = uuid)」一起放进外层 payload;卡片 JSON 里的uniseq与那个actionCommand必须相等(收端只拉一次最外层就能走完整棵树)。转发已有的 resId 卡片:节点里是「转发一张已存在的聊天记录」(
{kind:'forward', resId}) 时,会先用SsoRecvLongMsg把这个 resId 的原始 actions 拉下来,以原卡片的 uniseq 为actionCommand随包 piggyback 进本层(对齐 NapCat)—— 收端按 uniseq 就地展开, 不必再向服务器单独拉一次。拉取失败只记日志、卡片照发;原卡片的 source / summary / news / tSum 从 XML(m_fileName/<source>/<title>/tSum)或 Ark 的meta.detail里带上,收端才有预览行。节点内媒体:节点元素里的图片 / 语音 / 视频走同一套 NTV2 上传,私聊转发含媒体时必须 能解析出对方 uid(上传要有场景)。
转发已有媒体走免字节上传:转发一条已有消息里的图片 / 语音 / 视频时,元素带
fingerprint(来自 wire 的md5Bytes(45406)/md5(45424) +contentHash(45408, sha1) + 尺寸),就不读 本机文件,直接把这些报给 NTV2 走 fast-upload。图片同时保留download.fileToken/download.originalUrl,服务端要求字节时由服务层复用统一媒体下载服务(含缓存、CDN 与 外部 rkey 回退)取回原图,重新按实际字节计算哈希并申请上传;秒传命中不下载。 逐条发送、合并转发和嵌套节点共用此路径。缺少原图或下载失败时不继续发卡片。 语音、视频仍在服务端要求字节时抛fastOnlyError。本机路径要剥
::NTOSFull:::QQ NT 的 45004 / 45403 等路径字段常带这个虚拟前缀, 不是真实路径;渲染层读出来与协议层cleanNtLocalPath()都会剥掉,否则stat必 ENOENT。节点级装扮:每个节点可选
dress(气泡 / 字体 / 挂件)。字体有两个 wire 槽位, 两条通道必须分清:- 透传(转发已有消息走这条):
fontId1Raw→fontId1(tag 56)、fontId2Raw→fontId2(tag 15),两者都原样写、不做任何换算。取值来源就是 DB 列 40801:41525/41531。40801 与元素字段是恒等映射(真机实测41531 = 116182与 元素generalFlags.font.fontId2 = 116182完全相等)。 - 便利通道:
fontId→ tag 56 原样;fontId2→ tag 15 的低 16 位字节序交换形态 (收真实 itemId,换算在协议层做)。
⚠️ 绝不能用
fontId(解码出来的 itemId)去反推 font2:41531的低 16 位是交换过的 itemId,bit 16 是标志位(真机每条 40801 都置位;真实字体 54981 的 41531 是0x1C5D6, 而swap16(54981) = 0xC5D6)。反推会把标志位丢掉,收端可能直接忽略这个字体。 这条路径与普通发消息的dress是同一套实现;普通实时消息实测服务端不采信,但长消息 上传是把字节原样存下来的,收端解码走的是常规 msg-push 路径,所以合并转发里的节点装扮 更可能保住(尚未真机验证)。- 透传(转发已有消息走这条):
尚未真机验证:收发两个方向都做过离线单测(黄金字节 + 全链路 + 嵌套 uniseq 对齐), 但没有真机实发过。
四、服务层与 MCP
MessageSendService(packages/service/src/account/message_send.ts)负责把业务参数翻成 协议参数,四层能力:sendText(可带 @ / 引用)、sendMedia(图片 / 语音 / 视频)、 sendFile(群文件 / 私聊文件)、sendElements(逃生舱)。目标 targetId 收三种写法:
- 群聊:群号;
- 私聊:QQ 号(走本地
nt_uid_mapping_table补 uid)或 uid(反查 QQ 号)。
uid 的宽松度分两档:纯文本私聊不强制 uid(陌生人也能发第一句), 媒体必须 uid(NTV2 上传与路由都按 uid 认人),查不到就如实报错并说明去哪拿。
群临时会话(recent_contact.chatType = 100「群里发起的临时会话」)额外给一个 tempGroupCode(该会话行的列 60001 tempSourceGroupCode):给了就走 routingHead.grpTmp (来源群号 + 对方 uid),不是 c2c —— 对方往往不是好友,普通 c2c 会被服务端当成非好友 消息拒收。这一支的 uid 是必填(grpTmp.toUid 只认 uid),QQ 号会在本地目录里反查。 前端侧:会话映射带上了 tempSourceGroupCode(Conversation),输入框主链路(sendElements / sendVoice)把它随 tempGroupCode 一起过 IPC;发文件会直接告知暂不支持(文件走私聊专用的 trans0x211 管线,临时会话还没验证)。
已接线与未接线(同一会话里能点到但仍走 c2c的入口):
| 入口 | 临时会话 | 说明 |
|---|---|---|
输入框文本 / @ / 表情 / 图片 / 视频(sendElements) | ✅ grpTmp | 本次接线 |
语音(sendVoice → sendMedia) | ✅ grpTmp | 本次接线(录音与 TTS 同一入口) |
文件(sendFile)/ 闪传 | ❌ 直接提示不支持 | 私聊文件走 trans0x211,临时会话的对应管线未知 |
| 合并转发 / Ark 卡片 / 推荐卡片 / 位置卡片 | ❌ 仍走 c2c | 这些入口没传 tempGroupCode(要接就把参数透到各自的 sendElements) |
这套临时会话路由尚未真机验证(协议层离线单测已覆盖),发一条后要看回执 scene 是否为 group-temp、privateSequence 是否非 0。
MCP 四个发送工具(send_text_message / send_media_message / send_file_message / send_rich_message)在生产上应保持 assistantOnly(真实发送 = 有外部副作用,按仓库约定不进对外只读 MCP 面板,只给内置助手);真机联调期间临时摘掉了这个标记(tools.ts 的「发消息(真实副作用)」 小节开头有恢复说明), 联调结束要装回去。失败一律回 ok: false + result / errMsg / hint, 不把「调用了」当「发成功」。媒体消息的回执额外带 uploads[](见第三节的「秒传实测结论」)。
同样在真机联调期临时开放的还有两个轻互动工具(真实副作用,同样应恢复 assistantOnly):send_poke(戳一戳)与 set_message_reaction(贴 / 撤表情回应)。 它们不是消息,走的是独立 OIDB,与 pokeEmoji 互动表情消息元素是两回事:
| 能力 | 协议 | SSO | 说明 |
|---|---|---|---|
| 戳一戳 | 0xED3_1 | OidbSvcTrpcTcp.0xed3_1 | 群聊戳成员 / 私聊戳对方,收端是「戳一戳」灰条 |
| 戳一戳互动表情 | PbSendMsg | MessageSvc.PbSendMsg | commonElem svc 2,通过 pokeEmoji 发送;不再提供独立窗口抖动入口或 poke 别名 |
| 贴 / 撤表情回应 | 0x9082_1 / 0x9082_2 | OidbSvcTrpcTcp.0x9082_N | 群消息上的表情回应;code ≤3 位 = 小黄脸 id,>3 位 = Unicode 码点 |
| 查某表情的回应人 | 0x9083_1 | OidbSvcTrpcTcp.0x9083_1 | 单个表情的回应人列表,带续传 cookie 可分页;协议层 oidb/get-emoji-likes.ts |
0x9083_1 已接到渲染层:鼠标悬停消息气泡下的某枚贴表情,就在鼠标旁弹出回应人面板 (components/ReactionLikersPanel.tsx,头像 + 昵称 + QQ 号、自己那行高亮、滚到底续传)。 链路是 GetEmojiLikes → InteractionService.getMessageReactionUsers(用本地 profile 补服务端 没给的昵称 / 头像)→ IPC account.messageReactionUsers(cursor = 服务端续传 cookie)→ 面板。 MCP 没有开这条工具,要知道一条消息当前有哪些回应、各多少个,仍读 get_message_details 的 reactions[](来自本地库 40062 列)。常用表情目录(0x9084_1) 没有对接,它也不是消息的回应详情。
这几条都尚未真机验证(字段与 SnowLuma / Lagrange / NapCat 三边一致,但没有实发过); 0x9083_1 的回包字段(users / cookie / isLast)也只按 SnowLuma 的 RE 结果对齐,等一次抓包。
上传链路会把会话节点与每块 highway 回帧(errorCode / segRetCode / head hex)写进 账号日志(logger.info(..., { event: 'media-upload' }),日志目录见 getLogDir())—— 排查「上传成功但收端说过期」时,这是唯一能看到服务端态度的地方。
语音的 WAV→SILK 转换在 app 层(apps/desktop/src/main/voice.ts 的 encodeFileToSilk, 用已在依赖里的 silk-wasm),wasm 不放 @weq/service。
五、已知缺口
- 文件只做了「上传 + 发送」:群文件的列目录 / 删除 / 移动 / 重命名还没接(下载 URL 已接)。 真机已验证:群文件气泡能落进本地库(我们自己的解码器读成
[文件: <name>])、 3 MiB 文件 md5 与本地一致、重发命中群文件秒传。 - 文件转发(收 → 原样再发)没做:私聊文件元素能解码(
kind: 'file'),但buildSendElems还不接受它,需要先把 decode 的字段反向映射回NotOnlineFile。 - 私聊文件拿不到秒传(见上「秒传与回执」实测表):服务端对离线文件按次发新
uuid, 同一个文件重发也会再传一遍字节。想省流量得自己按 md5 缓存fileId/fileHash后直接重发消息。 - 语音 / 视频的下载 rkey 拿不到:
0x9067_202只给图片(见上)。要做「发完自查」的 语音 / 视频验收,得先接resolvePttUrl/resolveVideoUrl那条 OIDB。 - 系统表情目录(0x9154_1)没内置:
superSticker的packId/stickerId要调用方给, 拿不到就别走 svc 37 —— 服务端会把 faceId 静默换一张脸。 - @ 的显示名:
at元素默认显示@uin,真名由收端解析;想显示群名片得自己查 roster 再传textContent。 - 没有撤回:回执里有
groupSequence/privateSequence(以及random),但撤回接口还没接。 - 自发消息不会写回本地库:真机验证过 —— 群里自发消息靠服务端 push 回显入库, 私聊则可能延迟很久甚至不进(
result=0+ 服务端历史能拉到 ≠ 本地库有)。 所以前端做发送时必须自己乐观渲染,不能等本地库。乐观条目的对账键是客户端random(回执带回、写进本地库 40002、服务端历史原样保留),不是 msgId / seq —— 见第六节。 - 私聊文本的时间戳格子还没对齐真机:真机(群临时会话包)把 Unix 秒写在 Request field 6 (
syncCookie),私聊文本目前写 field 12(ctrl,取自 SnowLuma)。两者都能发出去,但要 逐字节复刻真机得再抓一条好友私聊的真机包来定论 ——c2cCmd该是 11 还是 0 同理。 - markdown 是账号级硬限制:普通账号发的
commonElem{serviceType:45}会被服务端静默丢掉 (result=0,但群里没有 seq/回显;私聊只留一条[空消息])。markdown 只有官方机器人身份 (@tencent-connect/qqbot-nodejs那条通道)才发得出去。
五之二、引用回复的指针:两个 seq 空间(2026-10-17 真机对账)
引用回复是「elem.replyElement(老 wire srcMsg)+ 正文」的组合,指针落在 origSeqs[0]。 这个格子群聊和私聊要填的不是同一套编号,而这正是 WeQ 私聊引用一直定位不到原消息的原因:
| 场景 | 填什么 | 列 | wire |
|---|---|---|---|
| 群聊 | 群内 seq | 40003 | contentHead.sequence(群消息这格就是群内 seq) |
| 私聊 | 发送方本地 client sequence | 40005 | contentHead.sequence tag 5 |
私聊的「会话级 seq」(40003 / contentHead.ntMsgSeq tag 11)是历史分页与回执用的另一套编号, QQ 不拿它解析引用指针 —— 填了它,收端只会画一个定位不到原消息的空引用框(群聊两个空间同值, 所以群聊这条一直是对的,也就一直没暴露问题)。同一条私聊引用里 47416 也镜像了原消息的另一份 id(实测 = 原消息行的 40006,形如 1<<56 | 40002),同样不是 40003。
判定依据(本地库对账,两条都是真实样本):
- 本机真 QQ 发的私聊引用:元素
47402 = 12,被引用行40005 = 12(40003 = 785)—— 引用元素与 40900 缓存里的源行逐字段对得上; - WeQ 发的私聊引用(
触发?):元素47402 = 821,被引用行40003 = 821、40005 = 6851—— 填的是会话级那套,收端定位不到。
实现上的三个落点:origMsgSeq 由调用方选定(@weq/protocol 的 SendReplyElement 有说明), @weq/service 的 buildTextElements 优先 replyToClientSeq、缺省退回 replyToMsgSeq, 渲染端 composerQuote.composerQuoteElement 优先用行里的 clientSeq(列 40005,经 ChatMsgWire / Message.clientSeq 透上来)。MCP 侧 send_text_message 因此多了 replyToClientSeq,get_messages(includeIds=true) 会连带返回 clientSeq。
两个已知缺口(都还没动):
- 自己发的消息:私聊发送时
clientSequence用send.ts的进程内自增游标(重启回 1), 而 QQ 客户端是几千几万的单调计数器。同一会话里两条 WeQ 消息可能共用同一个 client sequence,引用其中一条时指针会歧义(收端可能指到另一条)。要彻底稳,得把游标改成 按会话持久化(或从库里的MAX(40005)+1续号)。 - 漫游拉回来的消息:
contentHead.sequence(tag 5) 目前只在本地库里读得到 —— 漫游 / 缺口 补全链路存的还是解码时选定的sequence(私聊 = tag 11),缓存里没有 client sequence, 所以引用一条「缺口补全」来的私聊消息仍会退化成填40003。要支持得给漫游缓存加一列。
六、发送回执的对账键:用 random,不要用 msgId / seq
前端发出去的消息不会立刻(私聊甚至永远不)回到本地库,所以必须乐观渲染一条临时气泡, 等真消息同步进来再收掉。收掉靠什么键对账,是这个功能唯一容易做错的地方。
| 候选 | 发送前已知 | 回执带回 | 本地库 | 服务端历史 | 能当对账键吗 |
|---|---|---|---|---|---|
random | ✅ | ✅ | 40002 | ✅ 原样 | 能(唯一) |
msgId | ❌ | ❌(服务端才分配雪花 id) | 40001 | ✅ | 不能 |
msgSeq | ❌ | ✅ | 40003 | 群聊 ✅;私聊回执 seq ✅、漫游 seq 另一套 | 辅助(群聊更稳) |
要点:
random是我们自己在发送请求里填的(SendMessageParams.random,协议层缺省随机生成), 服务端把它原样回显在回执里、写进本地库的 40002、并在按 seq 拉回服务端历史时原样带回来。 所以它天然是「乐观条目 ↔ 真行」的通用主键,群聊私聊通吃。- 回执对象里直接给
SendMessageOutcome.random([message_send.ts]),前端记下来即可。 msgId那条路是死的,已删。 协议层以前有一个messageId = random & 0x7fffffff || seq的本地推导,和真实的 40001(雪花 id,~7.6e18)没有任何关系 —— 拿它去和库里的msgId比 永远不可能命中。真实数据抽 400 行,40001 & 0x7fffffff == 40002的命中数是 0。- 回执 seq 就是本地 40003 那一套(群聊私聊都是)。 群聊实测 1655 → 1656 连续、与本地 max 逐条相等;私聊回执是「本地 max + 1、逐条递增」,且有一条 weq 发的私聊消息后来真的同步回库、 本地 40003 == 当时的回执
privateSequence(实测见下)。所以回执 seq 可用于排序与 缺口判定;但对账仍首选random—— 参见下方「私聊的两套 seq 空间」。 - 本地库侧:
C2cMsg/GroupMsg暴露msgRandom(列 40002),ChatMsgWire.msgRandom透到前端。因为读列表是按位置索引列的,40002 追加在SELECT_COLUMNS末尾, 不当心插进中间会让后面所有列静默错位(packages/db/test/msg_order.test.ts有一条测试钉这个)。
私聊的三套编号(2026-09-27 实测)
2026-10-16 补充:须区分 wire contentHead.sequence(tag 5,发送方序号)与 contentHead.ntMsgSeq(tag 11,NT 会话序号)。当前 decodeMessage 在私聊优先 tag 11;已有近期私聊样本在 random、发送者、时间及本地 40003 上完成对账。下表是旧回执口径,不据其“服务端 seq 不同”推断当前 tag 11 也与本地不同,更不能直接拿 tag 5 判定漫游窗口。研究原件已移至仓库外,当前产品边界见 统一 SSO 说明。
同一个私聊会话(对方 uid u_EXAMPLEFRIEND... / u_EXAMPLESELF...)里,同一个「序号」概念有三个来源:
| 来源 | 值(实测) | 是否同一套 |
|---|---|---|
发送回执 privateSequence | 2039→2040→2041(逐条 +1);另一会话 47257 | 本地 40003 那一套 |
本地库 40003(自发不落库时该会话 max) | 2038 / 47256 | 与上一致(回执 = max+1) |
服务端 SsoGetC2cMsg(漫游)返回的 seq | 1、2、3…(从 1 起) | 独立的另一套 |
决定性证据:会话 u_EXAMPLESELF... 发过一条 weq 消息,回执 privateSequence=47257;它后来被 QQ 同步 回本地库,那一行的 40003 正是 47257(40040=0,即同步副本)。所以「回执 seq = 本地 40003」在私聊也成立。
但对账仍只认 random,因为:
- 回执 seq 在发送成功的那一刻才拿到,乐观条目在拿到之前(以及静默失败时 seq=0)没有它;
- 而
random在发送之前就生成,全程可用,群聊私聊、本地/漫游三边一致。
另注:私聊本地库确实收不到「刚发出、还没同步」的那条(发完 MAX(40003) 不变,按新的 40002 查也为空),而服务端有(漫游拉回来能看到,msg_id = 我们的 random)。 所以「私聊自发消息不回写本地库、但主动拉服务器能自证」已被实测确认。
真机验证(2026-09-27 已跑)
离线单测只覆盖到「列读出来没错位」。下面这条验的是端到端:我们指定的 random 是否真的 被服务端接受、回显、并写进 40002。这是整条对账链的地基,必须实机跑一次。
前置:QQ 在线(非完全离线模式)、WeQ 与 MCP 都在跑、能对一个自己的会话发消息。
结论:四步全部通过,random 作为对账键成立。 原始记录:
| 场景 | 回执 random | 回执 seq | 本地库 40002 | 服务端历史 msg_id |
|---|---|---|---|---|
私聊 weq-random-probe-c2c-1 | 1433233067 | privateSequence=2039 | ❌ 没有(自发不回写) | ✅ 1433233067 |
群聊 weq-random-probe-group-1 | 2144207638 | groupSequence=1655 | ✅ 命中,40040=1(本机发出) | ✅ 2144207638 |
群聊 weq-random-probe-group-2 | 1095899227 | groupSequence=1656 | ✅ 命中 | — |
私聊 weq-seqspace-probe-A | 226379500 | privateSequence=47257 | ✅ 后来同步命中(40040=0) | — |
| 静默失败:markdown | 634000806 | groupSequence=0 | ❌ 无 | ❌ 无 |
| 静默失败:坏 ark | 1530733653 | groupSequence=0 | ❌ 无 | ❌ 无 |
复现步骤(供回归):
发一条带可识别正文的文本,记下回执里的
random。 走 MCPsend_text_message(它直接返回服务端的SendMessageOutcome,含random)。 例:send_text_message({peerType:'group', targetId:'<群号>', text:'weq-random-probe-1'})。 回执里记下random(和groupSequence)。按 random 回查本地库,确认它落在 40002。 用 MCP
execute_sql(表group_msg_table或c2c_msg_table):SELECT "40003","40001","40002" FROM group_msg_table WHERE "40002"=<上一步的 random>。 群聊命中说明「回执 random = 本地 40002」成立。这一步是核心验收点。私聊再跑一次。 同样
send_text_message({peerType:'c2c', ...}),再SELECT ... FROM c2c_msg_table WHERE "40002"=<random>。 私聊更关键 —— 它正是「等不到 QQ 同步、必须靠 random 自证」的那条路。验「主动拉取能自证」。 对同一条消息,用
fetch_history_window按 seq 窗口从服务端拉回来。它会把结果写进本机漫游 缓存(~/.config/weq/cache/roam-msg/<uin>.db的gap_msg表),其中msg_id列就是 服务端contentHead.msgId(=decodeMessage().head.msgId)。核对:SELECT msg_id, msg_seq FROM gap_msg WHERE kind='group' AND conv='<群号>' AND msg_seq=<上一步的 seq>——msg_id应等于我们那个 random。相等 = 即使本地库没有这条,「主动拉服务器」也能证明 它发出去了,这是静默失败(签名错的 ark、被吞的 markdown)唯一能拿到确定结论的办法。验前端乐观条目会收掉。 在 WeQ 界面里用 Ark 面板发一张卡(图文 / 自定义 JSON)。预期:卡片立刻出现在会话末尾、 带「已发送」标识;等 QQ 把真消息同步进库后,乐观条目消失、只剩真卡片一张(不重影)。 群聊通常几秒内;私聊可能要等下一次 QQ 重启才同步 —— 重启后确认不重影。 (这一步依赖肉眼观察,尚未自动化;前四步已用 MCP 跑通。)
任何一步对不上,优先怀疑:回执 random 没透到前端、40002 没读出来(列错位)、 或该会话私聊的 seq 空间与预期不符(第 6 节表格)。
静默失败的判据:groupSequence / errMsg 都不可信
markdown / 签名错的 ark 这类服务端静默吞掉的发送,回执是 result=0 + errMsg='' —— 和 成功一模一样,只有 seq 能区分:真发出去的带 groupSequence(群)/ privateSequence(私聊), 被吞掉的恒为 0。实测两次吻合(见上表)。所以「已受理」这类状态不能只看 ok, 要么等 random 在库/漫游里命中,要么把 seq === 0 当成「本次极可能被静默丢弃」的强信号。
以上判据只适用于普通私聊与群聊。设备 FTN 文件通知成功时,groupSequence 和 privateSequence 也都为 0,不能据此标成「可能未送达」。前端按目标为设备伪 UID、 peerType=c2c 且回执成功区分,不伪造消息序号;真实失败仍保留失败提示。成功回执表示 提交成功,不等于收端已下载或打开文件。设备占位只做本地刷新,不走普通私聊漫游兜底。
前端据此做的三件事(MainView.tsx / messageBubble.tsx)
- 乐观条目带真实 seq、按 seq 混排。
OptimisticArk/OptimisticForward记下回执的seq(群聊groupSequence/ 私聊privateSequence),mergeOptimisticInto把它按 seq 插进已加载窗口的正确位置 —— 否则「我发一条 → 对方回一条」时,带 seq 的回复会被排到我们 前面。发送中 / 静默失败 / 位置卡片(拿不到 seq)的条目留在末尾。 - 缺口判定不再误报。 乐观条目现在带真实 seq、与真实行同序,
messageGapCount算出的 相邻差自然为 1,不会在「本地库停在 N、weq 发了 N+1」时弹出假缺口。反过来,若乐观 seq 小于 当前窗口下界(用户往上翻过),它按「无位置」处理、不插到顶部 —— 否则会在顶部造出假缺口。 seq === 0主动告警。 回执 seq 为 0 时立刻弹一次 warning toast,气泡上额外挂一个 琥珀色「可能未送达」标签(optimisticRejected)。这是静默失败当前唯一的可靠信号。- 未送达占位可一键移除。 这类条目没有可信序号,只能一直排在时间线末尾,所以状态条右侧 另给一枚「移除」按钮(
MessageBubble的onDismissUnsent)。判据是canDiscardRejectedMessage(state === 'sent'+optimisticRejected+ 无seq+ 本机optimistic-占位),与失败占位的canDiscardFailedMessage分开 —— 后者要求!cid, 而未送达条目正好带着 random 作对账主键。两者都只清前端 state:不写库、不改对方的 接收结果,迟到的真消息回来后仍正常显示。captureOutgoingAfterSeq沿用原规则 —— 没有可信序号的占位让水位退回「不确定」,不因为现在可移除就放宽。
