@zhin.js/adapter-icqq 6.0.2 → 6.0.3

package/src/endpoint.ts

@@ -1,846 +1,307 @@
 /**
- * ICQQ Bot：通过 @icqqjs/cli 守护进程 IPC 通信，实现 zhin Endpoint 接口
- *
- * 不再直接依赖 @icqqjs/icqq 协议库。
- * 登录由 `icqq login` 完成，本 Endpoint 只负责连接守护进程并收发消息。
+ * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import { formatCompact, Endpoint, Message, segment, SendContent, SendOptions, expandInteractiveSegmentsInContent, resolveSideEventDedupeKey, type QuotedMessagePayload,} from 'zhin.js';
-import type {
-  IcqqEndpointConfig,
-  IcqqSenderInfo,
-  IpcFriendInfo,
-  IpcGroupInfo,
-  IpcMemberInfo,
-} from "./types.js";
-import type { IcqqAdapter } from "./adapter.js";
-import { IpcClient } from "./ipc-client.js";
-import { Actions, type IpcEvent, type IpcGuildMessageEventData } from './protocol.js';
-import { findIcqqNestedMessageSource, InboundMessageDeduper, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveQuoteIdFromIcqqSource, shouldSkipSelfInboundMessage, unwrapIcqqIpcEventPayload, type IcqqIpcMessageEvent, type NormalizedIcqqInbound } from './icqq-inbound.js';
-
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
 import {
-  buildIcqqIpcMessage as buildIcqqIpcMessageImpl,
-  parseCqMessage as parseCqMessageImpl,
-  toCqString as toCqStringImpl,
-} from "./cq-message.js";
+  InboundMessageDeduper,
+  findIcqqNestedMessageSource,
+  isIcqqBotMentioned,
+  isIcqqMessagePostType,
+  normalizeIcqqInboundMessage,
+  quotedPayloadFromIcqqSource,
+  resolveIcqqQuoteIdFromEvent,
+  shouldSkipSelfInboundMessage,
+  unwrapIcqqIpcEventPayload,
+  type IcqqIpcMessageEvent,
+} from './icqq-inbound.js';
+import {
+  isIcqqGuildIpcEvent,
+  normalizeIcqqGuildInboundMessage,
+} from './icqq-guild.js';
+import { IpcClient } from './ipc-client.js';
 import {
   materializeOutboundBase64,
   resolveIcqqOutboundMediaMode,
-} from "./outbound-media.js";
-import {
-  formatIcqqMetaLog,
-  formatIcqqNotice,
-  formatIcqqRequest,
-  isIcqqMetaPayload,
-  isIcqqNoticePayload,
-  isIcqqRequestPayload,
-  resolveIcqqEventPostType,
-  shouldRefreshListsOnMeta,
-  type IcqqIpcRawEvent,
-} from "./icqq-side-events.js";
+} from './outbound-media.js';
 import {
-  disposeIcqqLoginAssistBridge,
-  handleIcqqLoginIpcEvent,
-} from "./icqq-login-assist-bridge.js";
-import { parseIcqqGetMsgResponse } from "./get-msg.js";
-import { enrichQuotedPayloadWithForward, isForwardPlaceholderPayload } from "./forward-msg.js";
-import {
-  IcqqGuildCatalog,
-  isIcqqGuildIpcEvent,
-  normalizeIcqqGuildInboundMessage,
-  type NormalizedIcqqGuildInbound,
-} from "./icqq-guild.js";
+  Actions,
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundBody,
+  parseSendTarget,
+  type IcqqInboundMessage,
+  type IpcEvent,
+  type IpcResponse,
+  type ResolvedIcqqConfig,
+} from './protocol.js';
+import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+
+const logger = getLogger('icqq');
+
+/** 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 class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessageEvent> {
-  $connected = false;
-  $config: IcqqEndpointConfig;
-  ipc!: IpcClient;
+export type CreateIcqqIpc = (config: ResolvedIcqqConfig) => Promise<IcqqIpcTransport>;
 
-  /** 缓存的好友列表 */
-  friends = new Map<number, IpcFriendInfo>();
-  /** 缓存的群列表 */
-  groups = new Map<number, IpcGroupInfo>();
-  /** QQ 频道（guild）子频道缓存 */
-  readonly guildCatalog = new IcqqGuildCatalog();
+export interface IcqqEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly config: ResolvedIcqqConfig;
+  readonly createIpc?: CreateIcqqIpc;
+}
 
