openclaw-plugin-yuanbao 2.13.5 → 2.15.0

package/dist/src/access/http/request.d.ts

@@ -44,6 +44,12 @@ export declare function getTokenStatus(accountId: string): {
     status: "valid" | "expired" | "refreshing" | "none";
     expiresAt: number | null;
 };
+export declare function computeSignature(params: {
+    nonce: string;
+    timestamp: string;
+    appKey: string;
+    appSecret: string;
+}): string;
 export declare function verifySignature(expected: string, actual: string): boolean;
 export declare function getSignToken(account: ResolvedYuanbaoAccount, log?: Log): Promise<SignTokenData>;
 export declare function forceRefreshSignToken(account: ResolvedYuanbaoAccount, log?: Log): Promise<SignTokenData>;

package/dist/src/access/http/request.js

@@ -46,7 +46,7 @@ export function getTokenStatus(accountId) {
         expiresAt: cached.expiresAt,
     };
 }
-function computeSignature(params) {
+export function computeSignature(params) {
     const plain = params.nonce + params.timestamp + params.appKey + params.appSecret;
     return createHmac("sha256", params.appSecret).update(plain).digest("hex");
 }

package/dist/src/access/ws/biz-codec.d.ts

@@ -1,6 +1,6 @@
 /** Business-layer Protobuf codec — encode/decode for business messages. */
 import type { YuanbaoInboundMessage, YuanbaoMsgBodyElement } from "../../types.js";
-import type { WsSendC2CMessageData, WsSendGroupMessageData, WsSendMessageResponse, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse } from "./types.js";
+import type { WsSendC2CMessageData, WsSendGroupMessageData, WsSendMessageResponse, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse, WsQueryBotInfoResponse } from "./types.js";
 export declare const BIZ_MSG_TYPES: {
     readonly MsgContent: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.MsgContent";
     readonly MsgBodyElement: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.MsgBodyElement";
@@ -19,6 +19,8 @@ export declare const BIZ_MSG_TYPES: {
     readonly SendGroupHeartbeatRsp: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.SendGroupHeartbeatRsp";
     readonly SyncInformationReq: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.SyncInformationReq";
     readonly SyncInformationRsp: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.SyncInformationRsp";
+    readonly QueryBotInfoReq: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.QueryBotInfoReq";
+    readonly QueryBotInfoRsp: "trpc.yuanbao.yuanbao_conn.yuanbao_openclaw_proxy.QueryBotInfoRsp";
 };
 export declare function encodeBizPB(key: string, value: Record<string, unknown>): Uint8Array | null;
 export declare function decodeBizPB(key: string, data: Uint8Array | ArrayBuffer): unknown;
@@ -64,3 +66,7 @@ export declare function decodeSendGroupHeartbeatRsp(data: Uint8Array | ArrayBuff
 export declare function encodeSyncInformationReq(data: WsSyncInformationData): Uint8Array | null;
 /** Decode SyncInformationRsp. */
 export declare function decodeSyncInformationRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsSyncInformationResponse | null;
+/** Encode QueryBotInfoReq. */
+export declare function encodeQueryBotInfoReq(botId: string): Uint8Array | null;
+/** Decode QueryBotInfoRsp. */
+export declare function decodeQueryBotInfoRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsQueryBotInfoResponse | null;

package/dist/src/access/ws/biz-codec.js

@@ -29,6 +29,8 @@ export const BIZ_MSG_TYPES = {
     SendGroupHeartbeatRsp: `${PKG}.SendGroupHeartbeatRsp`,
     SyncInformationReq: `${PKG}.SyncInformationReq`,
     SyncInformationRsp: `${PKG}.SyncInformationRsp`,
+    QueryBotInfoReq: `${PKG}.QueryBotInfoReq`,
+    QueryBotInfoRsp: `${PKG}.QueryBotInfoRsp`,
 };
 export function encodeBizPB(key, value) {
     try {
@@ -72,6 +74,7 @@ export function toProtoMsgBody(elements) {
                 url: c.url,
                 fileSize: c.file_size,
                 fileName: c.file_name,
+                extMap: c.ext_map,
             },
         };
     });
@@ -120,6 +123,9 @@ export function fromProtoMsgBody(elements) {
         if (mc?.fileName) {
             content.file_name = mc.fileName;
         }
+        if (mc?.extMap && Object.keys(mc.extMap).length > 0) {
+            content.ext_map = mc.extMap;
+        }
         return {
             msg_type: el.msgType || "",
             msg_content: content,
@@ -366,3 +372,21 @@ export function decodeSyncInformationRsp(data, msgId) {
         msg: decoded.msg || "",
     };
 }
+/** Encode QueryBotInfoReq. */
+export function encodeQueryBotInfoReq(botId) {
+    return encodeBizPB(BIZ_MSG_TYPES.QueryBotInfoReq, { botId });
+}
+/** Decode QueryBotInfoRsp. */
+export function decodeQueryBotInfoRsp(data, msgId) {
+    const decoded = decodeBizPB(BIZ_MSG_TYPES.QueryBotInfoRsp, data);
+    if (!decoded) {
+        return null;
+    }
+    return {
+        msgId,
+        code: decoded.code || 0,
+        msg: decoded.message || "",
+        botId: decoded.botInfo?.botId || "",
+        ownerId: decoded.botInfo?.encryptOwnerId || "",
+    };
+}

package/dist/src/access/ws/client.d.ts

@@ -1,6 +1,6 @@
 /** WebSocket client — connection management, auth, heartbeat, and auto-reconnect. */
 import type { LogSink } from "../../logger.js";
-import type { WsClientCallbacks, WsClientConfig, WsClientState, WsConnectionConfig, WsSendMessageResponse, WsSendC2CMessageData, WsSendGroupMessageData, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse } from "./types.js";
+import type { WsClientCallbacks, WsClientConfig, WsClientState, WsConnectionConfig, WsSendMessageResponse, WsSendC2CMessageData, WsSendGroupMessageData, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse, WsQueryBotInfoResponse } from "./types.js";
 /** Outbound business commands */
 export declare const BIZ_CMD: {
     /** Send C2C message */
@@ -12,6 +12,7 @@ export declare const BIZ_CMD: {
     readonly SendPrivateHeartbeat: "send_private_heartbeat";
     readonly SendGroupHeartbeat: "send_group_heartbeat";
     readonly SyncInformation: "sync_information";
+    readonly QueryBotInfo: "query_bot_info";
 };
 /**
  * Yuanbao WebSocket client.
@@ -66,6 +67,8 @@ export declare class YuanbaoWsClient {
     sendGroupHeartbeat(data: WsSendGroupHeartbeatData): Promise<WsHeartbeatResponse>;
     /** Sync information to the backend (command list, etc.). */
     syncInformation(data: WsSyncInformationData): Promise<WsSyncInformationResponse>;
+    /** Query bot info (owner id, etc.) from the backend. */
+    queryBotInfo(botId: string): Promise<WsQueryBotInfoResponse>;
     /** Establish WebSocket connection and bind event handlers. */
     private doConnect;
     private onMessage;

package/dist/src/access/ws/client.js

@@ -4,7 +4,7 @@ import WebSocket from "ws";
 import { msgBodyDesensitization } from "../../business/utils/utils.js";
 import { getPluginVersion, getOpenclawVersion, getOperationSystem } from "../../infra/env.js";
 import { createLog } from "../../logger.js";
-import { encodeSendC2CMessageReq, encodeSendGroupMessageReq, decodeSendMessageRsp, encodeSendPrivateHeartbeatReq, encodeSendGroupHeartbeatReq, decodeSendPrivateHeartbeatRsp, decodeSendGroupHeartbeatRsp, encodeQueryGroupInfoReq, decodeQueryGroupInfoRsp, encodeGetGroupMemberListReq, decodeGetGroupMemberListRsp, encodeSyncInformationReq, decodeSyncInformationRsp, } from "./biz-codec.js";
+import { encodeSendC2CMessageReq, encodeSendGroupMessageReq, decodeSendMessageRsp, encodeSendPrivateHeartbeatReq, encodeSendGroupHeartbeatReq, decodeSendPrivateHeartbeatRsp, decodeSendGroupHeartbeatRsp, encodeQueryGroupInfoReq, decodeQueryGroupInfoRsp, encodeGetGroupMemberListReq, decodeGetGroupMemberListRsp, encodeSyncInformationReq, decodeSyncInformationRsp, encodeQueryBotInfoReq, decodeQueryBotInfoRsp, } from "./biz-codec.js";
 import { decodeConnMsg, decodePB, buildAuthBindMsg, buildPingMsg, buildPushAck, buildBusinessConnMsg, PB_MSG_TYPES, CMD_TYPE, CMD, } from "./conn-codec.js";
 const DEFAULT_RECONNECT_DELAYS = [1_000, 2_000, 5_000, 10_000, 30_000, 60_000];
 const NO_RECONNECT_CLOSE_CODES = new Set([
@@ -42,6 +42,7 @@ export const BIZ_CMD = {
     SendPrivateHeartbeat: "send_private_heartbeat",
     SendGroupHeartbeat: "send_group_heartbeat",
     SyncInformation: "sync_information",
+    QueryBotInfo: "query_bot_info",
 };
 const BIZ_MODULE = "yuanbao_openclaw_proxy";
 /**
@@ -241,6 +242,15 @@ export class YuanbaoWsClient {
         }
         return this.sendAndWaitWith(BIZ_CMD.SyncInformation, BIZ_MODULE, encoded, decodeSyncInformationRsp);
     }
+    /** Query bot info (owner id, etc.) from the backend. */
+    queryBotInfo(botId) {
+        this.log.debug("[bot-info] querying bot info", { botId });
+        const encoded = encodeQueryBotInfoReq(botId);
+        if (!encoded) {
+            return Promise.reject(new Error("Failed to encode QueryBotInfoReq"));
+        }
+        return this.sendAndWaitWith(BIZ_CMD.QueryBotInfo, BIZ_MODULE, encoded, decodeQueryBotInfoRsp);
+    }
     /** Establish WebSocket connection and bind event handlers. */
     doConnect() {
         if (this.disposed) {
@@ -563,6 +573,7 @@ export class YuanbaoWsClient {
         this.lastHeartbeatAt = Date.now();
         this.sendBinary(binary);
         this.log.debug("heartbeat sent");
+        this.scheduleNextPingCheck();
     }
     onPingResponse(head, data) {
         this.heartbeatAckReceived = true;

package/dist/src/access/ws/gateway.js

@@ -35,6 +35,12 @@ export async function startYuanbaoWsGateway(params) {
                         error: String(err),
                     });
                 });
+                // Query and cache bot owner id (non-blocking)
+                queryAndCacheBotOwner(client, account, gwlog).catch((err) => {
+                    gwlog.warn(`[${account.accountId}] failed to query bot owner (non-blocking)`, {
+                        error: String(err),
+                    });
+                });
             },
             onDispatch: (pushEvent) => {
                 gwlog.debug(`[${account.accountId}] WS push: cmd=${pushEvent.cmd}, type=${pushEvent.type}`);
@@ -325,6 +331,28 @@ function handleWsDispatchEvent(params) {
         dlog.error(`[${account.accountId}][dispatch] WS ${isGroup ? "group " : ""} message handler failed: ${String(err)}`);
     });
 }
+/**
+ * Query bot info (owner id) from the backend after connection is established,
+ * and cache the result on the account object for use in owner-gating middleware.
+ *
+ * Called once after auth-bind succeeds. Failures are non-fatal.
+ */
+async function queryAndCacheBotOwner(client, account, log) {
+    const botId = account.botId;
+    if (!botId) {
+        log.warn(`[${account.accountId}] queryAndCacheBotOwner: botId not set, skipping`);
+        return;
+    }
+    const rsp = await client.queryBotInfo(botId);
+    if (rsp.code !== 0) {
+        log.warn(`[${account.accountId}] queryBotInfo returned non-zero code: ${rsp.code}`);
+        return;
+    }
+    if (rsp.ownerId) {
+        account.botOwnerId = rsp.ownerId;
+        log.info(`[${account.accountId}] bot owner cached: ownerId=${rsp.ownerId}`);
+    }
+}
 /**
  * Sync the command list to the backend after connection is established.
  *

package/dist/src/access/ws/proto/biz.json

@@ -97,6 +97,11 @@
                                                 "fileName": {
                                                     "type": "string",
                                                     "id": 12
+                                                },
+                                                "extMap": {
+                                                    "keyType": "string",
+                                                    "type": "string",
+                                                    "id": 999
                                                 }
                                             }
                                         },
@@ -539,6 +544,42 @@
                                                     "id": 2
                                                 }
                                             }
+                                        },
+                                        "BotInfo": {
+                                            "fields": {
+                                                "botId": {
+                                                    "type": "string",
+                                                    "id": 1
+                                                },
+                                                "encryptOwnerId": {
+                                                    "type": "string",
+                                                    "id": 2
+                                                }
+                                            }
+                                        },
+                                        "QueryBotInfoReq": {
+                                            "fields": {
+                                                "botId": {
+                                                    "type": "string",
+                                                    "id": 1
+                                                }
+                                            }
+                                        },
+                                        "QueryBotInfoRsp": {
+                                            "fields": {
+                                                "code": {
+                                                    "type": "int32",
+                                                    "id": 1
+                                                },
+                                                "message": {
+                                                    "type": "string",
+                                                    "id": 2
+                                                },
+                                                "botInfo": {
+                                                    "type": "BotInfo",
+                                                    "id": 3
+                                                }
+                                            }
                                         }
                                     }
                                 }

package/dist/src/access/ws/types.d.ts

@@ -173,3 +173,15 @@ export type WsSyncInformationResponse = {
     code: number;
     msg: string;
 };
+/** Query bot info request */
+export type WsQueryBotInfoData = {
+    bot_id: string;
+};
+/** Query bot info response */
+export type WsQueryBotInfoResponse = {
+    msgId: string;
+    code: number;
+    msg: string;
+    botId: string;
+    ownerId: string;
+};

package/dist/src/business/messaging/context.d.ts

@@ -7,6 +7,10 @@ import type { ResolvedYuanbaoAccount } from "../../types.js";
 /** Message processing context */
 export type MessageHandlerContext = {
     groupCode?: string;
+    /** User ID/account that sent the message; used for ext_map key matching. */
+    fromAccount?: string;
+    /** Display name of the message sender; used by forwarded-record parsing. */
+    senderNickname?: string;
     account: ResolvedYuanbaoAccount;
     config: OpenClawConfig;
     core: PluginRuntime;

package/dist/src/business/messaging/handlers/custom/forward-records-proto.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Protobuf decoder for WeChat forwarded chat-record payloads.
+ *
+ * The server stores `ForwardMsgData` in `MsgContent.ext_map` as a base64
+ * string whose decoded bytes are protobuf wire data.
+ */
+import type { ForwardMsgData } from "./forward-records.js";
+export declare function decodeForwardMsgDataBase64(value: string): ForwardMsgData | undefined;

package/dist/src/business/messaging/handlers/custom/forward-records-proto.js

@@ -0,0 +1,103 @@
+/**
+ * Protobuf decoder for WeChat forwarded chat-record payloads.
+ *
+ * The server stores `ForwardMsgData` in `MsgContent.ext_map` as a base64
+ * string whose decoded bytes are protobuf wire data.
+ */
+import protobuf from "protobufjs";
+const FORWARD_PROTO_DESCRIPTOR = {
+    nested: {
+        ForwardMsgData: {
+            fields: {
+                sub_type: { type: "int32", id: 1 },
+                msg_begin_time: { type: "int64", id: 2 },
+                msg_end_time: { type: "int64", id: 3 },
+                nick_name: { type: "string", id: 4 },
+                msg: { rule: "repeated", type: "Msg", id: 5 },
+            },
+        },
+        Msg: {
+            fields: {
+                sender: { type: "string", id: 1 },
+                time: { type: "int64", id: 2 },
+                plainText: { type: "string", id: 3 },
+                msgContent: { rule: "repeated", type: "MsgContent", id: 4 },
+            },
+        },
+        MsgContent: {
+            fields: {
+                type: { type: "int32", id: 1 },
+                text: { type: "string", id: 2 },
+                multimedia: { rule: "repeated", type: "Multimedia", id: 3 },
+            },
+        },
+        Multimedia: {
+            fields: {
+                type: { type: "string", id: 1 },
+                url: { type: "string", id: 2 },
+                origin_url: { type: "string", id: 3 },
+                file_name: { type: "string", id: 4 },
+                size: { type: "int64", id: 5 },
+                width: { type: "int32", id: 6 },
+                height: { type: "int32", id: 7 },
+                style: { type: "string", id: 8 },
+                pendants: { rule: "repeated", type: "string", id: 9 },
+                created_time: { type: "int64", id: 10 },
+                index_url: { type: "string", id: 11 },
+                cover_url: { type: "string", id: 12 },
+                duration: { type: "int64", id: 13 },
+                guide_id: { type: "int32", id: 14 },
+                media_id: { type: "string", id: 15 },
+                extract: { type: "bool", id: 16 },
+                title: { type: "string", id: 17 },
+                content: { type: "string", id: 18 },
+                session_id: { type: "string", id: 19 },
+                question_id: { type: "string", id: 20 },
+                goods_trace_id: { type: "string", id: 21 },
+                cache_key: { type: "string", id: 22 },
+                chat_record_id: { type: "string", id: 23 },
+                doc_type: { type: "string", id: 24 },
+                image_base64: { type: "string", id: 25 },
+                parse_file_type: { type: "string", id: 26 },
+                parse_file_url: { type: "string", id: 27 },
+                sensitive: { type: "bool", id: 28 },
+                extra: { type: "string", id: 29 },
+                icon_url: { type: "string", id: 30 },
+                source: { type: "string", id: 31 },
+                app_id: { type: "string", id: 32 },
+                link_url: { type: "string", id: 33 },
+                msg_count: { type: "int32", id: 34 },
+                msg_time: { type: "int64", id: 35 },
+                forward_msg_id: { type: "string", id: 36 },
+            },
+        },
+    },
+};
+let forwardMsgDataType;
+function getForwardMsgDataType() {
+    if (!forwardMsgDataType) {
+        forwardMsgDataType = protobuf.Root.fromJSON(FORWARD_PROTO_DESCRIPTOR).lookupType("ForwardMsgData");
+    }
+    return forwardMsgDataType;
+}
+export function decodeForwardMsgDataBase64(value) {
+    try {
+        const bytes = Buffer.from(value, "base64");
+        if (bytes.length === 0) {
+            return undefined;
+        }
+        const type = getForwardMsgDataType();
+        const decoded = type.decode(bytes);
+        const object = type.toObject(decoded, {
+            longs: String,
+            enums: Number,
+            bytes: String,
+            arrays: true,
+            objects: true,
+        });
+        return object && typeof object === "object" ? object : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/business/messaging/handlers/custom/forward-records.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WeChat forwarded chat-record (elem_type 1009) parsing.
+ *
+ * A forwarded chat record carries a truncated summary in `msg_content.data.text`
+ * and the full structured detail in `msg_content.ext_map` (protobuf field 999).
+ * The ext_map value is a base64-encoded protobuf `ForwardMsgData`.
+ *
+ * This module turns that detail into readable chat-record lines and appends
+ * contained images/files to the shared `medias` list so the existing download
+ * pipeline fetches them — matching how imageHandler / fileHandler already behave.
+ */
+import type { ExtractTextFromMsgBodyResult } from "../types.js";
+/** Multimedia entry inside a forwarded message content. */
+export interface ForwardMultimedia {
+    type?: string;
+    url?: string;
+    origin_url?: string;
+    parse_file_url?: string;
+    link_url?: string;
+    file_name?: string;
+    media_id?: string;
+    doc_type?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+/** One content fragment of a forwarded message. */
+export interface ForwardMsgContent {
+    type?: number;
+    text?: string;
+    multimedia?: ForwardMultimedia[];
+}
+/** One message inside a forwarded chat record. */
+export interface ForwardMsg {
+    sender?: string;
+    time?: number | string;
+    plainText?: string;
+    msgContent?: ForwardMsgContent[];
+}
+/** Parsed `ForwardMsgData` (ext_map value). */
+export interface ForwardMsgData {
+    sub_type?: number;
+    msg_begin_time?: number | string;
+    msg_end_time?: number | string;
+    nick_name?: string;
+    msg?: ForwardMsg[];
+}
+/**
+ * Extract the `ForwardMsgData` from a `msg_content.ext_map`.
+ *
+ * Matching strategy (per spec): prefer a `wexin_forward_msg_*` key that ends
+ * with `_{userId}`; otherwise fall back to the first entry that parses into a
+ * WeChat chat record (`sub_type === 1`). Returns undefined when none matches.
+ */
+export declare function parseForwardMsgData(extMap: Record<string, unknown> | undefined, userId?: string): ForwardMsgData | undefined;
+/**
+ * Build a structured text block from a forwarded chat record and append any
+ * contained images/files to `resData.medias` (and link URLs to
+ * `resData.linkUrls`) for the downstream download / link-understanding steps.
+ *
+ * @param senderNickname display name of the user who forwarded the record.
+ * @returns the structured text, or undefined when the record has no messages.
+ */
+export declare function buildForwardRecordsText(data: ForwardMsgData, resData: ExtractTextFromMsgBodyResult, senderNickname?: string): string | undefined;

package/dist/src/business/messaging/handlers/custom/forward-records.js

@@ -0,0 +1,169 @@
+/**
+ * WeChat forwarded chat-record (elem_type 1009) parsing.
+ *
+ * A forwarded chat record carries a truncated summary in `msg_content.data.text`
+ * and the full structured detail in `msg_content.ext_map` (protobuf field 999).
+ * The ext_map value is a base64-encoded protobuf `ForwardMsgData`.
+ *
+ * This module turns that detail into readable chat-record lines and appends
+ * contained images/files to the shared `medias` list so the existing download
+ * pipeline fetches them — matching how imageHandler / fileHandler already behave.
+ */
+import { sanitizeMediaFilename } from "../../../utils/media.js";
+import { decodeForwardMsgDataBase64 } from "./forward-records-proto.js";
+/** EnumMsgContentType inside a forwarded record. */
+var ForwardContentType;
+(function (ForwardContentType) {
+    ForwardContentType[ForwardContentType["Text"] = 1] = "Text";
+    ForwardContentType[ForwardContentType["Multimedia"] = 2] = "Multimedia";
+    ForwardContentType[ForwardContentType["ForwardMsg"] = 3] = "ForwardMsg";
+})(ForwardContentType || (ForwardContentType = {}));
+/** ext_map key prefix for WeChat forwarded chat records. */
+const FORWARD_KEY_PREFIX = "wexin_forward_msg_";
+/** Cap the number of records folded into a prompt to keep it bounded. */
+const MAX_RECORDS = 100;
+const HEADER_RECORDS = "以下为用户的聊天记录";
+/**
+ * Extract the `ForwardMsgData` from a `msg_content.ext_map`.
+ *
+ * Matching strategy (per spec): prefer a `wexin_forward_msg_*` key that ends
+ * with `_{userId}`; otherwise fall back to the first entry that parses into a
+ * WeChat chat record (`sub_type === 1`). Returns undefined when none matches.
+ */
+export function parseForwardMsgData(extMap, userId) {
+    if (!extMap || typeof extMap !== "object") {
+        return undefined;
+    }
+    const entries = Object.entries(extMap).filter(([key]) => key.startsWith(FORWARD_KEY_PREFIX));
+    if (entries.length === 0) {
+        return undefined;
+    }
+    // Prefer a key whose suffix matches the current user; otherwise keep order.
+    const ordered = userId
+        ? [...entries].sort(([a], [b]) => {
+            const am = a.endsWith(`_${userId}`) ? 0 : 1;
+            const bm = b.endsWith(`_${userId}`) ? 0 : 1;
+            return am - bm;
+        })
+        : entries;
+    for (const [, value] of ordered) {
+        const data = coerceForwardData(value);
+        if (data && Number(data.sub_type) === 1) {
+            return data;
+        }
+    }
+    return undefined;
+}
+function coerceForwardData(value) {
+    if (typeof value === "string") {
+        return decodeForwardMsgDataBase64(value);
+    }
+    return undefined;
+}
+/**
+ * Build a structured text block from a forwarded chat record and append any
+ * contained images/files to `resData.medias` (and link URLs to
+ * `resData.linkUrls`) for the downstream download / link-understanding steps.
+ *
+ * @param senderNickname display name of the user who forwarded the record.
+ * @returns the structured text, or undefined when the record has no messages.
+ */
+export function buildForwardRecordsText(data, resData, senderNickname) {
+    const msgList = Array.isArray(data.msg) ? data.msg.slice(0, MAX_RECORDS) : [];
+    if (msgList.length === 0) {
+        return undefined;
+    }
+    const lines = [];
+    if (senderNickname) {
+        lines.push(`当前用户的昵称为${senderNickname}`);
+    }
+    lines.push(HEADER_RECORDS);
+    for (const msg of msgList) {
+        const sender = msg.sender ?? "";
+        const parts = buildMessageParts(msg, resData);
+        const body = parts.length > 0 ? parts.join("  ") : (msg.plainText ?? "");
+        lines.push(`${sender}：${body}`);
+    }
+    return lines.join("\n");
+}
+function buildMessageParts(msg, resData) {
+    const contents = Array.isArray(msg.msgContent) ? msg.msgContent : [];
+    if (contents.length === 0) {
+        return [];
+    }
+    const parts = [];
+    for (const content of contents) {
+        switch (content.type) {
+            case ForwardContentType.Text:
+                if (content.text) {
+                    parts.push(content.text);
+                }
+                break;
+            case ForwardContentType.Multimedia:
+                for (const media of content.multimedia ?? []) {
+                    const part = appendMedia(media, resData);
+                    if (part) {
+                        parts.push(part);
+                    }
+                }
+                break;
+            case ForwardContentType.ForwardMsg:
+                parts.push("[嵌套聊天记录]");
+                break;
+            default:
+                if (msg.plainText) {
+                    parts.push(msg.plainText);
+                }
+                break;
+        }
+    }
+    return parts;
+}
+/**
+ * Resolve a single multimedia item to a text placeholder and, for downloadable
+ * media (image/file/code/video-as-file), push it to `resData.medias`. Link
+ * shares are recorded in `resData.linkUrls` for link understanding.
+ */
+function appendMedia(media, resData) {
+    const mediaType = (media.type || media.doc_type || "").toLowerCase();
+    const url = media.url || media.origin_url || media.parse_file_url || media.link_url || "";
+    switch (mediaType) {
+        case "image": {
+            if (!url) {
+                return `[image:${media.file_name || "image"}]`;
+            }
+            const count = resData.medias.filter(m => m.mediaType === "image").length + 1;
+            const mediaName = sanitizeMediaFilename(media.file_name || media.media_id, `image${count}`);
+            resData.medias.push({ mediaType: "image", url, mediaName });
+            return `[image:${mediaName}]`;
+        }
+        case "file":
+        case "code":
+        case "document": {
+            if (!url) {
+                return `[file:${media.file_name || "file"}]`;
+            }
+            const count = resData.medias.filter(m => m.mediaType === "file").length + 1;
+            const mediaName = sanitizeMediaFilename(media.file_name || media.media_id, `file${count}`);
+            resData.medias.push({ mediaType: "file", url, mediaName });
+            return `[file:${mediaName}]`;
+        }
+        case "url": {
+            if (url) {
+                resData.linkUrls.push(url);
+            }
+            return `[link] ${[media.title || media.file_name, url].filter(Boolean).join(" ")}`.trimEnd();
+        }
+        case "video": {
+            if (!url) {
+                return `[video] ${media.file_name || "video"}`;
+            }
+            const count = resData.medias.filter(m => m.mediaType === "file").length + 1;
+            const mediaName = sanitizeMediaFilename(media.file_name || media.media_id, `video${count}`);
+            resData.medias.push({ mediaType: "file", url, mediaName });
+            return `[video:${mediaName}]`;
+        }
+        default:
+            return `[${mediaType || "media"}] ${url || media.file_name || ""}`.trimEnd();
+    }
+}