@zhin.js/adapter-icqq 1.1.16 → 1.1.18

package/src/endpoint.ts

@@ -17,12 +17,14 @@ import {
   type EndpointPendingRequest,
   type EndpointSendRequest,
   type EndpointTransportState,
+  type AdapterOutageNotifier,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist } from '@zhin.js/core';
-import { EndpointDeliveryError, type MessageRef } from '@zhin.js/im-contract';
+import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type PendingLoginTask } from '@zhin.js/core';
+import { EndpointDeliveryError, type EndpointSendPart, type EndpointSendResult, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
+import type { IcqqLoginControl } from './icqq-login-control.js';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
 import {
@@ -39,6 +41,7 @@ import {
   type IcqqMessageEvent,
 } from './icqq-inbound.js';
 import {
+  icqqNoticeDedupeKey,
   isIcqqNoticePayload,
   isIcqqRequestPayload,
 } from './icqq-inbox.js';
@@ -52,7 +55,7 @@ import {
 } from './outbound-media.js';
 import {
   formatInboundContent,
-  formatOutboundMessages,
+  formatOutboundMessageParts,
   normalizeIcqqImageMedia,
   icqqInboundConversation,
   icqqOutboundTarget,
@@ -62,12 +65,15 @@ import {
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
+import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   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;
 }
 
 const BOUND_EVENTS = [
@@ -112,9 +118,17 @@ export class IcqqEndpoint extends Endpoint<Client> {
   readonly #inboundOwner = new AsyncLocalStorage<symbol>();
   readonly #contentResolver: IcqqContentResolver;
   readonly content: EndpointContentPort;
+  readonly loginControl: IcqqLoginControl;
+  #reloginTimer?: ReturnType<typeof setTimeout>;
+  #reloginAttempts = 0;
+  #reloginInFlight?: Promise<void>;
+  #offlineNoticeAt = 0;
+  #challengeNoticeAt = 0;
 
   readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
     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,
     ),
@@ -206,6 +220,19 @@ export class IcqqEndpoint extends Endpoint<Client> {
     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: string, value: string | Record<string, unknown>) => this.#options.loginAssist.submit(taskId, value),
+      cancel: (taskId: string, reason?: string) => this.#options.loginAssist.cancel(taskId, reason),
+    });
   }
 
   #handleBackgroundFailure(operation: IcqqBackgroundOperation, error: unknown): void {
@@ -224,6 +251,141 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.client.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
   }
 
