feishu-mcp 0.1.6 → 0.1.8

package/dist/services/feishuApiService.js

@@ -1,11 +1,11 @@
 import { BaseApiService } from './baseService.js';
 import { Logger } from '../utils/logger.js';
 import { Config } from '../utils/config.js';
-import { CacheManager } from '../utils/cache.js';
 import { ParamUtils } from '../utils/paramUtils.js';
 import { BlockFactory, BlockType } from './blockFactory.js';
 import { AuthUtils, TokenCacheManager } from '../utils/auth/index.js';
 import { AuthService } from './feishuAuthService.js';
+import { ScopeInsufficientError } from '../utils/error.js';
 import axios from 'axios';
 import FormData from 'form-data';
 import fs from 'fs';
@@ -20,12 +20,6 @@ export class FeishuApiService extends BaseApiService {
      */
     constructor() {
         super();
-        Object.defineProperty(this, "cacheManager", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         Object.defineProperty(this, "blockFactory", {
             enumerable: true,
             configurable: true,
@@ -44,7 +38,6 @@ export class FeishuApiService extends BaseApiService {
             writable: true,
             value: void 0
         });
-        this.cacheManager = CacheManager.getInstance();
         this.blockFactory = BlockFactory.getInstance();
         this.config = Config.getInstance();
         this.authService = new AuthService();
@@ -84,13 +77,231 @@ export class FeishuApiService extends BaseApiService {
         // 生成客户端缓存键
         const clientKey = AuthUtils.generateClientKey(userKey);
         Logger.debug(`[FeishuApiService] 获取访问令牌，userKey: ${userKey}, clientKey: ${clientKey}, authType: ${authType}`);
+        // 在使用token之前先校验scope（使用appId+appSecret获取临时tenant token来调用scope接口）
+        await this.validateScopeWithVersion(appId, appSecret, authType);
+        // 校验通过后，获取实际的token
         if (authType === 'tenant') {
             // 租户模式：获取租户访问令牌
-            return this.getTenantAccessToken(appId, appSecret, clientKey);
+            return await this.getTenantAccessToken(appId, appSecret, clientKey);
         }
         else {
             // 用户模式：获取用户访问令牌
-            return this.authService.getUserAccessToken(clientKey, appId, appSecret);
+            return await this.authService.getUserAccessToken(clientKey, appId, appSecret);
+        }
+    }
+    /**
+     * 获取应用权限范围
+     * @param accessToken 访问令牌
+     * @param authType 认证类型（tenant或user）
+     * @returns 应用权限范围列表
+     */
+    async getApplicationScopes(accessToken, authType) {
+        try {
+            const endpoint = '/application/v6/scopes';
+            const headers = {
+                'Authorization': `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            };
+            Logger.debug('请求应用权限范围:', endpoint);
+            const response = await axios.get(`${this.getBaseUrl()}${endpoint}`, { headers });
+            const data = response.data;
+            if (data.code !== 0) {
+                throw new Error(`获取应用权限范围失败：${data.msg || '未知错误'} (错误码: ${data.code})`);
+            }
+            // 提取权限列表
+            // API返回格式: { "data": { "scopes": [{ "grant_status": 1, "scope_name": "...", "scope_type": "tenant"|"user" }] } }
+            const scopes = [];
+            if (data.data && Array.isArray(data.data.scopes)) {
+                // 根据authType过滤，只取已授权的scope（grant_status === 1）
+                for (const scopeItem of data.data.scopes) {
+                    if (scopeItem.grant_status === 1 && scopeItem.scope_type === authType && scopeItem.scope_name) {
+                        scopes.push(scopeItem.scope_name);
+                    }
+                }
+            }
+            Logger.debug(`获取应用权限范围成功，共 ${scopes.length} 个${authType}权限`);
+            return scopes;
+        }
+        catch (error) {
+            Logger.error('获取应用权限范围失败:', error);
+            throw new Error('获取应用权限范围失败: ' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    /**
+     * 校验scope权限是否充足
+     * @param requiredScopes 所需的权限列表
+     * @param actualScopes 实际的权限列表
+     * @returns 是否权限充足，以及缺失的权限列表
+     */
+    validateScopes(requiredScopes, actualScopes) {
+        const actualScopesSet = new Set(actualScopes);
+        const missingScopes = [];
+        for (const requiredScope of requiredScopes) {
+            if (!actualScopesSet.has(requiredScope)) {
+                missingScopes.push(requiredScope);
+            }
+        }
+        return {
+            isValid: missingScopes.length === 0,
+            missingScopes
+        };
+    }
+    /**
+     * 获取所需的scope列表（根据认证类型）
+     * @param authType 认证类型
+     * @returns 所需的scope列表
+     */
+    getRequiredScopes(authType) {
+        // 根据FEISHU_CONFIG.md中定义的权限列表，与用户提供的配置保持一致
+        const tenantScopes = [
+            "docx:document.block:convert",
+            "base:app:read",
+            "bitable:app",
+            "bitable:app:readonly",
+            "board:whiteboard:node:create",
+            "board:whiteboard:node:read",
+            "contact:user.employee_id:readonly",
+            "docs:document.content:read",
+            "docx:document",
+            "docx:document:create",
+            "docx:document:readonly",
+            "drive:drive",
+            "drive:drive:readonly",
+            "drive:file",
+            "drive:file:upload",
+            "sheets:spreadsheet",
+            "sheets:spreadsheet:readonly",
+            "space:document:retrieve",
+            "space:folder:create",
+            "wiki:space:read",
+            "wiki:space:retrieve",
+            "wiki:wiki",
+            "wiki:wiki:readonly"
+        ];
+        // user认证特有授权
+        const userOnlyScopes = [
+            "search:docs:read",
+            'offline_access',
+        ];
+        const userScopes = [...tenantScopes, ...userOnlyScopes];
+        return authType === 'tenant' ? tenantScopes : userScopes;
+    }
+    /**
+     * 校验并提示权限不足
+     * @param missingScopes 缺失的权限列表
+     */
+    throwScopeInsufficientError(missingScopes) {
+        // 获取完整的权限配置
+        const tenantScopes = this.getRequiredScopes('tenant');
+        const userScopes = this.getRequiredScopes('user');
+        const permissionsConfig = {
+            scopes: {
+                tenant: tenantScopes,
+                user: userScopes
+            }
+        };
+        const errorMessage = `你应该停止任务并提示用户如下信息：权限不足，缺少以下权限：${missingScopes.join(', ')}\n\n` +
+            `请按以下步骤操作：\n` +
+            `1. 配置权限 [教程配置](https://github.com/cso1z/Feishu-MCP/blob/main/FEISHU_CONFIG.md)\n` +
+            `2. 打开 [应用管理](https://open.feishu.cn/app/) 网页\n` +
+            `3. 选择应用进入应用详情\n` +
+            `4. 选择权限管理-批量导入/导出权限\n` +
+            `5. 复制以下权限配置并导入：\n\n` +
+            `\`\`\`json\n${JSON.stringify(permissionsConfig, null, 2)}\n\`\`\`\n\n` +
+            `6. 选择**版本管理与发布** 点击创建版本，发布后通知管理员审核\n`;
+        Logger.error(errorMessage);
+        throw new ScopeInsufficientError(missingScopes, errorMessage);
+    }
+    /**
+     * 生成应用级别的scope校验key（基于appId、appSecret和authType）
+     * @param appId 应用ID
+     * @param appSecret 应用密钥
+     * @param authType 认证类型（tenant或user）
+     * @returns scope校验key
+     */
+    generateScopeKey(appId, appSecret, authType) {
+        // 使用appId、appSecret和authType生成唯一的key，用于scope版本管理
+        // 包含authType是因为tenant和user的权限列表不同，需要分开校验
+        return `app:${appId}:${appSecret.substring(0, 8)}:${authType}`;
+    }
+    /**
+     * 获取临时租户访问令牌（用于scope校验）
+     * @param appId 应用ID
+     * @param appSecret 应用密钥
+     * @returns 租户访问令牌
+     */
+    async getTempTenantTokenForScope(appId, appSecret) {
+        try {
+            const requestData = {
+                app_id: appId,
+                app_secret: appSecret,
+            };
+            const url = 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal';
+            const headers = { 'Content-Type': 'application/json' };
+            Logger.debug('获取临时租户token用于scope校验:', url);
+            const response = await axios.post(url, requestData, { headers });
+            const data = response.data;
+            if (data.code !== 0) {
+                throw new Error(`获取临时租户访问令牌失败：${data.msg || '未知错误'} (错误码: ${data.code})`);
+            }
+            if (!data.tenant_access_token) {
+                throw new Error('获取临时租户访问令牌失败：响应中没有token');
+            }
+            Logger.debug('临时租户token获取成功，用于scope校验');
+            return data.tenant_access_token;
+        }
+        catch (error) {
+            Logger.error('获取临时租户访问令牌失败:', error);
+            throw new Error('获取临时租户访问令牌失败: ' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    /**
+     * 校验scope权限（带版本管理）
+     * @param appId 应用ID
+     * @param appSecret 应用密钥
+     * @param authType 认证类型
+     */
+    async validateScopeWithVersion(appId, appSecret, authType) {
+        const tokenCacheManager = TokenCacheManager.getInstance();
+        // 生成应用级别的scope校验key（包含authType，因为tenant和user权限不同）
+        const scopeKey = this.generateScopeKey(appId, appSecret, authType);
+        const scopeVersion = '2.0.0'; // 当前scope版本号，可以根据需要更新
+        // 检查是否需要校验
+        if (!tokenCacheManager.shouldValidateScope(scopeKey, scopeVersion)) {
+            Logger.debug(`Scope版本已校验过，跳过校验: ${scopeKey}`);
+            return;
+        }
+        Logger.info(`开始校验scope权限，版本: ${scopeVersion}, scopeKey: ${scopeKey}`);
+        try {
+            // 使用appId和appSecret获取临时tenant token来调用scope接口
+            const tempTenantToken = await this.getTempTenantTokenForScope(appId, appSecret);
+            // 获取实际权限范围（使用tenant token，但根据authType过滤scope_type）
+            const actualScopes = await this.getApplicationScopes(tempTenantToken, authType);
+            // 获取当前版本所需的scope列表
+            const requiredScopes = this.getRequiredScopes(authType);
+            // 校验权限
+            const validationResult = this.validateScopes(requiredScopes, actualScopes);
+            if (!validationResult.isValid) {
+                // 权限不足，抛出错误
+                this.throwScopeInsufficientError(validationResult.missingScopes);
+            }
+            // 权限充足，保存版本信息
+            const scopeVersionInfo = {
+                scopeVersion,
+                scopeList: requiredScopes,
+                validatedAt: Math.floor(Date.now() / 1000),
+                validatedVersion: scopeVersion
+            };
+            tokenCacheManager.saveScopeVersionInfo(scopeKey, scopeVersionInfo);
+            Logger.info(`Scope权限校验成功，版本: ${scopeVersion}`);
+        }
+        catch (error) {
+            // 如果是权限不足错误，需要重新抛出，中断流程
+            if (error instanceof ScopeInsufficientError) {
+                throw error;
+            }
+            // 如果获取权限范围失败（网络错误、API调用失败等），记录警告但不阻止token使用
+            Logger.warn(`Scope权限校验失败，但继续使用token: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     /**
@@ -163,16 +374,57 @@ export class FeishuApiService extends BaseApiService {
         }
     }
     /**
-     * 获取文档信息
-     * @param documentId 文档ID或URL
-     * @returns 文档信息
+     * 获取文档信息（支持普通文档和Wiki文档）
+     * @param documentId 文档ID或URL（支持Wiki链接）
+     * @param documentType 文档类型（可选），'document' 或 'wiki'，如果不指定则自动检测
+     * @returns 文档信息或Wiki节点信息
      */
-    async getDocumentInfo(documentId) {
+    async getDocumentInfo(documentId, documentType) {
         try {
-            const normalizedDocId = ParamUtils.processDocumentId(documentId);
-            const endpoint = `/docx/v1/documents/${normalizedDocId}`;
-            const response = await this.get(endpoint);
-            return response;
+            let isWikiLink;
+            // 如果明确指定了类型，使用指定的类型
+            if (documentType === 'wiki') {
+                isWikiLink = true;
+            }
+            else if (documentType === 'document') {
+                isWikiLink = false;
+            }
+            else {
+                // 自动检测：检查是否是Wiki链接（包含 /wiki/ 路径）
+                isWikiLink = documentId.includes('/wiki/');
+            }
+            if (isWikiLink) {
+                // 处理Wiki文档
+                const wikiToken = ParamUtils.processWikiToken(documentId);
+                const endpoint = `/wiki/v2/spaces/get_node`;
+                const params = { token: wikiToken, obj_type: 'wiki' };
+                const response = await this.get(endpoint, params);
+                if (!response.node || !response.node.obj_token) {
+                    throw new Error(`无法从Wiki节点获取文档ID: ${wikiToken}`);
+                }
+                const node = response.node;
+                const docId = node.obj_token;
+                // 构建返回对象，包含完整节点信息和 documentId 字段
+                const result = {
+                    ...node,
+                    documentId: docId, // 添加 documentId 字段作为 obj_token 的别名
+                    _type: 'wiki', // 标识这是Wiki文档
+                };
+                Logger.debug(`获取Wiki文档信息: ${wikiToken} -> documentId: ${docId}, space_id: ${node.space_id}, node_token: ${node.node_token}`);
+                return result;
+            }
+            else {
+                // 处理普通文档
+                const normalizedDocId = ParamUtils.processDocumentId(documentId);
+                const endpoint = `/docx/v1/documents/${normalizedDocId}`;
+                const response = await this.get(endpoint);
+                const result = {
+                    ...response,
+                    _type: 'document', // 标识这是普通文档
+                };
+                Logger.debug(`获取普通文档信息: ${normalizedDocId}`);
+                return result;
+            }
         }
         catch (error) {
             this.handleApiError(error, '获取文档信息失败');
@@ -586,33 +838,28 @@ export class FeishuApiService extends BaseApiService {
      * @param wikiUrl Wiki链接或Token
      * @returns 文档ID
      */
-    async convertWikiToDocumentId(wikiUrl) {
-        try {
-            const wikiToken = ParamUtils.processWikiToken(wikiUrl);
-            // 尝试从缓存获取
-            const cachedDocId = this.cacheManager.getWikiToDocId(wikiToken);
-            if (cachedDocId) {
-                Logger.debug(`使用缓存的Wiki转换结果: ${wikiToken} -> ${cachedDocId}`);
-                return cachedDocId;
-            }
-            // 获取Wiki节点信息
-            const endpoint = `/wiki/v2/spaces/get_node`;
-            const params = { token: wikiToken, obj_type: 'wiki' };
-            const response = await this.get(endpoint, params);
-            if (!response.node || !response.node.obj_token) {
-                throw new Error(`无法从Wiki节点获取文档ID: ${wikiToken}`);
-            }
-            const documentId = response.node.obj_token;
-            // 缓存结果
-            this.cacheManager.cacheWikiToDocId(wikiToken, documentId);
-            Logger.debug(`Wiki转换为文档ID: ${wikiToken} -> ${documentId}`);
-            return documentId;
-        }
-        catch (error) {
-            this.handleApiError(error, 'Wiki转换为文档ID失败');
-            return ''; // 永远不会执行到这里
-        }
-    }
+    // public async convertWikiToDocumentId(wikiUrl: string): Promise<string> {
+    //   try {
+    //     const wikiToken = ParamUtils.processWikiToken(wikiUrl);
+    //
+    //     // 获取Wiki节点信息
+    //     const endpoint = `/wiki/v2/spaces/get_node`;
+    //     const params = { token: wikiToken, obj_type: 'wiki' };
+    //     const response = await this.get(endpoint, params);
+    //
+    //     if (!response.node || !response.node.obj_token) {
+    //       throw new Error(`无法从Wiki节点获取文档ID: ${wikiToken}`);
+    //     }
+    //
+    //     const documentId = response.node.obj_token;
+    //
+    //     Logger.debug(`Wiki转换为文档ID: ${wikiToken} -> ${documentId}`);
+    //     return documentId;
+    //   } catch (error) {
+    //     this.handleApiError(error, 'Wiki转换为文档ID失败');
+    //     return ''; // 永远不会执行到这里
+    //   }
+    // }
     /**
      * 获取BlockFactory实例
      * @returns BlockFactory实例
@@ -745,6 +992,21 @@ export class FeishuApiService extends BaseApiService {
                         };
                     }
                     break;
+                case BlockType.WHITEBOARD:
+                    if ('whiteboard' in options && options.whiteboard) {
+                        const whiteboardOptions = options.whiteboard;
+                        blockConfig.options = {
+                            align: (whiteboardOptions.align === 1 || whiteboardOptions.align === 2 || whiteboardOptions.align === 3)
+                                ? whiteboardOptions.align : 1
+                        };
+                    }
+                    else {
+                        // 默认画板块选项
+                        blockConfig.options = {
+                            align: 1
+                        };
+                    }
+                    break;
                 default:
                     Logger.warn(`未知的块类型: ${blockType}，尝试作为标准类型处理`);
                     if ('text' in options) {
@@ -815,6 +1077,14 @@ export class FeishuApiService extends BaseApiService {
                             code: mermaidConfig.code,
                         };
                     }
+                    else if ("whiteboard" in options) {
+                        blockConfig.type = BlockType.WHITEBOARD;
+                        const whiteboardConfig = options.whiteboard;
+                        blockConfig.options = {
+                            align: (whiteboardConfig.align === 1 || whiteboardConfig.align === 2 || whiteboardConfig.align === 3)
+                                ? whiteboardConfig.align : 1
+                        };
+                    }
                     break;
             }
             // 记录调试信息
@@ -871,6 +1141,148 @@ export class FeishuApiService extends BaseApiService {
             this.handleApiError(error, '获取飞书根文件夹信息失败');
         }
     }
+    /**
+     * 获取所有知识空间列表（遍历所有分页）
+     * @param pageSize 每页数量，默认20
+     * @returns 所有知识空间列表（仅包含 items 数组，不包含 has_more 和 page_token）
+     */
+    async getAllWikiSpacesList(pageSize = 20) {
+        try {
+            Logger.info(`开始获取所有知识空间列表，每页数量: ${pageSize}`);
+            const endpoint = '/wiki/v2/spaces';
+            let allItems = [];
+            let pageToken = undefined;
+            let hasMore = true;
+            // 循环获取所有页的数据
+            while (hasMore) {
+                const params = { page_size: pageSize };
+                if (pageToken) {
+                    params.page_token = pageToken;
+                }
+                Logger.debug(`请求知识空间列表，page_token: ${pageToken || 'null'}, page_size: ${pageSize}`);
+                const response = await this.get(endpoint, params);
+                if (response && response.items) {
+                    const newItems = response.items;
+                    allItems = [...allItems, ...newItems];
+                    hasMore = response.has_more || false;
+                    pageToken = response.page_token;
+                    Logger.debug(`当前页获取到 ${newItems.length} 个知识空间，累计 ${allItems.length} 个，hasMore: ${hasMore}`);
+                }
+                else {
+                    hasMore = false;
+                    Logger.warn('知识空间列表响应格式异常:', JSON.stringify(response, null, 2));
+                }
+            }
+            Logger.info(`知识空间列表获取完成，共 ${allItems.length} 个空间`);
+            return allItems; // 直接返回数组，不包装在 items 中
+        }
+        catch (error) {
+            this.handleApiError(error, '获取知识空间列表失败');
+        }
+    }
+    /**
+     * 获取所有知识空间子节点列表（遍历所有分页）
+     * @param spaceId 知识空间ID
+     * @param parentNodeToken 父节点Token（可选，为空时获取根节点）
+     * @param pageSize 每页数量，默认20
+     * @returns 所有子节点列表（仅包含 items 数组，不包含 has_more 和 page_token）
+     */
+    async getAllWikiSpaceNodes(spaceId, parentNodeToken, pageSize = 20) {
+        try {
+            Logger.info(`开始获取知识空间子节点列表，space_id: ${spaceId}, parent_node_token: ${parentNodeToken || 'null'}, 每页数量: ${pageSize}`);
+            const endpoint = `/wiki/v2/spaces/${spaceId}/nodes`;
+            let allItems = [];
+            let pageToken = undefined;
+            let hasMore = true;
+            // 循环获取所有页的数据
+            while (hasMore) {
+                const params = { page_size: pageSize };
+                if (parentNodeToken) {
+                    params.parent_node_token = parentNodeToken;
+                }
+                if (pageToken) {
+                    params.page_token = pageToken;
+                }
+                Logger.debug(`请求知识空间子节点列表，page_token: ${pageToken || 'null'}, page_size: ${pageSize}`);
+                const response = await this.get(endpoint, params);
+                if (response && response.items) {
+                    const newItems = response.items;
+                    allItems = [...allItems, ...newItems];
+                    hasMore = response.has_more || false;
+                    pageToken = response.page_token;
+                    Logger.debug(`当前页获取到 ${newItems.length} 个子节点，累计 ${allItems.length} 个，hasMore: ${hasMore}`);
+                }
+                else {
+                    hasMore = false;
+                    Logger.warn('知识空间子节点列表响应格式异常:', JSON.stringify(response, null, 2));
+                }
+            }
+            Logger.info(`知识空间子节点列表获取完成，共 ${allItems.length} 个节点`);
+            return allItems; // 直接返回数组，不包装在 items 中
+        }
+        catch (error) {
+            this.handleApiError(error, '获取知识空间子节点列表失败');
+        }
+    }
+    /**
+     * 获取知识空间信息
+     * @param spaceId 知识空间ID，传入 'my_library' 时获取"我的知识库"
+     * @param lang 语言（仅当 spaceId 为 'my_library' 时有效），默认'en'
+     * @returns 知识空间信息
+     */
+    async getWikiSpaceInfo(spaceId, lang = 'en') {
+        try {
+            const endpoint = `/wiki/v2/spaces/${spaceId}`;
+            const params = {};
+            // 当 spaceId 为 'my_library' 时，添加 lang 参数
+            if (spaceId === 'my_library') {
+                params.lang = lang;
+            }
+            const response = await this.get(endpoint, params);
+            Logger.debug(`获取知识空间信息成功 (space_id: ${spaceId}):`, response);
+            // 如果响应中包含 space 字段，直接返回 space 对象；否则返回整个响应
+            if (response && response.space) {
+                return response.space;
+            }
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, `获取知识空间信息失败 (space_id: ${spaceId})`);
+        }
+    }
+    /**
+     * 创建知识空间节点（知识库节点）
+     * @param spaceId 知识空间ID
+     * @param title 节点标题
+     * @param parentNodeToken 父节点Token（可选，为空时在根节点下创建）
+     * @returns 创建的节点信息，包含 node_token（节点ID）和 obj_token（文档ID）
+     */
+    async createWikiSpaceNode(spaceId, title, parentNodeToken) {
+        try {
+            Logger.info(`开始创建知识空间节点，space_id: ${spaceId}, title: ${title}, parent_node_token: ${parentNodeToken || 'null（根节点）'}`);
+            const endpoint = `/wiki/v2/spaces/${spaceId}/nodes`;
+            const payload = {
+                title,
+                obj_type: 'docx',
+                node_type: 'origin',
+            };
+            if (parentNodeToken) {
+                payload.parent_node_token = parentNodeToken;
+            }
+            const response = await this.post(endpoint, payload);
+            // 提取 node 对象，统一返回格式
+            if (response && response.data && response.data.node) {
+                const node = response.data.node;
+                Logger.info(`知识空间节点创建成功，node_token: ${node.node_token}, obj_token: ${node.obj_token}`);
+                return node;
+            }
+            Logger.info(`知识空间节点创建成功`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '创建知识空间节点失败');
+        }
+    }
     /**
      * 获取文件夹中的文件清单
      * @param folderToken 文件夹Token
@@ -916,51 +1328,282 @@ export class FeishuApiService extends BaseApiService {
         }
     }
     /**
-     * 搜索飞书文档
+     * 搜索飞书文档（支持分页和轮询）
      * @param searchKey 搜索关键字
-     * @param count 每页数量，默认50
-     * @returns 搜索结果，包含所有页的数据
+     * @param maxSize 最大返回数量，如果未指定则只返回一页
+     * @param offset 偏移量，用于分页，默认0
+     * @returns 搜索结果，包含数据和分页信息
      */
-    async searchDocuments(searchKey, count = 50) {
+    async searchDocuments(searchKey, maxSize, offset = 0) {
         try {
-            Logger.info(`开始搜索文档，关键字: ${searchKey}`);
+            Logger.info(`开始搜索文档，关键字: ${searchKey}, maxSize: ${maxSize || '未指定'}, offset: ${offset}`);
             const endpoint = `/suite/docs-api/search/object`;
-            let offset = 0;
-            let allResults = [];
+            const PAGE_SIZE = 50; // 文档API固定使用50
+            const allResults = [];
+            let currentOffset = offset;
             let hasMore = true;
-            // 循环获取所有页的数据
-            while (hasMore && offset + count < 200) {
+            // 如果指定了maxSize，轮询获取直到满足maxSize或没有更多数据
+            while (hasMore && (maxSize === undefined || allResults.length < maxSize)) {
                 const payload = {
                     search_key: searchKey,
                     docs_types: ["doc"],
-                    count: count,
-                    offset: offset
+                    count: PAGE_SIZE,
+                    offset: currentOffset
                 };
-                Logger.debug(`请求搜索，offset: ${offset}, count: ${count}`);
+                Logger.debug(`请求搜索文档，offset: ${currentOffset}, count: ${PAGE_SIZE}`);
                 const response = await this.post(endpoint, payload);
                 Logger.debug('搜索响应:', JSON.stringify(response, null, 2));
                 if (response && response.docs_entities) {
-                    const newDocs = response.docs_entities;
-                    allResults = [...allResults, ...newDocs];
-                    hasMore = response.has_more || false;
-                    offset += count;
-                    Logger.debug(`当前页获取到 ${newDocs.length} 条数据，累计 ${allResults.length} 条，总计 ${response.total} 条，hasMore: ${hasMore}`);
+                    const resultCount = response.docs_entities.length;
+                    const apiHasMore = response.has_more || false;
+                    // 更新offset
+                    currentOffset += resultCount;
+                    if (resultCount > 0) {
+                        allResults.push(...response.docs_entities);
+                        hasMore = apiHasMore; // 保持API返回的hasMore
+                        // 如果指定了maxSize，只取需要的数量
+                        if (maxSize == undefined || allResults.length >= maxSize) {
+                            // 如果已经达到maxSize，停止轮询，但保持API返回的hasMore值
+                            Logger.debug(`已达到maxSize ${maxSize}，停止获取，但API还有更多: ${hasMore}`);
+                            break; // 停止轮询
+                        }
+                    }
+                    else {
+                        hasMore = false;
+                    }
+                    Logger.debug(`文档搜索进度: 已获取 ${allResults.length} 条，hasMore: ${hasMore}`);
                 }
                 else {
-                    hasMore = false;
                     Logger.warn('搜索响应格式异常:', JSON.stringify(response, null, 2));
+                    hasMore = false;
                 }
             }
             const resultCount = allResults.length;
-            Logger.info(`文档搜索完成，找到 ${resultCount} 个结果`);
+            Logger.info(`文档搜索完成，找到 ${resultCount} 个结果${maxSize ? `(maxSize: ${maxSize})` : ''}`);
             return {
-                data: allResults
+                items: allResults,
+                hasMore: hasMore,
+                nextOffset: currentOffset
             };
         }
         catch (error) {
             this.handleApiError(error, '搜索文档失败');
+            throw error;
+        }
+    }
+    /**
+     * 搜索Wiki知识库节点（支持分页和轮询）
+     * @param query 搜索关键字
+     * @param maxSize 最大返回数量，如果未指定则只返回一页
+     * @param pageToken 分页token，用于获取下一页，可选
+     * @returns 搜索结果，包含数据和分页信息
+     */
+    async searchWikiNodes(query, maxSize, pageToken) {
+        try {
+            Logger.info(`开始搜索知识库，关键字: ${query}, maxSize: ${maxSize || '未指定'}, pageToken: ${pageToken || '无'}`);
+            const endpoint = `/wiki/v1/nodes/search`;
+            const PAGE_SIZE = 20; // Wiki API每页固定使用20
+            const allResults = [];
+            let currentPageToken = pageToken;
+            let hasMore = true;
+            // 如果指定了maxSize，轮询获取直到满足maxSize或没有更多数据
+            while (hasMore && (maxSize === undefined || allResults.length < maxSize)) {
+                const size = Math.min(PAGE_SIZE, 100); // Wiki API最大支持100
+                let url = `${endpoint}?page_size=${size}`;
+                if (currentPageToken) {
+                    url += `&page_token=${currentPageToken}`;
+                }
+                const payload = {
+                    query: query
+                };
+                Logger.debug(`请求搜索知识库，pageSize: ${size}, pageToken: ${currentPageToken || '无'}`);
+                const response = await this.post(url, payload);
+                Logger.debug('知识库搜索响应:', JSON.stringify(response, null, 2));
+                // baseService的post方法已经提取了response.data.data，所以response直接就是data字段的内容
+                if (response && response.items) {
+                    const resultCount = response.items?.length || 0;
+                    const apiHasMore = response.has_more || false;
+                    currentPageToken = response.page_token || null;
+                    if (resultCount > 0) {
+                        allResults.push(...response.items);
+                        hasMore = apiHasMore; // 保持API返回的hasMore，以便下次调用可以继续
+                        if (maxSize !== undefined) {
+                            // 如果已经达到maxSize，停止轮询，但保持API返回的hasMore值
+                            if (allResults.length >= maxSize) {
+                                Logger.debug(`已达到maxSize ${maxSize}，停止获取，但API还有更多: ${hasMore}`);
+                                break; // 停止轮询
+                            }
+                        }
+                        else {
+                            break; // 只返回一页
+                        }
+                    }
+                    else {
+                        hasMore = false;
+                    }
+                    Logger.debug(`知识库搜索进度: 已获取 ${allResults.length} 条，hasMore: ${hasMore}`);
+                }
+                else {
+                    Logger.warn('知识库搜索响应格式异常:', JSON.stringify(response, null, 2));
+                    hasMore = false;
+                }
+            }
+            const resultCount = allResults.length;
+            Logger.info(`知识库搜索完成，找到 ${resultCount} 个结果${maxSize ? `(maxSize: ${maxSize})` : ''}`);
+            return {
+                items: allResults,
+                hasMore: hasMore,
+                pageToken: currentPageToken,
+                count: resultCount
+            };
+        }
+        catch (error) {
+            this.handleApiError(error, '搜索知识库失败');
+            throw error;
         }
     }
+    /**
+     * 统一搜索方法，支持文档和知识库搜索
+     * @param searchKey 搜索关键字
+     * @param searchType 搜索类型：'document' | 'wiki' | 'both'，默认'both'
+     * @param offset 文档搜索的偏移量，可选（用于分页）
+     * @param pageToken 知识库搜索的分页token，可选（用于分页）
+     * @returns 搜索结果，包含documents、wikis和分页信息
+     */
+    async search(searchKey, searchType = 'both', offset, pageToken) {
+        try {
+            // wiki搜索不支持tenant认证，如果是tenant模式则强制使用document搜索
+            if (this.config.feishu.authType === 'tenant' && (searchType === 'wiki' || searchType === 'both')) {
+                Logger.info(`租户认证模式下wiki搜索不支持，强制将searchType从 ${searchType} 修改为 document`);
+                searchType = 'document';
+            }
+            const MAX_TOTAL_RESULTS = 100; // 总共最多200条（文档+wiki合计）
+            const docOffset = offset ?? 0;
+            Logger.info(`开始统一搜索，关键字: ${searchKey}, 类型: ${searchType}, offset: ${docOffset}, pageToken: ${pageToken || '无'}`);
+            const documents = [];
+            const wikis = [];
+            // 用于生成分页指导的内部变量
+            let documentOffset = docOffset;
+            let wikiPageToken = null;
+            let documentHasMore = false;
+            let wikiHasMore = false;
+            // 搜索文档
+            if (searchType === 'document' || searchType === 'both') {
+                // 计算文档的最大数量（不超过总限制）
+                const maxDocCount = MAX_TOTAL_RESULTS;
+                const docResult = await this.searchDocuments(searchKey, maxDocCount, docOffset);
+                if (docResult.items && docResult.items.length > 0) {
+                    documents.push(...docResult.items);
+                    documentOffset = docResult.nextOffset;
+                    documentHasMore = docResult.hasMore;
+                    Logger.debug(`文档搜索: 获取 ${docResult.items.length} 条，新offset: ${documentOffset}, hasMore: ${documentHasMore}`);
+                }
+                else {
+                    documentHasMore = false;
+                    Logger.debug('文档搜索: 无结果');
+                }
+            }
+            // 搜索知识库（仅在文档+wiki总数未达到100条时继续）
+            if (searchType === 'wiki' || searchType === 'both') {
+                const currentDocCount = documents.length;
+                const remainingCount = MAX_TOTAL_RESULTS - currentDocCount;
+                // 如果还有剩余空间，获取知识库
+                if (remainingCount > 0) {
+                    const wikiResult = await this.searchWikiNodes(searchKey, remainingCount, pageToken);
+                    if (wikiResult.items && wikiResult.items.length > 0) {
+                        wikis.push(...wikiResult.items);
+                        wikiPageToken = wikiResult.pageToken;
+                        wikiHasMore = wikiResult.hasMore;
+                        Logger.debug(`知识库搜索: 获取 ${wikiResult.items.length} 条，pageToken: ${wikiPageToken || '无'}, hasMore: ${wikiHasMore}`);
+                    }
+                    else {
+                        wikiHasMore = false;
+                        Logger.debug('知识库搜索: 无结果');
+                    }
+                }
+                else {
+                    Logger.info(`已达到总限制 ${MAX_TOTAL_RESULTS} 条，不再获取知识库`);
+                    wikiHasMore = true;
+                }
+            }
+            // 生成分页指导信息
+            const paginationGuide = this.generatePaginationGuide(searchType, documentHasMore, wikiHasMore, documentOffset, wikiPageToken);
+            const total = documents.length + wikis.length;
+            const hasMore = documentHasMore || wikiHasMore;
+            Logger.info(`统一搜索完成，文档: ${documents.length} 条, 知识库: ${wikis.length} 条, 总计: ${total} 条, hasMore: ${hasMore}`);
+            // 只返回必要字段，根据搜索类型动态添加
+            const result = {
+                paginationGuide
+            };
+            if (searchType === 'document' || searchType === 'both') {
+                result.documents = documents;
+            }
+            if (searchType === 'wiki' || searchType === 'both') {
+                result.wikis = wikis;
+            }
+            return result;
+        }
+        catch (error) {
+            this.handleApiError(error, '统一搜索失败');
+            throw error;
+        }
+    }
+    /**
+     * 生成分页指导信息
+     * @param searchType 搜索类型
+     * @param documentHasMore 文档是否还有更多
+     * @param wikiHasMore 知识库是否还有更多
+     * @param documentOffset 文档的下一offset
+     * @param wikiPageToken 知识库的下一页token
+     * @returns 分页指导信息
+     */
+    generatePaginationGuide(searchType, documentHasMore, wikiHasMore, documentOffset, wikiPageToken) {
+        const guide = {
+            hasMore: documentHasMore || wikiHasMore,
+            description: ''
+        };
+        if (!guide.hasMore) {
+            guide.description = '没有更多结果了';
+            return guide;
+        }
+        // 根据搜索类型和hasMore状态生成指导
+        if (searchType === 'document') {
+            if (documentHasMore) {
+                guide.nextPageParams = {
+                    searchType: 'document',
+                    offset: documentOffset
+                };
+                guide.description = `请使用 search_feishu_documents工具获取下一页,searchType = document offset=${documentOffset} 获取文档的下一页`;
+            }
+        }
+        else if (searchType === 'wiki') {
+            if (wikiHasMore && wikiPageToken) {
+                guide.nextPageParams = {
+                    searchType: 'wiki',
+                    pageToken: wikiPageToken
+                };
+                guide.description = `请使用 search_feishu_documents工具获取下一页,searchType = wiki pageToken="${wikiPageToken}" 获取知识库的下一页`;
+            }
+        }
+        else if (searchType === 'both') {
+            // both类型：优先返回文档的下一页，如果文档没有更多了，再返回知识库的下一页
+            if (documentHasMore) {
+                guide.nextPageParams = {
+                    searchType: 'both',
+                    offset: documentOffset
+                };
+                guide.description = `请使用 search_feishu_documents工具获取下一页,searchType = both offset=${documentOffset} 获取文档的下一页`;
+            }
+            else if (wikiHasMore && wikiPageToken) {
+                guide.nextPageParams = {
+                    searchType: 'wiki',
+                    pageToken: wikiPageToken
+                };
+                guide.description = `请使用 search_feishu_documents工具获取下一页,searchType = wiki pageToken="${wikiPageToken}" 获取知识库的下一页wiki结果`;
+            }
+        }
+        return guide;
+    }
     /**
      * 上传图片素材到飞书
      * @param imageBase64 图片的Base64编码
@@ -1162,6 +1805,36 @@ export class FeishuApiService extends BaseApiService {
             return Buffer.from([]); // 永远不会执行到这里
         }
     }
+    /**
+     * 在画板中创建图表节点（支持 PlantUML 和 Mermaid）
+     * @param whiteboardId 画板ID（token）
+     * @param code 图表代码（PlantUML 或 Mermaid）
+     * @param syntaxType 语法类型：1=PlantUML, 2=Mermaid
+     * @returns 创建结果
+     */
+    async createDiagramNode(whiteboardId, code, syntaxType) {
+        try {
+            const normalizedWhiteboardId = ParamUtils.processWhiteboardId(whiteboardId);
+            const endpoint = `/board/v1/whiteboards/${normalizedWhiteboardId}/nodes/plantuml`;
+            const syntaxTypeName = syntaxType === 1 ? 'PlantUML' : 'Mermaid';
+            Logger.info(`开始在画板中创建 ${syntaxTypeName} 节点，画板ID: ${normalizedWhiteboardId}`);
+            Logger.debug(`${syntaxTypeName} 代码: ${code.substring(0, 200)}...`);
+            const payload = {
+                plant_uml_code: code,
+                style_type: 1, // 画板样式（默认为2 经典样式） 示例值：1 可选值有： 1：画板样式（解析之后为多个画板节点，粘贴到画板中，不可对语法进行二次编辑） 2：经典样式（解析之后为一张图片，粘贴到画板中，可对语法进行二次编辑）（只有PlantUml语法支持经典样式
+                syntax_type: syntaxType
+            };
+            Logger.debug(`请求载荷: ${JSON.stringify(payload, null, 2)}`);
+            const response = await this.post(endpoint, payload);
+            Logger.info(`${syntaxTypeName} 节点创建成功`);
+            return response;
+        }
+        catch (error) {
+            const syntaxTypeName = syntaxType === 1 ? 'PlantUML' : 'Mermaid';
+            Logger.error(`创建 ${syntaxTypeName} 节点失败，画板ID: ${whiteboardId}`, error);
+            this.handleApiError(error, `创建 ${syntaxTypeName} 节点失败`);
+        }
+    }
     /**
      * 从路径或URL获取图片的Base64编码
      * @param imagePathOrUrl 图片路径或URL