diff --git a/packages/proto-defs/package.json b/packages/proto-defs/package.json index fad0accc..44296777 100644 --- a/packages/proto-defs/package.json +++ b/packages/proto-defs/package.json @@ -91,6 +91,10 @@ "./oidb-actions/ocr": { "types": "./src/oidb-actions/ocr.ts", "default": "./src/oidb-actions/ocr.ts" + }, + "./oidb-actions/sys-faces": { + "types": "./src/oidb-actions/sys-faces.ts", + "default": "./src/oidb-actions/sys-faces.ts" } }, "scripts": { diff --git a/packages/proto-defs/src/oidb-actions/sys-faces.ts b/packages/proto-defs/src/oidb-actions/sys-faces.ts new file mode 100644 index 00000000..b291c5f3 --- /dev/null +++ b/packages/proto-defs/src/oidb-actions/sys-faces.ts @@ -0,0 +1,61 @@ +// 0x9154_1 — system face / emoji catalog (sysface) protobuf shapes. +// +// Mirrors Lagrange.Core's FetchFullSysFacesService response: one round-trip +// returns every pack — common faces, "big"/super animated faces, and the +// magic-face pack. Each emoji carries its `aniSticker*` metadata, which the +// send path uses to pick the right wire encoding for a face id (classic +// FaceElem vs CommonElem 37/33). See protocol/oidb-services/sys-faces. + +import type { pb, pb_repeated, int_32 } from '@snowluma/proton'; + +export interface OidbFaceResourceUrl { + baseUrl?: pb<1, string>; + advUrl?: pb<2, string>; +} + +export interface OidbFaceEmoji { + qSid?: pb<1, string>; + qDes?: pb<2, string>; + emCode?: pb<3, string>; + qCid?: pb<4, int_32>; + aniStickerType?: pb<5, int_32>; + aniStickerPackId?: pb<6, int_32>; + aniStickerId?: pb<7, int_32>; + url?: pb<8, OidbFaceResourceUrl>; + emojiNameAlias?: pb_repeated<9, string>; + unknown10?: pb<10, int_32>; + aniStickerWidth?: pb<13, int_32>; + aniStickerHeight?: pb<14, int_32>; +} + +export interface OidbFaceEmojiList { + emojiPackName?: pb<1, string>; + emojiDetail?: pb_repeated<2, OidbFaceEmoji>; +} + +export interface OidbFaceContent { + emojiList?: pb_repeated<1, OidbFaceEmojiList>; + resourceUrl?: pb<2, OidbFaceResourceUrl>; +} + +export interface OidbFaceMagicContentList { + emojiList?: pb_repeated<2, OidbFaceEmoji>; +} + +export interface OidbFaceMagicContent { + field1?: pb<1, OidbFaceMagicContentList>; + resourceUrl?: pb<2, OidbFaceResourceUrl>; +} + +export interface OidbFetchSysFacesReq { + field1?: pb<1, int_32>; + field2?: pb<2, int_32>; + field3?: pb<3, string>; +} + +export interface OidbFetchSysFacesResp { + field1?: pb<1, int_32>; + commonFace?: pb<2, OidbFaceContent>; + specialBigFace?: pb<3, OidbFaceContent>; + specialMagicFace?: pb<4, OidbFaceMagicContent>; +} diff --git a/packages/protocol/src/element-builder.ts b/packages/protocol/src/element-builder.ts index dbc36354..2b28ffb7 100644 --- a/packages/protocol/src/element-builder.ts +++ b/packages/protocol/src/element-builder.ts @@ -2,11 +2,12 @@ import type { MarkdownData, MentionExtraSend, } from '@snowluma/proto-defs/action'; -import type { Elem, GroupFileExtra, MarketFacePbReserve } from '@snowluma/proto-defs/element'; +import type { Elem, GroupFileExtra, MarketFacePbReserve, 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 { uploadImageMsgInfo } from './highway/image-upload'; import { hexToBytes } from './highway/pipeline'; @@ -39,10 +40,45 @@ function makeTextElem(text: string): ProtoElem { }; } -function makeFaceElem(faceId: number): ProtoElem { - return { - face: { index: faceId }, - }; +// 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 +function makeFaceElem(faceId: number, ctx?: SendContext): ProtoElem { + // Keep the catalog warm so subsequent super-face sends are classified even if + // this one raced ahead of the first fetch. + if (ctx) sysFaceStore.ensureWarm(ctx.bridge); + + const wire = 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 { @@ -414,7 +450,7 @@ export async function buildSendElems(elements: MessageElement[], ctx?: SendConte break; case 'face': - if (elem.faceId !== undefined) result.push(makeFaceElem(elem.faceId)); + if (elem.faceId !== undefined) result.push(makeFaceElem(elem.faceId, ctx)); break; case 'mface': diff --git a/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts new file mode 100644 index 00000000..6f38d680 --- /dev/null +++ b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts @@ -0,0 +1,125 @@ +// 0x9154_1 — fetch the bot's system face / emoji catalog. +// +// Mirrors Lagrange.Core's `FetchFullSysFacesService`. One server round-trip +// returns the entire pack list — common faces, "big"/super faces (the giant +// animated emoji), and the magic-face pack. The send path uses each emoji's +// `aniSticker*` metadata to pick the right wire encoding for a face id (see +// element-builder's makeFaceElem + sys-face-store). + +import { protobuf_decode, protobuf_encode } from '@snowluma/proton'; +import type { OidbBase } from '@snowluma/proto-defs/oidb'; +import type { + OidbFaceEmoji, + OidbFetchSysFacesReq, + OidbFetchSysFacesResp, +} from '@snowluma/proto-defs/oidb-actions/sys-faces'; +import { invokeOidb, type OidbSender } from '../../oidb-service'; + +/** A single system face / emoji. Field names match Lagrange's `SysFaceEntry`; + * `qSid` is the numeric face ID as a string. */ +export interface SysFaceEntry { + qSid: string; + qDes: string; + emCode: string; + qCid: number | null; + aniStickerType: number | null; + aniStickerPackId: number | null; + aniStickerId: number | null; + url: string | null; + emojiNameAlias: string[]; + aniStickerWidth: number | null; + aniStickerHeight: number | null; +} + +/** One named pack of system faces (e.g. "经典", "MagicFace"). */ +export interface SysFacePackEntry { + packName: string; + emojis: SysFaceEntry[]; +} + +function emojiToEntry(e: OidbFaceEmoji): SysFaceEntry { + return { + qSid: e.qSid ?? '', + qDes: e.qDes ?? '', + emCode: e.emCode ?? '', + qCid: e.qCid ?? null, + aniStickerType: e.aniStickerType ?? null, + aniStickerPackId: e.aniStickerPackId ?? null, + aniStickerId: e.aniStickerId ?? null, + url: e.url?.baseUrl ?? null, + emojiNameAlias: e.emojiNameAlias ?? [], + aniStickerWidth: e.aniStickerWidth ?? null, + aniStickerHeight: e.aniStickerHeight ?? null, + }; +} + +export namespace FetchSysFaces { + export const command = 0x9154; + export const subCommand = 1; + + export type Params = Record; + export type Deps = OidbSender; + + export const serialize = (_ctx: Deps, _p: Params): OidbFetchSysFacesReq => ({ + field1: 0, + field2: 7, + field3: '0', + }); + + export const deserialize = (_ctx: Deps, body: OidbFetchSysFacesResp): SysFacePackEntry[] => { + const packs: SysFacePackEntry[] = []; + + // common + special-big share the same content shape. + for (const content of [body.commonFace, body.specialBigFace]) { + for (const list of content?.emojiList ?? []) { + packs.push({ + packName: list.emojiPackName ?? '', + emojis: (list.emojiDetail ?? []).map(emojiToEntry), + }); + } + } + + // Magic faces arrive as a single un-named bundle — Lagrange tags it + // "MagicFace" client-side, so we match for parity. + const magicEmojis = body.specialMagicFace?.field1?.emojiList ?? []; + if (magicEmojis.length > 0) { + packs.push({ packName: 'MagicFace', emojis: magicEmojis.map(emojiToEntry) }); + } + + return packs; + }; + + export const encode = (env: OidbBase): Uint8Array => + protobuf_encode>(env); + + export const decode = (bytes: Uint8Array): OidbBase => + protobuf_decode>(bytes); + + export const invoke = (deps: Deps, params: Params = {}): Promise => + invokeOidb(deps, FetchSysFaces, params); +} + +/** Walk a pack list to find an emoji by its numeric face ID, or null. */ +export function findFaceEntity(packs: SysFacePackEntry[], faceId: number): SysFaceEntry | null { + const idStr = String(faceId); + for (const pack of packs) { + for (const emoji of pack.emojis) { + if (emoji.qSid === idStr) return emoji; + } + } + return null; +} + +/** True when `faceId` is an animated "super face" — has both aniStickerType + * and aniStickerPackId set, and is NOT the (1,1) pack (the regular static + * emojis). Matches Lagrange's `GetUniqueSuperQSids` filter. Super faces ride + * CommonElem serviceType 37 (QFaceExtra); the (1,1) ones ride serviceType 33. */ +export function isSuperFaceEntry(emoji: SysFaceEntry): boolean { + if (emoji.aniStickerType == null || emoji.aniStickerPackId == null) return false; + return !(emoji.aniStickerType === 1 && emoji.aniStickerPackId === 1); +} + +export function isSuperFaceId(packs: SysFacePackEntry[], faceId: number): boolean { + const emoji = findFaceEntity(packs, faceId); + return emoji !== null && isSuperFaceEntry(emoji); +} diff --git a/packages/protocol/src/sys-face-store.ts b/packages/protocol/src/sys-face-store.ts new file mode 100644 index 00000000..5e92853e --- /dev/null +++ b/packages/protocol/src/sys-face-store.ts @@ -0,0 +1,93 @@ +// Process-wide cache of QQ's system-face catalog (fetched once via 0x9154_1), +// used by the send path to pick a face id's wire encoding. The catalog is the +// same for every account, so a single shared store is fetched lazily and reused. +// +// `classify` is synchronous (the element builder is sync); a face sent before +// the catalog is warm falls back to an id-range guess. `ensureWarm` kicks off +// the one-shot fetch — call it proactively at login so the first super-face +// send is already classified. + +import { createLogger } from '@snowluma/common/logger'; +import { + FetchSysFaces, + isSuperFaceEntry, + type SysFaceEntry, + type SysFacePackEntry, +} from './oidb-services/sys-faces/fetch-sys-faces'; +import type { OidbSender } from './oidb-service'; + +const log = createLogger('SysFace'); + +/** Wire encoding a face id maps to. `classic` → legacy FaceElem; `small` → + * CommonElem serviceType 33 (QSmallFaceExtra); `super` → CommonElem + * serviceType 37 (QFaceExtra) for animated/super faces. */ +export type FaceWire = + | { kind: 'classic' } + | { kind: 'small' } + | { kind: 'super'; packId: string; stickerId: string; stickerType: number }; + +/** Pure classification: a super face (per the catalog entry) → `super` with its + * pack/sticker ids; otherwise an id-range guess (`< 260` = classic, else + * small). Used both warm (entry from the catalog) and cold (entry undefined). */ +export function faceWireFor(entry: SysFaceEntry | null | undefined, faceId: number): FaceWire { + if (entry && isSuperFaceEntry(entry)) { + return { + kind: 'super', + packId: String(entry.aniStickerPackId ?? 1), + stickerId: String(entry.aniStickerId ?? 0), + stickerType: entry.aniStickerType ?? 0, + }; + } + return faceId < 260 ? { kind: 'classic' } : { kind: 'small' }; +} + +const RETRY_COOLDOWN_MS = 30_000; + +class SysFaceStore { + private byId: Map | null = null; + private inflight: Promise | null = null; + private lastFailedAt = 0; + + /** Index a fetched catalog (also used by tests to seed without a network). */ + load(packs: SysFacePackEntry[]): void { + this.byId = buildIndex(packs); + } + + /** Synchronous classification. Falls back to an id-range guess when the + * catalog isn't warm yet or the id is unknown. */ + classify(faceId: number): FaceWire { + return faceWireFor(this.byId?.get(String(faceId)), faceId); + } + + /** Fire-and-forget one-shot warm. Coalesces concurrent callers; backs off + * briefly after a failure so a flaky fetch isn't hammered per message. */ + ensureWarm(sender: OidbSender): void { + if (this.byId || this.inflight) return; + if (Date.now() - this.lastFailedAt < RETRY_COOLDOWN_MS) return; + this.inflight = FetchSysFaces.invoke(sender) + .then((packs) => { + this.load(packs); + log.info('system face catalog loaded: %d faces', this.byId?.size ?? 0); + }) + .catch((err) => { + this.lastFailedAt = Date.now(); + log.warn('failed to load system face catalog: %s', err instanceof Error ? err.message : String(err)); + }) + .finally(() => { + this.inflight = null; + }); + } +} + +function buildIndex(packs: SysFacePackEntry[]): Map { + const map = new Map(); + for (const pack of packs) { + for (const emoji of pack.emojis) { + if (emoji.qSid) map.set(emoji.qSid, emoji); + } + } + return map; +} + +/** Shared, process-wide catalog (the face set is account-independent). */ +export const sysFaceStore = new SysFaceStore(); diff --git a/packages/protocol/tests/sys-faces.test.ts b/packages/protocol/tests/sys-faces.test.ts new file mode 100644 index 00000000..6a92661a --- /dev/null +++ b/packages/protocol/tests/sys-faces.test.ts @@ -0,0 +1,104 @@ +import { describe, it, expect } from 'vitest'; +import { protobuf_decode } from '@snowluma/proton'; +import type { QFaceExtra, QSmallFaceExtra } from '@snowluma/proto-defs/element'; +import { + FetchSysFaces, + findFaceEntity, + isSuperFaceEntry, + isSuperFaceId, + type SysFaceEntry, + type SysFacePackEntry, +} from '../src/oidb-services/sys-faces/fetch-sys-faces'; +import { faceWireFor, sysFaceStore } from '../src/sys-face-store'; +import { buildSendElems } from '../src/element-builder'; + +function entry(qSid: string, aniStickerType: number | null, aniStickerPackId: number | null, aniStickerId: number | null): SysFaceEntry { + return { + qSid, qDes: '', emCode: '', qCid: null, + aniStickerType, aniStickerPackId, aniStickerId, + url: null, emojiNameAlias: [], aniStickerWidth: null, aniStickerHeight: null, + }; +} + +// 392 is a real non-(1,1) super face; 424 is a real (1,1) "new small" face. +const CATALOG: SysFacePackEntry[] = [ + { packName: '经典', emojis: [entry('14', null, null, null)] }, + { packName: '超级表情', emojis: [ + entry('392', 3, 2, 38), // super → CommonElem 37 + entry('424', 1, 1, 52), // (1,1) → small → CommonElem 33 + entry('358', 2, 1, 33), // super (packId 1 but type 2) → CommonElem 37 + ] }, +]; + +describe('isSuperFaceEntry / isSuperFaceId — the (1,1) rule', () => { + it('treats only non-(1,1) aniSticker faces as super', () => { + expect(isSuperFaceEntry(entry('x', 3, 2, 1))).toBe(true); + expect(isSuperFaceEntry(entry('x', 2, 1, 1))).toBe(true); // type≠1 + expect(isSuperFaceEntry(entry('x', 1, 2, 1))).toBe(true); // pack≠1 + expect(isSuperFaceEntry(entry('x', 1, 1, 52))).toBe(false); // the (1,1) pack + expect(isSuperFaceEntry(entry('x', null, null, null))).toBe(false); // not aniSticker + }); + + it('isSuperFaceId walks the packs by id', () => { + expect(isSuperFaceId(CATALOG, 392)).toBe(true); + expect(isSuperFaceId(CATALOG, 424)).toBe(false); + expect(isSuperFaceId(CATALOG, 14)).toBe(false); + expect(isSuperFaceId(CATALOG, 99999)).toBe(false); // unknown + }); + + it('findFaceEntity returns the matching emoji or null', () => { + expect(findFaceEntity(CATALOG, 392)?.qSid).toBe('392'); + expect(findFaceEntity(CATALOG, 99999)).toBeNull(); + }); +}); + +describe('faceWireFor — classification', () => { + it('super face → super wire with pack/sticker ids', () => { + expect(faceWireFor(entry('392', 3, 2, 38), 392)).toEqual({ + kind: 'super', packId: '2', stickerId: '38', stickerType: 3, + }); + }); + it('(1,1) face → small/classic by id range, not super', () => { + expect(faceWireFor(entry('424', 1, 1, 52), 424)).toEqual({ kind: 'small' }); + }); + it('cold (no catalog entry) → id-range guess', () => { + expect(faceWireFor(undefined, 14)).toEqual({ kind: 'classic' }); // < 260 + expect(faceWireFor(undefined, 424)).toEqual({ kind: 'small' }); // ≥ 260 + expect(faceWireFor(null, 100)).toEqual({ kind: 'classic' }); + }); +}); + +describe('FetchSysFaces.deserialize', () => { + it('flattens common + big + magic packs', () => { + const packs = FetchSysFaces.deserialize({} as never, { + commonFace: { emojiList: [{ emojiPackName: '经典', emojiDetail: [{ qSid: '14' }] }] }, + specialBigFace: { emojiList: [{ emojiPackName: '超级', emojiDetail: [{ qSid: '392', aniStickerType: 3, aniStickerPackId: 2 }] }] }, + specialMagicFace: { field1: { emojiList: [{ qSid: '999' }] } }, + } as never); + expect(packs.map((p) => p.packName)).toEqual(['经典', '超级', 'MagicFace']); + expect(packs[1].emojis[0].aniStickerType).toBe(3); + }); +}); + +describe('makeFaceElem (via buildSendElems) — three-way wire encoding', () => { + const ctx = { bridge: {} as never }; + + it('encodes each face id by its catalog classification', async () => { + sysFaceStore.load(CATALOG); // warm → ensureWarm no-ops, classify uses the catalog + + const [superElem] = await buildSendElems([{ type: 'face', faceId: 392 }], ctx); + expect(superElem.commonElem?.serviceType).toBe(37); + const big = protobuf_decode(superElem.commonElem!.pbElem!); + expect(big.qsid).toBe(392); + expect(big.packId).toBe('2'); + expect(big.stickerId).toBe('38'); + + const [smallElem] = await buildSendElems([{ type: 'face', faceId: 424 }], ctx); + expect(smallElem.commonElem?.serviceType).toBe(33); + const small = protobuf_decode(smallElem.commonElem!.pbElem!); + expect(small.faceId).toBe(424); + + const [classicElem] = await buildSendElems([{ type: 'face', faceId: 14 }], ctx); + expect(classicElem.face?.index).toBe(14); + }); +});