feishu-mcp 0.0.5 → 0.0.7

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}`);
+}

package/dist/utils/logger.js

@@ -0,0 +1,257 @@
+/**
+ * 日志级别枚举
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["LOG"] = 2] = "LOG";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+    LogLevel[LogLevel["NONE"] = 5] = "NONE";
+})(LogLevel || (LogLevel = {}));
+// 导入文件系统模块
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * 增强的日志管理器类
+ * 提供可配置的日志记录功能，支持不同日志级别和格式化
+ */
+export class Logger {
+    /**
+     * 配置日志管理器
+     * @param config 日志配置项
+     */
+    static configure(config) {
+        this.config = { ...this.config, ...config };
+        // 确保日志目录存在
+        if (this.config.logToFile) {
+            const logDir = path.dirname(this.config.logFilePath);
+            if (!fs.existsSync(logDir)) {
+                fs.mkdirSync(logDir, { recursive: true });
+            }
+        }
+    }
+    /**
+     * 格式化日志消息
+     * @param level 日志级别
+     * @param args 日志参数
+     * @returns 格式化后的日志字符串数组
+     */
+    static formatLogMessage(level, args) {
+        const result = [];
+        // 添加时间戳
+        if (this.config.showTimestamp) {
+            const now = new Date();
+            const timestamp = this.formatDate(now, this.config.timestampFormat || 'yyyy-MM-dd HH:mm:ss.SSS');
+            result.push(`[${timestamp}]`);
+        }
+        // 添加日志级别
+        if (this.config.showLevel) {
+            const levelStr = LogLevel[level].padEnd(5, ' ');
+            result.push(`[${levelStr}]`);
+        }
+        // 添加原始日志内容
+        return [...result, ...args];
+    }
+    /**
+     * 将日志写入文件
+     * @param logParts 日志内容部分
+     */
+    static writeToFile(logParts) {
+        if (!this.config.logToFile)
+            return;
+        try {
+            // 将日志内容转换为字符串
+            let logString = '';
+            for (const part of logParts) {
+                if (typeof part === 'object') {
+                    try {
+                        // 简化对象序列化
+                        logString += this.safeStringify(part) + ' ';
+                    }
+                    catch (e) {
+                        logString += '[Object] ';
+                    }
+                }
+                else {
+                    logString += part + ' ';
+                }
+            }
+            // 添加换行符
+            logString += '\n';
+            // 以追加模式写入文件
+            fs.appendFileSync(this.config.logFilePath, logString);
+        }
+        catch (error) {
+            console.error('写入日志文件失败:', error);
+        }
+    }
+    /**
+     * 安全的对象序列化，限制深度和长度
+     * @param obj 要序列化的对象
+     * @returns 序列化后的字符串
+     */
+    static safeStringify(obj) {
+        const seen = new Set();
+        const stringified = JSON.stringify(obj, (key, value) => {
+            // 处理循环引用
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    return '[Circular]';
+                }
+                seen.add(value);
+            }
+            // 处理请求/响应对象
+            if (key === 'request' || key === 'socket' || key === 'agent' ||
+                key === '_events' || key === '_eventsCount' || key === '_maxListeners' ||
+                key === 'rawHeaders' || key === 'rawTrailers') {
+                return '[Object]';
+            }
+            return value;
+        }, 2);
+        if (stringified && stringified.length > this.config.maxObjectStringLength) {
+            return stringified.substring(0, this.config.maxObjectStringLength) + '... [截断]';
+        }
+        return stringified;
+    }
+    /**
+     * 格式化日期
+     * @param date 日期对象
+     * @param format 格式字符串
+     * @returns 格式化后的日期字符串
+     */
+    static formatDate(date, format) {
+        const year = date.getFullYear().toString();
+        const month = (date.getMonth() + 1).toString().padStart(2, '0');
+        const day = date.getDate().toString().padStart(2, '0');
+        const hours = date.getHours().toString().padStart(2, '0');
+        const minutes = date.getMinutes().toString().padStart(2, '0');
+        const seconds = date.getSeconds().toString().padStart(2, '0');
+        const milliseconds = date.getMilliseconds().toString().padStart(3, '0');
+        return format
+            .replace('yyyy', year)
+            .replace('MM', month)
+            .replace('dd', day)
+            .replace('HH', hours)
+            .replace('mm', minutes)
+            .replace('ss', seconds)
+            .replace('SSS', milliseconds);
+    }
+    /**
+     * 记录调试级别日志
+     * @param args 日志参数
+     */
+    static debug(...args) {
+        if (this.config.minLevel <= LogLevel.DEBUG) {
+            const formattedMessage = this.formatLogMessage(LogLevel.DEBUG, args);
+            console.debug(...formattedMessage);
+            this.writeToFile(formattedMessage);
+        }
+    }
+    /**
+     * 记录信息级别日志
+     * @param args 日志参数
+     */
+    static info(...args) {
+        if (this.config.minLevel <= LogLevel.INFO) {
+            const formattedMessage = this.formatLogMessage(LogLevel.INFO, args);
+            console.info(...formattedMessage);
+            this.writeToFile(formattedMessage);
+        }
+    }
+    /**
+     * 记录普通级别日志
+     * @param args 日志参数
+     */
+    static log(...args) {
+        if (this.config.minLevel <= LogLevel.LOG) {
+            const formattedMessage = this.formatLogMessage(LogLevel.LOG, args);
+            console.log(...formattedMessage);
+            this.writeToFile(formattedMessage);
+        }
+    }
+    /**
+     * 记录警告级别日志
+     * @param args 日志参数
+     */
+    static warn(...args) {
+        if (this.config.minLevel <= LogLevel.WARN) {
+            const formattedMessage = this.formatLogMessage(LogLevel.WARN, args);
+            console.warn(...formattedMessage);
+            this.writeToFile(formattedMessage);
+        }
+    }
+    /**
+     * 记录错误级别日志
+     * @param args 日志参数
+     */
+    static error(...args) {
+        if (this.config.minLevel <= LogLevel.ERROR) {
+            const formattedMessage = this.formatLogMessage(LogLevel.ERROR, args);
+            console.error(...formattedMessage);
+            this.writeToFile(formattedMessage);
+        }
+    }
+    /**
+     * 记录请求和响应的详细信息
+     * @param method 请求方法
+     * @param url 请求URL
+     * @param data 请求数据
+     * @param response 响应数据
+     * @param statusCode 响应状态码
+     */
+    static logApiCall(method, url, data, response, statusCode) {
+        if (this.config.minLevel <= LogLevel.DEBUG) {
+            this.debug('API调用详情:');
+            this.debug(`请求: ${method} ${url}`);
+            // 简化请求数据记录
+            if (data) {
+                try {
+                    if (typeof data === 'string') {
+                        // 尝试解析JSON字符串
+                        const parsedData = JSON.parse(data);
+                        this.debug('请求数据:', parsedData);
+                    }
+                    else {
+                        this.debug('请求数据:', data);
+                    }
+                }
+                catch (e) {
+                    this.debug('请求数据:', data);
+                }
+            }
+            else {
+                this.debug('请求数据: None');
+            }
+            this.debug(`响应状态: ${statusCode}`);
+            // 简化响应数据记录
+            if (response) {
+                // 只记录关键信息
+                const simplifiedResponse = response.data ? { data: response.data } : response;
+                this.debug('响应数据:', simplifiedResponse);
+            }
+            else {
+                this.debug('响应数据: None');
+            }
+        }
+        else {
+            this.info(`API调用: ${method} ${url} - 状态码: ${statusCode}`);
+        }
+    }
+}
+Object.defineProperty(Logger, "config", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: {
+        minLevel: LogLevel.DEBUG, // 修改为DEBUG级别，确保捕获所有日志
+        showTimestamp: true,
+        showLevel: true,
+        timestampFormat: 'yyyy-MM-dd HH:mm:ss.SSS',
+        logToFile: false,
+        logFilePath: 'log/log.txt',
+        maxObjectDepth: 2, // 限制对象序列化深度
+        maxObjectStringLength: 5000000 // 限制序列化后字符串长度
+    }
+});

package/dist/utils/paramUtils.js

@@ -0,0 +1,193 @@
+import { normalizeDocumentId, normalizeWikiToken } from './document.js';
+import { Logger } from './logger.js';
+import { formatErrorMessage } from './error.js';
+/**
+ * 参数验证错误
+ */
+export class ParamValidationError extends Error {
+    constructor(param, message) {
+        super(message);
+        Object.defineProperty(this, "param", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'ParamValidationError';
+        this.param = param;
+    }
+}
+/**
+ * 参数处理工具类
+ * 提供参数验证、转换和处理功能
+ */
+export class ParamUtils {
+    /**
+     * 处理文档ID参数
+     * 验证并规范化文档ID
+     *
+     * @param documentId 文档ID或URL
+     * @returns 规范化的文档ID
+     * @throws 如果文档ID无效则抛出错误
+     */
+    static processDocumentId(documentId) {
+        if (!documentId) {
+            throw new ParamValidationError('documentId', '文档ID不能为空');
+        }
+        try {
+            return normalizeDocumentId(documentId);
+        }
+        catch (error) {
+            throw new ParamValidationError('documentId', formatErrorMessage(error));
+        }
+    }
+    /**
+     * 处理Wiki Token参数
+     * 验证并规范化Wiki Token
+     *
+     * @param wikiUrl Wiki URL或Token
+     * @returns 规范化的Wiki Token
+     * @throws 如果Wiki Token无效则抛出错误
+     */
+    static processWikiToken(wikiUrl) {
+        if (!wikiUrl) {
+            throw new ParamValidationError('wikiUrl', 'Wiki URL不能为空');
+        }
+        try {
+            return normalizeWikiToken(wikiUrl);
+        }
+        catch (error) {
+            throw new ParamValidationError('wikiUrl', formatErrorMessage(error));
+        }
+    }
+    /**
+     * 处理块ID参数
+     * 验证块ID是否有效
+     *
+     * @param blockId 块ID
+     * @returns 验证后的块ID
+     * @throws 如果块ID无效则抛出错误
+     */
+    static processBlockId(blockId) {
+        if (!blockId) {
+            throw new ParamValidationError('blockId', '块ID不能为空');
+        }
+        if (!/^[a-zA-Z0-9_-]{5,}$/.test(blockId)) {
+            throw new ParamValidationError('blockId', '块ID格式无效');
+        }
+        return blockId;
+    }
+    /**
+     * 处理父块ID参数
+     * 验证父块ID是否有效
+     *
+     * @param parentBlockId 父块ID
+     * @returns 验证后的父块ID
+     * @throws 如果父块ID无效则抛出错误
+     */
+    static processParentBlockId(parentBlockId) {
+        if (!parentBlockId) {
+            throw new ParamValidationError('parentBlockId', '父块ID不能为空');
+        }
+        if (!/^[a-zA-Z0-9_-]{5,}$/.test(parentBlockId)) {
+            throw new ParamValidationError('parentBlockId', '父块ID格式无效');
+        }
+        return parentBlockId;
+    }
+    /**
+     * 处理插入位置索引参数
+     * 验证并规范化索引值
+     *
+     * @param index 插入位置索引
+     * @returns 验证后的索引值
+     * @throws 如果索引无效则抛出错误
+     */
+    static processIndex(index) {
+        if (index === undefined || index === null) {
+            return 0; // 默认值
+        }
+        if (!Number.isInteger(index) || index < 0) {
+            throw new ParamValidationError('index', '索引必须是非负整数');
+        }
+        return index;
+    }
+    /**
+     * 处理对齐方式参数
+     * 验证并规范化对齐方式值
+     *
+     * @param align 对齐方式
+     * @returns 验证后的对齐方式值
+     */
+    static processAlign(align) {
+        if (align === undefined || align === null) {
+            return 1; // 默认左对齐
+        }
+        if (![1, 2, 3].includes(align)) {
+            Logger.warn(`对齐方式值 ${align} 无效，使用默认值1（左对齐）`);
+            return 1;
+        }
+        return align;
+    }
+    /**
+     * 处理语言类型参数
+     * 验证并规范化语言类型值
+     *
+     * @param language 语言类型
+     * @returns 验证后的语言类型值
+     */
+    static processLanguage(language) {
+        if (language === undefined || language === null) {
+            return 1; // 默认纯文本
+        }
+        if (!Number.isInteger(language) || language < 1 || language > 71) {
+            Logger.warn(`语言类型值 ${language} 无效，使用默认值1（纯文本）`);
+            return 1;
+        }
+        return language;
+    }
+    /**
+     * 处理标题级别参数
+     * 验证并规范化标题级别值
+     *
+     * @param level 标题级别
+     * @returns 验证后的标题级别值
+     */
+    static processHeadingLevel(level) {
+        if (level === undefined || level === null) {
+            return 1; // 默认一级标题
+        }
+        // 限制在1-9范围内
+        return Math.max(1, Math.min(9, level));
+    }
+    /**
+     * 批量处理通用参数
+     * 验证并规范化常用参数集
+     *
+     * @param params 通用参数对象
+     * @returns 处理后的参数对象
+     */
+    static processCommonParams(params) {
+        const result = { ...params };
+        // 处理文档ID
+        if (params.documentId) {
+            result.documentId = ParamUtils.processDocumentId(params.documentId);
+        }
+        // 处理块ID
+        if (params.blockId) {
+            result.blockId = ParamUtils.processBlockId(params.blockId);
+        }
+        // 处理父块ID
+        if (params.parentBlockId) {
+            result.parentBlockId = ParamUtils.processParentBlockId(params.parentBlockId);
+        }
+        // 处理索引
+        if (params.index !== undefined) {
+            result.index = ParamUtils.processIndex(params.index);
+        }
+        // 处理起始索引
+        if (params.startIndex !== undefined) {
+            result.startIndex = ParamUtils.processIndex(params.startIndex);
+        }
+        return result;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-mcp",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Model Context Protocol server for Feishu integration",
   "type": "module",
   "main": "dist/index.js",