@jsonstudio/llms 0.4.2

package/dist/utils/error-utils.js

@@ -0,0 +1,782 @@
+/**
+ * 错误处理工具函数
+ */
+/**
+ * LLMSwitch错误类型
+ */
+export var LLMSwitchErrorType;
+(function (LLMSwitchErrorType) {
+    // 请求相关错误
+    LLMSwitchErrorType["VALIDATION_ERROR"] = "validation_error";
+    LLMSwitchErrorType["INVALID_REQUEST_FORMAT"] = "invalid_request_format";
+    LLMSwitchErrorType["MISSING_REQUIRED_FIELD"] = "missing_required_field";
+    // 处理相关错误
+    LLMSwitchErrorType["PROCESSING_ERROR"] = "processing_error";
+    LLMSwitchErrorType["HOOK_EXECUTION_ERROR"] = "hook_execution_error";
+    LLMSwitchErrorType["TRANSFORMATION_ERROR"] = "transformation_error";
+    // 网络相关错误
+    LLMSwitchErrorType["NETWORK_ERROR"] = "network_error";
+    LLMSwitchErrorType["TIMEOUT_ERROR"] = "timeout_error";
+    LLMSwitchErrorType["CONNECTION_ERROR"] = "connection_error";
+    // 端点相关错误
+    LLMSwitchErrorType["ENDPOINT_NOT_FOUND"] = "endpoint_not_found";
+    LLMSwitchErrorType["ENDPOINT_UNAVAILABLE"] = "endpoint_unavailable";
+    LLMSwitchErrorType["UNSUPPORTED_PROTOCOL"] = "unsupported_protocol";
+    // 系统相关错误
+    LLMSwitchErrorType["MEMORY_ERROR"] = "memory_error";
+    LLMSwitchErrorType["CONFIGURATION_ERROR"] = "configuration_error";
+    LLMSwitchErrorType["INTERNAL_ERROR"] = "internal_error";
+    // 流式相关错误
+    LLMSwitchErrorType["STREAM_ERROR"] = "stream_error";
+    LLMSwitchErrorType["SSE_ERROR"] = "sse_error";
+})(LLMSwitchErrorType || (LLMSwitchErrorType = {}));
+/**
+ * 错误严重程度
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    ErrorSeverity["LOW"] = "low";
+    ErrorSeverity["MEDIUM"] = "medium";
+    ErrorSeverity["HIGH"] = "high";
+    ErrorSeverity["CRITICAL"] = "critical";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * 错误类型配置映射
+ */
+export const ERROR_TYPE_CONFIG = new Map([
+    // 请求相关错误 - 客户端问题
+    [LLMSwitchErrorType.VALIDATION_ERROR, {
+            severity: ErrorSeverity.LOW,
+            httpStatus: 400,
+            isRetryable: false,
+            defaultMessage: 'Invalid request data'
+        }],
+    [LLMSwitchErrorType.INVALID_REQUEST_FORMAT, {
+            severity: ErrorSeverity.LOW,
+            httpStatus: 400,
+            isRetryable: false,
+            defaultMessage: 'Invalid request format'
+        }],
+    [LLMSwitchErrorType.MISSING_REQUIRED_FIELD, {
+            severity: ErrorSeverity.LOW,
+            httpStatus: 400,
+            isRetryable: false,
+            defaultMessage: 'Missing required field'
+        }],
+    // 处理相关错误 - 服务端问题
+    [LLMSwitchErrorType.PROCESSING_ERROR, {
+            severity: ErrorSeverity.HIGH,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Request processing failed'
+        }],
+    [LLMSwitchErrorType.HOOK_EXECUTION_ERROR, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Hook execution failed'
+        }],
+    [LLMSwitchErrorType.TRANSFORMATION_ERROR, {
+            severity: ErrorSeverity.HIGH,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Data transformation failed'
+        }],
+    // 网络相关错误 - 可能重试
+    [LLMSwitchErrorType.NETWORK_ERROR, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 503,
+            isRetryable: true,
+            defaultMessage: 'Network connection failed'
+        }],
+    [LLMSwitchErrorType.TIMEOUT_ERROR, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 408,
+            isRetryable: true,
+            defaultMessage: 'Request timeout'
+        }],
+    [LLMSwitchErrorType.CONNECTION_ERROR, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 503,
+            isRetryable: true,
+            defaultMessage: 'Connection failed'
+        }],
+    // 端点相关错误
+    [LLMSwitchErrorType.ENDPOINT_NOT_FOUND, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 404,
+            isRetryable: false,
+            defaultMessage: 'Endpoint not found'
+        }],
+    [LLMSwitchErrorType.ENDPOINT_UNAVAILABLE, {
+            severity: ErrorSeverity.HIGH,
+            httpStatus: 503,
+            isRetryable: true,
+            defaultMessage: 'Endpoint unavailable'
+        }],
+    [LLMSwitchErrorType.UNSUPPORTED_PROTOCOL, {
+            severity: ErrorSeverity.LOW,
+            httpStatus: 400,
+            isRetryable: false,
+            defaultMessage: 'Unsupported protocol'
+        }],
+    // 系统相关错误 - 严重问题
+    [LLMSwitchErrorType.MEMORY_ERROR, {
+            severity: ErrorSeverity.CRITICAL,
+            httpStatus: 503,
+            isRetryable: true,
+            defaultMessage: 'Insufficient memory'
+        }],
+    [LLMSwitchErrorType.CONFIGURATION_ERROR, {
+            severity: ErrorSeverity.CRITICAL,
+            httpStatus: 500,
+            isRetryable: false,
+            defaultMessage: 'Configuration error'
+        }],
+    [LLMSwitchErrorType.INTERNAL_ERROR, {
+            severity: ErrorSeverity.CRITICAL,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Internal server error'
+        }],
+    // 流式相关错误
+    [LLMSwitchErrorType.STREAM_ERROR, {
+            severity: ErrorSeverity.HIGH,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Stream processing error'
+        }],
+    [LLMSwitchErrorType.SSE_ERROR, {
+            severity: ErrorSeverity.MEDIUM,
+            httpStatus: 500,
+            isRetryable: true,
+            defaultMessage: 'Server-sent events error'
+        }]
+]);
+/**
+ * LLMSwitch自定义错误类
+ */
+export class LLMSwitchError extends Error {
+    type;
+    code;
+    requestId;
+    endpoint;
+    stage;
+    originalError;
+    context;
+    timestamp;
+    severity;
+    httpStatus;
+    isRetryable;
+    constructor(type, message, options = {}) {
+        super(message);
+        this.name = 'LLMSwitchError';
+        this.type = type;
+        this.code = options.code || type;
+        this.requestId = options.requestId;
+        this.endpoint = options.endpoint;
+        this.stage = options.stage;
+        this.originalError = options.originalError;
+        this.context = options.context;
+        this.timestamp = Date.now();
+        // 从配置映射获取错误属性
+        const config = ERROR_TYPE_CONFIG.get(type);
+        if (config) {
+            this.severity = config.severity;
+            this.httpStatus = config.httpStatus;
+            this.isRetryable = config.isRetryable;
+        }
+        else {
+            // 默认配置
+            this.severity = ErrorSeverity.MEDIUM;
+            this.httpStatus = 500;
+            this.isRetryable = false;
+        }
+        // 保持堆栈跟踪
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LLMSwitchError);
+        }
+    }
+    /**
+     * 转换为JSON格式
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type,
+            code: this.code,
+            message: this.message,
+            requestId: this.requestId,
+            endpoint: this.endpoint,
+            stage: this.stage,
+            context: this.context,
+            timestamp: this.timestamp,
+            severity: this.severity,
+            httpStatus: this.httpStatus,
+            isRetryable: this.isRetryable,
+            stack: this.stack,
+            originalError: this.originalError ? {
+                name: this.originalError.name,
+                message: this.originalError.message,
+                stack: this.originalError.stack
+            } : undefined
+        };
+    }
+    /**
+     * 转换为标准HTTP错误响应格式
+     */
+    toErrorResponse() {
+        return {
+            success: false,
+            error: {
+                type: this.type,
+                code: this.code,
+                message: this.message,
+                severity: this.severity,
+                requestId: this.requestId,
+                endpoint: this.endpoint,
+                stage: this.stage,
+                timestamp: this.timestamp,
+                context: this.context
+            }
+        };
+    }
+    /**
+     * 转换为API错误响应格式（兼容旧版本）
+     */
+    toAPIResponse() {
+        return this.toErrorResponse();
+    }
+}
+/**
+ * 错误工厂类
+ */
+export class ErrorFactory {
+    /**
+     * 创建验证错误
+     */
+    static validationError(message, field, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.VALIDATION_ERROR, message, {
+            code: 'validation_failed',
+            context: { field, ...context }
+        });
+    }
+    /**
+     * 创建请求格式错误
+     */
+    static invalidRequestFormat(message, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.INVALID_REQUEST_FORMAT, message, {
+            code: 'invalid_format',
+            context
+        });
+    }
+    /**
+     * 创建缺失字段错误
+     */
+    static missingRequiredField(field, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.MISSING_REQUIRED_FIELD, `Missing required field: ${field}`, {
+            code: 'missing_field',
+            context: { field, ...context }
+        });
+    }
+    /**
+     * 创建处理错误
+     */
+    static processingError(message, originalError, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.PROCESSING_ERROR, message, {
+            code: 'processing_failed',
+            originalError,
+            context
+        });
+    }
+    /**
+     * 创建Hook执行错误
+     */
+    static hookExecutionError(stage, message, originalError, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.HOOK_EXECUTION_ERROR, `Hook execution failed at ${stage}: ${message}`, {
+            code: 'hook_failed',
+            stage,
+            originalError,
+            context
+        });
+    }
+    /**
+     * 创建转换错误
+     */
+    static transformationError(message, fromProtocol, toProtocol, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.TRANSFORMATION_ERROR, message, {
+            code: 'transformation_failed',
+            context: { fromProtocol, toProtocol, ...context }
+        });
+    }
+    /**
+     * 创建网络错误
+     */
+    static networkError(message, url, statusCode, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.NETWORK_ERROR, message, {
+            code: 'network_failed',
+            context: { url, statusCode, ...context }
+        });
+    }
+    /**
+     * 创建超时错误
+     */
+    static timeoutError(operation, timeout, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.TIMEOUT_ERROR, `Operation ${operation} timed out after ${timeout}ms`, {
+            code: 'timeout',
+            context: { operation, timeout, ...context }
+        });
+    }
+    /**
+     * 创建连接错误
+     */
+    static connectionError(message, endpoint, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.CONNECTION_ERROR, message, {
+            code: 'connection_failed',
+            context: { endpoint, ...context }
+        });
+    }
+    /**
+     * 创建端点未找到错误
+     */
+    static endpointNotFound(endpoint, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.ENDPOINT_NOT_FOUND, `Endpoint not found: ${endpoint}`, {
+            code: 'endpoint_not_found',
+            context: { endpoint, ...context }
+        });
+    }
+    /**
+     * 创建端点不可用错误
+     */
+    static endpointUnavailable(endpoint, reason, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.ENDPOINT_UNAVAILABLE, `Endpoint ${endpoint} unavailable${reason ? `: ${reason}` : ''}`, {
+            code: 'endpoint_unavailable',
+            context: { endpoint, reason, ...context }
+        });
+    }
+    /**
+     * 创建不支持的协议错误
+     */
+    static unsupportedProtocol(protocol, supportedProtocols, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.UNSUPPORTED_PROTOCOL, `Unsupported protocol: ${protocol}`, {
+            code: 'unsupported_protocol',
+            context: { protocol, supportedProtocols, ...context }
+        });
+    }
+    /**
+     * 创建内存错误
+     */
+    static memoryError(message, usage, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.MEMORY_ERROR, message, {
+            code: 'memory_error',
+            context: { usage, ...context }
+        });
+    }
+    /**
+     * 创建配置错误
+     */
+    static configurationError(message, configPath, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.CONFIGURATION_ERROR, message, {
+            code: 'configuration_error',
+            context: { configPath, ...context }
+        });
+    }
+    /**
+     * 创建内部错误
+     */
+    static internalError(message, originalError, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.INTERNAL_ERROR, `Internal error: ${message}`, {
+            code: 'internal_error',
+            originalError,
+            context
+        });
+    }
+    /**
+     * 创建流式错误
+     */
+    static streamError(message, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.STREAM_ERROR, message, {
+            code: 'stream_failed',
+            context
+        });
+    }
+    /**
+     * 创建SSE错误
+     */
+    static sseError(message, context) {
+        return new LLMSwitchError(LLMSwitchErrorType.SSE_ERROR, message, {
+            code: 'sse_failed',
+            context
+        });
+    }
+}
+/**
+ * 错误处理器
+ */
+export class ErrorHandler {
+    static errorHandlers = new Map();
+    static errorLog = [];
+    /**
+     * 注册错误处理器
+     */
+    static registerHandler(errorType, handler) {
+        this.errorHandlers.set(errorType, handler);
+    }
+    /**
+     * 处理错误
+     */
+    static handle(error, context) {
+        let llmswitchError;
+        if (error instanceof LLMSwitchError) {
+            llmswitchError = error;
+        }
+        else {
+            // 转换普通错误为LLMSwitchError
+            llmswitchError = new LLMSwitchError(LLMSwitchErrorType.INTERNAL_ERROR, error.message, {
+                originalError: error,
+                ...context
+            });
+        }
+        // 添加上下文信息
+        if (context) {
+            if (context.requestId && !llmswitchError.requestId) {
+                llmswitchError.requestId = context.requestId;
+            }
+            if (context.endpoint && !llmswitchError.endpoint) {
+                llmswitchError.endpoint = context.endpoint;
+            }
+            if (context.stage && !llmswitchError.stage) {
+                llmswitchError.stage = context.stage;
+            }
+        }
+        // 记录错误
+        this.logError(llmswitchError);
+        // 执行注册的错误处理器
+        const handler = this.errorHandlers.get(llmswitchError.type);
+        if (handler) {
+            try {
+                handler(llmswitchError);
+            }
+            catch (handlerError) {
+                console.error('Error handler failed:', handlerError);
+            }
+        }
+        return llmswitchError;
+    }
+    /**
+     * 记录错误
+     */
+    static logError(error) {
+        this.errorLog.push({
+            error,
+            timestamp: Date.now()
+        });
+        // 保持最近1000个错误记录
+        if (this.errorLog.length > 1000) {
+            this.errorLog = this.errorLog.slice(-1000);
+        }
+        // 输出到控制台
+        console.error(`[${new Date().toISOString()}] LLMSwitchError:`, {
+            type: error.type,
+            code: error.code,
+            message: error.message,
+            requestId: error.requestId,
+            endpoint: error.endpoint,
+            stage: error.stage,
+            context: error.context
+        });
+    }
+    /**
+     * 获取错误日志
+     */
+    static getErrorLog(filter) {
+        let log = this.errorLog;
+        if (filter) {
+            if (filter.errorType) {
+                log = log.filter(entry => entry.error.type === filter.errorType);
+            }
+            if (filter.since) {
+                log = log.filter(entry => entry.timestamp >= filter.since);
+            }
+            if (filter.requestId) {
+                log = log.filter(entry => entry.error.requestId === filter.requestId);
+            }
+            if (filter.endpoint) {
+                log = log.filter(entry => entry.error.endpoint === filter.endpoint);
+            }
+        }
+        return log;
+    }
+    /**
+     * 获取错误统计
+     */
+    static getErrorStats() {
+        const byType = {};
+        const byEndpoint = {};
+        const byStage = {};
+        for (const entry of this.errorLog) {
+            // 按类型统计
+            byType[entry.error.type] = (byType[entry.error.type] || 0) + 1;
+            // 按端点统计
+            if (entry.error.endpoint) {
+                byEndpoint[entry.error.endpoint] = (byEndpoint[entry.error.endpoint] || 0) + 1;
+            }
+            // 按阶段统计
+            if (entry.error.stage) {
+                byStage[entry.error.stage] = (byStage[entry.error.stage] || 0) + 1;
+            }
+        }
+        return {
+            total: this.errorLog.length,
+            byType,
+            byEndpoint,
+            byStage,
+            recentErrors: this.errorLog.slice(-10) // 最近10个错误
+        };
+    }
+    /**
+     * 清理错误日志
+     */
+    static clearErrorLog() {
+        this.errorLog = [];
+    }
+    /**
+     * 清理过期错误记录
+     */
+    static cleanup(maxAge = 3600000) {
+        const cutoff = Date.now() - maxAge;
+        this.errorLog = this.errorLog.filter(entry => entry.timestamp >= cutoff);
+    }
+}
+/**
+ * 错误恢复工具
+ */
+export class ErrorRecovery {
+    static recoveryStrategies = new Map();
+    /**
+     * 注册恢复策略
+     */
+    static registerStrategy(errorType, strategy) {
+        this.recoveryStrategies.set(errorType, strategy);
+    }
+    /**
+     * 尝试错误恢复
+     */
+    static async attemptRecovery(error, context) {
+        const strategy = this.recoveryStrategies.get(error.type);
+        if (!strategy) {
+            return { success: false, action: 'no_strategy' };
+        }
+        try {
+            return await strategy.recover(error, context);
+        }
+        catch (recoveryError) {
+            return {
+                success: false,
+                action: 'recovery_failed',
+                error: recoveryError instanceof Error ? recoveryError : new Error('Unknown recovery error')
+            };
+        }
+    }
+    /**
+     * 获取所有恢复策略
+     */
+    static getStrategies() {
+        return new Map(this.recoveryStrategies);
+    }
+}
+/**
+ * 默认恢复策略
+ */
+export class DefaultRecoveryStrategies {
+    /**
+     * 网络错误恢复策略
+     */
+    static networkErrorStrategy = {
+        maxAttempts: 3,
+        canRecover: (error) => error.type === LLMSwitchErrorType.NETWORK_ERROR,
+        recover: async (error, context) => {
+            const attempt = context?.attempt || 1;
+            if (attempt > 3) {
+                return { success: false, action: 'max_attempts_reached' };
+            }
+            // 等待一段时间后重试
+            await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+            return {
+                success: true,
+                action: 'retry',
+                data: { attempt: attempt + 1 }
+            };
+        }
+    };
+    /**
+     * 超时错误恢复策略
+     */
+    static timeoutErrorStrategy = {
+        maxAttempts: 2,
+        canRecover: (error) => error.type === LLMSwitchErrorType.TIMEOUT_ERROR,
+        recover: async (error, context) => {
+            const attempt = context?.attempt || 1;
+            if (attempt > 2) {
+                return { success: false, action: 'max_attempts_reached' };
+            }
+            // 增加超时时间后重试
+            const newTimeout = (context?.timeout || 30000) * 1.5;
+            return {
+                success: true,
+                action: 'retry_with_timeout',
+                data: { attempt: attempt + 1, timeout: newTimeout }
+            };
+        }
+    };
+    /**
+     * 内存错误恢复策略
+     */
+    static memoryErrorStrategy = {
+        canRecover: (error) => error.type === LLMSwitchErrorType.MEMORY_ERROR,
+        recover: async (error, context) => {
+            // 强制垃圾回收
+            if (global.gc) {
+                global.gc();
+            }
+            // 等待一段时间让内存释放
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            return {
+                success: true,
+                action: 'garbage_collection'
+            };
+        }
+    };
+    /**
+     * 注册所有默认策略
+     */
+    static registerAll() {
+        ErrorRecovery.registerStrategy(LLMSwitchErrorType.NETWORK_ERROR, this.networkErrorStrategy);
+        ErrorRecovery.registerStrategy(LLMSwitchErrorType.TIMEOUT_ERROR, this.timeoutErrorStrategy);
+        ErrorRecovery.registerStrategy(LLMSwitchErrorType.MEMORY_ERROR, this.memoryErrorStrategy);
+    }
+}
+// 注册默认恢复策略
+DefaultRecoveryStrategies.registerAll();
+/**
+ * 全局错误响应助手类
+ */
+export class ErrorMapper {
+    /**
+     * 将错误转换为标准HTTP响应
+     */
+    static toHTTPResponse(error, requestId) {
+        let llmswitchError;
+        if (error instanceof LLMSwitchError) {
+            llmswitchError = error;
+        }
+        else {
+            llmswitchError = ErrorHandler.handle(error, { requestId });
+        }
+        const errorResponse = llmswitchError.toErrorResponse();
+        return {
+            statusCode: llmswitchError.httpStatus,
+            body: errorResponse,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Error-Type': llmswitchError.type,
+                'X-Error-Severity': llmswitchError.severity,
+                'X-Request-ID': llmswitchError.requestId || requestId || 'unknown'
+            }
+        };
+    }
+    /**
+     * 发送HTTP错误响应
+     */
+    static sendErrorResponse(res, error, requestId) {
+        const { statusCode, body, headers } = this.toHTTPResponse(error, requestId);
+        // 设置响应头
+        Object.entries(headers).forEach(([key, value]) => {
+            res.setHeader(key, value);
+        });
+        res.writeHead(statusCode);
+        res.end(JSON.stringify(body));
+    }
+}
+/**
+ * 流式错误处理助手
+ */
+export class StreamErrorHandler {
+    /**
+     * 处理流式过程中的错误
+     */
+    static handleStreamError(error, stream, context) {
+        const llmswitchError = ErrorHandler.handle(error, context);
+        // 尝试写入错误事件到流
+        try {
+            if (stream && !stream.destroyed) {
+                const errorEvent = {
+                    type: 'error',
+                    error: llmswitchError.toErrorResponse().error
+                };
+                stream.write(`data: ${JSON.stringify(errorEvent)}\n\n`);
+                // 关闭流
+                stream.end();
+            }
+        }
+        catch (writeError) {
+            console.error('Failed to write error to stream:', writeError);
+        }
+        // 记录错误
+        console.error(`Stream error [${context.requestId}]:`, {
+            error: llmswitchError,
+            context
+        });
+    }
+    /**
+     * 安全地包装流式操作
+     */
+    static async wrapStreamOperation(operation, stream, context) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            this.handleStreamError(error, stream, context);
+            throw error; // 重新抛出以供上层处理
+        }
+    }
+}
+/**
+ * 安全JSON解析助手
+ */
+export class SafeJSONParser {
+    /**
+     * 安全解析JSON，失败时抛出结构化错误
+     */
+    static parse(jsonString, context) {
+        try {
+            return JSON.parse(jsonString);
+        }
+        catch (error) {
+            const errorMessage = context.field
+                ? `Invalid JSON in field '${context.field}': ${error.message}`
+                : `Invalid JSON: ${error.message}`;
+            throw ErrorHandler.handle(error, {
+                requestId: context.requestId,
+                stage: context.stage || 'json_parsing'
+            });
+        }
+    }
+    /**
+     * 安全字符串化JSON，失败时抛出结构化错误
+     */
+    static stringify(obj, context) {
+        try {
+            return JSON.stringify(obj);
+        }
+        catch (error) {
+            const errorMessage = context.field
+                ? `Failed to serialize field '${context.field}': ${error.message}`
+                : `Failed to serialize object: ${error.message}`;
+            throw ErrorHandler.handle(error, {
+                requestId: context.requestId,
+                stage: context.stage || 'json_stringification'
+            });
+        }
+    }
+}