@zhin.js/adapter-icqq 3.0.4 → 3.0.6

package/src/bot.ts

@@ -4,7 +4,7 @@
  * 不再直接依赖 @icqqjs/icqq 协议库。
  * 登录由 `icqq login` 完成，本 Bot 只负责连接守护进程并收发消息。
  */
-import { formatCompact, Bot, Message, MessageSegment, segment, SendContent, SendOptions } from 'zhin.js';
+import { formatCompact, Bot, Message, segment, SendContent, SendOptions, type QuotedMessagePayload } from 'zhin.js';
 import type {
   IcqqBotConfig,
   IcqqSenderInfo,
@@ -14,13 +14,42 @@ import type {
 } from "./types.js";
 import type { IcqqAdapter } from "./adapter.js";
 import { IpcClient } from "./ipc-client.js";
+import { Actions, type IpcEvent } from "./protocol.js";
+import type { IcqqIpcMessageEvent } from "./icqq-inbound.js";
 import {
-  Actions,
-  type IpcMessageEventData,
-  type IpcEvent,
-} from "./protocol.js";
-
-export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
+  findIcqqNestedMessageSource,
+  InboundMessageDeduper,
+  isIcqqMessagePostType,
+  normalizeIcqqInboundMessage,
+  quotedPayloadFromIcqqSource,
+  resolveIcqqQuoteIdFromEvent,
+  resolveQuoteIdFromIcqqSource,
+  shouldSkipSelfInboundMessage,
+  unwrapIcqqIpcEventPayload,
+  type NormalizedIcqqInbound,
+} from "./icqq-inbound.js";
+import {
+  buildIcqqIpcMessage as buildIcqqIpcMessageImpl,
+  parseCqMessage as parseCqMessageImpl,
+  toCqString as toCqStringImpl,
+} from "./cq-message.js";
+import {
+  formatIcqqMetaLog,
+  formatIcqqNotice,
+  formatIcqqRequest,
+  isIcqqMetaPayload,
+  isIcqqNoticePayload,
+  isIcqqRequestPayload,
+  resolveIcqqEventPostType,
+  resolveSideEventDedupeKey,
+  shouldRefreshListsOnMeta,
+  type IcqqIpcRawEvent,
+} from "./icqq-side-events.js";
+import { enableTypingIndicator, type ICQQTypingIndicatorManager } from "./typing-indicator.js";
+import { parseIcqqGetMsgResponse } from "./get-msg.js";
+import { enrichQuotedPayloadWithForward, isForwardPlaceholderPayload } from "./forward-msg.js";
+
+export class IcqqBot implements Bot<IcqqBotConfig, IcqqIpcMessageEvent> {
   $connected = false;
   $config: IcqqBotConfig;
   ipc!: IpcClient;
@@ -31,11 +60,18 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
   groups = new Map<number, IpcGroupInfo>();
 
   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;
   /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
   private reconnectRunning = false;
 
+  /** Typing Indicator 管理器 */
+  $typingIndicator?: ICQQTypingIndicatorManager;
+
   get $id() {
     return this.$config.name;
   }
@@ -66,13 +102,50 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
 
     await this.rebindIpcSession();
 
+    // 根据配置自动启用 Typing Indicator
+    this.initTypingIndicator();
+
     this.logger.info(formatCompact( {
-      bot: this.$id,
-      friends: this.friends.size,
-      groups: this.groups.size,
+      机器人: this.$id,
+      好友数: this.friends.size,
+      群组数: this.groups.size,
+      思考提示: this.$typingIndicator ? '已启用' : '未启用',
     }));
   }
 
