@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/tools/oapi/im/message.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_user_message tool -- 以用户身份发送/回复 IM 消息
+ *
+ * Actions: send, reply
+ *
+ * Uses the Feishu IM API:
+ *   - send:  POST /open-apis/im/v1/messages?receive_id_type=...
+ *   - reply: POST /open-apis/im/v1/messages/:message_id/reply
+ *
+ * 全部以用户身份（user_access_token）调用，scope 来自 real-scope.json。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuImUserMessageTool = registerFeishuImUserMessageTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const FeishuImMessageSchema = typebox_1.Type.Union([
+    // SEND
+    typebox_1.Type.Object({
+        action: typebox_1.Type.Literal('send'),
+        receive_id_type: (0, helpers_1.StringEnum)(['open_id', 'chat_id'], {
+            description: '接收者 ID 类型：open_id（私聊，ou_xxx）、chat_id（群聊，oc_xxx）',
+        }),
+        receive_id: typebox_1.Type.String({
+            description: "接收者 ID，与 receive_id_type 对应。open_id 填 'ou_xxx'，chat_id 填 'oc_xxx'",
+        }),
+        msg_type: (0, helpers_1.StringEnum)(['text', 'post', 'image', 'file', 'audio', 'media', 'interactive', 'share_chat', 'share_user'], {
+            description: '消息类型：text（纯文本）、post（富文本）、image（图片）、file（文件）、interactive（消息卡片）、share_chat（群名片）、share_user（个人名片）等',
+        }),
+        content: typebox_1.Type.String({
+            description: '消息内容（JSON 字符串），格式取决于 msg_type。' +
+                '示例：text → \'{"text":"你好"}\'，' +
+                'image → \'{"image_key":"img_xxx"}\'，' +
+                'share_chat → \'{"chat_id":"oc_xxx"}\'，' +
+                'post → \'{"zh_cn":{"title":"标题","content":[[{"tag":"text","text":"正文"}]]}}\'',
+        }),
+        uuid: typebox_1.Type.Optional(typebox_1.Type.String({
+            description: '幂等唯一标识。同一 uuid 在 1 小时内只会发送一条消息，用于去重',
+        })),
+    }),
+    // REPLY
+    typebox_1.Type.Object({
+        action: typebox_1.Type.Literal('reply'),
+        message_id: typebox_1.Type.String({
+            description: '被回复消息的 ID（om_xxx 格式）',
+        }),
+        msg_type: (0, helpers_1.StringEnum)(['text', 'post', 'image', 'file', 'audio', 'media', 'interactive', 'share_chat', 'share_user'], {
+            description: '消息类型：text（纯文本）、post（富文本）、image（图片）、interactive（消息卡片）等',
+        }),
+        content: typebox_1.Type.String({
+            description: '回复消息内容（JSON 字符串），格式同 send 的 content',
+        }),
+        reply_in_thread: typebox_1.Type.Optional(typebox_1.Type.Boolean({
+            description: '是否以话题形式回复。true 则消息出现在该消息的话题中，false（默认）则出现在聊天主流',
+        })),
+        uuid: typebox_1.Type.Optional(typebox_1.Type.String({
+            description: '幂等唯一标识',
+        })),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerFeishuImUserMessageTool(api) {
+    if (!api.config)
+        return false;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_im_user_message');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_im_user_message',
+        label: 'Feishu: IM User Message',
+        description: '飞书用户身份 IM 消息工具。**有且仅当用户明确要求以自己身份发消息、回复消息时使用，当没有明确要求时优先使用message系统工具**。' +
+            '\n\nActions:' +
+            '\n- send（发送消息）：发送消息到私聊或群聊。私聊用 receive_id_type=open_id，群聊用 receive_id_type=chat_id' +
+            '\n- reply（回复消息）：回复指定 message_id 的消息，支持话题回复（reply_in_thread=true）' +
+            '\n\n【重要】content 必须是合法 JSON 字符串，格式取决于 msg_type。' +
+            '最常用：text 类型 content 为 \'{"text":"消息内容"}\'。' +
+            '\n\n【安全约束】此工具以用户身份发送消息，发出后对方看到的发送者是用户本人。' +
+            '调用前必须先向用户确认：1) 发送对象（哪个人或哪个群）2) 消息内容。' +
+            '禁止在用户未明确同意的情况下自行发送消息。',
+        parameters: FeishuImMessageSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                switch (p.action) {
+                    // -----------------------------------------------------------------
+                    // SEND MESSAGE
+                    // -----------------------------------------------------------------
+                    case 'send': {
+                        log.info(`send: receive_id_type=${p.receive_id_type}, receive_id=${p.receive_id}, msg_type=${p.msg_type}`);
+                        const res = await client.invoke('feishu_im_user_message.send', (sdk, opts) => sdk.im.v1.message.create({
+                            params: { receive_id_type: p.receive_id_type },
+                            data: {
+                                receive_id: p.receive_id,
+                                msg_type: p.msg_type,
+                                content: p.content,
+                                uuid: p.uuid,
+                            },
+                        }, opts), {
+                            as: 'user',
+                        });
+                        (0, helpers_1.assertLarkOk)(res);
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const data = res.data;
+                        log.info(`send: message sent, message_id=${data?.message_id}`);
+                        return (0, helpers_1.json)({
+                            message_id: data?.message_id,
+                            chat_id: data?.chat_id,
+                            create_time: data?.create_time,
+                        });
+                    }
+                    // -----------------------------------------------------------------
+                    // REPLY MESSAGE
+                    // -----------------------------------------------------------------
+                    case 'reply': {
+                        log.info(`reply: message_id=${p.message_id}, msg_type=${p.msg_type}, reply_in_thread=${p.reply_in_thread ?? false}`);
+                        const res = await client.invoke('feishu_im_user_message.reply', (sdk, opts) => sdk.im.v1.message.reply({
+                            path: { message_id: p.message_id },
+                            data: {
+                                content: p.content,
+                                msg_type: p.msg_type,
+                                reply_in_thread: p.reply_in_thread,
+                                uuid: p.uuid,
+                            },
+                        }, opts), {
+                            as: 'user',
+                        });
+                        (0, helpers_1.assertLarkOk)(res);
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const data = res.data;
+                        log.info(`reply: message sent, message_id=${data?.message_id}`);
+                        return (0, helpers_1.json)({
+                            message_id: data?.message_id,
+                            chat_id: data?.chat_id,
+                            create_time: data?.create_time,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_im_user_message' });
+}

package/src/tools/oapi/im/resource.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_user_fetch_resource tool -- 以用户身份下载 IM 消息中的文件/图片资源
+ *
+ * 使用飞书 API:
+ *   - im.v1.messageResource.get: GET /open-apis/im/v1/messages/:message_id/resources/:file_key
+ *
+ * 全部以用户身份（user_access_token）调用，scope 来自 real-scope.json。
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuImUserFetchResourceTool(api: OpenClawPluginApi): boolean;

package/src/tools/oapi/im/resource.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_user_fetch_resource tool -- 以用户身份下载 IM 消息中的文件/图片资源
+ *
+ * 使用飞书 API:
+ *   - im.v1.messageResource.get: GET /open-apis/im/v1/messages/:message_id/resources/:file_key
+ *
+ * 全部以用户身份（user_access_token）调用，scope 来自 real-scope.json。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuImUserFetchResourceTool = registerFeishuImUserFetchResourceTool;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const temp_path_1 = require("openclaw/plugin-sdk/temp-path");
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Helper: MIME type to extension mapping
+// ---------------------------------------------------------------------------
+const MIME_TO_EXT = {
+    // Images
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'image/bmp': '.bmp',
+    'image/tiff': '.tiff',
+    // Videos
+    'video/mp4': '.mp4',
+    'video/mpeg': '.mpeg',
+    'video/quicktime': '.mov',
+    'video/x-msvideo': '.avi',
+    'video/webm': '.webm',
+    // Audio
+    'audio/mpeg': '.mp3',
+    'audio/wav': '.wav',
+    'audio/ogg': '.ogg',
+    'audio/mp4': '.m4a',
+    // Documents
+    'application/pdf': '.pdf',
+    'application/msword': '.doc',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'application/vnd.ms-excel': '.xls',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.ms-powerpoint': '.ppt',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+    // Others
+    'application/zip': '.zip',
+    'application/x-rar-compressed': '.rar',
+    'text/plain': '.txt',
+    'application/json': '.json',
+};
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const FetchResourceSchema = typebox_1.Type.Object({
+    message_id: typebox_1.Type.String({
+        description: '消息 ID（om_xxx 格式），从消息事件或消息列表中获取',
+    }),
+    file_key: typebox_1.Type.String({
+        description: '资源 Key，从消息体中获取。图片消息的 image_key（img_xxx）或文件消息的 file_key（file_xxx）',
+    }),
+    type: (0, helpers_1.StringEnum)(['image', 'file'], {
+        description: '资源类型：image（图片消息中的图片）、file（文件/音频/视频消息中的文件）',
+    }),
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerFeishuImUserFetchResourceTool(api) {
+    if (!api.config)
+        return false;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_im_user_fetch_resource');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_im_user_fetch_resource',
+        label: 'Feishu: IM Fetch Resource',
+        description: '【以用户身份】下载飞书 IM 消息中的文件或图片资源到本地文件。需要用户 OAuth 授权。' +
+            '\n\n适用场景：当你以用户身份调用了消息列表/搜索等 API 获取到 message_id 和 file_key 时，' +
+            '应使用本工具以同样的用户身份下载资源。' +
+            '\n注意：如果 message_id 来自当前对话上下文（用户发给机器人的消息、引用的消息），' +
+            '请使用 feishu_im_bot_image 工具以机器人身份下载，无需用户授权。' +
+            '\n\n参数说明：' +
+            '\n- message_id：消息 ID（om_xxx），从消息事件或消息列表中获取' +
+            '\n- file_key：资源 Key，从消息体中获取。图片用 image_key（img_xxx），文件用 file_key（file_xxx）' +
+            '\n- type：图片用 image，文件/音频/视频用 file' +
+            '\n\n文件自动保存到 /tmp/openclaw/ 下，返回值中的 saved_path 为实际保存路径。' +
+            '\n限制：文件大小不超过 100MB。不支持下载表情包、合并转发消息、卡片中的资源。',
+        parameters: FetchResourceSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                log.info(`fetch_resource: message_id="${p.message_id}", file_key="${p.file_key}", type="${p.type}"`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const res = await client.invoke('feishu_im_user_fetch_resource.default', (sdk, opts) => sdk.im.v1.messageResource.get({
+                    params: { type: p.type },
+                    path: { message_id: p.message_id, file_key: p.file_key },
+                }, opts), {
+                    as: 'user',
+                });
+                // 响应是二进制流，使用 getReadableStream() 读取
+                const stream = res.getReadableStream();
+                const chunks = [];
+                for await (const chunk of stream) {
+                    chunks.push(chunk);
+                }
+                const buffer = Buffer.concat(chunks);
+                log.info(`fetch_resource: downloaded ${buffer.length} bytes`);
+                // 从响应头获取 Content-Type，并确定文件扩展名
+                const contentType = res.headers?.['content-type'] || '';
+                log.info(`fetch_resource: content-type=${contentType}`);
+                // 从 Content-Type 推断扩展名，自动生成保存路径
+                const mimeType = contentType ? contentType.split(';')[0].trim() : '';
+                const mimeExt = mimeType ? MIME_TO_EXT[mimeType] : undefined;
+                const finalPath = (0, temp_path_1.buildRandomTempFilePath)({
+                    prefix: 'im-resource',
+                    extension: mimeExt,
+                });
+                log.info(`fetch_resource: saving to ${finalPath}`);
+                // 确保父目录存在
+                await fs.mkdir(path.dirname(finalPath), { recursive: true });
+                // 保存文件
+                try {
+                    await fs.writeFile(finalPath, buffer);
+                    log.info(`fetch_resource: saved to ${finalPath}`);
+                    return (0, helpers_1.json)({
+                        message_id: p.message_id,
+                        file_key: p.file_key,
+                        type: p.type,
+                        size_bytes: buffer.length,
+                        content_type: contentType,
+                        saved_path: finalPath,
+                    });
+                }
+                catch (err) {
+                    log.error(`fetch_resource: failed to save file: ${err}`);
+                    return (0, helpers_1.json)({
+                        error: `保存文件失败: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_im_user_fetch_resource' });
+}

package/src/tools/oapi/im/time-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 时间工具函数 — 对齐 Go 实现 (time.go + timerange.go)
+ *
+ * 以 ISO 8601 (RFC 3339) 作为标准时间交换格式，
+ * 提供 ISO 8601 ↔ Unix 转换工具及时间范围解析。
+ */
+/** Unix 秒（数字）→ ISO 8601 北京时间 */
+export declare function secondsToDateTime(seconds: number): string;
+/** Unix 秒（字符串）→ ISO 8601 北京时间 */
+export declare function secondsStringToDateTime(seconds: string): string;
+/** Unix 毫秒（数字）→ ISO 8601 北京时间 */
+export declare function millisToDateTime(millis: number): string;
+/** Unix 毫秒（字符串）→ ISO 8601 北京时间 */
+export declare function millisStringToDateTime(millis: string): string;
+/** ISO 8601 → Unix 秒（数字） */
+export declare function dateTimeToSeconds(datetime: string): number;
+/** ISO 8601 → Unix 秒（字符串） */
+export declare function dateTimeToSecondsString(datetime: string): string;
+/** ISO 8601 → Unix 毫秒（数字） */
+export declare function dateTimeToMillis(datetime: string): number;
+/** ISO 8601 时间范围 */
+export interface TimeRange {
+    start: string;
+    end: string;
+}
+/**
+ * 解析时间范围标识，返回 ISO 8601 字符串对。
+ *
+ * 支持的格式：
+ * - `today` / `yesterday` / `day_before_yesterday`
+ * - `this_week` / `last_week` / `this_month` / `last_month`
+ * - `last_{N}_{unit}` — unit: minutes / hours / days
+ *
+ * 所有计算基于北京时间 (UTC+8)。
+ */
+export declare function parseTimeRange(input: string): TimeRange;
+/**
+ * 解析时间范围标识，返回 Unix 秒字符串对（供 SDK 调用）。
+ */
+export declare function parseTimeRangeToSeconds(input: string): {
+    start: string;
+    end: string;
+};

package/src/tools/oapi/im/time-utils.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 时间工具函数 — 对齐 Go 实现 (time.go + timerange.go)
+ *
+ * 以 ISO 8601 (RFC 3339) 作为标准时间交换格式，
+ * 提供 ISO 8601 ↔ Unix 转换工具及时间范围解析。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secondsToDateTime = secondsToDateTime;
+exports.secondsStringToDateTime = secondsStringToDateTime;
+exports.millisToDateTime = millisToDateTime;
+exports.millisStringToDateTime = millisStringToDateTime;
+exports.dateTimeToSeconds = dateTimeToSeconds;
+exports.dateTimeToSecondsString = dateTimeToSecondsString;
+exports.dateTimeToMillis = dateTimeToMillis;
+exports.parseTimeRange = parseTimeRange;
+exports.parseTimeRangeToSeconds = parseTimeRangeToSeconds;
+const BJ_OFFSET_MS = 8 * 60 * 60 * 1000;
+// ===========================================================================
+// ISO 8601 ↔ Unix 转换工具（对齐 time.go）
+// ===========================================================================
+/** 将 Date 格式化为北京时间 ISO 8601 字符串 */
+function formatBeijingISO(d) {
+    const bj = new Date(d.getTime() + BJ_OFFSET_MS);
+    const y = bj.getUTCFullYear();
+    const mo = String(bj.getUTCMonth() + 1).padStart(2, '0');
+    const da = String(bj.getUTCDate()).padStart(2, '0');
+    const h = String(bj.getUTCHours()).padStart(2, '0');
+    const mi = String(bj.getUTCMinutes()).padStart(2, '0');
+    const s = String(bj.getUTCSeconds()).padStart(2, '0');
+    return `${y}-${mo}-${da}T${h}:${mi}:${s}+08:00`;
+}
+// ---------------------------------------------------------------------------
+// Unix 秒 → ISO 8601
+// ---------------------------------------------------------------------------
+/** Unix 秒（数字）→ ISO 8601 北京时间 */
+function secondsToDateTime(seconds) {
+    return formatBeijingISO(new Date(seconds * 1000));
+}
+/** Unix 秒（字符串）→ ISO 8601 北京时间 */
+function secondsStringToDateTime(seconds) {
+    return secondsToDateTime(parseInt(seconds, 10));
+}
+// ---------------------------------------------------------------------------
+// Unix 毫秒 → ISO 8601
+// ---------------------------------------------------------------------------
+/** Unix 毫秒（数字）→ ISO 8601 北京时间 */
+function millisToDateTime(millis) {
+    return formatBeijingISO(new Date(millis));
+}
+/** Unix 毫秒（字符串）→ ISO 8601 北京时间 */
+function millisStringToDateTime(millis) {
+    return millisToDateTime(parseInt(millis, 10));
+}
+// ---------------------------------------------------------------------------
+// ISO 8601 → Unix
+// ---------------------------------------------------------------------------
+/** ISO 8601 → Unix 秒（数字） */
+function dateTimeToSeconds(datetime) {
+    const d = new Date(datetime);
+    if (isNaN(d.getTime())) {
+        throw new Error(`无法解析 ISO 8601 时间: "${datetime}"。格式示例: 2026-02-27T14:30:00+08:00`);
+    }
+    return Math.floor(d.getTime() / 1000);
+}
+/** ISO 8601 → Unix 秒（字符串） */
+function dateTimeToSecondsString(datetime) {
+    return dateTimeToSeconds(datetime).toString();
+}
+/** ISO 8601 → Unix 毫秒（数字） */
+function dateTimeToMillis(datetime) {
+    const d = new Date(datetime);
+    if (isNaN(d.getTime())) {
+        throw new Error(`无法解析 ISO 8601 时间: "${datetime}"。格式示例: 2026-02-27T14:30:00+08:00`);
+    }
+    return d.getTime();
+}
+/**
+ * 解析时间范围标识，返回 ISO 8601 字符串对。
+ *
+ * 支持的格式：
+ * - `today` / `yesterday` / `day_before_yesterday`
+ * - `this_week` / `last_week` / `this_month` / `last_month`
+ * - `last_{N}_{unit}` — unit: minutes / hours / days
+ *
+ * 所有计算基于北京时间 (UTC+8)。
+ */
+function parseTimeRange(input) {
+    const now = new Date();
+    const bjNow = toBeijingDate(now);
+    let start;
+    let end;
+    switch (input) {
+        case 'today':
+            start = beijingStartOfDay(bjNow);
+            end = now;
+            break;
+        case 'yesterday': {
+            const d = new Date(bjNow);
+            d.setUTCDate(d.getUTCDate() - 1);
+            start = beijingStartOfDay(d);
+            end = beijingEndOfDay(d);
+            break;
+        }
+        case 'day_before_yesterday': {
+            const d = new Date(bjNow);
+            d.setUTCDate(d.getUTCDate() - 2);
+            start = beijingStartOfDay(d);
+            end = beijingEndOfDay(d);
+            break;
+        }
+        case 'this_week': {
+            const day = bjNow.getUTCDay(); // 0=Sun .. 6=Sat
+            const diffToMon = day === 0 ? 6 : day - 1;
+            const monday = new Date(bjNow);
+            monday.setUTCDate(monday.getUTCDate() - diffToMon);
+            start = beijingStartOfDay(monday);
+            end = now;
+            break;
+        }
+        case 'last_week': {
+            const day = bjNow.getUTCDay();
+            const diffToMon = day === 0 ? 6 : day - 1;
+            const thisMonday = new Date(bjNow);
+            thisMonday.setUTCDate(thisMonday.getUTCDate() - diffToMon);
+            const lastMonday = new Date(thisMonday);
+            lastMonday.setUTCDate(lastMonday.getUTCDate() - 7);
+            const lastSunday = new Date(thisMonday);
+            lastSunday.setUTCDate(lastSunday.getUTCDate() - 1);
+            start = beijingStartOfDay(lastMonday);
+            end = beijingEndOfDay(lastSunday);
+            break;
+        }
+        case 'this_month': {
+            const firstDay = new Date(Date.UTC(bjNow.getUTCFullYear(), bjNow.getUTCMonth(), 1));
+            start = beijingStartOfDay(firstDay);
+            end = now;
+            break;
+        }
+        case 'last_month': {
+            const firstDayThisMonth = new Date(Date.UTC(bjNow.getUTCFullYear(), bjNow.getUTCMonth(), 1));
+            const lastDayPrevMonth = new Date(firstDayThisMonth);
+            lastDayPrevMonth.setUTCDate(lastDayPrevMonth.getUTCDate() - 1);
+            const firstDayPrevMonth = new Date(Date.UTC(lastDayPrevMonth.getUTCFullYear(), lastDayPrevMonth.getUTCMonth(), 1));
+            start = beijingStartOfDay(firstDayPrevMonth);
+            end = beijingEndOfDay(lastDayPrevMonth);
+            break;
+        }
+        default: {
+            // last_{N}_{unit} — 只支持 minutes / hours / days（对齐 Go）
+            const match = input.match(/^last_(\d+)_(minutes?|hours?|days?)$/);
+            if (!match) {
+                throw new Error(`不支持的 relative_time 格式: "${input}"。` +
+                    '支持: today, yesterday, day_before_yesterday, this_week, last_week, this_month, last_month, last_{N}_{unit}（unit: minutes/hours/days）');
+            }
+            const n = parseInt(match[1], 10);
+            const unit = match[2].replace(/s$/, ''); // normalize plural
+            start = subtractFromNow(now, n, unit);
+            end = now;
+            break;
+        }
+    }
+    return {
+        start: formatBeijingISO(start),
+        end: formatBeijingISO(end),
+    };
+}
+/**
+ * 解析时间范围标识，返回 Unix 秒字符串对（供 SDK 调用）。
+ */
+function parseTimeRangeToSeconds(input) {
+    const range = parseTimeRange(input);
+    return {
+        start: dateTimeToSecondsString(range.start),
+        end: dateTimeToSecondsString(range.end),
+    };
+}
+// ===========================================================================
+// Internal helpers
+// ===========================================================================
+/** 将 UTC Date 转为「北京时间各部分存在 UTC 字段上」的 Date */
+function toBeijingDate(d) {
+    return new Date(d.getTime() + BJ_OFFSET_MS);
+}
+/** 北京时间当天 00:00:00 对应的真实 UTC Date */
+function beijingStartOfDay(bjDate) {
+    return new Date(Date.UTC(bjDate.getUTCFullYear(), bjDate.getUTCMonth(), bjDate.getUTCDate()) - BJ_OFFSET_MS);
+}
+/** 北京时间当天 23:59:59 对应的真实 UTC Date */
+function beijingEndOfDay(bjDate) {
+    return new Date(Date.UTC(bjDate.getUTCFullYear(), bjDate.getUTCMonth(), bjDate.getUTCDate(), 23, 59, 59) - BJ_OFFSET_MS);
+}
+function subtractFromNow(now, n, unit) {
+    const d = new Date(now);
+    switch (unit) {
+        case 'minute':
+            d.setMinutes(d.getMinutes() - n);
+            break;
+        case 'hour':
+            d.setHours(d.getHours() - n);
+            break;
+        case 'day':
+            d.setDate(d.getDate() - n);
+            break;
+        default:
+            throw new Error(`不支持的时间单位: ${unit}`);
+    }
+    return d;
+}

package/src/tools/oapi/im/user-name-uat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * UAT 用户名解析模块
+ *
+ * 独立于 messaging/inbound 层的 TAT UserNameCache，
+ * 用于工具层以用户身份（UAT）批量解析用户显示名。
+ *
+ * 设计动机：TAT 调用 contact/v3/users/batch 缺少权限导致返回的用户
+ * 条目不含 name 字段，而工具层搜索消息等场景运行在 UAT 上下文中，
+ * 用户 token 可以读取其他用户的名称。
+ *
+ * 底层使用 contact/v3/users/basic_batch 接口（scope: contact:user.basic_profile:readonly），
+ * 每次最多查询 10 个用户。
+ */
+import type { ToolClient } from '../../../core/tool-client';
+/** 从 UAT 缓存中获取用户名 */
+export declare function getUATUserName(accountId: string, openId: string): string | undefined;
+/** 批量写入 UAT 缓存 */
+export declare function setUATUserNames(accountId: string, entries: Map<string, string>): void;
+export declare function batchResolveUserNamesAsUser(params: {
+    client: ToolClient;
+    openIds: string[];
+    log: (...args: unknown[]) => void;
+}): Promise<Map<string, string>>;