@jsonstudio/llms 0.4.2

package/dist/core/llmswitch-engine-v2.js

@@ -0,0 +1,649 @@
+/**
+ * LLMSwitch V2 引擎
+ *
+ * 基于现有Hooks系统的多端点转换引擎，支持Chat、Responses、Messages三个端点
+ * 每个转换节点前后都有Hooks支持，并提供基于入口端点的路径隔离快照系统
+ */
+import { LLMSwitchHookStage } from '../api/llmswitch-types.js';
+import { createHooksIntegration } from '../hooks/hooks-integration.js';
+import { EndpointRouter } from '../endpoints/endpoint-router.js';
+/**
+ * LLMSwitch V2 引擎状态
+ */
+var EngineState;
+(function (EngineState) {
+    EngineState["UNINITIALIZED"] = "uninitialized";
+    EngineState["INITIALIZING"] = "initializing";
+    EngineState["INITIALIZED"] = "initialized";
+    EngineState["RUNNING"] = "running";
+    EngineState["PAUSED"] = "paused";
+    EngineState["STOPPING"] = "stopping";
+    EngineState["STOPPED"] = "stopped";
+    EngineState["ERROR"] = "error";
+})(EngineState || (EngineState = {}));
+/**
+ * LLMSwitch V2 引擎核心实现
+ */
+export class LLMSwitchEngineV2 {
+    config;
+    state = EngineState.UNINITIALIZED;
+    hooksAdapter;
+    endpointRouter;
+    metrics;
+    startTime = 0;
+    hookHandlers = new Map();
+    constructor(config) {
+        this.config = config;
+        this.metrics = this.initializeMetrics();
+        this.hooksAdapter = this.createHooksAdapter();
+        this.endpointRouter = this.createEndpointRouter();
+    }
+    /**
+     * 初始化引擎
+     */
+    async initialize() {
+        if (this.state !== EngineState.UNINITIALIZED) {
+            throw new Error(`Cannot initialize from state: ${this.state}`);
+        }
+        this.state = EngineState.INITIALIZING;
+        try {
+            // 验证配置
+            this.validateConfig();
+            // 初始化Hooks适配器
+            await this.hooksAdapter.initialize?.();
+            // 初始化端点路由器
+            await this.endpointRouter.initialize?.();
+            // 注册默认工具治理Hooks
+            this.registerDefaultToolHooks();
+            this.state = EngineState.INITIALIZED;
+            console.log('LLMSwitch V2 engine initialized successfully');
+        }
+        catch (error) {
+            this.state = EngineState.ERROR;
+            throw error;
+        }
+    }
+    /**
+     * 启动引擎
+     */
+    async start() {
+        if (this.state !== EngineState.INITIALIZED) {
+            throw new Error(`Cannot start from state: ${this.state}`);
+        }
+        this.state = EngineState.RUNNING;
+        this.startTime = Date.now();
+        // 启动Hooks适配器
+        await this.hooksAdapter.start?.();
+        // 启动端点路由器
+        await this.endpointRouter.start?.();
+        console.log('LLMSwitch V2 engine started');
+    }
+    /**
+     * 停止引擎
+     */
+    async stop() {
+        if (this.state !== EngineState.RUNNING) {
+            return;
+        }
+        this.state = EngineState.STOPPING;
+        // 停止端点路由器
+        await this.endpointRouter.stop?.();
+        // 停止Hooks适配器
+        await this.hooksAdapter.stop?.();
+        this.state = EngineState.STOPPED;
+        console.log('LLMSwitch V2 engine stopped');
+    }
+    /**
+     * 关闭引擎
+     */
+    async shutdown() {
+        await this.stop();
+        // 销毁组件
+        await this.hooksAdapter.destroy?.();
+        await this.endpointRouter.destroy?.();
+        this.state = EngineState.UNINITIALIZED;
+        console.log('LLMSwitch V2 engine shutdown complete');
+    }
+    /**
+     * 处理请求
+     */
+    async processRequest(request, endpoint = 'chat', context) {
+        if (this.state !== EngineState.RUNNING) {
+            throw new Error('Engine is not running');
+        }
+        const startTime = Date.now();
+        const requestId = context?.requestId || this.generateRequestId();
+        const pathIdentifier = context?.pathIdentifier || this.generatePathIdentifier(request, endpoint);
+        try {
+            // 更新指标
+            this.metrics.totalRequests++;
+            // 构建完整的Hook上下文
+            const hookContext = {
+                executionId: this.generateExecutionId(),
+                stage: LLMSwitchHookStage.REQUEST_1_VALIDATION_PRE,
+                startTime,
+                requestId,
+                moduleId: `llmswitch-${endpoint}`,
+                metadata: context?.metadata,
+                endpoint,
+                originalProtocol: this.config.endpoints[endpoint]?.protocol || 'openai-chat',
+                targetProtocol: this.config.defaultProtocol,
+                pathIdentifier,
+                processingMode: this.detectProcessingMode(request),
+                hookSequence: 1,
+                totalHooks: 16 // 8个请求Hook + 8个响应Hook
+            };
+            // 执行请求处理流程
+            const result = await this.executeRequestFlow(request, hookContext);
+            if (result.success) {
+                this.metrics.successfulRequests++;
+            }
+            else {
+                this.metrics.failedRequests++;
+            }
+            return result;
+        }
+        catch (error) {
+            this.metrics.failedRequests++;
+            return {
+                success: false,
+                error: error,
+                executionTime: Date.now() - startTime,
+                metadata: {
+                    endpoint,
+                    originalProtocol: this.config.endpoints[endpoint]?.protocol || 'openai-chat',
+                    targetProtocol: this.config.defaultProtocol,
+                    processingMode: 'non-streaming',
+                    stage: 'error'
+                }
+            };
+        }
+    }
+    /**
+     * 处理响应
+     */
+    async processResponse(response, originalEndpoint, context) {
+        const startTime = Date.now();
+        try {
+            // 构建响应Hook上下文
+            const responseContext = {
+                ...context,
+                stage: LLMSwitchHookStage.RESPONSE_1_RECEIVE_PRE,
+                startTime,
+                hookSequence: 9, // 响应Hook从9开始
+                totalHooks: 16
+            };
+            // 执行响应处理流程
+            return await this.executeResponseFlow(response, responseContext);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error,
+                executionTime: Date.now() - startTime,
+                metadata: {
+                    endpoint: originalEndpoint,
+                    originalProtocol: context.originalProtocol,
+                    targetProtocol: context.targetProtocol,
+                    processingMode: context.processingMode,
+                    stage: 'response_error'
+                }
+            };
+        }
+    }
+    /**
+     * 流式请求处理
+     */
+    async processStreamingRequest(request, endpoint = 'chat', context) {
+        if (this.state !== EngineState.RUNNING) {
+            throw new Error('Engine is not running');
+        }
+        const requestId = context?.requestId || this.generateRequestId();
+        const pathIdentifier = context?.pathIdentifier || this.generatePathIdentifier(request, endpoint);
+        // 构建Hook上下文
+        const hookContext = {
+            executionId: this.generateExecutionId(),
+            stage: LLMSwitchHookStage.REQUEST_5_SSE_PRE,
+            startTime: Date.now(),
+            requestId,
+            moduleId: `llmswitch-${endpoint}`,
+            metadata: context?.metadata,
+            endpoint,
+            originalProtocol: this.config.endpoints[endpoint]?.protocol || 'openai-chat',
+            targetProtocol: this.config.defaultProtocol,
+            pathIdentifier,
+            processingMode: 'streaming',
+            hookSequence: 1,
+            totalHooks: 16
+        };
+        // 委托给端点路由器处理
+        return this.endpointRouter.routeStreamingRequest(this.getEndpointPath(endpoint), 'POST', request, { 'x-request-id': requestId });
+    }
+    /**
+     * 配置管理
+     */
+    async configure(config) {
+        this.config = config;
+    }
+    async updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+    }
+    /**
+     * 健康检查
+     */
+    async healthCheck() {
+        const components = {
+            endpoints: await this.endpointRouter.healthCheck(),
+            hooks: true, // TODO: 实际检查hooks状态
+            snapshot: this.config.hooks.snapshot.enabled,
+            protocols: {
+                'openai-chat': this.config.endpoints.chat?.enabled || false,
+                'openai-responses': this.config.endpoints.responses?.enabled || false,
+                'anthropic-messages': this.config.endpoints.messages?.enabled || false
+            }
+        };
+        const issues = [];
+        if (this.state !== EngineState.RUNNING) {
+            issues.push(`Engine is not running (state: ${this.state})`);
+        }
+        return {
+            healthy: issues.length === 0,
+            version: this.config.version,
+            uptime: this.state === EngineState.RUNNING ? Date.now() - this.startTime : 0,
+            components,
+            issues,
+            metrics: this.metrics
+        };
+    }
+    // 兼容方法（保留对既有调用方的兼容入口）
+    async convertRequest(payload, profile, context) {
+        // 检测端点类型
+        const endpoint = this.detectEndpointFromPayload(payload);
+        return this.processRequest(payload, endpoint, {
+            requestId: context.requestId,
+            metadata: { profile }
+        });
+    }
+    async convertResponse(payload, profile, context) {
+        const endpoint = context.endpoint || 'chat';
+        return this.processResponse(payload, endpoint, context);
+    }
+    // 私有方法
+    async executeRequestFlow(request, context) {
+        // 执行请求Hook流程 (request_1_* - request_8_*)
+        const requestStages = [
+            LLMSwitchHookStage.REQUEST_1_VALIDATION_PRE,
+            LLMSwitchHookStage.REQUEST_1_VALIDATION_POST,
+            LLMSwitchHookStage.REQUEST_2_ROUTING_PRE,
+            LLMSwitchHookStage.REQUEST_2_ROUTING_POST,
+            LLMSwitchHookStage.REQUEST_3_CONVERSION_PRE,
+            LLMSwitchHookStage.REQUEST_3_CONVERSION_POST,
+            LLMSwitchHookStage.REQUEST_4_TOOLS_PRE,
+            LLMSwitchHookStage.REQUEST_4_TOOLS_POST,
+            LLMSwitchHookStage.REQUEST_5_SSE_PRE,
+            LLMSwitchHookStage.REQUEST_5_SSE_POST,
+            LLMSwitchHookStage.REQUEST_6_SNAPSHOT_PRE,
+            LLMSwitchHookStage.REQUEST_6_SNAPSHOT_POST,
+            LLMSwitchHookStage.REQUEST_7_MONITORING_PRE,
+            LLMSwitchHookStage.REQUEST_7_MONITORING_POST,
+            LLMSwitchHookStage.REQUEST_8_VALIDATION_PRE,
+            LLMSwitchHookStage.REQUEST_8_VALIDATION_POST
+        ];
+        let currentData = request;
+        const results = [];
+        for (let i = 0; i < requestStages.length; i++) {
+            const stage = requestStages[i];
+            const hookContext = { ...context, stage, hookSequence: i + 1 };
+            const result = await this.hooksAdapter.executeHook(stage, hookContext, currentData);
+            if (!result.success) {
+                throw result.error || new Error(`Hook stage ${stage} failed`);
+            }
+            currentData = result.data;
+            results.push(result.metadata?.hookResults || []);
+        }
+        // 委托给端点路由器进行实际处理
+        const path = this.getEndpointPath(context.endpoint);
+        const endpointResult = await this.endpointRouter.routeRequest(path, 'POST', currentData);
+        return {
+            success: true,
+            data: endpointResult.data,
+            executionTime: Date.now() - context.startTime,
+            metadata: {
+                endpoint: context.endpoint,
+                originalProtocol: context.originalProtocol,
+                targetProtocol: context.targetProtocol,
+                processingMode: context.processingMode,
+                stage: 'request_completed',
+                hookResults: results.flat()
+            }
+        };
+    }
+    async executeResponseFlow(response, context) {
+        // 执行响应Hook流程 (response_1_* - response_8_*)
+        const responseStages = [
+            LLMSwitchHookStage.RESPONSE_1_RECEIVE_PRE,
+            LLMSwitchHookStage.RESPONSE_1_RECEIVE_POST,
+            LLMSwitchHookStage.RESPONSE_2_CONVERSION_PRE,
+            LLMSwitchHookStage.RESPONSE_2_CONVERSION_POST,
+            LLMSwitchHookStage.RESPONSE_3_TOOLS_PRE,
+            LLMSwitchHookStage.RESPONSE_3_TOOLS_POST,
+            LLMSwitchHookStage.RESPONSE_4_SSE_PRE,
+            LLMSwitchHookStage.RESPONSE_4_SSE_POST,
+            LLMSwitchHookStage.RESPONSE_5_FORMATTING_PRE,
+            LLMSwitchHookStage.RESPONSE_5_FORMATTING_POST,
+            LLMSwitchHookStage.RESPONSE_6_SNAPSHOT_PRE,
+            LLMSwitchHookStage.RESPONSE_6_SNAPSHOT_POST,
+            LLMSwitchHookStage.RESPONSE_7_QUALITY_PRE,
+            LLMSwitchHookStage.RESPONSE_7_QUALITY_POST,
+            LLMSwitchHookStage.RESPONSE_8_MONITORING_PRE,
+            LLMSwitchHookStage.RESPONSE_8_MONITORING_POST
+        ];
+        let currentData = response;
+        const results = [];
+        for (let i = 0; i < responseStages.length; i++) {
+            const stage = responseStages[i];
+            const hookContext = { ...context, stage, hookSequence: i + 9 };
+            const result = await this.hooksAdapter.executeHook(stage, hookContext, currentData);
+            if (!result.success) {
+                throw result.error || new Error(`Hook stage ${stage} failed`);
+            }
+            currentData = result.data;
+            results.push(result.metadata?.hookResults || []);
+        }
+        return {
+            success: true,
+            data: currentData,
+            executionTime: Date.now() - context.startTime,
+            metadata: {
+                endpoint: context.endpoint,
+                originalProtocol: context.originalProtocol,
+                targetProtocol: context.targetProtocol,
+                processingMode: context.processingMode,
+                stage: 'response_completed',
+                hookResults: results.flat()
+            }
+        };
+    }
+    createHooksAdapter() {
+        const adapterConfig = {
+            enabled: this.config.hooks.enabled,
+            timeout: 5000,
+            retryAttempts: 2,
+            parallel: false,
+            snapshot: {
+                enabled: this.config.hooks.snapshot.enabled,
+                level: this.config.hooks.snapshot.level || 'normal',
+                basePath: this.config.hooks.snapshot.basePath,
+                endpointIsolation: {
+                    enabled: this.config.hooks.snapshot.endpointIsolation.enabled,
+                    pathStructure: this.config.hooks.snapshot.endpointIsolation.pathStructure
+                }
+            }
+        };
+        return createHooksIntegration(adapterConfig);
+    }
+    createEndpointRouter() {
+        const defaultEndpoint = this.config.defaultProtocol === 'openai-chat'
+            ? 'chat'
+            : this.config.defaultProtocol === 'openai-responses'
+                ? 'responses'
+                : 'messages';
+        const routerConfig = {
+            defaultEndpoint,
+            endpointConfigs: this.config.endpoints,
+            autoDetect: true,
+            fallbackEnabled: false // 零fallback原则
+        };
+        return new EndpointRouter(this.hooksAdapter, routerConfig);
+    }
+    /**
+     * 注册默认的工具治理 Hooks：
+     * - request_4_tools_pre: 请求侧仅做 augment + 指引注入（不做文本→工具）
+     * - response_3_tools_pre: 响应侧做文本→工具；Responses 非流追加 required_action
+     *
+     * DISABLED: Tool governance is now handled exclusively in ChatProcessNode (conversion-v3)
+     * to avoid duplicate processing and interference with TOON decoding.
+     */
+    registerDefaultToolHooks() {
+        // Tool governance is now centralized in conversion-v3/ChatProcessNode
+        // These hooks are disabled to prevent duplicate processing
+        return;
+        /* DISABLED - DO NOT RE-ENABLE WITHOUT UPDATING ChatProcessNode
+        try {
+          const h: any = this.hooksAdapter as any;
+          if (!h || typeof h.registerHookHandler !== 'function') return;
+    
+          // 请求侧 Hooks
+          h.registerHookHandler('request_4_tools_pre', async (params: any) => {
+            try {
+              const mod = await import('../conversion/shared/tool-governor.js');
+              const { governTools } = mod as any;
+              const out = governTools(params.data, {
+                phase: 'request',
+                endpoint: params?.context?.endpoint || 'chat',
+                requestId: params?.context?.requestId,
+                snapshot: { enabled: true, endpoint: params?.context?.endpoint || 'chat', requestId: params?.context?.requestId }
+              });
+              return { success: true, data: out };
+            } catch (e) {
+              return { success: true, data: params.data };
+            }
+          });
+    
+          // 响应侧 Hooks
+          h.registerHookHandler('response_3_tools_pre', async (params: any) => {
+            try {
+              const mod = await import('../conversion/shared/tool-governor.js');
+              const { governTools } = mod as any;
+              const ep = params?.context?.endpoint || 'chat';
+              const out = governTools(params.data, {
+                phase: 'response',
+                endpoint: ep,
+                stream: params?.context?.processingMode === 'streaming',
+                // 在 tools_pre 阶段仅做 canonicalize，不合成 required_action
+                produceRequiredAction: false,
+                requestId: params?.context?.requestId
+              });
+              return { success: true, data: out };
+            } catch (e) {
+              return { success: true, data: params.data };
+            }
+          });
+    
+          // Responses 非流的 required_action 生成在 formatting_post 阶段进行
+          h.registerHookHandler('response_5_formatting_post', async (params: any) => {
+            try {
+              const mod = await import('../conversion/shared/tool-governor.js');
+              const { governTools } = mod as any;
+              const ep = params?.context?.endpoint || 'chat';
+              const out = governTools(params.data, {
+                phase: 'response',
+                endpoint: ep,
+                stream: params?.context?.processingMode === 'streaming',
+                produceRequiredAction: (ep === 'responses'),
+                requestId: params?.context?.requestId
+              });
+              return { success: true, data: out };
+            } catch (e) {
+              return { success: true, data: params.data };
+            }
+          });
+        } catch { }
+        */
+    }
+    validateConfig() {
+        if (!this.config.version) {
+            throw new Error('Version is required');
+        }
+        if (!this.config.endpoints || Object.keys(this.config.endpoints).length === 0) {
+            throw new Error('At least one endpoint must be configured');
+        }
+    }
+    detectProcessingMode(request) {
+        return request.stream === true ? 'streaming' : 'non-streaming';
+    }
+    detectEndpointFromPayload(payload) {
+        // 基于payload内容检测端点类型
+        if (payload.messages) {
+            return 'chat';
+        }
+        if (payload.input) {
+            return 'responses';
+        }
+        return 'messages';
+    }
+    generateRequestId() {
+        return `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    generateExecutionId() {
+        return `exec-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    generatePathIdentifier(request, endpoint) {
+        return `${endpoint}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    getEndpointPath(endpoint) {
+        switch (endpoint) {
+            case 'chat':
+                return '/v1/chat/completions';
+            case 'responses':
+                return '/v1/responses';
+            case 'messages':
+                return '/v1/messages';
+            default:
+                return '/v1/chat/completions';
+        }
+    }
+    initializeMetrics() {
+        return {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            averageProcessingTime: 0,
+            endpointMetrics: {
+                chat: { requestCount: 0, averageTime: 0, errorRate: 0 },
+                responses: { requestCount: 0, averageTime: 0, errorRate: 0 },
+                messages: { requestCount: 0, averageTime: 0, errorRate: 0 }
+            },
+            protocolMetrics: {
+                'openai-chat': { conversionCount: 0, successRate: 0, averageTime: 0 },
+                'openai-responses': { conversionCount: 0, successRate: 0, averageTime: 0 },
+                'anthropic-messages': { conversionCount: 0, successRate: 0, averageTime: 0 }
+            },
+            hookMetrics: {}
+        };
+    }
+    // Hook管理方法实现
+    registerHookHandler(stage, handler) {
+        this.hookHandlers.set(stage, handler);
+    }
+    unregisterHookHandler(stage) {
+        this.hookHandlers.delete(stage);
+    }
+    getHookStats() {
+        return {
+            registeredHandlers: this.hookHandlers.size,
+            stages: Array.from(this.hookHandlers.keys())
+        };
+    }
+    // ===== V2 新增接口方法实现 =====
+    /**
+     * V2 核心功能：请求预处理（为workflow准备）
+     */
+    async preprocessRequest(request, endpoint, context) {
+        return this.processRequest(request, endpoint, context);
+    }
+    /**
+     * V2 核心功能：响应后处理（从workflow接收）
+     */
+    async postprocessResponse(response, originalEndpoint, context) {
+        return this.processResponse(response, originalEndpoint, context);
+    }
+    /**
+     * 协议转换到统一格式（为workflow准备）
+     */
+    async convertToUnifiedProtocol(request, sourceProtocol) {
+        // 简化实现，实际应该根据sourceProtocol进行相应转换
+        return {
+            sourceProtocol,
+            targetProtocol: this.config.defaultProtocol,
+            payload: request,
+            conversionTime: Date.now()
+        };
+    }
+    /**
+     * 统一工具处理（三端工具调用的唯一入口）
+     */
+    async processToolCalls(request, endpoint) {
+        return {
+            tools: request.tools || [],
+            toolCalls: request.tool_calls || [],
+            executionMode: request.stream ? 'streaming' : 'non-streaming',
+            requestId: this.generateRequestId(),
+            processingTime: 0,
+            endpoint
+        };
+    }
+    /**
+     * 系统工具指引注入
+     */
+    async injectSystemToolGuidance(request, tools) {
+        // 简化实现，实际应该注入系统工具指引
+        return {
+            ...request,
+            systemToolGuidance: {
+                tools,
+                injectedAt: Date.now()
+            }
+        };
+    }
+    /**
+     * 流式请求预处理
+     */
+    async preprocessStreamingRequest(request, endpoint, context) {
+        return this.processStreamingRequest(request, endpoint, context);
+    }
+    /**
+     * 流式响应后处理
+     */
+    async postprocessStreamingResponse(events, originalEndpoint, context) {
+        // 简化实现，直接返回原事件流
+        return events;
+    }
+    /**
+     * 获取配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * 获取指标
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    // ===== 缺失的Hook管理方法 =====
+    /**
+     * 执行Hooks
+     */
+    async executeHooks(stage, context, data) {
+        const handler = this.hookHandlers.get(stage);
+        if (handler) {
+            return await handler(context, data);
+        }
+        return { success: true, data };
+    }
+    /**
+     * 捕获快照
+     */
+    async captureSnapshot(stage, context, data) {
+        // 简化实现，实际应该调用SnapshotService
+        console.log(`Capturing snapshot for stage: ${stage}`);
+    }
+    /**
+     * 获取快照路径
+     */
+    getSnapshotPath(stage, context) {
+        // 简化实现，实际应该生成基于端点的路径
+        return `snapshots/${context.endpoint}/${stage}/${context.requestId}`;
+    }
+}