@jsonstudio/llms 0.4.2

package/dist/conversion/conversion-v3/sse/json-to-sse/responses-json-to-sse-converter.js

@@ -0,0 +1,322 @@
+/**
+ * Responses JSON → SSE转换器（重构版本）
+ * 使用函数化架构：事件生成 + 序列化 + 写入分离
+ */
+import { PassThrough } from 'stream';
+import { DEFAULT_RESPONSES_CONVERSION_CONFIG } from '../types/index.js';
+import { ErrorUtils } from '../shared/utils.js';
+import { createResponsesSequencer } from './sequencers/responses-sequencer.js';
+import { createResponsesStreamWriter } from '../shared/writer.js';
+/**
+ * 重构后的Responses JSON到SSE转换器
+ * 采用函数化架构，专注于编排而非具体业务逻辑
+ */
+export class ResponsesJsonToSseConverterRefactored {
+    config = DEFAULT_RESPONSES_CONVERSION_CONFIG;
+    contexts = new Map();
+    constructor(config) {
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+    }
+    /**
+     * 将Responses请求转换为SSE流
+     */
+    async convertRequestToJsonToSse(request, options) {
+        // 1. 创建上下文
+        const context = this.createRequestContext(request, options);
+        this.contexts.set(options.requestId, context);
+        // 2. 创建底层流
+        const stream = new PassThrough({ objectMode: true });
+        // 3. 创建SSE事件流接口
+        const sseStream = Object.assign(stream, {
+            protocol: 'responses',
+            direction: 'json_to_sse',
+            requestId: options.requestId,
+            getStats: () => context.eventStats,
+            getConfig: () => this.config,
+            complete: () => this.completeStream(context, stream),
+            abort: (error) => this.abortStream(context, stream, error)
+        });
+        // 4. 启动异步转换过程（使用函数化架构）
+        this.processRequestToSseWithFunctions(request, context, stream).catch(error => {
+            this.handleStreamError(context, error, stream);
+        });
+        return sseStream;
+    }
+    /**
+     * 将Responses响应转换为SSE流
+     */
+    async convertResponseToJsonToSse(response, options) {
+        // 1. 创建上下文
+        const context = this.createResponseContext(response, options);
+        this.contexts.set(options.requestId, context);
+        // 2. 创建底层流
+        const stream = new PassThrough({ objectMode: true });
+        // 3. 创建SSE事件流接口
+        const sseStream = Object.assign(stream, {
+            protocol: 'responses',
+            direction: 'json_to_sse',
+            requestId: options.requestId,
+            getStats: () => context.eventStats,
+            getConfig: () => this.config,
+            complete: () => this.completeStream(context, stream),
+            abort: (error) => this.abortStream(context, stream, error)
+        });
+        // 4. 启动异步转换过程（使用函数化架构）
+        this.processResponseToSseWithFunctions(response, context, stream).catch(error => {
+            this.handleStreamError(context, error, stream);
+        });
+        return sseStream;
+    }
+    /**
+     * 使用函数化架构处理请求转换
+     */
+    async processRequestToSseWithFunctions(request, context, stream) {
+        try {
+            // 1. 验证请求
+            this.validateRequest(request);
+            // 2. 创建流写入器
+            const writer = createResponsesStreamWriter(stream, {
+                onEvent: (event) => this.updateStats(context, event),
+                onError: (error) => this.handleStreamError(context, error, stream)
+            });
+            // 3. 创建事件序列化器
+            const sequencer = createResponsesSequencer({
+                chunkSize: context.options.chunkSize || this.config.defaultChunkSize,
+                chunkDelayMs: context.options.delayMs || this.config.defaultDelayMs,
+                enableDelay: !!context.options.delayMs,
+                enableValidation: this.config.enableEventValidation,
+                enableRecovery: this.config.strictMode,
+                submittedToolOutputs: context.options.resumeToolOutputs
+            });
+            // 4. 生成事件序列并写入流
+            const eventStream = sequencer.sequenceRequest(request, context.requestId);
+            await writer.writeResponsesEvents(eventStream);
+            // 5. 完成流
+            writer.complete();
+        }
+        catch (error) {
+            throw this.wrapError('REQUEST_CONVERSION_ERROR', error, context.requestId);
+        }
+    }
+    /**
+     * 使用函数化架构处理响应转换
+     */
+    async processResponseToSseWithFunctions(response, context, stream) {
+        try {
+            // 1. 验证响应
+            this.validateResponse(response);
+            // 2. 创建流写入器
+            const writer = createResponsesStreamWriter(stream, {
+                onEvent: (event) => this.updateStats(context, event),
+                onError: (error) => this.handleStreamError(context, error, stream)
+            });
+            // 3. 创建事件序列化器
+            const sequencer = createResponsesSequencer({
+                chunkSize: context.options.chunkSize || this.config.defaultChunkSize,
+                chunkDelayMs: context.options.delayMs || this.config.defaultDelayMs,
+                enableDelay: !!context.options.delayMs,
+                enableValidation: this.config.enableEventValidation,
+                enableRecovery: this.config.strictMode
+            });
+            // 4. 生成事件序列并写入流
+            const eventStream = sequencer.sequenceResponse(response, context.requestId);
+            await writer.writeResponsesEvents(eventStream);
+            // 5. 完成流
+            writer.complete();
+        }
+        catch (error) {
+            throw this.wrapError('RESPONSE_CONVERSION_ERROR', error, context.requestId);
+        }
+    }
+    /**
+     * 验证请求格式
+     */
+    validateRequest(request) {
+        if (!request.model || !request.input) {
+            throw new Error('Invalid ResponsesRequest: missing required fields');
+        }
+        if (!Array.isArray(request.input)) {
+            throw new Error('Invalid ResponsesRequest: input must be an array');
+        }
+    }
+    /**
+     * 验证响应格式
+     */
+    validateResponse(response) {
+        if (!response.id || !response.model || !response.object) {
+            throw new Error('Invalid ResponsesResponse: missing required fields');
+        }
+        if (response.object !== 'response') {
+            throw new Error('Invalid ResponsesResponse: object must be "response"');
+        }
+        if (!Array.isArray(response.output)) {
+            throw new Error('Invalid ResponsesResponse: output must be an array');
+        }
+    }
+    /**
+     * 更新统计信息
+     */
+    updateStats(context, event) {
+        context.eventStats.totalEvents++;
+        context.eventStats.eventTypes[event.type] = (context.eventStats.eventTypes[event.type] || 0) + 1;
+        // 根据事件类型更新特定统计
+        switch (event.type) {
+            case 'response.created':
+            case 'response.in_progress':
+            case 'response.completed':
+            case 'response.required_action':
+            case 'response.done':
+                context.eventStats.messageEventsCount++;
+                break;
+            case 'response.output_item.added':
+            case 'response.output_item.done':
+                context.eventStats.outputItemsCount++;
+                break;
+            case 'response.content_part.added':
+            case 'response.content_part.done':
+                context.eventStats.contentPartsCount++;
+                break;
+            case 'response.output_text.delta':
+            case 'response.output_text.done':
+                context.eventStats.deltaEventsCount++;
+                break;
+            case 'response.reasoning_text.delta':
+            case 'response.reasoning_text.done':
+                context.eventStats.reasoningEventsCount++;
+                break;
+            case 'response.function_call_arguments.delta':
+            case 'response.function_call_arguments.done':
+                context.eventStats.functionCallEventsCount++;
+                break;
+            case 'response.error':
+                context.eventStats.errorCount++;
+                break;
+        }
+        // 更新时间戳
+        context.eventStats.lastEventTime = event.timestamp;
+    }
+    /**
+     * 包装错误
+     */
+    wrapError(code, originalError, requestId) {
+        return ErrorUtils.createError(`${code}: ${originalError.message}`, code, { requestId, originalError });
+    }
+    /**
+     * 处理流错误
+     */
+    handleStreamError(context, error, stream) {
+        context.eventStats.errorCount++;
+        const wrappedError = this.wrapError('STREAM_ERROR', error, context.requestId);
+        if (stream.writable) {
+            stream.destroy(wrappedError);
+        }
+    }
+    /**
+     * 完成流
+     */
+    completeStream(context, stream) {
+        context.eventStats.endTime = Date.now();
+        context.eventStats.duration = context.eventStats.endTime - context.eventStats.startTime;
+        if (stream.writable) {
+            stream.end();
+        }
+    }
+    /**
+     * 中止流
+     */
+    abortStream(context, stream, error) {
+        context.eventStats.endTime = Date.now();
+        context.eventStats.duration = context.eventStats.endTime - context.eventStats.startTime;
+        if (error) {
+            context.eventStats.errorCount++;
+        }
+        if (stream.writable) {
+            stream.destroy(error);
+        }
+    }
+    /**
+     * 创建请求上下文
+     */
+    createRequestContext(request, options) {
+        const eventStats = {
+            totalEvents: 0,
+            eventTypes: {},
+            startTime: Date.now(),
+            outputItemsCount: 0,
+            contentPartsCount: 0,
+            deltaEventsCount: 0,
+            reasoningEventsCount: 0,
+            functionCallEventsCount: 0,
+            messageEventsCount: 0,
+            errorCount: 0
+        };
+        return {
+            requestId: options.requestId,
+            model: request.model,
+            responsesRequest: request,
+            options,
+            startTime: Date.now(),
+            sequenceCounter: 0,
+            outputIndexCounter: 0,
+            contentIndexCounter: new Map(),
+            isStreaming: true,
+            currentResponse: {},
+            eventStats,
+            outputItemStates: new Map()
+        };
+    }
+    /**
+     * 创建响应上下文
+     */
+    createResponseContext(response, options) {
+        const eventStats = {
+            totalEvents: 0,
+            eventTypes: {},
+            startTime: Date.now(),
+            outputItemsCount: 0,
+            contentPartsCount: 0,
+            deltaEventsCount: 0,
+            reasoningEventsCount: 0,
+            functionCallEventsCount: 0,
+            messageEventsCount: 0,
+            errorCount: 0
+        };
+        return {
+            requestId: options.requestId,
+            model: response.model,
+            responsesRequest: {}, // 空请求，因为是从响应转换
+            responsesResponse: response,
+            options,
+            startTime: Date.now(),
+            sequenceCounter: 0,
+            outputIndexCounter: 0,
+            contentIndexCounter: new Map(),
+            isStreaming: true,
+            currentResponse: response,
+            eventStats,
+            outputItemStates: new Map()
+        };
+    }
+    /**
+     * 获取上下文
+     */
+    getContext(requestId) {
+        return this.contexts.get(requestId);
+    }
+    /**
+     * 清理上下文
+     */
+    clearContext(requestId) {
+        this.contexts.delete(requestId);
+    }
+    /**
+     * 获取所有活跃的上下文
+     */
+    getActiveContexts() {
+        return new Map(this.contexts);
+    }
+}
+// 为了向后兼容，导出原有名称
+export const ResponsesJsonToSseConverter = ResponsesJsonToSseConverterRefactored;

