feishu-mcp 0.2.2 → 0.2.7

package/dist/services/feishu/FeishuFoldService.js

@@ -0,0 +1,187 @@
+import { Logger } from '../../utils/logger.js';
+import { FeishuBaseApiService } from './FeishuBaseApiService.js';
+/**
+ * 飞书文件夹与知识空间服务
+ * 整合云盘文件夹（Drive）和知识空间（Wiki）的查询与创建操作
+ */
+export class FeishuFoldService extends FeishuBaseApiService {
+    constructor(authService) {
+        super(authService);
+    }
+    // ─── 云盘文件夹（Drive）─────────────────────────────────────────
+    /**
+     * 获取当前用户根文件夹的元数据信息
+     * @returns 根文件夹信息，包含 token（文件夹 Token）、id 和 user_id 字段
+     */
+    async getRootFolderInfo() {
+        try {
+            const response = await this.get('/drive/explorer/v2/root_folder/meta');
+            Logger.debug('获取根文件夹信息成功:', response);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取飞书根文件夹信息失败');
+        }
+    }
+    /**
+     * 获取指定文件夹内的文件和子文件夹列表
+     * @param folderToken 目标文件夹的 Token
+     * @param orderBy 排序字段，可选 'EditedTime'（编辑时间）、'CreatedTime'（创建时间）等，默认 'EditedTime'
+     * @param direction 排序方向，'ASC' 升序 / 'DESC' 降序，默认 'DESC'
+     * @returns 文件夹文件清单，包含 files 数组，每项含文件名、类型、token 等信息
+     */
+    async getFolderFileList(folderToken, orderBy = 'EditedTime', direction = 'DESC') {
+        try {
+            const response = await this.get('/drive/v1/files', {
+                folder_token: folderToken,
+                order_by: orderBy,
+                direction
+            });
+            Logger.debug(`获取文件夹(${folderToken})中的文件清单成功，文件数量: ${response.files?.length || 0}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取文件夹中的文件清单失败');
+        }
+    }
+    /**
+     * 在指定文件夹下创建子文件夹
+     * @param folderToken 父文件夹的 Token
+     * @param name 新文件夹的名称
+     * @returns 创建结果，包含新文件夹的 token 和访问 url
+     */
+    async createFolder(folderToken, name) {
+        try {
+            const response = await this.post('/drive/v1/files/create_folder', { folder_token: folderToken, name });
+            Logger.debug(`文件夹创建成功, token: ${response.token}, url: ${response.url}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '创建文件夹失败');
+        }
+    }
+    // ─── 知识空间（Wiki）────────────────────────────────────────────
+    /**
+     * 获取当前用户可见的所有知识空间列表，自动处理分页直到获取全部数据
+     * @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, '创建知识空间节点失败');
+        }
+    }
+}

package/dist/services/feishu/FeishuImageService.js

@@ -0,0 +1,219 @@
+import axios from 'axios';
+import FormData from 'form-data';
+import fs from 'fs';
+import path from 'path';
+import { Logger } from '../../utils/logger.js';
+import { ParamUtils } from '../../utils/paramUtils.js';
+import { FeishuBaseApiService } from './FeishuBaseApiService.js';
+/**
+ * 飞书图片服务
+ * 负责图片的获取、上传和块创建
+ */
+export class FeishuImageService extends FeishuBaseApiService {
+    constructor(authService, blockFactory, blockService) {
+        super(authService);
+        Object.defineProperty(this, "blockFactory", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: blockFactory
+        });
+        Object.defineProperty(this, "blockService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: blockService
+        });
+    }
+    /**
+     * 下载飞书云文档中的图片素材，返回二进制数据
+     * @param mediaId 图片的媒体 ID（media_id / file_token）
+     * @param extra 额外参数，部分场景需要传递（如加密图片），默认为空字符串
+     * @returns 图片的二进制 Buffer 数据
+     */
+    async getImageResource(mediaId, extra = '') {
+        try {
+            Logger.info(`开始获取图片资源，媒体ID: ${mediaId}`);
+            if (!mediaId)
+                throw new Error('媒体ID不能为空');
+            const endpoint = `/drive/v1/medias/${mediaId}/download`;
+            const params = {};
+            if (extra)
+                params.extra = extra;
+            const response = await this.request(endpoint, 'GET', params, true, {}, 'arraybuffer');
+            const imageBuffer = Buffer.from(response);
+            Logger.info(`图片资源获取成功，大小: ${imageBuffer.length} 字节`);
+            return imageBuffer;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取图片资源失败');
+            return Buffer.from([]);
+        }
+    }
+    /**
+     * 将图片素材上传到飞书云端，关联到指定的图片块
+     * @param imageBase64 图片的 Base64 编码字符串（不含 data:image/xxx;base64, 前缀）
+     * @param fileName 图片文件名（含扩展名），若为空字符串则根据 Base64 内容自动检测格式并生成文件名
+     * @param parentBlockId 关联的图片块 ID（parent_node），用于告知飞书该素材归属的块
+     * @returns 上传结果，包含 file_token 字段，用于后续 setImageBlockContent 调用
+     */
+    async uploadImageMedia(imageBase64, fileName, parentBlockId) {
+        try {
+            const endpoint = '/drive/v1/medias/upload_all';
+            const imageBuffer = Buffer.from(imageBase64, 'base64');
+            const imageSize = imageBuffer.length;
+            if (!fileName) {
+                if (imageBase64.startsWith('/9j/')) {
+                    fileName = `image_${Date.now()}.jpg`;
+                }
+                else if (imageBase64.startsWith('iVBORw0KGgo')) {
+                    fileName = `image_${Date.now()}.png`;
+                }
+                else if (imageBase64.startsWith('R0lGODlh')) {
+                    fileName = `image_${Date.now()}.gif`;
+                }
+                else {
+                    fileName = `image_${Date.now()}.png`;
+                }
+            }
+            Logger.info(`开始上传图片素材，文件名: ${fileName}，大小: ${imageSize} 字节，关联块ID: ${parentBlockId}`);
+            if (imageSize > 20 * 1024 * 1024) {
+                Logger.warn(`图片文件过大: ${imageSize} 字节，建议小于20MB`);
+            }
+            const formData = new FormData();
+            formData.append('file', imageBuffer, {
+                filename: fileName,
+                contentType: this.getMimeTypeFromFileName(fileName),
+                knownLength: imageSize
+            });
+            formData.append('file_name', fileName);
+            formData.append('parent_type', 'docx_image');
+            formData.append('parent_node', parentBlockId);
+            formData.append('size', imageSize.toString());
+            const response = await this.post(endpoint, formData);
+            Logger.info(`图片素材上传成功，file_token: ${response.file_token}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '上传图片素材失败');
+        }
+    }
+    /**
+     * 将已上传的图片素材绑定到指定的图片块，完成图片块的最终渲染
+     * @param documentId 文档 ID 或 URL
+     * @param imageBlockId 目标图片块的 block_id
+     * @param fileToken 图片素材的 file_token（由 uploadImageMedia 返回）
+     * @returns 更新结果，包含 document_revision_id 等字段
+     */
+    async setImageBlockContent(documentId, imageBlockId, fileToken) {
+        try {
+            const normalizedDocId = ParamUtils.processDocumentId(documentId);
+            const endpoint = `/docx/v1/documents/${normalizedDocId}/blocks/${imageBlockId}`;
+            const payload = { replace_image: { token: fileToken } };
+            Logger.info(`开始设置图片块内容，文档ID: ${normalizedDocId}，块ID: ${imageBlockId}，file_token: ${fileToken}`);
+            const response = await this.patch(endpoint, payload);
+            Logger.info('图片块内容设置成功');
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '设置图片块内容失败');
+        }
+    }
+    /**
+     * 完整创建图片块的三步流程：创建空块 → 上传素材 → 绑定素材
+     * 支持本地文件路径和 HTTP/HTTPS URL 两种图片来源
+     * @param documentId 文档 ID 或 URL
+     * @param parentBlockId 父块 ID，图片块将插入到该块的子节点列表中
+     * @param imagePathOrUrl 图片来源，支持本地绝对路径或 HTTP/HTTPS URL
+     * @param options 可选配置
+     * @param options.fileName 自定义文件名（含扩展名），不传则从路径/URL 自动提取
+     * @param options.width 图片显示宽度（像素），不传则使用默认值
+     * @param options.height 图片显示高度（像素），不传则使用默认值
+     * @param options.index 插入位置索引，默认 0
+     * @returns 综合结果对象，包含 imageBlockId、fileToken、imageBlock、uploadResult、setContentResult、documentRevisionId
+     */
+    async createImageBlock(documentId, parentBlockId, imagePathOrUrl, options = {}) {
+        try {
+            const { fileName: providedFileName, width, height, index = 0 } = options;
+            Logger.info(`开始创建图片块，文档ID: ${documentId}，父块ID: ${parentBlockId}，图片源: ${imagePathOrUrl}，插入位置: ${index}`);
+            const { base64: imageBase64, fileName: detectedFileName } = await this.getImageBase64FromPathOrUrl(imagePathOrUrl);
+            const finalFileName = providedFileName || detectedFileName;
+            Logger.info('第1步：创建空图片块');
+            const imageBlockContent = this.blockFactory.createImageBlock({ width, height });
+            const createBlockResult = await this.blockService.createDocumentBlock(documentId, parentBlockId, imageBlockContent, index);
+            if (!createBlockResult?.children?.[0]?.block_id) {
+                throw new Error('创建空图片块失败：无法获取块ID');
+            }
+            const imageBlockId = createBlockResult.children[0].block_id;
+            Logger.info(`空图片块创建成功，块ID: ${imageBlockId}`);
+            Logger.info('第2步：上传图片素材');
+            const uploadResult = await this.uploadImageMedia(imageBase64, finalFileName, imageBlockId);
+            if (!uploadResult?.file_token) {
+                throw new Error('上传图片素材失败：无法获取file_token');
+            }
+            Logger.info(`图片素材上传成功，file_token: ${uploadResult.file_token}`);
+            Logger.info('第3步：设置图片块内容');
+            const setContentResult = await this.setImageBlockContent(documentId, imageBlockId, uploadResult.file_token);
+            Logger.info('图片块创建完成');
+            return {
+                imageBlock: createBlockResult.children[0],
+                imageBlockId,
+                fileToken: uploadResult.file_token,
+                uploadResult,
+                setContentResult,
+                documentRevisionId: setContentResult.document_revision_id || createBlockResult.document_revision_id
+            };
+        }
+        catch (error) {
+            this.handleApiError(error, '创建图片块失败');
+        }
+    }
+    getMimeTypeFromFileName(fileName) {
+        const extension = fileName.toLowerCase().split('.').pop();
+        switch (extension) {
+            case 'jpg':
+            case 'jpeg':
+                return 'image/jpeg';
+            case 'png':
+                return 'image/png';
+            case 'gif':
+                return 'image/gif';
+            case 'webp':
+                return 'image/webp';
+            case 'bmp':
+                return 'image/bmp';
+            case 'svg':
+                return 'image/svg+xml';
+            default:
+                return 'image/png';
+        }
+    }
+    async getImageBase64FromPathOrUrl(imagePathOrUrl) {
+        try {
+            let imageBuffer;
+            let fileName;
+            if (imagePathOrUrl.startsWith('http://') || imagePathOrUrl.startsWith('https://')) {
+                Logger.info(`从URL获取图片: ${imagePathOrUrl}`);
+                const response = await axios.get(imagePathOrUrl, { responseType: 'arraybuffer', timeout: 30000 });
+                imageBuffer = Buffer.from(response.data);
+                const urlPath = new URL(imagePathOrUrl).pathname;
+                fileName = path.basename(urlPath) || `image_${Date.now()}.png`;
+                Logger.info(`从URL成功获取图片，大小: ${imageBuffer.length} 字节，文件名: ${fileName}`);
+            }
+            else {
+                Logger.info(`从本地路径读取图片: ${imagePathOrUrl}`);
+                if (!fs.existsSync(imagePathOrUrl)) {
+                    throw new Error(`图片文件不存在: ${imagePathOrUrl}`);
+                }
+                imageBuffer = fs.readFileSync(imagePathOrUrl);
+                fileName = path.basename(imagePathOrUrl);
+                Logger.info(`从本地路径成功读取图片，大小: ${imageBuffer.length} 字节，文件名: ${fileName}`);
+            }
+            return { base64: imageBuffer.toString('base64'), fileName };
+        }
+        catch (error) {
+            Logger.error(`获取图片失败: ${error}`);
+            throw new Error(`获取图片失败: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

package/dist/services/feishu/FeishuScopeValidator.js

@@ -0,0 +1,177 @@
+import axios from 'axios';
+import { Logger } from '../../utils/logger.js';
+import { Config } from '../../utils/config.js';
+import { TokenCacheManager } from '../../utils/auth/tokenCacheManager.js';
+import { ScopeInsufficientError } from '../../utils/error.js';
+import { getRequiredScopes, MODULE_SCOPES } from '../constants/feishuScopes.js';
+import { ModuleRegistry } from '../../modules/ModuleRegistry.js';
+/**
+ * 飞书应用权限 Scope 校验器
+ * 根据已启用的功能模块动态计算所需权限，仅校验最小权限集
+ */
+export class FeishuScopeValidator {
+    async getApplicationScopes(accessToken, authType) {
+        try {
+            const baseUrl = 'https://open.feishu.cn/open-apis';
+            const endpoint = '/application/v6/scopes';
+            const headers = {
+                'Authorization': `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            };
+            Logger.debug('请求应用权限范围:', endpoint);
+            const response = await axios.get(`${baseUrl}${endpoint}`, { headers });
+            const data = response.data;
+            if (data.code !== 0) {
+                throw new Error(`获取应用权限范围失败：${data.msg || '未知错误'} (错误码: ${data.code})`);
+            }
+            const scopes = [];
+            if (data.data && Array.isArray(data.data.scopes)) {
+                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)));
+        }
+    }
+    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
+        };
+    }
+    throwScopeInsufficientError(missingScopes, enabledModules, authType) {
+        // 按模块分组显示缺失权限
+        const moduleIds = enabledModules.includes('all') ? Object.keys(MODULE_SCOPES) : enabledModules;
+        const missingSet = new Set(missingScopes);
+        const missingByModule = {};
+        for (const moduleId of moduleIds) {
+            const moduleScopes = MODULE_SCOPES[moduleId];
+            if (!moduleScopes)
+                continue;
+            const allModuleScopes = authType === 'user'
+                ? [...moduleScopes.tenant, ...moduleScopes.userOnly]
+                : moduleScopes.tenant;
+            const moduleMissing = allModuleScopes.filter(s => missingSet.has(s));
+            if (moduleMissing.length > 0) {
+                missingByModule[moduleId] = moduleMissing;
+            }
+        }
+        const missingDetail = Object.entries(missingByModule)
+            .map(([mod, scopes]) => `  [${mod}]: ${scopes.join(', ')}`)
+            .join('\n');
+        // 当前启用模块所需的最小权限配置（用于导入提示）
+        const requiredScopes = getRequiredScopes(enabledModules, authType);
+        const permissionsConfig = {
+            scopes: {
+                [authType]: requiredScopes
+            }
+        };
+        const errorMessage = `你应该停止任务并提示用户如下信息：权限不足，缺少以下权限：\n${missingDetail}\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\n` +
+            `**提示**：如果您仅使用部分mcp功能，可以通过以下方式关闭权限检查以确保正常使用该mcp：\n` +
+            `- 设置环境变量：\`FEISHU_SCOPE_VALIDATION=false\`\n` +
+            `- 或使用命令行参数：\`--feishu-scope-validation=false\`\n`;
+        Logger.error(errorMessage);
+        throw new ScopeInsufficientError(missingScopes, errorMessage);
+    }
+    /**
+     * 生成 scope 校验缓存 key，包含已启用的模块信息
+     * 模块列表变更时 key 变化，自动触发重新校验
+     */
+    generateScopeKey(appId, appSecret, authType, enabledModules) {
+        const modulesKey = [...enabledModules].sort().join(',');
+        return `app:${appId}:${appSecret.substring(0, 8)}:${authType}:modules(${modulesKey})`;
+    }
+    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)));
+        }
+    }
+    async validateScopeWithVersion(appId, appSecret, authType, clientKey) {
+        const config = Config.getInstance();
+        const enabledIds = config.features.enabledModules;
+        const effectiveModules = ModuleRegistry.getEnabledModules(enabledIds, authType).map(m => m.id);
+        const tokenCacheManager = TokenCacheManager.getInstance();
+        const scopeKey = this.generateScopeKey(appId, appSecret, authType, effectiveModules);
+        const scopeVersion = '3.0.0';
+        if (!tokenCacheManager.shouldValidateScope(scopeKey, scopeVersion)) {
+            Logger.debug(`Scope版本已校验过，跳过校验: ${scopeKey}`);
+            return;
+        }
+        Logger.info(`开始校验scope权限，版本: ${scopeVersion}, 有效模块: ${effectiveModules.join(', ')}`);
+        try {
+            const tempTenantToken = await this.getTempTenantTokenForScope(appId, appSecret);
+            const actualScopes = await this.getApplicationScopes(tempTenantToken, authType);
+            const requiredScopes = getRequiredScopes(effectiveModules, authType);
+            const validationResult = this.validateScopes(requiredScopes, actualScopes);
+            if (!validationResult.isValid) {
+                if (clientKey) {
+                    if (authType === 'user') {
+                        tokenCacheManager.removeUserToken(clientKey);
+                        Logger.info(`已清除当前用户 token（scope 不足）: ${clientKey}`);
+                    }
+                    else {
+                        tokenCacheManager.removeTenantToken(clientKey);
+                        Logger.info(`已清除当前租户 token（scope 不足）: ${clientKey}`);
+                    }
+                }
+                this.throwScopeInsufficientError(validationResult.missingScopes, effectiveModules, authType);
+            }
+            const scopeVersionInfo = {
+                scopeVersion,
+                scopeList: requiredScopes,
+                validatedAt: Math.floor(Date.now() / 1000),
+                validatedVersion: scopeVersion
+            };
+            tokenCacheManager.saveScopeVersionInfo(scopeKey, scopeVersionInfo);
+            Logger.info(`Scope权限校验成功，版本: ${scopeVersion}，共 ${requiredScopes.length} 个权限`);
+        }
+        catch (error) {
+            if (error instanceof ScopeInsufficientError) {
+                throw error;
+            }
+            Logger.warn(`Scope权限校验失败，但继续使用token: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}