@jsonstudio/llms 0.4.2

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 工具函数模块导出
+ */
+export { RequestIdGenerator, RequestValidator, RequestTransformer, RequestContextBuilder, RequestTracker } from './request-utils.js';
+export { ResponseNormalizer, ResponseValidator, ResponseProcessor, ResponseCache } from './response-utils.js';
+export { PerformanceMonitor, PerformanceTimer, MemoryMonitor, PerformanceReporter, type PerformanceMetrics } from './performance-utils.js';
+export { TokenCounter } from './token-counter.js';
+export { LLMSwitchErrorType, ErrorFactory, ErrorHandler, ErrorRecovery, DefaultRecoveryStrategies, type RecoveryStrategy, type RecoveryResult } from './error-utils.js';

package/dist/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * 工具函数模块导出
+ */
+// 请求工具
+export { RequestIdGenerator, RequestValidator, RequestTransformer, RequestContextBuilder, RequestTracker } from './request-utils.js';
+// 响应工具
+export { ResponseNormalizer, ResponseValidator, ResponseProcessor, ResponseCache } from './response-utils.js';
+// 性能工具
+export { PerformanceMonitor, PerformanceTimer, MemoryMonitor, PerformanceReporter } from './performance-utils.js';
+// Token计数工具（提供tiktoken优先的智能Token计算接口）
+export { TokenCounter } from './token-counter.js';
+// 错误工具
+export { LLMSwitchErrorType, ErrorFactory, ErrorHandler, ErrorRecovery, DefaultRecoveryStrategies } from './error-utils.js';

package/dist/utils/performance-utils.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 性能监控工具函数
+ */
+import type { LLMSwitchHookContext } from '../api/llmswitch-types.js';
+/**
+ * 性能指标接口
+ */
+export interface PerformanceMetrics {
+    requestId: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    memoryUsage?: {
+        initial: number;
+        final: number;
+        peak: number;
+    };
+    tokenMetrics?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        tokensPerSecond?: number;
+    };
+    hookMetrics?: {
+        [hookStage: string]: {
+            duration: number;
+            success: boolean;
+            error?: string;
+        };
+    };
+    networkMetrics?: {
+        requestSize: number;
+        responseSize: number;
+        connectionTime?: number;
+        dnsTime?: number;
+        tlsTime?: number;
+    };
+}
+/**
+ * 性能监控器
+ */
+export declare class PerformanceMonitor {
+    private static metrics;
+    private static memoryBaseline;
+    /**
+     * 开始监控请求
+     */
+    static startMonitoring(requestId: string, context: LLMSwitchHookContext): PerformanceMetrics;
+    /**
+     * 结束监控请求
+     */
+    static endMonitoring(requestId: string): PerformanceMetrics | null;
+    /**
+     * 记录Hook性能
+     */
+    static recordHookPerformance(requestId: string, hookStage: string, duration: number, success: boolean, error?: string): void;
+    /**
+     * 设置Token指标
+     */
+    static setTokenMetrics(requestId: string, inputTokens: number, outputTokens: number, totalTokens?: number): void;
+    /**
+     * 设置网络指标
+     */
+    static setNetworkMetrics(requestId: string, requestSize: number, responseSize: number, connectionTime?: number, dnsTime?: number, tlsTime?: number): void;
+    /**
+     * 获取性能指标
+     */
+    static getMetrics(requestId: string): PerformanceMetrics | null;
+    /**
+     * 获取所有指标
+     */
+    static getAllMetrics(): PerformanceMetrics[];
+    /**
+     * 清理指标
+     */
+    static clearMetrics(requestId?: string): void;
+    /**
+     * 获取性能统计
+     */
+    static getPerformanceStats(): {
+        totalRequests: number;
+        averageDuration: number;
+        averageTokensPerSecond: number;
+        memoryUsageStats: {
+            average: number;
+            peak: number;
+            baseline: number;
+        };
+        hookPerformanceStats: {
+            [hookStage: string]: {
+                averageDuration: number;
+                successRate: number;
+                callCount: number;
+            };
+        };
+    };
+    /**
+     * 清理过期指标
+     */
+    static cleanupExpiredMetrics(maxAge?: number): void;
+}
+/**
+ * 性能计时器
+ */
+export declare class PerformanceTimer {
+    private startTime;
+    private endTime?;
+    private checkpoints;
+    constructor();
+    /**
+     * 设置检查点
+     */
+    checkpoint(name: string): number;
+    /**
+     * 获取从开始到检查点的持续时间
+     */
+    getDurationFromStart(checkpointName?: string): number;
+    /**
+     * 获取两个检查点之间的持续时间
+     */
+    getDurationBetween(from: string, to: string): number;
+    /**
+     * 结束计时
+     */
+    end(): number;
+    /**
+     * 获取总持续时间
+     */
+    getTotalDuration(): number;
+    /**
+     * 获取所有检查点
+     */
+    getCheckpoints(): Map<string, number>;
+    /**
+     * 重置计时器
+     */
+    reset(): void;
+}
+/**
+ * 内存监控器
+ */
+export declare class MemoryMonitor {
+    private static baseline;
+    private static measurements;
+    /**
+     * 记录内存使用
+     */
+    static record(label?: string): NodeJS.MemoryUsage;
+    /**
+     * 获取内存增长
+     */
+    static getMemoryGrowth(): {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        arrayBuffers: number;
+    };
+    /**
+     * 获取内存使用趋势
+     */
+    static getMemoryTrend(minutes?: number): {
+        trend: 'increasing' | 'decreasing' | 'stable';
+        rate: number;
+        confidence: number;
+    };
+    /**
+     * 检测内存泄漏
+     */
+    static detectMemoryLeak(threshold?: number): {
+        detected: boolean;
+        growth: number;
+        trend: string;
+    };
+    /**
+     * 清理测量数据
+     */
+    static cleanup(): void;
+    /**
+     * 重置基线
+     */
+    static resetBaseline(): void;
+}
+/**
+ * 性能报告生成器
+ */
+export declare class PerformanceReporter {
+    /**
+     * 生成性能报告
+     */
+    static generateReport(): {
+        timestamp: number;
+        summary: any;
+        detailed: any;
+        memory: any;
+        recommendations: string[];
+    };
+    /**
+     * 生成JSON报告
+     */
+    static generateJSONReport(): string;
+    /**
+     * 生成Markdown报告
+     */
+    static generateMarkdownReport(): string;
+}