package/dist/conversion/conversion-v3/sse/json-to-sse/sequencers/chat-sequencer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chat协议事件编排器
+ * 负责严格的事件时序组合：role → content OR tool_calls(name → args.delta*) → finish_reason → done
+ */
+import { ChatCompletionResponse, ChatSseEvent } from '../../types/index.js';
+import { ChatEventGeneratorContext, ChatEventGeneratorConfig } from '../event-generators/chat.js';
+export interface ChatSequencerConfig extends ChatEventGeneratorConfig {
+    includeSequenceNumbers: boolean;
+    enableDelay: boolean;
+    validateOrder: boolean;
+}
+export declare const DEFAULT_CHAT_SEQUENCER_CONFIG: ChatSequencerConfig;
+/**
+ * 主编排器：将Chat响应转换为有序的SSE事件流
+ */
+export declare function sequenceChatResponse(response: ChatCompletionResponse, context: ChatEventGeneratorContext, config?: ChatSequencerConfig): AsyncGenerator<ChatSseEvent>;
+/**
+ * 序列化Chat请求（用于请求→SSE转换）
+ */
+export declare function sequenceChatRequest(request: any, context: ChatEventGeneratorContext, config?: ChatSequencerConfig): AsyncGenerator<ChatSseEvent>;
+/**
+ * 创建Chat事件序列化器工厂
+ */
+export declare function createChatSequencer(config?: Partial<ChatSequencerConfig>): {
+    /**
+     * 序列化响应
+     */
+    sequenceResponse(response: ChatCompletionResponse, model: string, requestId: string): AsyncGenerator<ChatSseEvent, void, any>;
+    /**
+     * 序列化请求
+     */
+    sequenceRequest(request: any, model: string, requestId: string): AsyncGenerator<ChatSseEvent, void, any>;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): ChatSequencerConfig;
+};

