feishu-mcp 0.2.2 → 0.2.7

package/dist/modules/document/toolApi/documentToolApi.js

@@ -0,0 +1,65 @@
+import { Logger } from '../../../utils/logger.js';
+import { extractSpecialBlocks, appendSpecialBlockTextHints } from '../tools/toolHelpers.js';
+/**
+ * 创建飞书文档（文件夹模式或知识库节点模式）
+ */
+export async function createDocument(params, api) {
+    const { title, folderToken, wikiContext } = params;
+    if (folderToken && wikiContext) {
+        throw new Error('错误：不能同时提供 folderToken 和 wikiContext 参数，请选择其中一种模式。\n' +
+            '- 使用 folderToken 在飞书文档目录中操作\n' +
+            '- 使用 wikiContext 在知识库中操作');
+    }
+    if (!folderToken && !wikiContext) {
+        throw new Error('错误：必须提供 folderToken（飞书文档目录模式）或 wikiContext（知识库节点模式）参数之一。');
+    }
+    if (folderToken) {
+        Logger.info(`createDocument invoked: folder mode, title=${title}`);
+        const newDoc = await api.createDocument(title, folderToken);
+        if (!newDoc)
+            throw new Error('创建文档失败，未返回文档信息');
+        return newDoc;
+    }
+    if (!wikiContext)
+        throw new Error('错误：内部参数状态异常。');
+    const { spaceId, parentNodeToken } = wikiContext;
+    if (!spaceId) {
+        throw new Error('错误：使用 wikiContext 模式时，必须提供 spaceId。');
+    }
+    Logger.info(`createDocument invoked: wiki mode, title=${title}, spaceId=${spaceId}`);
+    const node = await api.createWikiSpaceNode(spaceId, title, parentNodeToken);
+    if (!node)
+        throw new Error('创建知识库节点失败，未返回节点信息');
+    return {
+        ...node,
+        _note: '知识库节点既是节点又是文档：node_token 可作为父节点使用，obj_token 可用于文档编辑操作',
+    };
+}
+/**
+ * 获取飞书文档信息（支持普通文档和 Wiki 文档）
+ */
+export async function getDocumentInfo(params, api) {
+    const { documentId, documentType } = params;
+    Logger.info(`getDocumentInfo invoked: documentId=${documentId}, type=${documentType ?? 'auto'}`);
+    const docInfo = await api.getDocumentInfo(documentId, documentType);
+    if (!docInfo)
+        throw new Error('获取文档信息失败，未返回数据');
+    return docInfo;
+}
+/**
+ * 获取飞书文档块结构
+ */
+export async function getDocumentBlocks(documentId, api) {
+    Logger.info(`getDocumentBlocks invoked: documentId=${documentId}`);
+    const blocks = await api.getDocumentBlocks(documentId);
+    const { imageBlocks, whiteboardBlocks } = extractSpecialBlocks(blocks);
+    return appendSpecialBlockTextHints(JSON.stringify(blocks, null, 2), imageBlocks, whiteboardBlocks);
+}
+/**
+ * 搜索飞书文档和/或知识库节点
+ */
+export async function searchDocuments(params, api) {
+    const { searchKey, searchType = 'both', offset, pageToken } = params;
+    Logger.info(`searchDocuments invoked: searchKey=${searchKey}, type=${searchType}`);
+    return api.search(searchKey, searchType, offset, pageToken);
+}

package/dist/modules/document/toolApi/folderToolApi.js

