feishu-mcp 0.0.6 → 0.0.8

package/dist/utils/config.js

@@ -0,0 +1,363 @@
+import { config as loadDotEnv } from 'dotenv';
+import { hideBin } from 'yargs/helpers';
+import yargs from 'yargs';
+import { Logger, LogLevel } from './logger.js';
+/**
+ * 配置来源枚举
+ */
+export var ConfigSource;
+(function (ConfigSource) {
+    ConfigSource["DEFAULT"] = "default";
+    ConfigSource["ENV"] = "env";
+    ConfigSource["CLI"] = "cli";
+    ConfigSource["FILE"] = "file";
+})(ConfigSource || (ConfigSource = {}));
+/**
+ * 应用配置管理类
+ * 统一管理所有配置，支持环境变量、命令行参数和默认值
+ */
+export class Config {
+    /**
+     * 私有构造函数，用于单例模式
+     */
+    constructor() {
+        Object.defineProperty(this, "server", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "feishu", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "log", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "configSources", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // 确保在任何配置读取前加载.env文件
+        loadDotEnv();
+        // 解析命令行参数
+        const argv = this.parseCommandLineArgs();
+        // 初始化配置来源记录
+        this.configSources = {};
+        // 配置服务器
+        this.server = this.initServerConfig(argv);
+        // 配置飞书
+        this.feishu = this.initFeishuConfig(argv);
+        // 配置日志
+        this.log = this.initLogConfig(argv);
+        // 配置缓存
+        this.cache = this.initCacheConfig(argv);
+    }
+    /**
+     * 获取配置单例
+     * @returns 配置实例
+     */
+    static getInstance() {
+        if (!Config.instance) {
+            Config.instance = new Config();
+        }
+        return Config.instance;
+    }
+    /**
+     * 解析命令行参数
+     * @returns 解析后的参数对象
+     */
+    parseCommandLineArgs() {
+        return yargs(hideBin(process.argv))
+            .options({
+            port: {
+                type: 'number',
+                description: '服务器监听端口'
+            },
+            'log-level': {
+                type: 'string',
+                description: '日志级别 (debug, info, log, warn, error, none)'
+            },
+            'feishu-app-id': {
+                type: 'string',
+                description: '飞书应用ID'
+            },
+            'feishu-app-secret': {
+                type: 'string',
+                description: '飞书应用密钥'
+            },
+            'feishu-base-url': {
+                type: 'string',
+                description: '飞书API基础URL'
+            },
+            'cache-enabled': {
+                type: 'boolean',
+                description: '是否启用缓存'
+            },
+            'cache-ttl': {
+                type: 'number',
+                description: '缓存生存时间（秒）'
+            }
+        })
+            .help()
+            .parseSync();
+    }
+    /**
+     * 初始化服务器配置
+     * @param argv 命令行参数
+     * @returns 服务器配置
+     */
+    initServerConfig(argv) {
+        const serverConfig = {
+            port: 3333,
+        };
+        // 处理PORT
+        if (argv.port) {
+            serverConfig.port = argv.port;
+            this.configSources['server.port'] = ConfigSource.CLI;
+        }
+        else if (process.env.PORT) {
+            serverConfig.port = parseInt(process.env.PORT, 10);
+            this.configSources['server.port'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['server.port'] = ConfigSource.DEFAULT;
+        }
+        return serverConfig;
+    }
+    /**
+     * 初始化飞书配置
+     * @param argv 命令行参数
+     * @returns 飞书配置
+     */
+    initFeishuConfig(argv) {
+        const feishuConfig = {
+            appId: '',
+            appSecret: '',
+            baseUrl: 'https://open.feishu.cn/open-apis',
+            tokenLifetime: 7200000 // 2小时，单位：毫秒
+        };
+        // 处理App ID
+        if (argv['feishu-app-id']) {
+            feishuConfig.appId = argv['feishu-app-id'];
+            this.configSources['feishu.appId'] = ConfigSource.CLI;
+        }
+        else if (process.env.FEISHU_APP_ID) {
+            feishuConfig.appId = process.env.FEISHU_APP_ID;
+            this.configSources['feishu.appId'] = ConfigSource.ENV;
+        }
+        // 处理App Secret
+        if (argv['feishu-app-secret']) {
+            feishuConfig.appSecret = argv['feishu-app-secret'];
+            this.configSources['feishu.appSecret'] = ConfigSource.CLI;
+        }
+        else if (process.env.FEISHU_APP_SECRET) {
+            feishuConfig.appSecret = process.env.FEISHU_APP_SECRET;
+            this.configSources['feishu.appSecret'] = ConfigSource.ENV;
+        }
+        // 处理Base URL
+        if (argv['feishu-base-url']) {
+            feishuConfig.baseUrl = argv['feishu-base-url'];
+            this.configSources['feishu.baseUrl'] = ConfigSource.CLI;
+        }
+        else if (process.env.FEISHU_BASE_URL) {
+            feishuConfig.baseUrl = process.env.FEISHU_BASE_URL;
+            this.configSources['feishu.baseUrl'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['feishu.baseUrl'] = ConfigSource.DEFAULT;
+        }
+        // 处理token生命周期
+        if (process.env.FEISHU_TOKEN_LIFETIME) {
+            feishuConfig.tokenLifetime = parseInt(process.env.FEISHU_TOKEN_LIFETIME, 10) * 1000;
+            this.configSources['feishu.tokenLifetime'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['feishu.tokenLifetime'] = ConfigSource.DEFAULT;
+        }
+        return feishuConfig;
+    }
+    /**
+     * 初始化日志配置
+     * @param argv 命令行参数
+     * @returns 日志配置
+     */
+    initLogConfig(argv) {
+        const logConfig = {
+            level: LogLevel.INFO,
+            showTimestamp: true,
+            showLevel: true,
+            timestampFormat: 'yyyy-MM-dd HH:mm:ss.SSS'
+        };
+        // 处理日志级别
+        if (argv['log-level']) {
+            logConfig.level = this.getLogLevelFromString(argv['log-level']);
+            this.configSources['log.level'] = ConfigSource.CLI;
+        }
+        else if (process.env.LOG_LEVEL) {
+            logConfig.level = this.getLogLevelFromString(process.env.LOG_LEVEL);
+            this.configSources['log.level'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['log.level'] = ConfigSource.DEFAULT;
+        }
+        // 处理时间戳显示
+        if (process.env.LOG_SHOW_TIMESTAMP) {
+            logConfig.showTimestamp = process.env.LOG_SHOW_TIMESTAMP.toLowerCase() === 'true';
+            this.configSources['log.showTimestamp'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['log.showTimestamp'] = ConfigSource.DEFAULT;
+        }
+        // 处理级别显示
+        if (process.env.LOG_SHOW_LEVEL) {
+            logConfig.showLevel = process.env.LOG_SHOW_LEVEL.toLowerCase() === 'true';
+            this.configSources['log.showLevel'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['log.showLevel'] = ConfigSource.DEFAULT;
+        }
+        // 处理时间戳格式
+        if (process.env.LOG_TIMESTAMP_FORMAT) {
+            logConfig.timestampFormat = process.env.LOG_TIMESTAMP_FORMAT;
+            this.configSources['log.timestampFormat'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['log.timestampFormat'] = ConfigSource.DEFAULT;
+        }
+        return logConfig;
+    }
+    /**
+     * 初始化缓存配置
+     * @param argv 命令行参数
+     * @returns 缓存配置
+     */
+    initCacheConfig(argv) {
+        const cacheConfig = {
+            enabled: true,
+            ttl: 300, // 5分钟，单位：秒
+            maxSize: 100
+        };
+        // 处理缓存启用
+        if (argv['cache-enabled'] !== undefined) {
+            cacheConfig.enabled = argv['cache-enabled'];
+            this.configSources['cache.enabled'] = ConfigSource.CLI;
+        }
+        else if (process.env.CACHE_ENABLED) {
+            cacheConfig.enabled = process.env.CACHE_ENABLED.toLowerCase() === 'true';
+            this.configSources['cache.enabled'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['cache.enabled'] = ConfigSource.DEFAULT;
+        }
+        // 处理TTL
+        if (argv['cache-ttl']) {
+            cacheConfig.ttl = argv['cache-ttl'];
+            this.configSources['cache.ttl'] = ConfigSource.CLI;
+        }
+        else if (process.env.CACHE_TTL) {
+            cacheConfig.ttl = parseInt(process.env.CACHE_TTL, 10);
+            this.configSources['cache.ttl'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['cache.ttl'] = ConfigSource.DEFAULT;
+        }
+        // 处理最大缓存大小
+        if (process.env.CACHE_MAX_SIZE) {
+            cacheConfig.maxSize = parseInt(process.env.CACHE_MAX_SIZE, 10);
+            this.configSources['cache.maxSize'] = ConfigSource.ENV;
+        }
+        else {
+            this.configSources['cache.maxSize'] = ConfigSource.DEFAULT;
+        }
+        return cacheConfig;
+    }
+    /**
+     * 从字符串获取日志级别
+     * @param levelStr 日志级别字符串
+     * @returns 日志级别枚举值
+     */
+    getLogLevelFromString(levelStr) {
+        switch (levelStr.toLowerCase()) {
+            case 'debug': return LogLevel.DEBUG;
+            case 'info': return LogLevel.INFO;
+            case 'log': return LogLevel.LOG;
+            case 'warn': return LogLevel.WARN;
+            case 'error': return LogLevel.ERROR;
+            case 'none': return LogLevel.NONE;
+            default: return LogLevel.INFO;
+        }
+    }
+    /**
+     * 打印当前配置信息
+     * @param isStdioMode 是否在stdio模式下
+     */
+    printConfig(isStdioMode = false) {
+        if (isStdioMode)
+            return;
+        Logger.info('当前配置:');
+        Logger.info('服务器配置:');
+        Logger.info(`- 端口: ${this.server.port} (来源: ${this.configSources['server.port']})`);
+        Logger.info('飞书配置:');
+        if (this.feishu.appId) {
+            Logger.info(`- App ID: ${this.maskApiKey(this.feishu.appId)} (来源: ${this.configSources['feishu.appId']})`);
+        }
+        if (this.feishu.appSecret) {
+            Logger.info(`- App Secret: ${this.maskApiKey(this.feishu.appSecret)} (来源: ${this.configSources['feishu.appSecret']})`);
+        }
+        Logger.info(`- API URL: ${this.feishu.baseUrl} (来源: ${this.configSources['feishu.baseUrl']})`);
+        Logger.info(`- Token生命周期: ${this.feishu.tokenLifetime / 1000}秒 (来源: ${this.configSources['feishu.tokenLifetime']})`);
+        Logger.info('日志配置:');
+        Logger.info(`- 日志级别: ${LogLevel[this.log.level]} (来源: ${this.configSources['log.level']})`);
+        Logger.info(`- 显示时间戳: ${this.log.showTimestamp} (来源: ${this.configSources['log.showTimestamp']})`);
+        Logger.info(`- 显示日志级别: ${this.log.showLevel} (来源: ${this.configSources['log.showLevel']})`);
+        Logger.info('缓存配置:');
+        Logger.info(`- 启用缓存: ${this.cache.enabled} (来源: ${this.configSources['cache.enabled']})`);
+        Logger.info(`- 缓存TTL: ${this.cache.ttl}秒 (来源: ${this.configSources['cache.ttl']})`);
+        Logger.info(`- 最大缓存条目: ${this.cache.maxSize} (来源: ${this.configSources['cache.maxSize']})`);
+    }
+    /**
+     * 掩盖API密钥
+     * @param key API密钥
+     * @returns 掩盖后的密钥字符串
+     */
+    maskApiKey(key) {
+        if (!key || key.length <= 4)
+            return '****';
+        return `${key.substring(0, 2)}****${key.substring(key.length - 2)}`;
+    }
+    /**
+     * 验证配置是否完整有效
+     * @returns 是否验证成功
+     */
+    validate() {
+        // 验证服务器配置
+        if (!this.server.port || this.server.port <= 0) {
+            Logger.error('无效的服务器端口配置');
+            return false;
+        }
+        // 验证飞书配置
+        if (!this.feishu.appId) {
+            Logger.error('缺少飞书应用ID，请通过环境变量FEISHU_APP_ID或命令行参数--feishu-app-id提供');
+            return false;
+        }
+        if (!this.feishu.appSecret) {
+            Logger.error('缺少飞书应用Secret，请通过环境变量FEISHU_APP_SECRET或命令行参数--feishu-app-secret提供');
+            return false;
+        }
+        return true;
+    }
+}

package/dist/utils/document.js

@@ -0,0 +1,112 @@
+/**
+ * 从URL或ID中提取飞书文档ID
+ * 支持多种格式:
+ * 1. 标准文档URL: https://xxx.feishu.cn/docs/xxx 或 https://xxx.feishu.cn/docx/xxx
+ * 2. API URL: https://open.feishu.cn/open-apis/docx/v1/documents/xxx
+ * 3. 直接ID: JcKbdlokYoPIe0xDzJ1cduRXnRf
+ *
+ * @param input 文档URL或ID
+ * @returns 提取的文档ID或null
+ */
+export function extractDocumentId(input) {
+    // 移除首尾空白
+    input = input.trim();
+    // 处理各种URL格式
+    const docxMatch = input.match(/\/docx\/([a-zA-Z0-9_-]+)/i);
+    const docsMatch = input.match(/\/docs\/([a-zA-Z0-9_-]+)/i);
+    const apiMatch = input.match(/\/documents\/([a-zA-Z0-9_-]+)/i);
+    const directIdMatch = input.match(/^([a-zA-Z0-9_-]{10,})$/); // 假设ID至少10个字符
+    // 按优先级返回匹配结果
+    const match = docxMatch || docsMatch || apiMatch || directIdMatch;
+    return match ? match[1] : null;
+}
+/**
+ * 从URL或Token中提取Wiki节点ID
+ * 支持多种格式:
+ * 1. Wiki URL: https://xxx.feishu.cn/wiki/xxx
+ * 2. 直接Token: xxx
+ *
+ * @param input Wiki URL或Token
+ * @returns 提取的Wiki Token或null
+ */
+export function extractWikiToken(input) {
+    // 移除首尾空白
+    input = input.trim();
+    // 处理Wiki URL格式
+    const wikiMatch = input.match(/\/wiki\/([a-zA-Z0-9_-]+)/i);
+    const directMatch = input.match(/^([a-zA-Z0-9_-]{10,})$/); // 假设Token至少10个字符
+    // 提取Token，如果存在查询参数，去掉它们
+    let token = wikiMatch ? wikiMatch[1] : (directMatch ? directMatch[1] : null);
+    if (token && token.includes('?')) {
+        token = token.split('?')[0];
+    }
+    return token;
+}
+/**
+ * 规范化文档ID
+ * 提取输入中的文档ID，如果提取失败则返回原输入
+ *
+ * @param input 文档URL或ID
+ * @returns 规范化的文档ID
+ * @throws 如果无法提取有效ID则抛出错误
+ */
+export function normalizeDocumentId(input) {
+    const id = extractDocumentId(input);
+    if (!id) {
+        throw new Error(`无法从 "${input}" 提取有效的文档ID`);
+    }
+    return id;
+}
+/**
+ * 规范化Wiki Token
+ * 提取输入中的Wiki Token，如果提取失败则返回原输入
+ *
+ * @param input Wiki URL或Token
+ * @returns 规范化的Wiki Token
+ * @throws 如果无法提取有效Token则抛出错误
+ */
+export function normalizeWikiToken(input) {
+    const token = extractWikiToken(input);
+    if (!token) {
+        throw new Error(`无法从 "${input}" 提取有效的Wiki Token`);
+    }
+    return token;
+}
+/**
+ * 根据图片二进制数据检测MIME类型
+ * @param buffer 图片二进制数据
+ * @returns MIME类型字符串
+ */
+export function detectMimeType(buffer) {
+    // 简单的图片格式检测，根据文件头进行判断
+    if (buffer.length < 4) {
+        return 'application/octet-stream';
+    }
+    // JPEG格式
+    if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    // PNG格式
+    else if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    // GIF格式
+    else if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) {
+        return 'image/gif';
+    }
+    // SVG格式 - 检查字符串前缀
+    else if (buffer.length > 5 && buffer.toString('ascii', 0, 5).toLowerCase() === '<?xml' ||
+        buffer.toString('ascii', 0, 4).toLowerCase() === '<svg') {
+        return 'image/svg+xml';
+    }
+    // WebP格式
+    else if (buffer.length > 12 &&
+        buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    // 默认二进制流
+    else {
+        return 'application/octet-stream';
+    }
+}

package/dist/utils/error.js

@@ -0,0 +1,154 @@
+import { Logger } from './logger.js';
+/**
+ * 错误排查指南映射
+ */
+const errorGuides = {
+    // 飞书API标准错误码
+    '1770002': '资源未找到。请检查文档ID/块ID是否正确，并确保您有权限访问该资源。',
+    '1770001': '权限不足。请确保应用有足够的权限访问此资源。',
+    '1770003': '内部服务错误。请稍后重试。',
+    '1770004': '参数格式错误。请检查API请求参数是否正确。',
+    '1770005': '请求频率限制。请减少请求频率后重试。',
+    '1770006': '操作冲突。可能有其他用户正在编辑同一资源。',
+    '1770007': '资源已被删除。请检查资源是否存在。',
+    '1770008': '资源已被归档。请检查资源状态。',
+    '1770015': '文档或文件夹已被移动。请使用新的位置访问。',
+    // 身份验证和通用错误
+    '99991671': '飞书应用身份验证失败。请检查App ID和App Secret是否正确，或者重新注册飞书应用。',
+    '99991663': '权限不足。请确保：\n1. 应用已获得正确的权限范围\n2. 文档已与应用共享\n3. 您有访问该文档的权限',
+    '99991672': '请求频率超过限制。请稍后再试或优化代码减少请求次数。',
+    '99991661': '资源不存在。请检查文档ID/块ID是否正确，并确保资源仍然存在。',
+    '99991648': '文档ID格式不正确。请检查ID格式，应为标准飞书文档ID、URL或Token。',
+    'token_invalid': '访问令牌无效。请尝试刷新访问令牌。',
+    'invalid_token': '访问令牌无效。请尝试刷新访问令牌。',
+    '404': '资源未找到。请检查URL或ID是否正确。',
+    '403': '访问被拒绝。请检查权限设置并确保您有足够的访问权限。',
+    '401': '未授权。请检查认证凭据或尝试重新获取访问令牌。',
+    '400': '请求参数有误。请检查提供的参数格式和值是否正确。',
+    '500': '服务器内部错误。请稍后重试或联系飞书支持团队。'
+};
+/**
+ * 格式化错误消息
+ * 对飞书API各种错误响应格式进行统一处理
+ *
+ * @param error 原始错误
+ * @param context 错误上下文（可选）
+ * @returns 格式化的错误消息
+ */
+export function formatErrorMessage(error, context) {
+    try {
+        // 预处理错误对象
+        if (!error) {
+            return '发生未知错误';
+        }
+        // 确定错误类型
+        let errorCode;
+        let errorMsg = '';
+        let fieldViolations = [];
+        let troubleshooter = '';
+        let logId = '';
+        // 处理飞书API标准错误格式
+        if (error.apiError) {
+            const apiError = error.apiError;
+            errorCode = apiError.code;
+            errorMsg = apiError.msg || '';
+            if (apiError.error) {
+                fieldViolations = apiError.error.field_violations || [];
+                troubleshooter = apiError.error.troubleshooter || '';
+                logId = apiError.error.log_id || '';
+            }
+        }
+        // 处理直接包含code和msg的格式
+        else if (error.code !== undefined && error.msg !== undefined) {
+            errorCode = error.code;
+            errorMsg = error.msg;
+            if (error.error) {
+                fieldViolations = error.error.field_violations || [];
+                troubleshooter = error.error.troubleshooter || '';
+                logId = error.error.log_id || '';
+            }
+        }
+        // 处理HTTP类错误
+        else if (error.status) {
+            errorCode = error.status;
+            errorMsg = error.statusText || error.err || '请求失败';
+        }
+        // 处理标准Error对象
+        else if (error instanceof Error) {
+            errorMsg = error.message;
+        }
+        // 处理字符串错误
+        else if (typeof error === 'string') {
+            errorMsg = error;
+        }
+        // 处理其他对象类型的错误
+        else if (typeof error === 'object') {
+            errorMsg = error.message || error.error || JSON.stringify(error);
+        }
+        // 构建基本错误消息
+        let formattedMessage = '';
+        if (context) {
+            formattedMessage += `${context}: `;
+        }
+        if (errorCode !== undefined) {
+            formattedMessage += `${errorMsg} (错误码: ${errorCode})`;
+        }
+        else {
+            formattedMessage += errorMsg;
+        }
+        // 添加日志ID
+        if (logId) {
+            formattedMessage += `\n日志ID: ${logId}`;
+        }
+        // 添加字段验证错误信息
+        if (fieldViolations && fieldViolations.length > 0) {
+            formattedMessage += '\n字段验证错误:';
+            fieldViolations.forEach((violation) => {
+                let detail = `\n - ${violation.field}`;
+                if (violation.description) {
+                    detail += `: ${violation.description}`;
+                }
+                if (violation.value !== undefined) {
+                    detail += `，提供的值: ${violation.value}`;
+                }
+                formattedMessage += detail;
+            });
+        }
+        // 添加排查建议
+        if (troubleshooter) {
+            formattedMessage += `\n\n排查建议:\n${troubleshooter}`;
+        }
+        else {
+            // 尝试添加预定义的错误指南
+            const errorCodeStr = String(errorCode);
+            if (errorGuides[errorCodeStr]) {
+                formattedMessage += `\n\n排查建议:\n${errorGuides[errorCodeStr]}`;
+            }
+            else {
+                // 如果没有精确匹配，尝试通过错误消息内容模糊匹配
+                for (const [key, guide] of Object.entries(errorGuides)) {
+                    if (errorMsg.toLowerCase().includes(key.toLowerCase())) {
+                        formattedMessage += `\n\n排查建议:\n${guide}`;
+                        break;
+                    }
+                }
+            }
+        }
+        return formattedMessage;
+    }
+    catch (e) {
+        Logger.error("格式化错误消息时发生错误:", e);
+        return typeof error === 'string' ? error : '发生未知错误';
+    }
+}
+/**
+ * 包装错误为标准格式
+ *
+ * @param message 错误消息前缀
+ * @param originalError 原始错误
+ * @returns 包装后的错误对象
+ */
+export function wrapError(message, originalError) {
+    const errorMessage = formatErrorMessage(originalError);
+    return new Error(`${message}: ${errorMessage}`);
+}