@zhin.js/adapter-icqq 1.0.71 → 1.1.2

package/lib/forward-msg.d.ts

@@ -0,0 +1,6 @@
+import { type IcqqMessageElement } from "./icqq-inbound.js";
+import type { ForwardEntry } from '@zhin.js/im-contract';
+/** 从 QQ 合并转发 json 元素提取 resid */
+export declare function extractForwardResidFromJsonElement(el: IcqqMessageElement): string | undefined;
+/** Canonical merged-forward entries. Speakers are data actors, never LLM roles. */
+export declare function normalizeForwardMsgResponse(data: unknown): readonly ForwardEntry[];

package/lib/forward-msg.js

@@ -0,0 +1,107 @@
+import { icqqElementsToSegments, } from "./icqq-inbound.js";
+import { toCanonicalSegments } from '@zhin.js/core';
+const RESID_IN_XML_RE = /(?:m_resid|resid|fileid|res_id)=["']?([A-Za-z0-9+/=_.-]{8,})/i;
+function parseJsonPayload(raw) {
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        return raw;
+    }
+    if (typeof raw !== "string" || !raw.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+/** 从 QQ 合并转发 json 元素提取 resid */
+export function extractForwardResidFromJsonElement(el) {
+    const record = parseJsonPayload(el.data) ??
+        parseJsonPayload(el.text) ??
+        parseJsonPayload(el);
+    if (!record) {
+        const text = typeof el.text === "string" ? el.text : "";
+        const m = text.match(RESID_IN_XML_RE);
+        return m?.[1]?.trim();
+    }
+    const bytes = record.bytesData ?? record.bytes_data ?? record.bytes;
+    if (typeof bytes === "string" && bytes.trim()) {
+        const inner = parseJsonPayload(bytes);
+        if (inner) {
+            const nested = extractForwardResidFromJsonElement({
+                type: "json",
+                data: inner,
+            });
+            if (nested)
+                return nested;
+        }
+        const m = bytes.match(RESID_IN_XML_RE);
+        if (m?.[1])
+            return m[1].trim();
+    }
+    const app = String(record.app ?? record.App ?? "");
+    if (app.includes("multimsg") || app.includes("MultiMsg")) {
+        const meta = record.meta;
+        const detail = meta?.detail;
+        const resid = detail?.resid ?? detail?.ResID ?? detail?.resId;
+        if (resid != null && String(resid).trim())
+            return String(resid).trim();
+    }
+    const prompt = record.prompt;
+    if (prompt) {
+        const m = prompt.match(RESID_IN_XML_RE);
+        if (m?.[1])
+            return m[1].trim();
+    }
+    const direct = record.resid ?? record.m_resid ?? record.fileid;
+    if (direct != null && String(direct).trim())
+        return String(direct).trim();
+    return undefined;
+}
+/** Canonical merged-forward entries. Speakers are data actors, never LLM roles. */
+export function normalizeForwardMsgResponse(data) {
+    const root = data && typeof data === 'object' && !Array.isArray(data)
+        ? data
+        : undefined;
+    const list = Array.isArray(data)
+        ? data
+        : Array.isArray(root?.messages) ? root.messages
+            : Array.isArray(root?.msgList) ? root.msgList
+                : Array.isArray(root?.msg_list) ? root.msg_list
+                    : Array.isArray(root?.message) ? root.message
+                        : [];
+    return Object.freeze(list.flatMap((item) => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const row = item;
+        const sender = row.sender && typeof row.sender === 'object'
+            ? row.sender
+            : row.user && typeof row.user === 'object'
+                ? row.user
+                : undefined;
+        const id = sender?.user_id ?? sender?.uin ?? sender?.id;
+        const displayName = sender?.nickname ?? sender?.card ?? sender?.name;
+        const body = row.message ?? row.content ?? row.elements ?? row.raw_message;
+        let segments;
+        if (Array.isArray(body))
+            segments = toCanonicalSegments(icqqElementsToSegments(body) ?? body);
+        else if (typeof body === 'string' && body.trim())
+            segments = [{ type: 'text', data: { text: body.trim() } }];
+        else
+            segments = [];
+        if (segments.length === 0)
+            return [];
+        return [Object.freeze({
+                ...(id != null ? { actor: Object.freeze({
+                        id: String(id),
+                        ...(displayName != null && String(displayName).trim() ? { displayName: String(displayName) } : {}),
+                    }) } : {}),
+                ...(typeof row.time === 'number' ? { timestamp: row.time < 1e12 ? row.time * 1000 : row.time } : {}),
+                segments: Object.freeze(segments),
+            })];
+    }));
+}

package/lib/icqq-guild.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import { type MessageSegment } from "zhin.js";
+import type { GuildMessageEventData } from "./protocol.js";
+export interface IcqqGuildClient {
+    getGuildList(): Array<{
+        guild_id: string;
+        guild_name: string;
+    }>;
+    getChannelList(guildId: string): Array<{
+        guild_id: string;
+        channel_id: string;
+        channel_name: string;
+    }>;
+}
+export interface IcqqGuildChannelEntry {
+    channel_id: string;
+    channel_name: string;
+    guild_id: string;
+    guild_name: string;
+}
+export interface NormalizedIcqqGuildInbound {
+    messageId: string;
+    channelId: string;
+    guildId: string;
+    guildName: string;
+    channelName: string;
+    userId: string;
+    nickname: string;
+    content: MessageSegment[];
+    rawMessage: string;
+    timestampMs: number;
+    raw: GuildMessageEventData;
+}
+export declare class IcqqGuildCatalog {
+    private readonly channels;
+    private readonly guilds;
+    clear(): void;
+    syncAll(client: IcqqGuildClient): Promise<void>;
+    upsertFromInbound(data: GuildMessageEventData): void;
+    getGuildChannelList(): Array<{
+        id: string;
+        name: string;
+        parent: {
+            type: "guild";
+            id: string;
+            name: string;
+        };
+    }>;
+    resolveConsoleChannelNames(channelId: string, guildId?: string): {
+        channelName?: string;
+        parentName?: string;
+    };
+}
+export declare function isIcqqGuildEvent(eventName: string | undefined): boolean;
+export declare function normalizeIcqqGuildInboundMessage(data: GuildMessageEventData & Record<string, unknown>): NormalizedIcqqGuildInbound | null;

package/lib/icqq-guild.js

@@ -0,0 +1,109 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import { toCanonicalSegments } from "zhin.js";
+import { parseCqMessage } from "./cq-message.js";
+export class IcqqGuildCatalog {
+    channels = new Map();
+    guilds = new Map();
+    clear() {
+        this.channels.clear();
+        this.guilds.clear();
+    }
+    async syncAll(client) {
+        const guildRows = client.getGuildList();
+        for (const row of guildRows) {
+            const guild_id = String(row.guild_id ?? "");
+            if (!guild_id)
+                continue;
+            const guild_name = String(row.guild_name ?? guild_id);
+            this.guilds.set(guild_id, { guild_id, guild_name });
+            const channels = client.getChannelList(guild_id);
+            for (const ch of channels) {
+                const channel_id = String(ch.channel_id ?? "");
+                if (!channel_id)
+                    continue;
+                const channel_name = String(ch.channel_name ?? channel_id);
+                this.channels.set(channel_id, {
+                    channel_id,
+                    channel_name,
+                    guild_id,
+                    guild_name,
+                });
+            }
+        }
+    }
+    upsertFromInbound(data) {
+        const guild_id = String(data.guild_id ?? "");
+        const channel_id = String(data.channel_id ?? "");
+        if (!guild_id || !channel_id)
+            return;
+        const guild_name = String(data.guild_name ?? guild_id);
+        const channel_name = String(data.channel_name ?? channel_id);
+        this.guilds.set(guild_id, { guild_id, guild_name });
+        this.channels.set(channel_id, {
+            channel_id,
+            channel_name,
+            guild_id,
+            guild_name,
+        });
+    }
+    getGuildChannelList() {
+        return Array.from(this.channels.values()).map((entry) => ({
+            id: entry.channel_id,
+            name: entry.channel_name,
+            parent: {
+                type: "guild",
+                id: entry.guild_id,
+                name: entry.guild_name,
+            },
+        }));
+    }
+    resolveConsoleChannelNames(channelId, guildId) {
+        const entry = this.channels.get(channelId);
+        if (entry) {
+            return { channelName: entry.channel_name, parentName: entry.guild_name };
+        }
+        if (guildId) {
+            const guild = this.guilds.get(guildId);
+            return guild ? { parentName: guild.guild_name } : {};
+        }
+        return {};
+    }
+}
+export function isIcqqGuildEvent(eventName) {
+    return typeof eventName === "string" && eventName.startsWith("message.guild");
+}
+export function normalizeIcqqGuildInboundMessage(data) {
+    if (data.type !== "guild")
+        return null;
+    const guildId = String(data.guild_id ?? "");
+    const channelId = String(data.channel_id ?? "");
+    if (!guildId || !channelId)
+        return null;
+    const userId = String(data.tiny_id ?? data.user_id ?? "");
+    const nickname = String(data.nickname ?? userId);
+    const rawMessage = String(data.raw_message ?? "");
+    const timestampMs = typeof data.time === "number" ? data.time * 1000 : Date.now();
+    const messageId = data.message_id != null && String(data.message_id) !== ""
+        ? String(data.message_id)
+        : data.seq != null
+            ? String(data.seq)
+            : `${data.time ?? 0}_${userId}_${channelId}`;
+    const parsed = parseCqMessage(rawMessage);
+    const canonical = toCanonicalSegments(parsed);
+    const content = canonical.length > 0 ? canonical : [{ type: "text", data: { text: rawMessage } }];
+    return {
+        messageId,
+        channelId,
+        guildId,
+        guildName: String(data.guild_name ?? guildId),
+        channelName: String(data.channel_name ?? channelId),
+        userId,
+        nickname,
+        content,
+        rawMessage,
+        timestampMs,
+        raw: data,
+    };
+}

package/lib/icqq-inbound.d.ts

@@ -0,0 +1,165 @@
+/**
+ * icqq 入站事件归一化（post_type / message_type / message 段）
+ */
+import { type MessageSegment } from "zhin.js";
+import type { GroupRole } from "./types.js";
+/** 守护进程推送的通用事件壳 */
+export interface IcqqEventBase {
+    post_type?: string;
+    self_id?: number;
+}
+/** post_type=message 时的消息体（字段随 icqqjs/cli 演进，未知字段保留） */
+export interface IcqqMessageEvent extends IcqqEventBase {
+    post_type: "message";
+    message_id?: string;
+    msg_id?: string;
+    user_id: number;
+    user_uid?: string;
+    time: number;
+    seq?: number;
+    message_type: string;
+    sub_type?: string;
+    raw_message?: string;
+    message?: IcqqMessageElement[];
+    sender?: {
+        user_id?: number;
+        user_uid?: string;
+        nickname?: string;
+        card?: string;
+        /** 群临时会话来源群号 */
+        group_id?: number;
+        /** 群成员角色：owner | admin | member */
+        role?: GroupRole | string;
+    };
+    from_id?: number;
+    from_uid?: string;
+    group_id?: number;
+    to_id?: number;
+    nickname?: string;
+    /** 旧版仅有 type 无 message_type */
+    type?: "group" | "private";
+    /** oicq Message#source：被引用回复的源消息 */
+    source?: IcqqMessageSource;
+}
+/** oicq 引用源消息（与 MessageEvent.source 对齐） */
+export interface IcqqMessageSource {
+    message_id?: string;
+    msg_id?: string;
+    seq?: number;
+    rand?: number;
+    time?: number;
+    user_id?: number;
+    group_id?: number;
+    raw_message?: string;
+    /** 元素数组，或 NT 推送的纯文本摘要 */
+    message?: IcqqMessageElement[] | string;
+    sender?: {
+        user_id?: number;
+        nickname?: string;
+        card?: string;
+    };
+    [key: string]: unknown;
+}
+interface IcqqMessageLookup {
+    readonly messageId: string;
+    readonly sender?: Readonly<{
+        id?: string;
+        name?: string;
+    }>;
+    readonly content: readonly MessageSegment[] | string;
+    readonly raw?: string;
+    readonly time?: number;
+}
+export type IcqqMessageElement = {
+    type: string;
+    text?: string;
+    qq?: string | number;
+    user_id?: string | number;
+    id?: string | number;
+    url?: string;
+    file?: string;
+    fid?: string;
+    name?: string;
+    size?: number;
+    seconds?: number;
+    [key: string]: unknown;
+};
+export interface IcqqInboundMediaResolver {
+    getPttUrl(element: IcqqMessageElement): Promise<string | null | undefined>;
+    getVideoUrl(element: IcqqMessageElement): Promise<string | null | undefined>;
+}
+/**
+ * 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 declare function resolveIcqqInboundMedia(elements: IcqqMessageElement[] | undefined, resolver: IcqqInboundMediaResolver): Promise<void>;
+/** 归一化后供适配器使用的入站消息 */
+export interface NormalizedIcqqInbound {
+    messageId: string;
+    idSource: "message_id" | "msg_id" | "seq" | "synthetic";
+    channelType: "group" | "private";
+    channelId: string;
+    /** 群临时会话：来源群号 */
+    channelParentGroupId?: string;
+    userId: string;
+    nickname: string;
+    /** 群聊时来自 sender.role（私聊无） */
+    senderRole?: GroupRole;
+    content: MessageSegment[];
+    rawMessage: string;
+    timestampMs: number;
+    raw: IcqqMessageEvent;
+}
+/** 从 sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
+export declare function parseIcqqSenderGroupRole(sender: {
+    role?: unknown;
+} | undefined): GroupRole | undefined;
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export declare function isIcqqBotMentioned(input: {
+    readonly uin: string;
+    readonly content?: readonly MessageSegment[] | null;
+    readonly rawMessage?: string;
+}): boolean;
+/** 从事件壳中取出 OneBot/icqq 载荷（兼容 data 嵌套或字段在根级） */
+export declare function unwrapIcqqEventPayload(event: {
+    data?: unknown;
+    [key: string]: unknown;
+}): unknown;
+export declare function resolveIcqqInboundUserId(data: Record<string, unknown>): number | undefined;
+export declare function isIcqqMessagePostType(data: unknown): data is IcqqMessageEvent;
+export declare function shouldSkipSelfInboundMessage(data: IcqqMessageEvent): boolean;
+/** 群临时会话私聊：icqq message_type=private & sub_type=group */
+export declare function isIcqqGroupTempPrivateMessage(data: IcqqMessageEvent): boolean;
+export declare function resolveChannelFromIcqqMessage(data: IcqqMessageEvent): {
+    channelType: "group" | "private";
+    channelId: string;
+    channelParentGroupId?: string;
+};
+export declare function resolveIcqqInboundMessageId(data: IcqqMessageEvent, channelId: string): {
+    id: string;
+    source: "message_id" | "msg_id" | "seq" | "synthetic";
+};
+export declare function icqqElementsToSegments(elements: IcqqMessageElement[] | undefined): MessageSegment[] | null;
+/** 载荷可能把 source 嵌在 data / event 等字段，深度查找 */
+export declare function findIcqqNestedMessageSource(root: unknown, maxDepth?: number): IcqqMessageSource | undefined;
+/** 从 oicq MessageEvent.source 解析被引用消息的 message_id */
+export declare function resolveQuoteIdFromIcqqSource(source: unknown): string | undefined;
+/** Convert an ICQQ source into the adapter-local lookup payload. */
+export declare function messageLookupFromIcqqSource(source: unknown): IcqqMessageLookup | null;
+/** 从事件顶层字段解析引用 message_id（与 message 段互补） */
+export declare function resolveIcqqQuoteIdFromEvent(data: IcqqMessageEvent): string | undefined;
+export declare function resolveInboundContent(data: IcqqMessageEvent): MessageSegment[];
+export declare function normalizeIcqqInboundMessage(data: IcqqMessageEvent): NormalizedIcqqInbound | null;
+/** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
+export declare class InboundMessageDeduper {
+    private readonly seen;
+    shouldProcess(messageId: string): boolean;
+    clear(): void;
+}
+export {};