@larksuite/openclaw-lark 2026.3.9

package/src/tools/oapi/im/format-messages.js

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 消息格式化公共函数
+ *
+ * 将飞书 IM API 返回的原始消息对象转换为 AI 可读的 JSON 格式。
+ * 由 feishu_im_user_get_messages 和 feishu_im_user_get_thread_messages 共享。
+ *
+ * 所有 API 调用均通过 UAT（用户身份）进行。
+ */
+import { larkLogger } from '../../../core/lark-logger';
+import { convertMessageContent, buildConvertContextFromItem, extractMentionOpenId, } from '../../../messaging/converters/content-converter';
+import { getUATUserName, setUATUserNames, batchResolveUserNamesAsUser } from './user-name-uat';
+import { millisStringToDateTime } from './time-utils';
+const log = larkLogger('oapi/im/format-messages');
+// ---------------------------------------------------------------------------
+// UAT callbacks for merge_forward expansion
+// ---------------------------------------------------------------------------
+/** 通过 UAT 获取合并转发子消息 */
+function createUATFetchSubMessages(client) {
+    return async (messageId) => {
+        const res = await client.invokeByPath('feishu_im_user_get_messages.default', `/open-apis/im/v1/messages/${messageId}`, {
+            method: 'GET',
+            query: { user_id_type: 'open_id', card_msg_content_type: 'raw_card_content' },
+            as: 'user',
+        });
+        if (res.code !== 0) {
+            throw new Error(`API error: code=${res.code} msg=${res.msg}`);
+        }
+        return res.data?.items ?? [];
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 格式化单条消息对象。
+ *
+ * 使用 convertMessageContent 将 body.content 转为 AI 可读文本，
+ * 并过滤掉 AI 不需要的字段（upper_message_id、tenant_key 等）。
+ */
+export async function formatMessageItem(item, accountId, nameResolver, ctxOverrides) {
+    const messageId = item.message_id ?? '';
+    const msgType = item.msg_type ?? 'unknown';
+    // 使用 converter 处理消息内容
+    let content = '';
+    try {
+        const rawContent = item.body?.content ?? '';
+        if (rawContent) {
+            const ctx = {
+                ...buildConvertContextFromItem(item, messageId, accountId),
+                ...ctxOverrides,
+            };
+            const result = await convertMessageContent(rawContent, msgType, ctx);
+            content = result.content;
+        }
+    }
+    catch (err) {
+        log.warn('converter failed, falling back to raw content', {
+            messageId,
+            msgType,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        content = item.body?.content ?? '';
+    }
+    // 构建 sender（从 UAT 缓存中读取名字）
+    const senderId = item.sender?.id ?? '';
+    const senderType = item.sender?.sender_type ?? 'unknown';
+    let senderName;
+    if (senderId && senderType === 'user') {
+        senderName = nameResolver(senderId);
+    }
+    const sender = {
+        id: senderId,
+        sender_type: senderType,
+    };
+    if (senderName) {
+        sender.name = senderName;
+    }
+    // 构建 mentions（简化格式）
+    let mentions;
+    if (item.mentions && item.mentions.length > 0) {
+        mentions = item.mentions.map((m) => ({
+            key: m.key ?? '',
+            id: extractMentionOpenId(m.id),
+            name: m.name ?? '',
+        }));
+    }
+    // 转换 create_time（飞书 API 返回毫秒时间戳字符串 → ISO 8601 +08:00）
+    const createTime = item.create_time ? millisStringToDateTime(item.create_time) : '';
+    const formatted = {
+        message_id: messageId,
+        msg_type: msgType,
+        content,
+        sender,
+        create_time: createTime,
+        deleted: item.deleted ?? false,
+        updated: item.updated ?? false,
+    };
+    // 可选字段
+    // reply_to（parent_id）和 thread_id 的展示逻辑参考 Go MCP：
+    // - 有 thread_id 时只展示 thread_id，省略 reply_to（话题上下文可推断）
+    // - 无 thread_id 但有 parent_id 时，展示为 reply_to
+    if (item.thread_id) {
+        formatted.thread_id = item.thread_id;
+    }
+    else if (item.parent_id) {
+        formatted.reply_to = item.parent_id;
+    }
+    if (mentions) {
+        formatted.mentions = mentions;
+    }
+    return formatted;
+}
+/**
+ * 批量格式化消息列表（UAT 路径）。
+ *
+ * 先批量解析所有 sender 的名字（写入 UAT 缓存），再逐条格式化。
+ * 这样 formatMessageItem 中的 sender.name 和 converter 的
+ * resolveUserName 都能从 UAT 缓存中读到名字。
+ */
+export async function formatMessageList(items, account, log, client) {
+    const accountId = account.accountId;
+    const nameResolver = (openId) => getUATUserName(accountId, openId);
+    // 1. 把 mention 自带的名字写入 UAT 缓存（免费信息）
+    const mentionNames = new Map();
+    for (const item of items) {
+        for (const m of item.mentions ?? []) {
+            const openId = extractMentionOpenId(m.id);
+            if (openId && m.name) {
+                mentionNames.set(openId, m.name);
+            }
+        }
+    }
+    if (mentionNames.size > 0) {
+        setUATUserNames(accountId, mentionNames);
+    }
+    // 2. 收集所有 user 类型 sender 的 open_id
+    const senderIds = [
+        ...new Set(items
+            .map((item) => (item.sender?.sender_type === 'user' ? item.sender.id : undefined))
+            .filter((id) => !!id)),
+    ];
+    // 3. 批量解析 UAT 缓存中缺失的名字
+    if (senderIds.length > 0) {
+        const missing = senderIds.filter((id) => getUATUserName(accountId, id) === undefined);
+        if (missing.length > 0) {
+            await batchResolveUserNamesAsUser({ client, openIds: missing, log });
+        }
+    }
+    // 4. 构建 merge_forward 展开所需的回调
+    const uatBatchResolve = async (openIds) => {
+        await batchResolveUserNamesAsUser({ client, openIds, log });
+    };
+    const ctxOverrides = {
+        account,
+        accountId,
+        resolveUserName: nameResolver,
+        batchResolveNames: uatBatchResolve,
+        fetchSubMessages: createUATFetchSubMessages(client),
+    };
+    // 5. 逐条格式化
+    return Promise.all(items.map((item) => formatMessageItem(item, accountId, nameResolver, ctxOverrides)));
+}
+//# sourceMappingURL=format-messages.js.map

package/src/tools/oapi/im/format-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-messages.js","sourceRoot":"","sources":["../../../../../src/tools/oapi/im/format-messages.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM Tools Index
+ *
+ * 即时通讯相关工具
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuImTools(api: OpenClawPluginApi): void;
+//# sourceMappingURL=index.d.ts.map

package/src/tools/oapi/im/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/tools/oapi/im/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAK7D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,QAQ3D"}

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

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM Tools Index
+ *
+ * 即时通讯相关工具
+ */
+import { registerFeishuImUserMessageTool } from './message';
+import { registerFeishuImUserFetchResourceTool } from './resource';
+import { registerMessageReadTools } from './message-read';
+export function registerFeishuImTools(api) {
+    registerFeishuImUserMessageTool(api);
+    registerFeishuImUserFetchResourceTool(api);
+    registerMessageReadTools(api);
+    api.logger.info?.('feishu_im: Registered feishu_im_user_message, feishu_im_user_fetch_resource, feishu_im_user_get_messages, feishu_im_user_get_thread_messages, feishu_im_user_search_messages');
+}
+//# sourceMappingURL=index.js.map

package/src/tools/oapi/im/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/tools/oapi/im/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,MAAM,UAAU,qBAAqB,CAAC,GAAsB;IAC1D,+BAA+B,CAAC,GAAG,CAAC,CAAC;IACrC,qCAAqC,CAAC,GAAG,CAAC,CAAC;IAC3C,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAE9B,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CACf,8KAA8K,CAC/K,CAAC;AACJ,CAAC"}

package/src/tools/oapi/im/message-read.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 消息读取工具集 -- 以用户身份获取/搜索飞书消息
+ *
+ * 包含：
+ *   - feishu_im_user_get_messages       (chat_id / open_id → 会话消息)
+ *   - feishu_im_user_get_thread_messages (thread_id → 话题消息)
+ *   - feishu_im_user_search_messages     (跨会话关键词搜索)
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerMessageReadTools(api: OpenClawPluginApi): void;
+//# sourceMappingURL=message-read.d.ts.map

package/src/tools/oapi/im/message-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-read.d.ts","sourceRoot":"","sources":["../../../../../src/tools/oapi/im/message-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA4kB7D,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,QAI9D"}

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

@@ -0,0 +1,412 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 消息读取工具集 -- 以用户身份获取/搜索飞书消息
+ *
+ * 包含：
+ *   - feishu_im_user_get_messages       (chat_id / open_id → 会话消息)
+ *   - feishu_im_user_get_thread_messages (thread_id → 话题消息)
+ *   - feishu_im_user_search_messages     (跨会话关键词搜索)
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Type } from '@sinclair/typebox';
+import { assertLarkOk, createToolContext, getFirstAccount, handleInvokeErrorWithAutoAuth, json } from '../helpers';
+import { dateTimeToSecondsString, parseTimeRangeToSeconds } from './time-utils';
+import { formatMessageList } from './format-messages';
+import { getUATUserName, batchResolveUserNamesAsUser } from './user-name-uat';
+// ===========================================================================
+// Shared helpers
+// ===========================================================================
+function sortRuleToSortType(rule) {
+    return rule === 'create_time_asc' ? 'ByCreateTimeAsc' : 'ByCreateTimeDesc';
+}
+/** open_id → chat_id (P2P 单聊) */
+async function resolveP2PChatId(client, openId, log) {
+    const res = await client.invokeByPath('feishu_im_user_get_messages.default', '/open-apis/im/v1/chat_p2p/batch_query', {
+        method: 'POST',
+        body: { chatter_ids: [openId] },
+        query: { user_id_type: 'open_id' },
+        as: 'user',
+    });
+    const chats = res.data?.p2p_chats;
+    if (!chats?.length) {
+        log.info(`batch_query: no p2p chat found for open_id=${openId}`);
+        throw new Error(`no 1-on-1 chat found with open_id=${openId}. You may not have chat history with this user.`);
+    }
+    log.info(`batch_query: resolved chat_id=${chats[0].chat_id}`);
+    return chats[0].chat_id;
+}
+/** 解析时间参数，返回秒级时间戳字符串 */
+function resolveTimeRange(p, logInfo) {
+    if (p.relative_time) {
+        const range = parseTimeRangeToSeconds(p.relative_time);
+        logInfo(`relative_time="${p.relative_time}" → start=${range.start}, end=${range.end}`);
+        return range;
+    }
+    return {
+        start: p.start_time ? dateTimeToSecondsString(p.start_time) : undefined,
+        end: p.end_time ? dateTimeToSecondsString(p.end_time) : undefined,
+    };
+}
+/** 格式化 message.list 结果并返回 */
+async function formatAndReturn(res, config, log, client) {
+    const items = res.data?.items ?? [];
+    const account = getFirstAccount(config);
+    const messages = await formatMessageList(items, account, (...args) => log.info(args.map(String).join(' ')), client);
+    const hasMore = res.data?.has_more ?? false;
+    const pageToken = res.data?.page_token;
+    log.info(`list: returned ${messages.length} messages, has_more=${hasMore}`);
+    return json({ messages, has_more: hasMore, page_token: pageToken });
+}
+// ===========================================================================
+// feishu_im_user_get_messages
+// ===========================================================================
+const GetMessagesSchema = Type.Object({
+    open_id: Type.Optional(Type.String({
+        description: '用户 open_id（ou_xxx），获取与该用户的单聊消息。与 chat_id 互斥',
+    })),
+    chat_id: Type.Optional(Type.String({
+        description: '会话 ID（oc_xxx），支持单聊和群聊。与 open_id 互斥',
+    })),
+    sort_rule: Type.Optional(Type.Union([Type.Literal('create_time_asc'), Type.Literal('create_time_desc')], {
+        description: '排序方式，默认 create_time_desc（最新消息在前）',
+    })),
+    page_size: Type.Optional(Type.Number({ description: '每页消息数（1-50），默认 50', minimum: 1, maximum: 50 })),
+    page_token: Type.Optional(Type.String({ description: '分页标记，用于获取下一页' })),
+    relative_time: Type.Optional(Type.String({
+        description: '相对时间范围：today / yesterday / day_before_yesterday / this_week / last_week / this_month / last_month / last_{N}_{unit}（unit: minutes/hours/days）。与 start_time/end_time 互斥',
+    })),
+    start_time: Type.Optional(Type.String({
+        description: '起始时间（ISO 8601 格式，如 2026-02-27T00:00:00+08:00）。与 relative_time 互斥',
+    })),
+    end_time: Type.Optional(Type.String({
+        description: '结束时间（ISO 8601 格式，如 2026-02-27T23:59:59+08:00）。与 relative_time 互斥',
+    })),
+});
+function registerGetMessages(api) {
+    if (!api.config)
+        return;
+    const config = api.config;
+    const { toolClient, log } = createToolContext(api, 'feishu_im_user_get_messages');
+    api.registerTool({
+        name: 'feishu_im_user_get_messages',
+        label: 'Feishu: Get IM Messages',
+        description: '【以用户身份】获取群聊或单聊的历史消息。' +
+            '\n\n用法：' +
+            '\n- 通过 chat_id 获取群聊/单聊消息' +
+            '\n- 通过 open_id 获取与指定用户的单聊消息（自动解析 chat_id）' +
+            '\n- 支持时间范围过滤：relative_time（如 today、last_3_days）或 start_time/end_time（ISO 8601 格式）' +
+            '\n- 支持分页：page_size + page_token' +
+            '\n\n【参数约束】' +
+            '\n- open_id 和 chat_id 必须二选一，不能同时提供' +
+            '\n- relative_time 和 start_time/end_time 不能同时使用' +
+            '\n- page_size 范围 1-50，默认 50' +
+            '\n\n返回消息列表，每条消息包含 message_id、msg_type、content（AI 可读文本）、sender、create_time 等字段。',
+        parameters: GetMessagesSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                if (p.open_id && p.chat_id) {
+                    return json({ error: 'cannot provide both open_id and chat_id, please provide only one' });
+                }
+                if (!p.open_id && !p.chat_id) {
+                    return json({ error: 'either open_id or chat_id is required' });
+                }
+                if (p.relative_time && (p.start_time || p.end_time)) {
+                    return json({ error: 'cannot use both relative_time and start_time/end_time' });
+                }
+                const client = toolClient();
+                let chatId = p.chat_id ?? '';
+                if (p.open_id) {
+                    log.info(`resolving P2P chat for open_id=${p.open_id}`);
+                    chatId = await resolveP2PChatId(client, p.open_id, log);
+                }
+                const time = resolveTimeRange(p, log.info);
+                log.info(`list: chat_id=${chatId}, sort=${p.sort_rule ?? 'create_time_desc'}, page_size=${p.page_size ?? 50}`);
+                const res = await client.invoke('feishu_im_user_get_messages.default', (sdk, opts) => sdk.im.v1.message.list({
+                    params: {
+                        container_id_type: 'chat',
+                        container_id: chatId,
+                        start_time: time.start,
+                        end_time: time.end,
+                        sort_type: sortRuleToSortType(p.sort_rule),
+                        page_size: p.page_size ?? 50,
+                        page_token: p.page_token,
+                        card_msg_content_type: 'raw_card_content',
+                    },
+                }, opts), {
+                    as: 'user',
+                });
+                assertLarkOk(res);
+                return formatAndReturn(res, config, log, client);
+            }
+            catch (err) {
+                return await handleInvokeErrorWithAutoAuth(err, config);
+            }
+        },
+    }, { name: 'feishu_im_user_get_messages' });
+}
+// ===========================================================================
+// feishu_im_user_get_thread_messages
+// ===========================================================================
+const GetThreadMessagesSchema = Type.Object({
+    thread_id: Type.String({ description: '话题 ID（omt_xxx 格式）' }),
+    sort_rule: Type.Optional(Type.Union([Type.Literal('create_time_asc'), Type.Literal('create_time_desc')], {
+        description: '排序方式，默认 create_time_desc（最新消息在前）',
+    })),
+    page_size: Type.Optional(Type.Number({ description: '每页消息数（1-50），默认 50', minimum: 1, maximum: 50 })),
+    page_token: Type.Optional(Type.String({ description: '分页标记，用于获取下一页' })),
+});
+function registerGetThreadMessages(api) {
+    if (!api.config)
+        return;
+    const config = api.config;
+    const { toolClient, log } = createToolContext(api, 'feishu_im_user_get_thread_messages');
+    api.registerTool({
+        name: 'feishu_im_user_get_thread_messages',
+        label: 'Feishu: Get Thread Messages',
+        description: '【以用户身份】获取话题（thread）内的消息列表。' +
+            '\n\n用法：' +
+            '\n- 通过 thread_id（omt_xxx）获取话题内的所有消息' +
+            '\n- 支持分页：page_size + page_token' +
+            '\n\n【注意】话题消息不支持时间范围过滤（飞书 API 限制）' +
+            '\n\n返回消息列表，格式同 feishu_im_user_get_messages。',
+        parameters: GetThreadMessagesSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                log.info(`list: thread_id=${p.thread_id}, sort=${p.sort_rule ?? 'create_time_desc'}, page_size=${p.page_size ?? 50}`);
+                const res = await client.invoke('feishu_im_user_get_messages.default', (sdk, opts) => sdk.im.v1.message.list({
+                    params: {
+                        container_id_type: 'thread',
+                        container_id: p.thread_id,
+                        sort_type: sortRuleToSortType(p.sort_rule),
+                        page_size: p.page_size ?? 50,
+                        page_token: p.page_token,
+                        card_msg_content_type: 'raw_card_content',
+                    },
+                }, opts), {
+                    as: 'user',
+                });
+                assertLarkOk(res);
+                return formatAndReturn(res, config, log, client);
+            }
+            catch (err) {
+                return await handleInvokeErrorWithAutoAuth(err, config);
+            }
+        },
+    }, { name: 'feishu_im_user_get_thread_messages' });
+}
+// ===========================================================================
+// feishu_im_user_search_messages
+// ===========================================================================
+const SearchMessagesSchema = Type.Object({
+    query: Type.Optional(Type.String({ description: '搜索关键词，匹配消息内容。可为空字符串表示不按内容过滤' })),
+    sender_ids: Type.Optional(Type.Array(Type.String({ description: '发送者的 open_id（ou_xxx）' }), {
+        description: '发送者 open_id 列表。如需根据用户名查找 open_id，请先使用 search_user 工具',
+    })),
+    chat_id: Type.Optional(Type.String({ description: '限定搜索范围的会话 ID（oc_xxx）' })),
+    mention_ids: Type.Optional(Type.Array(Type.String({ description: '被@用户的 open_id（ou_xxx）' }), { description: '被@用户的 open_id 列表' })),
+    message_type: Type.Optional(Type.Union([Type.Literal('file'), Type.Literal('image'), Type.Literal('media')], {
+        description: '消息类型过滤：file / image / media。为空则搜索所有类型',
+    })),
+    sender_type: Type.Optional(Type.Union([Type.Literal('user'), Type.Literal('bot'), Type.Literal('all')], {
+        description: '发送者类型：user / bot / all。默认 user',
+    })),
+    chat_type: Type.Optional(Type.Union([Type.Literal('group'), Type.Literal('p2p')], {
+        description: '会话类型：group（群聊）/ p2p（单聊）',
+    })),
+    relative_time: Type.Optional(Type.String({
+        description: '相对时间范围：today / yesterday / day_before_yesterday / this_week / last_week / this_month / last_month / last_{N}_{unit}（unit: minutes/hours/days）。与 start_time/end_time 互斥',
+    })),
+    start_time: Type.Optional(Type.String({
+        description: '起始时间（ISO 8601 格式，如 2026-02-27T00:00:00+08:00）。与 relative_time 互斥',
+    })),
+    end_time: Type.Optional(Type.String({
+        description: '结束时间（ISO 8601 格式，如 2026-02-27T23:59:59+08:00）。与 relative_time 互斥',
+    })),
+    page_size: Type.Optional(Type.Number({ description: '每页消息数（1-50），默认 50', minimum: 1, maximum: 50 })),
+    page_token: Type.Optional(Type.String({ description: '分页标记，用于获取下一页' })),
+});
+function buildSearchData(p, time) {
+    const data = {
+        query: p.query ?? '',
+        start_time: time.start,
+        end_time: time.end,
+    };
+    if (p.sender_ids?.length)
+        data.from_ids = p.sender_ids;
+    if (p.chat_id)
+        data.chat_ids = [p.chat_id];
+    if (p.mention_ids?.length)
+        data.at_chatter_ids = p.mention_ids;
+    if (p.message_type)
+        data.message_type = p.message_type;
+    if (p.sender_type && p.sender_type !== 'all')
+        data.from_type = p.sender_type;
+    if (p.chat_type)
+        data.chat_type = p.chat_type === 'group' ? 'group_chat' : 'p2p_chat';
+    return data;
+}
+async function fetchChatContexts(client, chatIds, logInfo, logWarn) {
+    const map = new Map();
+    if (chatIds.length === 0)
+        return map;
+    try {
+        logInfo(`batch_query: requesting ${chatIds.length} chat_ids: ${chatIds.join(', ')}`);
+        const res = await client.invokeByPath('feishu_im_user_search_messages.default', '/open-apis/im/v1/chats/batch_query', {
+            method: 'POST',
+            body: { chat_ids: chatIds },
+            query: { user_id_type: 'open_id' },
+            as: 'user',
+        });
+        logInfo(`batch_query: response code=${res.code}, msg=${res.msg}, items=${res.data?.items?.length ?? 0}`);
+        if (res.code !== 0) {
+            logWarn(`batch_query: API returned error code=${res.code}, msg=${res.msg}`);
+        }
+        for (const c of res.data?.items ?? []) {
+            if (c.chat_id) {
+                map.set(c.chat_id, {
+                    name: c.name ?? '',
+                    chat_mode: c.chat_mode ?? '',
+                    p2p_target_id: c.p2p_target_id,
+                });
+            }
+        }
+    }
+    catch (err) {
+        logInfo(`batch_query chats failed, skipping: ${err}`);
+    }
+    return map;
+}
+async function resolveP2PTargetNames(chatMap, client, logFn) {
+    const ids = [...new Set([...chatMap.values()].map((c) => c.p2p_target_id).filter((id) => !!id))];
+    if (ids.length > 0) {
+        await batchResolveUserNamesAsUser({ client, openIds: ids, log: logFn });
+    }
+}
+function enrichMessages(messages, items, chatMap, nameResolver) {
+    return messages.map((msg, idx) => {
+        const chatId = items[idx]?.chat_id;
+        const ctx = chatId ? chatMap.get(chatId) : undefined;
+        if (!chatId || !ctx)
+            return { ...msg, chat_id: chatId };
+        if (ctx.chat_mode === 'p2p' && ctx.p2p_target_id) {
+            const name = nameResolver(ctx.p2p_target_id);
+            return {
+                ...msg,
+                chat_id: chatId,
+                chat_type: 'p2p',
+                chat_name: name || undefined,
+                chat_partner: { open_id: ctx.p2p_target_id, name: name || undefined },
+            };
+        }
+        return {
+            ...msg,
+            chat_id: chatId,
+            chat_type: ctx.chat_mode,
+            chat_name: ctx.name || undefined,
+        };
+    });
+}
+function registerSearchMessages(api) {
+    if (!api.config)
+        return;
+    const config = api.config;
+    const { toolClient, log } = createToolContext(api, 'feishu_im_user_search_messages');
+    api.registerTool({
+        name: 'feishu_im_user_search_messages',
+        label: 'Feishu: Search Messages',
+        description: '【以用户身份】跨会话搜索飞书消息。' +
+            '\n\n用法：' +
+            '\n- 按关键词搜索消息内容' +
+            '\n- 按发送者、被@用户、消息类型过滤' +
+            '\n- 按时间范围过滤：relative_time 或 start_time/end_time' +
+            '\n- 限定在某个会话内搜索（chat_id）' +
+            '\n- 支持分页：page_size + page_token' +
+            '\n\n【参数约束】' +
+            '\n- 所有参数均可选，但至少应提供一个过滤条件' +
+            '\n- relative_time 和 start_time/end_time 不能同时使用' +
+            '\n- page_size 范围 1-50，默认 50' +
+            '\n\n返回消息列表，每条消息包含 message_id、msg_type、content、sender、create_time 等字段。' +
+            '\n每条消息还包含 chat_id、chat_type（p2p/group）、chat_name（群名或单聊对方名字）。' +
+            '\n单聊消息额外包含 chat_partner（对方 open_id 和名字）。' +
+            '\n搜索结果中的 chat_id 和 thread_id 可配合 feishu_im_user_get_messages / feishu_im_user_get_thread_messages 查看上下文。',
+        parameters: SearchMessagesSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                if (p.relative_time && (p.start_time || p.end_time)) {
+                    return json({ error: 'cannot use both relative_time and start_time/end_time' });
+                }
+                const client = toolClient();
+                const account = getFirstAccount(config);
+                const logFn = (...args) => log.info(args.map(String).join(' '));
+                // 1. 搜索消息 ID
+                const time = resolveTimeRange(p, log.info);
+                const searchData = buildSearchData(p, {
+                    start: time.start ?? '978307200',
+                    end: time.end ?? Math.floor(Date.now() / 1000).toString(),
+                });
+                log.info(`search: query="${p.query ?? ''}", page_size=${p.page_size ?? 50}`);
+                const searchRes = await client.invoke('feishu_im_user_search_messages.default', (sdk, opts) => sdk.search.message.create({
+                    data: searchData,
+                    params: {
+                        user_id_type: 'open_id',
+                        page_size: p.page_size ?? 50,
+                        page_token: p.page_token,
+                    },
+                }, opts), {
+                    as: 'user',
+                });
+                assertLarkOk(searchRes);
+                const messageIds = searchRes.data?.items ?? [];
+                const hasMore = searchRes.data?.has_more ?? false;
+                const pageToken = searchRes.data?.page_token;
+                log.info(`search: found ${messageIds.length} IDs, has_more=${hasMore}`);
+                if (messageIds.length === 0) {
+                    return json({ messages: [], has_more: hasMore, page_token: pageToken });
+                }
+                // 2. 批量获取消息详情
+                const queryStr = messageIds.map((id) => `message_ids=${encodeURIComponent(id)}`).join('&');
+                const mgetRes = await client.invokeByPath('feishu_im_user_search_messages.default', `/open-apis/im/v1/messages/mget?${queryStr}`, {
+                    method: 'GET',
+                    query: { user_id_type: 'open_id', card_msg_content_type: 'raw_card_content' },
+                    as: 'user',
+                });
+                const items = mgetRes.data?.items ?? [];
+                log.info(`mget: ${items.length} details`);
+                // 3. 批量获取会话信息
+                const chatIds = [
+                    ...new Set(items.map((i) => i.chat_id).filter(Boolean)),
+                ];
+                const chatMap = await fetchChatContexts(client, chatIds, log.info, log.warn);
+                const p2pChats = [...chatMap.entries()].filter(([, v]) => v.chat_mode === 'p2p');
+                log.info(`chats: ${chatMap.size}/${chatIds.length} resolved, p2p=${p2pChats.length}`);
+                // 4. 格式化消息（填充 sender 名字缓存，使用 UAT）
+                const messages = await formatMessageList(items, account, logFn, client);
+                // 5. 解析 p2p 对方用户名（使用 UAT）
+                await resolveP2PTargetNames(chatMap, client, logFn);
+                // 6. 拼装返回
+                const uatNameResolver = (id) => getUATUserName(account.accountId, id);
+                const result = enrichMessages(messages, items, chatMap, uatNameResolver);
+                log.info(`result: ${result.length} messages, has_more=${hasMore}`);
+                return json({ messages: result, has_more: hasMore, page_token: pageToken });
+            }
+            catch (err) {
+                return await handleInvokeErrorWithAutoAuth(err, config);
+            }
+        },
+    }, { name: 'feishu_im_user_search_messages' });
+}
+// ===========================================================================
+// Unified registration
+// ===========================================================================
+export function registerMessageReadTools(api) {
+    registerGetMessages(api);
+    registerGetThreadMessages(api);
+    registerSearchMessages(api);
+}
+//# sourceMappingURL=message-read.js.map