@zhin.js/adapter-icqq 1.0.71 → 1.1.2

package/src/icqq-inbound.ts

@@ -0,0 +1,814 @@
+/**
+ * icqq 入站事件归一化（post_type / message_type / message 段）
+ */
+import { toCanonicalSegments, type MessageSegment } from "zhin.js";
+import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
+import { extractForwardResidFromJsonElement } from "./forward-msg.js";
+import type { GroupRole } from "./types.js";
+
+/** 守护进程推送的通用事件壳 */
+export interface IcqqEventBase {
+  post_type?: string;
+  self_id?: number;
+}
+
+/** post_type=message 时的消息体（字段随 icqqjs/cli 演进，未知字段保留） */
+export interface IcqqMessageEvent extends IcqqEventBase {
+  post_type: "message";
+  message_id?: string;
+  msg_id?: string;
+  user_id: number;
+  user_uid?: string;
+  time: number;
+  seq?: number;
+  message_type: string;
+  sub_type?: string;
+  raw_message?: string;
+  message?: IcqqMessageElement[];
+  sender?: {
+    user_id?: number;
+    user_uid?: string;
+    nickname?: string;
+    card?: string;
+    /** 群临时会话来源群号 */
+    group_id?: number;
+    /** 群成员角色：owner | admin | member */
+    role?: GroupRole | string;
+  };
+  from_id?: number;
+  from_uid?: string;
+  group_id?: number;
+  to_id?: number;
+  nickname?: string;
+  /** 旧版仅有 type 无 message_type */
+  type?: "group" | "private";
+  /** oicq Message#source：被引用回复的源消息 */
+  source?: IcqqMessageSource;
+}
+
+/** oicq 引用源消息（与 MessageEvent.source 对齐） */
+export interface IcqqMessageSource {
+  message_id?: string;
+  msg_id?: string;
+  seq?: number;
+  rand?: number;
+  time?: number;
+  user_id?: number;
+  group_id?: number;
+  raw_message?: string;
+  /** 元素数组，或 NT 推送的纯文本摘要 */
+  message?: IcqqMessageElement[] | string;
+  sender?: {
+    user_id?: number;
+    nickname?: string;
+    card?: string;
+  };
+  [key: string]: unknown;
+}
+
+interface IcqqMessageLookup {
+  readonly messageId: string;
+  readonly sender?: Readonly<{ id?: string; name?: string }>;
+  readonly content: readonly MessageSegment[] | string;
+  readonly raw?: string;
+  readonly time?: number;
+}
+
+export type IcqqMessageElement = {
+  type: string;
+  text?: string;
+  qq?: string | number;
+  user_id?: string | number;
+  id?: string | number;
+  url?: string;
+  file?: string;
+  fid?: string;
+  name?: string;
+  size?: number;
+  seconds?: number;
+  [key: string]: unknown;
+};
+
+export interface IcqqInboundMediaResolver {
+  getPttUrl(element: IcqqMessageElement): Promise<string | null | undefined>;
+  getVideoUrl(element: IcqqMessageElement): Promise<string | null | undefined>;
+}
+
+/**
+ * Resolve ICQQ's opaque protobuf media references while the endpoint-owned
+ * native client is still available. Resolution failure preserves the opaque
+ * reference, so canonical ingress stays truthful and can report unsupported
+ * media instead of inventing a URL.
+ */
+export async function resolveIcqqInboundMedia(
+  elements: IcqqMessageElement[] | undefined,
+  resolver: IcqqInboundMediaResolver,
+): Promise<void> {
+  if (!elements?.length) return;
+  await Promise.all(elements.map(async (element) => {
+    if (!element || typeof element !== "object") return;
+    if (typeof element.url === "string" && element.url) return;
+    try {
+      const url = element.type === "record" || element.type === "audio"
+        ? await resolver.getPttUrl(element)
+        : element.type === "video"
+          ? await resolver.getVideoUrl(element)
+          : undefined;
+      if (typeof url === "string" && url) element.url = url;
+    } catch {
+      // The original platform reference remains the canonical fallback.
+    }
+  }));
+}
+
+/** 归一化后供适配器使用的入站消息 */
+export interface NormalizedIcqqInbound {
+  messageId: string;
+  idSource: "message_id" | "msg_id" | "seq" | "synthetic";
+  channelType: "group" | "private";
+  channelId: string;
+  /** 群临时会话：来源群号 */
+  channelParentGroupId?: string;
+  userId: string;
+  nickname: string;
+  /** 群聊时来自 sender.role（私聊无） */
+  senderRole?: GroupRole;
+  content: MessageSegment[];
+  rawMessage: string;
+  timestampMs: number;
+  raw: IcqqMessageEvent;
+}
+
+const DEDUPE_TTL_MS = 120_000;
+
+const ICQQ_GROUP_ROLES = new Set<GroupRole>(["owner", "admin", "member"]);
+
+/** 从 sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
+export function parseIcqqSenderGroupRole(
+  sender: { role?: unknown } | undefined,
+): GroupRole | undefined {
+  const raw = sender?.role;
+  if (typeof raw !== "string" || !raw.trim()) return undefined;
+  const role = raw.trim().toLowerCase() as GroupRole;
+  return ICQQ_GROUP_ROLES.has(role) ? role : undefined;
+}
+
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export function isIcqqBotMentioned(input: {
+  readonly uin: string;
+  readonly content?: readonly MessageSegment[] | null;
+  readonly rawMessage?: string;
+}): boolean {
+  const uin = String(input.uin ?? "").trim();
+  if (!uin) return false;
+  for (const seg of input.content ?? []) {
+    if (!seg || (seg.type !== "at" && seg.type !== "mention")) continue;
+    const data = (seg.data ?? {}) as Record<string, unknown>;
+    const target = String(
+      data.qq ?? data.user_id ?? data.id ?? data.target ?? "",
+    ).trim();
+    if (target && target !== "all" && Number(target) === Number(uin)) {
+      return true;
+    }
+  }
+  const raw = input.rawMessage ?? "";
+  if (!raw) return false;
+  const escaped = uin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // OneBot CQ 码 `[CQ:at,qq=uin]`；QQ 频道 markdown `<@!uin>`
+  return new RegExp(`\\[CQ:at,qq=${escaped}\\]`, "u").test(raw)
+    || new RegExp(`<@!?${escaped}>`, "u").test(raw);
+}
+
+const MESSAGE_POST_TYPES = new Set(["message"]);
+
+function isMessagePostType(postType: unknown): boolean {
+  if (typeof postType !== "string" || postType === "") return false;
+  if (MESSAGE_POST_TYPES.has(postType)) return true;
+  // 如 message.private / message.group
+  return postType.startsWith("message.");
+}
+
+/** 从事件壳中取出 OneBot/icqq 载荷（兼容 data 嵌套或字段在根级） */
+export function unwrapIcqqEventPayload(event: {
+  data?: unknown;
+  [key: string]: unknown;
+}): unknown {
+  const nested = event.data;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const d = nested as Record<string, unknown>;
+    if (isRecognizedIcqqPayload(d)) {
+      return nested;
+    }
+    for (const key of ["data", "detail", "payload", "event"]) {
+      const inner = d[key];
+      if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+        return inner;
+      }
+    }
+  }
+
+  const { id: _id, event: _ev, data: _data, ok: _ok, ...rest } = event;
+  if (isRecognizedIcqqPayload(rest)) {
+    return rest;
+  }
+  return nested;
+}
+
+function isRecognizedIcqqPayload(d: Record<string, unknown>): boolean {
+  const pt = d.post_type;
+  if (typeof pt === "string") {
+    if (
+      isMessagePostType(pt) ||
+      pt === "notice" ||
+      pt === "request" ||
+      pt === "meta_event" ||
+      pt.startsWith("notice.") ||
+      pt.startsWith("request.") ||
+      pt.startsWith("system.")
+    ) {
+      return true;
+    }
+  }
+  return (
+    d.message_type != null ||
+    d.raw_message != null ||
+    d.message != null ||
+    d.type === "group" ||
+    d.type === "private" ||
+    d.notice_type != null ||
+    d.request_type != null ||
+    d.meta_event_type != null
+  );
+}
+
+export function resolveIcqqInboundUserId(
+  data: Record<string, unknown>,
+): number | undefined {
+  const sender = data.sender;
+  if (sender && typeof sender === "object" && !Array.isArray(sender)) {
+    const suid = (sender as { user_id?: unknown }).user_id;
+    if (suid != null) return Number(suid);
+  }
+  if (data.user_id != null) return Number(data.user_id);
+  if (data.from_id != null) return Number(data.from_id);
+  return undefined;
+}
+
+export function isIcqqMessagePostType(
+  data: unknown,
+): data is IcqqMessageEvent {
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  if (isMessagePostType(d.post_type)) return true;
+  // 其它 post_type（notice/request 等）明确排除
+  if (d.post_type != null && d.post_type !== "") return false;
+  const hasBody =
+    typeof d.raw_message === "string" ||
+    Array.isArray(d.message) ||
+    typeof d.message_type === "string" ||
+    d.type === "group" ||
+    d.type === "private";
+  return hasBody && resolveIcqqInboundUserId(d) != null;
+}
+
+export function shouldSkipSelfInboundMessage(
+  data: IcqqMessageEvent,
+): boolean {
+  if (data.self_id == null || data.user_id == null) return false;
+  return Number(data.self_id) === Number(data.user_id);
+}
+
+/** 群临时会话私聊：icqq message_type=private & sub_type=group */
+export function isIcqqGroupTempPrivateMessage(data: IcqqMessageEvent): boolean {
+  const messageType =
+    data.message_type ??
+    (data.type === "group" || data.type === "private" ? data.type : undefined);
+  if (messageType !== "private") return false;
+  if (data.sub_type === "group") return true;
+  const groupId = data.sender?.group_id;
+  return typeof groupId === "number" && groupId > 0;
+}
+
+export function resolveChannelFromIcqqMessage(
+  data: IcqqMessageEvent,
+): {
+  channelType: "group" | "private";
+  channelId: string;
+  channelParentGroupId?: string;
+} {
+  if (isIcqqGroupTempPrivateMessage(data)) {
+    const groupId = data.sender?.group_id ?? data.group_id;
+    const userId = resolveIcqqInboundUserId(
+      data as unknown as Record<string, unknown>,
+    );
+    if (groupId != null && userId != null) {
+      return {
+        channelType: "private",
+        channelId: String(userId),
+        channelParentGroupId: String(groupId),
+      };
+    }
+  }
+
+  const messageType =
+    data.message_type ??
+    (data.type === "group" || data.type === "private" ? data.type : undefined);
+
+  if (messageType === "group" || data.group_id != null) {
+    return {
+      channelType: "group",
+      channelId: String(data.group_id ?? data.from_id ?? data.user_id),
+    };
+  }
+  return {
+    channelType: "private",
+    channelId: String(data.from_id ?? data.user_id),
+  };
+}
+
+export function resolveIcqqInboundMessageId(
+  data: IcqqMessageEvent,
+  channelId: string,
+): { id: string; source: "message_id" | "msg_id" | "seq" | "synthetic" } {
+  if (data.message_id != null && String(data.message_id) !== "") {
+    return { id: String(data.message_id), source: "message_id" };
+  }
+  if (data.msg_id != null && String(data.msg_id) !== "") {
+    return { id: String(data.msg_id), source: "msg_id" };
+  }
+  if (data.seq != null && String(data.seq) !== "") {
+    return { id: String(data.seq), source: "seq" };
+  }
+  const uid =
+    resolveIcqqInboundUserId(data as unknown as Record<string, unknown>) ?? 0;
+  return {
+    id: `${data.time}_${uid}_${channelId}`,
+    source: "synthetic",
+  };
+}
+
+export function icqqElementsToSegments(
+  elements: IcqqMessageElement[] | undefined,
+): MessageSegment[] | null {
+  if (!elements?.length) return null;
+  const out: MessageSegment[] = [];
+
+  for (const el of elements) {
+    if (!el || typeof el !== "object") continue;
+    const type = el.type;
+    switch (type) {
+      case "text":
+        if (el.text != null && el.text !== "") {
+          out.push({ type: "text", data: { text: String(el.text) } });
+        }
+        break;
+      case "at": {
+        const atId = String(el.qq ?? el.user_id ?? "");
+        const name =
+          typeof el.name === "string"
+            ? el.name
+            : typeof el.nickname === "string"
+              ? el.nickname
+              : undefined;
+        out.push({
+          type: "at",
+          data: name
+            ? { qq: atId, user_id: atId, id: atId, name }
+            : { qq: atId, user_id: atId, id: atId },
+        });
+        break;
+      }
+      case "face":
+        out.push({ type: "face", data: { id: Number(el.id) } });
+        break;
+      case "image": {
+        const value = String(el.url ?? el.file ?? "");
+        if (!value) break;
+        out.push({
+          type: "image",
+          data: { media: icqqMediaRefFromElement(value, el) },
+        });
+        break;
+      }
+      case "flash": {
+        const value = String(el.url ?? el.file ?? "");
+        if (!value) break;
+        out.push({
+          type: "image",
+          data: { media: icqqMediaRefFromElement(value, el), flash: true },
+        });
+        break;
+      }
+      case "forward": {
+        const forwardResid = String(
+          el.id ?? el.resid ?? el.res_id ?? el.file ?? "",
+        ).trim();
+        if (forwardResid) {
+          out.push({
+            type: "forward",
+            data: { id: forwardResid, resid: forwardResid },
+          });
+        } else {
+          out.push({ type: "text", data: { text: "[聊天记录]" } });
+        }
+        break;
+      }
+      case "light_app":
+      case "xml": {
+        const forwardResid = extractForwardResidFromJsonElement(el);
+        if (forwardResid) {
+          out.push({
+            type: "forward",
+            data: { id: forwardResid, resid: forwardResid },
+          });
+        } else if (el.text != null && el.text !== "") {
+          out.push({ type: "text", data: { text: String(el.text) } });
+        } else {
+          out.push({ type: "text", data: { text: "[聊天记录]" } });
+        }
+        break;
+      }
+      case "reply": {
+        const replyId = String(el.id ?? el.message_id ?? "");
+        if (replyId) {
+          out.push({
+            type: "reply",
+            data: { id: replyId, message_id: replyId },
+          });
+        }
+        break;
+      }
+      case "json": {
+        const forwardResid = extractForwardResidFromJsonElement(el);
+        if (forwardResid) {
+          out.push({
+            type: "forward",
+            data: { id: forwardResid, resid: forwardResid },
+          });
+          break;
+        }
+        const replyFromJson = resolveReplyIdFromJsonElement(el);
+        if (replyFromJson) {
+          out.push({
+            type: "reply",
+            data: { id: replyFromJson, message_id: replyFromJson },
+          });
+        } else if (el.text != null && el.text !== "") {
+          out.push({ type: "text", data: { text: String(el.text) } });
+        }
+        break;
+      }
+      case "record":
+      case "audio": {
+        const value = String(el.url ?? el.file ?? "");
+        if (!value) break;
+        out.push({
+          type: "audio",
+          data: {
+            media: icqqMediaRefFromElement(value, el),
+            ...(typeof el.seconds === "number" ? { duration: el.seconds } : {}),
+          },
+        });
+        break;
+      }
+      case "video": {
+        const value = String(el.url ?? el.file ?? "");
+        if (!value) break;
+        out.push({
+          type: "video",
+          data: {
+            media: icqqMediaRefFromElement(value, el),
+            ...(typeof el.seconds === "number" ? { duration: el.seconds } : {}),
+          },
+        });
+        break;
+      }
+      case "file": {
+        const value = String(el.url ?? el.file ?? el.fid ?? "");
+        if (!value) break;
+        const name = typeof el.name === "string" && el.name ? el.name : undefined;
+        out.push({
+          type: "file",
+          data: {
+            media: icqqMediaRefFromElement(value, el),
+            ...(name ? { name } : {}),
+          },
+        });
+        break;
+      }
+      default:
+        if (el.text != null && el.text !== "") {
+          out.push({ type: "text", data: { text: String(el.text) } });
+        }
+        break;
+    }
+  }
+  return out.length ? out : null;
+}
+
+function icqqMediaRefFromElement(
+  value: string,
+  element: IcqqMessageElement,
+): ReturnType<typeof icqqMediaRefFromString> {
+  const media = icqqMediaRefFromString(value);
+  const fileName = typeof element.name === "string" && element.name
+    ? element.name
+    : undefined;
+  const size = typeof element.size === "number" && Number.isFinite(element.size)
+    ? element.size
+    : undefined;
+  return {
+    ...media,
+    ...(fileName ? { file_name: fileName } : {}),
+    ...(size != null ? { size } : {}),
+  };
+}
+
+function resolveReplyIdFromJsonElement(el: IcqqMessageElement): string | undefined {
+  let payload: unknown = el.data ?? el;
+  if (typeof payload === "string") {
+    try {
+      payload = JSON.parse(payload) as unknown;
+    } catch {
+      return undefined;
+    }
+  }
+  if (!payload || typeof payload !== "object") return undefined;
+  const record = payload as Record<string, unknown>;
+  const refer =
+    record.msgRefer ??
+    record.reply ??
+    record.resid ??
+    record.message_id ??
+    record.id;
+  if (refer && typeof refer === "object") {
+    const r = refer as Record<string, unknown>;
+    const id = r.msgId ?? r.message_id ?? r.id ?? r.msg_id;
+    if (id != null && String(id)) return String(id);
+  }
+  if (typeof refer === "string" && refer) return refer;
+  if (typeof refer === "number") return String(refer);
+  return undefined;
+}
+
+const MAX_SOURCE_WALK_DEPTH = 10;
+
+function icqqSourceMessageBody(s: IcqqMessageSource): unknown {
+  return (s as Record<string, unknown>).message;
+}
+
+function icqqSourceHasBody(s: IcqqMessageSource): boolean {
+  const body = icqqSourceMessageBody(s);
+  if (Array.isArray(body) && body.length > 0) return true;
+  if (typeof body === "string" && body.trim().length > 0) return true;
+  return typeof s.raw_message === "string" && s.raw_message.length > 0;
+}
+
+function looksLikeIcqqMessageSource(value: unknown): value is IcqqMessageSource {
+  if (!value || typeof value !== "object") return false;
+  const r = value as Record<string, unknown>;
+  // 整条入站事件也有 message_id，不能与 oicq Message#source 混淆
+  if (r.post_type != null || r.message_type != null) return false;
+  const s = value as IcqqMessageSource;
+  if (!icqqSourceHasBody(s)) return false;
+  return !!resolveQuoteIdFromIcqqSource(value);
+}
+
+/** 载荷可能把 source 嵌在 data / event 等字段，深度查找 */
+export function findIcqqNestedMessageSource(
+  root: unknown,
+  maxDepth = MAX_SOURCE_WALK_DEPTH,
+): IcqqMessageSource | undefined {
+  const seen = new Set<unknown>();
+  function walk(node: unknown, depth: number): IcqqMessageSource | undefined {
+    if (depth > maxDepth || node == null) return undefined;
+    if (typeof node !== "object") return undefined;
+    if (seen.has(node)) return undefined;
+    seen.add(node);
+
+    if (looksLikeIcqqMessageSource(node)) {
+      return node as IcqqMessageSource;
+    }
+
+    const record = node as Record<string, unknown>;
+    if (record.source && looksLikeIcqqMessageSource(record.source)) {
+      return record.source as IcqqMessageSource;
+    }
+
+    for (const value of Object.values(record)) {
+      if (value && typeof value === "object") {
+        const hit = walk(value, depth + 1);
+        if (hit) return hit;
+      }
+    }
+    return undefined;
+  }
+  return walk(root, 0);
+}
+
+/** 从 oicq MessageEvent.source 解析被引用消息的 message_id */
+export function resolveQuoteIdFromIcqqSource(
+  source: unknown,
+): string | undefined {
+  if (!source || typeof source !== "object") return undefined;
+  const s = source as IcqqMessageSource;
+  if (s.message_id != null && String(s.message_id).trim()) {
+    return String(s.message_id).trim();
+  }
+  if (s.msg_id != null && String(s.msg_id).trim()) {
+    return String(s.msg_id).trim();
+  }
+  // NT 引用源常仅有 seq/rand，无 message_id
+  if (s.seq != null && String(s.seq) !== "") {
+    const seq = String(s.seq);
+    if (s.rand != null && String(s.rand) !== "") {
+      return `${seq}:${s.rand}`;
+    }
+    return seq;
+  }
+  return undefined;
+}
+
+function icqqSourceToContentSegments(
+  s: IcqqMessageSource,
+): MessageSegment[] {
+  const body = icqqSourceMessageBody(s);
+  if (Array.isArray(body) && body.length) {
+    return icqqElementsToSegments(body as IcqqMessageElement[]) ?? [];
+  }
+  if (typeof body === "string" && body.trim()) {
+    return [{ type: "text", data: { text: body.trim() } }];
+  }
+  if (typeof s.raw_message === "string" && s.raw_message) {
+    return parseCqMessage(s.raw_message);
+  }
+  return [];
+}
+
+/** Convert an ICQQ source into the adapter-local lookup payload. */
+export function messageLookupFromIcqqSource(
+  source: unknown,
+): IcqqMessageLookup | null {
+  if (!source || typeof source !== "object") return null;
+  const s = source as IcqqMessageSource;
+  const body = icqqSourceMessageBody(s);
+  const content = icqqSourceToContentSegments(s);
+  const messageId = resolveQuoteIdFromIcqqSource(source);
+  if (!messageId && !content.length) return null;
+  const senderRaw = s.sender;
+  const senderFromUserId =
+    s.user_id != null
+      ? { id: String(s.user_id), name: "" }
+      : undefined;
+  return {
+    messageId: messageId ?? `seq:${s.seq ?? 0}:${s.rand ?? 0}`,
+    sender: senderRaw
+      ? {
+          id: String(senderRaw.user_id ?? ""),
+          name: String(senderRaw.nickname ?? senderRaw.card ?? ""),
+        }
+      : senderFromUserId,
+    content,
+    raw:
+      typeof s.raw_message === "string"
+        ? s.raw_message
+        : typeof body === "string"
+          ? body
+          : undefined,
+    time: typeof s.time === "number" ? s.time : undefined,
+  };
+}
+
+/** 从事件顶层字段解析引用 message_id（与 message 段互补） */
+export function resolveIcqqQuoteIdFromEvent(
+  data: IcqqMessageEvent,
+): string | undefined {
+  const fromSource =
+    resolveQuoteIdFromIcqqSource(data.source) ??
+    resolveQuoteIdFromIcqqSource(findIcqqNestedMessageSource(data));
+  if (fromSource) return fromSource;
+
+  const ext = data as IcqqMessageEvent & Record<string, unknown>;
+  const candidates = [
+    ext.reply,
+    ext.quoted_message_id,
+    ext.quote_message_id,
+    ext.source_message_id,
+  ];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.trim()) return c.trim();
+    if (typeof c === "number") return String(c);
+    if (c && typeof c === "object") {
+      const r = c as Record<string, unknown>;
+      const id = r.id ?? r.message_id ?? r.msg_id ?? r.msgId;
+      if (id != null && String(id)) return String(id);
+    }
+  }
+  return undefined;
+}
+
+function mergeReplyFromRawMessage(
+  content: MessageSegment[],
+  rawMessage: string,
+): MessageSegment[] {
+  if (!rawMessage || quoteIdFromSegments(content)) return content;
+  const fromRaw = parseCqMessage(rawMessage);
+  const quoteFromRaw = quoteIdFromSegments(fromRaw);
+  if (!quoteFromRaw) return content;
+  return [
+    { type: "reply", data: { message_id: quoteFromRaw } },
+    ...content.filter((s) => s.type !== "reply"),
+  ];
+}
+
+function mergeReplyFromSource(
+  content: MessageSegment[],
+  data: IcqqMessageEvent,
+): MessageSegment[] {
+  if (quoteIdFromSegments(content)) return content;
+  const quoteId =
+    resolveQuoteIdFromIcqqSource(data.source) ??
+    resolveQuoteIdFromIcqqSource(findIcqqNestedMessageSource(data));
+  if (!quoteId) return content;
+  return [
+    { type: "reply", data: { message_id: quoteId } },
+    ...content.filter((s) => s.type !== "reply"),
+  ];
+}
+
+function quoteIdFromSegments(content: readonly MessageSegment[]): string | undefined {
+  const reply = content.find((item) => item.type === 'reply');
+  const value = reply?.data?.message_id ?? reply?.data?.id;
+  return value == null || !String(value).trim() ? undefined : String(value).trim();
+}
+
+export function resolveInboundContent(
+  data: IcqqMessageEvent,
+): MessageSegment[] {
+  const fromElements = icqqElementsToSegments(data.message);
+  const raw = data.raw_message ?? "";
+  let content: MessageSegment[];
+  if (fromElements?.length) {
+    content = mergeReplyFromRawMessage(fromElements, raw);
+  } else if (raw) {
+    content = parseCqMessage(raw);
+  } else {
+    content = [{ type: "text", data: { text: "" } }];
+  }
+  return toCanonicalSegments(mergeReplyFromSource(content, data));
+}
+
+export function normalizeIcqqInboundMessage(
+  data: IcqqMessageEvent,
+): NormalizedIcqqInbound | null {
+  if (!isIcqqMessagePostType(data)) return null;
+  const ext = data as IcqqMessageEvent & Record<string, unknown>;
+  const userIdNum = resolveIcqqInboundUserId(ext);
+  if (userIdNum == null) return null;
+  const { channelType, channelId, channelParentGroupId } = resolveChannelFromIcqqMessage(data);
+  const resolved = resolveIcqqInboundMessageId(data, channelId);
+  const nickname =
+    data.sender?.nickname ?? data.nickname ?? String(userIdNum);
+  const senderRole =
+    channelType === "group"
+      ? parseIcqqSenderGroupRole(data.sender)
+      : undefined;
+  const rawMessage = data.raw_message ?? "";
+  return {
+    messageId: resolved.id,
+    idSource: resolved.source,
+    channelType,
+    channelId,
+    channelParentGroupId,
+    userId: String(userIdNum),
+    nickname,
+    senderRole,
+    content: resolveInboundContent(data),
+    rawMessage,
+    timestampMs: data.time * 1000,
+    raw: data,
+  };
+}
+
+/** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
+export class InboundMessageDeduper {
+  private readonly seen = new Map<string, number>();
+
+  shouldProcess(messageId: string): boolean {
+    const now = Date.now();
+    for (const [id, t] of this.seen) {
+      if (now - t > DEDUPE_TTL_MS) this.seen.delete(id);
+    }
+    if (this.seen.has(messageId)) return false;
+    this.seen.set(messageId, now);
+    return true;
+  }
+
+  clear(): void {
+    this.seen.clear();
+  }
+}