@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/tools/oapi/calendar/freebusy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_calendar_freebusy tool -- Query user/room calendar free/busy status.
+ *
+ * P0 Actions: list
+ *
+ * Uses the Feishu Calendar API:
+ *   - list: POST /open-apis/calendar/v4/freebusy/batch (批量查询接口)
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuCalendarFreebusyTool(api: OpenClawPluginApi): void;

package/src/tools/oapi/calendar/freebusy.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_calendar_freebusy tool -- Query user/room calendar free/busy status.
+ *
+ * P0 Actions: list
+ *
+ * Uses the Feishu Calendar API:
+ *   - list: POST /open-apis/calendar/v4/freebusy/batch (批量查询接口)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuCalendarFreebusyTool = registerFeishuCalendarFreebusyTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const FeishuCalendarFreebusySchema = typebox_1.Type.Object({
+    action: typebox_1.Type.Literal('list'),
+    time_min: typebox_1.Type.String({
+        description: "查询起始时间（ISO 8601 / RFC 3339 格式（包含时区），例如 '2024-01-01T00:00:00+08:00'）",
+    }),
+    time_max: typebox_1.Type.String({
+        description: "查询结束时间（ISO 8601 / RFC 3339 格式（包含时区），例如 '2024-01-01T00:00:00+08:00'）",
+    }),
+    user_ids: typebox_1.Type.Array(typebox_1.Type.String({
+        description: '用户 open_id',
+    }), {
+        description: '要查询忙闲的用户 ID 列表（1-10 个用户）',
+        minItems: 1,
+        maxItems: 10,
+    }),
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerFeishuCalendarFreebusyTool(api) {
+    if (!api.config)
+        return;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_calendar_freebusy');
+    (0, helpers_1.registerTool)(api, {
+        name: 'feishu_calendar_freebusy',
+        label: 'Feishu Calendar Free/Busy Status',
+        description: '【以用户身份】飞书日历忙闲查询工具。当用户要求查询某时间段内某人是否空闲、查看忙闲状态时使用。支持批量查询 1-10 个用户的主日历忙闲信息，用于安排会议时间。',
+        parameters: FeishuCalendarFreebusySchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            log.info(`[FREEBUSY] Execute called with params: ${JSON.stringify(p)}`);
+            try {
+                const client = toolClient();
+                if (p.action !== 'list') {
+                    log.warn(`[FREEBUSY] Unknown action: ${p.action}`);
+                    return (0, helpers_1.json)({ error: `Unknown action: ${p.action}` });
+                }
+                // Validate user_ids (batch API requires 1-10 users)
+                if (!p.user_ids || p.user_ids.length === 0) {
+                    log.warn(`[FREEBUSY] user_ids is empty`);
+                    return (0, helpers_1.json)({
+                        error: 'user_ids is required (1-10 user IDs)',
+                    });
+                }
+                if (p.user_ids.length > 10) {
+                    log.warn(`[FREEBUSY] user_ids exceeds limit: ${p.user_ids.length}`);
+                    return (0, helpers_1.json)({
+                        error: `user_ids count exceeds limit, maximum 10 users (current: ${p.user_ids.length})`,
+                    });
+                }
+                log.info(`[FREEBUSY] Validation passed, user_ids count: ${p.user_ids.length}`);
+                // Convert time strings to RFC 3339 format (required by freebusy API)
+                const timeMin = (0, helpers_1.parseTimeToRFC3339)(p.time_min);
+                const timeMax = (0, helpers_1.parseTimeToRFC3339)(p.time_max);
+                if (!timeMin || !timeMax) {
+                    log.warn(`[FREEBUSY] Time format error: time_min=${p.time_min}, time_max=${p.time_max}`);
+                    return (0, helpers_1.json)({
+                        error: "Invalid time format. Must use ISO 8601 / RFC 3339 with timezone, e.g. '2024-01-01T00:00:00+08:00' or '2026-02-25 14:00:00'.",
+                        received_time_min: p.time_min,
+                        received_time_max: p.time_max,
+                    });
+                }
+                log.info(`[FREEBUSY] Calling batch API: time_min=${p.time_min} -> ${timeMin}, time_max=${p.time_max} -> ${timeMax}, user_ids=${p.user_ids.length}`);
+                const res = await client.invoke('feishu_calendar_freebusy.list', (sdk, opts) => sdk.calendar.freebusy.batch({
+                    data: {
+                        time_min: timeMin,
+                        time_max: timeMax,
+                        user_ids: p.user_ids,
+                        include_external_calendar: true,
+                        only_busy: true,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    }, // SDK 类型定义可能未包含所有字段
+                }, opts), { as: 'user' });
+                (0, helpers_1.assertLarkOk)(res);
+                const data = res.data;
+                const freebusyLists = data?.freebusy_lists ?? [];
+                log.info(`[FREEBUSY] Success: returned ${freebusyLists.length} user(s) freebusy data`);
+                return (0, helpers_1.json)({
+                    freebusy_lists: freebusyLists,
+                    _debug: {
+                        time_min_input: p.time_min,
+                        time_min_rfc3339: timeMin,
+                        time_max_input: p.time_max,
+                        time_max_rfc3339: timeMax,
+                        user_count: p.user_ids.length,
+                    },
+                });
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_calendar_freebusy' });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+export { registerFeishuCalendarCalendarTool } from './calendar';
+export { registerFeishuCalendarEventTool } from './event';
+export { registerFeishuCalendarEventAttendeeTool } from './event-attendee';
+export { registerFeishuCalendarFreebusyTool } from './freebusy';

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

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuCalendarFreebusyTool = exports.registerFeishuCalendarEventAttendeeTool = exports.registerFeishuCalendarEventTool = exports.registerFeishuCalendarCalendarTool = void 0;
+var calendar_1 = require("./calendar.js");
+Object.defineProperty(exports, "registerFeishuCalendarCalendarTool", { enumerable: true, get: function () { return calendar_1.registerFeishuCalendarCalendarTool; } });
+var event_1 = require("./event.js");
+Object.defineProperty(exports, "registerFeishuCalendarEventTool", { enumerable: true, get: function () { return event_1.registerFeishuCalendarEventTool; } });
+var event_attendee_1 = require("./event-attendee.js");
+Object.defineProperty(exports, "registerFeishuCalendarEventAttendeeTool", { enumerable: true, get: function () { return event_attendee_1.registerFeishuCalendarEventAttendeeTool; } });
+var freebusy_1 = require("./freebusy.js");
+Object.defineProperty(exports, "registerFeishuCalendarFreebusyTool", { enumerable: true, get: function () { return freebusy_1.registerFeishuCalendarFreebusyTool; } });

package/src/tools/oapi/chat/chat.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_chat tool -- 管理飞书群聊
+ *
+ * Actions:
+ *   - search: 搜索对用户或机器人可见的群列表
+ *   - get:    获取指定群的详细信息
+ *
+ * Uses the Feishu IM v1 API:
+ *   - search: GET /open-apis/im/v1/chats/search
+ *   - get:    GET /open-apis/im/v1/chats/:chat_id
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerChatSearchTool(api: OpenClawPluginApi): boolean;

package/src/tools/oapi/chat/chat.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_chat tool -- 管理飞书群聊
+ *
+ * Actions:
+ *   - search: 搜索对用户或机器人可见的群列表
+ *   - get:    获取指定群的详细信息
+ *
+ * Uses the Feishu IM v1 API:
+ *   - search: GET /open-apis/im/v1/chats/search
+ *   - get:    GET /open-apis/im/v1/chats/:chat_id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerChatSearchTool = registerChatSearchTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const FeishuChatSchema = typebox_1.Type.Union([
+    // SEARCH
+    typebox_1.Type.Object({
+        action: typebox_1.Type.Literal('search'),
+        query: typebox_1.Type.String({
+            description: '搜索关键词（必填）。支持匹配群名称、群成员名称。' + '支持多语种、拼音、前缀等模糊搜索。',
+        }),
+        page_size: typebox_1.Type.Optional(typebox_1.Type.Integer({
+            description: '分页大小（默认20）',
+            minimum: 1,
+        })),
+        page_token: typebox_1.Type.Optional(typebox_1.Type.String({
+            description: '分页标记。首次请求无需填写',
+        })),
+        user_id_type: typebox_1.Type.Optional((0, helpers_1.StringEnum)(['open_id', 'union_id', 'user_id'], {
+            description: '用户 ID 类型（默认 open_id）',
+        })),
+    }),
+    // GET
+    typebox_1.Type.Object({
+        action: typebox_1.Type.Literal('get'),
+        chat_id: typebox_1.Type.String({
+            description: '群 ID（格式如 oc_xxx）',
+        }),
+        user_id_type: typebox_1.Type.Optional((0, helpers_1.StringEnum)(['open_id', 'union_id', 'user_id'], {
+            description: '用户 ID 类型（默认 open_id）',
+        })),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerChatSearchTool(api) {
+    if (!api.config)
+        return false;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_chat');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_chat',
+        label: 'Feishu: Chat Management',
+        description: '以用户身份调用飞书群聊管理工具。Actions: search（搜索群列表，支持关键词匹配群名称、群成员）, get（获取指定群的详细信息，包括群名称、描述、头像、群主、权限配置等）。',
+        parameters: FeishuChatSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                switch (p.action) {
+                    // -----------------------------------------------------------------
+                    // SEARCH
+                    // -----------------------------------------------------------------
+                    case 'search': {
+                        log.info(`search: query="${p.query}", page_size=${p.page_size ?? 20}`);
+                        const res = await client.invoke('feishu_chat.search', (sdk, opts) => sdk.im.v1.chat.search({
+                            params: {
+                                user_id_type: p.user_id_type || 'open_id',
+                                query: p.query,
+                                page_size: p.page_size,
+                                page_token: p.page_token,
+                            },
+                        }, opts), { as: 'user' });
+                        (0, helpers_1.assertLarkOk)(res);
+                        const data = res.data;
+                        const chatCount = data?.items?.length ?? 0;
+                        log.info(`search: found ${chatCount} chats`);
+                        return (0, helpers_1.json)({
+                            items: data?.items,
+                            has_more: data?.has_more ?? false,
+                            page_token: data?.page_token,
+                        });
+                    }
+                    // -----------------------------------------------------------------
+                    // GET
+                    // -----------------------------------------------------------------
+                    case 'get': {
+                        log.info(`get: chat_id=${p.chat_id}, user_id_type=${p.user_id_type ?? 'open_id'}`);
+                        const res = await client.invoke('feishu_chat.get', (sdk, opts) => sdk.im.v1.chat.get({
+                            path: {
+                                chat_id: p.chat_id,
+                            },
+                            params: {
+                                user_id_type: p.user_id_type || 'open_id',
+                            },
+                        }, {
+                            ...(opts ?? {}),
+                            headers: {
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                ...(opts?.headers ?? {}),
+                                'X-Chat-Custom-Header': 'enable_chat_list_security_check',
+                            },
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        }), { as: 'user' });
+                        (0, helpers_1.assertLarkOk)(res);
+                        log.info(`get: retrieved chat info for ${p.chat_id}`);
+                        return (0, helpers_1.json)({
+                            chat: res.data,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_chat' });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Chat Tools Index
+ *
+ * 群组相关工具
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuChatTools(api: OpenClawPluginApi): void;

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

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Chat Tools Index
+ *
+ * 群组相关工具
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuChatTools = registerFeishuChatTools;
+const chat_1 = require("./chat.js");
+const members_1 = require("./members.js");
+function registerFeishuChatTools(api) {
+    const registered = [];
+    if ((0, chat_1.registerChatSearchTool)(api))
+        registered.push('feishu_chat');
+    if ((0, members_1.registerChatMembersTool)(api))
+        registered.push('feishu_chat_members');
+    if (registered.length > 0) {
+        api.logger.debug?.(`feishu_chat: Registered ${registered.join(', ')}`);
+    }
+}

package/src/tools/oapi/chat/members.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_chat_members tool -- 获取群成员列表
+ *
+ * 获取指定群组的成员信息，包括成员名字与 ID
+ * 使用 sdk.im.v1.chatMembers.get 接口
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerChatMembersTool(api: OpenClawPluginApi): boolean;

package/src/tools/oapi/chat/members.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_chat_members tool -- 获取群成员列表
+ *
+ * 获取指定群组的成员信息，包括成员名字与 ID
+ * 使用 sdk.im.v1.chatMembers.get 接口
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerChatMembersTool = registerChatMembersTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const ChatMembersSchema = typebox_1.Type.Object({
+    chat_id: typebox_1.Type.String({
+        description: '群 ID（格式如 oc_xxx）。' + '可以通过 feishu_chat_search 工具搜索获取',
+    }),
+    member_id_type: typebox_1.Type.Optional((0, helpers_1.StringEnum)(['open_id', 'union_id', 'user_id'])),
+    page_size: typebox_1.Type.Optional(typebox_1.Type.Integer({
+        description: '分页大小（默认20）',
+        minimum: 1,
+    })),
+    page_token: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: '分页标记。首次请求无需填写',
+    })),
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerChatMembersTool(api) {
+    if (!api.config)
+        return false;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_chat_members');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_chat_members',
+        label: 'Feishu: Get Chat Members',
+        description: '以用户的身份获取指定群组的成员列表。' +
+            '返回成员信息，包含成员 ID、姓名等。' +
+            '注意：不会返回群组内的机器人成员。',
+        parameters: ChatMembersSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                log.info(`chat_members: chat_id="${p.chat_id}", page_size=${p.page_size ?? 20}`);
+                const res = await client.invoke('feishu_chat_members.default', (sdk, opts) => sdk.im.v1.chatMembers.get({
+                    path: { chat_id: p.chat_id },
+                    params: {
+                        member_id_type: p.member_id_type || 'open_id',
+                        page_size: p.page_size,
+                        page_token: p.page_token,
+                    },
+                }, {
+                    ...(opts ?? {}),
+                    headers: {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        ...(opts?.headers ?? {}),
+                        'X-Chat-Custom-Header': 'enable_chat_list_security_check',
+                    },
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                }), { as: 'user' });
+                (0, helpers_1.assertLarkOk)(res);
+                const data = res.data;
+                const memberCount = data?.items?.length ?? 0;
+                const memberTotal = data?.member_total ?? 0;
+                log.info(`chat_members: found ${memberCount} members (total: ${memberTotal})`);
+                return (0, helpers_1.json)({
+                    items: data?.items,
+                    has_more: data?.has_more ?? false,
+                    page_token: data?.page_token,
+                    member_total: memberTotal,
+                });
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_chat_members' });
+}

package/src/tools/oapi/common/get-user.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_get_user tool -- 获取用户信息
+ *
+ * 支持两种模式:
+ * 1. 不传 user_id: 获取当前用户自己的信息 (sdk.authen.userInfo.get)
+ * 2. 传 user_id: 获取指定用户的信息 (sdk.contact.v3.user.get)
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerGetUserTool(api: OpenClawPluginApi): void;

package/src/tools/oapi/common/get-user.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_get_user tool -- 获取用户信息
+ *
+ * 支持两种模式:
+ * 1. 不传 user_id: 获取当前用户自己的信息 (sdk.authen.userInfo.get)
+ * 2. 传 user_id: 获取指定用户的信息 (sdk.contact.v3.user.get)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGetUserTool = registerGetUserTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const GetUserSchema = typebox_1.Type.Object({
+    user_id: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: '用户 ID（格式如 ou_xxx）。若不传入，则获取当前用户自己的信息',
+    })),
+    user_id_type: typebox_1.Type.Optional((0, helpers_1.StringEnum)(['open_id', 'union_id', 'user_id'])),
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerGetUserTool(api) {
+    if (!api.config)
+        return;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_get_user');
+    (0, helpers_1.registerTool)(api, {
+        name: 'feishu_get_user',
+        label: 'Feishu: Get User Info',
+        description: '获取用户信息。不传 user_id 时获取当前用户自己的信息；传 user_id 时获取指定用户的信息。' +
+            '返回用户姓名、头像、邮箱、手机号、部门等信息。',
+        parameters: GetUserSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                // 模式 1: 获取当前用户自己的信息
+                if (!p.user_id) {
+                    log.info('get_user: fetching current user info');
+                    try {
+                        const res = await client.invoke('feishu_get_user.default', (sdk, opts) => sdk.authen.userInfo.get({}, opts), { as: 'user' });
+                        (0, helpers_1.assertLarkOk)(res);
+                        log.info('get_user: current user fetched successfully');
+                        return (0, helpers_1.json)({
+                            user: res.data,
+                        });
+                    }
+                    catch (invokeErr) {
+                        // 特殊处理错误码 41050：用户组织架构可见范围限制
+                        if (invokeErr && typeof invokeErr === 'object') {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            const e = invokeErr;
+                            if (e.response?.data?.code === 41050) {
+                                return (0, helpers_1.json)({
+                                    error: '无权限查询该用户信息。\n\n' +
+                                        '说明：使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，' +
+                                        '而是受当前用户的组织架构可见范围影响。该范围限制了用户在企业内可见的组织架构数据范围。',
+                                });
+                            }
+                        }
+                        throw invokeErr;
+                    }
+                }
+                // 模式 2: 获取指定用户的信息
+                log.info(`get_user: fetching user ${p.user_id}`);
+                const userIdType = p.user_id_type || 'open_id';
+                try {
+                    const res = await client.invoke('feishu_get_user.default', (sdk, opts) => sdk.contact.v3.user.get({
+                        path: { user_id: p.user_id },
+                        params: {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            user_id_type: userIdType,
+                        },
+                    }, opts), { as: 'user' });
+                    (0, helpers_1.assertLarkOk)(res);
+                    log.info(`get_user: user ${p.user_id} fetched successfully`);
+                    return (0, helpers_1.json)({
+                        user: res.data?.user,
+                    });
+                }
+                catch (invokeErr) {
+                    // 特殊处理错误码 41050：用户组织架构可见范围限制
+                    if (invokeErr && typeof invokeErr === 'object') {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const e = invokeErr;
+                        if (e.response?.data?.code === 41050) {
+                            return (0, helpers_1.json)({
+                                error: '无权限查询该用户信息。\n\n' +
+                                    '说明：使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，' +
+                                    '而是受当前用户的组织架构可见范围影响。该范围限制了用户在企业内可见的组织架构数据范围。\n\n' +
+                                    '建议：请联系管理员调整当前用户的组织架构可见范围，或使用应用身份（tenant_access_token）调用 API。',
+                            });
+                        }
+                    }
+                    throw invokeErr;
+                }
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_get_user' });
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+export { registerGetUserTool } from './get-user';
+export { registerSearchUserTool } from './search-user';

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

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSearchUserTool = exports.registerGetUserTool = void 0;
+var get_user_1 = require("./get-user.js");
+Object.defineProperty(exports, "registerGetUserTool", { enumerable: true, get: function () { return get_user_1.registerGetUserTool; } });
+var search_user_1 = require("./search-user.js");
+Object.defineProperty(exports, "registerSearchUserTool", { enumerable: true, get: function () { return search_user_1.registerSearchUserTool; } });

package/src/tools/oapi/common/search-user.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_search_user tool -- 搜索员工
+ *
+ * 通过关键词搜索员工，结果按亲密度排序
+ * 使用搜索接口（/open-apis/search/v1/user）
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerSearchUserTool(api: OpenClawPluginApi): void;