openclaw-plugin-yuanbao 2.13.4 → 2.14.0

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelEntryContract<import("openclaw/plugin-sdk").ChannelPlugin>;
+declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelEntryContract<import("openclaw/plugin-sdk/channel-plugin-common").ChannelPlugin>;
 export default _default;

package/dist/setup-entry.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelSetupEntryContract<import("openclaw/plugin-sdk").ChannelPlugin>;
+declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelSetupEntryContract<import("openclaw/plugin-sdk/channel-plugin-common").ChannelPlugin>;
 export default _default;

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 {
@@ -366,3 +368,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) {

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

@@ -539,6 +539,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/commands/log-upload/cos-upload.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { apiGetUploadInfo } from "../../../access/api.js";
+import { createCosClient } from "../../../infra/cos.js";
 import { createLog } from "../../../logger.js";
 const DEFAULT_RECORD_API_URL = "https://yuanbao.tencent.com/e/api/clawLogUpload";
 function resolveRecordApiUrl(config) {
@@ -14,46 +15,8 @@ function resolveRecordApiUrl(config) {
 function generateFileId() {
     return randomBytes(16).toString("hex");
 }
-/**
- * Upload Buffer data to Tencent Cloud COS.
- *
- * Same COS upload implementation as uploadBufferToCos in media.ts.
- * Initializes COS SDK with temp credentials from genUploadInfo, then calls putObject.
- * Uses dynamic import for cos-nodejs-sdk-v5, compatible with both CJS and ESM.
- */
 async function uploadBufferToCos(config, data) {
-    let COS;
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        COS = require("cos-nodejs-sdk-v5");
-        if (COS?.default) {
-            COS = COS.default;
-        }
-    }
-    catch {
-        try {
-            const pkg = await import("cos-nodejs-sdk-v5");
-            COS = pkg.default ?? pkg;
-        }
-        catch {
-            throw new Error("缺少依赖 cos-nodejs-sdk-v5，请运行 pnpm add cos-nodejs-sdk-v5");
-        }
-    }
-    const COSConstructor = COS;
-    const cos = new COSConstructor({
-        FileParallelLimit: 10,
-        getAuthorization(_, callback) {
-            callback({
-                TmpSecretId: config.encryptTmpSecretId,
-                TmpSecretKey: config.encryptTmpSecretKey,
-                SecurityToken: config.encryptToken,
-                StartTime: config.startTime,
-                ExpiredTime: config.expiredTime,
-                ScopeLimit: true,
-            });
-        },
-        UseAccelerate: true,
-    });
+    const cos = createCosClient(config);
     await cos.putObject({
         Bucket: config.bucketName,
         Region: config.region,

package/dist/src/business/commands/upgrade/utils.d.ts

@@ -17,7 +17,7 @@ export declare function getLatestStableVersion(): Promise<string | null>;
  */
 export declare function isPublishedVersionOnNpm(version: string): Promise<boolean>;
 /**
- * Parse `openclaw plugins list` output and return the installed version of the specified plugin.
+ * Query `openclaw plugins inspect --json` and return the installed version of the specified plugin.
  * Returns null if plugin is not installed or parsing fails.
  */
 export declare function readInstalledVersion(pluginId: string): Promise<string | null>;

package/dist/src/business/commands/upgrade/utils.js

@@ -123,30 +123,33 @@ export async function isPublishedVersionOnNpm(version) {
     }
 }
 /**
- * Parse `openclaw plugins list` output and return the installed version of the specified plugin.
+ * Query `openclaw plugins inspect --json` and return the installed version of the specified plugin.
  * Returns null if plugin is not installed or parsing fails.
  */
 export async function readInstalledVersion(pluginId) {
     log.info("读取已安装版本", { pluginId });
-    const result = await runOpenClawCommand(["plugins", "list"]);
+    const result = await runOpenClawCommand(["plugins", "inspect", pluginId, "--json"]);
     if (!result.ok) {
-        log.warn("openclaw plugins list 执行失败", {
+        log.warn("openclaw plugins inspect 执行失败", {
             summary: result.error,
             ...(result.stderr ? { stderr: result.stderr } : {}),
         });
         return null;
     }
-    for (const line of (result.stdout ?? "").split("\n")) {
-        if (line.toLowerCase().includes(pluginId.toLowerCase())) {
-            const match = line.match(/(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
-            if (match) {
-                log.info("已安装版本", { pluginId, version: match[1] });
-                return match[1];
-            }
+    try {
+        const data = JSON.parse(result.stdout ?? "");
+        const version = data.plugin?.version;
+        if (version && isValidVersion(version)) {
+            log.info("已安装版本", { pluginId, version });
+            return version;
         }
+        log.warn("未检测到已安装版本", { pluginId, raw: result.stdout });
+        return null;
+    }
+    catch (e) {
+        log.warn("解析 inspect JSON 失败", { pluginId, summary: firstLine(e) });
+        return null;
     }
-    log.warn("未检测到已安装版本", { pluginId });
-    return null;
 }
 /**
  * Snapshot `channels.yuanbao` config, outputting a JSON string usable with `config set ... --strict-json`.

package/dist/src/business/messaging/chat-history.d.ts

@@ -26,10 +26,15 @@ export type MediaHistoryEntry = {
 };
 /** Group chat message history Map, keyed by groupCode */
 export declare const chatHistories: Map<string, GroupHistoryEntry[]>;
-/** Media history LRU, keyed by groupCode, not cleared by clearHistoryEntriesIfEnabled */
+/** Media history LRU, keyed by chatKey. Not cleared by clearHistoryEntriesIfEnabled. */
 export declare const chatMediaHistories: Map<string, MediaHistoryEntry[]>;
+/**
+ * Derive a chat-level cache key for media history.
+ * Format follows prepare-sender convention: `group:{groupCode}` / `direct:{fromAccount}`.
+ */
+export declare function deriveChatKey(isGroup: boolean, groupCode?: string, fromAccount?: string): string;
 /**
  * Write media entry to standalone LRU, evicting oldest entries when exceeding limit.
  * Decoupled from text `chatHistories` to prevent media loss when text history is cleared after @bot.
  */
-export declare function recordMediaHistory(groupCode: string, entry: MediaHistoryEntry): void;
+export declare function recordMediaHistory(chatKey: string, entry: MediaHistoryEntry): void;

package/dist/src/business/messaging/chat-history.js

@@ -8,24 +8,34 @@
  */
 /** Group chat message history Map, keyed by groupCode */
 export const chatHistories = new Map();
-const MEDIA_HISTORY_MAX_PER_GROUP = 50;
-/** Media history LRU, keyed by groupCode, not cleared by clearHistoryEntriesIfEnabled */
+const MEDIA_HISTORY_MAX_PER_CHAT = 50;
+/** Media history LRU, keyed by chatKey. Not cleared by clearHistoryEntriesIfEnabled. */
 export const chatMediaHistories = new Map();
+/**
+ * Derive a chat-level cache key for media history.
+ * Format follows prepare-sender convention: `group:{groupCode}` / `direct:{fromAccount}`.
+ */
+export function deriveChatKey(isGroup, groupCode, fromAccount) {
+    if (isGroup && groupCode) {
+        return `group:${groupCode}`;
+    }
+    return `direct:${fromAccount ?? "unknown"}`;
+}
 /**
  * Write media entry to standalone LRU, evicting oldest entries when exceeding limit.
  * Decoupled from text `chatHistories` to prevent media loss when text history is cleared after @bot.
  */
-export function recordMediaHistory(groupCode, entry) {
+export function recordMediaHistory(chatKey, entry) {
     if (entry.medias.length === 0) {
         return;
     }
-    let list = chatMediaHistories.get(groupCode);
+    let list = chatMediaHistories.get(chatKey);
     if (!list) {
         list = [];
-        chatMediaHistories.set(groupCode, list);
+        chatMediaHistories.set(chatKey, list);
     }
     list.push(entry);
-    if (list.length > MEDIA_HISTORY_MAX_PER_GROUP) {
-        list.splice(0, list.length - MEDIA_HISTORY_MAX_PER_GROUP);
+    if (list.length > MEDIA_HISTORY_MAX_PER_CHAT) {
+        list.splice(0, list.length - MEDIA_HISTORY_MAX_PER_CHAT);
     }
 }

package/dist/src/business/messaging/extract.test.js

@@ -20,9 +20,10 @@ void test("extractTextFromMsgBody 处理混合消息体", () => {
         {
             msg_type: "TIMImageElem",
             msg_content: {
+                uuid: "shot.jpeg",
                 image_info_array: [
-                    { type: 1, url: "https://example.com/img.png" },
-                    { type: 2, url: "https://example.com/medium.png" },
+                    { type: 1, width: 800, height: 600, url: "https://example.com/img.png" },
+                    { type: 2, width: 400, height: 300, url: "https://example.com/medium.png" },
                 ],
             },
         },
@@ -30,9 +31,10 @@ void test("extractTextFromMsgBody 处理混合消息体", () => {
     ]);
     assert.ok(result.rawBody.includes("hello"));
     assert.ok(result.rawBody.includes("world"));
-    assert.ok(result.rawBody.includes("[image1]"));
+    assert.ok(result.rawBody.includes("[image:shot_400_300.jpeg]"), `rawBody was: ${result.rawBody}`);
     assert.equal(result.medias.length, 1);
     assert.equal(result.medias[0].url, "https://example.com/medium.png");
+    assert.equal(result.medias[0].mediaName, "shot_400_300.jpeg");
 });
 void test("extractTextFromMsgBody 处理 @Bot 消息", () => {
     const ctx = makeMockCtx("bot-001");

package/dist/src/business/messaging/handlers/file.js

@@ -4,6 +4,7 @@
  * File message: on input, extracts file URL and filename to media list and returns file identifier;
  * on output, constructs file message body.
  */
+import { sanitizeMediaFilename } from "../../utils/media.js";
 export const fileHandler = {
     msgType: "TIMFileElem",
     /**
@@ -14,10 +15,10 @@ export const fileHandler = {
         const fileUrl = elem.msg_content?.url;
         const fileName = elem.msg_content?.file_name;
         if (fileUrl) {
-            resData.medias.push({ mediaType: "file", url: fileUrl, mediaName: fileName });
-            return fileName
-                ? `[${fileName}]`
-                : `[file${resData.medias.filter(m => m.mediaType === "file").length}]`;
+            const fileCount = resData.medias.filter(m => m.mediaType === "file").length + 1;
+            const displayName = sanitizeMediaFilename(fileName, `file${fileCount}`);
+            resData.medias.push({ mediaType: "file", url: fileUrl, mediaName: displayName });
+            return `[file:${displayName}]`;
         }
         return "[file]";
     },

package/dist/src/business/messaging/handlers/image.d.ts

@@ -1,8 +1,8 @@
 /**
  * TIMImageElem message handler.
  *
- * Image message: on input, extracts image URL to media list and returns [imageN] placeholder;
- * on output, constructs image message body.
+ * Image message: on input, extracts image URL to media list and returns
+ * [image:{name}_{w}_{h}.{ext}] placeholder; on output, constructs image message body.
  */
 import type { MessageElemHandler } from "./types.js";
 export declare const imageHandler: MessageElemHandler;

package/dist/src/business/messaging/handlers/image.js

@@ -1,24 +1,43 @@
 /**
  * TIMImageElem message handler.
  *
- * Image message: on input, extracts image URL to media list and returns [imageN] placeholder;
- * on output, constructs image message body.
+ * Image message: on input, extracts image URL to media list and returns
+ * [image:{name}_{w}_{h}.{ext}] placeholder; on output, constructs image message body.
  */
+import { sanitizeMediaFilename } from "../../utils/media.js";
+/**
+ * Build a descriptive filename for an image from its uuid and dimensions.
+ * e.g. uuid="c9a1b3f8784898.jpeg", w=720, h=1793 → "c9a1b3f8784898_720_1793.jpeg"
+ * Falls back to plain uuid (no dimensions available) or "image{N}" (no uuid).
+ */
+function buildImageMediaName(uuid, w, h, fallbackIndex) {
+    const fallback = `image${fallbackIndex}`;
+    if (!uuid) {
+        return fallback;
+    }
+    const dotIdx = uuid.lastIndexOf(".");
+    const stem = dotIdx > 0 ? uuid.slice(0, dotIdx) : uuid;
+    const ext = dotIdx > 0 ? uuid.slice(dotIdx) : "";
+    const raw = w && h ? `${stem}_${w}_${h}${ext}` : uuid;
+    return sanitizeMediaFilename(raw, fallback);
+}
 export const imageHandler = {
     msgType: "TIMImageElem",
     /**
      * Extract image URL and record to media list.
-     * Returns [imageN] placeholder (1-indexed); undefined if no URL.
+     * Returns [image:{mediaName}] placeholder; undefined if no URL.
+     * mediaName encodes uuid + selected resolution (width x height).
      */
     extract(_ctx, elem, resData) {
-        // Get url from first element in image_info_array (original image, type=1)
         const imageInfoArray = elem.msg_content?.image_info_array;
-        // Use medium-size image for download
+        // Prefer medium-size image (index 1) for download; fall back to original (index 0)
         const imageInfo = imageInfoArray?.[1] || imageInfoArray?.[0];
         if (imageInfo?.url) {
-            resData.medias.push({ mediaType: "image", url: imageInfo.url });
-            // Image index starts from 1, corresponding to [image1][image2]
-            return `[image${resData.medias.filter(m => m.mediaType === "image").length}]`;
+            const uuid = elem.msg_content?.uuid ?? "";
+            const imageCount = resData.medias.filter(m => m.mediaType === "image").length;
+            const mediaName = buildImageMediaName(uuid, imageInfo.width, imageInfo.height, imageCount + 1);
+            resData.medias.push({ mediaType: "image", url: imageInfo.url, mediaName });
+            return `[image:${mediaName}]`;
         }
         return undefined;
     },

package/dist/src/business/messaging/handlers/image.test.js

@@ -24,18 +24,51 @@ void test("imageHandler extract extracts image URL to media list", () => {
     const elem = {
         msg_type: "TIMImageElem",
         msg_content: {
+            uuid: "abc123.jpeg",
             image_info_array: [
-                { type: 1, url: "https://example.com/original.png" },
-                { type: 2, url: "https://example.com/medium.png" },
+                { type: 1, width: 735, height: 1830, url: "https://example.com/original.png" },
+                { type: 2, width: 720, height: 1793, url: "https://example.com/medium.png" },
             ],
         },
     };
     const result = imageHandler.extract(ctx, elem, resData);
-    assert.equal(result, "[image1]");
+    assert.equal(result, "[image:abc123_720_1793.jpeg]");
     assert.equal(resData.medias.length, 1);
     // Prefers medium image (index 1)
     assert.equal(resData.medias[0].url, "https://example.com/medium.png");
     assert.equal(resData.medias[0].mediaType, "image");
+    assert.equal(resData.medias[0].mediaName, "abc123_720_1793.jpeg");
+});
+void test("imageHandler extract falls back to plain uuid when no dimensions", () => {
+    const ctx = makeMockCtx();
+    const resData = makeResData();
+    const elem = {
+        msg_type: "TIMImageElem",
+        msg_content: {
+            uuid: "photo.jpg",
+            image_info_array: [
+                { type: 1, url: "https://example.com/photo.jpg" },
+            ],
+        },
+    };
+    const result = imageHandler.extract(ctx, elem, resData);
+    assert.equal(result, "[image:photo.jpg]");
+    assert.equal(resData.medias[0].mediaName, "photo.jpg");
+});
+void test("imageHandler extract falls back to image{N} when no uuid", () => {
+    const ctx = makeMockCtx();
+    const resData = makeResData();
+    const elem = {
+        msg_type: "TIMImageElem",
+        msg_content: {
+            image_info_array: [
+                { type: 1, width: 100, height: 200, url: "https://example.com/img.png" },
+            ],
+        },
+    };
+    const result = imageHandler.extract(ctx, elem, resData);
+    assert.equal(result, "[image:image1]");
+    assert.equal(resData.medias[0].mediaName, "image1");
 });
 void test("imageHandler extract returns undefined when no URL", () => {
     const ctx = makeMockCtx();

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

@@ -1,22 +1,31 @@
 /**
- * Quote message parsing module.
- *
- * Extracts quoted messages from cloud_custom_data and formats them as context text.
+ * Quote message business logic: parsing, media desc resolution, and formatting.
  */
 import type { QuoteInfo } from "../../types.js";
 /**
- * Parse quote info from cloud_custom_data JSON string.
- * Returns undefined if no quote exists or parsing fails.
+ * Parse quote info from cloud_custom_data JSON string and resolve its desc.
+ *
+ * For media-type quotes (image/file/video/voice) whose desc is empty,
+ * resolves actual filenames from the media history LRU. Falls back to a
+ * generic label (e.g. "[image]") when LRU data is unavailable.
+ *
+ * @param chatKey — used for LRU lookup; pass deriveChatKey() result.
+ * @returns undefined if no quote exists, parsing fails, or the quote carries
+ *          no useful information (empty desc AND not a recognized media type).
+ */
+export declare function parseQuoteFromCloudCustomData(cloudCustomData: string | undefined, chatKey?: string): QuoteInfo | undefined;
+/**
+ * Resolve a descriptive desc for a media-type quote.
+ * Looks up actual filenames from the media history LRU; falls back to
+ * a generic label (e.g. "[image]") when LRU data is unavailable.
  */
-export declare function parseQuoteFromCloudCustomData(cloudCustomData?: string): QuoteInfo | undefined;
+export declare function resolveMediaQuoteDesc(type: number, quoteId: string | undefined, chatKey: string | undefined): string;
 /**
- * Format quoted message into context text that can be appended to user messages.
+ * Format quoted message into context text for AI consumption.
  *
- * Generated format:
  * ```
- * [Quoted message from <sender_nickname>]:
- * <desc (truncated to QUOTE_DESC_MAX_LENGTH)>
- * ---
+ * > [Quoted message from <sender_nickname>]:
+ * ><desc>
  * ```
  */
 export declare function formatQuoteContext(quote: QuoteInfo): string;