@zhin.js/adapter-icqq 1.1.17 → 1.1.18

package/lib/console-spec.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ICQQ Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+export declare const icqqConsoleSpec: {
+    readonly adapterKey: "icqq";
+    readonly adapterDisplayName: "ICQQ";
+    readonly fields: readonly AdapterConsoleField[];
+    readonly docsUrl: "https://zhin.js.org/adapters/icqq";
+    readonly readPermission: "icqq:read";
+    readonly writePermission: "icqq:write";
+    readonly idPattern: RegExp;
+    readonly idHint: "ICQQ endpoint id 是 QQ 号（纯数字）";
+    readonly idHintI18n: {
+        readonly en: "ICQQ endpoint ID is the QQ number (digits only)";
+    };
+};

package/lib/console-spec.js

@@ -0,0 +1,11 @@
+export const icqqConsoleSpec = {
+    adapterKey: 'icqq',
+    adapterDisplayName: 'ICQQ',
+    fields: [],
+    docsUrl: 'https://zhin.js.org/adapters/icqq',
+    readPermission: 'icqq:read',
+    writePermission: 'icqq:write',
+    idPattern: /^\d+$/,
+    idHint: 'ICQQ endpoint id 是 QQ 号（纯数字）',
+    idHintI18n: { en: 'ICQQ endpoint ID is the QQ number (digits only)' },
+};

package/lib/console.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ICQQ Console RPC：运行状态 + endpoint 增删（原 `icqq endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+export declare function createIcqqConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,16 @@
+/**
+ * ICQQ Console RPC：运行状态 + endpoint 增删（原 `icqq endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import { icqqRuntimeStateToken } from './icqq-runtime-state.js';
+import { icqqConsoleSpec } from './console-spec.js';
+export function createIcqqConsoleRpc(resources, getConfig) {
+    const state = resources.use(icqqRuntimeStateToken);
+    return createAdapterConsoleRpc({
+        ...icqqConsoleSpec,
+        running: () => state.endpoints.values(),
+        getConfig,
+    }, resources);
+}

package/lib/endpoint.d.ts

@@ -1,8 +1,10 @@
 import { Client } from '@icqqjs/icqq';
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState, type AdapterOutageNotifier } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
 import { type LoginAssist } from '@zhin.js/core';
+import { type EndpointSendResult } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
+import type { IcqqLoginControl } from './icqq-login-control.js';
 import { type IcqqInboundMessage, type ResolvedIcqqConfig } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
 export interface IcqqEndpointOptions {
@@ -10,20 +12,25 @@ export interface IcqqEndpointOptions {
     readonly config: ResolvedIcqqConfig;
     readonly loginAssist: LoginAssist;
     readonly locale?: import('zhin.js/i18n').Locale;
+    /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+    readonly notifier?: AdapterOutageNotifier;
 }
 export declare class IcqqEndpoint extends Endpoint<Client> {
     #private;
     readonly client: ManagedIcqqClient;
     readonly endpointName: string;
     readonly content: EndpointContentPort;
+    readonly loginControl: IcqqLoginControl;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: IcqqEndpointOptions);
+    /** Force a login attempt (manual recovery command). */
+    relogin(): Promise<void>;
     get transportState(): EndpointTransportState;
     start(signal: AbortSignal): Promise<void>;
     open(): void;
     close(): Promise<void>;
     stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<EndpointSendResult>;
     admit(msg: IcqqInboundMessage): Promise<void>;
 }

package/lib/endpoint.js

@@ -11,7 +11,7 @@ import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned,
 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';
@@ -56,6 +56,12 @@ 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),
@@ -143,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)
@@ -162,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({
@@ -210,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;
@@ -243,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]);
@@ -305,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 {
@@ -324,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);
@@ -541,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 / 终端确认后继续');
@@ -561,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);
@@ -571,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');
@@ -628,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,

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;
@@ -269,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;

package/lib/protocol.js

@@ -1,4 +1,5 @@
 import { isMediaRef } from '@zhin.js/im-contract';
+import { resolveAdapterNotifyTarget } from 'zhin.js/adapter';
 import { resolveIcqqMediaFile } from "./cq-message.js";
 export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
 /**
@@ -190,6 +191,7 @@ export function resolveIcqqConfig(config) {
     const autoServer = config.autoServer ?? true;
     const qqnt = config.qqnt;
     const ntLogin = config.ntLogin;
+    const notify = resolveAdapterNotifyTarget(config.notify);
     return {
         context: 'icqq',
         id,
@@ -206,6 +208,7 @@ export function resolveIcqqConfig(config) {
         ...(autoServer != null ? { autoServer } : {}),
         ...(qqnt != null ? { qqnt } : {}),
         ...(ntLogin != null ? { ntLogin } : {}),
+        ...(notify ? { notify } : {}),
     };
 }
 /**
@@ -326,22 +329,34 @@ export function formatOutboundBody(payload) {
  * quote or whitespace are dropped: a standalone element cannot carry the quote.
  */
 export function formatOutboundMessages(payload) {
+    return formatOutboundMessageParts(payload).map(part => part.message);
+}
+export function formatOutboundMessageParts(payload) {
     if (!Array.isArray(payload)) {
-        return isWireSegment(payload) ? formatOutboundMessages([payload]) : [formatOutboundBody(payload)];
+        if (isWireSegment(payload))
+            return formatOutboundMessageParts([payload]);
+        const message = formatOutboundBody(payload);
+        return [{ message, ...(typeof payload === 'string' && message !== payload ? {} : { sourceIndices: [0] }) }];
     }
     const groups = [[]];
-    for (const element of formatOutboundElements(payload)) {
-        if (isStandaloneElement(element))
-            groups.push([element], []);
-        else
-            groups.at(-1).push(element);
+    for (const [sourceIndex, source] of payload.entries()) {
+        for (const element of formatOutboundElements([source])) {
+            const item = { element, sourceIndex };
+            if (isStandaloneElement(element))
+                groups.push([item], []);
+            else
+                groups.at(-1).push(item);
+        }
     }
-    const messages = groups.filter(group => group.some(element => typeof element === 'string'
+    const messages = groups.filter(group => group.some(({ element }) => typeof element === 'string'
         ? element.trim() !== ''
         : element.type !== 'reply' && element.type !== 'quote'));
     if (messages.length === 0)
-        return ['\u200b'];
-    return messages.map(group => group.length === 1 ? group[0] : group);
+        return [{ message: '\u200b', sourceIndices: [] }];
+    return messages.map(group => ({
+        message: group.length === 1 ? group[0].element : group.map(item => item.element),
+        sourceIndices: [...new Set(group.map(item => item.sourceIndex))],
+    }));
 }
 function isStandaloneElement(element) {
     return typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,24 +33,27 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.24",
+    "@zhin.js/adapter": "1.1.25",
     "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
+    "@zhin.js/client": "1.1.21",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.53",
     "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
+    "@zhin.js/page": "1.1.10",
     "@zhin.js/permission": "1.1.9",
     "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/tool": "1.1.12"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
+    "@zhin.js/adapter": "^1.1.25",
     "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
+    "@zhin.js/core": "^1.1.53",
     "@zhin.js/prompt-section": "^1.1.9",
-    "zhin.js": "^1.1.17"
+    "zhin.js": "^1.1.18"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -76,11 +79,12 @@
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
     "@zhin.js/prompt-section": "1.1.9",
-    "zhin.js": "1.1.17"
+    "zhin.js": "1.1.18"
   },
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -124,6 +128,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []