@zhin.js/adapter-icqq 8.0.9 → 8.0.11

package/src/endpoint.ts

@@ -1,16 +1,20 @@
-/**
- * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
- */
+import {
+  Client,
+  parseGroupMessageId,
+  type Config as NativeIcqqClientConfig,
+  type Sendable,
+} from '@icqqjs/icqq';
+import { inspect } from 'node:util';
 import type {
   EndpointControl,
   EndpointInstance,
   EndpointManagement,
   EndpointSendRequest,
-} from '@zhin.js/adapter';
+} from 'zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
-import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import type { CapabilityId } from 'zhin.js';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
 import {
   InboundMessageDeduper,
@@ -21,8 +25,7 @@ import {
   quotedPayloadFromIcqqSource,
   resolveIcqqQuoteIdFromEvent,
   shouldSkipSelfInboundMessage,
-  unwrapIcqqIpcEventPayload,
-  type IcqqIpcMessageEvent,
+  type IcqqMessageEvent,
 } from './icqq-inbound.js';
 import {
   buildIcqqInboxNoticeRow,
@@ -33,45 +36,22 @@ import {
 } from './icqq-inbox.js';
 import {
   IcqqGuildCatalog,
-  isIcqqGuildIpcEvent,
   normalizeIcqqGuildInboundMessage,
 } from './icqq-guild.js';
-import { IpcClient } from './ipc-client.js';
 import {
   materializeOutboundBase64,
   resolveIcqqOutboundMediaMode,
 } from './outbound-media.js';
 import {
-  Actions,
   formatInboundContent,
   formatOutboundBody,
   icqqInboundConversation,
   icqqOutboundTarget,
   type IcqqInboundMessage,
-  type IpcEvent,
-  type IpcResponse,
   type ResolvedIcqqConfig,
 } from './protocol.js';
-import type { IpcFriendInfo, IpcGroupInfo, IpcMemberInfo, IpcSystemMessage } from './types.js';
-
-/** Minimal IPC surface used by the endpoint (real IpcClient or test mock). */
-export interface IcqqIpcTransport {
-  request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
-  subscribe(
-    action: string,
-    params: Record<string, unknown>,
-    handler: (event: IpcEvent) => void,
-  ): { unsubscribe: () => Promise<void> };
-  setOnRemoteDisconnect(handler: (() => void) | null): void;
-  close(): void;
-}
-
-export type CreateIcqqIpc = (config: ResolvedIcqqConfig) => Promise<IcqqIpcTransport>;
+import type { SystemMessage as IcqqSystemMessage } from './types.js';
 
-/**
- * 收件箱写/推钩子（由装配层注入，见 adapters/icqq.ts）。
- * record* 写 unified_inbox_request/notice；publish 向 console hub 推送实时事件。
- */
 export interface IcqqInboxHooks {
   recordRequest(row: Record<string, unknown>): void | Promise<void>;
   recordNotice(row: Record<string, unknown>): void | Promise<void>;
@@ -82,156 +62,156 @@ export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
   readonly config: ResolvedIcqqConfig;
-  readonly createIpc?: CreateIcqqIpc;
-  /** 未注入时 request/notice 事件仅按非消息载荷忽略（不报错）。 */
   readonly inbox?: IcqqInboxHooks;
 }
 
-export class IcqqIpcEndpoint implements EndpointInstance {
-  readonly #logger!: ReturnType<typeof getAdapterLogger>;
-
+const BOUND_EVENTS = [
+  'message.private',
+  'message.group',
+  'message.guild',
+  'request.friend',
+  'request.group',
+  'notice.friend',
+  'notice.group',
+  'system.online',
+  'system.offline',
+  'system.offline.network',
+  'system.offline.kickoff',
+  'system.login.qrcode',
+  'system.login.device',
+  'system.login.slider',
+  'system.login.error',
+  'system.login.auth',
+] as const;
+
+export class IcqqEndpoint extends Client implements EndpointInstance {
+  readonly #logger: ReturnType<typeof getAdapterLogger>;
   readonly #options: IcqqEndpointOptions;
-  readonly #createIpc: CreateIcqqIpc;
-  readonly name: string;
-  /** Populated after start(); agent tools read this. */
-  ipc!: IcqqIpcTransport;
-  readonly friends = new Map<number, IpcFriendInfo>();
-  readonly groups = new Map<number, IpcGroupInfo>();
+  readonly endpointName: string;
   readonly #guildCatalog = new IcqqGuildCatalog();
+  readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly #inboxDeduper = new InboundMessageDeduper();
+  #open = false;
+  #started = false;
+  #heldInbound: IcqqInboundMessage[] = [];
+  #unregisterAgent?: () => void;
+
   readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
-    listFriends: () => this.getFriendList(),
-    listGroups: () => this.getGroupList(),
+    listFriends: async () =>
+      Array.from(this.fl.values()).map((f) => ({
+        user_id: f.user_id,
+        nickname: f.nickname,
+        remark: f.remark ?? '',
+      })),
+    listGroups: async () =>
+      Array.from(this.gl.values()).map((g) => ({
+        group_id: g.group_id,
+        name: g.group_name,
+      })),
     listChannels: async () => {
-      await this.#guildCatalog.syncAll(this.ipc);
+      await this.#guildCatalog.syncAll(this);
       return this.#guildCatalog.getGuildChannelList();
     },
-    listGroupMembers: (groupId) => this.getGroupMemberList(groupId),
-    approveRequest: (requestId, remark) => this.approveRequest(requestId, remark),
-    rejectRequest: (requestId, reason) => this.rejectRequest(requestId, reason),
-    kickGroupMember: (groupId, userId) => this.removeMember(groupId, userId),
-    muteGroupMember: (groupId, userId, duration) => this.muteMember(groupId, userId, duration),
-    setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
-    deleteFriend: (userId) => this.deleteFriend(userId),
+    listGroupMembers: async (groupId) =>
+      Array.from((await this.getGroupMemberList(Number(groupId))).values()),
+    approveRequest: (requestId, remark) => this.#approveRequest(requestId, remark),
+    rejectRequest: (requestId, reason) => this.#rejectRequest(requestId, reason),
+    kickGroupMember: async (groupId, userId) => {
+      await this.setGroupKick(Number(groupId), Number(userId));
+    },
+    muteGroupMember: async (groupId, userId, duration) => {
+      await this.setGroupBan(Number(groupId), Number(userId), duration);
+    },
+    setGroupAdmin: async (groupId, userId, enabled) => {
+      await this.setGroupAdmin(Number(groupId), Number(userId), enabled);
+    },
+    deleteFriend: async (userId) => {
+      await this.deleteFriend(Number(userId));
+    },
   });
+
   readonly control: EndpointControl = Object.freeze({
-    recall: (message: MessageRef) => this.recallMessage(message.id),
-    addReaction: (message: MessageRef, emoji: string) => this.addReaction(message.id, emoji),
-    removeReaction: (message: MessageRef, reactionId: string) =>
-      this.removeReaction(message.id, reactionId),
+    recall: async (message: MessageRef) => {
+      if (!message.id || message.id.startsWith('outbound:')) return;
+      await this.deleteMsg(message.id);
+    },
+    addReaction: async (message: MessageRef, emoji: string) => {
+      const target = resolveIcqqGroupReactionTarget(message);
+      if (!target) return null;
+      try {
+        // Do not await protocol ACK — packet timeout must not stall the AI reply.
+        this.#ignoreReactionAck(
+          'add',
+          this.pickGroup(target.groupId).setReaction(target.seq, emoji),
+        );
+      } catch (error) {
+        this.#logger.debug(formatCompact({
+          op: 'reaction_add_failed',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+      return emoji;
+    },
+    removeReaction: async (message: MessageRef, reactionId: string) => {
+      const target = resolveIcqqGroupReactionTarget(message);
+      if (!target) return;
+      try {
+        this.#ignoreReactionAck(
+          'remove',
+          this.pickGroup(target.groupId).delReaction(target.seq, reactionId),
+        );
+      } catch (error) {
+        this.#logger.debug(formatCompact({
+          op: 'reaction_remove_failed',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    },
   });
-  #open = false;
-  #started = false;
-  #subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];
-  #inboundDeduper = new InboundMessageDeduper();
-  /** request/notice 去重（推送事件与 GET_SYSTEM_MSG 首拉可能重复同一 flag）。 */
-  #inboxDeduper = new InboundMessageDeduper();
-  #unregisterAgent?: () => void;
-  /** 用户主动 stop 时为 true，阻止自动重连 */
-  #intentionalDisconnect = false;
-  /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
-  #reconnectRunning = false;
 
   constructor(options: IcqqEndpointOptions) {
+    const nativeConfig = resolveNativeClientConfig(options.config);
+    super(Number(options.config.id), nativeConfig);
     this.#logger = getAdapterLogger('icqq', options.config.id);
     this.#options = options;
-    this.name = options.config.id;
-    this.#createIpc = options.createIpc ?? defaultCreateIpc;
+    this.endpointName = options.config.id;
   }
 
-  async request(action: string, params?: Record<string, unknown>): Promise<IpcResponse> {
-    if (!this.ipc) {
-      throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发起请求: ${action}`);
-    }
-    return this.ipc.request(action, params);
+  #ignoreReactionAck(action: 'add' | 'remove', task: Promise<unknown> | unknown): void {
+    void Promise.resolve(task).catch((error) => {
+      this.#logger.debug(formatCompact({
+        op: `reaction_${action}_failed`,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
   }
 
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
-    this.#intentionalDisconnect = false;
     try {
-      await this.#bindIpcSession();
-      this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
+      const onlineReady = new Promise<void>((resolve) => {
+        this.on('system.online', () => resolve());
+      });
+      this.#bindClientEvents();
+      await this.login(this.#options.config.password);
+      await onlineReady;
+      await this.#pullPendingSystemMessages();
+      this.#unregisterAgent = registerIcqqAgentEndpoint(this.endpointName, this);
       this.#logger.info(
-        `connected (${this.#options.config.rpc ? 'rpc' : 'ipc'}) | friends: ${this.friends.size} | groups: ${this.groups.size}`,
+        `connected (direct) | friends: ${this.fl.size} | groups: ${this.gl.size}`,
       );
     } catch (error) {
       await this.stop();
-      // Startup connect failures are surfaced once (with stack) by AdapterIndex;
-      // keep this at debug to avoid a duplicate error-level log.
-      this.#logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+      this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
       throw error;
     }
   }
 
-  /** 建立或恢复与守护进程的 IPC/RPC 会话（订阅、缓存列表） */
-  async #bindIpcSession(): Promise<void> {
-    // 旧连接上的订阅句柄已失效，不再对死 socket 发 unsubscribe
-    this.#subscriptions = [];
-    this.ipc = await this.#createIpc(this.#options.config);
-    if (this.#options.config.autoReconnect !== false) {
-      this.ipc.setOnRemoteDisconnect(() => this.#scheduleReconnect());
-    }
-    await this.#refreshLists();
-    const sub = this.ipc.subscribe(Actions.SUBSCRIBE, {}, (event) => {
-      this.#handleEvent(event);
-    });
-    this.#subscriptions.push(sub);
-    // daemon 推送 client.em 全部事件，request/notice 实时到达；
-    // 启动时补一次 GET_SYSTEM_MSG，捞离线期间积存的待处理请求。
-    void this.#pullPendingSystemMessages();
-  }
-
-  /** IPC/RPC 意外断开时调度重连（指数退避） */
-  #scheduleReconnect(): void {
-    if (this.#options.config.autoReconnect === false) return;
-    if (this.#intentionalDisconnect) return;
-    if (this.#reconnectRunning) return;
-    this.#reconnectRunning = true;
-    void this.#runReconnectLoop();
-  }
-
-  async #runReconnectLoop(): Promise<void> {
-    try {
-      for (let attempt = 0; !this.#intentionalDisconnect; attempt++) {
-        const base = Math.min(30_000, 500 * 2 ** Math.min(attempt, 6));
-        const jitter = Math.floor(Math.random() * 400);
-        const delayMs = base + jitter;
-        // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏
-        const disconnectLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
-        disconnectLog(formatCompact({
-          op: 'disconnect',
-          ok: false,
-          delay_ms: delayMs,
-          attempt: attempt + 1,
-        }));
-        await new Promise<void>((r) => setTimeout(r, delayMs));
-        if (this.#intentionalDisconnect) break;
-        try {
-          await this.#bindIpcSession();
-          this.#logger.info(
-            `reconnected after ${attempt + 1} attempt(s)`
-            + ` | friends: ${this.friends.size} | groups: ${this.groups.size}`,
-          );
-          break;
-        } catch (error) {
-          const retryLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
-          retryLog(formatCompact({
-            op: 'reconnect',
-            endpoint: this.name,
-            ok: false,
-            attempt: attempt + 1,
-            error: error instanceof Error ? error.message : String(error),
-          }));
-        }
-      }
-    } finally {
-      this.#reconnectRunning = false;
-    }
-  }
-
   open(): void {
     this.#open = true;
+    const held = this.#heldInbound.splice(0);
+    for (const msg of held) this.admit(msg);
   }
 
   close(): void {
@@ -239,409 +219,89 @@ export class IcqqIpcEndpoint implements EndpointInstance {
   }
 
   async stop(): Promise<void> {
-    this.#intentionalDisconnect = true;
     this.#open = false;
-    this.ipc?.setOnRemoteDisconnect(null);
-    for (const sub of this.#subscriptions.splice(0)) {
-      await sub.unsubscribe().catch(() => { /* ignore */ });
-    }
+    this.#heldInbound.length = 0;
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
+    for (const event of BOUND_EVENTS) this.off(event);
+    try {
+      await this.logout?.();
+    } catch { /* ignore */ }
+    try {
+      this.terminate();
+    } catch { /* ignore */ }
     this.#inboundDeduper.clear();
     this.#inboxDeduper.clear();
-    this.friends.clear();
-    this.groups.clear();
     this.#guildCatalog.clear();
-    try {
-      this.ipc?.close();
-    } catch {
-      /* ignore */
-    }
-    // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
-    this.ipc = undefined as unknown as IcqqIpcTransport;
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    if (!this.ipc) {
-      throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
-    }
+    if (!this.#started) throw new Error('icqq endpoint 未连接');
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
     const content = Array.isArray(payload)
       ? materializeOutboundBase64(payload, mediaMode)
       : payload;
     const message = formatOutboundBody(content);
     const parsed = icqqOutboundTarget(conversation);
-    let action: string;
-    let params: Record<string, unknown>;
-    switch (parsed.kind) {
-      case 'private':
-        action = Actions.SEND_PRIVATE_MSG;
-        params = { user_id: parsed.userId, message };
-        break;
-      case 'group':
-        action = Actions.SEND_GROUP_MSG;
-        params = { group_id: parsed.groupId, message };
-        break;
-      case 'temp':
-        action = Actions.SEND_TEMP_MSG;
-        params = {
-          group_id: parsed.groupId,
-          user_id: parsed.userId,
-          message,
-        };
-        break;
-      case 'channel':
-        action = Actions.GUILD_SEND_MSG;
-        params = {
-          guild_id: parsed.guildId,
-          channel_id: parsed.channelId,
-          message,
-        };
-        break;
-    }
-    const resp = await this.ipc.request(action, params);
-    if (!resp.ok) {
-      this.#logger.warn(
-        `send failed ${conversation.kind}:${conversation.id} | ${resp.error} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
-      );
-      throw new Error(`发送消息失败: ${resp.error}`);
-    }
-    const messageId = String(
-      (resp.data as { message_id?: unknown } | undefined)?.message_id ?? `sent_${Date.now()}`,
-    );
-    this.#logger.info(
-      `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
-    );
-    return messageId;
-  }
-
-  // ── 消息回应（activity-feedback / typing reaction）────────────────────
-
-  private static readonly EMOJI_MAP: Record<string, string> = {
-    '⏳': '1468368274',
-    '👍': '128077',
-    '❤️': '10084',
-    '😊': '128522',
-    '🎉': '127881',
-    '🔥': '128293',
-    '✅': '9989',
-    '❌': '10060',
-    '⭐': '11088',
-    '💯': '128175',
-  };
-
-  private getEmojiId(emoji: string): string {
-    if (/^\d+$/u.test(emoji)) return emoji;
-    return IcqqIpcEndpoint.EMOJI_MAP[emoji] ?? String(emoji.codePointAt(0) || 0);
-  }
-
-  /** Activity-feedback / OutboundHost reaction surface. */
-  async addReaction(messageId: string, emoji: string): Promise<string | null> {
-    try {
-      const emojiId = this.getEmojiId(emoji);
-      const resp = await this.request(Actions.GROUP_SET_REACTION, {
-        message_id: messageId,
-        id: emojiId,
-      });
-      if (!resp.ok) {
-        this.#logger.warn(formatCompact({
-          op: 'add_reaction',
-          endpoint: this.name,
-          message_id: messageId,
-          emoji,
-          id: emojiId,
-          ok: false,
-          error: resp.error,
-        }));
-        return null;
-      }
-      this.#logger.debug(formatCompact({
-        op: 'add_reaction',
-        endpoint: this.name,
-        message_id: messageId,
-        emoji,
-        id: emojiId,
-        ok: true,
-      }));
-      return emojiId;
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'add_reaction',
-        endpoint: this.name,
-        message_id: messageId,
-        emoji,
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-      return null;
-    }
-  }
-
-  async removeReaction(messageId: string, reactionId: string): Promise<void> {
-    try {
-      const parts = reactionId.split('_');
-      const emojiId = parts.length >= 2 ? parts[1]! : reactionId;
-      const resp = await this.request(Actions.GROUP_DEL_REACTION, {
-        message_id: messageId,
-        id: emojiId,
-      });
-      if (!resp.ok) {
-        this.#logger.warn(formatCompact({
-          op: 'remove_reaction',
-          endpoint: this.name,
-          message_id: messageId,
-          reaction_id: reactionId,
-          id: emojiId,
-          ok: false,
-          error: resp.error,
-        }));
-        return;
-      }
-      this.#logger.debug(formatCompact({
-        op: 'remove_reaction',
-        endpoint: this.name,
-        message_id: messageId,
-        reaction_id: reactionId,
-        id: emojiId,
-        ok: true,
-      }));
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'remove_reaction',
-        endpoint: this.name,
-        message_id: messageId,
-        reaction_id: reactionId,
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
-
-  /** Activity-feedback autoRemove / Console recall. */
-  async recallMessage(messageId: string): Promise<void> {
-    if (!messageId || messageId.startsWith('outbound:')) return;
+    let result: { message_id?: unknown };
     try {
-      const resp = await this.request(Actions.RECALL_MSG, { message_id: messageId });
-      if (!resp.ok) {
-        this.#logger.warn(formatCompact({
-          op: 'recall_message',
-          endpoint: this.name,
-          message_id: messageId,
-          ok: false,
-          error: resp.error,
-        }));
-        return;
+      switch (parsed.kind) {
+        case 'private':
+          result = await this.sendPrivateMsg(parsed.userId, message as Sendable);
+          break;
+        case 'group':
+          result = await this.sendGroupMsg(parsed.groupId, message as Sendable);
+          break;
+        case 'temp':
+          result = await this.sendTempMsg(parsed.groupId, parsed.userId, message as Sendable);
+          break;
+        case 'channel':
+          result = await this.sendGuildMsg(parsed.guildId, parsed.channelId, message as Sendable) as unknown as { message_id?: unknown };
+          break;
       }
