Skip to content

发消息(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:

场景routingHeadcontentHead备注
群聊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>:

text
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 可以直接再发出去(搬运、转发),不需要中间结构。 测试里有一条自解码往返就是钉这个性质。

已有的类型:

kindwire 形态需要上传
textelem.text.str否
atelem.text + pbReserve(3=type/4=uin/9=uid)否
face老 elem.face / commonElem svc 33 / svc 37否
mfaceelem.marketFace(16 字节 GUID)否
replyelem.replyElement(嵌套 origElementsRaw)否
arkelem.lightApp.data(deflate + 0x01 头)否
xmlelem.richMsg.template1(同上)否
markdowncommonElem svc 45 + MarkdownData否
pokecommonElem svc 2 + PbElem否
forwardelem.lightApp(com.tencent.multimsg 卡片,只引用一个已有 resId)否
imagecommonElem(48, 20).pbElem = msgInfo是
recordcommonElem(48, 22).pbElem = msgInfo是
videocommonElem(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(群 / 私聊)requestIdbusinessType(场景)commonElem businessType
图片0x11c4 / 0x11c51004 / 10031120
语音0x126e / 0x126d1008 / 10071 / 4322
视频0x11ea / 0x11e91005 / 1001(封面 1006 / 1002)3221

几个必须照抄的细节 ​

  • tryFastUploadCompleted: true:资源已在服务端时响应里没有 uKey,就不必传字节 (秒传)。有 uKey 却没有字节时按 fastOnlyError 抛错,而不是发一条空消息。
  • compatQmsgSceneType:图片 / 语音是 群 2 / 私聊 1(旧版兼容元素分场景), 视频固定 2(连私聊也是 —— 老 videoFile 元素没有场景之分,给 1 会让旧客户端 显示「视频已过期」)。
  • 语音的 bytesReserve 分场景,形状不同(真机抓包 2026-09-24):
    • 群聊:4 字节 08 00 38 00,并带 bytesGeneralFlags(照抄 NapCat)。
    • 私聊:33 字节容器(见下)。
  • 私聊的 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 上。参考实现都取小端: NapCat packet/highway/utils.ts:int32ip2str、Lagrange.Core Utility/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。 在另一份实现上 把「同一段音频、同一版本、只有这一个字段不同」的四种组合都跑了一遍:

私聊 bytesGeneralFlagsbytesReserve收端波形
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_00xE37_1700
highway cmdId7195
额外一步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 拒收。发布是独立的 OIDB 0x6D9_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=false1750_0 → HttpConn.0x6ff_501 → 1753_4真传字节(3 MiB 用 2.5s)
群文件重发同一份boolFileExist=true1750_0 → 直接 1753_4(无会话申请)秒传命中,换了个新 fileId
私聊文件首发boolFileExist=false3639_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 OIDBLongConn.OffPicUp
highway appId160000160416
highway commandId1003/1004…1
bytesReqExtendInfoNTV2RichMediaHighwayExt空
serviceTicket会话的 sig_sessionOffPicUp 响应 field9
产物commonElem{48}.pbElemNotOnlineImage 记录

五个容易写错的地方 ​

  • 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 字段号不同):

  1. 上传内容:把每条子消息编码成 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} 不同)。
  2. 发卡片:用 { 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_1OidbSvcTrpcTcp.0xed3_1群聊戳成员 / 私聊戳对方,收端是「戳一戳」灰条
戳一戳互动表情PbSendMsgMessageSvc.PbSendMsgcommonElem svc 2,通过 pokeEmoji 发送;不再提供独立窗口抖动入口或 poke 别名
贴 / 撤表情回应0x9082_1 / 0x9082_2OidbSvcTrpcTcp.0x9082_N群消息上的表情回应;code ≤3 位 = 小黄脸 id,>3 位 = Unicode 码点
查某表情的回应人0x9083_1OidbSvcTrpcTcp.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
群聊群内 seq40003contentHead.sequence(群消息这格就是群内 seq)
私聊发送方本地 client sequence40005contentHead.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...)里,同一个「序号」概念有三个来源:

