@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/tools/oapi/im/user-name-uat.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * 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 个用户。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUATUserName = getUATUserName;
+exports.setUATUserNames = setUATUserNames;
+exports.batchResolveUserNamesAsUser = batchResolveUserNamesAsUser;
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// 独立缓存：accountId → Map<openId, { name, expireAt }>
+// ---------------------------------------------------------------------------
+const UAT_MAX_SIZE = 500;
+const UAT_TTL_MS = 30 * 60 * 1000; // 30 分钟
+const uatRegistry = new Map();
+function getOrCreateCache(accountId) {
+    let cache = uatRegistry.get(accountId);
+    if (!cache) {
+        cache = new Map();
+        uatRegistry.set(accountId, cache);
+    }
+    return cache;
+}
+function evict(cache) {
+    while (cache.size > UAT_MAX_SIZE) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+}
+/** 从 UAT 缓存中获取用户名 */
+function getUATUserName(accountId, openId) {
+    const cache = uatRegistry.get(accountId);
+    if (!cache)
+        return undefined;
+    const entry = cache.get(openId);
+    if (!entry)
+        return undefined;
+    if (entry.expireAt <= Date.now()) {
+        cache.delete(openId);
+        return undefined;
+    }
+    // LRU refresh
+    cache.delete(openId);
+    cache.set(openId, entry);
+    return entry.name;
+}
+/** 批量写入 UAT 缓存 */
+function setUATUserNames(accountId, entries) {
+    const cache = getOrCreateCache(accountId);
+    const now = Date.now();
+    for (const [openId, name] of entries) {
+        cache.delete(openId);
+        cache.set(openId, { name, expireAt: now + UAT_TTL_MS });
+    }
+    evict(cache);
+}
+// ---------------------------------------------------------------------------
+// 以 UAT 身份批量解析用户名
+// ---------------------------------------------------------------------------
+const BATCH_SIZE = 10; // basic_batch API 限制每次最多 10 个
+async function batchResolveUserNamesAsUser(params) {
+    const { client, openIds, log } = params;
+    if (openIds.length === 0)
+        return new Map();
+    const accountId = client.account.accountId;
+    const cache = getOrCreateCache(accountId);
+    const result = new Map();
+    const now = Date.now();
+    // 1. 从缓存读取已有的
+    const missing = [];
+    for (const id of openIds) {
+        const entry = cache.get(id);
+        if (entry && entry.expireAt > now) {
+            result.set(id, entry.name);
+        }
+        else {
+            if (entry)
+                cache.delete(id);
+            missing.push(id);
+        }
+    }
+    // 去重
+    const uniqueMissing = [...new Set(missing)];
+    if (uniqueMissing.length === 0)
+        return result;
+    // 2. 分批通过 SDK 调用 contact/v3/users/basic_batch（UAT）
+    const totalBatches = Math.ceil(uniqueMissing.length / BATCH_SIZE);
+    log(`batchResolveUserNamesAsUser: resolving ${uniqueMissing.length} user(s) in ${totalBatches} batch(es), ${result.size} cache hit(s)`);
+    for (let i = 0; i < uniqueMissing.length; i += BATCH_SIZE) {
+        const chunk = uniqueMissing.slice(i, i + BATCH_SIZE);
+        const batchIndex = Math.floor(i / BATCH_SIZE) + 1;
+        try {
+            const res = await client.invoke('feishu_get_user.basic_batch', (sdk, opts) => sdk.request({
+                method: 'POST',
+                url: '/open-apis/contact/v3/users/basic_batch',
+                data: { user_ids: chunk },
+                params: { user_id_type: 'open_id' },
+            }, opts), {
+                as: 'user',
+            });
+            const users = res?.data?.users ?? [];
+            let resolved = 0;
+            for (const user of users) {
+                const openId = user.user_id;
+                // 实际返回 name 为字符串，兼容文档中 name.value 的对象结构
+                const rawName = user.name;
+                const name = typeof rawName === 'string' ? rawName : rawName?.value;
+                if (openId && name) {
+                    cache.delete(openId);
+                    cache.set(openId, { name, expireAt: Date.now() + UAT_TTL_MS });
+                    result.set(openId, name);
+                    resolved++;
+                }
+            }
+            const unresolvedCount = chunk.length - resolved;
+            if (unresolvedCount > 0) {
+                log(`batchResolveUserNamesAsUser: batch ${batchIndex}/${totalBatches}: ${resolved} resolved, ${unresolvedCount} missing name`);
+            }
+        }
+        catch (err) {
+            // 授权/权限错误向上冒泡，由上层 handleInvokeErrorWithAutoAuth 处理自动授权
+            if ((0, helpers_1.isInvokeError)(err))
+                throw err;
+            log(`batchResolveUserNamesAsUser: failed: ${String(err)}`);
+        }
+    }
+    evict(cache);
+    return result;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAPI Tools Index
+ *
+ * This module registers all tools that directly use Feishu Open API (OAPI).
+ * These tools are placed here to distinguish them from MCP-based tools.
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerOapiTools(api: OpenClawPluginApi): void;

package/src/tools/oapi/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAPI Tools Index
+ *
+ * This module registers all tools that directly use Feishu Open API (OAPI).
+ * These tools are placed here to distinguish them from MCP-based tools.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOapiTools = registerOapiTools;
+const index_1 = require("../tat/im/index.js");
+const index_2 = require("./calendar/index.js");
+const index_3 = require("./task/index.js");
+const index_4 = require("./bitable/index.js");
+const index_5 = require("./common/index.js");
+// import { registerFeishuMailTools } from "./mail/index";
+const index_6 = require("./search/index.js");
+const index_7 = require("./drive/index.js");
+const index_8 = require("./wiki/index.js");
+const index_9 = require("./sheets/index.js");
+// import { registerFeishuOkrTools } from "./okr/index";
+const index_10 = require("./chat/index.js");
+const index_11 = require("./im/index.js");
+function registerOapiTools(api) {
+    // Common tools
+    (0, index_5.registerGetUserTool)(api);
+    (0, index_5.registerSearchUserTool)(api);
+    // Chat tools
+    (0, index_10.registerFeishuChatTools)(api);
+    // IM tools (user identity)
+    (0, index_11.registerFeishuImTools)(api);
+    // Calendar tools
+    (0, index_2.registerFeishuCalendarCalendarTool)(api);
+    (0, index_2.registerFeishuCalendarEventTool)(api);
+    (0, index_2.registerFeishuCalendarEventAttendeeTool)(api);
+    (0, index_2.registerFeishuCalendarFreebusyTool)(api);
+    // Task tools
+    (0, index_3.registerFeishuTaskTaskTool)(api);
+    (0, index_3.registerFeishuTaskTasklistTool)(api);
+    (0, index_3.registerFeishuTaskAttachmentTool)(api);
+    (0, index_3.registerFeishuTaskSectionTool)(api);
+    (0, index_3.registerFeishuTaskCommentTool)(api);
+    (0, index_3.registerFeishuTaskSubtaskTool)(api);
+    (0, index_3.registerFeishuTaskAgentTool)(api);
+    // Bitable tools
+    (0, index_4.registerFeishuBitableAppTool)(api);
+    (0, index_4.registerFeishuBitableAppTableTool)(api);
+    (0, index_4.registerFeishuBitableAppTableRecordTool)(api);
+    (0, index_4.registerFeishuBitableAppTableFieldTool)(api);
+    (0, index_4.registerFeishuBitableAppTableViewTool)(api);
+    // Search tools
+    (0, index_6.registerFeishuSearchTools)(api);
+    // Drive tools
+    (0, index_7.registerFeishuDriveTools)(api);
+    // Wiki tools
+    (0, index_8.registerFeishuWikiTools)(api);
+    // Sheets tools
+    (0, index_9.registerFeishuSheetsTools)(api);
+    // IM tools (bot identity)
+    (0, index_1.registerFeishuImTools)(api);
+    api.logger.debug?.('Registered all OAPI tools (calendar, task, bitable, search, drive, wiki, sheets, im)');
+}

package/src/tools/oapi/sdk-types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Common response type helpers for Lark SDK.
+ *
+ * The Lark Node SDK's generic response types often lack specific field
+ * definitions for `data`, requiring `as any` casts.  These lightweight
+ * interfaces let us replace `(res.data as any)?.items` with a single typed
+ * assertion at the top of each block.
+ */
+/** Standard paginated list response (items / has_more / page_token). */
+export interface PaginatedData<T = unknown> {
+    items?: T[];
+    has_more?: boolean;
+    page_token?: string;
+    total?: number;
+}
+/** Calendar-specific list response that uses `calendar_list` key. */
+export interface CalendarListData {
+    calendar_list?: unknown[];
+    has_more?: boolean;
+    page_token?: string;
+}
+/** Calendar primary response. */
+export interface CalendarPrimaryData {
+    calendars?: Array<{
+        calendar?: {
+            calendar_id?: string;
+        };
+    }>;
+}
+/** Freebusy response. */
+export interface FreebusyData {
+    freebusy_lists?: unknown[];
+}
+/** Drive file list response (uses `files` key). */
+export interface DriveFileListData {
+    files?: unknown[];
+    has_more?: boolean;
+    next_page_token?: string;
+}
+/** Drive file copy / create response. */
+export interface DriveFileData {
+    file?: {
+        token?: string;
+        [key: string]: unknown;
+    };
+}
+/** Drive async task response (move / delete). */
+export interface DriveTaskData {
+    task_id?: string;
+}
+/** Bitable app list response (uses `files` key from drive search). */
+export interface BitableAppListData {
+    files?: unknown[];
+    has_more?: boolean;
+    page_token?: string;
+}
+/** Field create / update response. */
+export interface FieldData {
+    field?: {
+        field_id?: string;
+        [key: string]: unknown;
+    };
+}
+/** Chat member list response. */
+export interface ChatMemberListData {
+    items?: unknown[];
+    member_total?: number;
+    has_more?: boolean;
+    page_token?: string;
+}
+/** Search user response. */
+export interface SearchUserData {
+    users?: unknown[];
+    has_more?: boolean;
+    page_token?: string;
+}
+/** Task create response. */
+export interface TaskCreateData {
+    task?: {
+        guid?: string;
+        [key: string]: unknown;
+    };
+}
+/** Calendar get response. */
+export interface CalendarGetData {
+    calendar?: unknown;
+}
+/** Comment list reply response. */
+export interface CommentReplyListData {
+    items?: unknown[];
+    has_more?: boolean;
+    page_token?: string;
+}

package/src/tools/oapi/sdk-types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Common response type helpers for Lark SDK.
+ *
+ * The Lark Node SDK's generic response types often lack specific field
+ * definitions for `data`, requiring `as any` casts.  These lightweight
+ * interfaces let us replace `(res.data as any)?.items` with a single typed
+ * assertion at the top of each block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/tools/oapi/search/doc-search.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_search_doc_wiki tool -- Search Feishu documents and wikis.
+ *
+ * Actions: search
+ *
+ * Uses the Feishu Search API:
+ *   - search: POST /open-apis/search/v2/doc_wiki/search
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuSearchDocWikiTool(api: OpenClawPluginApi): boolean;

package/src/tools/oapi/search/doc-search.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_search_doc_wiki tool -- Search Feishu documents and wikis.
+ *
+ * Actions: search
+ *
+ * Uses the Feishu Search API:
+ *   - search: POST /open-apis/search/v2/doc_wiki/search
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuSearchDocWikiTool = registerFeishuSearchDocWikiTool;
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../helpers.js");
+// ---------------------------------------------------------------------------
+// Schema - Helper types
+// ---------------------------------------------------------------------------
+const TimeRangeSchema = typebox_1.Type.Object({
+    start: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: "时间范围的起始时间，ISO 8601 / RFC 3339 格式（包含时区），例如 '2024-01-01T00:00:00+08:00'",
+    })),
+    end: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: "时间范围的截止时间，ISO 8601 / RFC 3339 格式（包含时区），例如 '2024-01-01T00:00:00+08:00'",
+    })),
+});
+const DocTypeEnum = (0, helpers_1.StringEnum)([
+    'DOC',
+    'SHEET',
+    'BITABLE',
+    'MINDNOTE',
+    'FILE',
+    'WIKI',
+    'DOCX',
+    'FOLDER',
+    'CATALOG',
+    'SLIDES',
+    'SHORTCUT',
+]);
+const SortTypeEnum = (0, helpers_1.StringEnum)(['DEFAULT_TYPE', 'OPEN_TIME', 'EDIT_TIME', 'EDIT_TIME_ASC', 'CREATE_TIME'], {
+    description: '排序方式。EDIT_TIME=编辑时间降序（最新文档在前，推荐），EDIT_TIME_ASC=编辑时间升序，CREATE_TIME=按文档创建时间排序，OPEN_TIME=打开时间，DEFAULT_TYPE=默认排序',
+});
+// ---------------------------------------------------------------------------
+// Schema - Main
+// ---------------------------------------------------------------------------
+const FeishuSearchDocWikiSchema = typebox_1.Type.Object({
+    action: typebox_1.Type.Literal('search'),
+    query: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: '搜索关键词（可选）。不传或传空字符串表示空搜，也可以支持排序规则与筛选，默认根据最近浏览时间返回结果',
+        maxLength: 50,
+    })),
+    filter: typebox_1.Type.Optional(typebox_1.Type.Object({
+        creator_ids: typebox_1.Type.Optional(typebox_1.Type.Array(typebox_1.Type.String(), {
+            description: '创建者 OpenID 列表（最多 20 个）',
+            maxItems: 20,
+        })),
+        doc_types: typebox_1.Type.Optional(typebox_1.Type.Array(DocTypeEnum, {
+            description: '文档类型列表：DOC（文档）、SHEET（表格）、BITABLE（多维表格）、MINDNOTE（思维导图）、FILE（文件）、WIKI（维基）、DOCX（新版文档）、FOLDER（space文件夹）、CATALOG（wiki2.0文件夹）、SLIDES（新版幻灯片）、SHORTCUT（快捷方式）',
+            maxItems: 10,
+        })),
+        only_title: typebox_1.Type.Optional(typebox_1.Type.Boolean({
+            description: '仅搜索标题（默认 false，搜索标题和正文）',
+        })),
+        open_time: typebox_1.Type.Optional(TimeRangeSchema),
+        sort_type: typebox_1.Type.Optional(SortTypeEnum),
+        create_time: typebox_1.Type.Optional(TimeRangeSchema),
+    }, {
+        description: '搜索过滤条件（可选）。不传则搜索所有文档和 Wiki；传了则同时对文档和 Wiki 应用相同的过滤条件。',
+    })),
+    page_token: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: '分页标记。首次请求不填；当返回结果中 has_more 为 true 时，可传入返回的 page_token 继续请求下一页',
+    })),
+    page_size: typebox_1.Type.Optional(typebox_1.Type.Integer({
+        description: '分页大小（默认 15，最大 20）',
+        minimum: 0,
+        maximum: 20,
+    })),
+});
+function normalizeSearchResultTimeFields(value, converted) {
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeSearchResultTimeFields(item, converted));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const source = value;
+    const normalized = {};
+    for (const [key, item] of Object.entries(source)) {
+        if (key.endsWith('_time')) {
+            const iso = (0, helpers_1.unixTimestampToISO8601)(item);
+            if (iso) {
+                normalized[key] = iso;
+                converted.count += 1;
+                continue;
+            }
+        }
+        normalized[key] = normalizeSearchResultTimeFields(item, converted);
+    }
+    return normalized;
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+function registerFeishuSearchDocWikiTool(api) {
+    if (!api.config)
+        return false;
+    const cfg = api.config;
+    const { toolClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_search_doc_wiki');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_search_doc_wiki',
+        label: 'Feishu Document & Wiki Search',
+        description: '【以用户身份】飞书文档与 Wiki 统一搜索工具。同时搜索云空间文档和知识库 Wiki。Actions: search。' +
+            '【重要】query 参数是搜索关键词（必填），filter 参数可选。' +
+            '【重要】filter 不传时，搜索所有文档和 Wiki；传了则同时对文档和 Wiki 应用相同的过滤条件。' +
+            '【重要】支持按文档类型、创建者、创建时间、打开时间等多维度筛选。' +
+            '【重要】返回结果包含标题和摘要高亮（<h>标签包裹匹配关键词）。',
+        parameters: FeishuSearchDocWikiSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = toolClient();
+                switch (p.action) {
+                    // -----------------------------------------------------------------
+                    // SEARCH DOCUMENTS AND WIKIS
+                    // -----------------------------------------------------------------
+                    case 'search': {
+                        // query 为可选参数，默认使用空字符串（表示空搜）
+                        const query = p.query ?? '';
+                        log.info(`search: query="${query}", has_filter=${!!p.filter}, page_size=${p.page_size ?? 15}`);
+                        // 构建请求体
+                        const requestData = {
+                            query: query,
+                            page_size: p.page_size,
+                            page_token: p.page_token,
+                        };
+                        // 必须传递 doc_filter 和 wiki_filter，即使为空对象（API 要求）
+                        if (p.filter) {
+                            const filter = { ...p.filter };
+                            // 处理时间字段转换
+                            if (filter.open_time) {
+                                filter.open_time = (0, helpers_1.convertTimeRange)(filter.open_time);
+                            }
+                            if (filter.create_time) {
+                                filter.create_time = (0, helpers_1.convertTimeRange)(filter.create_time);
+                            }
+                            // 同时设置 doc_filter 和 wiki_filter（内容相同）
+                            requestData.doc_filter = { ...filter };
+                            requestData.wiki_filter = { ...filter };
+                            log.info(`search: applying filter to both doc and wiki: doc_types=${filter.doc_types?.join(',') || 'all'}, only_title=${filter.only_title ?? false}`);
+                        }
+                        else {
+                            // 即使没有筛选条件，也必须传空对象（否则 API 不返回内容）
+                            requestData.doc_filter = {};
+                            requestData.wiki_filter = {};
+                            log.info(`search: no filter provided, using empty filters (required by API)`);
+                        }
+                        // 使用 client.invoke 统一封装底层 request 调用
+                        const res = await client.invoke('feishu_search_doc_wiki.search', async (sdk, _opts, uat) => {
+                            return sdk.request({
+                                method: 'POST',
+                                url: '/open-apis/search/v2/doc_wiki/search',
+                                data: requestData,
+                                headers: {
+                                    Authorization: `Bearer ${uat}`,
+                                    'Content-Type': 'application/json; charset=utf-8',
+                                },
+                            }, _opts);
+                        }, { as: 'user' });
+                        // 检查响应
+                        if (res.code !== 0) {
+                            throw new Error(`API Error: code=${res.code}, msg=${res.msg}`);
+                        }
+                        const data = res.data || {};
+                        log.info(`search: found ${data.res_units?.length ?? 0} results, total=${data.total ?? 0}, has_more=${data.has_more ?? false}`);
+                        const converted = { count: 0 };
+                        const normalizedResults = normalizeSearchResultTimeFields(data.res_units, converted);
+                        log.info(`search: normalized ${converted.count} timestamp fields to ISO8601`);
+                        return (0, helpers_1.json)({
+                            total: data.total,
+                            has_more: data.has_more,
+                            results: normalizedResults,
+                            page_token: data.page_token,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                return await (0, helpers_1.handleInvokeErrorWithAutoAuth)(err, cfg);
+            }
+        },
+    }, { name: 'feishu_search_doc_wiki' });
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Search 工具集
+ * 统一导出所有搜索相关工具的注册函数
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+/**
+ * 注册所有 Search 工具
+ */
+export declare function registerFeishuSearchTools(api: OpenClawPluginApi): void;

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

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Search 工具集
+ * 统一导出所有搜索相关工具的注册函数
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuSearchTools = registerFeishuSearchTools;
+const accounts_1 = require("../../../core/accounts.js");
+const tools_config_1 = require("../../../core/tools-config.js");
+const doc_search_1 = require("./doc-search.js");
+/**
+ * 注册所有 Search 工具
+ */
+function registerFeishuSearchTools(api) {
+    if (!api.config) {
+        api.logger.debug?.('feishu_search: No config available, skipping');
+        return;
+    }
+    const accounts = (0, accounts_1.getEnabledLarkAccounts)(api.config);
+    if (accounts.length === 0) {
+        api.logger.debug?.('feishu_search: No Feishu accounts configured, skipping');
+        return;
+    }
+    // search 工具使用 doc 配置项控制，因为搜索是文档相关功能
+    const toolsCfg = (0, tools_config_1.resolveAnyEnabledToolsConfig)(accounts);
+    if (!toolsCfg.doc) {
+        api.logger.debug?.('feishu_search: search tool disabled in all accounts (controlled by doc config)');
+        return;
+    }
+    // 注册所有工具
+    if ((0, doc_search_1.registerFeishuSearchDocWikiTool)(api)) {
+        api.logger.debug?.('feishu_search: Registered feishu_search_doc_wiki');
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Sheets 工具集
+ * 注册飞书电子表格工具
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+/**
+ * 注册 Sheets 工具
+ */
+export declare function registerFeishuSheetsTools(api: OpenClawPluginApi): void;

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

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Sheets 工具集
+ * 注册飞书电子表格工具
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuSheetsTools = registerFeishuSheetsTools;
+const accounts_1 = require("../../../core/accounts.js");
+const tools_config_1 = require("../../../core/tools-config.js");
+const sheet_1 = require("./sheet.js");
+/**
+ * 注册 Sheets 工具
+ */
+function registerFeishuSheetsTools(api) {
+    if (!api.config) {
+        api.logger.debug?.('feishu_sheets: No config available, skipping');
+        return;
+    }
+    const accounts = (0, accounts_1.getEnabledLarkAccounts)(api.config);
+    if (accounts.length === 0) {
+        api.logger.debug?.('feishu_sheets: No Feishu accounts configured, skipping');
+        return;
+    }
+    const toolsCfg = (0, tools_config_1.resolveAnyEnabledToolsConfig)(accounts);
+    if (!toolsCfg.sheets) {
+        api.logger.debug?.('feishu_sheets: sheets tool disabled in all accounts');
+        return;
+    }
+    if ((0, sheet_1.registerFeishuSheetTool)(api)) {
+        api.logger.debug?.('feishu_sheets: Registered feishu_sheet');
+    }
+}

package/src/tools/oapi/sheets/sheet.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_sheet — 飞书电子表格统一工具。
+ *
+ * Actions: info, read, write, append, find, create, export
+ *
+ * 设计原则：
+ *   - 接受 URL 或 spreadsheet_token（工具层自动解析）
+ *   - read 不指定 range 时自动读取第一个工作表全部数据
+ *   - create 支持带表头和初始数据一步创建
+ *   - info 一次返回表格信息 + 全部工作表列表
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuSheetTool(api: OpenClawPluginApi): boolean;