feishu-mcp 0.2.2 → 0.2.7

package/dist/services/feishu/FeishuSearchService.js

@@ -0,0 +1,232 @@
+import { Logger } from '../../utils/logger.js';
+import { Config } from '../../utils/config.js';
+import { FeishuBaseApiService } from './FeishuBaseApiService.js';
+/**
+ * 飞书搜索服务
+ * 负责文档和知识库的搜索
+ */
+export class FeishuSearchService extends FeishuBaseApiService {
+    constructor(authService) {
+        super(authService);
+    }
+    /**
+     * 搜索飞书文档（Docs），支持分页轮询直到获取指定数量的结果
+     * 注意：仅支持 tenant 和 user 两种认证模式
+     * @param searchKey 搜索关键字
+     * @param maxSize 最大返回数量；不指定时只返回第一页（约 50 条）
+     * @param offset 起始偏移量，用于分页续取，默认 0
+     * @returns 搜索结果对象，包含 items（文档列表）、hasMore（是否还有更多）、nextOffset（下次请求的偏移量）
+     */
+    async searchDocuments(searchKey, maxSize, offset = 0) {
+        try {
+            Logger.info(`开始搜索文档，关键字: ${searchKey}, maxSize: ${maxSize || '未指定'}, offset: ${offset}`);
+            const endpoint = '/suite/docs-api/search/object';
+            const PAGE_SIZE = 50;
+            const allResults = [];
+            let currentOffset = offset;
+            let hasMore = true;
+            while (hasMore && (maxSize === undefined || allResults.length < maxSize)) {
+                const payload = {
+                    search_key: searchKey,
+                    docs_types: ['doc'],
+                    count: PAGE_SIZE,
+                    offset: currentOffset
+                };
+                Logger.debug(`请求搜索文档，offset: ${currentOffset}, count: ${PAGE_SIZE}`);
+                const response = await this.post(endpoint, payload);
+                Logger.debug('搜索响应:', JSON.stringify(response, null, 2));
+                if (response?.docs_entities) {
+                    const resultCount = response.docs_entities.length;
+                    const apiHasMore = response.has_more || false;
+                    currentOffset += resultCount;
+                    if (resultCount > 0) {
+                        allResults.push(...response.docs_entities);
+                        hasMore = apiHasMore;
+                        if (maxSize == undefined || allResults.length >= maxSize) {
+                            Logger.debug(`已达到maxSize ${maxSize}，停止获取，但API还有更多: ${hasMore}`);
+                            break;
+                        }
+                    }
+                    else {
+                        hasMore = false;
+                    }
+                    Logger.debug(`文档搜索进度: 已获取 ${allResults.length} 条，hasMore: ${hasMore}`);
+                }
+                else {
+                    Logger.warn('搜索响应格式异常:', JSON.stringify(response, null, 2));
+                    hasMore = false;
+                }
+            }
+            Logger.info(`文档搜索完成，找到 ${allResults.length} 个结果${maxSize ? `(maxSize: ${maxSize})` : ''}`);
+            return { items: allResults, hasMore, nextOffset: currentOffset };
+        }
+        catch (error) {
+            this.handleApiError(error, '搜索文档失败');
+            throw error;
+        }
+    }
+    /**
+     * 搜索飞书知识库（Wiki）节点，支持分页轮询直到获取指定数量的结果
+     * 注意：Wiki 搜索需要 user 认证，tenant 模式下不可用
+     * @param query 搜索关键字
+     * @param maxSize 最大返回数量；不指定时只返回第一页（约 20 条）
+     * @param pageToken 分页 Token，用于续取下一页，从上次返回的 pageToken 传入
+     * @returns 搜索结果对象，包含 items（节点列表）、hasMore、pageToken（下次请求用）、count（本次数量）
+     */
+    async searchWikiNodes(query, maxSize, pageToken) {
+        try {
+            Logger.info(`开始搜索知识库，关键字: ${query}, maxSize: ${maxSize || '未指定'}, pageToken: ${pageToken || '无'}`);
+            const endpoint = '/wiki/v1/nodes/search';
+            const PAGE_SIZE = 20;
+            const allResults = [];
+            let currentPageToken = pageToken;
+            let hasMore = true;
+            while (hasMore && (maxSize === undefined || allResults.length < maxSize)) {
+                const size = Math.min(PAGE_SIZE, 100);
+                let url = `${endpoint}?page_size=${size}`;
+                if (currentPageToken)
+                    url += `&page_token=${currentPageToken}`;
+                const payload = { query };
+                Logger.debug(`请求搜索知识库，pageSize: ${size}, pageToken: ${currentPageToken || '无'}`);
+                const response = await this.post(url, payload);
+                Logger.debug('知识库搜索响应:', JSON.stringify(response, null, 2));
+                if (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;
+                        if (maxSize !== undefined) {
+                            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;
+                }
+            }
+            Logger.info(`知识库搜索完成，找到 ${allResults.length} 个结果${maxSize ? `(maxSize: ${maxSize})` : ''}`);
+            return { items: allResults, hasMore, pageToken: currentPageToken, count: allResults.length };
+        }
+        catch (error) {
+            this.handleApiError(error, '搜索知识库失败');
+            throw error;
+        }
+    }
+    /**
+     * 统一搜索入口，可同时搜索文档和知识库节点
+     * 当 authType 为 tenant 时，wiki 搜索不可用，会自动降级为 document 搜索
+     * 单次调用最多返回 100 条合并结果（文档 + Wiki）
+     * @param searchKey 搜索关键字
+     * @param searchType 搜索范围：'document' 仅搜文档，'wiki' 仅搜知识库，'both' 同时搜索，默认 'both'
+     * @param offset 文档搜索的起始偏移量，用于分页续取，默认 0
+     * @param pageToken 知识库搜索的分页 Token，用于续取下一页
+     * @returns 搜索结果对象，包含 documents（文档列表）、wikis（知识库节点列表）和 paginationGuide（分页指导）
+     */
+    async search(searchKey, searchType = 'both', offset, pageToken) {
+        try {
+            if (Config.getInstance().feishu.authType === 'tenant' && (searchType === 'wiki' || searchType === 'both')) {
+                Logger.info(`租户认证模式下wiki搜索不支持，强制将searchType从 ${searchType} 修改为 document`);
+                searchType = 'document';
+            }
+            const MAX_TOTAL_RESULTS = 100;
+            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 docResult = await this.searchDocuments(searchKey, MAX_TOTAL_RESULTS, docOffset);
+                if (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('文档搜索: 无结果');
+                }
+            }
+            if (searchType === 'wiki' || searchType === 'both') {
+                const remainingCount = MAX_TOTAL_RESULTS - documents.length;
+                if (remainingCount > 0) {
+                    const wikiResult = await this.searchWikiNodes(searchKey, remainingCount, pageToken);
+                    if (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;
+        }
+    }
+    generatePaginationGuide(searchType, documentHasMore, wikiHasMore, documentOffset, wikiPageToken) {
+        const guide = { hasMore: documentHasMore || wikiHasMore, description: '' };
+        if (!guide.hasMore) {
+            guide.description = '没有更多结果了';
+            return guide;
+        }
+        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') {
+            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;
+    }
+}

package/dist/services/feishu/FeishuWhiteboardService.js

@@ -0,0 +1,80 @@
+import { Logger } from '../../utils/logger.js';
+import { ParamUtils } from '../../utils/paramUtils.js';
+import { FeishuBaseApiService } from './FeishuBaseApiService.js';
+/**
+ * 飞书画板（Whiteboard）服务
+ */
+export class FeishuWhiteboardService extends FeishuBaseApiService {
+    constructor(authService) {
+        super(authService);
+    }
+    /**
+     * 获取画板的所有节点内容
+     * @param whiteboardId 画板 ID、Token 或包含画板 ID 的 URL
+     * @returns 画板节点数据，包含 nodes 数组，每项含节点 ID、类型、位置等信息
+     */
+    async getWhiteboardContent(whiteboardId) {
+        try {
+            const normalizedWhiteboardId = ParamUtils.processWhiteboardId(whiteboardId);
+            const endpoint = `/board/v1/whiteboards/${normalizedWhiteboardId}/nodes`;
+            Logger.info(`开始获取画板内容，画板ID: ${normalizedWhiteboardId}`);
+            const response = await this.get(endpoint);
+            Logger.info(`画板内容获取成功，节点数量: ${response.nodes?.length || 0}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取画板内容失败');
+        }
+    }
+    /**
+     * 获取画板的缩略图，以二进制数据返回
+     * @param whiteboardId 画板 ID、Token 或包含画板 ID 的 URL
+     * @returns 缩略图的二进制 Buffer 数据（PNG 格式）
+     */
+    async getWhiteboardThumbnail(whiteboardId) {
+        try {
+            const normalizedWhiteboardId = ParamUtils.processWhiteboardId(whiteboardId);
+            const endpoint = `/board/v1/whiteboards/${normalizedWhiteboardId}/download_as_image`;
+            Logger.info(`开始获取画板缩略图，画板ID: ${normalizedWhiteboardId}`);
+            const response = await this.request(endpoint, 'GET', {}, true, {}, 'arraybuffer');
+            const thumbnailBuffer = Buffer.from(response);
+            Logger.info(`画板缩略图获取成功，大小: ${thumbnailBuffer.length} 字节`);
+            return thumbnailBuffer;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取画板缩略图失败');
+            return Buffer.from([]);
+        }
+    }
+    /**
+     * 在画板中创建图表节点，支持 PlantUML 和 Mermaid 两种语法
+     * 注意：style_type 固定为 1（画板样式），会解析为多个画板节点
+     * @param whiteboardId 画板 ID、Token 或包含画板 ID 的 URL
+     * @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,
+                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} 节点失败`);
+        }
+    }
+}

package/dist/services/feishu/FeishuWikiService.js

@@ -0,0 +1,134 @@
+import { Logger } from '../../utils/logger.js';
+import { FeishuBaseApiService } from './FeishuBaseApiService.js';
+/**
+ * 飞书知识库（Wiki）服务
+ * 负责知识空间及节点的查询与创建
+ */
+export class FeishuWikiService extends FeishuBaseApiService {
+    constructor(authService) {
+        super(authService);
+    }
+    /**
+     * 获取当前用户可见的所有知识空间列表，自动处理分页直到获取全部数据
+     * @param pageSize 每次分页请求的数量，默认 20
+     * @returns 知识空间对象数组，每项包含 space_id、name、description 等字段
+     */
+    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?.items) {
+                    allItems = [...allItems, ...response.items];
+                    hasMore = response.has_more || false;
+                    pageToken = response.page_token;
+                    Logger.debug(`当前页获取到 ${response.items.length} 个知识空间，累计 ${allItems.length} 个，hasMore: ${hasMore}`);
+                }
+                else {
+                    hasMore = false;
+                    Logger.warn('知识空间列表响应格式异常:', JSON.stringify(response, null, 2));
+                }
+            }
+            Logger.info(`知识空间列表获取完成，共 ${allItems.length} 个空间`);
+            return allItems;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取知识空间列表失败');
+        }
+    }
+    /**
+     * 获取指定知识空间下的所有子节点，自动处理分页直到获取全部数据
+     * @param spaceId 知识空间 ID
+     * @param parentNodeToken 父节点 Token，不传则获取根节点下的直属子节点
+     * @param pageSize 每次分页请求的数量，默认 20
+     * @returns 节点对象数组，每项包含 node_token、obj_token、title、obj_type 等字段
+     */
+    async getAllWikiSpaceNodes(spaceId, parentNodeToken, pageSize = 20) {
+        try {
+            Logger.info(`开始获取知识空间子节点列表，space_id: ${spaceId}, parent_node_token: ${parentNodeToken || 'null'}`);
+            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'}`);
+                const response = await this.get(endpoint, params);
+                if (response?.items) {
+                    allItems = [...allItems, ...response.items];
+                    hasMore = response.has_more || false;
+                    pageToken = response.page_token;
+                    Logger.debug(`当前页获取到 ${response.items.length} 个子节点，累计 ${allItems.length} 个，hasMore: ${hasMore}`);
+                }
+                else {
+                    hasMore = false;
+                    Logger.warn('知识空间子节点列表响应格式异常:', JSON.stringify(response, null, 2));
+                }
+            }
+            Logger.info(`知识空间子节点列表获取完成，共 ${allItems.length} 个节点`);
+            return allItems;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取知识空间子节点列表失败');
+        }
+    }
+    /**
+     * 获取指定知识空间的详细信息
+     * 当 spaceId 传入 'my_library' 时，获取当前用户的"我的知识库"信息
+     * @param spaceId 知识空间 ID，或传入 'my_library' 获取个人知识库
+     * @param lang 语言参数，仅当 spaceId 为 'my_library' 时有效，默认 'en'
+     * @returns 知识空间信息对象，包含 space_id、name、description 等字段
+     */
+    async getWikiSpaceInfo(spaceId, lang = 'en') {
+        try {
+            const params = {};
+            if (spaceId === 'my_library')
+                params.lang = lang;
+            const response = await this.get(`/wiki/v2/spaces/${spaceId}`, params);
+            Logger.debug(`获取知识空间信息成功 (space_id: ${spaceId}):`, response);
+            return response?.space || response;
+        }
+        catch (error) {
+            this.handleApiError(error, `获取知识空间信息失败 (space_id: ${spaceId})`);
+        }
+    }
+    /**
+     * 在知识空间中创建一个新的文档节点（类型固定为 docx）
+     * @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);
+            if (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, '创建知识空间节点失败');
+        }
+    }
+}