package/dist/conversion/conversion-v3/sse/json-to-sse/sequencers/chat-sequencer.js

@@ -0,0 +1,218 @@
+/**
+ * Chat协议事件编排器
+ * 负责严格的事件时序组合：role → content OR tool_calls(name → args.delta*) → finish_reason → done
+ */
+import { buildRoleDelta, buildReasoningDeltas, buildContentDeltas, buildToolCallStart, buildToolCallArgsDeltas, buildFinishEvent, buildDoneEvent, buildErrorEvent, DEFAULT_CHAT_EVENT_GENERATOR_CONFIG, createDefaultContext } from '../event-generators/chat.js';
+// 默认配置
+export const DEFAULT_CHAT_SEQUENCER_CONFIG = {
+    ...DEFAULT_CHAT_EVENT_GENERATOR_CONFIG,
+    includeSequenceNumbers: true,
+    enableDelay: false,
+    validateOrder: true
+};
+/**
+ * 验证消息顺序的合法性
+ */
+function validateMessageSequence(message, previousMessage) {
+    // 基本字段
+    if (!message || typeof message.role !== 'string')
+        return false;
+    // 允许两种有效形态：
+    // 1) content 存在（字符串/数组/对象）
+    // 2) 仅工具调用（content 为空，但存在 tool_calls[] 且 finish_reason=tool_calls）
+    const hasContent = hasMeaningfulContent(message.content);
+    const hasToolCalls = Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+    if (!hasContent && !hasToolCalls)
+        return false;
+    // 不允许 assistant 之后出现 user 倒序
+    if (previousMessage?.role === 'assistant' && message.role === 'user')
+        return false;
+    return true;
+}
+function hasMeaningfulContent(content) {
+    if (content == null)
+        return false;
+    if (typeof content === 'string')
+        return content.trim().length > 0;
+    if (Array.isArray(content))
+        return content.length > 0;
+    if (typeof content === 'object')
+        return Object.keys(content).length > 0;
+    return false;
+}
+/**
+ * 异步生成器：为事件添加序列号和延迟
+ */
+async function* withSequencing(events, config, startSequence = 0) {
+    let sequenceNumber = startSequence;
+    for await (const event of events) {
+        if (config.includeSequenceNumbers)
+            event.sequenceNumber = sequenceNumber++;
+        yield event;
+        if (config.enableDelay && config.chunkDelayMs > 0) {
+            await new Promise(resolve => setTimeout(resolve, config.chunkDelayMs));
+        }
+    }
+}
+/**
+ * 序列化单个消息的内容和工具调用
+ */
+async function* sequenceMessageContent(message, context, config) {
+    // 1. 发送role delta
+    for (const roleEvent of buildRoleDelta(message.role, context, config)) {
+        yield roleEvent;
+    }
+    // 2. 处理reasoning（如果有）
+    if (message.reasoning) {
+        yield* withSequencing(buildReasoningDeltas(message.reasoning, context, config), config);
+    }
+    // 3. 处理content和tool_calls
+    if (hasMeaningfulContent(message.content)) {
+        yield* withSequencing(buildContentDeltas(message.content, context, config), config);
+    }
+    if (message.tool_calls && message.tool_calls.length > 0) {
+        for (let i = 0; i < message.tool_calls.length; i++) {
+            const toolCall = message.tool_calls[i];
+            const toolCallIndex = context.toolCallIndexCounter + i;
+            yield buildToolCallStart(toolCall, toolCallIndex, context, config);
+            if (toolCall.function?.arguments) {
+                yield* withSequencing(buildToolCallArgsDeltas(toolCall.function.arguments, toolCallIndex, context, config), config);
+            }
+        }
+    }
+}
+/**
+ * 主编排器：将Chat响应转换为有序的SSE事件流
+ */
+export async function* sequenceChatResponse(response, context, config = DEFAULT_CHAT_SEQUENCER_CONFIG) {
+    try {
+        // 验证响应格式
+        if (!response.choices || response.choices.length === 0) {
+            throw new Error('Invalid ChatCompletionResponse: missing choices');
+        }
+        const choice = response.choices[0];
+        let message = choice?.message;
+        // 兼容上游给到的 chunk 形态（choices[0].delta）
+        if (!message && choice && typeof choice === 'object' && choice.delta) {
+            const d = choice.delta;
+            message = {
+                role: typeof d.role === 'string' ? d.role : 'assistant',
+                content: typeof d.content !== 'undefined' ? d.content : null,
+                tool_calls: Array.isArray(d.tool_calls) ? d.tool_calls : undefined
+            };
+            // 为了下游 finish 事件合理性，缺省 finish_reason：若存在工具调用则用 tool_calls，否则 stop
+            if (!('finish_reason' in choice)) {
+                choice.finish_reason = message.tool_calls ? 'tool_calls' : 'stop';
+            }
+        }
+        message = normalizeFunctionCall(message);
+        // 验证消息顺序（如果启用）
+        if (config.validateOrder) {
+            // 这里可以添加更多的顺序验证逻辑
+            if (!validateMessageSequence(message)) {
+                const roleSafe = message && typeof message.role === 'string' ? message.role : 'unknown';
+                throw new Error(`Invalid message sequence for role: ${roleSafe}`);
+            }
+        }
+        // 序列化消息内容
+        yield* sequenceMessageContent(message, context, config);
+        // 发送finish_reason事件（若未提供则根据消息推断）
+        yield buildFinishEvent(choice.finish_reason || (message?.tool_calls ? 'tool_calls' : 'stop'), context, config);
+        // 发送done事件
+        yield buildDoneEvent(context, config);
+    }
+    catch (error) {
+        // 发送错误事件
+        yield buildErrorEvent(error, context, config);
+    }
+}
+function normalizeFunctionCall(message) {
+    if (!message || typeof message !== 'object')
+        return message;
+    if ((message.tool_calls && message.tool_calls.length) || !message.function_call) {
+        return message;
+    }
+    const fc = message.function_call;
+    const name = typeof fc?.name === 'string' ? fc.name : 'function';
+    let args = '';
+    if (typeof fc?.arguments === 'string') {
+        args = fc.arguments;
+    }
+    else {
+        try {
+            args = JSON.stringify(fc?.arguments ?? {});
+        }
+        catch {
+            args = '{}';
+        }
+    }
+    message.tool_calls = [
+        {
+            id: typeof fc?.id === 'string' ? fc.id : `call_${Math.random().toString(36).slice(2, 10)}`,
+            type: 'function',
+            function: { name, arguments: args }
+        }
+    ];
+    return message;
+}
+/**
+ * 序列化Chat请求（用于请求→SSE转换）
+ */
+export async function* sequenceChatRequest(request, context, config = DEFAULT_CHAT_SEQUENCER_CONFIG) {
+    try {
+        // 验证请求格式
+        if (!request.messages || !Array.isArray(request.messages)) {
+            throw new Error('Invalid ChatCompletionRequest: missing messages');
+        }
+        // 为每个消息生成事件（主要用于流式回显）
+        for (let messageIndex = 0; messageIndex < request.messages.length; messageIndex++) {
+            const message = request.messages[messageIndex];
+            // 为每条消息创建新的上下文
+            const messageContext = {
+                ...context,
+                choiceIndex: messageIndex,
+                toolCallIndexCounter: 0,
+                contentIndexCounter: new Map()
+            };
+            // 序列化消息
+            yield* sequenceMessageContent(message, messageContext, config);
+            // 消息间添加小延迟（如果启用）
+            if (config.enableDelay && config.chunkDelayMs > 0 && messageIndex < request.messages.length - 1) {
+                await new Promise(resolve => setTimeout(resolve, config.chunkDelayMs * 2));
+            }
+        }
+        // 请求结束时发送done事件
+        yield buildDoneEvent(context, config);
+    }
+    catch (error) {
+        yield buildErrorEvent(error, context, config);
+    }
+}
+/**
+ * 创建Chat事件序列化器工厂
+ */
+export function createChatSequencer(config) {
+    const finalConfig = { ...DEFAULT_CHAT_SEQUENCER_CONFIG, ...config };
+    return {
+        /**
+         * 序列化响应
+         */
+        async *sequenceResponse(response, model, requestId) {
+            const context = createDefaultContext(model, requestId);
+            yield* sequenceChatResponse(response, context, finalConfig);
+        },
+        /**
+         * 序列化请求
+         */
+        async *sequenceRequest(request, model, requestId) {
+            const context = createDefaultContext(model, requestId);
+            yield* sequenceChatRequest(request, context, finalConfig);
+        },
+        /**
+         * 获取当前配置
+         */
+        getConfig() {
+            return { ...finalConfig };
+        }
+    };
+}