+  /**
+   * 初始化 Typing Indicator
+   * 根据配置自动启用或禁用
+   */
+  private initTypingIndicator(): void {
+    const typingConfig = this.$config.typingIndicator;
+
+    // 如果配置中明确设置为 false，则不启用
+    if (typingConfig?.enabled === false) {
+      this.logger.debug(formatCompact({
+        bot: this.$id,
+        typingIndicator: 'disabled_by_config',
+      }));
+      return;
+    }
+
+    // 启用 Typing Indicator
+    try {
+      this.$typingIndicator = enableTypingIndicator(this, typingConfig);
+      this.logger.debug(formatCompact({
+        bot: this.$id,
+        typingIndicator: 'enabled',
+        emoji: typingConfig?.defaultEmoji || '⏳',
+      }));
+    } catch (error) {
+      this.logger.warn(formatCompact({
+        bot: this.$id,
+        typingIndicator: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  }
+
   /** 建立或恢复与守护进程的 IPC/RPC 会话（订阅、缓存列表） */
   private async rebindIpcSession(): Promise<void> {
     const uin = Number(this.$config.name);
@@ -102,23 +175,13 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
 
     await this.refreshLists();
 
-    for (const [uid] of this.friends) {
-      const sub = this.ipc.subscribe(
-        Actions.SUBSCRIBE,
-        { type: "private", id: uid },
-        (event) => this.handleEvent(event),
-      );
-      this.subscriptions.push(sub);
-    }
-
-    for (const [gid] of this.groups) {
-      const sub = this.ipc.subscribe(
-        Actions.SUBSCRIBE,
-        { type: "group", id: gid },
-        (event) => this.handleEvent(event),
-      );
-      this.subscriptions.push(sub);
-    }
+    // 新版 icqq cli 在认证后自动广播事件，订阅过滤改为客户端侧完成。
+    const sub = this.ipc.subscribe(
+      Actions.SUBSCRIBE,
+      {},
+      (event) => this.handleEvent(event),
+    );
+    this.subscriptions.push(sub);
 
     this.$connected = true;
   }
@@ -200,11 +263,19 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
 
   async $disconnect(): Promise<void> {
     this.intentionalDisconnect = true;
+
+    // 停止所有 Typing Indicator
+    if (this.$typingIndicator) {
+      await this.$typingIndicator.stopAll().catch(() => {});
+      this.$typingIndicator = undefined;
+    }
+
     this.ipc?.setOnRemoteDisconnect(null);
     for (const sub of this.subscriptions) {
       await sub.unsubscribe().catch(() => {});
     }
     this.subscriptions = [];
+    this.inboundDeduper.clear();
     this.ipc?.close();
     this.$connected = false;
     this.logger.info(formatCompact( { op: "disconnect", bot: this.$id }));
@@ -213,47 +284,227 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
   // ── 消息处理 ───────────────────────────────────────────────────────
 
   private handleEvent(event: IpcEvent): void {
-    const data = event.data as IpcMessageEventData;
-    if (!data || !data.raw_message) 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.info(formatCompact({ ipc_skip: "self_message" }));
+      }
+      return;
+    }
+
+    const normalized = normalizeIcqqInboundMessage(data);
+    if (!normalized) {
+      if (process.env.ICQQ_IPC_LOG_RAW === "1") {
+        this.logger.info(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);
 
-    const message = this.$formatMessage(data);
+    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)}`,
+      `${this.$id} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}${message.$quote_id ? ` quote_id=${message.$quote_id}` : ""}`,
+    );
+  }
+
+  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.info(formatCompact({ ipc_dedupe: dedupeKey }));
+      }
+      return;
+    }
+    const notice = formatIcqqNotice(event, this.$config.name);
+    this.adapter.emit("notice.receive", notice);
+    this.logger.info(
+      formatCompact({
+        notice: notice.$type,
+        channel: `${notice.$channel.type}(${notice.$channel.id})`,
+        bot: this.$id,
+        sub_type: notice.$subType,
+      }),
+    );
+  }
+
+  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.info(formatCompact({ ipc_dedupe: dedupeKey }));
+      }
+      return;
+    }
+    const request = formatIcqqRequest(event, this.$config.name, this.ipc);
+    this.adapter.emit("request.receive", request);
+    this.logger.info(
+      formatCompact({
+        request: request.$type,
+        channel: `${request.$channel.type}(${request.$channel.id})`,
+        bot: this.$id,
+        from: request.$sender.id,
+      }),
     );
   }
 
-  $formatMessage(raw: IpcMessageEventData) {
-    const channelId =
-      raw.type === "group"
-        ? String(raw.group_id ?? raw.from_id)
-        : String(raw.from_id);
-    const channelType = raw.type === "group" ? "group" : "private";
-    // 守护进程推送无 message_id，合成一个
-    const syntheticId = `${raw.time}_${raw.user_id}_${channelId}`;
+  private handleMetaEvent(event: IcqqIpcRawEvent): void {
+    const dedupeKey = resolveSideEventDedupeKey(event, "meta");
+    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 入站消息");
+    }
+    const raw = normalized.raw;
     const senderInfo: IcqqSenderInfo = {
-      id: String(raw.user_id),
-      name: raw.nickname,
+      id: normalized.userId,
+      name: normalized.nickname,
     };
 
+    const quoteId =
+      Message.quoteIdFromContent(normalized.content) ??
+      resolveIcqqQuoteIdFromEvent(normalized.raw);
+    Message.alignReplySegments(normalized.content, quoteId);
+
     const result = Message.from(raw, {
-      $id: syntheticId,
+      $id: normalized.messageId,
       $adapter: "icqq" as const,
       $bot: this.$config.name,
       $sender: senderInfo,
-      $channel: { id: channelId, type: channelType },
-      $content: IcqqBot.parseCqMessage(raw.raw_message),
-      $raw: raw.raw_message,
-      $timestamp: raw.time * 1000,
+      $channel: {
+        id: normalized.channelId,
+        type: normalized.channelType,
+      },
+      $content: normalized.content,
+      $quote_id: quoteId,
+      $raw: normalized.rawMessage,
+      $timestamp: normalized.timestampMs,
       $recall: async () => {
-        // 合成 id 无法撤回
-        this.logger.warn(formatCompact( {
-          op: "recall",
-          bot: this.$id,
-          ok: false,
-          error: "no message_id in push",
-        }));
+        if (normalized.idSource === "synthetic") {
+          this.logger.warn(formatCompact( {
+            op: "recall",
+            bot: this.$id,
+            ok: false,
+            error: "no message_id in push",
+          }));
+          return;
+        }
+        await this.$recallMessage(result.$id);
       },
       $reply: async (
         content: SendContent,
@@ -277,6 +528,85 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
     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;
+  }
+
+  async $getMsg(messageId: string): Promise<QuotedMessagePayload> {
+    const cached = this.quotedSourceCache.get(messageId);
+    if (cached) {
+      return enrichQuotedPayloadWithForward(this.ipc, cached);
+    }
+    return this.fetchQuotedMessagePayload(messageId);
+  }
+
   // ── 撤回 ───────────────────────────────────────────────────────────
 
   async $recallMessage(id: string): Promise<void> {
@@ -296,7 +626,7 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
   // ── 发送消息 ───────────────────────────────────────────────────────
 
   async $sendMessage(options: SendOptions): Promise<string> {
-    const content = IcqqBot.toCqString(options.content);
+    const message = buildIcqqIpcMessageImpl(options.content);
 
     let action: string;
     let params: Record<string, unknown>;
@@ -304,11 +634,11 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
     switch (options.type) {
       case "private":
         action = Actions.SEND_PRIVATE_MSG;
-        params = { user_id: Number(options.id), message: content };
+        params = { user_id: Number(options.id), message };
         break;
       case "group":
         action = Actions.SEND_GROUP_MSG;
-        params = { group_id: Number(options.id), message: content };
+        params = { group_id: Number(options.id), message };
         break;
       default:
         throw new Error(`不支持的频道类型: ${options.type}`);
@@ -316,6 +646,10 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
 
     const resp = await this.ipc.request(action, params);
     if (!resp.ok) {
+      this.logger.debug(formatCompact({
+        op: action,
+        ...params,
+      }));
       throw new Error(`发送消息失败: ${resp.error}`);
     }
 
@@ -327,112 +661,153 @@ export class IcqqBot implements Bot<IcqqBotConfig, IpcMessageEventData> {
     );
     return messageId;
   }
-}
 
-// ── CQ 码解析工具 ──────────────────────────────────────────────────
+  // ── 消息回应 ───────────────────────────────────────────────────────
 
-export namespace IcqqBot {
   /**
-   * 将 CQ 码原始消息字符串解析为 MessageSegment 数组。
-   * 格式: `[type:value]` 或纯文本
+   * 表情符号到 reaction id 的映射
+   * QQ 使用数字 ID 来标识表情，而不是 Unicode 字符
    */
-  export function parseCqMessage(raw: string): MessageSegment[] {
-    const segments: MessageSegment[] = [];
-    // 匹配 [type:arg] 或 [type:arg1,arg2=val] 等 CQ 码
-    const cqRegex = /\[([a-z_]+)(?::([^\]]*))?\]/g;
-    let lastIndex = 0;
-
-    for (const match of raw.matchAll(cqRegex)) {
-      // 前面的纯文本
-      if (match.index! > lastIndex) {
-        const text = raw.slice(lastIndex, match.index!);
-        if (text) segments.push({ type: "text", data: { text } });
-      }
+  private static readonly EMOJI_MAP: Record<string, string> = {
+    '⏳': '1468368274',  // 沙漏
+    '👍': '128077',      // 竖起大拇指
+    '❤️': '10084',       // 红心
+    '😊': '128522',      // 微笑
+    '🎉': '127881',      // 派对
+    '🔥': '128293',      // 火
+    '✅': '9989',        // 勾选
+    '❌': '10060',       // 叉号
+    '⭐': '11088',       // 星星
+    '💯': '128175',      // 一百分
+  };
 
-      const type = match[1];
-      const arg = match[2] ?? "";
+  /**
+   * 将表情符号转换为 reaction id
+   */
+  private getEmojiId(emoji: string): string {
+    // 如果已经是数字 ID，直接返回
+    if (/^\d+$/.test(emoji)) {
+      return emoji;
+    }
 
-      switch (type) {
-        case "face":
-          segments.push({ type: "face", data: { id: Number(arg) } });
-          break;
-        case "image":
-          segments.push({ type: "image", data: { url: arg, file: arg } });
-          break;
-        case "at":
-          if (arg === "all") {
-            segments.push({ type: "at", data: { qq: "all" } });
-          } else {
-            segments.push({ type: "at", data: { qq: arg } });
-          }
-          break;
-        case "dice":
-          segments.push({ type: "dice", data: {} });
-          break;
-        case "rps":
-          segments.push({ type: "rps", data: {} });
-          break;
-        case "record":
-        case "audio":
-          segments.push({ type: "record", data: { file: arg } });
-          break;
-        case "video":
-          segments.push({ type: "video", data: { file: arg } });
-          break;
-        case "reply":
-          segments.push({ type: "reply", data: { id: arg } });
-          break;
-        default:
-          segments.push({ type, data: { text: `[${type}:${arg}]` } });
-          break;
+    // 从映射中查找
+    const id = IcqqBot.EMOJI_MAP[emoji];
+    if (id) {
+      return id;
+    }
+
+    // 默认返回 Unicode 码点
+    return String(emoji.codePointAt(0) || 0);
+  }
+
+  /**
+   * 添加消息回应（表情）
+   *
+   * @param messageId - 消息 ID
+  * @param emoji - 表情符号或 reaction id
+   * @returns 反应 ID，可用于后续移除
+   */
+  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, {
+        message_id: messageId,
+        id: emojiId,
+      });
+
+      if (!resp.ok) {
+        this.logger.warn(formatCompact({
+          op: "add_reaction",
+          bot: this.$id,
+          message_id: messageId,
+          emoji,
+          id: emojiId,
+          ok: false,
+          error: resp.error,
+        }));
+        return null;
       }
 
-      lastIndex = match.index! + match[0].length;
-    }
+      this.logger.debug(formatCompact({
+        op: "add_reaction",
+        bot: this.$id,
+        message_id: messageId,
+        emoji,
+        id: emojiId,
+        ok: true,
+      }));
 
-    // 尾部文本
-    if (lastIndex < raw.length) {
-      const text = raw.slice(lastIndex);
-      if (text) segments.push({ type: "text", data: { text } });
+      // 返回 reaction id，供 $removeReaction 直接使用
+      return emojiId;
+    } catch (error) {
+      this.logger.warn(formatCompact({
+        op: "add_reaction",
+        bot: this.$id,
+        message_id: messageId,
+        emoji,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      return null;
     }
-
-    return segments.length ? segments : [{ type: "text", data: { text: raw } }];
   }
 
   /**
-   * 将 SendContent（MessageSegment[] 或字符串）转为 CQ 码字符串。
-   * 守护进程使用 CQ 码字符串格式收发消息。
+   * 移除消息回应
+   *
+   * @param messageId - 消息 ID
+   * @param reactionId - 反应 ID（由 $addReaction 返回）
    */
-  export function toCqString(content: SendContent): string {
-    if (!Array.isArray(content)) content = [content];
-    return content
-      .map((seg) => {
-        if (typeof seg === "string") return seg;
-        const { type, data } = seg as MessageSegment;
-        switch (type) {
-          case "text":
-            return data.text ?? "";
-          case "face":
-            return `[face:${data.id}]`;
-          case "image":
-            return `[image:${data.file || data.url || data.src}]`;
-          case "at":
-            return `[at:${data.qq ?? data.id}]`;
-          case "dice":
-            return "[dice]";
-          case "rps":
-            return "[rps]";
-          case "record":
-          case "audio":
-            return `[record:${data.file || data.url}]`;
-          case "video":
-            return `[video:${data.file || data.url}]`;
-          case "reply":
-            return `[reply:${data.id}]`;
-          default:
-            return segment.toString(seg);
-        }
-      })
-      .join("");
+  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, {
+        message_id: messageId,
+        id: emojiId,
+      });
+
+      if (!resp.ok) {
+        this.logger.warn(formatCompact({
+          op: "remove_reaction",
+          bot: this.$id,
+          message_id: messageId,
+          reaction_id: reactionId,
+          id: emojiId,
+          ok: false,
+          error: resp.error,
+        }));
+      } else {
+        this.logger.debug(formatCompact({
+          op: "remove_reaction",
+          bot: this.$id,
+          message_id: messageId,
+          reaction_id: reactionId,
+          id: emojiId,
+          ok: true,
+        }));
+      }
+    } catch (error) {
+      this.logger.warn(formatCompact({
+        op: "remove_reaction",
+        bot: this.$id,
+        message_id: messageId,
+        reaction_id: reactionId,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
   }
 }
+
+/** @deprecated 使用 `./cq-message.js` 导出 */
+export namespace IcqqBot {
+  export const parseCqMessage = parseCqMessageImpl;
+  export const buildIcqqIpcMessage = buildIcqqIpcMessageImpl;
+  export const toCqString = toCqStringImpl;
+}