来源值(实测)是否同一套
发送回执 privateSequence2039→2040→2041(逐条 +1);另一会话 47257本地 40003 那一套
本地库 40003(自发不落库时该会话 max)2038 / 47256与上一致(回执 = max+1)
服务端 SsoGetC2cMsg(漫游)返回的 seq1、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-11433233067privateSequence=2039❌ 没有(自发不回写)✅ 1433233067
群聊 weq-random-probe-group-12144207638groupSequence=1655✅ 命中,40040=1(本机发出)✅ 2144207638
群聊 weq-random-probe-group-21095899227groupSequence=1656✅ 命中—
私聊 weq-seqspace-probe-A226379500privateSequence=47257✅ 后来同步命中(40040=0)—
静默失败:markdown634000806groupSequence=0❌ 无❌ 无
静默失败:坏 ark1530733653groupSequence=0❌ 无❌ 无

复现步骤(供回归):

  1. 发一条带可识别正文的文本,记下回执里的 random。 走 MCP send_text_message(它直接返回服务端的 SendMessageOutcome,含 random)。 例:send_text_message({peerType:'group', targetId:'<群号>', text:'weq-random-probe-1'})。 回执里记下 random(和 groupSequence)。

  2. 按 random 回查本地库,确认它落在 40002。 用 MCP execute_sql(表 group_msg_table 或 c2c_msg_table): SELECT "40003","40001","40002" FROM group_msg_table WHERE "40002"=<上一步的 random>。 群聊命中说明「回执 random = 本地 40002」成立。这一步是核心验收点。

  3. 私聊再跑一次。 同样 send_text_message({peerType:'c2c', ...}),再 SELECT ... FROM c2c_msg_table WHERE "40002"=<random>。 私聊更关键 —— 它正是「等不到 QQ 同步、必须靠 random 自证」的那条路。

  4. 验「主动拉取能自证」。 对同一条消息,用 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)唯一能拿到确定结论的办法。

  5. 验前端乐观条目会收掉。 在 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) ​

  1. 乐观条目带真实 seq、按 seq 混排。 OptimisticArk / OptimisticForward 记下回执的 seq(群聊 groupSequence / 私聊 privateSequence),mergeOptimisticInto 把它按 seq 插进已加载窗口的正确位置 —— 否则「我发一条 → 对方回一条」时,带 seq 的回复会被排到我们 前面。发送中 / 静默失败 / 位置卡片(拿不到 seq)的条目留在末尾。
  2. 缺口判定不再误报。 乐观条目现在带真实 seq、与真实行同序,messageGapCount 算出的 相邻差自然为 1,不会在「本地库停在 N、weq 发了 N+1」时弹出假缺口。反过来,若乐观 seq 小于 当前窗口下界(用户往上翻过),它按「无位置」处理、不插到顶部 —— 否则会在顶部造出假缺口。
  3. seq === 0 主动告警。 回执 seq 为 0 时立刻弹一次 warning toast,气泡上额外挂一个 琥珀色「可能未送达」标签(optimisticRejected)。这是静默失败当前唯一的可靠信号。
  4. 未送达占位可一键移除。 这类条目没有可信序号,只能一直排在时间线末尾,所以状态条右侧 另给一枚「移除」按钮(MessageBubble 的 onDismissUnsent)。判据是 canDiscardRejectedMessage(state === 'sent' + optimisticRejected + 无 seq + 本机 optimistic- 占位),与失败占位的 canDiscardFailedMessage 分开 —— 后者要求 !cid, 而未送达条目正好带着 random 作对账主键。两者都只清前端 state:不写库、不改对方的 接收结果,迟到的真消息回来后仍正常显示。captureOutgoingAfterSeq 沿用原规则 —— 没有可信序号的占位让水位退回「不确定」,不因为现在可移除就放宽。

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