-      this.#logger.debug(formatCompact({
-        op: 'recall_message',
-        endpoint: this.name,
-        message_id: messageId,
-        ok: true,
-      }));
     } catch (error) {
       this.#logger.warn(formatCompact({
-        op: 'recall_message',
-        endpoint: this.name,
-        message_id: messageId,
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
+        op: 'icqq_send_failed',
+        target: `${conversation.kind}:${conversation.id}`,
+        error: describeUnknownError(error),
+        preview: truncatePreview(typeof message === 'string' ? message : String(message), 120),
       }));
+      throw error;
     }
-  }
-
-  // ── 社交/群管（Console endpoint RPC 探测面）────────────────────────
-  // console-rpc-extended.ts 按方法名探测这些接口；全部薄封装走 IPC daemon。
-
-  /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
-  async getFriendList(): Promise<Array<{ user_id: number; nickname: string; remark: string }>> {
-    const resp = await this.#mustRequest(Actions.LIST_FRIENDS, undefined, '获取好友列表');
-    const list = Array.isArray(resp.data) ? (resp.data as IpcFriendInfo[]) : [];
-    return list.map((f) => ({
-      user_id: f.user_id,
-      nickname: f.nickname,
-      remark: f.remark ?? '',
-    }));
-  }
-
-  /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
-  async getGroupList(): Promise<Array<{ group_id: number; name: string }>> {
-    const resp = await this.#mustRequest(Actions.LIST_GROUPS, undefined, '获取群列表');
-    const list = Array.isArray(resp.data) ? (resp.data as IpcGroupInfo[]) : [];
-    return list.map((g) => ({
-      group_id: g.group_id,
-      name: g.group_name,
-    }));
-  }
-
-  /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
-  async getGroupMemberList(groupId: number | string): Promise<IpcMemberInfo[]> {
-    const resp = await this.#mustRequest(
-      Actions.LIST_GROUP_MEMBERS,
-      { group_id: toNumericId(groupId, 'group_id') },
-      '获取群成员列表',
-    );
-    return Array.isArray(resp.data) ? (resp.data as IpcMemberInfo[]) : [];
-  }
-
-  /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
-  listMembers(groupId: number | string): Promise<IpcMemberInfo[]> {
-    return this.getGroupMemberList(groupId);
-  }
-
-  getMemberList(groupId: number | string): Promise<IpcMemberInfo[]> {
-    return this.getGroupMemberList(groupId);
-  }
-
-  /**
-   * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
-   * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
-   */
-  async approveRequest(id: string, remark?: string): Promise<void> {
-    await this.#handleSystemRequest(id, true, { remark });
-  }
-
-  async rejectRequest(id: string, reason?: string): Promise<void> {
-    await this.#handleSystemRequest(id, false, { reason });
-  }
-
-  /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
-  async deleteFriend(userId: number | string): Promise<void> {
-    await this.#mustRequest(
-      Actions.FRIEND_DELETE,
-      { user_id: toNumericId(userId, 'user_id') },
-      '删除好友',
-    );
-  }
-
-  /** deleteFriend 别名（console 探测 delete_friend）。 */
-  delete_friend(userId: number | string): Promise<void> {
-    return this.deleteFriend(userId);
-  }
-
-  /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
-  async removeMember(groupId: number | string, userId: number | string): Promise<void> {
-    await this.#mustRequest(
-      Actions.GROUP_KICK,
-      { group_id: toNumericId(groupId, 'group_id'), user_id: toNumericId(userId, 'user_id') },
-      '踢出群成员',
-    );
-  }
-
-  kickMember(groupId: number | string, userId: number | string): Promise<void> {
-    return this.removeMember(groupId, userId);
-  }
-
-  setGroupKick(groupId: number | string, userId: number | string): Promise<void> {
-    return this.removeMember(groupId, userId);
-  }
-
-  /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
-  async muteMember(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
-    await this.#mustRequest(
-      Actions.GROUP_MUTE,
-      {
-        group_id: toNumericId(groupId, 'group_id'),
-        user_id: toNumericId(userId, 'user_id'),
-        duration,
-      },
-      '禁言群成员',
-    );
-  }
-
-  banMember(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
-    return this.muteMember(groupId, userId, duration);
-  }
-
-  setGroupMute(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
-    return this.muteMember(groupId, userId, duration);
-  }
-
-  /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
-  async setModerator(groupId: number | string, userId: number | string, enable = true): Promise<void> {
-    await this.#mustRequest(
-      Actions.SET_GROUP_ADMIN,
-      {
-        group_id: toNumericId(groupId, 'group_id'),
-        user_id: toNumericId(userId, 'user_id'),
-        enable,
-      },
-      '设置群管理员',
+    const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+    this.#logger.info(
+      `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
     );
+    return messageId;
   }
 
-  setAdmin(groupId: number | string, userId: number | string, enable = true): Promise<void> {
-    return this.setModerator(groupId, userId, enable);
-  }
-
-  setGroupAdmin(groupId: number | string, userId: number | string, enable = true): Promise<void> {
-    return this.setModerator(groupId, userId, enable);
-  }
-
-  /** IPC 请求并统一错误上下文：daemon 返回 ok=false 时抛出带操作名的错误。 */
-  async #mustRequest(
-    action: string,
-    params: Record<string, unknown> | undefined,
-    label: string,
-  ): Promise<IpcResponse> {
-    const resp = await this.request(action, params);
-    if (!resp.ok) {
-      throw new Error(`icqq ${label}失败: ${resp.error ?? 'daemon 未返回错误详情'}`);
-    }
-    return resp;
-  }
-
-  /** 按 flag/seq 在 GET_SYSTEM_MSG 中定位请求，路由到好友/群请求处理 action。 */
-  async #handleSystemRequest(
-    id: string,
-    approve: boolean,
-    extra: { remark?: string; reason?: string },
-  ): Promise<void> {
-    const resp = await this.#mustRequest(Actions.GET_SYSTEM_MSG, undefined, '获取待处理请求');
-    const data = resp.data as
-      | { friendRequests?: unknown; groupRequests?: unknown }
-      | undefined;
-    const friendRequests = Array.isArray(data?.friendRequests)
-      ? (data.friendRequests as IpcSystemMessage[])
-      : [];
-    const groupRequests = Array.isArray(data?.groupRequests)
-      ? (data.groupRequests as IpcSystemMessage[])
-      : [];
-    const matches = (m: IpcSystemMessage): boolean =>
-      m.flag === id || (m.seq != null && String(m.seq) === id);
-    const friend = friendRequests.find(matches);
-    const group = friend ? undefined : groupRequests.find(matches);
-    const target = friend ?? group;
-    if (!target?.flag) {
-      throw new Error(`icqq 未找到待处理请求: ${id}（GET_SYSTEM_MSG 中无匹配 flag/seq）`);
-    }
-    const params: Record<string, unknown> = { flag: target.flag, approve };
-    if (friend) {
-      if (extra.remark) params.remark = extra.remark;
-      await this.#mustRequest(Actions.HANDLE_FRIEND_REQUEST, params, '处理好友请求');
-    } else {
-      if (extra.reason) params.reason = extra.reason;
-      await this.#mustRequest(Actions.HANDLE_GROUP_REQUEST, params, '处理群请求');
-    }
-  }
-
-  /** Test / internal: admit when open. */
   admit(msg: IcqqInboundMessage): void {
     const conversation = msg.conversation;
     if (!this.#open) {
-      this.#logger.debug(formatCompact({
-        op: 'icqq_inbound_skip',
-        reason: 'endpoint_closed',
-        endpoint: this.name,
-        id: msg.id,
-        target: `${conversation.kind}:${conversation.id}`,
-      }));
+      if (this.#heldInbound.length >= INBOUND_HOLD_LIMIT) {
+        const dropped = this.#heldInbound.shift();
+        this.#logger.warn(formatCompact({
+          op: 'icqq_inbound_hold_drop',
+          endpoint: this.endpointName,
+          id: dropped?.id,
+          target: dropped
+            ? `${dropped.conversation.kind}:${dropped.conversation.id}`
+            : undefined,
+          limit: INBOUND_HOLD_LIMIT,
+        }));
+      }
+      this.#heldInbound.push(msg);
+      this.#logger.info(
+        `hold ${conversation.kind}:${conversation.id}`
+        + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
+        + ` until open | ${truncatePreview(msg.content, 80)}`,
+      );
       return;
     }
-    // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）经结构化段 / metadata 传递
     const mentioned = isIcqqBotMentioned({
-      uin: this.name,
+      uin: this.endpointName,
       content: msg.segments,
       rawMessage: msg.content,
     });
@@ -659,7 +319,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       content: msg.content,
       ...(msg.segments ? { segments: msg.segments } : {}),
       sender: msg.sender,
-      endpointId: this.name,
+      endpointId: this.endpointName,
       ...(mentioned ? { mentioned: true } : {}),
       ...(quoteId ? { replyTo: { id: String(quoteId) } } : {}),
       metadata: Object.freeze({
@@ -669,7 +329,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }).catch((err) => {
       this.#logger.warn(formatCompact({
         op: 'recv',
-        endpoint: this.name,
+        endpoint: this.endpointName,
         target: `${conversation.kind}:${conversation.id}`,
         ok: false,
         error: err instanceof Error ? err.message : String(err),
@@ -677,47 +337,64 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     });
   }
 
-  async #refreshLists(): Promise<void> {
-    const [flResp, glResp] = await Promise.all([
-      this.ipc.request(Actions.LIST_FRIENDS),
-      this.ipc.request(Actions.LIST_GROUPS),
-    ]);
-    this.friends.clear();
-    if (flResp.ok && Array.isArray(flResp.data)) {
-      for (const f of flResp.data as IpcFriendInfo[]) {
-        this.friends.set(f.user_id, f);
-      }
-    }
-    this.groups.clear();
-    if (glResp.ok && Array.isArray(glResp.data)) {
-      for (const g of glResp.data as IpcGroupInfo[]) {
-        this.groups.set(g.group_id, g);
+  #bindClientEvents(): void {
+    const safe = (label: string, fn: () => void): void => {
+      try {
+        fn();
+      } catch (error) {
+        this.#logger.warn(formatCompact({
+          op: 'icqq_event_handler',
+          endpoint: this.endpointName,
+          event: label,
+          error: error instanceof Error ? error.message : String(error),
+        }));
       }
-    }
+    };
+    this.on('message.private', (event) => safe('message.private', () => this.#handleMessageEvent('message.private', event)));
+    this.on('message.group', (event) => safe('message.group', () => this.#handleMessageEvent('message.group', event)));
+    this.on('message.guild', (event) => safe('message.guild', () => this.#handleGuildEvent(event)));
+    this.on('request.friend', (event) => safe('request.friend', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
+    this.on('request.group', (event) => safe('request.group', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
+    this.on('notice.friend', (event) => safe('notice.friend', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
+    this.on('notice.group', (event) => safe('notice.group', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
+    this.on('system.offline', (event) => this.#logSystemEvent('offline', event));
+    this.on('system.offline.network', (event) => this.#logSystemEvent('offline.network', event));
+    this.on('system.offline.kickoff', (event) => this.#logSystemEvent('offline.kickoff', event));
+    this.on('system.login.qrcode', () => {
+      this.#logger.info('icqq 收到二维码登录事件，请按 icqq 默认流程扫码后继续登录');
+    });
+    this.on('system.login.device', (event) => this.#logSystemEvent('login.device', event));
+    this.on('system.login.slider', (event) => this.#logSystemEvent('login.slider', event));
+    this.on('system.login.error', (event) => this.#logSystemEvent('login.error', event));
+    this.on('system.login.auth', (event) => this.#logSystemEvent('login.auth', event));
+  }
+
+  #logSystemEvent(type: string, event: unknown): void {
+    const payload = serializeIcqqEvent(event);
+    this.#logger.warn(formatCompact({
+      op: `system.${type}`,
+      endpoint: this.endpointName,
+      ...(payload ? { event: JSON.stringify(payload) } : {}),
+    }));
   }
 
-  #handleEvent(event: IpcEvent): void {
-    if (isIcqqGuildIpcEvent(event.event)) {
-      this.#handleGuildEvent(event);
-      return;
-    }
-    const payload = unwrapIcqqIpcEventPayload(event);
-    if (!payload || typeof payload !== 'object') return;
-    if (isIcqqRequestPayload(payload)) {
-      this.#recordInboxRequest(payload as Record<string, unknown>);
-      return;
-    }
-    if (isIcqqNoticePayload(payload)) {
-      this.#recordInboxNotice(payload as Record<string, unknown>);
+  #handleMessageEvent(eventName: 'message.private' | 'message.group', event: unknown): void {
+    const payload = serializeIcqqEvent(event);
+    if (!payload || !isIcqqMessagePostType(payload)) {
+      this.#logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: payload ? 'not_message_post' : 'serialize_failed',
+        endpoint: this.endpointName,
+        event: eventName,
+      }));
       return;
     }
-    if (!isIcqqMessagePostType(payload)) return;
-    const data = payload as IcqqIpcMessageEvent;
+    const data = payload as IcqqMessageEvent;
     if (shouldSkipSelfInboundMessage(data)) {
       this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'self',
-        endpoint: this.name,
+        endpoint: this.endpointName,
         user_id: data.user_id,
         self_id: data.self_id,
       }));
@@ -728,9 +405,9 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'normalize_failed',
-        endpoint: this.name,
+        endpoint: this.endpointName,
+        event: eventName,
         message_id: data.message_id,
-        message_type: data.message_type ?? data.type,
       }));
       return;
     }
@@ -738,7 +415,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'dedupe',
-        endpoint: this.name,
+        endpoint: this.endpointName,
         id: normalized.messageId,
       }));
       return;
@@ -765,8 +442,8 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     });
   }
 
-  #handleGuildEvent(event: IpcEvent): void {
-    const payload = event.data;
+  #handleGuildEvent(event: unknown): void {
+    const payload = serializeIcqqEvent(event);
     if (!payload || typeof payload !== 'object') return;
     const normalized = normalizeIcqqGuildInboundMessage(
       payload as Parameters<typeof normalizeIcqqGuildInboundMessage>[0],
@@ -775,7 +452,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'guild_normalize_failed',
-        endpoint: this.name,
+        endpoint: this.endpointName,
       }));
       return;
     }
@@ -784,7 +461,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'dedupe',
-        endpoint: this.name,
+        endpoint: this.endpointName,
         id: `guild:${normalized.messageId}`,
       }));
       return;
@@ -807,13 +484,8 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     });
   }
 
-  /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
-  #inboxBase(): { adapter: string; endpointKey: string } {
-    const id = String(this.#options.id);
-    return { adapter: id.split('\0').pop() ?? id, endpointKey: this.name };
-  }
-
-  #recordInboxRequest(payload: Record<string, unknown>): void {
+  #recordInboxRequest(payload: Record<string, unknown> | null): void {
+    if (!payload || !isIcqqRequestPayload(payload)) return;
     const hooks = this.#options.inbox;
     if (!hooks) return;
     const row = buildIcqqInboxRequestRow(payload, this.#inboxBase());
@@ -823,7 +495,8 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     hooks.publish?.('endpoint:request', row);
   }
 
-  #recordInboxNotice(payload: Record<string, unknown>): void {
+  #recordInboxNotice(payload: Record<string, unknown> | null): void {
+    if (!payload || !isIcqqNoticePayload(payload)) return;
     const hooks = this.#options.inbox;
     if (!hooks) return;
     const row = buildIcqqInboxNoticeRow(payload, this.#inboxBase());
@@ -833,26 +506,29 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     hooks.publish?.('endpoint:notice', row);
   }
 
-  /** 启动/重连后首拉 GET_SYSTEM_MSG：补录离线期间的好友/群待处理请求。 */
+  #inboxBase(): { adapter: string; endpointKey: string } {
+    const id = String(this.#options.id);
+    return { adapter: id.split('\0').pop() ?? id, endpointKey: this.endpointName };
+  }
+
   async #pullPendingSystemMessages(): Promise<void> {
     const hooks = this.#options.inbox;
-    if (!hooks || !this.ipc) return;
+    if (!hooks) return;
     try {
-      const resp = await this.ipc.request(Actions.GET_SYSTEM_MSG);
-      if (!resp.ok) return;
-      const data = resp.data as
-        | { friendRequests?: unknown; groupRequests?: unknown }
-        | undefined;
+      const messages = await this.getSystemMsg();
+      const friendRequests: IcqqSystemMessage[] = [];
+      const groupRequests: IcqqSystemMessage[] = [];
+      for (const msg of messages) {
+        if ((msg as { request_type?: string }).request_type === 'friend') {
+          friendRequests.push(msg as unknown as IcqqSystemMessage);
+        } else {
+          groupRequests.push(msg as unknown as IcqqSystemMessage);
+        }
+      }
       const base = this.#inboxBase();
       const rows = [
-        ...(Array.isArray(data?.friendRequests)
-          ? (data.friendRequests as IpcSystemMessage[]).map((m) =>
-            buildIcqqSystemRequestRow(m, 'friend', base))
-          : []),
-        ...(Array.isArray(data?.groupRequests)
-          ? (data.groupRequests as IpcSystemMessage[]).map((m) =>
-            buildIcqqSystemRequestRow(m, 'group', base))
-          : []),
+        ...friendRequests.map((m) => buildIcqqSystemRequestRow(m, 'friend', base)),
+        ...groupRequests.map((m) => buildIcqqSystemRequestRow(m, 'group', base)),
       ];
       for (const row of rows) {
         if (!row) continue;
@@ -863,20 +539,94 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     } catch (error) {
       this.#logger.debug(formatCompact({
         op: 'inbox_pull_system_msg',
-        endpoint: this.name,
+        endpoint: this.endpointName,
         error: error instanceof Error ? error.message : String(error),
       }));
     }
   }
+
+  async #approveRequest(id: string, remark?: string): Promise<void> {
+    const messages = await this.getSystemMsg();
+    const target = messages.find((m) => {
+      const msg = m as unknown as IcqqSystemMessage;
+      return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
+    }) as unknown as IcqqSystemMessage | undefined;
+    if (!target?.flag) {
+      throw new Error(`icqq 未找到待处理请求: ${id}`);
+    }
+    if ((target as { request_type?: string }).request_type === 'friend') {
+      await this.setFriendAddRequest(target.flag, true, remark);
+    } else {
+      await this.setGroupAddRequest(target.flag, true);
+    }
+  }
+
+  async #rejectRequest(id: string, reason?: string): Promise<void> {
+    const messages = await this.getSystemMsg();
+    const target = messages.find((m) => {
+      const msg = m as unknown as IcqqSystemMessage;
+      return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
+    }) as unknown as IcqqSystemMessage | undefined;
+    if (!target?.flag) {
+      throw new Error(`icqq 未找到待处理请求: ${id}`);
+    }
+    if ((target as { request_type?: string }).request_type === 'friend') {
+      await this.setFriendAddRequest(target.flag, false);
+    } else {
+      await this.setGroupAddRequest(target.flag, false, reason);
+    }
+  }
+}
+
+function describeUnknownError(error: unknown): string {
+  if (error instanceof Error) return error.stack ?? error.message;
+  if (error && typeof error === 'object') {
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return inspect(error, { depth: 4, breakLength: 120 });
+    }
+  }
+  return String(error);
+}
+
+function resolveIcqqGroupReactionTarget(
+  message: MessageRef,
+): { groupId: number; seq: number } | null {
+  if (message.conversation.kind !== 'group') return null;
+  const groupId = Number(message.conversation.id);
+  if (!Number.isFinite(groupId) || groupId <= 0) return null;
+  const raw = message.id?.trim();
+  if (!raw || raw.startsWith('outbound:')) return null;
+  if (/^[1-9]\d*$/.test(raw)) return { groupId, seq: Number(raw) };
+  try {
+    const parsed = parseGroupMessageId(raw);
+    if (parsed.seq > 0) return { groupId: parsed.group_id || groupId, seq: parsed.seq };
+  } catch {
+    // not a cqhttp group message id
+  }
+  return null;
+}
+
+function resolveNativeClientConfig(config: ResolvedIcqqConfig): NativeIcqqClientConfig {
+  return {
+    log_level: 'info',
+    platform: config.platform,
+    ...(config.ver ? { ver: config.ver } : {}),
+    ...(config.dataDir ? { data_dir: config.dataDir } : {}),
+    ...(config.signApiAddr ? { sign_api_addr: config.signApiAddr } : {}),
+    ...(config.ignoreSelf != null ? { ignore_self: config.ignoreSelf } : {}),
+    ...(config.resend != null ? { resend: config.resend } : {}),
+    ...(config.cacheGroupMember != null ? { cache_group_member: config.cacheGroupMember } : {}),
+    ...(config.autoServer != null ? { auto_server: config.autoServer } : {}),
+    ...(config.qqnt != null ? { QQNT: config.qqnt } : {}),
+    ...(config.ntLogin != null ? { NTLogin: config.ntLogin } : {}),
+    reconn_interval: config.autoReconnect ? 5 : 0,
+  };
 }
 
-/**
- * 组装入站 metadata：在基础字段上补充 quote 链路信息。
- * - quote_id：被引用消息 id（resolveIcqqQuoteIdFromEvent，无则不写）
- * - quote_sender_id / quote_sender_name / quote_content：source 可用时的平铺摘要
- */
 function buildIcqqQuoteMetadata(
-  data: IcqqIpcMessageEvent,
+  data: IcqqMessageEvent,
   base: Record<string, unknown>,
 ): Record<string, unknown> {
   const metadata: Record<string, unknown> = { ...base };
@@ -901,19 +651,27 @@ function buildIcqqQuoteMetadata(
   return metadata;
 }
 
-/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
-function toNumericId(value: number | string, label: string): number {
-  const n = Number(value);
-  if (!Number.isFinite(n) || String(value).trim() === '') {
-    throw new TypeError(`icqq ${label} 必须是数字: ${String(value)}`);
-  }
-  return n;
-}
+const INBOUND_HOLD_LIMIT = 32;
+
+const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'] as const;
 
-async function defaultCreateIpc(config: ResolvedIcqqConfig): Promise<IcqqIpcTransport> {
-  const uin = Number(config.id);
-  if (config.rpc) {
-    return IpcClient.connectRpc(config.rpc);
+function serializeIcqqEvent(event: unknown): Record<string, unknown> | null {
+  if (!event || typeof event !== 'object') return null;
+  const nativeToJSON = (event as { toJSON?: (keys: string[]) => unknown }).toJSON;
+  if (typeof nativeToJSON === 'function') {
+    try {
+      const json = nativeToJSON.call(event, [...ICQQ_SERIALIZE_SKIP]);
+      if (json && typeof json === 'object' && !Array.isArray(json)) {
+        return json as Record<string, unknown>;
+      }
+    } catch {
+      /* JSON.stringify 也会无参调 toJSON，不能当回退 */
+    }
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(event as Record<string, unknown>)) {
+    if (typeof value === 'function' || (ICQQ_SERIALIZE_SKIP as readonly string[]).includes(key)) continue;
+    out[key] = value;
   }
-  return IpcClient.connect(uin);
+  return Object.keys(out).length > 0 ? out : null;
 }