@jsonstudio/llms 0.4.2

package/dist/sse/shared/serializers/responses-event-serializer.js

@@ -0,0 +1,356 @@
+/**
+ * Responses协议事件序列化适配器
+ * 将内部ResponsesSseEvent对象转换为真实的SSE wire格式
+ */
+/**
+ * Responses协议SSE事件序列化器
+ * 负责将内部事件对象转换为符合LMStudio/官方SDK习惯的SSE格式
+ */
+export class ResponsesEventSerializer {
+    /**
+     * 将Responses事件序列化为SSE wire格式
+     */
+    serializeToWire(event) {
+        switch (event.type) {
+            case 'response.created':
+                return this.serializeResponseCreated(event);
+            case 'response.in_progress':
+                return this.serializeResponseInProgress(event);
+            case 'response.reasoning_text.delta':
+                return this.serializeReasoningTextDelta(event);
+            case 'response.reasoning_text.done':
+                return this.serializeReasoningTextDone(event);
+            case 'response.content_part.added':
+                return this.serializeContentPartAdded(event);
+            case 'response.content_part.done':
+                return this.serializeContentPartDone(event);
+            case 'response.output_item.added':
+                return this.serializeOutputItemAdded(event);
+            case 'response.output_item.done':
+                return this.serializeOutputItemDone(event);
+            case 'response.function_call_arguments.delta':
+                return this.serializeFunctionCallArgumentsDelta(event);
+            case 'response.function_call_arguments.done':
+                return this.serializeFunctionCallArgumentsDone(event);
+            case 'response.required_action':
+                return this.serializeRequiredAction(event);
+            case 'response.completed':
+                return this.serializeResponseCompleted(event);
+            case 'response.done':
+                return this.serializeResponseDone(event);
+            case 'response.error':
+                return this.serializeResponseError(event);
+            case 'response.cancelled':
+                return this.serializeResponseCancelled(event);
+            default:
+                throw new Error(`Unsupported ResponsesSseEvent type: ${event.type}`);
+        }
+    }
+    /**
+     * 从SSE wire格式反序列化为Responses事件
+     */
+    deserializeFromWire(wireData) {
+        const lines = wireData.trim().split('\n');
+        let eventType = null;
+        let eventData = null;
+        let eventId = null;
+        for (const line of lines) {
+            if (line.startsWith('event:')) {
+                eventType = line.substring(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                const dataStr = line.substring(5).trim();
+                try {
+                    eventData = dataStr ? JSON.parse(dataStr) : null;
+                }
+                catch {
+                    eventData = dataStr;
+                }
+            }
+            else if (line.startsWith('id:')) {
+                eventId = line.substring(3).trim();
+            }
+        }
+        if (!eventType) {
+            throw new Error('Missing event type in SSE data');
+        }
+        const timestampValue = this.parseTimestamp(eventId);
+        return this.decorate({
+            type: eventType,
+            timestamp: timestampValue,
+            data: eventData
+        });
+    }
+    /**
+     * 验证SSE wire格式
+     */
+    validateWireFormat(wireData) {
+        try {
+            const lines = wireData.trim().split('\n');
+            let hasEvent = false;
+            let hasData = false;
+            for (const line of lines) {
+                if (line.startsWith('event:')) {
+                    hasEvent = true;
+                }
+                else if (line.startsWith('data:')) {
+                    hasData = true;
+                }
+            }
+            return hasEvent && hasData;
+        }
+        catch {
+            return false;
+        }
+    }
+    decorate(event) {
+        return {
+            ...event,
+            protocol: 'responses',
+            direction: 'sse_to_json'
+        };
+    }
+    /**
+     * 序列化response.created事件
+     * 格式: event: response.created\ndata: {"response": {...}}\n\n
+     */
+    serializeResponseCreated(event) {
+        return this.buildSSEEvent('response.created', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.in_progress事件
+     */
+    serializeResponseInProgress(event) {
+        return this.buildSSEEvent('response.in_progress', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.reasoning_text.delta事件
+     */
+    serializeReasoningTextDelta(event) {
+        return this.buildSSEEvent('response.reasoning_text.delta', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.reasoning_text.done事件
+     */
+    serializeReasoningTextDone(event) {
+        return this.buildSSEEvent('response.reasoning_text.done', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.content_part.added事件
+     */
+    serializeContentPartAdded(event) {
+        return this.buildSSEEvent('response.content_part.added', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.content_part.done事件
+     */
+    serializeContentPartDone(event) {
+        return this.buildSSEEvent('response.content_part.done', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.output_item.added事件
+     */
+    serializeOutputItemAdded(event) {
+        return this.buildSSEEvent('response.output_item.added', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.output_item.done事件
+     */
+    serializeOutputItemDone(event) {
+        return this.buildSSEEvent('response.output_item.done', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.function_call_arguments.delta事件
+     */
+    serializeFunctionCallArgumentsDelta(event) {
+        return this.buildSSEEvent('response.function_call_arguments.delta', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.function_call_arguments.done事件
+     */
+    serializeFunctionCallArgumentsDone(event) {
+        return this.buildSSEEvent('response.function_call_arguments.done', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.required_action事件
+     */
+    serializeRequiredAction(event) {
+        return this.buildSSEEvent('response.required_action', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.completed事件
+     */
+    serializeResponseCompleted(event) {
+        return this.buildSSEEvent('response.completed', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.done事件
+     */
+    serializeResponseDone(event) {
+        return this.buildSSEEvent('response.done', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.error事件
+     */
+    serializeResponseError(event) {
+        return this.buildSSEEvent('response.error', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 序列化response.cancelled事件
+     */
+    serializeResponseCancelled(event) {
+        return this.buildSSEEvent('response.cancelled', event.data, event.timestamp, event.sequenceNumber);
+    }
+    /**
+     * 构建标准SSE事件格式
+     */
+    buildSSEEvent(eventType, data, timestamp, sequenceNumber) {
+        let wireEvent = `event: ${eventType}\n`;
+        if (data === '[DONE]') {
+            wireEvent += 'data: [DONE]\n';
+        }
+        else {
+            const finalData = this.buildEventPayload(eventType, data, sequenceNumber);
+            wireEvent += `data: ${JSON.stringify(finalData)}\n`;
+        }
+        if (timestamp) {
+            wireEvent += `id: ${timestamp}\n`;
+        }
+        wireEvent += `\n`;
+        return wireEvent;
+    }
+    /**
+     * 创建标准response.created事件
+     */
+    static createResponseCreatedEvent(response, timestamp) {
+        return {
+            type: 'response.created',
+            timestamp: timestamp ?? Date.now(),
+            data: { response },
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    /**
+     * 创建标准response.in_progress事件
+     */
+    static createResponseInProgressEvent(timestamp) {
+        return {
+            type: 'response.in_progress',
+            timestamp: timestamp ?? Date.now(),
+            data: {},
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    /**
+     * 创建标准response.completed事件
+     */
+    static createResponseCompletedEvent(responseId, status, usage, timestamp) {
+        return {
+            type: 'response.completed',
+            timestamp: timestamp ?? Date.now(),
+            data: {
+                response: {
+                    id: responseId,
+                    status,
+                    ...(usage && { usage })
+                }
+            },
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    /**
+     * 创建标准response.required_action事件
+     */
+    static createRequiredActionEvent(toolCalls, timestamp) {
+        return {
+            type: 'response.required_action',
+            timestamp: timestamp ?? Date.now(),
+            data: {
+                type: 'submit_tool_outputs',
+                submit_tool_outputs: {
+                    tool_calls: toolCalls
+                }
+            },
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    /**
+     * 创建标准response.done事件
+     */
+    static createResponseDoneEvent(requestId, totalEvents, timestamp) {
+        return {
+            type: 'response.done',
+            timestamp: timestamp ?? Date.now(),
+            data: {
+                type: 'done',
+                requestId,
+                totalEvents
+            },
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    /**
+     * 创建标准response.error事件
+     */
+    static createResponseErrorEvent(error, requestId, timestamp) {
+        return {
+            type: 'response.error',
+            timestamp: timestamp ?? Date.now(),
+            data: {
+                type: 'error',
+                requestId,
+                error: {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack
+                }
+            },
+            protocol: 'responses',
+            direction: 'json_to_sse'
+        };
+    }
+    buildEventPayload(eventType, data, sequenceNumber) {
+        let payload;
+        if (data === null || data === undefined) {
+            payload = { type: eventType };
+        }
+        else if (typeof data === 'object') {
+            const existing = data;
+            payload = {
+                ...(existing || {})
+            };
+            if (!Object.prototype.hasOwnProperty.call(payload, 'type')) {
+                payload.type = eventType;
+            }
+        }
+        else {
+            payload = { type: eventType, value: data };
+        }
+        if (sequenceNumber !== undefined && !Object.prototype.hasOwnProperty.call(payload, 'sequence_number')) {
+            payload.sequence_number = sequenceNumber;
+        }
+        return payload;
+    }
+    /**
+     * 解析 wire 中的时间戳字符串
+     */
+    parseTimestamp(source) {
+        if (!source)
+            return Date.now();
+        const numeric = Number(source);
+        if (!Number.isNaN(numeric)) {
+            return numeric;
+        }
+        const parsed = Date.parse(source);
+        return Number.isNaN(parsed) ? Date.now() : parsed;
+    }
+}
+/**
+ * 默认Responses事件序列化器实例
+ */
+export const defaultResponsesEventSerializer = new ResponsesEventSerializer();

package/dist/sse/shared/serializers/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 序列化器相关类型定义
+ */
+export interface SerializationOptions {
+    /** 是否启用格式化 */
+    pretty?: boolean;
+    /** 是否启用压缩 */
+    compress?: boolean;
+    /** 字符编码 */
+    encoding?: 'utf8' | 'ascii' | 'base64';
+    /** 自定义分隔符 */
+    delimiter?: string;
+}
+export interface ChatSerializationOptions extends SerializationOptions {
+    /** 是否包含系统指纹 */
+    includeSystemFingerprint?: boolean;
+    /** 是否包含logprobs */
+    includeLogprobs?: boolean;
+    /** 自定义事件映射 */
+    eventMapping?: Record<string, string>;
+}
+export interface ResponsesSerializationOptions extends SerializationOptions {
+    /** 是否包含元数据 */
+    includeMetadata?: boolean;
+    /** 是否包含统计信息 */
+    includeStats?: boolean;
+    /** 自定义事件过滤 */
+    eventFilter?: (event: any) => boolean;
+}
+export interface EventSerializer<TOptions extends SerializationOptions = SerializationOptions> {
+    /** 序列化单个事件 */
+    serialize(event: any, options?: TOptions): string;
+    /** 反序列化单个事件 */
+    deserialize(data: string, options?: TOptions): any;
+    /** 批量序列化 */
+    serializeBatch(events: any[], options?: TOptions): string[];
+    /** 批量反序列化 */
+    deserializeBatch(data: string[], options?: TOptions): any[];
+}
+export interface ChatEventSerializer extends EventSerializer<ChatSerializationOptions> {
+    /** 序列化Chat Completion Chunk */
+    serializeChatChunk(chunk: any, options?: ChatSerializationOptions): string;
+    /** 反序列化Chat Completion Chunk */
+    deserializeChatChunk(data: string, options?: ChatSerializationOptions): any;
+}
+export interface ResponsesEventSerializer extends EventSerializer<ResponsesSerializationOptions> {
+    /** 序列化Responses事件 */
+    serializeResponsesEvent(event: any, options?: ResponsesSerializationOptions): string;
+    /** 反序列化Responses事件 */
+    deserializeResponsesEvent(data: string, options?: ResponsesSerializationOptions): any;
+}

package/dist/sse/shared/serializers/types.js

@@ -0,0 +1,4 @@
+/**
+ * 序列化器相关类型定义
+ */
+export {};

package/dist/sse/shared/utils.d.ts

@@ -0,0 +1,254 @@
+/**
+ * 共享工具函数
+ * 提供JSON↔SSE双向转换中常用的工具函数
+ */
+import { Readable } from 'stream';
+/**
+ * 字符串工具
+ */
+export declare class StringUtils {
+    /**
+     * 安全地将值转换为字符串
+     */
+    static safeStringify(value: unknown): string;
+    /**
+     * 安全地解析JSON字符串
+     */
+    static safeParse<T = any>(text: string): T | null;
+    /**
+     * 检查字符串是否为空或只包含空白字符
+     */
+    static isEmpty(str: string): boolean;
+    /**
+     * 检查字符串是否为有效的JSON
+     */
+    static isValidJson(str: string): boolean;
+    /**
+     * 截断字符串到指定长度
+     */
+    static truncate(str: string, maxLength: number, suffix?: string): string;
+    /**
+     * 生成随机字符串
+     */
+    static random(length?: number): string;
+    /**
+     * 分割字符串为块
+     */
+    static chunkString(text: string, chunkSize: number, boundary: RegExp): string[];
+}
+/**
+ * 对象工具
+ */
+export declare class ObjectUtils {
+    /**
+     * 深度冻结对象
+     */
+    static deepFreeze<T>(obj: T): T;
+    /**
+     * 深度克隆对象
+     */
+    static deepClone<T>(obj: T): T;
+    /**
+     * 安全地获取嵌套对象属性
+     */
+    static get(obj: any, path: string, defaultValue?: any): any;
+    /**
+     * 安全地设置嵌套对象属性
+     */
+    static set(obj: any, path: string, value: any): void;
+    /**
+     * 检查对象是否为空
+     */
+    static isEmpty(obj: any): boolean;
+    /**
+     * 合并对象
+     */
+    static merge<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+}
+/**
+ * 数组工具
+ */
+export declare class ArrayUtils {
+    /**
+     * 数组去重
+     */
+    static unique<T>(arr: T[]): T[];
+    /**
+     * 分组数组
+     */
+    static groupBy<T, K extends string | number>(arr: T[], keyFn: (item: T) => K): Record<K, T[]>;
+    /**
+     * 分块数组
+     */
+    static chunk<T>(arr: T[], size: number): T[][];
+    /**
+     * 扁平化数组
+     */
+    static flatten<T>(arr: (T | T[])[]): T[];
+    /**
+     * 找到数组中的差异
+     */
+    static diff<T>(arr1: T[], arr2: T[]): {
+        added: T[];
+        removed: T[];
+        common: T[];
+    };
+}
+/**
+ * 时间工具
+ */
+export declare class TimeUtils {
+    /**
+     * 获取当前时间戳（毫秒）
+     */
+    static now(): number;
+    /**
+     * 获取当前时间戳（秒）
+     */
+    static nowSeconds(): number;
+    /**
+     * 格式化时间戳
+     */
+    static formatTimestamp(timestamp: number, format?: string): string;
+    /**
+     * 延迟指定时间
+     */
+    static delay(ms: number): Promise<void>;
+    /**
+     * 带超时的Promise
+     */
+    static timeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+}
+/**
+ * 验证工具
+ */
+export declare class ValidationUtils {
+    /**
+     * 检查值是否为对象
+     */
+    static isObject(value: unknown): value is Record<string, unknown>;
+    /**
+     * 检查值是否为有效的ID
+     */
+    static isValidId(value: string, pattern: RegExp): boolean;
+    /**
+     * 验证序列号
+     */
+    static isValidSequenceNumber(value: number, max?: number): boolean;
+    /**
+     * 验证时间戳
+     */
+    static isValidTimestamp(value: number): boolean;
+    /**
+     * 验证JSON结构
+     */
+    static validateJsonStructure(obj: any, schema: any): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * 流工具
+ */
+export declare class StreamUtils {
+    /**
+     * 创建可读流
+     */
+    static createReadable<T>(data: T[]): Readable;
+    /**
+     * 将异步生成器转换为流
+     */
+    static asyncGeneratorToStream<T>(generator: AsyncGenerator<T>): Readable;
+    /**
+     * 将流转换为数组
+     */
+    static streamToArray<T>(stream: Readable): Promise<T[]>;
+    /**
+     * 管道流超时
+     */
+    static pipeWithTimeout<T>(source: Readable, destination: NodeJS.WritableStream, timeoutMs: number): Promise<void>;
+}
+/**
+ * ID生成工具
+ */
+export declare class IdUtils {
+    /**
+     * 生成请求ID
+     */
+    static generateRequestId(): string;
+    /**
+     * 生成响应ID
+     */
+    static generateResponseId(): string;
+    /**
+     * 生成推理项目ID
+     */
+    static generateReasoningId(): string;
+    /**
+     * 生成函数调用ID
+     */
+    static generateFunctionCallId(): string;
+    /**
+     * 生成工具调用ID
+     */
+    static generateToolCallId(): string;
+    /**
+     * 生成消息ID
+     */
+    static generateMessageId(): string;
+}
+/**
+ * 错误处理工具
+ */
+export declare class ErrorUtils {
+    /**
+     * 创建标准错误
+     */
+    static createError(message: string, code: string, context?: any): Error & {
+        code: string;
+        context?: any;
+    };
+    /**
+     * 包装错误
+     */
+    static wrapError(error: unknown, context?: string): Error;
+    /**
+     * 判断是否为超时错误
+     */
+    static isTimeoutError(error: Error): boolean;
+    /**
+     * 判断是否为网络错误
+     */
+    static isNetworkError(error: Error): boolean;
+}
+/**
+ * 正则表达式模式
+ */
+export declare const REGEX_PATTERNS: {
+    readonly WORD_BOUNDARY: RegExp;
+};
+/**
+ * 性能监控工具
+ */
+export declare class PerformanceUtils {
+    /**
+     * 创建性能计时器
+     */
+    static createTimer(): () => number;
+    /**
+     * 测量函数执行时间
+     */
+    static measureTime<T>(fn: () => T | Promise<T>): Promise<{
+        result: T;
+        duration: number;
+    }>;
+    /**
+     * 创建内存使用快照
+     */
+    static createMemorySnapshot(): {
+        rss: number;
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+    };
+}