feishu-mcp 0.1.6 → 0.1.7

package/dist/mcp/tools/feishuBlockTools.js

@@ -12,7 +12,7 @@ BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema,
 // MermaidCodeSchema,
 // ImageWidthSchema,
 // ImageHeightSchema
-TableCreateSchema } from '../../types/feishuSchema.js';
+TableCreateSchema, WhiteboardFillArraySchema } from '../../types/feishuSchema.js';
 /**
  * 注册飞书块相关的MCP工具
  * @param server MCP服务器实例
@@ -47,7 +47,7 @@ export function registerFeishuBlockTools(server, feishuService) {
         }
     });
     // 添加通用飞书块创建工具（支持文本、代码、标题）
-    server.tool('batch_create_feishu_blocks', 'PREFERRED: Efficiently creates multiple blocks (text, code, heading, list) in a single API call. USE THIS TOOL when creating multiple consecutive blocks at the same position - reduces API calls by up to 90%. KEY FEATURES: (1) Handles any number of blocks by auto-batching large requests (>50 blocks), (2) Creates blocks at consecutive positions in a document, (3) Supports direct heading level format (e.g. "heading1", "heading2") or standard "heading" type with level in options. CORRECT FORMAT: mcp_feishu_batch_create_feishu_blocks({documentId:"doc123",parentBlockId:"para123",startIndex:0,blocks:[{blockType:"text",options:{...}},{blockType:"heading1",options:{heading:{content:"Title"}}}]}). For separate positions, use individual block creation tools instead. For wiki links (https://xxx.feishu.cn/wiki/xxx), first convert with convert_feishu_wiki_to_document_id tool.', {
+    server.tool('batch_create_feishu_blocks', 'PREFERRED: Efficiently creates multiple blocks (text, code, heading, list, image, mermaid, whiteboard) in a single API call. USE THIS TOOL when creating multiple consecutive blocks at the same position - reduces API calls by up to 90%. KEY FEATURES: (1) Handles any number of blocks by auto-batching large requests (>50 blocks), (2) Creates blocks at consecutive positions in a document, (3) Supports direct heading level format (e.g. "heading1", "heading2") or standard "heading" type with level in options. CORRECT FORMAT: mcp_feishu_batch_create_feishu_blocks({documentId:"doc123",parentBlockId:"para123",startIndex:0,blocks:[{blockType:"text",options:{...}},{blockType:"heading1",options:{heading:{content:"Title"}}}]}). For whiteboard blocks, use blockType:"whiteboard" with options:{whiteboard:{align:1}}. After creating a whiteboard block, you will receive a token in the response (board.token field) which can be used with fill_whiteboard_with_plantuml tool. The fill_whiteboard_with_plantuml tool supports both PlantUML (syntax_type: 1) and Mermaid (syntax_type: 2) formats. For separate positions, use individual block creation tools instead. For wiki links (https://xxx.feishu.cn/wiki/xxx), first convert with convert_feishu_wiki_to_document_id tool.', {
         documentId: DocumentIdSchema,
         parentBlockId: ParentBlockIdSchema,
         index: IndexSchema,
@@ -110,6 +110,9 @@ export function registerFeishuBlockTools(server, feishuService) {
                 // 检查是否有图片块（block_type=27）
                 const imageBlocks = result.children?.filter((child) => child.block_type === 27) || [];
                 const hasImageBlocks = imageBlocks.length > 0;
+                // 检查是否有画板块（block_type=43）
+                const whiteboardBlocks = result.children?.filter((child) => child.block_type === 43) || [];
+                const hasWhiteboardBlocks = whiteboardBlocks.length > 0;
                 const responseData = {
                     ...result,
                     nextIndex: index + blockContents.length,
@@ -120,6 +123,17 @@ export function registerFeishuBlockTools(server, feishuService) {
                             blockIds: imageBlocks.map((block) => block.block_id),
                             reminder: "检测到图片块已创建！请使用 upload_and_bind_image_to_block 工具上传图片并绑定到对应的块ID。"
                         }
+                    }),
+                    ...(hasWhiteboardBlocks && {
+                        whiteboardBlocksInfo: {
+                            count: whiteboardBlocks.length,
+                            blocks: whiteboardBlocks.map((block) => ({
+                                blockId: block.block_id,
+                                token: block.board?.token,
+                                align: block.board?.align
+                            })),
+                            reminder: "检测到画板块已创建！请使用 fill_whiteboard_with_plantuml 工具填充画板内容，使用返回的 token 作为 whiteboardId 参数。支持 PlantUML (syntax_type: 1) 和 Mermaid (syntax_type: 2) 两种格式。"
+                        }
                     })
                 };
                 return {
@@ -201,12 +215,26 @@ export function registerFeishuBlockTools(server, feishuService) {
                         allImageBlocks.push(...imageBlocks);
                     });
                     const hasImageBlocks = allImageBlocks.length > 0;
-                    const responseText = `所有飞书块创建成功，共分 ${totalBatches} 批创建了 ${createdBlocksCount} 个块。\n\n` +
+                    // 检查所有批次中是否有画板块（block_type=43）
+                    const allWhiteboardBlocks = [];
+                    results.forEach(batchResult => {
+                        const whiteboardBlocks = batchResult.children?.filter((child) => child.block_type === 43) || [];
+                        allWhiteboardBlocks.push(...whiteboardBlocks);
+                    });
+                    const hasWhiteboardBlocks = allWhiteboardBlocks.length > 0;
+                    let responseText = `所有飞书块创建成功，共分 ${totalBatches} 批创建了 ${createdBlocksCount} 个块。\n\n` +
                         `最后一批结果: ${JSON.stringify(results[results.length - 1], null, 2)}\n\n` +
-                        `下一个索引位置: ${currentStartIndex}，总创建块数: ${createdBlocksCount}` +
-                        (hasImageBlocks ? `\n\n⚠️ 检测到 ${allImageBlocks.length} 个图片块已创建！\n` +
+                        `下一个索引位置: ${currentStartIndex}，总创建块数: ${createdBlocksCount}`;
+                    if (hasImageBlocks) {
+                        responseText += `\n\n⚠️ 检测到 ${allImageBlocks.length} 个图片块已创建！\n` +
                             `图片块IDs: ${allImageBlocks.map(block => block.block_id).join(', ')}\n` +
-                            `请使用 upload_and_bind_image_to_block 工具上传图片并绑定到对应的块ID。` : '');
+                            `请使用 upload_and_bind_image_to_block 工具上传图片并绑定到对应的块ID。`;
+                    }
+                    if (hasWhiteboardBlocks) {
+                        responseText += `\n\n⚠️ 检测到 ${allWhiteboardBlocks.length} 个画板块已创建！\n` +
+                            `画板块信息:\n${allWhiteboardBlocks.map((block) => `  - blockId: ${block.block_id}, token: ${block.board?.token || 'N/A'}\n`).join('')}` +
+                            `请使用 fill_whiteboard_with_plantuml 工具填充画板内容，使用返回的 token 作为 whiteboardId 参数。支持 PlantUML (syntax_type: 1) 和 Mermaid (syntax_type: 2) 两种格式。`;
+                    }
                     return {
                         content: [
                             {
@@ -659,4 +687,97 @@ export function registerFeishuBlockTools(server, feishuService) {
             };
         }
     });
+    // 添加批量填充画板工具（支持 PlantUML 和 Mermaid）
+    server.tool('fill_whiteboard_with_plantuml', 'Batch fills multiple whiteboard blocks with diagram content (PlantUML or Mermaid). Use this tool after creating whiteboard blocks with batch_create_feishu_blocks tool. Each item in the array should contain whiteboardId (the token from board.token field), code and syntax_type. Supports both PlantUML (syntax_type: 1) and Mermaid (syntax_type: 2) formats. Returns detailed results including which whiteboards were filled successfully and which failed, along with failure reasons. The same whiteboard can be filled multiple times.', {
+        whiteboards: WhiteboardFillArraySchema,
+    }, async ({ whiteboards }) => {
+        try {
+            if (!feishuService) {
+                return {
+                    content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                };
+            }
+            if (!whiteboards || whiteboards.length === 0) {
+                return {
+                    content: [{ type: 'text', text: '错误：画板数组不能为空' }],
+                };
+            }
+            Logger.info(`开始批量填充画板内容，共 ${whiteboards.length} 个画板`);
+            const results = [];
+            let successCount = 0;
+            let failCount = 0;
+            // 逐个处理每个画板
+            for (let i = 0; i < whiteboards.length; i++) {
+                const item = whiteboards[i];
+                const { whiteboardId, code, syntax_type } = item;
+                const syntaxTypeName = syntax_type === 1 ? 'PlantUML' : 'Mermaid';
+                Logger.info(`处理第 ${i + 1}/${whiteboards.length} 个画板，画板ID: ${whiteboardId}，语法类型: ${syntaxTypeName}`);
+                try {
+                    const result = await feishuService.createDiagramNode(whiteboardId, code, syntax_type);
+                    Logger.info(`画板填充成功，画板ID: ${whiteboardId}`);
+                    successCount++;
+                    results.push({
+                        whiteboardId: whiteboardId,
+                        syntaxType: syntaxTypeName,
+                        status: 'success',
+                        nodeId: result.node_id,
+                        result: result
+                    });
+                }
+                catch (error) {
+                    Logger.error(`画板填充失败，画板ID: ${whiteboardId}`, error);
+                    failCount++;
+                    // 提取详细的错误信息
+                    let errorMessage = formatErrorMessage(error);
+                    let errorCode;
+                    let logId;
+                    if (error?.apiError) {
+                        const apiError = error.apiError;
+                        if (apiError.code !== undefined && apiError.msg) {
+                            errorCode = apiError.code;
+                            errorMessage = apiError.msg;
+                            if (apiError.log_id) {
+                                logId = apiError.log_id;
+                            }
+                        }
+                    }
+                    else if (error?.err) {
+                        errorMessage = error.err;
+                    }
+                    else if (error?.message) {
+                        errorMessage = error.message;
+                    }
+                    results.push({
+                        whiteboardId: whiteboardId,
+                        syntaxType: syntaxTypeName,
+                        status: 'failed',
+                        error: {
+                            message: errorMessage,
+                            code: errorCode,
+                            logId: logId,
+                            details: error
+                        }
+                    });
+                }
+            }
+            // 构建返回结果
+            const summary = {
+                total: whiteboards.length,
+                success: successCount,
+                failed: failCount,
+                results: results
+            };
+            Logger.info(`批量填充画板完成，成功: ${successCount}，失败: ${failCount}`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+            };
+        }
+        catch (error) {
+            Logger.error(`批量填充画板内容失败:`, error);
+            const errorMessage = formatErrorMessage(error);
+            return {
+                content: [{ type: 'text', text: `批量填充画板内容失败: ${errorMessage}\n\n错误详情: ${JSON.stringify(error, null, 2)}` }],
+            };
+        }
+    });
 }

package/dist/services/baseService.js

@@ -1,7 +1,7 @@
 import axios, { AxiosError } from 'axios';
 import FormData from 'form-data';
 import { Logger } from '../utils/logger.js';
-import { formatErrorMessage, AuthRequiredError } from '../utils/error.js';
+import { formatErrorMessage, AuthRequiredError, ScopeInsufficientError } from '../utils/error.js';
 import { Config } from '../utils/config.js';
 import { TokenCacheManager, UserContextManager, AuthUtils } from '../utils/auth/index.js';
 /**
@@ -126,6 +126,10 @@ export class BaseApiService {
         }
         catch (error) {
             const config = Config.getInstance().feishu;
+            // 优先处理权限不足异常
+            if (error instanceof ScopeInsufficientError) {
+                return this.handleScopeInsufficientError(error);
+            }
             // 处理授权异常
             if (error instanceof AuthRequiredError) {
                 return this.handleAuthFailure(config.authType === "tenant", clientKey, baseUrl, userKey);
@@ -212,6 +216,13 @@ export class BaseApiService {
     async delete(endpoint, data, needsAuth = true) {
         return this.request(endpoint, 'DELETE', data, needsAuth);
     }
+    /**
+     * 处理权限不足异常
+     * @param error 权限不足错误
+     */
+    handleScopeInsufficientError(error) {
+        throw error;
+    }
     /**
      * 处理认证失败
      * @param tenant 是否是tenant
@@ -300,7 +311,7 @@ export class BaseApiService {
         const { appId, appSecret } = Config.getInstance().feishu;
         const clientKey = AuthUtils.generateClientKey(userKey);
         const redirect_uri = `${baseUrl}/callback`;
-        const scope = encodeURIComponent('base:app:read bitable:app bitable:app:readonly board:whiteboard:node:read contact:user.employee_id:readonly docs:document.content:read docx:document docx:document.block:convert 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 offline_access');
+        const scope = encodeURIComponent('base:app:read bitable:app bitable:app:readonly board:whiteboard:node:read board:whiteboard:node:create contact:user.employee_id:readonly docs:document.content:read docx:document docx:document.block:convert 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 offline_access');
         const state = AuthUtils.encodeState(appId, appSecret, clientKey, redirect_uri);
         return `https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=${appId}&redirect_uri=${encodeURIComponent(redirect_uri)}&scope=${scope}&state=${state}`;
     }

package/dist/services/blockFactory.js

@@ -10,6 +10,7 @@ export var BlockType;
     BlockType["LIST"] = "list";
     BlockType["IMAGE"] = "image";
     BlockType["MERMAID"] = "mermaid";
+    BlockType["WHITEBOARD"] = "whiteboard";
 })(BlockType || (BlockType = {}));
 /**
  * 对齐方式枚举
@@ -78,6 +79,8 @@ export class BlockFactory {
                 return this.createImageBlock(options);
             case BlockType.MERMAID:
                 return this.createMermaidBlock(options);
+            case BlockType.WHITEBOARD:
+                return this.createWhiteboardBlock(options);
             default:
                 Logger.error(`不支持的块类型: ${type}`);
                 throw new Error(`不支持的块类型: ${type}`);
@@ -246,6 +249,20 @@ export class BlockFactory {
             },
         };
     }
+    /**
+     * 创建画板块内容（空画板块，需要后续填充内容）
+     * @param options 画板块选项
+     * @returns 画板块内容对象
+     */
+    createWhiteboardBlock(options = {}) {
+        const { align = AlignType.CENTER } = options;
+        return {
+            block_type: 43, // 43表示画板块
+            board: {
+                align: align // 1 居左，2 居中，3 居右
+            }
+        };
+    }
     /**
      * 创建表格块
      * @param options 表格块选项

package/dist/services/feishuApiService.js

@@ -6,6 +6,7 @@ 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';
@@ -84,13 +85,229 @@ 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"
+        ];
+        const userScopes = [
+            ...tenantScopes,
+            'offline_access'
+        ];
+        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 = '1.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)}`);
         }
     }
     /**
@@ -745,6 +962,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 +1047,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;
             }
             // 记录调试信息
@@ -1162,6 +1402,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

package/dist/types/feishuSchema.js

@@ -103,9 +103,10 @@ export const ListBlockSchema = z.object({
     align: AlignSchemaWithValidation,
 });
 // 块类型枚举 - 用于批量创建块工具
-export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', 'image','mermaid',as well as 'heading1' through 'heading9'. " +
+export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', 'image','mermaid','whiteboard',as well as 'heading1' through 'heading9'. " +
     "For headings, we recommend using 'heading' with level property, but 'heading1'-'heading9' are also supported. " +
     "For images, use 'image' to create empty image blocks that can be filled later. " +
+    "For whiteboards, use 'whiteboard' to create empty whiteboard blocks that return a token for filling content. " +
     "For text blocks, you can include both regular text and equation elements in the same block.");
 // 图片宽度参数定义
 export const ImageWidthSchema = z.number().optional().describe('Image width in pixels (optional). If not provided, the original image width will be used.');
@@ -124,6 +125,12 @@ export const MermaidCodeSchema = z.string().describe('Mermaid code (required). T
 export const MermaidBlockSchema = z.object({
     code: MermaidCodeSchema,
 });
+// 画板对齐方式参数定义
+export const WhiteboardAlignSchema = z.number().optional().default(2).describe('Whiteboard alignment: 1 for left, 2 for center (default), 3 for right.');
+// 画板块内容定义 - 用于批量创建块工具
+export const WhiteboardBlockSchema = z.object({
+    align: WhiteboardAlignSchema,
+});
 // 块配置定义 - 用于批量创建块工具
 export const BlockConfigSchema = z.object({
     blockType: BlockTypeEnum,
@@ -134,6 +141,7 @@ export const BlockConfigSchema = z.object({
         z.object({ list: ListBlockSchema }).describe("List block options. Used when blockType is 'list'."),
         z.object({ image: ImageBlockSchema }).describe("Image block options. Used when blockType is 'image'. Creates empty image blocks."),
         z.object({ mermaid: MermaidBlockSchema }).describe("Mermaid block options.  Used when blockType is 'mermaid'."),
+        z.object({ whiteboard: WhiteboardBlockSchema }).describe("Whiteboard block options. Used when blockType is 'whiteboard'. Creates empty whiteboard blocks that return a token for filling content."),
         z.record(z.any()).describe("Fallback for any other block options")
     ]).describe('Options for the specific block type. Provide the corresponding options object based on blockType.'),
 });
@@ -196,5 +204,26 @@ export const ImagesArraySchema = z.array(z.object({
 export const WhiteboardIdSchema = z.string().describe('Whiteboard ID (required). This is the token value from the board.token field when getting document blocks.\n' +
     'When you find a block with block_type: 43, the whiteboard ID is located in board.token field.\n' +
     'Example: "EPJKwvY5ghe3pVbKj9RcT2msnBX"');
+// 画板代码参数定义（支持 PlantUML 和 Mermaid）
+export const WhiteboardCodeSchema = z.string().describe('Diagram code (required). The complete diagram code to create in the whiteboard.\n' +
+    'Supports both PlantUML and Mermaid formats.\n' +
+    'PlantUML example: "@startuml\nAlice -> Bob: Hello\n@enduml"\n' +
+    'Mermaid example: "graph TD\nA[Start] --> B[End]"');
+// 语法类型参数定义
+export const SyntaxTypeSchema = z.number().describe('Syntax type (required). Specifies the diagram syntax format.\n' +
+    '1: PlantUML syntax\n' +
+    '2: Mermaid syntax');
+// 画板内容配置定义（包含画板ID和内容配置）
+export const WhiteboardContentSchema = z.object({
+    whiteboardId: WhiteboardIdSchema,
+    code: WhiteboardCodeSchema,
+    syntax_type: SyntaxTypeSchema,
+}).describe('Whiteboard content configuration. Contains the whiteboard ID, diagram code and syntax type.\n' +
+    'whiteboardId: The token value from board.token field when creating whiteboard block (required)\n' +
+    'code: The diagram code (PlantUML or Mermaid format) (required)\n' +
+    'syntax_type: 1 for PlantUML, 2 for Mermaid (required)');
+// 批量填充画板数组定义
+export const WhiteboardFillArraySchema = z.array(WhiteboardContentSchema).describe('Array of whiteboard fill items (required). Each item must include whiteboardId, code and syntax_type.\n' +
+    'Example: [{whiteboardId:"token1", code:"@startuml...", syntax_type:1}, {whiteboardId:"token2", code:"graph TD...", syntax_type:2}]');
 // 文档标题参数定义
 export const DocumentTitleSchema = z.string().describe('Document title (required). This will be displayed in the Feishu document list and document header.');