+  /** Force a login attempt (manual recovery command). */
+  relogin(): Promise<void> {
+    return this.#startRelogin(true);
+  }
+
+  #startRelogin(resetAttempts: boolean): Promise<void> {
+    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(): Promise<void> {
+    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: string): void {
+    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(): void {
+    if (!this.#reloginTimer) return;
+    clearTimeout(this.#reloginTimer);
+    this.#reloginTimer = undefined;
+  }
+
+  #pendingLoginTasks(): readonly PendingLoginTask[] {
+    return this.#options.loginAssist.listPending()
+      .filter((task) => task.adapter === 'icqq' && task.endpointKey === this.endpointName);
+  }
+
+  #notifyOffline(reason: string, willRetry: boolean): void {
+    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: 'qrcode' | 'slider' | 'device' | 'auth'): void {
+    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(): void {
+    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: 'add' | 'remove', task: Promise<unknown> | unknown): void {
     void Promise.resolve(task).catch((error) => {
       this.#logger.debug(formatCompact({
@@ -270,6 +432,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
         `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;
@@ -304,6 +467,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   async stop(): Promise<void> {
     this.#stopped = true;
+    this.#clearReloginTimer();
     this.#assertExternalLifecycle('stop');
     this.#armRetirementFence();
     await Promise.allSettled([...this.#inflightInbound]);
@@ -354,7 +518,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     });
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<EndpointSendResult> {
     if (!this.#started) throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
     const prepared = isIcqqSegmentPayload(payload)
@@ -362,10 +526,10 @@ export class IcqqEndpoint extends Endpoint<Client> {
       : { 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: string | undefined;
-      for (const [index, message] of messages.entries()) {
+      const parts: EndpointSendPart[] = [];
+      for (const [index, { message, sourceIndices }] of messages.entries()) {
         const preview = formatIcqqSendablePreview(message);
         let result: { message_id?: unknown };
         try {
@@ -379,48 +543,30 @@ export class IcqqEndpoint extends Endpoint<Client> {
             preview: truncatePreview(preview, 120),
           }));
           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: () => Promise<readonly { message_id?: unknown; time?: number; message?: readonly { type?: string }[]; sender?: { user_id?: number }; user_id?: number }[]>,
-    sentAt: number,
-  ): Promise<string | undefined> {
-    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(
@@ -430,16 +576,14 @@ export class IcqqEndpoint extends Endpoint<Client> {
     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);
@@ -610,12 +754,16 @@ export class IcqqEndpoint extends Endpoint<Client> {
     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 / 终端确认后继续');
@@ -630,6 +778,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
     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);
@@ -640,6 +790,9 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.client.on('system.online', (event) => {
       if (this.#retiring) return;
       this.#everOnline = true;
+      this.#clearReloginTimer();
+      this.#reloginAttempts = 0;
+      this.#notifyRecovered();
       try {
         this.#resolveStartOnline?.();
         this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
@@ -703,6 +856,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
       ? event as Record<string, unknown>
       : null);
     this.#logSystemEvent(`login.${step}`, event);
+    this.#clearReloginTimer();
+    this.#notifyChallenge(step);
     void runIcqqLoginAssistStep({
       assist: this.#options.loginAssist,
       locale: this.#options.locale,
@@ -823,6 +978,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
       channelType: normalized.channelType,
       channelId: normalized.channelId,
       channelParentGroupId: normalized.channelParentGroupId,
+      name: normalized.groupName,
     });
     const quoteId = resolveIcqqQuoteIdFromEvent(data);
     const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
@@ -942,13 +1098,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   #onNoticeEvent(payload: Record<string, unknown> | null): void {
     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}`)) return;
+    if (!this.#sideEventDeduper.shouldProcess(icqqNoticeDedupeKey(payload))) return;
     this.#dispatchIcqqSideEvent(payload);
   }
 

package/src/group-moderation.ts

@@ -8,17 +8,22 @@ export async function inspectGroupMember(
   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/src/group-scene.ts

@@ -0,0 +1,76 @@
+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 const ADMIN_SCAN_MAX_MEMBERS = 1000;
+const MAX_ADMIN_IDS = 20;
+
+function positiveId(value: unknown): string | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+}
+
+function numericId(value: string): number {
+  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: Client, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts> {
+  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: string[] | undefined;
+  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 is string => 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: Client, groupId: string, userId: string, signal: AbortSignal,
+): Promise<GroupMemberProfile> {
+  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/src/icqq-inbound.ts

@@ -129,6 +129,8 @@ export interface NormalizedIcqqInbound {
   channelId: string;
   /** 群临时会话：来源群号 */
   channelParentGroupId?: string;
+  /** 群聊时来自 group_name */
+  groupName?: string;
   userId: string;
   nickname: string;
   /** 群聊时来自 sender.role（私聊无） */
@@ -847,6 +849,9 @@ export function normalizeIcqqInboundMessage(
     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/src/icqq-inbox.ts

@@ -20,6 +20,21 @@ export function isIcqqNoticePayload(payload: unknown): boolean {
     && (postType === 'notice' || postType.startsWith('notice.'));
 }
 
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export function icqqNoticeDedupeKey(payload: Record<string, unknown>): string {
+  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/src/icqq-login-control.ts

@@ -0,0 +1,30 @@
+/**
+ * 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';
+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 const icqqLoginControlToken = createToken<Map<string, IcqqLoginControl>>(
+  'zhin.icqq.login-control',
+  'ICQQ login control surface for recovery commands',
+);

package/src/index.ts

@@ -3,12 +3,14 @@ export {
   formatInboundContent,
   formatOutboundBody,
   formatOutboundMessages,
+  formatOutboundMessageParts,
   icqqInboundConversation,
   icqqOutboundTarget,
   type ActionResult,
   type IcqqEndpointConfig,
   type IcqqInboundMessage,
   type IcqqWireSegment,
+  type IcqqOutboundMessagePart,
   type ParsedIcqqSendTarget,
   type ResolvedIcqqConfig,
 } from './protocol.js';