@@ -0,0 +1,73 @@
+import { Logger } from '../../../utils/logger.js';
+import { formatErrorMessage } from '../../../utils/error.js';
+/**
+ * 获取飞书根文件夹信息、知识空间列表和我的知识库
+ */
+export async function getRootFolderInfo(api) {
+    Logger.info('getRootFolderInfo invoked');
+    const result = {
+        root_folder: null,
+        wiki_spaces: [],
+        my_library: null,
+    };
+    try {
+        const folderInfo = await api.getRootFolderInfo();
+        result.root_folder = folderInfo?.data ?? folderInfo;
+    }
+    catch (error) {
+        Logger.error(`获取飞书根文件夹信息失败:`, error);
+        result.root_folder = { error: formatErrorMessage(error, '获取根文件夹信息失败') };
+    }
+    try {
+        result.wiki_spaces = (await api.getAllWikiSpacesList(20)) ?? [];
+    }
+    catch (error) {
+        Logger.error(`获取知识空间列表失败:`, error);
+        result.wiki_spaces = [];
+    }
+    try {
+        const myLibrary = await api.getWikiSpaceInfo('my_library', 'en');
+        const libraryData = myLibrary?.data ?? myLibrary;
+        result.my_library = libraryData?.space ?? libraryData;
+    }
+    catch (error) {
+        Logger.error(`获取我的知识库失败:`, error);
+        result.my_library = { error: formatErrorMessage(error, '获取我的知识库失败') };
+    }
+    return result;
+}
+/**
+ * 获取文件夹或知识空间节点下的文件列表
+ */
+export async function getFolderFiles(params, api) {
+    const { folderToken, wikiContext } = params;
+    if (folderToken && wikiContext) {
+        throw new Error('错误：不能同时提供 folderToken 和 wikiContext 参数，请选择其中一种模式。\n' +
+            '- 使用 folderToken 在飞书文档目录中操作\n' +
+            '- 使用 wikiContext 在知识库中操作');
+    }
+    if (!folderToken && !wikiContext) {
+        throw new Error('错误：必须提供 folderToken（飞书文档目录模式）或 wikiContext（知识库节点模式）参数之一。');
+    }
+    if (folderToken) {
+        Logger.info(`getFolderFiles invoked: folder mode, folderToken=${folderToken}`);
+        return api.getFolderFileList(folderToken);
+    }
+    if (!wikiContext)
+        throw new Error('错误：内部参数状态异常。');
+    const { spaceId, parentNodeToken } = wikiContext;
+    if (!spaceId) {
+        throw new Error('错误：使用 wikiContext 模式时，必须提供 spaceId。');
+    }
+    Logger.info(`getFolderFiles invoked: wiki mode, spaceId=${spaceId}`);
+    const nodeList = await api.getAllWikiSpaceNodes(spaceId, parentNodeToken);
+    return { nodes: nodeList ?? [] };
+}
+/**
+ * 在指定文件夹下创建子文件夹
+ */
+export async function createFolder(params, api) {
+    const { folderToken, folderName } = params;
+    Logger.info(`createFolder invoked: folderToken=${folderToken}, folderName=${folderName}`);
+    return api.createFolder(folderToken, folderName);
+}

package/dist/modules/document/toolApi/index.js

@@ -0,0 +1,3 @@
+export { createDocument, getDocumentInfo, getDocumentBlocks, searchDocuments, } from './documentToolApi.js';
+export { batchUpdateBlockText, batchCreateBlocks, deleteDocumentBlocks, getImageResource, uploadAndBindImageToBlock, createTable, getWhiteboardContent, fillWhiteboardWithPlantuml, } from './blockToolApi.js';
+export { getRootFolderInfo, getFolderFiles, createFolder, } from './folderToolApi.js';

