@zhin.js/adapter-icqq 1.1.16 → 1.1.18

package/lib/endpoint.js

@@ -8,12 +8,13 @@ import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logge
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
 import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, resolveIcqqSelfUserId, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
-import { isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
+import { icqqNoticeDedupeKey, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { formatInboundContent, formatOutboundMessages, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+import { formatInboundContent, formatOutboundMessageParts, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
+import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 const BOUND_EVENTS = [
     'message.private',
     'message.group',
@@ -55,8 +56,16 @@ export class IcqqEndpoint extends Endpoint {
     #inboundOwner = new AsyncLocalStorage();
     #contentResolver;
     content;
+    loginControl;
+    #reloginTimer;
+    #reloginAttempts = 0;
+    #reloginInFlight;
+    #offlineNoticeAt = 0;
+    #challengeNoticeAt = 0;
     management = Object.freeze({
         inspectGroupMember: (group, user, signal) => inspectGroupMember(this.client, group, user, signal),
+        inspectGroupScene: (group, signal) => inspectGroupScene(this.client, group, signal),
+        inspectGroupMemberProfile: (group, user, signal) => inspectGroupMemberProfile(this.client, group, user, signal),
         moderateGroupMember: (group, user, action, signal) => moderateGroupMember(this.client, group, user, action, signal, () => this.#open && !this.#retiring && !this.#stopped),
         listFriends: async () => Array.from(this.client.fl.values()).map((f) => ({
             user_id: f.user_id,
@@ -140,6 +149,19 @@ export class IcqqEndpoint extends Endpoint {
         this.#logger = getAdapterLogger('icqq', options.config.id);
         this.#options = options;
         this.endpointName = options.config.id;
+        this.loginControl = Object.freeze({
+            endpointId: this.endpointName,
+            state: () => ({
+                endpointId: this.endpointName,
+                transportState: this.transportState,
+                online: this.client.isOnline(),
+                pending: this.#pendingLoginTasks(),
+            }),
+            pending: () => this.#pendingLoginTasks(),
+            relogin: () => this.relogin(),
+            submit: (taskId, value) => this.#options.loginAssist.submit(taskId, value),
+            cancel: (taskId, reason) => this.#options.loginAssist.cancel(taskId, reason),
+        });
     }
     #handleBackgroundFailure(operation, error) {
         if (!this.#started || this.#stopped || this.#retiring)
@@ -159,6 +181,148 @@ export class IcqqEndpoint extends Endpoint {
         // reconn_interval policy. No account-level logout or second retry timer.
         this.client.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
     }
+    /** Force a login attempt (manual recovery command). */
+    relogin() {
+        return this.#startRelogin(true);
+    }
+    #startRelogin(resetAttempts) {
+        if (this.#stopped || this.#retiring) {
+            return Promise.reject(new Error('ICQQ endpoint 已停止'));
+        }
+        if (this.#reloginInFlight)
+            return this.#reloginInFlight;
+        if (resetAttempts)
+            this.#reloginAttempts = 0;
+        const task = this.#performRelogin();
+        this.#reloginInFlight = task;
+        void task.catch(() => undefined).finally(() => {
+            if (this.#reloginInFlight === task)
+                this.#reloginInFlight = undefined;
+            if (this.#started && !this.#stopped && !this.#retiring && !this.client.isOnline()) {
+                this.#scheduleRelogin('relogin_failed');
+            }
+        });
+        return task;
+    }
+    async #performRelogin() {
+        this.#clearReloginTimer();
+        this.client.cancelReconnect();
+        this.#logger.info(formatCompact({ op: 'icqq_relogin', endpoint: this.endpointName }));
+        try {
+            await this.client.login(this.#options.config.password);
+        }
+        catch (error) {
+            this.#logger.warn(formatCompact({
+                op: 'icqq_relogin_failed',
+                endpoint: this.endpointName,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            throw error;
+        }
+    }
+    #scheduleRelogin(reason) {
+        if (!this.#options.config.autoReconnect || this.#stopped || this.#retiring)
+            return;
+        if (this.#reloginTimer || this.#reloginInFlight)
+            return;
+        if (this.#reloginAttempts >= 8)
+            return;
+        const attempt = this.#reloginAttempts++;
+        const delayMs = Math.min(300_000, 5_000 * (2 ** Math.min(attempt, 5)));
+        this.#logger.info(formatCompact({
+            op: 'icqq_relogin_scheduled',
+            endpoint: this.endpointName,
+            reason,
+            attempt: attempt + 1,
+            delay_ms: delayMs,
+        }));
+        this.#reloginTimer = setTimeout(() => {
+            this.#reloginTimer = undefined;
+            void this.#startRelogin(false).catch(() => {
+                // #performRelogin already scheduled the next attempt.
+            });
+        }, delayMs);
+        this.#reloginTimer.unref?.();
+    }
+    #clearReloginTimer() {
+        if (!this.#reloginTimer)
+            return;
+        clearTimeout(this.#reloginTimer);
+        this.#reloginTimer = undefined;
+    }
+    #pendingLoginTasks() {
+        return this.#options.loginAssist.listPending()
+            .filter((task) => task.adapter === 'icqq' && task.endpointKey === this.endpointName);
+    }
+    #notifyOffline(reason, willRetry) {
+        const notifier = this.#options.notifier;
+        if (!notifier?.configured)
+            return;
+        const now = Date.now();
+        if (now - this.#offlineNoticeAt < 60_000)
+            return;
+        this.#offlineNoticeAt = now;
+        const recovery = willRetry
+            ? '已开始自动重新登录。'
+            : '请手动重新登录。';
+        const qrCommand = `icqq login qr ${this.endpointName}`;
+        const confirmCommand = `icqq login confirm ${this.endpointName}`;
+        const codeCommand = `icqq login code ${this.endpointName} <内容>`;
+        const text = `[Zhin] ICQQ ${this.endpointName} 掉线（${reason}）。${recovery}\n`
+            + `恢复：在 QQ 回复 \`${qrCommand}\` 获取二维码，扫码后回复 \`${confirmCommand}\`；`
+            + `滑块/短信验证请回复 \`${codeCommand}\`。也可以打开 Console 的 ICQQ 页面完成登录。`;
+        void notifier.send(text).then((sent) => {
+            if (sent)
+                return;
+            this.#logger.warn(formatCompact({
+                op: 'icqq_notify_failed',
+                endpoint: this.endpointName,
+                reason,
+            }));
+        });
+    }
+    #notifyChallenge(step) {
+        const notifier = this.#options.notifier;
+        if (!notifier?.configured)
+            return;
+        const now = Date.now();
+        if (now - this.#challengeNoticeAt < 30_000)
+            return;
+        this.#challengeNoticeAt = now;
+        const label = step === 'qrcode' ? '二维码验证'
+            : step === 'slider' ? '滑块验证'
+                : step === 'device' ? '设备确认'
+                    : '登录确认';
+        const qrCommand = `icqq login qr ${this.endpointName}`;
+        const confirmCommand = `icqq login confirm ${this.endpointName}`;
+        const codeCommand = `icqq login code ${this.endpointName} <内容>`;
+        const text = `[Zhin] ICQQ ${this.endpointName} 需要${label}。\n`
+            + (step === 'qrcode' || step === 'auth'
+                ? `在 QQ 回复 \`${qrCommand}\` 获取二维码，完成后回复 \`${confirmCommand}\`。`
+                : `在 QQ 回复 \`icqq login status ${this.endpointName}\` 查看验证链接，再用 \`${codeCommand}\` 提交验证码；也可以打开 Console 的 ICQQ 页面。`);
+        void notifier.send(text).then((sent) => {
+            if (sent)
+                return;
+            this.#logger.warn(formatCompact({
+                op: 'icqq_notify_failed',
+                endpoint: this.endpointName,
+                reason: `login_${step}`,
+            }));
+        });
+    }
+    #notifyRecovered() {
+        const notifier = this.#options.notifier;
+        const hadOfflineNotice = this.#offlineNoticeAt > 0;
+        this.#offlineNoticeAt = 0;
+        this.#challengeNoticeAt = 0;
+        if (!notifier?.configured || !hadOfflineNotice)
+            return;
+        void notifier.send(`[Zhin] ICQQ ${this.endpointName} 已重新上线。`).then((sent) => {
+            if (sent)
+                return;
+            this.#logger.warn(formatCompact({ op: 'icqq_notify_failed', endpoint: this.endpointName, reason: 'recovered' }));
+        });
+    }
     #ignoreReactionAck(action, task) {
         void Promise.resolve(task).catch((error) => {
             this.#logger.debug(formatCompact({
@@ -207,6 +371,7 @@ export class IcqqEndpoint extends Endpoint {
             this.#logger.info(`connected (direct) | friends: ${this.client.fl.size} | groups: ${this.client.gl.size}`);
         }
         catch (error) {
+            this.#notifyOffline('start_failed', false);
             await this.stop();
             this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
             throw error;
@@ -240,6 +405,7 @@ export class IcqqEndpoint extends Endpoint {
     }
     async stop() {
         this.#stopped = true;
+        this.#clearReloginTimer();
         this.#assertExternalLifecycle('stop');
         this.#armRetirementFence();
         await Promise.allSettled([...this.#inflightInbound]);
@@ -302,10 +468,10 @@ export class IcqqEndpoint extends Endpoint {
             : { content: payload, dispose() { } };
         try {
             // Standalone elements (share / file / …) are split into ordered messages.
-            const messages = formatOutboundMessages(prepared.content);
+            const messages = formatOutboundMessageParts(prepared.content);
             const parsed = icqqOutboundTarget(conversation);
-            let messageId;
-            for (const [index, message] of messages.entries()) {
+            const parts = [];
+            for (const [index, { message, sourceIndices }] of messages.entries()) {
                 const preview = formatIcqqSendablePreview(message);
                 let result;
                 try {
@@ -321,60 +487,43 @@ export class IcqqEndpoint extends Endpoint {
                     }));
                     if (index === 0)
                         throw error;
-                    // Earlier parts are already delivered: a retry would duplicate them.
-                    throw new EndpointDeliveryError('partial_delivery', `ICQQ delivered ${index} of ${messages.length} message parts`, 'unknown', { cause: error });
+                    // Earlier sends completed; retrying can duplicate accepted messages, even without ids.
+                    throw new EndpointDeliveryError('partial_delivery', `ICQQ completed ${index} of ${messages.length} message sends`, 'unknown', { cause: error, parts });
                 }
                 const rawId = result?.message_id;
                 const id = (typeof rawId === 'string' || (typeof rawId === 'number' && Number.isFinite(rawId))) && String(rawId).trim() !== ''
                     ? String(rawId) : undefined;
-                messageId ??= id;
+                parts.push({ ...(id ? { messageId: id } : {}), ...(sourceIndices ? { sourceIndices } : {}) });
                 this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${id ?? '-'} | ${truncatePreview(preview, 80)}`);
             }
-            // Native share / file APIs return no id; the reply is confirmed by any part that has one.
-            if (!messageId) {
-                throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
+            // A resolved share/file call has no message identity; retain that unknown slot in the batch.
+            if (!parts.some(part => part.messageId)) {
+                throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown', { parts });
             }
-            return messageId;
+            return { parts };
         }
         finally {
-            prepared.dispose();
-        }
-    }
-    /**
-     * ICQQ's share API returns no message id; a resolved call only means the server accepted it.
-     * The card is the bot's own newest card message in the conversation history, so read the id
-     * from there (once more after a short wait, history can lag). Undefined keeps the delivery
-     * unconfirmed rather than inventing an id.
-     */
-    async #findOwnCard(history, sentAt) {
-        const self = Number(this.client.uin);
-        for (const wait of [0, 500]) {
-            if (wait)
-                await new Promise(resolve => setTimeout(resolve, wait));
-            // A missing or throwing history API must not turn an accepted share into a send failure.
-            const messages = await Promise.resolve().then(history).catch(() => []);
-            const card = [...messages].reverse().find(item => Number(item.sender?.user_id ?? item.user_id) === self
-                && (item.time ?? 0) >= sentAt - 2
-                && (item.message ?? []).some(element => element.type === 'json' || element.type === 'xml' || element.type === 'share'));
-            if (card && card.message_id != null && String(card.message_id).trim())
-                return String(card.message_id);
+            try {
+                prepared.dispose();
+            }
+            catch (error) {
+                // Temporary-file cleanup cannot change an already observed platform send outcome.
+                this.#logger.warn(formatCompact({ op: 'icqq_media_cleanup_failed', error: describeUnknownError(error) }));
+            }
         }
-        return undefined;
     }
     async #sendNative(target, message) {
         if (isIcqqShareElement(message)) {
             switch (target.kind) {
                 case 'private': {
-                    const sentAt = Math.floor(Date.now() / 1000);
                     const friend = this.client.pickFriend(target.userId);
                     await friend.share(message);
-                    return { message_id: await this.#findOwnCard(() => friend.getChatHistory(), sentAt) };
+                    return {};
                 }
                 case 'group': {
-                    const sentAt = Math.floor(Date.now() / 1000);
                     const group = this.client.pickGroup(target.groupId);
                     await group.share(message);
-                    return { message_id: await this.#findOwnCard(() => group.getChatHistory(), sentAt) };
+                    return {};
                 }
                 case 'temp':
                     await this.client.pickMember(target.groupId, target.userId).share(message);
@@ -538,12 +687,16 @@ export class IcqqEndpoint extends Endpoint {
         this.#bindSystemOnlineEvent();
         this.client.on('system.offline', (event) => {
             this.#logSystemEvent('offline', event);
+            this.#notifyOffline('offline', this.#options.config.autoReconnect);
         });
         this.client.on('system.offline.network', (event) => {
             this.#logSystemEvent('offline.network', event);
+            this.#notifyOffline('network', this.#options.config.autoReconnect);
         });
         this.client.on('system.offline.kickoff', (event) => {
             this.#logSystemEvent('offline.kickoff', event);
+            this.#notifyOffline('kickoff', this.#options.config.autoReconnect);
+            this.#scheduleRelogin('kickoff');
         });
         this.client.on('system.login.qrcode', (event) => {
             this.#logger.info('icqq 收到二维码登录事件，等待 LoginAssist / 终端确认后继续');
@@ -558,6 +711,8 @@ export class IcqqEndpoint extends Endpoint {
         this.client.on('system.login.error', (event) => {
             this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'login_error');
             this.#logSystemEvent('login.error', event);
+            this.#notifyOffline('login_error', this.#options.config.autoReconnect);
+            this.#scheduleRelogin('login_error');
         });
         this.client.on('system.login.auth', (event) => {
             this.#handleLoginChallenge('auth', event);
@@ -568,6 +723,9 @@ export class IcqqEndpoint extends Endpoint {
             if (this.#retiring)
                 return;
             this.#everOnline = true;
+            this.#clearReloginTimer();
+            this.#reloginAttempts = 0;
+            this.#notifyRecovered();
             try {
                 this.#resolveStartOnline?.();
                 this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
@@ -625,6 +783,8 @@ export class IcqqEndpoint extends Endpoint {
             ? event
             : null);
         this.#logSystemEvent(`login.${step}`, event);
+        this.#clearReloginTimer();
+        this.#notifyChallenge(step);
         void runIcqqLoginAssistStep({
             assist: this.#options.loginAssist,
             locale: this.#options.locale,
@@ -743,6 +903,7 @@ export class IcqqEndpoint extends Endpoint {
             channelType: normalized.channelType,
             channelId: normalized.channelId,
             channelParentGroupId: normalized.channelParentGroupId,
+            name: normalized.groupName,
         });
         const quoteId = resolveIcqqQuoteIdFromEvent(data);
         const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
@@ -857,13 +1018,7 @@ export class IcqqEndpoint extends Endpoint {
     #onNoticeEvent(payload) {
         if (!payload || !isIcqqNoticePayload(payload))
             return;
-        const key = [
-            payload.time,
-            payload.operator_id ?? payload.user_id,
-            payload.notice_type ?? payload.type,
-            payload.sub_type,
-        ].join('_');
-        if (!this.#sideEventDeduper.shouldProcess(`notice:${key}`))
+        if (!this.#sideEventDeduper.shouldProcess(icqqNoticeDedupeKey(payload)))
             return;
         this.#dispatchIcqqSideEvent(payload);
     }

package/lib/group-moderation.js

@@ -3,17 +3,22 @@ export async function inspectGroupMember(client, groupId, userId, signal) {
     signal.throwIfAborted();
     const group = numericId(groupId);
     const user = numericId(userId);
+    const selfLookup = client.getGroupMemberInfo(group, client.uin, true);
     const [self, member] = await Promise.all([
-        client.getGroupMemberInfo(group, client.uin, true),
-        client.getGroupMemberInfo(group, user, true),
+        selfLookup,
+        user === client.uin ? selfLookup : client.getGroupMemberInfo(group, user, true),
     ]);
     signal.throwIfAborted();
     const joinedAt = member.join_time * 1000;
+    const platformRole = member.user_id === user && member.group_id === group
+        && (member.role === 'owner' || member.role === 'admin' || member.role === 'member')
+        ? member.role : undefined;
     return {
         canModerate: client.isOnline() && user !== client.uin
             && self.user_id === client.uin && self.group_id === group
             && member.user_id === user && member.group_id === group
             && (self.role === 'owner' || self.role === 'admin') && member.role === 'member',
+        ...(platformRole ? { platformRole } : {}),
         ...(Number.isSafeInteger(joinedAt) && joinedAt > 0 && joinedAt <= Date.now() ? { joinedAt } : {}),
     };
 }

package/lib/group-scene.d.ts

@@ -0,0 +1,11 @@
+import type { Client } from '@icqqjs/icqq';
+import type { GroupMemberProfile, GroupSceneFacts } from 'zhin.js/adapter';
+/** Listing a very large roster only to find admins is not worth the packet; adminIds stay unknown. */
+export declare const ADMIN_SCAN_MAX_MEMBERS = 1000;
+/**
+ * ADR 0041 scene facts: one uncached group-info read, plus (small groups only) one roster read for
+ * admins. A roster failure leaves adminIds unknown instead of failing the other facts.
+ */
+export declare function inspectGroupScene(client: Client, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts>;
+/** ADR 0041 member facts from one uncached lookup (same rationale as the agent `freshMember` helper). */
+export declare function inspectGroupMemberProfile(client: Client, groupId: string, userId: string, signal: AbortSignal): Promise<GroupMemberProfile>;

package/lib/group-scene.js

@@ -0,0 +1,71 @@
+/** Listing a very large roster only to find admins is not worth the packet; adminIds stay unknown. */
+export const ADMIN_SCAN_MAX_MEMBERS = 1000;
+const MAX_ADMIN_IDS = 20;
+function positiveId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+}
+function numericId(value) {
+    const id = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id))
+        throw new Error('Invalid QQ identifier');
+    return id;
+}
+/**
+ * ADR 0041 scene facts: one uncached group-info read, plus (small groups only) one roster read for
+ * admins. A roster failure leaves adminIds unknown instead of failing the other facts.
+ */
+export async function inspectGroupScene(client, groupId, signal) {
+    signal.throwIfAborted();
+    const group = numericId(groupId);
+    const info = await client.getGroupInfo(group, true);
+    signal.throwIfAborted();
+    if (info.group_id !== group)
+        return {};
+    const memberCount = Number.isSafeInteger(info.member_count) && info.member_count > 0 ? info.member_count : undefined;
+    const ownerId = positiveId(info.owner_id);
+    let adminIds;
+    if (memberCount === undefined || memberCount <= ADMIN_SCAN_MAX_MEMBERS) {
+        try {
+            const roster = await client.getGroupMemberList(group);
+            signal.throwIfAborted();
+            adminIds = [...roster.values()]
+                .filter(member => member.role === 'admin' && member.group_id === group)
+                .map(member => positiveId(member.user_id))
+                .filter((id) => id !== undefined)
+                .slice(0, MAX_ADMIN_IDS);
+        }
+        catch {
+            signal.throwIfAborted();
+            adminIds = undefined;
+        }
+    }
+    const name = typeof info.group_name === 'string' && info.group_name.trim() ? info.group_name.trim() : undefined;
+    const nowSeconds = Date.now() / 1000;
+    return {
+        ...(name ? { name } : {}),
+        ...(ownerId ? { ownerId } : {}),
+        ...(adminIds ? { adminIds } : {}),
+        ...(memberCount !== undefined ? { memberCount } : {}),
+        ...(typeof info.shutup_time_whole === 'number' ? { muteAll: info.shutup_time_whole > nowSeconds } : {}),
+    };
+}
+/** ADR 0041 member facts from one uncached lookup (same rationale as the agent `freshMember` helper). */
+export async function inspectGroupMemberProfile(client, groupId, userId, signal) {
+    signal.throwIfAborted();
+    const group = numericId(groupId);
+    const user = numericId(userId);
+    const member = await client.getGroupMemberInfo(group, user, true);
+    signal.throwIfAborted();
+    if (member.user_id !== user || member.group_id !== group)
+        return {};
+    const card = typeof member.card === 'string' && member.card.trim() ? member.card.trim() : undefined;
+    const title = typeof member.title === 'string' && member.title.trim() ? member.title.trim() : undefined;
+    const shutupSeconds = member.shutup_time;
+    return {
+        ...(member.role === 'owner' || member.role === 'admin' || member.role === 'member' ? { platformRole: member.role } : {}),
+        ...(card ? { card } : {}),
+        ...(title ? { title } : {}),
+        ...(typeof shutupSeconds === 'number' && Number.isFinite(shutupSeconds)
+            ? { mutedUntil: shutupSeconds * 1000 > Date.now() ? shutupSeconds * 1000 : 0 } : {}),
+    };
+}

package/lib/icqq-inbound.d.ts

@@ -103,6 +103,8 @@ export interface NormalizedIcqqInbound {
     channelId: string;
     /** 群临时会话：来源群号 */
     channelParentGroupId?: string;
+    /** 群聊时来自 group_name */
+    groupName?: string;
     userId: string;
     nickname: string;
     /** 群聊时来自 sender.role（私聊无） */

package/lib/icqq-inbound.js

@@ -688,6 +688,9 @@ export function normalizeIcqqInboundMessage(data) {
         channelType,
         channelId,
         channelParentGroupId,
+        ...(channelType === "group" && typeof ext.group_name === "string" && ext.group_name.trim()
+            ? { groupName: ext.group_name.trim() }
+            : {}),
         userId: String(userIdNum),
         nickname,
         senderRole,

package/lib/icqq-inbox.d.ts

@@ -8,6 +8,11 @@ export interface IcqqInboxBase {
 export declare function isIcqqRequestPayload(payload: unknown): boolean;
 /** post_type=notice / notice.* 判定。 */
 export declare function isIcqqNoticePayload(payload: unknown): boolean;
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export declare function icqqNoticeDedupeKey(payload: Record<string, unknown>): string;
 /**
  * request 事件载荷 → unified_inbox_request 行。
  * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。

package/lib/icqq-inbox.js

@@ -10,6 +10,20 @@ export function isIcqqNoticePayload(payload) {
     return typeof postType === 'string'
         && (postType === 'notice' || postType.startsWith('notice.'));
 }
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export function icqqNoticeDedupeKey(payload) {
+    return `notice:${[
+        payload.time,
+        payload.group_id,
+        payload.user_id,
+        payload.operator_id,
+        payload.notice_type ?? payload.type,
+        payload.sub_type,
+    ].join('_')}`;
+}
 /**
  * request 事件载荷 → unified_inbox_request 行。
  * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。

package/lib/icqq-login-control.d.ts

@@ -0,0 +1,18 @@
+import type { PendingLoginTask } from '@zhin.js/core';
+export interface IcqqLoginControlState {
+    readonly endpointId: string;
+    readonly transportState: string;
+    readonly online: boolean;
+    readonly pending: readonly PendingLoginTask[];
+}
+export interface IcqqLoginControl {
+    readonly endpointId: string;
+    state(): IcqqLoginControlState;
+    pending(): readonly PendingLoginTask[];
+    /** Force a login attempt; rejects when the endpoint is stopped or the SDK login fails. */
+    relogin(): Promise<void>;
+    submit(taskId: string, value: string | Record<string, unknown>): boolean;
+    cancel(taskId: string, reason?: string): boolean;
+}
+/** `endpoint id (QQ uin)` → control for the current generation. */
+export declare const icqqLoginControlToken: import("zhin.js").Token<Map<string, IcqqLoginControl>>;

package/lib/icqq-login-control.js

@@ -0,0 +1,8 @@
+/**
+ * ICQQ login control surface exposed to the Plugin Runtime, Console and the
+ * recovery command. One control per endpoint instance (UIN), provided by the
+ * ICQQ plugin setup and filled by `adapters/icqq/create()`.
+ */
+import { createToken } from 'zhin.js';
+/** `endpoint id (QQ uin)` → control for the current generation. */
+export const icqqLoginControlToken = createToken('zhin.icqq.login-control', 'ICQQ login control surface for recovery commands');

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, icqqInboundConversation, icqqOutboundTarget, type ActionResult, type IcqqEndpointConfig, type IcqqInboundMessage, type IcqqWireSegment, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, formatOutboundMessageParts, icqqInboundConversation, icqqOutboundTarget, type ActionResult, type IcqqEndpointConfig, type IcqqInboundMessage, type IcqqWireSegment, type IcqqOutboundMessagePart, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
 export { IcqqEndpoint, type IcqqEndpointOptions, } from './endpoint.js';
 export * from './types.js';
 export { icqqClient, type IcqqClient, type IcqqClientEventMap, } from './client.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, formatOutboundMessageParts, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 export { IcqqEndpoint, } from './endpoint.js';
 export * from './types.js';
 export { icqqClient, } from './client.js';

package/lib/protocol.d.ts

@@ -1,5 +1,6 @@
 import type { Sendable } from '@icqqjs/icqq';
 import { type ConversationRef } from '@zhin.js/im-contract';
+import { type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
 import type { MessageSegment, SendContent } from "zhin.js";
 export type ActionResult = {
     id: string;
@@ -177,6 +178,8 @@ export interface IcqqEndpointConfig {
     readonly autoServer?: boolean;
     readonly qqnt?: boolean;
     readonly ntLogin?: boolean;
+    /** Optional out-of-band outage notification target (usually a QQ adapter instance). */
+    readonly notify?: AdapterNotifyTarget;
 }
 export interface ResolvedIcqqConfig {
     readonly context: 'icqq';
@@ -194,6 +197,7 @@ export interface ResolvedIcqqConfig {
     readonly autoServer?: boolean;
     readonly qqnt?: boolean;
     readonly ntLogin?: boolean;
+    readonly notify?: ResolvedAdapterNotifyTarget;
 }
 export interface IcqqWireSegment {
     readonly type: string;
@@ -246,6 +250,8 @@ export declare function icqqInboundConversation(endpointKey: string, input: {
     readonly channelId: string;
     readonly channelParentGroupId?: string;
     readonly guildId?: string;
+    /** 群名（仅 group 会话使用） */
+    readonly name?: string;
 }): ConversationRef;
 /**
  * 出站：从 ConversationRef 派生 action 路由。
@@ -267,4 +273,10 @@ export declare function formatOutboundBody(payload: unknown): Sendable;
  * quote or whitespace are dropped: a standalone element cannot carry the quote.
  */
 export declare function formatOutboundMessages(payload: unknown): Sendable[];
+/** Native bubble and the exact source segment positions which produced it. */
+export interface IcqqOutboundMessagePart {
+    readonly message: Sendable;
+    readonly sourceIndices?: readonly number[];
+}
+export declare function formatOutboundMessageParts(payload: unknown): IcqqOutboundMessagePart[];
 export declare function formatInboundContent(rawMessage: string): string;