@zhin.js/adapter-icqq 1.0.70 → 1.1.0

package/lib/icqq-inbound.js

@@ -0,0 +1,651 @@
+/**
+ * icqq 入站事件归一化（post_type / message_type / message 段）
+ */
+import { toCanonicalSegments } from "zhin.js";
+import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
+import { extractForwardResidFromJsonElement } from "./forward-msg.js";
+/**
+ * Resolve ICQQ's opaque protobuf media references while the endpoint-owned
+ * native client is still available. Resolution failure preserves the opaque
+ * reference, so canonical ingress stays truthful and can report unsupported
+ * media instead of inventing a URL.
+ */
+export async function resolveIcqqInboundMedia(elements, resolver) {
+    if (!elements?.length)
+        return;
+    await Promise.all(elements.map(async (element) => {
+        if (!element || typeof element !== "object")
+            return;
+        if (typeof element.url === "string" && element.url)
+            return;
+        try {
+            const url = element.type === "record" || element.type === "audio"
+                ? await resolver.getPttUrl(element)
+                : element.type === "video"
+                    ? await resolver.getVideoUrl(element)
+                    : undefined;
+            if (typeof url === "string" && url)
+                element.url = url;
+        }
+        catch {
+            // The original platform reference remains the canonical fallback.
+        }
+    }));
+}
+const DEDUPE_TTL_MS = 120_000;
+const ICQQ_GROUP_ROLES = new Set(["owner", "admin", "member"]);
+/** 从 sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
+export function parseIcqqSenderGroupRole(sender) {
+    const raw = sender?.role;
+    if (typeof raw !== "string" || !raw.trim())
+        return undefined;
+    const role = raw.trim().toLowerCase();
+    return ICQQ_GROUP_ROLES.has(role) ? role : undefined;
+}
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export function isIcqqBotMentioned(input) {
+    const uin = String(input.uin ?? "").trim();
+    if (!uin)
+        return false;
+    for (const seg of input.content ?? []) {
+        if (!seg || (seg.type !== "at" && seg.type !== "mention"))
+            continue;
+        const data = (seg.data ?? {});
+        const target = String(data.qq ?? data.user_id ?? data.id ?? data.target ?? "").trim();
+        if (target && target !== "all" && Number(target) === Number(uin)) {
+            return true;
+        }
+    }
+    const raw = input.rawMessage ?? "";
+    if (!raw)
+        return false;
+    const escaped = uin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // OneBot CQ 码 `[CQ:at,qq=uin]`；QQ 频道 markdown `<@!uin>`
+    return new RegExp(`\\[CQ:at,qq=${escaped}\\]`, "u").test(raw)
+        || new RegExp(`<@!?${escaped}>`, "u").test(raw);
+}
+const MESSAGE_POST_TYPES = new Set(["message"]);
+function isMessagePostType(postType) {
+    if (typeof postType !== "string" || postType === "")
+        return false;
+    if (MESSAGE_POST_TYPES.has(postType))
+        return true;
+    // 如 message.private / message.group
+    return postType.startsWith("message.");
+}
+/** 从事件壳中取出 OneBot/icqq 载荷（兼容 data 嵌套或字段在根级） */
+export function unwrapIcqqEventPayload(event) {
+    const nested = event.data;
+    if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+        const d = nested;
+        if (isRecognizedIcqqPayload(d)) {
+            return nested;
+        }
+        for (const key of ["data", "detail", "payload", "event"]) {
+            const inner = d[key];
+            if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+                return inner;
+            }
+        }
+    }
+    const { id: _id, event: _ev, data: _data, ok: _ok, ...rest } = event;
+    if (isRecognizedIcqqPayload(rest)) {
+        return rest;
+    }
+    return nested;
+}
+function isRecognizedIcqqPayload(d) {
+    const pt = d.post_type;
+    if (typeof pt === "string") {
+        if (isMessagePostType(pt) ||
+            pt === "notice" ||
+            pt === "request" ||
+            pt === "meta_event" ||
+            pt.startsWith("notice.") ||
+            pt.startsWith("request.") ||
+            pt.startsWith("system.")) {
+            return true;
+        }
+    }
+    return (d.message_type != null ||
+        d.raw_message != null ||
+        d.message != null ||
+        d.type === "group" ||
+        d.type === "private" ||
+        d.notice_type != null ||
+        d.request_type != null ||
+        d.meta_event_type != null);
+}
+export function resolveIcqqInboundUserId(data) {
+    const sender = data.sender;
+    if (sender && typeof sender === "object" && !Array.isArray(sender)) {
+        const suid = sender.user_id;
+        if (suid != null)
+            return Number(suid);
+    }
+    if (data.user_id != null)
+        return Number(data.user_id);
+    if (data.from_id != null)
+        return Number(data.from_id);
+    return undefined;
+}
+export function isIcqqMessagePostType(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    if (isMessagePostType(d.post_type))
+        return true;
+    // 其它 post_type（notice/request 等）明确排除
+    if (d.post_type != null && d.post_type !== "")
+        return false;
+    const hasBody = typeof d.raw_message === "string" ||
+        Array.isArray(d.message) ||
+        typeof d.message_type === "string" ||
+        d.type === "group" ||
+        d.type === "private";
+    return hasBody && resolveIcqqInboundUserId(d) != null;
+}
+export function shouldSkipSelfInboundMessage(data) {
+    if (data.self_id == null || data.user_id == null)
+        return false;
+    return Number(data.self_id) === Number(data.user_id);
+}
+/** 群临时会话私聊：icqq message_type=private & sub_type=group */
+export function isIcqqGroupTempPrivateMessage(data) {
+    const messageType = data.message_type ??
+        (data.type === "group" || data.type === "private" ? data.type : undefined);
+    if (messageType !== "private")
+        return false;
+    if (data.sub_type === "group")
+        return true;
+    const groupId = data.sender?.group_id;
+    return typeof groupId === "number" && groupId > 0;
+}
+export function resolveChannelFromIcqqMessage(data) {
+    if (isIcqqGroupTempPrivateMessage(data)) {
+        const groupId = data.sender?.group_id ?? data.group_id;
+        const userId = resolveIcqqInboundUserId(data);
+        if (groupId != null && userId != null) {
+            return {
+                channelType: "private",
+                channelId: String(userId),
+                channelParentGroupId: String(groupId),
+            };
+        }
+    }
+    const messageType = data.message_type ??
+        (data.type === "group" || data.type === "private" ? data.type : undefined);
+    if (messageType === "group" || data.group_id != null) {
+        return {
+            channelType: "group",
+            channelId: String(data.group_id ?? data.from_id ?? data.user_id),
+        };
+    }
+    return {
+        channelType: "private",
+        channelId: String(data.from_id ?? data.user_id),
+    };
+}
+export function resolveIcqqInboundMessageId(data, channelId) {
+    if (data.message_id != null && String(data.message_id) !== "") {
+        return { id: String(data.message_id), source: "message_id" };
+    }
+    if (data.msg_id != null && String(data.msg_id) !== "") {
+        return { id: String(data.msg_id), source: "msg_id" };
+    }
+    if (data.seq != null && String(data.seq) !== "") {
+        return { id: String(data.seq), source: "seq" };
+    }
+    const uid = resolveIcqqInboundUserId(data) ?? 0;
+    return {
+        id: `${data.time}_${uid}_${channelId}`,
+        source: "synthetic",
+    };
+}
+export function icqqElementsToSegments(elements) {
+    if (!elements?.length)
+        return null;
+    const out = [];
+    for (const el of elements) {
+        if (!el || typeof el !== "object")
+            continue;
+        const type = el.type;
+        switch (type) {
+            case "text":
+                if (el.text != null && el.text !== "") {
+                    out.push({ type: "text", data: { text: String(el.text) } });
+                }
+                break;
+            case "at": {
+                const atId = String(el.qq ?? el.user_id ?? "");
+                const name = typeof el.name === "string"
+                    ? el.name
+                    : typeof el.nickname === "string"
+                        ? el.nickname
+                        : undefined;
+                out.push({
+                    type: "at",
+                    data: name
+                        ? { qq: atId, user_id: atId, id: atId, name }
+                        : { qq: atId, user_id: atId, id: atId },
+                });
+                break;
+            }
+            case "face":
+                out.push({ type: "face", data: { id: Number(el.id) } });
+                break;
+            case "image": {
+                const value = String(el.url ?? el.file ?? "");
+                if (!value)
+                    break;
+                out.push({
+                    type: "image",
+                    data: { media: icqqMediaRefFromElement(value, el) },
+                });
+                break;
+            }
+            case "flash": {
+                const value = String(el.url ?? el.file ?? "");
+                if (!value)
+                    break;
+                out.push({
+                    type: "image",
+                    data: { media: icqqMediaRefFromElement(value, el), flash: true },
+                });
+                break;
+            }
+            case "forward": {
+                const forwardResid = String(el.id ?? el.resid ?? el.res_id ?? el.file ?? "").trim();
+                if (forwardResid) {
+                    out.push({
+                        type: "forward",
+                        data: { id: forwardResid, resid: forwardResid },
+                    });
+                }
+                else {
+                    out.push({ type: "text", data: { text: "[聊天记录]" } });
+                }
+                break;
+            }
+            case "light_app":
+            case "xml": {
+                const forwardResid = extractForwardResidFromJsonElement(el);
+                if (forwardResid) {
+                    out.push({
+                        type: "forward",
+                        data: { id: forwardResid, resid: forwardResid },
+                    });
+                }
+                else if (el.text != null && el.text !== "") {
+                    out.push({ type: "text", data: { text: String(el.text) } });
+                }
+                else {
+                    out.push({ type: "text", data: { text: "[聊天记录]" } });
+                }
+                break;
+            }
+            case "reply": {
+                const replyId = String(el.id ?? el.message_id ?? "");
+                if (replyId) {
+                    out.push({
+                        type: "reply",
+                        data: { id: replyId, message_id: replyId },
+                    });
+                }
+                break;
+            }
+            case "json": {
+                const forwardResid = extractForwardResidFromJsonElement(el);
+                if (forwardResid) {
+                    out.push({
+                        type: "forward",
+                        data: { id: forwardResid, resid: forwardResid },
+                    });
+                    break;
+                }
+                const replyFromJson = resolveReplyIdFromJsonElement(el);
+                if (replyFromJson) {
+                    out.push({
+                        type: "reply",
+                        data: { id: replyFromJson, message_id: replyFromJson },
+                    });
+                }
+                else if (el.text != null && el.text !== "") {
+                    out.push({ type: "text", data: { text: String(el.text) } });
+                }
+                break;
+            }
+            case "record":
+            case "audio": {
+                const value = String(el.url ?? el.file ?? "");
+                if (!value)
+                    break;
+                out.push({
+                    type: "audio",
+                    data: {
+                        media: icqqMediaRefFromElement(value, el),
+                        ...(typeof el.seconds === "number" ? { duration: el.seconds } : {}),
+                    },
+                });
+                break;
+            }
+            case "video": {
+                const value = String(el.url ?? el.file ?? "");
+                if (!value)
+                    break;
+                out.push({
+                    type: "video",
+                    data: {
+                        media: icqqMediaRefFromElement(value, el),
+                        ...(typeof el.seconds === "number" ? { duration: el.seconds } : {}),
+                    },
+                });
+                break;
+            }
+            case "file": {
+                const value = String(el.url ?? el.file ?? el.fid ?? "");
+                if (!value)
+                    break;
+                const name = typeof el.name === "string" && el.name ? el.name : undefined;
+                out.push({
+                    type: "file",
+                    data: {
+                        media: icqqMediaRefFromElement(value, el),
+                        ...(name ? { name } : {}),
+                    },
+                });
+                break;
+            }
+            default:
+                if (el.text != null && el.text !== "") {
+                    out.push({ type: "text", data: { text: String(el.text) } });
+                }
+                break;
+        }
+    }
+    return out.length ? out : null;
+}
+function icqqMediaRefFromElement(value, element) {
+    const media = icqqMediaRefFromString(value);
+    const fileName = typeof element.name === "string" && element.name
+        ? element.name
+        : undefined;
+    const size = typeof element.size === "number" && Number.isFinite(element.size)
+        ? element.size
+        : undefined;
+    return {
+        ...media,
+        ...(fileName ? { file_name: fileName } : {}),
+        ...(size != null ? { size } : {}),
+    };
+}
+function resolveReplyIdFromJsonElement(el) {
+    let payload = el.data ?? el;
+    if (typeof payload === "string") {
+        try {
+            payload = JSON.parse(payload);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const record = payload;
+    const refer = record.msgRefer ??
+        record.reply ??
+        record.resid ??
+        record.message_id ??
+        record.id;
+    if (refer && typeof refer === "object") {
+        const r = refer;
+        const id = r.msgId ?? r.message_id ?? r.id ?? r.msg_id;
+        if (id != null && String(id))
+            return String(id);
+    }
+    if (typeof refer === "string" && refer)
+        return refer;
+    if (typeof refer === "number")
+        return String(refer);
+    return undefined;
+}
+const MAX_SOURCE_WALK_DEPTH = 10;
+function icqqSourceMessageBody(s) {
+    return s.message;
+}
+function icqqSourceHasBody(s) {
+    const body = icqqSourceMessageBody(s);
+    if (Array.isArray(body) && body.length > 0)
+        return true;
+    if (typeof body === "string" && body.trim().length > 0)
+        return true;
+    return typeof s.raw_message === "string" && s.raw_message.length > 0;
+}
+function looksLikeIcqqMessageSource(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const r = value;
+    // 整条入站事件也有 message_id，不能与 oicq Message#source 混淆
+    if (r.post_type != null || r.message_type != null)
+        return false;
+    const s = value;
+    if (!icqqSourceHasBody(s))
+        return false;
+    return !!resolveQuoteIdFromIcqqSource(value);
+}
+/** 载荷可能把 source 嵌在 data / event 等字段，深度查找 */
+export function findIcqqNestedMessageSource(root, maxDepth = MAX_SOURCE_WALK_DEPTH) {
+    const seen = new Set();
+    function walk(node, depth) {
+        if (depth > maxDepth || node == null)
+            return undefined;
+        if (typeof node !== "object")
+            return undefined;
+        if (seen.has(node))
+            return undefined;
+        seen.add(node);
+        if (looksLikeIcqqMessageSource(node)) {
+            return node;
+        }
+        const record = node;
+        if (record.source && looksLikeIcqqMessageSource(record.source)) {
+            return record.source;
+        }
+        for (const value of Object.values(record)) {
+            if (value && typeof value === "object") {
+                const hit = walk(value, depth + 1);
+                if (hit)
+                    return hit;
+            }
+        }
+        return undefined;
+    }
+    return walk(root, 0);
+}
+/** 从 oicq MessageEvent.source 解析被引用消息的 message_id */
+export function resolveQuoteIdFromIcqqSource(source) {
+    if (!source || typeof source !== "object")
+        return undefined;
+    const s = source;
+    if (s.message_id != null && String(s.message_id).trim()) {
+        return String(s.message_id).trim();
+    }
+    if (s.msg_id != null && String(s.msg_id).trim()) {
+        return String(s.msg_id).trim();
+    }
+    // NT 引用源常仅有 seq/rand，无 message_id
+    if (s.seq != null && String(s.seq) !== "") {
+        const seq = String(s.seq);
+        if (s.rand != null && String(s.rand) !== "") {
+            return `${seq}:${s.rand}`;
+        }
+        return seq;
+    }
+    return undefined;
+}
+function icqqSourceToContentSegments(s) {
+    const body = icqqSourceMessageBody(s);
+    if (Array.isArray(body) && body.length) {
+        return icqqElementsToSegments(body) ?? [];
+    }
+    if (typeof body === "string" && body.trim()) {
+        return [{ type: "text", data: { text: body.trim() } }];
+    }
+    if (typeof s.raw_message === "string" && s.raw_message) {
+        return parseCqMessage(s.raw_message);
+    }
+    return [];
+}
+/** Convert an ICQQ source into the adapter-local lookup payload. */
+export function messageLookupFromIcqqSource(source) {
+    if (!source || typeof source !== "object")
+        return null;
+    const s = source;
+    const body = icqqSourceMessageBody(s);
+    const content = icqqSourceToContentSegments(s);
+    const messageId = resolveQuoteIdFromIcqqSource(source);
+    if (!messageId && !content.length)
+        return null;
+    const senderRaw = s.sender;
+    const senderFromUserId = s.user_id != null
+        ? { id: String(s.user_id), name: "" }
+        : undefined;
+    return {
+        messageId: messageId ?? `seq:${s.seq ?? 0}:${s.rand ?? 0}`,
+        sender: senderRaw
+            ? {
+                id: String(senderRaw.user_id ?? ""),
+                name: String(senderRaw.nickname ?? senderRaw.card ?? ""),
+            }
+            : senderFromUserId,
+        content,
+        raw: typeof s.raw_message === "string"
+            ? s.raw_message
+            : typeof body === "string"
+                ? body
+                : undefined,
+        time: typeof s.time === "number" ? s.time : undefined,
+    };
+}
+/** 从事件顶层字段解析引用 message_id（与 message 段互补） */
+export function resolveIcqqQuoteIdFromEvent(data) {
+    const fromSource = resolveQuoteIdFromIcqqSource(data.source) ??
+        resolveQuoteIdFromIcqqSource(findIcqqNestedMessageSource(data));
+    if (fromSource)
+        return fromSource;
+    const ext = data;
+    const candidates = [
+        ext.reply,
+        ext.quoted_message_id,
+        ext.quote_message_id,
+        ext.source_message_id,
+    ];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.trim())
+            return c.trim();
+        if (typeof c === "number")
+            return String(c);
+        if (c && typeof c === "object") {
+            const r = c;
+            const id = r.id ?? r.message_id ?? r.msg_id ?? r.msgId;
+            if (id != null && String(id))
+                return String(id);
+        }
+    }
+    return undefined;
+}
+function mergeReplyFromRawMessage(content, rawMessage) {
+    if (!rawMessage || quoteIdFromSegments(content))
+        return content;
+    const fromRaw = parseCqMessage(rawMessage);
+    const quoteFromRaw = quoteIdFromSegments(fromRaw);
+    if (!quoteFromRaw)
+        return content;
+    return [
+        { type: "reply", data: { message_id: quoteFromRaw } },
+        ...content.filter((s) => s.type !== "reply"),
+    ];
+}
+function mergeReplyFromSource(content, data) {
+    if (quoteIdFromSegments(content))
+        return content;
+    const quoteId = resolveQuoteIdFromIcqqSource(data.source) ??
+        resolveQuoteIdFromIcqqSource(findIcqqNestedMessageSource(data));
+    if (!quoteId)
+        return content;
+    return [
+        { type: "reply", data: { message_id: quoteId } },
+        ...content.filter((s) => s.type !== "reply"),
+    ];
+}
+function quoteIdFromSegments(content) {
+    const reply = content.find((item) => item.type === 'reply');
+    const value = reply?.data?.message_id ?? reply?.data?.id;
+    return value == null || !String(value).trim() ? undefined : String(value).trim();
+}
+export function resolveInboundContent(data) {
+    const fromElements = icqqElementsToSegments(data.message);
+    const raw = data.raw_message ?? "";
+    let content;
+    if (fromElements?.length) {
+        content = mergeReplyFromRawMessage(fromElements, raw);
+    }
+    else if (raw) {
+        content = parseCqMessage(raw);
+    }
+    else {
+        content = [{ type: "text", data: { text: "" } }];
+    }
+    return toCanonicalSegments(mergeReplyFromSource(content, data));
+}
+export function normalizeIcqqInboundMessage(data) {
+    if (!isIcqqMessagePostType(data))
+        return null;
+    const ext = data;
+    const userIdNum = resolveIcqqInboundUserId(ext);
+    if (userIdNum == null)
+        return null;
+    const { channelType, channelId, channelParentGroupId } = resolveChannelFromIcqqMessage(data);
+    const resolved = resolveIcqqInboundMessageId(data, channelId);
+    const nickname = data.sender?.nickname ?? data.nickname ?? String(userIdNum);
+    const senderRole = channelType === "group"
+        ? parseIcqqSenderGroupRole(data.sender)
+        : undefined;
+    const rawMessage = data.raw_message ?? "";
+    return {
+        messageId: resolved.id,
+        idSource: resolved.source,
+        channelType,
+        channelId,
+        channelParentGroupId,
+        userId: String(userIdNum),
+        nickname,
+        senderRole,
+        content: resolveInboundContent(data),
+        rawMessage,
+        timestampMs: data.time * 1000,
+        raw: data,
+    };
+}
+/** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
+export class InboundMessageDeduper {
+    seen = new Map();
+    shouldProcess(messageId) {
+        const now = Date.now();
+        for (const [id, t] of this.seen) {
+            if (now - t > DEDUPE_TTL_MS)
+                this.seen.delete(id);
+        }
+        if (this.seen.has(messageId))
+            return false;
+        this.seen.set(messageId, now);
+        return true;
+    }
+    clear() {
+        this.seen.clear();
+    }
+}

package/lib/icqq-inbox.d.ts

@@ -0,0 +1,25 @@
+import type { SystemMessage } from './types.js';
+/** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+export interface IcqqInboxBase {
+    readonly adapter: string;
+    readonly endpointKey: string;
+}
+/** post_type=request / request.* 判定（OneBot 事件壳）。 */
+export declare function isIcqqRequestPayload(payload: unknown): boolean;
+/** post_type=notice / notice.* 判定。 */
+export declare function isIcqqNoticePayload(payload: unknown): boolean;
+/**
+ * request 事件载荷 → unified_inbox_request 行。
+ * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。
+ */
+export declare function buildIcqqInboxRequestRow(payload: Record<string, unknown>, base: IcqqInboxBase): Record<string, unknown> | null;
+/**
+ * notice 事件载荷 → unified_inbox_notice 行。
+ * 事件本身无稳定 id，platform_notice_id 由 time + actor + type 合成（配合去重）。
+ */
+export declare function buildIcqqInboxNoticeRow(payload: Record<string, unknown>, base: IcqqInboxBase): Record<string, unknown> | null;
+/**
+ * GET_SYSTEM_MSG 返回项 → unified_inbox_request 行（启动时首次拉取）。
+ * friend 列表项 type 语义即好友请求；group 列表项 type 为 add/invite（记 sub_type）。
+ */
+export declare function buildIcqqSystemRequestRow(message: SystemMessage, kind: 'friend' | 'group', base: IcqqInboxBase): Record<string, unknown> | null;