package/dist/modules/document/tools/blockTools.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { formatErrorMessage } from '../../../utils/error.js';
+import { Logger } from '../../../utils/logger.js';
+import { detectMimeType } from '../../../utils/document.js';
+import { batchUpdateBlockText, batchCreateBlocks, deleteDocumentBlocks, getImageResource, uploadAndBindImageToBlock, createTable, getWhiteboardContent, fillWhiteboardWithPlantuml, } from '../toolApi/blockToolApi.js';
+import { DocumentIdSchema, ParentBlockIdSchema, IndexSchema, StartIndexSchema, EndIndexSchema, BlockTextUpdatesArraySchema, BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema, TableCreateSchema, WhiteboardFillArraySchema, WhiteboardIdSchema, } from '../../../types/documentSchema.js';
+import { WIKI_NOTE, errorResponse } from './toolHelpers.js';
+/**
+ * 注册飞书块相关的MCP工具
+ */
+export function registerBlockTools(server, feishuService) {
+    server.tool('batch_update_feishu_block_text', 'Updates text content and styling of multiple document blocks. ' + WIKI_NOTE, {
+        documentId: DocumentIdSchema,
+        updates: BlockTextUpdatesArraySchema,
+    }, async ({ documentId, updates }) => {
+        try {
+            const result = await batchUpdateBlockText({ documentId, updates }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`批量更新飞书块文本内容失败:`, error);
+            return errorResponse(`批量更新飞书块文本内容失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('batch_create_feishu_blocks', 'Creates one or more blocks at a specified position within a Feishu document. Supports text, code, heading, list, image, mermaid, and whiteboard block types. Accepts any number of blocks. ' + WIKI_NOTE, {
+        documentId: DocumentIdSchema,
+        parentBlockId: ParentBlockIdSchema,
+        index: IndexSchema,
+        blocks: z.array(BlockConfigSchema).describe('Array of block configurations to create. Pass as a JSON array, not a serialized string.\n' +
+            'Example: [{blockType:"text",options:{text:{textStyles:[{text:"Hello",style:{bold:true}}]}}},{blockType:"heading",options:{heading:{level:1,content:"My Title"}}}]'),
+    }, async ({ documentId, parentBlockId, index = 0, blocks }) => {
+        try {
+            const result = await batchCreateBlocks({ documentId, parentBlockId, index, blocks }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`批量创建飞书块失败:`, error);
+            return errorResponse(`批量创建飞书块失败: ${formatErrorMessage(error)}\n\n` +
+                `建议使用 get_feishu_document_blocks 工具获取文档当前状态，确认是否有部分内容已创建成功。`);
+        }
+    });
+    server.tool('delete_feishu_document_blocks', 'Deletes a consecutive range of blocks from a Feishu document identified by startIndex (inclusive) and endIndex (exclusive). ' + WIKI_NOTE, {
+        documentId: DocumentIdSchema,
+        parentBlockId: ParentBlockIdSchema,
+        startIndex: StartIndexSchema,
+        endIndex: EndIndexSchema,
+    }, async ({ documentId, parentBlockId, startIndex, endIndex }) => {
+        try {
+            const result = await deleteDocumentBlocks({ documentId, parentBlockId, startIndex, endIndex }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`删除飞书文档块失败:`, error);
+            return errorResponse(`删除飞书文档块失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('get_feishu_image_resource', 'Downloads an image resource from Feishu by its media ID and returns binary image data. To get the mediaId, extract block.image.token from an image block (block_type=27) returned by get_feishu_document_blocks.', {
+        mediaId: MediaIdSchema,
+        extra: MediaExtraSchema,
+    }, async ({ mediaId, extra = '' }) => {
+        try {
+            const imageBuffer = await getImageResource(mediaId, extra, feishuService);
+            const base64Image = imageBuffer.toString('base64');
+            const mimeType = detectMimeType(imageBuffer);
+            return { content: [{ type: 'image', mimeType, data: base64Image }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书图片资源失败:`, error);
+            return errorResponse(`获取飞书图片资源失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('upload_and_bind_image_to_block', 'Uploads images from local paths or URLs and binds them to existing empty image blocks. This tool is used after creating image blocks with batch_create_feishu_blocks tool. It handles uploading the image media and setting the image content to the specified block IDs. Supports local file paths and HTTP/HTTPS URLs. Each image upload and binding is processed independently, and all results are returned in order.', {
+        documentId: DocumentIdSchema,
+        images: ImagesArraySchema,
+    }, async ({ documentId, images }) => {
+        try {
+            const results = await uploadAndBindImageToBlock({ documentId, images }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`批量上传图片并绑定到块失败:`, error);
+            return errorResponse(`批量上传图片并绑定到块失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('create_feishu_table', 'Creates a table block with specified rows and columns in a Feishu document. Each cell can contain text, list, code, or other block types. ' + WIKI_NOTE, {
+        documentId: DocumentIdSchema,
+        parentBlockId: ParentBlockIdSchema,
+        index: IndexSchema,
+        tableConfig: TableCreateSchema,
+    }, async ({ documentId, parentBlockId, index = 0, tableConfig }) => {
+        try {
+            const result = await createTable({ documentId, parentBlockId, index, tableConfig }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`创建飞书表格失败:`, error);
+            return errorResponse(`创建飞书表格失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('get_feishu_whiteboard_content', 'Retrieves the content and structure of a Feishu whiteboard. Use this to analyze whiteboard content, extract information, or understand the structure of collaborative diagrams. The whiteboard ID can be obtained from the board.token field when getting document blocks with block_type: 43.', {
+        whiteboardId: WhiteboardIdSchema,
+    }, async ({ whiteboardId }) => {
+        try {
+            const result = await getWhiteboardContent(whiteboardId, feishuService);
+            if (result.type === 'thumbnail') {
+                return {
+                    content: [
+                        { type: 'image', data: result.buffer.toString('base64'), mimeType: 'image/png' },
+                    ],
+                };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result.content, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书画板内容失败:`, error);
+            return errorResponse(`获取飞书画板内容失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('fill_whiteboard_with_plantuml', 'Fills whiteboard blocks with PlantUML or Mermaid diagram code. Accepts any number of whiteboards. Returns per-item success/failure details.', {
+        whiteboards: WhiteboardFillArraySchema,
+    }, async ({ whiteboards }) => {
+        try {
+            const result = await fillWhiteboardWithPlantuml({ whiteboards }, feishuService);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ total: result.total, success: result.success, failed: result.failed, results: result.results }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            Logger.error(`批量填充画板内容失败:`, error);
+            return errorResponse(`批量填充画板内容失败: ${formatErrorMessage(error)}\n\n错误详情: ${JSON.stringify(error, null, 2)}`);
+        }
+    });
+}

package/dist/modules/document/tools/documentTools.js

@@ -0,0 +1,64 @@
+import { formatErrorMessage } from '../../../utils/error.js';
+import { Logger } from '../../../utils/logger.js';
+import { createDocument, getDocumentInfo, getDocumentBlocks, searchDocuments, } from '../toolApi/documentToolApi.js';
+import { WIKI_NOTE, errorResponse, } from './toolHelpers.js';
+import { DocumentIdSchema, DocumentIdOrWikiIdSchema, DocumentTypeSchema, SearchKeySchema, SearchTypeSchema, PageTokenSchema, OffsetSchema, DocumentTitleSchema, FolderTokenOptionalSchema, WikiSpaceNodeContextSchema, } from '../../../types/documentSchema.js';
+/**
+ * 注册飞书文档相关的MCP工具
+ */
+export function registerDocumentTools(server, feishuService) {
+    server.tool('create_feishu_document', 'Creates a new Feishu document and returns its information. Supports two modes: (1) Feishu Drive folder mode: use folderToken to create a document in a folder. (2) Wiki space node mode: use wikiContext with spaceId (and optional parentNodeToken) to create a node (document) in a wiki space. IMPORTANT: In wiki spaces, documents are nodes themselves - they can act as parent nodes containing child documents, and can also be edited as regular documents. The created node returns both node_token (node ID, can be used as parentNodeToken for creating child nodes) and obj_token (document ID, can be used for document editing operations like get_feishu_document_blocks, batch_create_feishu_blocks, etc.). Only one mode can be used at a time - provide either folderToken OR wikiContext, not both.', {
+        title: DocumentTitleSchema,
+        folderToken: FolderTokenOptionalSchema,
+        wikiContext: WikiSpaceNodeContextSchema,
+    }, async ({ title, folderToken, wikiContext }) => {
+        try {
+            const result = await createDocument({ title, folderToken, wikiContext }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`创建文档失败:`, error);
+            return errorResponse(`创建文档失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('get_feishu_document_info', 'Retrieves basic information about a Feishu document or Wiki node. Supports both regular documents (via document ID/URL) and Wiki documents (via Wiki URL/token). Use this to verify a document exists, check access permissions, or get metadata like title, type, and creation information. For Wiki documents, returns complete node information including documentId (obj_token) for document editing operations, and space_id and node_token for creating child nodes.', {
+        documentId: DocumentIdOrWikiIdSchema,
+        documentType: DocumentTypeSchema,
+    }, async ({ documentId, documentType }) => {
+        try {
+            const docInfo = await getDocumentInfo({ documentId, documentType }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(docInfo, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书文档信息失败:`, error);
+            return errorResponse(formatErrorMessage(error, '获取飞书文档信息失败'));
+        }
+    });
+    server.tool('get_feishu_document_blocks', 'Retrieves the block hierarchy of a Feishu document, including block IDs, types, and content. ' + WIKI_NOTE, {
+        documentId: DocumentIdSchema,
+    }, async ({ documentId }) => {
+        try {
+            const responseText = await getDocumentBlocks(documentId, feishuService);
+            return { content: [{ type: 'text', text: responseText }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书文档块失败:`, error);
+            return errorResponse(`获取飞书文档块失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('search_feishu_documents', 'Searches for documents and/or Wiki knowledge base nodes in Feishu. Supports keyword-based search with type filtering (document, wiki, or both). Returns document and wiki information including title, type, and owner. Supports pagination: use offset for document search pagination and pageToken for wiki search pagination. Each type (document or wiki) can return up to 100 results maximum per search. Default page size is 20 items.', {
+        searchKey: SearchKeySchema,
+        searchType: SearchTypeSchema,
+        offset: OffsetSchema,
+        pageToken: PageTokenSchema,
+    }, async ({ searchKey, searchType, offset, pageToken }) => {
+        try {
+            const searchResult = await searchDocuments({ searchKey, searchType, offset, pageToken }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(searchResult, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`搜索失败:`, error);
+            return errorResponse(`搜索失败: ${formatErrorMessage(error)}`);
+        }
+    });
+}

package/dist/modules/document/tools/folderTools.js

@@ -0,0 +1,46 @@
+import { formatErrorMessage } from '../../../utils/error.js';
+import { Logger } from '../../../utils/logger.js';
+import { getRootFolderInfo, getFolderFiles, createFolder, } from '../toolApi/folderToolApi.js';
+import { FolderTokenSchema, FolderTokenOptionalSchema, FolderNameSchema, WikiSpaceNodeContextSchema, } from '../../../types/documentSchema.js';
+import { errorResponse } from './toolHelpers.js';
+/**
+ * 注册飞书文件夹相关的MCP工具
+ */
+export function registerFolderTools(server, feishuService) {
+    server.tool('get_feishu_root_folder_info', 'Retrieves the root folder in Feishu Drive, wiki spaces list, and "My Library". Use this when you need to browse folders or wiki spaces from the root. If you know the wiki node name, you can also use search_feishu_documents to directly locate specific wiki nodes instead of traversing from root. Returns root folder token, all wiki spaces, and personal library information.', {}, async () => {
+        try {
+            const result = await getRootFolderInfo(feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书信息失败:`, error);
+            return errorResponse(formatErrorMessage(error, '获取飞书信息失败'));
+        }
+    });
+    server.tool('get_feishu_folder_files', 'Retrieves a list of files and subfolders in a specified folder or wiki space node. Supports two modes: (1) Feishu Drive folder mode: use folderToken to get files in a Feishu Drive folder. (2) Wiki space node mode: use wikiContext with spaceId (and optional parentNodeToken) to get documents under a wiki space node. If parentNodeToken is not provided, retrieves nodes from the root of the wiki space. Only one mode can be used at a time - provide either folderToken OR wikiContext.', {
+        folderToken: FolderTokenOptionalSchema,
+        wikiContext: WikiSpaceNodeContextSchema,
+    }, async ({ folderToken, wikiContext }) => {
+        try {
+            const result = await getFolderFiles({ folderToken, wikiContext }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取文件列表失败:`, error);
+            return errorResponse(`获取文件列表失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    server.tool('create_feishu_folder', 'Creates a new folder in a specified parent folder. Use this to organize documents and files within your Feishu Drive structure. Returns the token and URL of the newly created folder.', {
+        folderToken: FolderTokenSchema,
+        folderName: FolderNameSchema,
+    }, async ({ folderToken, folderName }) => {
+        try {
+            const result = await createFolder({ folderToken, folderName }, feishuService);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`创建飞书文件夹失败:`, error);
+            return errorResponse(`创建飞书文件夹失败: ${formatErrorMessage(error)}`);
+        }
+    });
+}

package/dist/modules/document/tools/toolHelpers.js

@@ -0,0 +1,155 @@
+import { formatErrorMessage } from '../../../utils/error.js';
+import { Logger } from '../../../utils/logger.js';
+export const WHITEBOARD_NODE_THUMBNAIL_THRESHOLD = 200;
+export const BATCH_SIZE = 50;
+/** wiki 链接转换提示，在所有需要 documentId 的编辑类工具中复用 */
+export const WIKI_NOTE = 'For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx), ' +
+    'use get_feishu_document_info first to obtain the documentId, then use that ID for editing operations.';
+const BLOCK_TYPE_IMAGE = 27;
+const BLOCK_TYPE_WHITEBOARD = 43;
+export function errorResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// ---------------------------------------------------------------------------
+// 参数校验
+// ---------------------------------------------------------------------------
+/**
+ * 校验 folderToken 与 wikiContext 的互斥关系（文件夹模式 vs 知识库模式）。
+ * 返回 null 表示校验通过，否则返回可直接 return 的错误响应。
+ */
+export function validateFolderOrWikiContext(folderToken, wikiContext) {
+    if (folderToken && wikiContext) {
+        return errorResponse('错误：不能同时提供 folderToken 和 wikiContext 参数，请选择其中一种模式。\n' +
+            '- 使用 folderToken 在飞书文档目录中操作\n' +
+            '- 使用 wikiContext 在知识库中操作');
+    }
+    if (!folderToken && !wikiContext) {
+        return errorResponse('错误：必须提供 folderToken（飞书文档目录模式）或 wikiContext（知识库节点模式）参数之一。');
+    }
+    return null;
+}
+/**
+ * 将 BlockConfig 数组转换为飞书 API 所需的块内容数组。
+ * 遇到单个块处理失败时立即终止。
+ *
+ * 注：contents 类型为 any[] 以匹配 FeishuApiService.createDocumentBlocks 的参数类型。
+ */
+export function prepareBlockContents(configs, feishuService) {
+    const contents = [];
+    for (const { blockType, options = {} } of configs) {
+        try {
+            const blockContent = feishuService.createBlockContent(blockType, options);
+            if (blockContent) {
+                contents.push(blockContent);
+                Logger.info(`已准备 ${blockType} 块，内容: ${JSON.stringify(blockContent).substring(0, 100)}...`);
+            }
+            else {
+                Logger.warn(`创建 ${blockType} 块失败，跳过此块`);
+            }
+        }
+        catch (err) {
+            Logger.error(`处理块类型 ${blockType} 时出错: ${err}`);
+            return {
+                ok: false,
+                error: errorResponse(`处理块类型"${blockType}"时出错: ${err}\n请检查该块类型的配置是否正确。`),
+            };
+        }
+    }
+    return { ok: true, contents };
+}
+// ---------------------------------------------------------------------------
+// 特殊块提取与提示
+// ---------------------------------------------------------------------------
+/**
+ * 从块列表中提取图片块（block_type=27）和画板块（block_type=43）。
+ */
+export function extractSpecialBlocks(blocks) {
+    return {
+        imageBlocks: blocks.filter(b => b.block_type === BLOCK_TYPE_IMAGE),
+        whiteboardBlocks: blocks.filter(b => b.block_type === BLOCK_TYPE_WHITEBOARD),
+    };
+}
+/**
+ * 构建特殊块的 JSON 提示对象，用于展开合并到 JSON 响应中。
+ */
+export function buildSpecialBlockHints(imageBlocks, whiteboardBlocks) {
+    const hints = {};
+    if (imageBlocks.length > 0) {
+        hints.imageBlocksInfo = {
+            count: imageBlocks.length,
+            blockIds: imageBlocks.map(b => b.block_id),
+            reminder: '检测到图片块已创建！请使用 upload_and_bind_image_to_block 工具上传图片并绑定到对应的块ID。',
+        };
+    }
+    if (whiteboardBlocks.length > 0) {
+        hints.whiteboardBlocksInfo = {
+            count: whiteboardBlocks.length,
+            blocks: whiteboardBlocks.map(b => ({
+                blockId: b.block_id,
+                token: b.board?.token,
+                align: b.board?.align,
+            })),
+            reminder: '检测到画板块已创建！请使用 fill_whiteboard_with_plantuml 工具填充画板内容，使用返回的 token 作为 whiteboardId 参数。支持 PlantUML (syntax_type: "plantuml") 和 Mermaid (syntax_type: "mermaid") 两种格式。',
+        };
+    }
+    return hints;
+}
+/**
+ * 构建文本形式的特殊块提示，追加到现有响应文本后。
+ */
+export function appendSpecialBlockTextHints(base, imageBlocks, whiteboardBlocks) {
+    const sections = [base];
+    if (imageBlocks.length > 0) {
+        const lines = [
+            `\n\n🖼️ 检测到 ${imageBlocks.length} 个图片块 (block_type: 27)！`,
+            '💡 提示：如需查看图片内容，可使用 get_feishu_image_resource 工具下载图片。',
+            '图片信息:',
+            ...imageBlocks.map((b, idx) => {
+                const parts = [`  ${idx + 1}. 块ID: ${b.block_id}`];
+                if (b.image?.token)
+                    parts.push(`媒体ID: ${b.image.token}`);
+                return parts.join('，');
+            }),
+            '📝 注意：只有在需要查看图片内容时才调用上述工具，仅了解文档结构时无需获取。',
+        ];
+        sections.push(lines.join('\n'));
+    }
+    if (whiteboardBlocks.length > 0) {
+        const lines = [
+            `\n\n⚠️ 检测到 ${whiteboardBlocks.length} 个画板块 (block_type: 43)！`,
+            '💡 提示：如需获取画板具体内容，可使用 get_feishu_whiteboard_content 工具。',
+            '画板信息:',
+            ...whiteboardBlocks.map((b, idx) => {
+                const parts = [`  ${idx + 1}. 块ID: ${b.block_id}`];
+                if (b.board?.token)
+                    parts.push(`画板ID: ${b.board.token}`);
+                return parts.join('，');
+            }),
+            '📝 注意：只有在需要分析画板内容时才调用上述工具，仅了解文档结构时无需获取。',
+        ];
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('');
+}
+/**
+ * 从飞书 API 抛出的错误对象中提取结构化错误信息。
+ * 飞书 API 错误可能包含 apiError.code / apiError.msg / apiError.log_id 等字段。
+ */
+export function extractFeishuApiError(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        const apiError = e.apiError;
+        if (apiError && apiError.code !== undefined && apiError.msg) {
+            return {
+                message: String(apiError.msg),
+                code: Number(apiError.code),
+                logId: apiError.log_id != null ? String(apiError.log_id) : undefined,
+            };
+        }
+        if (typeof e.err === 'string')
+            return { message: e.err };
+        if (typeof e.message === 'string')
+            return { message: e.message };
+    }
+    return { message: formatErrorMessage(err) };
+}

package/dist/modules/index.js

@@ -0,0 +1,5 @@
+export { ModuleRegistry } from './ModuleRegistry.js';
+export { documentModule } from './document/index.js';
+export { taskModule } from './task/index.js';
+export { calendarModule } from './calendar/index.js';
+export { memberModule } from './member/index.js';

package/dist/modules/member/index.js

@@ -0,0 +1,11 @@
+import { MODULE_SCOPES } from '../../services/constants/feishuScopes.js';
+import { registerMemberTools } from './tools/memberTools.js';
+export const memberModule = {
+    id: 'member',
+    name: '飞书成员',
+    description: '通过用户名关键词搜索用户，返回头像、部门、open_id 等，用于任务指派（1 个工具）',
+    requiredScopes: MODULE_SCOPES.member,
+    registerTools(server, apiService) {
+        registerMemberTools(server, apiService);
+    },
+};

package/dist/modules/member/services/FeishuMemberService.js

@@ -0,0 +1,41 @@
+import { FeishuBaseApiService } from '../../../services/feishu/FeishuBaseApiService.js';
+import { Logger } from '../../../utils/logger.js';
+const PAGE_SIZE = 200;
+/**
+ * 飞书成员搜索 API 服务
+ * 封装飞书搜索用户接口（/search/v1/user）、批量获取用户（/contact/v3/users/batch）
+ */
+export class FeishuMemberService extends FeishuBaseApiService {
+    constructor(authService) {
+        super(authService);
+    }
+    /**
+     * 通过用户名关键词搜索用户
+     * 返回用户头像、用户名、部门、open_id、user_id 等
+     * @param query 搜索关键词
+     * @param pageToken 分页 token
+     */
+    async searchUsers(query, pageToken) {
+        Logger.info(`搜索用户，关键词: ${query}`);
+        const params = {
+            query,
+            page_size: PAGE_SIZE,
+        };
+        if (pageToken)
+            params.page_token = pageToken;
+        return this.get('/search/v1/user', params);
+    }
+    /**
+     * 批量获取用户信息（通讯录）
+     * GET /contact/v3/users/batch，返回用户 ID、名称、邮箱、手机、状态、部门等基本信息。
+     * 权限：contact:contact.base:readonly。单次最多 50 个 user_id。
+     */
+    async batchGetUsers(userIds, userIdType = 'open_id') {
+        Logger.info(`批量获取用户，数量: ${userIds.length}, user_id_type: ${userIdType}`);
+        const qs = new URLSearchParams();
+        userIds.forEach((id) => qs.append('user_ids', id));
+        qs.set('user_id_type', userIdType);
+        const res = await this.get(`/contact/v3/users/batch?${qs.toString()}`, {});
+        return res ?? { items: [] };
+    }
+}

package/dist/modules/member/toolApi/index.js

@@ -0,0 +1 @@
+export { getUsers } from './memberToolApi.js';