import type { MarkdownData, MentionExtraSend, } from '@snowluma/proto-defs/action'; import type { Elem, GroupFileExtra, MarketFacePbReserve, PokeExtra, QFaceExtra, QSmallFaceExtra } from '@snowluma/proto-defs/element'; import { protobuf_encode } from '@snowluma/proton'; import { randomUUID } from 'crypto'; import { deflateSync } from 'zlib'; import type { BridgeContext } from './bridge-context'; import { sysFaceStore } from './sys-face-store'; import type { MessageElement } from './events'; import { assertVideoSendPolicy, assertWindowShakeSendPolicy, assertValidMessageElements, MessageElementValidationError, type OutboundMessageScene, } from './element-manifest'; import { uploadImageMsgInfo } from './highway/image-upload'; import { hexToBytes } from './highway/pipeline'; import { uploadPttMsgInfo } from './highway/ptt-upload'; import { uploadVideoMsgInfo } from './highway/video-upload'; type ProtoElem = Partial; export interface SendContext { bridge: BridgeContext; groupId?: number; userUid?: string; /** Explicit transport scene used by scene-limited message elements. */ scene?: OutboundMessageScene; /** * Set by the forward-message upload path. When `true`, file segments * are encoded as receive-side wire shapes (group → `transElem(24)`, * c2c → caller writes `body.msgContent` separately) instead of being * dropped. The QQ-NT server rejects outgoing PbSendMsg with * `transElem(24)` (result=79), but the long-msg upload service does * NOT — it stores the gzipped protobuf verbatim, so the receiver * can walk it back through the regular decoder. Mirrors NapCat's * `PacketMsgFileElement.buildElement` + `buildContent` split (see * `dev/napcatQQ/.../packet/message/element.ts:530-610`). */ forwardFake?: boolean; } function makeTextElem(text: string): ProtoElem { return { text: { str: text }, }; } // QQ-NT splits face ids across three wire encodings. The legacy FaceElem only // renders classic small faces; newer "super" / animated faces sent that way are // silently remapped by the server (e.g. 424→168, issue #168). The split is // data-driven off the system-face catalog (0x9154_1, see sys-face-store): // super (animated, aniSticker not pack (1,1)) → CommonElem 37 + QFaceExtra // other id ≥ 260 → CommonElem 33 + QSmallFaceExtra // classic id < 260 → legacy FaceElem async function makeFaceElem(faceId: number, ctx?: SendContext): Promise { // With a live bridge, wait for the authoritative catalog. Login normally // preloads it, while this await closes the reconnect / first-send race. const wire = ctx ? await sysFaceStore.resolveWire(ctx.bridge, faceId) : sysFaceStore.classify(faceId); if (wire.kind === 'super') { return { commonElem: { serviceType: 37, pbElem: protobuf_encode({ packId: wire.packId, stickerId: wire.stickerId, qsid: faceId, sourceType: 1, stickerType: wire.stickerType, randomType: 1, }), businessType: 1, }, }; } if (wire.kind === 'small') { return { commonElem: { serviceType: 33, pbElem: protobuf_encode({ faceId, preview: '', preview2: '' }), businessType: 1, }, }; } return { face: { index: faceId } }; } function resolveMentionDisplay(ctx: SendContext | undefined, targetUin: number): string { if (!ctx || !targetUin) return ''; if (ctx.groupId !== undefined) { const member = ctx.bridge.identity.findGroupMember(ctx.groupId, targetUin); return member?.card?.trim() || member?.nickname?.trim() || ''; } const friend = ctx.bridge.identity.findFriend(targetUin); return friend?.remark?.trim() || friend?.nickname?.trim() || ''; } function makeMentionElem(element: MessageElement, ctx?: SendContext): ProtoElem { const mentionAll = element.uid === 'all' || element.targetUin === 0; const targetUin = element.targetUin ?? 0; const extra = protobuf_encode({ type: mentionAll ? 1 : 2, uin: mentionAll ? 0 : targetUin, field5: 0, uid: mentionAll ? 'all' : (element.uid ?? ''), }); // Prefer an explicit display string from the caller; otherwise look the // target up in the roster so QQ renders `@昵称` instead of `@QQ号`. // Falls back to the bare uin when the roster doesn't know them yet. let str = element.text; if (!str) { if (mentionAll) { str = '@全体成员 '; } else { const name = resolveMentionDisplay(ctx, targetUin); str = name ? `@${name} ` : `@${targetUin} `; } } return { text: { str, pbReserve: extra, }, }; } function makeReplyElem(element: MessageElement): ProtoElem { const seq = element.replySeq! & 0xFFFFFFFF; const srcMsg: NonNullable = { origSeqs: [seq], }; // Add additional fields if available for better reply display if (element.replySenderUin) { srcMsg.senderUin = BigInt(element.replySenderUin); } if (element.replyTime) { srcMsg.time = element.replyTime; } return { srcMsg }; } // The replied sender, encoded as a mention element placed right after srcMsg. // QQ NT's group reply wire shape expects this; without it a following // user-supplied @ is silently not honored by the server (issue #129). async function makeReplyMentionElem(ctx: SendContext, uin: number): Promise { if (ctx.groupId === undefined || uin <= 0) return null; const member = ctx.bridge.identity.findGroupMember(ctx.groupId, uin); let uid = member?.uid ?? ''; if (!uid) uid = await ctx.bridge.identity.resolveUid(uin, ctx.groupId).catch(() => ''); if (!uid) return null; const name = member?.card?.trim() || member?.nickname?.trim() || String(uin); // uin=0 matches QQ NT's native reply auto-mention (the real uid lives in // `uid`). It does not itself notify — the user's own @ does — and the receive // side strips a type=2/uin=0 mention as structural (#127), so the bot's own // replies don't surface a spurious @ either. const extra = protobuf_encode({ type: 2, uin: 0, field5: 0, uid }); return { text: { str: `@${name} `, pbReserve: extra } }; } function makeDeflatedPayload(content: string): Uint8Array { const deflated = deflateSync(Buffer.from(content, 'utf8')); const payload = new Uint8Array(deflated.length + 1); payload[0] = 0x01; payload.set(deflated, 1); return payload; } function makeJsonElem(element: MessageElement): ProtoElem { const content = element.text ?? ''; return { lightApp: { data: makeDeflatedPayload(content), }, }; } function makeXmlElem(element: MessageElement): ProtoElem { const content = element.text ?? ''; return { richMsg: { serviceId: element.subType === 0 ? 35 : (element.subType ?? 35), template1: makeDeflatedPayload(content), }, }; } function makeMarkdownElem(element: MessageElement): ProtoElem { const data = protobuf_encode({ content: element.text ?? '' }); return { commonElem: { serviceType: 45, pbElem: data, businessType: 1, }, }; } function makePokeElem(element: MessageElement): ProtoElem { const pokeType = element.subType; return { commonElem: { serviceType: 2, pbElem: protobuf_encode({ type: pokeType }), businessType: pokeType, }, }; } /** * Build a market-face (商城表情) wire element from the markers carried on the * receive-side `image` segment (`emoji_id`/`emoji_package_id`/`key`/summary). * * The constants (`itemType=6`, `faceInfo=1`, `subType=3`, 300×300, * `pbReserve.field8=1`) mirror NapCat's `PacketMsgMarkFaceElement.buildElement` * (`dev/NapCatQQ/.../packet/message/element.ts:318-335`) — the QQ-NT server * pairs them with the faceId/tabId/key to relay the sticker. `faceId` is the * raw GUID bytes, recovered from the hex `emojiId`. */ function makeMarketFaceElem(element: MessageElement): ProtoElem { const emojiId = (element.emojiId ?? '').trim(); return { marketFace: { faceName: element.text ?? '', itemType: 6, faceInfo: 1, faceId: hexToBytes(emojiId), tabId: element.emojiPackageId ?? 0, subType: 3, key: element.emojiKey ?? '', imageWidth: 300, imageHeight: 300, pbReserve: protobuf_encode({ field8: 1 }), }, }; } function makeForwardElem(element: MessageElement): ProtoElem { const resId = (element.resId ?? '').trim(); if (!resId) { throw new Error('forward resId is required'); } // `uniseq` MUST round-trip between the preview JSON and the outer // upload's piggyback `actionCommand` for nested forwards to resolve // without an extra server hit. Generate one fresh if absent (flat // forwards don't piggyback anyway, so the value is cosmetic there). const uniseq = (element.forwardUuid ?? '').trim() || randomUUID(); const source = element.forwardSource && element.forwardSource.length > 0 ? element.forwardSource : '聊天记录'; const summary = element.forwardSummary && element.forwardSummary.length > 0 ? element.forwardSummary : '查看转发消息'; const prompt = element.forwardPrompt && element.forwardPrompt.length > 0 ? element.forwardPrompt : '[聊天记录]'; const news = Array.isArray(element.forwardNews) ? element.forwardNews : []; const tSum = element.forwardTSum && element.forwardTSum > 0 ? element.forwardTSum : Math.max(news.length, 1); // LightApp / `com.tencent.multimsg` is the modern wire shape both // QQ-NT, Lagrange.Core, and NapCat emit and decode. The older // `richMsg serviceID=35 m_resid=…` XML still renders on mobile QQ // but it doesn't carry `uniseq`, so nested forwards lose the link // between the inner preview and the piggybacked actions on the // outer's LongMsgResult — cross-checked against // `dev/Lagrange.Core/.../Message/Entity/MultiMsgEntity.cs:43-115` // and `dev/NapCatQQ/.../helper/forward-msg-builder.ts:52-122`. const lightApp = { app: 'com.tencent.multimsg', config: { autosize: 1, forward: 1, round: 1, type: 'normal', width: 300, }, desc: prompt, extra: JSON.stringify({ filename: uniseq, tsum: tSum }), meta: { detail: { news: news.map(n => ({ text: n.text ?? '' })), resid: resId, source, summary, uniseq, }, }, prompt, ver: '0.0.0.5', view: 'contact', }; const json = JSON.stringify(lightApp); return { lightApp: { data: makeDeflatedPayload(json), }, }; } async function makeImageElem(ctx: SendContext, element: MessageElement): Promise { const isGroup = ctx.groupId !== undefined; const targetIdOrUid = isGroup ? ctx.groupId! : (ctx.userUid ?? ''); if (!isGroup && !targetIdOrUid) { throw new Error('private image target uid is missing'); } const msgInfo = await uploadImageMsgInfo(ctx.bridge, isGroup, targetIdOrUid, element); return { commonElem: { serviceType: 48, pbElem: msgInfo, businessType: isGroup ? 20 : 10, }, }; } async function makePttElem(ctx: SendContext, element: MessageElement): Promise { const isGroup = ctx.groupId !== undefined; const targetIdOrUid = isGroup ? ctx.groupId! : (ctx.userUid ?? ''); if (!isGroup && !targetIdOrUid) { throw new Error('private record target uid is missing'); } const msgInfo = await uploadPttMsgInfo(ctx.bridge, isGroup, targetIdOrUid, element); // commonElem.businessType is the QQ NT scene tag the receive-side // decoder pairs with: 12=c2c, 22=group. Sending the group tag on a // c2c message bounces with PbSendMsg result=79. return { commonElem: { serviceType: 48, pbElem: msgInfo, businessType: isGroup ? 22 : 12, }, }; } /** * Receive-side group file element shape — `transElem(elemType=24, * elemValue: 0x01 | BE16(len) | GroupFileExtra)`. * * NOT used for outgoing PbSendMsg (the QQ-NT server rejects that with * result=79); the group-file send-side flow goes through dedicated * OIDB 0x6d9_4 via `bridge.apis.groupFile.publish`. This shape IS used * inside the long-msg upload (forward / multi-msg) — the long-msg * service stores the gzipped protobuf verbatim, and the receiver * decodes file entities from `transElem(24)` (see * `msg-push/rich-body-decoder.ts:169-187`). * * `ctx` is consulted to fill in size/name/md5/sha1 from the upload * metadata cache when the caller only threaded the file_id through. * Mirrors the c2c forward path in `apis/forward.ts::buildForwardPushBody` * which already does this lookup — without it the receiver sees a * "0 B" file with no name (OneBot11 `{type:'file', file_id}` segments * typically omit the metadata since the upload action returned only * the id). */ function makeGroupFileElem(element: MessageElement, ctx?: SendContext): ProtoElem { if (!element.fileId) throw new Error('file element missing fileId'); const cached = ctx?.bridge.recallUploadedFile(element.fileId); const fileSize = element.fileSize ?? cached?.fileSize ?? 0; const fileName = element.fileName ?? cached?.fileName ?? ''; const md5 = element.md5Hex ? hexToBytes(element.md5Hex) : (cached?.fileMd5 ?? new Uint8Array(0)); const sha1 = element.sha1Hex ? hexToBytes(element.sha1Hex) : (cached?.fileSha1 ?? new Uint8Array(0)); // Outer field1 is hardcoded to 6 in NapCat's encoder // (`packet/message/element.ts:589`). Inner GroupFileExtraInfo carries // busId=102 + the file_id + name + size + sha1/md5 hashes. const extraBytes = protobuf_encode({ field1: 6, fileName, inner: { info: { busId: 102, fileId: element.fileId, fileSize: BigInt(fileSize), fileName, fileSha: sha1, extInfoString: '', fileMd5: md5, }, }, }); if (extraBytes.length > 0xFFFF) { // The 16-bit length prefix caps the payload at 64 KiB; even the // densest GroupFileExtra (fileId/name/two hashes) is well under. throw new Error(`group file extra too large (${extraBytes.length} > 65535)`); } const elemValue = new Uint8Array(3 + extraBytes.length); elemValue[0] = 0x01; elemValue[1] = (extraBytes.length >> 8) & 0xff; elemValue[2] = extraBytes.length & 0xff; elemValue.set(extraBytes, 3); return { transElem: { elemType: 24, elemValue, }, }; } async function makeVideoElem(ctx: SendContext, element: MessageElement): Promise { const isGroup = ctx.groupId !== undefined; const targetIdOrUid = isGroup ? ctx.groupId! : (ctx.userUid ?? ''); if (!isGroup && !targetIdOrUid) { throw new Error('private video target uid is missing'); } const msgInfo = await uploadVideoMsgInfo(ctx.bridge, isGroup, targetIdOrUid, element); // commonElem.businessType is the QQ NT scene tag the receive-side // decoder pairs with: 11=c2c, 21=group. Sending the group tag on a // c2c message bounces with PbSendMsg result=79. // // Oversize videos throw here; the OneBot layer catches that and falls // back to file upload (see message-actions.ts video fallback). A file // element can't be built here — there's no uploaded file_id yet. return { commonElem: { serviceType: 48, pbElem: msgInfo, businessType: isGroup ? 21 : 11, }, }; } /** * Build proto Elem objects from an array of MessageElements. * Supports: text, face, mface, at, reply, json, xml, markdown, image, record, video, forward, poke. * Image, record and video elements trigger NTV2 highway upload via the SendContext. */ export async function buildSendElems(elements: MessageElement[], ctx?: SendContext): Promise { // Validate the whole message before the first upload or packet build. This // preserves all-or-nothing semantics: a malformed later segment cannot make // an earlier media segment perform side effects before the send is rejected. assertValidMessageElements(elements, 'W'); // Canonical MessageElements cannot contain empty text. OneBot's explicit // empty-text compatibility placeholders are removed before this boundary, // so the array length here is the effective on-wire segment count. assertVideoSendPolicy( elements.filter((element) => element.type === 'video').length, elements.length, ); assertWindowShakeSendPolicy( elements.filter((element) => element.type === 'poke').length, elements.length, ctx?.scene, ); for (const element of elements) { if ((element.type === 'image' || element.type === 'record' || element.type === 'video') && !ctx) { throw new MessageElementValidationError( 'MISSING_FIELD', `message element "${element.type}" requires SendContext`, element.type, ); } if (element.type === 'file' && !ctx?.forwardFake) { throw new MessageElementValidationError( 'UNSENDABLE_TYPE', 'message element "file" must use the group/private file upload pipeline', element.type, ); } } const result: ProtoElem[] = []; // A user-supplied @ that lands immediately after a reply's srcMsg isn't // honored by the QQ NT group server (the @ shows but never notifies, #129). // When a reply and an @ coexist, emit the replied sender as a trailing // mention right after srcMsg (mirrors Lagrange ForwardEntity.PackElement), // which restores the wire shape the server expects. const hasUserAt = elements.some((e) => e.type === 'at'); for (const elem of elements) { switch (elem.type) { case 'text': result.push(makeTextElem(elem.text)); break; case 'face': result.push(await makeFaceElem(elem.faceId, ctx)); break; case 'poke': result.push(makePokeElem(elem)); break; case 'mface': result.push(makeMarketFaceElem(elem)); break; case 'at': result.push(makeMentionElem(elem, ctx)); break; case 'reply': result.push(makeReplyElem(elem)); if (hasUserAt && ctx?.groupId !== undefined && elem.replySenderUin) { const replyMention = await makeReplyMentionElem(ctx, elem.replySenderUin); if (replyMention) result.push(replyMention); } break; case 'json': result.push(makeJsonElem(elem)); break; case 'xml': result.push(makeXmlElem(elem)); break; case 'markdown': result.push(makeMarkdownElem(elem)); break; case 'image': result.push(await makeImageElem(ctx!, elem)); break; case 'forward': result.push(makeForwardElem(elem)); break; case 'record': result.push(await makePttElem(ctx!, elem)); break; case 'video': result.push(await makeVideoElem(ctx!, elem)); break; case 'file': // Files split into two routes depending on whether this is a // live send or a forward-message fake-send: // // 1. LIVE send (PbSendMsg / OIDB 0x6d9_4) — never carried on // elems[]. The OneBot layer splits file segments off before // calling buildSendElems: // * c2c (private): split → `bridge.sendC2cFileMessage` // (routingHead.trans0x211 + msgContent FileExtra). // * group: split → `bridge.sendGroupFileMessage` // (OIDB 0x6d9_4 publish). // The QQ-NT server REJECTS outgoing PbSendMsg with a // transElem(24) (result=79), so the all-message preflight above // raises a typed validation error when a live file reaches here. // // 2. FORWARD-FAKE upload (long-msg) — `ctx.forwardFake===true`. // The long-msg service stores the gzipped protobuf verbatim // and the receiver decodes file entities from transElem(24) // + msgContent FileExtra. Mirror NapCat's split (see // `dev/napcatQQ/.../packet/message/element.ts:530-610`): // * group → emit transElem(24) via makeGroupFileElem // * c2c → emit NOTHING here; the forward-builder pulls // the file segment off and writes msgContent // separately (because RichText.notOnlineFile + // FileExtra both live outside elems[]). if (!ctx?.forwardFake) { throw new Error('element-builder file routing invariant failed after preflight'); } if (ctx.groupId !== undefined) { result.push(makeGroupFileElem(elem, ctx)); } // c2c forwardFake intentionally emits no Elem — handled by the // forward-builder at the msgContent level. break; default: // assertValidMessageElements above rejects every non-W type before any // side effect. Reaching this branch means the manifest and dispatcher // drifted despite their reconciliation test. throw new Error(`element-builder dispatch invariant failed: ${elem.type}`); } } return result; }