-  private subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];
-  /** 事件去重：覆盖多端回流/服务端重复推送等场景 */
-  private readonly inboundDeduper = new InboundMessageDeduper();
-  /** MessageEvent.source 解析结果，供 $getMsg 优先命中 */
-  private readonly quotedSourceCache = new Map<string, QuotedMessagePayload>();
-  /** 用户主动断开时为 true，阻止自动重连 */
-  private intentionalDisconnect = false;
+export class IcqqIpcEndpoint implements EndpointInstance {
+  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>();
+  #open = false;
+  #started = false;
+  #subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];
+  #inboundDeduper = new InboundMessageDeduper();
+  #unregisterAgent?: () => void;
+  /** 用户主动 stop 时为 true，阻止自动重连 */
+  #intentionalDisconnect = false;
   /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
-  private reconnectRunning = false;
+  #reconnectRunning = false;
 
-  get $id() {
-    return this.$config.name;
+  constructor(options: IcqqEndpointOptions) {
+    this.#options = options;
+    this.name = options.config.name;
+    this.#createIpc = options.createIpc ?? defaultCreateIpc;
   }
 
-  get logger() {
-    return this.adapter.plugin.logger;
-  }
-
-  constructor(
-    public adapter: IcqqAdapter,
-    config: IcqqEndpointConfig,
-  ) {
-    this.$config = config;
+  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);
   }
 
-  // ── 连接 ───────────────────────────────────────────────────────────
-
-  async $connect(): Promise<void> {
-    this.intentionalDisconnect = false;
-    const rpc = this.$config.rpc;
-
-    this.logger.debug(formatCompact( {
-      connecting: this.$id,
-      mode: rpc ? "rpc" : "ipc",
-      host: rpc?.host,
-      port: rpc?.port,
-    }));
-
-    await this.rebindIpcSession();
-
-    this.logger.debug(formatCompact( {
-      机器人: this.$id,
-      好友数: this.friends.size,
-      群组数: this.groups.size,
-    }));
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    this.#intentionalDisconnect = false;
+    try {
+      await this.#bindIpcSession();
+      this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
+      logger.info(formatCompact({
+        op: 'connect',
+        endpoint: this.name,
+        mode: this.#options.config.rpc ? 'rpc' : 'ipc',
+        friends: this.friends.size,
+        groups: this.groups.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.
+      logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+      throw error;
+    }
   }
 
   /** 建立或恢复与守护进程的 IPC/RPC 会话（订阅、缓存列表） */
-  private async rebindIpcSession(): Promise<void> {
-    const uin = Number(this.$config.name);
-    const rpc = this.$config.rpc;
-
+  async #bindIpcSession(): Promise<void> {
     // 旧连接上的订阅句柄已失效，不再对死 socket 发 unsubscribe
-    this.subscriptions = [];
-
-    let client: IpcClient;
-    if (rpc) {
-      client = await IpcClient.connectRpc(rpc);
-    } else {
-      client = await IpcClient.connect(uin);
-    }
-
-    if (this.intentionalDisconnect) {
-      client.close();
-      throw new Error("连接已取消");
-    }
-
-    this.ipc = client;
-    if (this.$config.autoReconnect !== false) {
-      this.ipc.setOnRemoteDisconnect(() => this.scheduleReconnect());
-    } else {
-      this.ipc.setOnRemoteDisconnect(null);
-    }
-
-    await this.refreshLists();
-
-    // 新版 icqq cli 在认证后自动广播事件，订阅过滤改为客户端侧完成。
-    const sub = this.ipc.subscribe(
-      Actions.SUBSCRIBE,
-      {},
-      (event) => this.handleEvent(event),
-    );
-    this.subscriptions.push(sub);
-
-    this.$connected = true;
+    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);
   }
 
   /** IPC/RPC 意外断开时调度重连（指数退避） */
-  private scheduleReconnect(): void {
-    if (this.$config.autoReconnect === false) return;
-    if (this.intentionalDisconnect) return;
-    if (this.reconnectRunning) return;
-    this.reconnectRunning = true;
-    void this.runReconnectLoop();
+  #scheduleReconnect(): void {
+    if (this.#options.config.autoReconnect === false) return;
+    if (this.#intentionalDisconnect) return;
+    if (this.#reconnectRunning) return;
+    this.#reconnectRunning = true;
+    void this.#runReconnectLoop();
   }
 
-  private async runReconnectLoop(): Promise<void> {
+  async #runReconnectLoop(): Promise<void> {
     try {
-      for (let attempt = 0; !this.intentionalDisconnect; attempt++) {
+      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;
-
-        this.$connected = false;
-        this.logger.warn(formatCompact( {
-          op: "disconnect",
-          endpoint: this.$id,
+        // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏
+        const disconnectLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+        disconnectLog(formatCompact({
+          op: 'disconnect',
+          endpoint: this.name,
           ok: false,
           delay_ms: delayMs,
           attempt: attempt + 1,
         }));
-
         await new Promise<void>((r) => setTimeout(r, delayMs));
-        if (this.intentionalDisconnect) break;
-
+        if (this.#intentionalDisconnect) break;
         try {
-          await this.rebindIpcSession();
-          this.logger.debug(formatCompact( {
-            op: "reconnect",
-            endpoint: this.$id,
+          await this.#bindIpcSession();
+          logger.info(formatCompact({
+            op: 'reconnect',
+            endpoint: this.name,
+            ok: true,
+            attempts: attempt + 1,
             friends: this.friends.size,
             groups: this.groups.size,
           }));
           break;
-        } catch (e: unknown) {
-          this.logger.warn(formatCompact( {
-            op: "reconnect",
-            endpoint: this.$id,
+        } catch (error) {
+          const retryLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+          retryLog(formatCompact({
+            op: 'reconnect',
+            endpoint: this.name,
             ok: false,
-            error: e instanceof Error ? e.message : String(e),
+            attempt: attempt + 1,
+            error: error instanceof Error ? error.message : String(error),
           }));
         }
       }
     } finally {
-      this.reconnectRunning = false;
+      this.#reconnectRunning = false;
     }
   }
 
-  /** 刷新好友/群列表缓存 */
-  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);
-      }
-    }
-
-    await this.guildCatalog.syncAll(this.ipc).catch((e: unknown) => {
-      this.logger.warn(formatCompact({
-        op: "sync_guilds",
-        endpoint: this.$id,
-        ok: false,
-        error: e instanceof Error ? e.message : String(e),
-      }));
-    });
+  open(): void {
+    this.#open = true;
   }
 
-  /** Console：列出 guild 子频道（含 parent.guild） */
-  getGuildChannelList(): ReturnType<IcqqGuildCatalog["getGuildChannelList"]> {
-    return this.guildCatalog.getGuildChannelList();
+  close(): void {
+    this.#open = false;
   }
 
-  resolveConsoleChannelNames(
-    channelId: string,
-    guildId?: string,
-  ): { channelName?: string; parentName?: string } {
-    return this.guildCatalog.resolveConsoleChannelNames(channelId, guildId);
-  }
-
-  // ── 断开 ───────────────────────────────────────────────────────────
-
-  async $disconnect(): Promise<void> {
-    this.intentionalDisconnect = true;
-
+  async stop(): Promise<void> {
+    this.#intentionalDisconnect = true;
+    this.#open = false;
     this.ipc?.setOnRemoteDisconnect(null);
-    for (const sub of this.subscriptions) {
-      await sub.unsubscribe().catch(() => {});
-    }
-    this.subscriptions = [];
-    this.inboundDeduper.clear();
-    disposeIcqqLoginAssistBridge(this.$id);
-    this.ipc?.close();
-    this.$connected = false;
-    this.logger.debug(formatCompact( { op: "disconnect", endpoint: this.$id }));
-  }
-
-  // ── 消息处理 ───────────────────────────────────────────────────────
-
-  private handleEvent(event: IpcEvent): void {
-    if (event.event?.startsWith("system.login.")) {
-      handleIcqqLoginIpcEvent(this, event.event, event.data);
-      return;
-    }
-
-    if (event.event === Actions.RELOAD_GUILDS) {
-      void this.guildCatalog.syncAll(this.ipc).catch((e: unknown) => {
-        this.logger.warn(formatCompact({
-          op: "reload_guilds",
-          endpoint: this.$id,
-          ok: false,
-          error: e instanceof Error ? e.message : String(e),
-        }));
-      });
-      return;
-    }
-
-    if (isIcqqGuildIpcEvent(event.event)) {
-      this.handleGuildMessageEvent(event);
-      return;
-    }
-
-    const payload = unwrapIcqqIpcEventPayload(event);
-    if (!payload || typeof payload !== "object") {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.info(
-          formatCompact({
-            ipc_skip: "no_payload",
-            ipc_event: event.event,
-          }),
-        );
-      }
-      return;
-    }
-
-    if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-      this.logger.info(
-        formatCompact({
-          ipc_raw: JSON.stringify(payload).slice(0, 800),
-        }),
-      );
-    }
-
-    if (isIcqqNoticePayload(payload)) {
-      this.handleNoticeEvent(payload);
-      return;
-    }
-    if (isIcqqRequestPayload(payload)) {
-      this.handleRequestEvent(payload);
-      return;
-    }
-    if (isIcqqMetaPayload(payload)) {
-      this.handleMetaEvent(payload);
-      return;
-    }
-
-    if (!isIcqqMessagePostType(payload)) {
-      const postType = resolveIcqqEventPostType(
-        payload as Record<string, unknown>,
-      );
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.info(
-          formatCompact({ ipc_skip: postType ?? "unknown_event" }),
-        );
-      }
-      return;
-    }
-
-    const data = payload;
-
-    if (shouldSkipSelfInboundMessage(data)) {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.debug(formatCompact({ ipc_skip: "self_message" }));
-      }
-      return;
-    }
-
-    const normalized = normalizeIcqqInboundMessage(data);
-    if (!normalized) {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.debug(formatCompact({ ipc_skip: "normalize_failed" }));
-      }
-      return;
-    }
-
-    if (!this.inboundDeduper.shouldProcess(normalized.messageId)) {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.info(
-          formatCompact({ ipc_dedupe: normalized.messageId }),
-        );
-      }
-      return;
-    }
-
-    void this.dispatchInboundMessage(data, normalized);
-  }
-
-  private async dispatchInboundMessage(
-    data: IcqqIpcMessageEvent,
-    normalized: NormalizedIcqqInbound,
-  ): Promise<void> {
-    this.logIpcInboundPayload(data, normalized);
-
-    await this.primeQuotedSourceCache(
-      data.source ?? findIcqqNestedMessageSource(data),
-    );
-
-    const message = this.$formatMessage(normalized);
-    this.adapter.emit("message.receive", message);
-    this.logger.debug(
-      `${this.$id} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}${message.$quote_id ? ` quote_id=${message.$quote_id}` : ""}`,
-    );
-  }
-
-  private handleGuildMessageEvent(event: IpcEvent): void {
-    const payload = event.data;
-    if (!payload || typeof payload !== "object") return;
-    const data = payload as IpcGuildMessageEventData & Record<string, unknown>;
-    const normalized = normalizeIcqqGuildInboundMessage(data);
-    if (!normalized) return;
-
-    this.guildCatalog.upsertFromInbound(data);
-
-    if (!this.inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
-      return;
-    }
-
-    void this.dispatchGuildInboundMessage(normalized);
-  }
-
-  private async dispatchGuildInboundMessage(
-    normalized: NormalizedIcqqGuildInbound,
-  ): Promise<void> {
-    const message = this.$formatGuildMessage(normalized);
-    this.adapter.emit("message.receive", message);
-    this.logger.debug(
-      `${this.$id} recv channel(${message.$channel.id}):${segment.raw(message.$content)}`,
-    );
-  }
-
-  private $formatGuildMessage(
-    normalized: NormalizedIcqqGuildInbound,
-  ): ReturnType<typeof Message.from<IpcGuildMessageEventData>> {
-    const senderInfo: IcqqSenderInfo = {
-      id: normalized.userId,
-      name: normalized.nickname,
-    };
-
-    const result = Message.from(normalized.raw, {
-      $id: normalized.messageId,
-      $adapter: "icqq" as const,
-      $endpoint: this.$config.name,
-      $sender: senderInfo,
-      $channel: {
-        id: normalized.channelId,
-        type: "channel",
-        parent: { type: "guild", id: normalized.guildId },
-      },
-      $content: normalized.content,
-      $raw: normalized.rawMessage,
-      $timestamp: normalized.timestampMs,
-      $recall: async () => {
-        await this.$recallMessage(result.$id);
-      },
-      $reply: async (
-        content: SendContent,
-        quote?: boolean | string,
-      ): Promise<string> => {
-        if (!Array.isArray(content)) content = [content];
-        if (quote) {
-          content.unshift({
-            type: "reply",
-            data: { id: typeof quote === "boolean" ? result.$id : quote },
-          });
-        }
-        return await this.adapter.sendMessage({
-          context: "icqq",
-          endpoint: this.$config.name,
-          id: normalized.channelId,
-          type: "channel",
-          parent: { type: "guild", id: normalized.guildId },
-          content,
-        });
-      },
-    });
-    return result;
-  }
-
-  private handleNoticeEvent(event: IcqqIpcRawEvent): void {
-    const dedupeKey = resolveSideEventDedupeKey(event, "notice");
-    if (!this.inboundDeduper.shouldProcess(dedupeKey)) {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.debug(formatCompact({ ipc_dedupe: dedupeKey }));
-      }
-      return;
-    }
-    const notice = formatIcqqNotice(event, this.$config.name);
-    this.adapter.emit("notice.receive", notice);
-    this.logger.debug(
-      formatCompact({
-        notice: `${notice.$type}.${notice.$scene_type}.${notice.$sub_type}`,
-        scene: `${notice.$scene_type}(${notice.$scene_id})`,
-        endpoint: this.$id,
-      }),
-    );
-  }
-
-  private handleRequestEvent(event: IcqqIpcRawEvent): void {
-    const dedupeKey = resolveSideEventDedupeKey(event, "request");
-    if (!this.inboundDeduper.shouldProcess(dedupeKey)) {
-      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-        this.logger.debug(formatCompact({ ipc_dedupe: dedupeKey }));
-      }
-      return;
-    }
-    const request = formatIcqqRequest(event, this.$config.name, this.ipc);
-    this.adapter.emit("request.receive", request);
-    this.logger.debug(
-      formatCompact({
-        request: `${request.$type}.${request.$scene_type}.${request.$sub_type}`,
-        scene: `${request.$scene_type}(${request.$scene_id})`,
-        endpoint: this.$id,
-        from: request.$actor.id,
-      }),
-    );
-  }
-
-  private handleMetaEvent(event: IcqqIpcRawEvent): void {
-    const time = event.time ?? 0;
-    const kind = event.meta_event_type ?? event.post_type ?? 'meta';
-    const dedupeKey = `meta:${time}_${kind}_${event.sub_type ?? ''}`;
-    if (!this.inboundDeduper.shouldProcess(dedupeKey)) return;
-
-    this.logger.debug(formatIcqqMetaLog(event));
-    if (shouldRefreshListsOnMeta(event)) {
-      void this.refreshLists().catch((e: unknown) => {
-        this.logger.warn(
-          formatCompact({
-            op: "refresh_lists",
-            ok: false,
-            error: e instanceof Error ? e.message : String(e),
-          }),
-        );
-      });
-    }
-  }
-
-  /** 调试 IPC 入站字段：默认 debug；设 ICQQ_IPC_LOG_RAW=1 则 info 打完整 payload */
-  private logIpcInboundPayload(
-    data: IcqqIpcMessageEvent,
-    normalized: NormalizedIcqqInbound,
-  ): void {
-    const ext = data as IcqqIpcMessageEvent & Record<string, unknown>;
-    const keys = Object.keys(ext);
-    const idHints: Record<string, unknown> = {};
-    for (const key of keys) {
-      if (/message|msg|seq|id|source/i.test(key)) {
-        idHints[key] = ext[key];
-      }
-    }
-    const preview = JSON.stringify(data);
-    const compact = formatCompact({
-      post_type: data.post_type ?? "legacy",
-      message_type: data.message_type ?? data.type,
-      ipc_message_id: normalized.messageId,
-      id_source: normalized.idSource,
-      ipc_keys: keys.join(","),
-      ...(Object.keys(idHints).length ? { ipc_id_hints: JSON.stringify(idHints) } : {}),
-    });
-    this.logger.debug(compact);
-    this.logger.debug(formatCompact({ ipc_payload: preview.slice(0, 1200) }));
-  }
-
-  $formatMessage(
-    input: NormalizedIcqqInbound | IcqqIpcMessageEvent,
-  ): ReturnType<typeof Message.from<IcqqIpcMessageEvent>> {
-    const normalized =
-      "messageId" in input
-        ? input
-        : normalizeIcqqInboundMessage(input);
-    if (!normalized) {
-      throw new Error("无法解析 icqq 入站消息");
+    for (const sub of this.#subscriptions.splice(0)) {
+      await sub.unsubscribe().catch(() => { /* ignore */ });
     }
-    const raw = normalized.raw;
-    const senderInfo: IcqqSenderInfo = {
-      id: normalized.userId,
-      name: normalized.nickname,
-    };
-    if (normalized.senderRole && normalized.senderRole !== "member") {
-      senderInfo.role = normalized.senderRole;
-      if (normalized.senderRole === "owner") {
-        senderInfo.isOwner = true;
-        senderInfo.permissions = ["owner"];
-      } else if (normalized.senderRole === "admin") {
-        senderInfo.isAdmin = true;
-        senderInfo.permissions = ["admin"];
-      }
-    }
-
-    const quoteId =
-      Message.quoteIdFromContent(normalized.content) ??
-      resolveIcqqQuoteIdFromEvent(normalized.raw);
-    Message.alignReplySegments(normalized.content, quoteId);
-
-    const result = Message.from(raw, {
-      $id: normalized.messageId,
-      $adapter: "icqq" as const,
-      $endpoint: this.$config.name,
-      $sender: senderInfo,
-      $channel: {
-        id: normalized.channelId,
-        type: normalized.channelType,
-        ...(normalized.channelParentGroupId
-          ? { parent: { type: 'group' as const, id: normalized.channelParentGroupId } }
-          : {}),
-      },
-      $content: normalized.content,
-      $quote_id: quoteId,
-      $raw: normalized.rawMessage,
-      $timestamp: normalized.timestampMs,
-      $recall: async () => {
-        if (normalized.idSource === "synthetic") {
-          this.logger.warn(formatCompact( {
-            op: "recall",
-            endpoint: this.$id,
-            ok: false,
-            error: "no message_id in push",
-          }));
-          return;
-        }
-        await this.$recallMessage(result.$id);
-      },
-      $reply: async (
-        content: SendContent,
-        quote?: boolean | string,
-      ): Promise<string> => {
-        if (!Array.isArray(content)) content = [content];
-        if (quote) {
-          content.unshift({
-            type: "reply",
-            data: { id: typeof quote === "boolean" ? result.$id : quote },
-          });
-        }
-        return await this.adapter.sendMessage({
-          ...result.$channel,
-          context: "icqq",
-          endpoint: this.$config.name,
-          content,
-        });
-      },
-    });
-    return result;
-  }
-
-  /**
-   * 有 source.message_id 时用 get_msg 拉全量正文；否则仅用 source 内联摘要。
-   */
-  private async primeQuotedSourceCache(source: unknown): Promise<void> {
-    if (!source) return;
-    const quoteId = resolveQuoteIdFromIcqqSource(source);
-    const s = source as { message_id?: unknown };
-    const hasCanonicalId =
-      quoteId &&
-      s.message_id != null &&
-      String(s.message_id).trim() === quoteId;
-
-    if (hasCanonicalId) {
-      try {
-        await this.fetchQuotedMessagePayload(quoteId);
-        return;
-      } catch (e: unknown) {
-        this.logger.debug(
-          formatCompact({
-            op: "quote_get_msg",
-            message_id: quoteId,
-            ok: false,
-            error: e instanceof Error ? e.message : String(e),
-          }),
-        );
-      }
-    }
-
-    const sourcePayload = quotedPayloadFromIcqqSource(source);
-    if (!sourcePayload) return;
-    const enriched = await enrichQuotedPayloadWithForward(
-      this.ipc,
-      sourcePayload,
-    );
-    this.quotedSourceCache.set(enriched.messageId, enriched);
-  }
-
-  private async fetchQuotedMessagePayload(
-    messageId: string,
-  ): Promise<QuotedMessagePayload> {
-    const resp = await this.ipc.request(Actions.GET_MSG, {
-      message_id: messageId,
-    });
-    if (!resp.ok) {
-      throw new Error(resp.error ?? "get_msg failed");
-    }
-    const payload = parseIcqqGetMsgResponse(messageId, resp.data);
-    const enriched = await enrichQuotedPayloadWithForward(
-      this.ipc,
-      payload,
-      resp.data,
-    );
-    if (
-      isForwardPlaceholderPayload(enriched) &&
-      !String(
-        Array.isArray(enriched.content)
-          ? segment.raw(enriched.content)
-          : enriched.content ?? "",
-      ).includes("[Merged chat history")
-    ) {
-      this.logger.debug(
-        formatCompact({
-          op: "forward_unresolved",
-          message_id: messageId,
-        }),
-      );
-    }
-    this.quotedSourceCache.set(messageId, enriched);
-    return enriched;
+    this.#unregisterAgent?.();
+    this.#unregisterAgent = undefined;
+    this.#inboundDeduper.clear();
+    this.friends.clear();
+    this.groups.clear();
+    try {
+      this.ipc?.close();
+    } catch {
+      /* ignore */
+    }
+    // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
+    this.ipc = undefined as unknown as IcqqIpcTransport;
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
   }
 
-  async $getMsg(messageId: string): Promise<QuotedMessagePayload> {
-    const cached = this.quotedSourceCache.get(messageId);
-    if (cached) {
-      return enrichQuotedPayloadWithForward(this.ipc, cached);
+  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+    if (!this.ipc) {
+      throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
     }
-    return this.fetchQuotedMessagePayload(messageId);
-  }
-
-  // ── 撤回 ───────────────────────────────────────────────────────────
-
-  async $recallMessage(id: string): Promise<void> {
-    const resp = await this.ipc.request(Actions.RECALL_MSG, {
-      message_id: id,
-    });
-    if (!resp.ok) {
-      this.logger.warn(formatCompact( {
-        op: "recall",
-        endpoint: this.$id,
-        ok: false,
-        error: resp.error,
-      }));
-    }
-  }
-
-  // ── 发送消息 ───────────────────────────────────────────────────────
-
-  async $sendMessage(options: SendOptions): Promise<string> {
-    const outboundMedia = resolveIcqqOutboundMediaMode(this.$config);
-    const expanded = expandInteractiveSegmentsInContent(options.content);
-    const qrcodeContent = expanded;
-    const content = materializeOutboundBase64(qrcodeContent, outboundMedia);
-    const message = buildIcqqIpcMessageImpl(content);
-
+    const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
+    const content = Array.isArray(payload)
+      ? materializeOutboundBase64(payload, mediaMode)
+      : payload;
+    const message = formatOutboundBody(content);
+    const parsed = parseSendTarget(target);
     let action: string;
     let params: Record<string, unknown>;
-
-    switch (options.type) {
-      case "private": {
-        const groupParent =
-          options.parent?.type === "group" ? options.parent.id : undefined;
-        if (groupParent) {
-          action = Actions.SEND_TEMP_MSG;
-          params = {
-            group_id: Number(groupParent),
-            user_id: Number(options.id),
-            message,
-          };
-        } else {
-          action = Actions.SEND_PRIVATE_MSG;
-          params = { user_id: Number(options.id), message };
-        }
+    switch (parsed.kind) {
+      case 'private':
+        action = Actions.SEND_PRIVATE_MSG;
+        params = { user_id: parsed.userId, message };
         break;
-      }
-      case "group":
+      case 'group':
         action = Actions.SEND_GROUP_MSG;
-        params = { group_id: Number(options.id), message };
+        params = { group_id: parsed.groupId, message };
         break;
-      case "channel": {
-        const guildId =
-          options.parent?.type === "guild" ? options.parent.id : undefined;
-        if (!guildId) {
-          throw new Error(
-            'channel 发送需要 parent: { type: "guild", id: guild_id }',
-          );
-        }
+      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: guildId,
-          channel_id: options.id,
+          guild_id: parsed.guildId,
+          channel_id: parsed.channelId,
           message,
         };
         break;
-      }
-      default:
-        throw new Error(`不支持的频道类型: ${options.type}`);
     }
-
     const resp = await this.ipc.request(action, params);
     if (!resp.ok) {
-      this.logger.debug(formatCompact({
-        op: action,
-        ...params,
-      }));
       throw new Error(`发送消息失败: ${resp.error}`);
     }
-
     const messageId = String(
-      (resp.data as any)?.message_id ?? `sent_${Date.now()}`,
-    );
-    this.logger.debug(
-      `${this.$id} send ${options.type}(${options.id}):${segment.raw(options.content)}`,
+      (resp.data as { message_id?: unknown } | undefined)?.message_id ?? `sent_${Date.now()}`,
     );
+    logger.debug(formatCompact({
+      op: 'icqq_send',
+      endpoint: this.name,
+      target,
+      messageId,
+    }));
     return messageId;
   }
 
-  // ── 消息回应 ───────────────────────────────────────────────────────
+  // ── 消息回应（activity-feedback / typing reaction）────────────────────
 
-  /**
-   * 表情符号到 reaction id 的映射
-   * QQ 使用数字 ID 来标识表情，而不是 Unicode 字符
-   */
   private static readonly EMOJI_MAP: Record<string, string> = {
-    '⏳': '1468368274',  // 沙漏
-    '👍': '128077',      // 竖起大拇指
-    '❤️': '10084',       // 红心
-    '😊': '128522',      // 微笑
-    '🎉': '127881',      // 派对
-    '🔥': '128293',      // 火
-    '✅': '9989',        // 勾选
-    '❌': '10060',       // 叉号
-    '⭐': '11088',       // 星星
-    '💯': '128175',      // 一百分
+    '⏳': '1468368274',
+    '👍': '128077',
+    '❤️': '10084',
+    '😊': '128522',
+    '🎉': '127881',
+    '🔥': '128293',
+    '✅': '9989',
+    '❌': '10060',
+    '⭐': '11088',
+    '💯': '128175',
   };
 
-  /**
-   * 将表情符号转换为 reaction id
-   */
   private getEmojiId(emoji: string): string {
-    // 如果已经是数字 ID，直接返回
-    if (/^\d+$/.test(emoji)) {
-      return emoji;
-    }
-
-    // 从映射中查找
-    const id = IcqqEndpoint.EMOJI_MAP[emoji];
-    if (id) {
-      return id;
-    }
-
-    // 默认返回 Unicode 码点
-    return String(emoji.codePointAt(0) || 0);
+    if (/^\d+$/u.test(emoji)) return emoji;
+    return IcqqIpcEndpoint.EMOJI_MAP[emoji] ?? String(emoji.codePointAt(0) || 0);
   }
 
-  /**
-   * 添加消息回应（表情）
-   *
-   * @param messageId - 消息 ID
-  * @param emoji - 表情符号或 reaction id
-   * @returns 反应 ID，可用于后续移除
-   */
-  async $addReaction(messageId: string, emoji: string): Promise<string | null> {
+  /** Activity-feedback / OutboundHost reaction surface. */
+  async addReaction(messageId: string, emoji: string): Promise<string | null> {
     try {
       const emojiId = this.getEmojiId(emoji);
-
-      const resp = await this.ipc.request(Actions.GROUP_SET_REACTION, {
+      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.$id,
+        logger.warn(formatCompact({
+          op: 'add_reaction',
+          endpoint: this.name,
           message_id: messageId,
           emoji,
           id: emojiId,
@@ -849,22 +310,19 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
         }));
         return null;
       }
-
-      this.logger.debug(formatCompact({
-        op: "add_reaction",
-        endpoint: this.$id,
+      logger.debug(formatCompact({
+        op: 'add_reaction',
+        endpoint: this.name,
         message_id: messageId,
         emoji,
         id: emojiId,
         ok: true,
       }));
-
-      // 返回 reaction id，供 $removeReaction 直接使用
       return emojiId;
     } catch (error) {
-      this.logger.warn(formatCompact({
-        op: "add_reaction",
-        endpoint: this.$id,
+      logger.warn(formatCompact({
+        op: 'add_reaction',
+        endpoint: this.name,
         message_id: messageId,
         emoji,
         ok: false,
@@ -874,61 +332,214 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
     }
   }
 
-  /**
-   * 移除消息回应
-   *
-   * @param messageId - 消息 ID
-   * @param reactionId - 反应 ID（由 $addReaction 返回）
-   */
-  async $removeReaction(messageId: string, reactionId: string): Promise<void> {
+  async removeReaction(messageId: string, reactionId: string): Promise<void> {
     try {
-      // 兼容两种格式：
-      // 1) 旧格式 reaction_{id}_{timestamp}
-      // 2) 新格式直接为 id
       const parts = reactionId.split('_');
-      const emojiId = parts.length >= 2 ? parts[1] : reactionId;
-
-      const resp = await this.ipc.request(Actions.GROUP_DEL_REACTION, {
+      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.$id,
+        logger.warn(formatCompact({
+          op: 'remove_reaction',
+          endpoint: this.name,
           message_id: messageId,
           reaction_id: reactionId,
           id: emojiId,
           ok: false,
           error: resp.error,
         }));
-      } else {
-        this.logger.debug(formatCompact({
-          op: "remove_reaction",
-          endpoint: this.$id,
+        return;
+      }
+      logger.debug(formatCompact({
+        op: 'remove_reaction',
+        endpoint: this.name,
+        message_id: messageId,
+        reaction_id: reactionId,
+        id: emojiId,
+        ok: true,
+      }));
+    } catch (error) {
+      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;
+    try {
+      const resp = await this.request(Actions.RECALL_MSG, { message_id: messageId });
+      if (!resp.ok) {
+        logger.warn(formatCompact({
+          op: 'recall_message',
+          endpoint: this.name,
           message_id: messageId,
-          reaction_id: reactionId,
-          id: emojiId,
-          ok: true,
+          ok: false,
+          error: resp.error,
         }));
+        return;
       }
+      logger.debug(formatCompact({
+        op: 'recall_message',
+        endpoint: this.name,
+        message_id: messageId,
+        ok: true,
+      }));
     } catch (error) {
-      this.logger.warn(formatCompact({
-        op: "remove_reaction",
-        endpoint: this.$id,
+      logger.warn(formatCompact({
+        op: 'recall_message',
+        endpoint: this.name,
         message_id: messageId,
-        reaction_id: reactionId,
         ok: false,
         error: error instanceof Error ? error.message : String(error),
       }));
     }
   }
+
+  /** Test / internal: admit when open. */
+  admit(msg: IcqqInboundMessage): void {
+    if (!this.#open) return;
+    // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）只能经 metadata 传递
+    const mentioned = isIcqqBotMentioned({ uin: this.name, rawMessage: msg.content });
+    void this.#options.gateway.receive({
+      adapter: this.#options.id,
+      target: msg.target,
+      content: msg.content,
+      sender: msg.sender,
+      id: msg.id,
+      metadata: Object.freeze({
+        endpoint: this.name,
+        channelType: msg.channelType,
+        ...msg.metadata,
+        ...(mentioned ? { mentioned: true } : {}),
+      }),
+    }).catch((err) => {
+      logger.warn(formatCompact({
+        op: 'icqq_gateway_receive_failed',
+        target: msg.target,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  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);
+      }
+    }
+  }
+
+  #handleEvent(event: IpcEvent): void {
+    if (isIcqqGuildIpcEvent(event.event)) {
+      this.#handleGuildEvent(event);
+      return;
+    }
+    const payload = unwrapIcqqIpcEventPayload(event);
+    if (!payload || typeof payload !== 'object') return;
+    if (!isIcqqMessagePostType(payload)) return;
+    const data = payload as IcqqIpcMessageEvent;
+    if (shouldSkipSelfInboundMessage(data)) return;
+    const normalized = normalizeIcqqInboundMessage(data);
+    if (!normalized) return;
+    if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) return;
+    this.admit({
+      id: normalized.messageId,
+      target: formatInboundTarget({
+        channelType: normalized.channelType,
+        channelId: normalized.channelId,
+        channelParentGroupId: normalized.channelParentGroupId,
+      }),
+      content: formatInboundContent(normalized.rawMessage),
+      sender: normalized.userId,
+      channelType: normalized.channelType,
+      metadata: buildIcqqQuoteMetadata(data, {
+        nickname: normalized.nickname,
+        senderRole: normalized.senderRole,
+      }),
+    });
+  }
+
+  #handleGuildEvent(event: IpcEvent): void {
+    const payload = event.data;
+    if (!payload || typeof payload !== 'object') return;
+    const normalized = normalizeIcqqGuildInboundMessage(
+      payload as Parameters<typeof normalizeIcqqGuildInboundMessage>[0],
+    );
+    if (!normalized) return;
+    if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) return;
+    this.admit({
+      id: normalized.messageId,
+      target: formatInboundTarget({
+        channelType: 'channel',
+        channelId: normalized.channelId,
+        guildId: normalized.guildId,
+      }),
+      content: formatInboundContent(normalized.rawMessage),
+      sender: normalized.userId,
+      channelType: 'channel',
+      metadata: {
+        guildId: normalized.guildId,
+        nickname: normalized.nickname,
+      },
+    });
+  }
 }
 
-/** @deprecated 使用 `./cq-message.js` 导出 */
-export namespace IcqqEndpoint {
-  export const parseCqMessage = parseCqMessageImpl;
-  export const buildIcqqIpcMessage = buildIcqqIpcMessageImpl;
-  export const toCqString = toCqStringImpl;
+/**
+ * 组装入站 metadata：在基础字段上补充 quote 链路信息。
+ * - quote_id：被引用消息 id（resolveIcqqQuoteIdFromEvent，无则不写）
+ * - quote_sender_id / quote_sender_name / quote_content：source 可用时的平铺摘要
+ */
+function buildIcqqQuoteMetadata(
+  data: IcqqIpcMessageEvent,
+  base: Record<string, unknown>,
+): Record<string, unknown> {
+  const metadata: Record<string, unknown> = { ...base };
+  const quoteId = resolveIcqqQuoteIdFromEvent(data);
+  if (quoteId) metadata.quote_id = quoteId;
+  const quoted = quotedPayloadFromIcqqSource(findIcqqNestedMessageSource(data));
+  if (quoted?.sender?.id) metadata.quote_sender_id = quoted.sender.id;
+  if (quoted?.sender?.name) metadata.quote_sender_name = quoted.sender.name;
+  const quoteText = quoted
+    ? (typeof quoted.content === 'string'
+        ? quoted.content
+        : quoted.content
+            .map((seg) =>
+              seg && typeof seg === 'object' && seg.type === 'text'
+                ? String((seg.data as { text?: unknown } | undefined)?.text ?? '')
+                : '',
+            )
+            .join('')
+      ).trim() || quoted.raw || ''
+    : '';
+  if (quoteText) metadata.quote_content = quoteText;
+  return metadata;
+}
+
+async function defaultCreateIpc(config: ResolvedIcqqConfig): Promise<IcqqIpcTransport> {
+  const uin = Number(config.name);
+  if (config.rpc) {
+    return IpcClient.connectRpc(config.rpc);
+  }
+  return IpcClient.connect(uin);
 }