package/dist/conversion/conversion-v3/sse/json-to-sse/sequencers/responses-sequencer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Responses协议事件编排器
+ * 负责将Responses响应数据转换为有序的SSE事件流
+ */
+import { ResponsesResponse, ResponsesFunctionCallOutputItem, ResponsesSseEvent } from '../../types/index.js';
+import { ResponsesEventGeneratorContext, ResponsesEventGeneratorConfig } from '../event-generators/responses.js';
+export interface ResponsesSequencerConfig extends ResponsesEventGeneratorConfig {
+    enableValidation: boolean;
+    enableRecovery: boolean;
+    enableDelay: boolean;
+    maxOutputItems: number;
+    maxContentParts: number;
+    submittedToolOutputs?: ResponsesFunctionCallOutputItem[];
+}
+export declare const DEFAULT_RESPONSES_SEQUENCER_CONFIG: ResponsesSequencerConfig;
+/**
+ * 主编排器：将Responses响应转换为有序的SSE事件流
+ */
+export declare function sequenceResponse(response: ResponsesResponse, context: ResponsesEventGeneratorContext, config?: ResponsesSequencerConfig): AsyncGenerator<ResponsesSseEvent>;
+/**
+ * 序列化Responses请求（用于请求→SSE转换）
+ */
+export declare function sequenceRequest(request: any, context: ResponsesEventGeneratorContext, config?: ResponsesSequencerConfig): AsyncGenerator<ResponsesSseEvent>;
+/**
+ * 创建Responses事件序列化器工厂
+ */
+export declare function createResponsesSequencer(config?: Partial<ResponsesSequencerConfig>): {
+    /**
+     * 序列化响应
+     */
+    sequenceResponse(response: ResponsesResponse, requestId: string): AsyncGenerator<ResponsesSseEvent, void, any>;
+    /**
+     * 序列化请求
+     */
+    sequenceRequest(request: any, requestId: string): AsyncGenerator<ResponsesSseEvent, void, any>;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): ResponsesSequencerConfig;
+};