package/dist/utils/performance-utils.js

@@ -0,0 +1,440 @@
+/**
+ * 性能监控工具函数
+ */
+/**
+ * 性能监控器
+ */
+export class PerformanceMonitor {
+    static metrics = new Map();
+    static memoryBaseline = process.memoryUsage();
+    /**
+     * 开始监控请求
+     */
+    static startMonitoring(requestId, context) {
+        const metrics = {
+            requestId,
+            startTime: Date.now(),
+            memoryUsage: {
+                initial: process.memoryUsage().heapUsed,
+                final: 0,
+                peak: process.memoryUsage().heapUsed
+            }
+        };
+        this.metrics.set(requestId, metrics);
+        return metrics;
+    }
+    /**
+     * 结束监控请求
+     */
+    static endMonitoring(requestId) {
+        const metrics = this.metrics.get(requestId);
+        if (!metrics) {
+            return null;
+        }
+        metrics.endTime = Date.now();
+        metrics.duration = metrics.endTime - metrics.startTime;
+        if (metrics.memoryUsage) {
+            metrics.memoryUsage.final = process.memoryUsage().heapUsed;
+        }
+        // 计算token处理速度
+        if (metrics.tokenMetrics && metrics.duration) {
+            metrics.tokenMetrics.tokensPerSecond =
+                metrics.tokenMetrics.totalTokens / (metrics.duration / 1000);
+        }
+        return metrics;
+    }
+    /**
+     * 记录Hook性能
+     */
+    static recordHookPerformance(requestId, hookStage, duration, success, error) {
+        const metrics = this.metrics.get(requestId);
+        if (!metrics) {
+            return;
+        }
+        if (!metrics.hookMetrics) {
+            metrics.hookMetrics = {};
+        }
+        metrics.hookMetrics[hookStage] = {
+            duration,
+            success,
+            error
+        };
+        // 更新峰值内存使用
+        const currentMemory = process.memoryUsage().heapUsed;
+        if (metrics.memoryUsage && currentMemory > metrics.memoryUsage.peak) {
+            metrics.memoryUsage.peak = currentMemory;
+        }
+    }
+    /**
+     * 设置Token指标
+     */
+    static setTokenMetrics(requestId, inputTokens, outputTokens, totalTokens) {
+        const metrics = this.metrics.get(requestId);
+        if (!metrics) {
+            return;
+        }
+        metrics.tokenMetrics = {
+            inputTokens,
+            outputTokens,
+            totalTokens: totalTokens || inputTokens + outputTokens
+        };
+    }
+    /**
+     * 设置网络指标
+     */
+    static setNetworkMetrics(requestId, requestSize, responseSize, connectionTime, dnsTime, tlsTime) {
+        const metrics = this.metrics.get(requestId);
+        if (!metrics) {
+            return;
+        }
+        metrics.networkMetrics = {
+            requestSize,
+            responseSize,
+            connectionTime,
+            dnsTime,
+            tlsTime
+        };
+    }
+    /**
+     * 获取性能指标
+     */
+    static getMetrics(requestId) {
+        return this.metrics.get(requestId) || null;
+    }
+    /**
+     * 获取所有指标
+     */
+    static getAllMetrics() {
+        return Array.from(this.metrics.values());
+    }
+    /**
+     * 清理指标
+     */
+    static clearMetrics(requestId) {
+        if (requestId) {
+            this.metrics.delete(requestId);
+        }
+        else {
+            this.metrics.clear();
+        }
+    }
+    /**
+     * 获取性能统计
+     */
+    static getPerformanceStats() {
+        const metrics = Array.from(this.metrics.values()).filter(m => m.duration);
+        if (metrics.length === 0) {
+            return {
+                totalRequests: 0,
+                averageDuration: 0,
+                averageTokensPerSecond: 0,
+                memoryUsageStats: { average: 0, peak: 0, baseline: this.memoryBaseline.heapUsed },
+                hookPerformanceStats: {}
+            };
+        }
+        const totalDuration = metrics.reduce((sum, m) => sum + (m.duration || 0), 0);
+        const averageDuration = totalDuration / metrics.length;
+        // 计算token处理速度
+        const tokenMetrics = metrics.filter(m => m.tokenMetrics?.tokensPerSecond);
+        const averageTokensPerSecond = tokenMetrics.length > 0
+            ? tokenMetrics.reduce((sum, m) => sum + (m.tokenMetrics?.tokensPerSecond || 0), 0) / tokenMetrics.length
+            : 0;
+        // 计算内存使用统计
+        const memoryUsages = metrics.map(m => (m.memoryUsage?.final || 0) - (m.memoryUsage?.initial || 0));
+        const averageMemoryUsage = memoryUsages.reduce((sum, usage) => sum + usage, 0) / memoryUsages.length;
+        const peakMemoryUsage = Math.max(...metrics.map(m => m.memoryUsage?.peak || 0));
+        // 计算Hook性能统计
+        const hookStats = {};
+        const allHookMetrics = metrics.flatMap(m => Object.entries(m.hookMetrics || {}));
+        for (const [hookStage, hookMetric] of allHookMetrics) {
+            if (!hookStats[hookStage]) {
+                hookStats[hookStage] = {
+                    totalDuration: 0,
+                    successCount: 0,
+                    totalCount: 0
+                };
+            }
+            hookStats[hookStage].totalDuration += hookMetric.duration;
+            if (hookMetric.success) {
+                hookStats[hookStage].successCount++;
+            }
+            hookStats[hookStage].totalCount++;
+        }
+        const hookPerformanceStats = {};
+        for (const [hookStage, stats] of Object.entries(hookStats)) {
+            hookPerformanceStats[hookStage] = {
+                averageDuration: stats.totalDuration / stats.totalCount,
+                successRate: stats.successCount / stats.totalCount,
+                callCount: stats.totalCount
+            };
+        }
+        return {
+            totalRequests: metrics.length,
+            averageDuration,
+            averageTokensPerSecond,
+            memoryUsageStats: {
+                average: averageMemoryUsage,
+                peak: peakMemoryUsage,
+                baseline: this.memoryBaseline.heapUsed
+            },
+            hookPerformanceStats
+        };
+    }
+    /**
+     * 清理过期指标
+     */
+    static cleanupExpiredMetrics(maxAge = 3600000) {
+        const now = Date.now();
+        const expiredRequests = [];
+        for (const [requestId, metrics] of this.metrics) {
+            if (now - (metrics.endTime || metrics.startTime) > maxAge) {
+                expiredRequests.push(requestId);
+            }
+        }
+        for (const requestId of expiredRequests) {
+            this.metrics.delete(requestId);
+        }
+    }
+}
+/**
+ * 性能计时器
+ */
+export class PerformanceTimer {
+    startTime;
+    endTime;
+    checkpoints = new Map();
+    constructor() {
+        this.startTime = Date.now();
+    }
+    /**
+     * 设置检查点
+     */
+    checkpoint(name) {
+        const time = Date.now();
+        this.checkpoints.set(name, time);
+        return time;
+    }
+    /**
+     * 获取从开始到检查点的持续时间
+     */
+    getDurationFromStart(checkpointName) {
+        const endTime = checkpointName ? this.checkpoints.get(checkpointName) : Date.now();
+        return (endTime || 0) - this.startTime;
+    }
+    /**
+     * 获取两个检查点之间的持续时间
+     */
+    getDurationBetween(from, to) {
+        const fromTime = this.checkpoints.get(from);
+        const toTime = this.checkpoints.get(to);
+        if (fromTime === undefined || toTime === undefined) {
+            throw new Error(`检查点 ${from} 或 ${to} 不存在`);
+        }
+        return toTime - fromTime;
+    }
+    /**
+     * 结束计时
+     */
+    end() {
+        this.endTime = Date.now();
+        return this.endTime - this.startTime;
+    }
+    /**
+     * 获取总持续时间
+     */
+    getTotalDuration() {
+        const endTime = this.endTime || Date.now();
+        return endTime - this.startTime;
+    }
+    /**
+     * 获取所有检查点
+     */
+    getCheckpoints() {
+        return new Map(this.checkpoints);
+    }
+    /**
+     * 重置计时器
+     */
+    reset() {
+        this.startTime = Date.now();
+        this.endTime = undefined;
+        this.checkpoints.clear();
+    }
+}
+/**
+ * 内存监控器
+ */
+export class MemoryMonitor {
+    static baseline = process.memoryUsage();
+    static measurements = [];
+    /**
+     * 记录内存使用
+     */
+    static record(label) {
+        const usage = process.memoryUsage();
+        this.measurements.push({
+            timestamp: Date.now(),
+            usage: { ...usage },
+            label
+        });
+        // 保持最近1000次测量
+        if (this.measurements.length > 1000) {
+            this.measurements = this.measurements.slice(-1000);
+        }
+        return usage;
+    }
+    /**
+     * 获取内存增长
+     */
+    static getMemoryGrowth() {
+        const current = process.memoryUsage();
+        const baseline = this.baseline;
+        return {
+            heapUsed: current.heapUsed - baseline.heapUsed,
+            heapTotal: current.heapTotal - baseline.heapTotal,
+            external: current.external - baseline.external,
+            arrayBuffers: current.arrayBuffers - baseline.arrayBuffers
+        };
+    }
+    /**
+     * 获取内存使用趋势
+     */
+    static getMemoryTrend(minutes = 10) {
+        const cutoff = Date.now() - (minutes * 60 * 1000);
+        const relevant = this.measurements.filter(m => m.timestamp >= cutoff);
+        if (relevant.length < 2) {
+            return { trend: 'stable', rate: 0, confidence: 0 };
+        }
+        const first = relevant[0];
+        const last = relevant[relevant.length - 1];
+        const timeDiff = (last.timestamp - first.timestamp) / (60 * 1000); // 分钟
+        const memoryDiff = last.usage.heapUsed - first.usage.heapUsed;
+        const rate = memoryDiff / timeDiff;
+        // 计算趋势的置信度（基于数据点的线性相关性）
+        const n = relevant.length;
+        const x = relevant.map((_, i) => i);
+        const y = relevant.map(m => m.usage.heapUsed);
+        const sumX = x.reduce((a, b) => a + b, 0);
+        const sumY = y.reduce((a, b) => a + b, 0);
+        const sumXY = x.reduce((total, xi, i) => total + xi * y[i], 0);
+        const sumX2 = x.reduce((total, xi) => total + xi * xi, 0);
+        const correlation = (n * sumXY - sumX * sumY) /
+            Math.sqrt((n * sumX2 - sumX * sumX) * (n * sumY * sumY - sumY * sumY));
+        let trend;
+        if (Math.abs(rate) < 1024 * 1024) { // 小于1MB/分钟认为是稳定的
+            trend = 'stable';
+        }
+        else if (rate > 0) {
+            trend = 'increasing';
+        }
+        else {
+            trend = 'decreasing';
+        }
+        return {
+            trend,
+            rate,
+            confidence: Math.abs(correlation)
+        };
+    }
+    /**
+     * 检测内存泄漏
+     */
+    static detectMemoryLeak(threshold = 50 * 1024 * 1024) {
+        const growth = this.getMemoryGrowth();
+        const trend = this.getMemoryTrend(30); // 30分钟趋势
+        return {
+            detected: growth.heapUsed > threshold && trend.trend === 'increasing' && trend.confidence > 0.7,
+            growth: growth.heapUsed,
+            trend: `${trend.trend} (${(trend.rate / (1024 * 1024)).toFixed(2)}MB/min)`
+        };
+    }
+    /**
+     * 清理测量数据
+     */
+    static cleanup() {
+        this.measurements = [];
+    }
+    /**
+     * 重置基线
+     */
+    static resetBaseline() {
+        this.baseline = process.memoryUsage();
+    }
+}
+/**
+ * 性能报告生成器
+ */
+export class PerformanceReporter {
+    /**
+     * 生成性能报告
+     */
+    static generateReport() {
+        const stats = PerformanceMonitor.getPerformanceStats();
+        const memoryLeak = MemoryMonitor.detectMemoryLeak();
+        const memoryTrend = MemoryMonitor.getMemoryTrend();
+        const recommendations = [];
+        // 生成建议
+        if (stats.averageDuration > 5000) {
+            recommendations.push('平均响应时间较长，考虑优化处理逻辑或增加超时设置');
+        }
+        if (stats.averageTokensPerSecond < 10) {
+            recommendations.push('Token处理速度较慢，可能存在性能瓶颈');
+        }
+        if (memoryLeak.detected) {
+            recommendations.push('检测到可能的内存泄漏，建议检查长期运行的请求');
+        }
+        if (memoryTrend.trend === 'increasing' && memoryTrend.rate > 10 * 1024 * 1024) {
+            recommendations.push('内存使用呈快速增长趋势，建议监控内存使用情况');
+        }
+        // 找出最慢的Hook
+        const slowHooks = Object.entries(stats.hookPerformanceStats)
+            .filter(([_, stats]) => stats.averageDuration > 100)
+            .sort((a, b) => b[1].averageDuration - a[1].averageDuration)
+            .slice(0, 3);
+        if (slowHooks.length > 0) {
+            recommendations.push(`以下Hook执行较慢: ${slowHooks.map(([name]) => name).join(', ')}`);
+        }
+        return {
+            timestamp: Date.now(),
+            summary: stats,
+            detailed: {
+                slowHooks,
+                memoryLeak,
+                memoryTrend
+            },
+            memory: {
+                current: process.memoryUsage(),
+                growth: MemoryMonitor.getMemoryGrowth(),
+                measurements: MemoryMonitor['measurements'].length
+            },
+            recommendations
+        };
+    }
+    /**
+     * 生成JSON报告
+     */
+    static generateJSONReport() {
+        return JSON.stringify(this.generateReport(), null, 2);
+    }
+    /**
+     * 生成Markdown报告
+     */
+    static generateMarkdownReport() {
+        const report = this.generateReport();
+        let markdown = `# 性能监控报告\n\n`;
+        markdown += `生成时间: ${new Date(report.timestamp).toISOString()}\n\n`;
+        markdown += `## 性能概览\n\n`;
+        markdown += `- 总请求数: ${report.summary.totalRequests}\n`;
+        markdown += `- 平均响应时间: ${report.summary.averageDuration.toFixed(2)}ms\n`;
+        markdown += `- 平均Token处理速度: ${report.summary.averageTokensPerSecond.toFixed(2)} tokens/s\n`;
+        markdown += `- 内存使用增长: ${(report.memory.growth.heapUsed / (1024 * 1024)).toFixed(2)}MB\n\n`;
+        if (report.recommendations.length > 0) {
+            markdown += `## 性能建议\n\n`;
+            for (const recommendation of report.recommendations) {
+                markdown += `- ${recommendation}\n`;
+            }
+            markdown += `\n`;
+        }
+        return markdown;
+    }
+}

package/dist/utils/profile-mapper.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 兼容配置映射器（可选）
+ *
+ * 将既有转换配置映射到V2端点配置（不依赖旧版本命名）。
+ */
+import type { ConversionProfile } from '../conversion/types.js';
+import type { LLMSwitchV2Config, EndpointConfig } from '../api/llmswitch-types.js';
+/**
+ * 旧版转换配置映射到 V2 端点配置（Legacy → V2）
+ */
+export declare class LegacyConfigMapper {
+    /**
+     * 将旧版 ConversionProfile 转换为 V2 的 EndpointConfig
+     */
+    static mapProfileToV2Endpoint(profile: ConversionProfile): EndpointConfig;
+    /**
+     * 将旧版 codec 映射到端点类型
+     */
+    private static mapCodecToEndpoint;
+    /**
+     * 将旧版 codec 映射到协议类型
+     */
+    private static mapCodecToProtocol;
+    /**
+     * 将旧版 hooks 映射到 V2 的 hook 阶段
+     */
+    private static mapHooksToV2Stages;
+    /**
+     * 从旧版配置文件生成 V2 配置（占位实现）
+     */
+    static generateV2ConfigFromLegacy(profilesPath: string): Promise<LLMSwitchV2Config>;
+}