@jsonstudio/rcc 0.89.611 → 0.89.683

package/node_modules/@jsonstudio/llms/dist/router/virtual-router/engine.js

@@ -1,1273 +0,0 @@
-import { ProviderHealthManager } from './health-manager.js';
-import { ProviderRegistry } from './provider-registry.js';
-import { RouteLoadBalancer } from './load-balancer.js';
-import { RoutingClassifier } from './classifier.js';
-import { buildRoutingFeatures } from './features.js';
-import { ContextAdvisor } from './context-advisor.js';
-import { DEFAULT_MODEL_CONTEXT_TOKENS, DEFAULT_ROUTE, ROUTE_PRIORITY, VirtualRouterError, VirtualRouterErrorCode } from './types.js';
-import { getStatsCenter } from '../../telemetry/stats-center.js';
-import { parseRoutingInstructions, applyRoutingInstructions, cleanMessagesFromRoutingInstructions } from './routing-instructions.js';
-import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync } from './sticky-session-store.js';
-export class VirtualRouterEngine {
-    routing = {};
-    providerRegistry = new ProviderRegistry();
-    healthManager = new ProviderHealthManager();
-    loadBalancer = new RouteLoadBalancer();
-    classifier = new RoutingClassifier({});
-    contextAdvisor = new ContextAdvisor();
-    contextRouting;
-    routeStats = new Map();
-    debug = console; // thin hook; host may monkey-patch for colored logging
-    healthConfig = null;
-    statsCenter = getStatsCenter();
-    // Derived flags from VirtualRouterConfig/routing used by process / response layers.
-    webSearchForce = false;
-    routingInstructionState = new Map();
-    initialize(config) {
-        this.validateConfig(config);
-        this.routing = config.routing;
-        this.providerRegistry.load(config.providers);
-        this.healthManager.configure(config.health);
-        this.healthConfig = config.health ?? null;
-        this.healthManager.registerProviders(Object.keys(config.providers));
-        this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
-        this.classifier = new RoutingClassifier(config.classifier);
-        this.contextRouting = config.contextRouting ?? { warnRatio: 0.9, hardLimit: false };
-        this.contextAdvisor.configure(this.contextRouting);
-        this.webSearchForce = config.webSearch?.force === true;
-        this.routeStats = new Map();
-        for (const routeName of Object.keys(this.routing)) {
-            this.routeStats.set(routeName, { hits: 0 });
-        }
-    }
-    route(request, metadata) {
-        const stickyKey = this.resolveStickyKey(metadata);
-        const baseState = this.getRoutingInstructionState(stickyKey);
-        let routingState = baseState;
-        const metadataInstructions = this.buildMetadataInstructions(metadata);
-        if (metadataInstructions.length > 0) {
-            routingState = applyRoutingInstructions(metadataInstructions, routingState);
-        }
-        const instructions = parseRoutingInstructions(request.messages);
-        if (instructions.length > 0) {
-            routingState = applyRoutingInstructions(instructions, routingState);
-            const effectiveKey = stickyKey || 'default';
-            this.routingInstructionState.set(effectiveKey, routingState);
-            request.messages = cleanMessagesFromRoutingInstructions(request.messages);
-            this.persistRoutingInstructionState(effectiveKey, routingState);
-        }
-        const routingMode = this.resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
-        const features = buildRoutingFeatures(request, metadata);
-        const classification = metadata.routeHint && metadata.routeHint.trim()
-            ? {
-                routeName: metadata.routeHint.trim(),
-                confidence: 1,
-                reasoning: `route_hint:${metadata.routeHint.trim()}`,
-                fallback: false,
-                candidates: [metadata.routeHint.trim()]
-            }
-            : this.classifier.classify(features);
-        const requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
-        const selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
-        const baseTarget = this.providerRegistry.buildTarget(selection.providerKey);
-        const forceVision = this.routeHasForceFlag('vision');
-        const target = {
-            ...baseTarget,
-            ...(this.webSearchForce ? { forceWebSearch: true } : {}),
-            ...(forceVision ? { forceVision: true } : {})
-        };
-        this.healthManager.recordSuccess(selection.providerKey);
-        this.incrementRouteStat(selection.routeUsed, selection.providerKey);
-        try {
-            this.statsCenter.recordVirtualRouterHit({
-                requestId: metadata.requestId,
-                timestamp: Date.now(),
-                entryEndpoint: metadata.entryEndpoint || '/v1/chat/completions',
-                routeName: selection.routeUsed,
-                pool: selection.poolId || selection.routeUsed,
-                providerKey: selection.providerKey,
-                modelId: target.modelId || undefined
-            });
-        }
-        catch {
-            // stats must never break routing
-        }
-        const hitReason = this.buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode);
-        const stickyScope = routingMode !== 'none' ? this.resolveSessionScope(metadata) : undefined;
-        const routeForLog = routingMode === 'sticky' ? 'sticky' : selection.routeUsed;
-        const formatted = this.formatVirtualRouterHit(routeForLog, selection.poolId, selection.providerKey, target.modelId || '', hitReason, stickyScope);
-        if (formatted) {
-            this.debug?.log?.(formatted);
-        }
-        else {
-            this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
-        }
-        const didFallback = selection.routeUsed !== requestedRoute;
-        return {
-            target,
-            decision: {
-                routeName: selection.routeUsed,
-                providerKey: selection.providerKey,
-                pool: selection.pool,
-                poolId: selection.poolId,
-                confidence: classification.confidence,
-                reasoning: classification.reasoning,
-                fallback: didFallback
-            },
-            diagnostics: {
-                routeName: selection.routeUsed,
-                providerKey: selection.providerKey,
-                pool: selection.pool,
-                poolId: selection.poolId,
-                reasoning: classification.reasoning,
-                fallback: didFallback,
-                confidence: classification.confidence
-            }
-        };
-    }
-    handleProviderFailure(event) {
-        if (!event || !event.providerKey) {
-            return;
-        }
-        if (event.affectsHealth === false) {
-            return;
-        }
-        if (event.fatal) {
-            this.healthManager.tripProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
-        }
-        else if (event.reason === 'rate_limit' && event.statusCode === 429) {
-            // 对可恢复的 429 错误使用短冷静期：在 cooldownMs 内将该 key 标记为不可用，
-            // 以便 Virtual Router 在随后的选路中优先尝试其他 key 或模型。
-            this.healthManager.cooldownProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
-        }
-        else {
-            this.healthManager.recordFailure(event.providerKey, event.reason);
-        }
-    }
-    handleProviderError(event) {
-        const derived = this.mapProviderError(event);
-        if (!derived) {
-            return;
-        }
-        this.handleProviderFailure(derived);
-    }
-    getStatus() {
-        const routes = {};
-        for (const [route, pools] of Object.entries(this.routing)) {
-            const stats = this.routeStats.get(route) ?? { hits: 0 };
-            routes[route] = {
-                providers: this.flattenPoolTargets(pools),
-                hits: stats.hits,
-                lastUsedProvider: stats.lastProvider
-            };
-        }
-        return {
-            routes,
-            health: this.healthManager.getSnapshot()
-        };
-    }
-    /**
-     * 将分类器产生的逻辑路由名直接归一化为配置中的路由键。
-     * 不再维护 "websearch" 之类的别名，调用方应显式使用 "web_search" 或 "search" 等实际路由名。
-     */
-    normalizeRouteAlias(routeName) {
-        const base = routeName && routeName.trim() ? routeName.trim() : DEFAULT_ROUTE;
-        return base;
-    }
-    validateConfig(config) {
-        if (!config.routing || typeof config.routing !== 'object') {
-            throw new VirtualRouterError('routing configuration is required', VirtualRouterErrorCode.CONFIG_ERROR);
-        }
-        if (!config.providers || Object.keys(config.providers).length === 0) {
-            throw new VirtualRouterError('providers configuration is required', VirtualRouterErrorCode.CONFIG_ERROR);
-        }
-        const defaultPools = config.routing[DEFAULT_ROUTE];
-        if (!this.routeHasTargets(defaultPools)) {
-            throw new VirtualRouterError('default route must be configured with at least one provider', VirtualRouterErrorCode.CONFIG_ERROR);
-        }
-        if (!this.hasPrimaryPool(defaultPools)) {
-            throw new VirtualRouterError('default route must define at least one non-backup pool', VirtualRouterErrorCode.CONFIG_ERROR);
-        }
-        const providerKeys = new Set(Object.keys(config.providers));
-        for (const [routeName, pools] of Object.entries(config.routing)) {
-            if (!this.routeHasTargets(pools)) {
-                if (routeName === DEFAULT_ROUTE) {
-                    throw new VirtualRouterError('default route cannot be empty', VirtualRouterErrorCode.CONFIG_ERROR);
-                }
-                continue;
-            }
-            for (const pool of pools) {
-                if (!Array.isArray(pool.targets) || !pool.targets.length) {
-                    continue;
-                }
-                for (const providerKey of pool.targets) {
-                    if (!providerKeys.has(providerKey)) {
-                        throw new VirtualRouterError(`Route ${routeName} references unknown provider ${providerKey}`, VirtualRouterErrorCode.CONFIG_ERROR);
-                    }
-                }
-            }
-        }
-    }
-    selectProvider(requestedRoute, metadata, classification, features, routingState) {
-        const activeState = routingState || this.getRoutingInstructionState(this.resolveStickyKey(metadata));
-        const forcedResolution = activeState.forcedTarget
-            ? this.resolveInstructionTarget(activeState.forcedTarget)
-            : null;
-        if (forcedResolution && forcedResolution.mode === 'exact') {
-            const forcedKey = forcedResolution.keys[0];
-            return {
-                providerKey: forcedKey,
-                routeUsed: requestedRoute,
-                pool: [forcedKey],
-                poolId: 'forced'
-            };
-        }
-        // sticky 语义：
-        // - 显式绑定到具体 key（alias/index）时，直接使用该 key；
-        // - provider / model 级别 sticky 解析为一组 providerKey；
-        //   在 sticky 这组 key「可用」之前，不会回落到 default 中的非 sticky provider。
-        let stickyResolution = null;
-        let stickyKeySet;
-        if (!forcedResolution && activeState.stickyTarget) {
-            stickyResolution = this.resolveInstructionTarget(activeState.stickyTarget);
-            if (stickyResolution && stickyResolution.mode === 'exact') {
-                const stickyKey = stickyResolution.keys[0];
-                // 已经被健康管理标记为不可用的 key 不能被 sticky 语法“复活”
-                if (this.healthManager.isAvailable(stickyKey)) {
-                    return {
-                        providerKey: stickyKey,
-                        routeUsed: requestedRoute,
-                        pool: [stickyKey],
-                        poolId: 'sticky'
-                    };
-                }
-            }
-            if (stickyResolution && stickyResolution.mode === 'filter' && stickyResolution.keys.length > 0) {
-                // 仅保留当前仍可用的 key；已被熔断/拉黑的 key 不会被 sticky 语法重新加入池子
-                const liveKeys = stickyResolution.keys.filter((key) => this.healthManager.isAvailable(key));
-                if (liveKeys.length > 0) {
-                    stickyKeySet = new Set(liveKeys);
-                }
-            }
-        }
-        const allowAliasRotation = Boolean(activeState.stickyTarget) &&
-            !activeState.stickyTarget?.keyAlias &&
-            activeState.stickyTarget?.keyIndex === undefined;
-        // force(filter) 优先级高于 sticky：显式 force 视为覆盖 sticky 约束。
-        if (forcedResolution && forcedResolution.mode === 'filter') {
-            const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates, features);
-            const filteredCandidates = this.filterCandidatesByRoutingState(candidates, activeState);
-            if (filteredCandidates.length === 0) {
-                throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
-                    requestedRoute,
-                    allowedProviders: Array.from(activeState.allowedProviders),
-                    disabledProviders: Array.from(activeState.disabledProviders)
-                });
-            }
-            const forcedKeySet = new Set(forcedResolution.keys);
-            return this.selectFromCandidates(filteredCandidates, metadata, classification, features, activeState, forcedKeySet, allowAliasRotation);
-        }
-        if (stickyKeySet && stickyKeySet.size > 0) {
-            const stickySelection = this.selectFromStickyPool(stickyKeySet, metadata, features, activeState, allowAliasRotation);
-            if (stickySelection) {
-                return stickySelection;
-            }
-            // sticky 池在本次请求中完全不可用（全部被黑名单/健康状态过滤）：视为 sticky 池暂时失效，
-            // 本次回落到普通路由选择，但保留 stickyTarget，等待后续恢复。
-        }
-        // 无 sticky，或 sticky 池在本次请求中全部不可用（无可用 key）：按原始分类结果执行正常路由选择。
-        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates, features);
-        const filteredCandidates = this.filterCandidatesByRoutingState(candidates, activeState);
-        if (filteredCandidates.length === 0) {
-            throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
-                requestedRoute,
-                allowedProviders: Array.from(activeState.allowedProviders),
-                disabledProviders: Array.from(activeState.disabledProviders)
-            });
-        }
-        return this.selectFromCandidates(filteredCandidates, metadata, classification, features, activeState, undefined, allowAliasRotation);
-    }
-    trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features, disabledProviders, disabledKeysMap, allowedProviders, disabledModels, requiredProviderKeys, allowAliasRotation) {
-        let targets = Array.isArray(tier.targets) ? tier.targets : [];
-        // 基于本次请求 metadata 中的 excludedProviderKeys 做临时过滤：
-        // - 这些 key 仅在当前 route() 调用内被排除，不会写入 sticky 状态；
-        // - 主要用于 HTTP 层在同一请求内对 429 失败的 key 进行快速 failover。
-        const excludedRaw = features.metadata?.excludedProviderKeys &&
-            Array.isArray(features.metadata.excludedProviderKeys)
-            ? features.metadata.excludedProviderKeys
-            : [];
-        const excludedKeys = new Set(excludedRaw
-            .map((val) => (typeof val === 'string' ? val.trim() : ''))
-            .filter((val) => Boolean(val)));
-        if (excludedKeys.size > 0) {
-            targets = targets.filter((key) => !excludedKeys.has(key));
-        }
-        if (allowedProviders && allowedProviders.size > 0) {
-            targets = targets.filter(key => {
-                const providerId = this.extractProviderId(key);
-                return providerId && allowedProviders.has(providerId);
-            });
-        }
-        if (disabledProviders && disabledProviders.size > 0) {
-            targets = targets.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                return providerId && !disabledProviders.has(providerId);
-            });
-        }
-        if (disabledKeysMap && disabledKeysMap.size > 0) {
-            targets = targets.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                if (!providerId)
-                    return true;
-                const disabledKeys = disabledKeysMap.get(providerId);
-                if (!disabledKeys || disabledKeys.size === 0)
-                    return true;
-                const keyAlias = this.extractKeyAlias(key);
-                const keyIndex = this.extractKeyIndex(key);
-                if (keyAlias && disabledKeys.has(keyAlias)) {
-                    return false;
-                }
-                if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
-                    return false;
-                }
-                return true;
-            });
-        }
-        if (disabledModels && disabledModels.size > 0) {
-            targets = targets.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                if (!providerId) {
-                    return true;
-                }
-                const disabled = disabledModels.get(providerId);
-                if (!disabled || disabled.size === 0) {
-                    return true;
-                }
-                const modelId = this.getProviderModelId(key);
-                if (!modelId) {
-                    return true;
-                }
-                return !disabled.has(modelId);
-            });
-        }
-        if (requiredProviderKeys && requiredProviderKeys.size > 0) {
-            targets = targets.filter((key) => requiredProviderKeys.has(key));
-        }
-        const serverToolRequired = features.metadata?.serverToolRequired === true;
-        if (serverToolRequired) {
-            const filtered = [];
-            for (const key of targets) {
-                try {
-                    const profile = this.providerRegistry.get(key);
-                    if (!profile.serverToolsDisabled) {
-                        filtered.push(key);
-                    }
-                }
-                catch {
-                    // ignore unknown providers when filtering for servertools
-                }
-            }
-            targets = filtered;
-        }
-        // 当当前请求包含图片且路由为 default/thinking 时，优先在该路由池内选择
-        // Responses/Gemini 类型的 Provider，以便一次完成多模态推理；如果不存在则回退到原始列表。
-        if (features.hasImageAttachment && (routeName === DEFAULT_ROUTE || routeName === 'thinking')) {
-            const prioritized = [];
-            const fallthrough = [];
-            for (const key of targets) {
-                try {
-                    const profile = this.providerRegistry.get(key);
-                    if (profile.providerType === 'responses') {
-                        prioritized.push(key);
-                    }
-                    else if (profile.providerType === 'gemini') {
-                        prioritized.push(key);
-                    }
-                    else {
-                        fallthrough.push(key);
-                    }
-                }
-                catch {
-                    fallthrough.push(key);
-                }
-            }
-            if (prioritized.length) {
-                targets = prioritized;
-            }
-        }
-        if (!targets.length) {
-            return { providerKey: null, poolTargets: [], tierId: tier.id, failureHint: `${routeName}:${tier.id}:empty` };
-        }
-        const contextResult = this.contextAdvisor.classify(targets, estimatedTokens, (key) => this.providerRegistry.get(key));
-        const prioritizedPools = this.buildContextCandidatePools(contextResult);
-        for (const candidatePool of prioritizedPools) {
-            const providerKey = this.loadBalancer.select({
-                routeName: `${routeName}:${tier.id}`,
-                candidates: candidatePool,
-                stickyKey: allowAliasRotation ? undefined : stickyKey,
-                availabilityCheck: (key) => this.healthManager.isAvailable(key)
-            });
-            if (providerKey) {
-                return { providerKey, poolTargets: tier.targets, tierId: tier.id };
-            }
-        }
-        return {
-            providerKey: null,
-            poolTargets: tier.targets,
-            tierId: tier.id,
-            failureHint: this.describeAttempt(routeName, tier.id, contextResult)
-        };
-    }
-    incrementRouteStat(routeName, providerKey) {
-        if (!this.routeStats.has(routeName)) {
-            this.routeStats.set(routeName, { hits: 0, lastProvider: providerKey });
-            return;
-        }
-        const stats = this.routeStats.get(routeName);
-        stats.hits += 1;
-        stats.lastProvider = providerKey;
-    }
-    providerHealthConfig() {
-        return this.healthManager.getConfig();
-    }
-    initializeRouteQueue(candidates) {
-        return Array.from(new Set(candidates));
-    }
-    buildContextCandidatePools(result) {
-        const ordered = [];
-        if (result.safe.length) {
-            ordered.push(result.safe);
-            // 如果存在安全候选，直接放弃当前处于警戒阈值的模型
-            return ordered;
-        }
-        if (result.risky.length) {
-            ordered.push(result.risky);
-        }
-        // ratio >= 1 视为上下文溢出，直接标记为不可用
-        return ordered;
-    }
-    describeAttempt(routeName, poolId, result) {
-        const prefix = poolId ? `${routeName}:${poolId}` : routeName;
-        if (result.safe.length > 0) {
-            return `${prefix}:health`;
-        }
-        if (result.risky.length > 0) {
-            return `${prefix}:context_risky`;
-        }
-        if (result.overflow.length > 0) {
-            return `${prefix}:max_context_window`;
-        }
-        return prefix;
-    }
-    resolveStickyKey(metadata) {
-        const sessionScope = this.resolveSessionScope(metadata);
-        if (sessionScope) {
-            return sessionScope;
-        }
-        const resume = metadata.responsesResume;
-        if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
-            return resume.previousRequestId.trim();
-        }
-        return metadata.requestId;
-    }
-    resolveSessionScope(metadata) {
-        const sessionId = typeof metadata.sessionId === 'string' ? metadata.sessionId.trim() : '';
-        if (sessionId) {
-            return `session:${sessionId}`;
-        }
-        const conversationId = typeof metadata.conversationId === 'string' ? metadata.conversationId.trim() : '';
-        if (conversationId) {
-            return `conversation:${conversationId}`;
-        }
-        return undefined;
-    }
-    getRoutingInstructionState(stickyKey) {
-        const key = stickyKey || 'default';
-        if (this.routingInstructionState.has(key)) {
-            return this.routingInstructionState.get(key);
-        }
-        let initial = null;
-        // 仅对 session:/conversation: 作用域的 key 尝试从磁盘恢复持久化状态
-        if (key.startsWith('session:') || key.startsWith('conversation:')) {
-            initial = loadRoutingInstructionStateSync(key);
-        }
-        if (!initial) {
-            initial = {
-                forcedTarget: undefined,
-                stickyTarget: undefined,
-                allowedProviders: new Set(),
-                disabledProviders: new Set(),
-                disabledKeys: new Map(),
-                disabledModels: new Map()
-            };
-        }
-        this.routingInstructionState.set(key, initial);
-        return initial;
-    }
-    buildMetadataInstructions(metadata) {
-        const instructions = [];
-        if (Array.isArray(metadata.disabledProviderKeyAliases)) {
-            for (const entry of metadata.disabledProviderKeyAliases) {
-                const parsed = this.parseMetadataDisableDescriptor(entry);
-                if (parsed) {
-                    instructions.push({ type: 'disable', ...parsed });
-                }
-            }
-        }
-        return instructions;
-    }
-    parseMetadataDisableDescriptor(entry) {
-        if (typeof entry !== 'string') {
-            return null;
-        }
-        const trimmed = entry.trim();
-        if (!trimmed) {
-            return null;
-        }
-        const parts = trimmed.split('.');
-        if (parts.length < 2) {
-            return null;
-        }
-        const provider = parts[0];
-        const alias = parts[1];
-        if (!provider || !alias) {
-            return null;
-        }
-        if (/^\d+$/.test(alias)) {
-            return { provider, keyIndex: Number.parseInt(alias, 10) };
-        }
-        return { provider, keyAlias: alias };
-    }
-    resolveRoutingMode(instructions, state) {
-        const hasForce = instructions.some((inst) => inst.type === 'force');
-        const hasAllow = instructions.some((inst) => inst.type === 'allow');
-        const hasClear = instructions.some((inst) => inst.type === 'clear');
-        if (hasClear) {
-            return 'none';
-        }
-        if (hasAllow || state.allowedProviders.size > 0) {
-            return 'sticky';
-        }
-        if (hasForce || state.forcedTarget) {
-            return 'force';
-        }
-        if (state.stickyTarget) {
-            return 'sticky';
-        }
-        return 'none';
-    }
-    resolveInstructionTarget(target) {
-        if (!target || !target.provider) {
-            return null;
-        }
-        const providerId = target.provider;
-        const providerKeys = this.providerRegistry.listProviderKeys(providerId);
-        if (providerKeys.length === 0) {
-            return null;
-        }
-        const alias = typeof target.keyAlias === 'string' ? target.keyAlias.trim() : '';
-        const aliasExplicit = alias.length > 0 && target.pathLength === 3;
-        if (aliasExplicit) {
-            const runtimeKey = this.providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
-            if (runtimeKey) {
-                return { mode: 'exact', keys: [runtimeKey] };
-            }
-        }
-        if (typeof target.keyIndex === 'number' && target.keyIndex > 0) {
-            const runtimeKey = this.providerRegistry.resolveRuntimeKeyByIndex(providerId, target.keyIndex);
-            if (runtimeKey) {
-                return { mode: 'exact', keys: [runtimeKey] };
-            }
-        }
-        if (target.model && target.model.trim()) {
-            const normalizedModel = target.model.trim();
-            const matchingKeys = providerKeys.filter((key) => {
-                const modelId = this.getProviderModelId(key);
-                return modelId === normalizedModel;
-            });
-            if (matchingKeys.length > 0) {
-                return { mode: 'filter', keys: matchingKeys };
-            }
-        }
-        if (alias && !aliasExplicit) {
-            const legacyKey = this.providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
-            if (legacyKey) {
-                return { mode: 'exact', keys: [legacyKey] };
-            }
-        }
-        return { mode: 'filter', keys: providerKeys };
-    }
-    filterCandidatesByRoutingState(routes, state) {
-        // console.log('[filter] routes:', routes, 'state:', {
-        //   allowed: Array.from(state.allowedProviders),
-        //   disabled: Array.from(state.disabledProviders)
-        // });
-        if (state.allowedProviders.size === 0 &&
-            state.disabledProviders.size === 0 &&
-            state.disabledKeys.size === 0 &&
-            state.disabledModels.size === 0) {
-            return routes;
-        }
-        return routes.filter(routeName => {
-            const pools = this.routing[routeName];
-            if (!pools)
-                return false;
-            for (const pool of pools) {
-                if (!Array.isArray(pool.targets) || pool.targets.length === 0) {
-                    continue;
-                }
-                for (const providerKey of pool.targets) {
-                    const providerId = this.extractProviderId(providerKey);
-                    // console.log('[filter] checking', providerKey, 'id=', providerId);
-                    if (!providerId)
-                        continue;
-                    if (state.allowedProviders.size > 0 && !state.allowedProviders.has(providerId)) {
-                        // console.log('[filter] dropped by allowed list');
-                        continue;
-                    }
-                    if (state.disabledProviders.has(providerId)) {
-                        continue;
-                    }
-                    const disabledKeys = state.disabledKeys.get(providerId);
-                    if (disabledKeys && disabledKeys.size > 0) {
-                        const keyAlias = this.extractKeyAlias(providerKey);
-                        const keyIndex = this.extractKeyIndex(providerKey);
-                        if (keyAlias && disabledKeys.has(keyAlias)) {
-                            continue;
-                        }
-                        if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
-                            continue;
-                        }
-                    }
-                    const disabledModels = state.disabledModels.get(providerId);
-                    if (disabledModels && disabledModels.size > 0) {
-                        const modelId = this.getProviderModelId(providerKey);
-                        if (modelId && disabledModels.has(modelId)) {
-                            continue;
-                        }
-                    }
-                    return true;
-                }
-            }
-            return false;
-        });
-    }
-    selectFromCandidates(routes, metadata, classification, features, state, requiredProviderKeys, allowAliasRotation) {
-        const allowedProviders = new Set(state.allowedProviders);
-        const disabledProviders = new Set(state.disabledProviders);
-        const disabledKeysMap = new Map(Array.from(state.disabledKeys.entries()).map(([provider, keys]) => [
-            provider,
-            new Set(Array.from(keys).map(k => typeof k === 'string' ? k : k + 1))
-        ]));
-        const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
-        const stickyKey = allowAliasRotation ? undefined : this.resolveStickyKey(metadata);
-        const attempted = [];
-        const visitedRoutes = new Set();
-        const routeQueue = this.initializeRouteQueue(routes);
-        const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
-            ? Math.max(0, features.estimatedTokens)
-            : 0;
-        while (routeQueue.length) {
-            const routeName = routeQueue.shift();
-            if (visitedRoutes.has(routeName)) {
-                continue;
-            }
-            const routePools = this.routing[routeName];
-            if (!this.routeHasTargets(routePools)) {
-                visitedRoutes.add(routeName);
-                attempted.push(`${routeName}:empty`);
-                continue;
-            }
-            visitedRoutes.add(routeName);
-            const orderedPools = this.sortRoutePools(routePools);
-            for (const poolTier of orderedPools) {
-                const { providerKey, poolTargets, tierId, failureHint } = this.trySelectFromTier(routeName, poolTier, stickyKey, estimatedTokens, features, disabledProviders, disabledKeysMap, allowedProviders, disabledModels, requiredProviderKeys, allowAliasRotation);
-                if (providerKey) {
-                    return { providerKey, routeUsed: routeName, pool: poolTargets, poolId: tierId };
-                }
-                if (failureHint) {
-                    attempted.push(failureHint);
-                }
-            }
-        }
-        const requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
-        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
-    }
-    extractProviderId(providerKey) {
-        const firstDot = providerKey.indexOf('.');
-        if (firstDot <= 0)
-            return null;
-        return providerKey.substring(0, firstDot);
-    }
-    /**
-     * 在已有候选路由集合上，筛选出真正挂载了 sticky 池内 providerKey 的路由，
-     * 并按 ROUTE_PRIORITY 进行排序；同时显式排除 tools 路由，保证一旦进入
-     * sticky 模式，就不会再命中独立的 tools 池（例如 glm/qwen 工具模型）。
-     * 若候选集合中完全没有挂载 sticky key 的路由，则尝试在 default 路由上兜底。
-     */
-    buildStickyRouteCandidatesFromFiltered(filteredCandidates, stickyKeySet) {
-        const routesWithSticky = [];
-        const candidateSet = new Set(filteredCandidates.filter((name) => name && name !== 'tools'));
-        for (const routeName of candidateSet) {
-            const pools = this.routing[routeName];
-            if (!this.routeHasTargets(pools)) {
-                continue;
-            }
-            const targets = this.flattenPoolTargets(pools);
-            if (!targets.some((key) => stickyKeySet.has(key))) {
-                continue;
-            }
-            routesWithSticky.push(routeName);
-        }
-        // 若当前候选路由中没有任何挂载 sticky key 的路由，尝试直接在 default 路由上兜底；
-        // 若 default 也不包含 sticky key，则视为 sticky 配置失效，由调用方回落到非 sticky 逻辑。
-        if (routesWithSticky.length === 0) {
-            const defaultPools = this.routing[DEFAULT_ROUTE];
-            if (this.routeHasTargets(defaultPools)) {
-                const targets = this.flattenPoolTargets(defaultPools);
-                if (targets.some((key) => stickyKeySet.has(key))) {
-                    return [DEFAULT_ROUTE];
-                }
-            }
-            return [];
-        }
-        const ordered = this.sortByPriority(routesWithSticky);
-        const result = [];
-        let hasDefault = false;
-        for (const routeName of ordered) {
-            if (routeName === DEFAULT_ROUTE) {
-                hasDefault = true;
-                continue;
-            }
-            if (!result.includes(routeName)) {
-                result.push(routeName);
-            }
-        }
-        // default 路由若包含 sticky key，则始终放在候选列表最后，用于 sticky 模式兜底。
-        if (hasDefault && !result.includes(DEFAULT_ROUTE)) {
-            result.push(DEFAULT_ROUTE);
-        }
-        return result;
-    }
-    /**
-     * 在 sticky 模式下，仅在 sticky 池内选择 Provider：
-     * - stickyKeySet 表示已经解析并通过健康检查的 providerKey 集合；
-     * - 不再依赖 routing[*].targets 中是否挂载这些 key，避免「未初始化路由池」导致 sticky 池为空；
-     * - 仍然尊重 allowed/disabledProviders、disabledKeys、disabledModels 以及上下文长度。
-     */
-    selectFromStickyPool(stickyKeySet, metadata, features, state, allowAliasRotation) {
-        if (!stickyKeySet || stickyKeySet.size === 0) {
-            return null;
-        }
-        const allowedProviders = new Set(state.allowedProviders);
-        const disabledProviders = new Set(state.disabledProviders);
-        const disabledKeysMap = new Map(Array.from(state.disabledKeys.entries()).map(([provider, keys]) => [
-            provider,
-            new Set(Array.from(keys).map((k) => (typeof k === 'string' ? k : k + 1)))
-        ]));
-        const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
-        // 初始候选集合：sticky 池中的所有 key
-        let candidates = Array.from(stickyKeySet);
-        // 应用 provider 白名单 / 黑名单
-        if (allowedProviders.size > 0) {
-            candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                return providerId && allowedProviders.has(providerId);
-            });
-        }
-        if (disabledProviders.size > 0) {
-            candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                return providerId && !disabledProviders.has(providerId);
-            });
-        }
-        // 应用 key / model 级别黑名单
-        if (disabledKeysMap.size > 0 || disabledModels.size > 0) {
-            candidates = candidates.filter((key) => {
-                const providerId = this.extractProviderId(key);
-                if (!providerId) {
-                    return true;
-                }
-                const disabledKeys = disabledKeysMap.get(providerId);
-                if (disabledKeys && disabledKeys.size > 0) {
-                    const keyAlias = this.extractKeyAlias(key);
-                    const keyIndex = this.extractKeyIndex(key);
-                    if (keyAlias && disabledKeys.has(keyAlias)) {
-                        return false;
-                    }
-                    if (keyIndex !== undefined && disabledKeys.has(keyIndex + 1)) {
-                        return false;
-                    }
-                }
-                const disabledModelSet = disabledModels.get(providerId);
-                if (disabledModelSet && disabledModelSet.size > 0) {
-                    const modelId = this.getProviderModelId(key);
-                    if (modelId && disabledModelSet.has(modelId)) {
-                        return false;
-                    }
-                }
-                return true;
-            });
-        }
-        if (!candidates.length) {
-            return null;
-        }
-        const stickyKey = allowAliasRotation ? undefined : this.resolveStickyKey(metadata);
-        const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
-            ? Math.max(0, features.estimatedTokens)
-            : 0;
-        const tier = {
-            id: 'sticky-primary',
-            targets: candidates,
-            priority: 0
-        };
-        const { providerKey, poolTargets, tierId } = this.trySelectFromTier('sticky', tier, stickyKey, estimatedTokens, features, disabledProviders, disabledKeysMap, allowedProviders, disabledModels, stickyKeySet, allowAliasRotation);
-        if (!providerKey) {
-            return null;
-        }
-        return {
-            providerKey,
-            routeUsed: 'sticky',
-            pool: poolTargets,
-            poolId: tierId
-        };
-    }
-    extractKeyAlias(providerKey) {
-        const parts = providerKey.split('.');
-        if (parts.length === 3) {
-            return this.normalizeAliasDescriptor(parts[1]);
-        }
-        return null;
-    }
-    normalizeAliasDescriptor(alias) {
-        if (/^\d+-/.test(alias)) {
-            return alias.replace(/^\d+-/, '');
-        }
-        return alias;
-    }
-    extractKeyIndex(providerKey) {
-        const parts = providerKey.split('.');
-        if (parts.length === 2) {
-            const index = parseInt(parts[1], 10);
-            if (!isNaN(index) && index > 0) {
-                return index;
-            }
-        }
-        return undefined;
-    }
-    getProviderModelId(providerKey) {
-        const profile = this.providerRegistry.get(providerKey);
-        if (profile.modelId) {
-            return profile.modelId;
-        }
-        const parts = providerKey.split('.');
-        if (parts.length === 2) {
-            return parts[1] || null;
-        }
-        if (parts.length === 3) {
-            return parts[2] || null;
-        }
-        return null;
-    }
-    mapProviderError(event) {
-        // NOTE: mapProviderError is the only place where VirtualRouter translates providerErrorCenter
-        // events into health signals. Classification is intentionally coarse; upstream providers
-        // are expected to set event.recoverable explicitly when they know an error is safe to retry.
-        if (!event || !event.runtime) {
-            return null;
-        }
-        const runtime = event.runtime;
-        const providerKey = runtime.providerKey ||
-            (runtime.target && typeof runtime.target === 'object' ? runtime.target.providerKey : undefined);
-        if (!providerKey) {
-            return null;
-        }
-        const routeName = runtime.routeName;
-        const statusCode = event.status;
-        const code = event.code?.toUpperCase() ?? 'ERR_UNKNOWN';
-        const stage = event.stage?.toLowerCase() ?? 'unknown';
-        const recoverable = event.recoverable === true;
-        // 默认策略：只有显式可恢复的错误才视为非致命；其余一律按致命处理。
-        // 注意：provider 层已经对 429 做了「连续 4 次升级为不可恢复」的判断，这里不再把所有 429 强行当作可恢复。
-        let fatal = !recoverable;
-        let reason = this.deriveReason(code, stage, statusCode);
-        let cooldownOverrideMs;
-        // 401 / 402 / 500 / 524 以及所有未被标记为可恢复的错误一律视为不可恢复
-        if (statusCode === 401 || statusCode === 402 || statusCode === 403 || code.includes('AUTH')) {
-            fatal = true;
-            cooldownOverrideMs = Math.max(10 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 10 * 60_000);
-            reason = 'auth';
-        }
-        else if (statusCode === 429 && !recoverable) {
-            // 连续 429 已在 provider 层被升级为不可恢复：这里按致命限流处理（长冷却，等同熔断）
-            fatal = true;
-            cooldownOverrideMs = Math.max(10 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 10 * 60_000);
-            reason = 'rate_limit';
-        }
-        else if (statusCode && statusCode >= 500) {
-            fatal = true;
-            cooldownOverrideMs = Math.max(5 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 5 * 60_000);
-            reason = 'upstream_error';
-        }
-        else if (stage.includes('compat')) {
-            fatal = true;
-            cooldownOverrideMs = Math.max(10 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 10 * 60_000);
-            reason = 'compatibility';
-        }
-        return {
-            providerKey,
-            routeName,
-            reason,
-            fatal,
-            statusCode,
-            errorCode: code,
-            retryable: recoverable,
-            // 是否影响健康由 provider 层决定；这里仅在 event.affectsHealth !== false 时才计入健康状态
-            affectsHealth: event.affectsHealth !== false,
-            cooldownOverrideMs,
-            metadata: {
-                ...event.runtime,
-                stage,
-                eventCode: code,
-                originalMessage: event.message,
-                statusCode
-            }
-        };
-    }
-    deriveReason(code, stage, statusCode) {
-        if (code.includes('RATE') || code.includes('429'))
-            return 'rate_limit';
-        if (code.includes('AUTH') || statusCode === 401 || statusCode === 403)
-            return 'auth';
-        if (stage.includes('compat'))
-            return 'compatibility';
-        if (code.includes('SSE'))
-            return 'sse';
-        if (code.includes('TIMEOUT') || statusCode === 408 || statusCode === 504)
-            return 'timeout';
-        if (statusCode && statusCode >= 500)
-            return 'upstream_error';
-        if (statusCode && statusCode >= 400)
-            return 'client_error';
-        return 'unknown';
-    }
-    buildRouteCandidates(requestedRoute, classificationCandidates, features) {
-        const forceVision = this.routeHasForceFlag('vision');
-        const normalized = this.normalizeRouteAlias(requestedRoute || DEFAULT_ROUTE);
-        const baseList = [];
-        if (classificationCandidates && classificationCandidates.length) {
-            for (const candidate of classificationCandidates) {
-                baseList.push(this.normalizeRouteAlias(candidate));
-            }
-        }
-        else if (normalized) {
-            baseList.push(normalized);
-        }
-        // 当检测到当前请求包含图片时，确保 default/thinking 也参与候选集，
-        // 以便优先尝试内建多模态模型（Responses/Gemini），再回落到 vision 路由池。
-        if (features.hasImageAttachment && !forceVision) {
-            const visionAwareRoutes = [DEFAULT_ROUTE, 'thinking'];
-            for (const routeName of visionAwareRoutes) {
-                if (this.routeHasTargets(this.routing[routeName]) && !baseList.includes(routeName)) {
-                    baseList.push(routeName);
-                }
-            }
-        }
-        let ordered = this.sortByPriority(baseList);
-        if (features.hasImageAttachment && !forceVision) {
-            ordered = this.reorderForInlineVision(ordered);
-        }
-        const deduped = [];
-        for (const routeName of ordered) {
-            if (routeName && !deduped.includes(routeName)) {
-                deduped.push(routeName);
-            }
-        }
-        if (!deduped.includes(DEFAULT_ROUTE)) {
-            deduped.push(DEFAULT_ROUTE);
-        }
-        const filtered = deduped.filter((routeName) => this.routeHasTargets(this.routing[routeName]));
-        if (!filtered.includes(DEFAULT_ROUTE) && this.routeHasTargets(this.routing[DEFAULT_ROUTE])) {
-            filtered.push(DEFAULT_ROUTE);
-        }
-        return filtered.length ? filtered : [DEFAULT_ROUTE];
-    }
-    reorderForInlineVision(routeNames) {
-        const unique = Array.from(new Set(routeNames.filter(Boolean)));
-        if (!unique.length) {
-            return unique;
-        }
-        // 仅当 default/thinking 中存在 Responses/Gemini 提供方时，才将其提前作为「一次完成」优先级。
-        const inlinePreferred = [];
-        const inlineRoutes = [DEFAULT_ROUTE, 'thinking'];
-        for (const routeName of inlineRoutes) {
-            if (this.routeSupportsInlineVision(routeName) && !inlinePreferred.includes(routeName)) {
-                inlinePreferred.push(routeName);
-            }
-        }
-        if (!inlinePreferred.length) {
-            return unique;
-        }
-        const remaining = [];
-        for (const routeName of unique) {
-            if (!inlinePreferred.includes(routeName)) {
-                remaining.push(routeName);
-            }
-        }
-        return [...inlinePreferred, ...remaining];
-    }
-    routeSupportsInlineVision(routeName) {
-        const pools = this.routing[routeName];
-        if (!Array.isArray(pools)) {
-            return false;
-        }
-        for (const pool of pools) {
-            if (!Array.isArray(pool.targets)) {
-                continue;
-            }
-            for (const providerKey of pool.targets) {
-                try {
-                    const profile = this.providerRegistry.get(providerKey);
-                    if (profile.providerType === 'responses' || profile.providerType === 'gemini') {
-                        return true;
-                    }
-                }
-                catch {
-                    // ignore unknown provider keys during capability probing
-                }
-            }
-        }
-        return false;
-    }
-    sortByPriority(routeNames) {
-        return [...routeNames].sort((a, b) => this.routeWeight(a) - this.routeWeight(b));
-    }
-    routeWeight(routeName) {
-        const idx = ROUTE_PRIORITY.indexOf(routeName);
-        return idx >= 0 ? idx : ROUTE_PRIORITY.length;
-    }
-    routeHasForceFlag(routeName) {
-        const pools = this.routing[routeName];
-        if (!Array.isArray(pools)) {
-            return false;
-        }
-        return pools.some((pool) => pool.force);
-    }
-    routeHasTargets(pools) {
-        if (!Array.isArray(pools)) {
-            return false;
-        }
-        return pools.some((pool) => Array.isArray(pool.targets) && pool.targets.length > 0);
-    }
-    hasPrimaryPool(pools) {
-        if (!Array.isArray(pools)) {
-            return false;
-        }
-        return pools.some((pool) => !pool.backup && Array.isArray(pool.targets) && pool.targets.length > 0);
-    }
-    sortRoutePools(pools) {
-        if (!Array.isArray(pools)) {
-            return [];
-        }
-        return pools
-            .filter((pool) => Array.isArray(pool.targets) && pool.targets.length > 0)
-            .sort((a, b) => {
-            if (a.backup && !b.backup)
-                return 1;
-            if (!a.backup && b.backup)
-                return -1;
-            if (a.priority !== b.priority) {
-                return b.priority - a.priority;
-            }
-            return a.id.localeCompare(b.id);
-        });
-    }
-    flattenPoolTargets(pools) {
-        const flattened = [];
-        if (!Array.isArray(pools)) {
-            return flattened;
-        }
-        for (const pool of pools) {
-            if (!Array.isArray(pool.targets)) {
-                continue;
-            }
-            for (const target of pool.targets) {
-                if (typeof target === 'string' && target && !flattened.includes(target)) {
-                    flattened.push(target);
-                }
-            }
-        }
-        return flattened;
-    }
-    buildHitReason(routeUsed, providerKey, classification, features, mode) {
-        const reasoning = classification.reasoning || '';
-        let primary = reasoning.split('|')[0] || '';
-        const commandDetail = features.lastAssistantToolLabel;
-        const isStickyMode = mode === 'sticky';
-        if (isStickyMode &&
-            (routeUsed === 'tools' || routeUsed === 'thinking' || routeUsed === 'coding')) {
-            // sticky 模式下不再把 tools/thinking/coding 作为主标签，统一折叠为 sticky，
-            // 避免日志中出现 "tools:last-tool-*" 这类误导性前缀。
-            primary = '';
-        }
-        const base = (() => {
-            if (routeUsed === 'tools') {
-                const label = isStickyMode ? 'sticky' : 'tools';
-                return this.decorateWithDetail(primary || label, primary, commandDetail);
-            }
-            if (routeUsed === 'thinking') {
-                const label = isStickyMode ? 'sticky' : 'thinking';
-                return this.decorateWithDetail(primary || label, primary, commandDetail);
-            }
-            if (routeUsed === 'coding') {
-                const label = isStickyMode ? 'sticky' : 'coding';
-                return this.decorateWithDetail(primary || label, primary, commandDetail);
-            }
-            if (routeUsed === 'web_search' || routeUsed === 'search') {
-                return this.decorateWithDetail(primary || routeUsed, primary, commandDetail);
-            }
-            if (routeUsed === DEFAULT_ROUTE && classification.fallback) {
-                if (isStickyMode) {
-                    return primary || 'sticky:default';
-                }
-                return primary || 'fallback:default';
-            }
-            if (primary) {
-                return primary;
-            }
-            return routeUsed ? `route:${routeUsed}` : 'route:unknown';
-        })();
-        const contextDetail = this.describeContextUsage(providerKey, features.estimatedTokens);
-        if (contextDetail) {
-            return `${base}|context:${contextDetail}`;
-        }
-        return base;
-    }
-    isRoutingStateEmpty(state) {
-        if (!state) {
-            return true;
-        }
-        const noForced = !state.forcedTarget;
-        const noSticky = !state.stickyTarget;
-        const noAllowed = state.allowedProviders.size === 0;
-        const noDisabledProviders = state.disabledProviders.size === 0;
-        const noDisabledKeys = state.disabledKeys.size === 0;
-        const noDisabledModels = state.disabledModels.size === 0;
-        return noForced && noSticky && noAllowed && noDisabledProviders && noDisabledKeys && noDisabledModels;
-    }
-    persistRoutingInstructionState(key, state) {
-        if (!key || (!key.startsWith('session:') && !key.startsWith('conversation:'))) {
-            return;
-        }
-        if (this.isRoutingStateEmpty(state)) {
-            saveRoutingInstructionStateAsync(key, null);
-            return;
-        }
-        saveRoutingInstructionStateAsync(key, state);
-    }
-    decorateWithDetail(baseLabel, primaryReason, detail) {
-        const normalizedDetail = detail && detail.trim();
-        if (!normalizedDetail) {
-            return primaryReason || baseLabel;
-        }
-        if (primaryReason) {
-            return `${primaryReason}(${normalizedDetail})`;
-        }
-        return `${baseLabel}(${normalizedDetail})`;
-    }
-    formatVirtualRouterHit(routeName, poolId, providerKey, modelId, hitReason, stickyScope) {
-        try {
-            // 生成本地时间戳
-            const now = new Date();
-            const hours = String(now.getHours()).padStart(2, '0');
-            const minutes = String(now.getMinutes()).padStart(2, '0');
-            const seconds = String(now.getSeconds()).padStart(2, '0');
-            const timestamp = `${hours}:${minutes}:${seconds}`;
-            const prefixColor = '\x1b[38;5;208m';
-            const reset = '\x1b[0m';
-            const timeColor = '\x1b[90m'; // 灰色
-            const stickyColor = '\x1b[33m'; // 黄色
-            const routeColor = this.resolveRouteColor(routeName);
-            const prefix = `${prefixColor}[virtual-router-hit]${reset}`;
-            const timeLabel = `${timeColor}${timestamp}${reset}`;
-            const { providerLabel, resolvedModel } = this.describeTargetProvider(providerKey, modelId);
-            const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
-            const targetLabel = `${routeLabel} -> ${providerLabel}${resolvedModel ? '.' + resolvedModel : ''}`;
-            const stickyLabel = stickyScope ? ` ${stickyColor}[sticky:${stickyScope}]${reset}` : '';
-            const reasonLabel = hitReason ? ` reason=${hitReason}` : '';
-            return `${prefix} ${timeLabel} ${routeColor}${targetLabel}${stickyLabel}${reasonLabel}${reset}`;
-        }
-        catch {
-            const now = new Date();
-            const timestamp = now.toLocaleTimeString('zh-CN', { hour12: false });
-            const routeLabel = poolId ? `${routeName}/${poolId}` : routeName;
-            const stickyLabel = stickyScope ? ` [sticky:${stickyScope}]` : '';
-            return `[virtual-router-hit] ${timestamp} ${routeLabel} -> ${providerKey}${modelId ? '.' + modelId : ''}${stickyLabel}${hitReason ? ` reason=${hitReason}` : ''}`;
-        }
-    }
-    resolveRouteColor(routeName) {
-        const reset = '\x1b[0m';
-        const map = {
-            tools: '\x1b[38;5;214m',
-            thinking: '\x1b[34m',
-            coding: '\x1b[35m',
-            longcontext: '\x1b[38;5;141m',
-            web_search: '\x1b[32m',
-            search: '\x1b[38;5;34m',
-            vision: '\x1b[38;5;207m',
-            background: '\x1b[90m'
-        };
-        return map[routeName] ?? '\x1b[36m';
-    }
-    describeContextUsage(providerKey, estimatedTokens) {
-        if (typeof estimatedTokens !== 'number' || !Number.isFinite(estimatedTokens) || estimatedTokens <= 0) {
-            return undefined;
-        }
-        let limit = DEFAULT_MODEL_CONTEXT_TOKENS;
-        try {
-            const profile = this.providerRegistry.get(providerKey);
-            if (profile?.maxContextTokens && Number.isFinite(profile.maxContextTokens)) {
-                limit = profile.maxContextTokens;
-            }
-        }
-        catch {
-            limit = DEFAULT_MODEL_CONTEXT_TOKENS;
-        }
-        if (!limit || limit <= 0) {
-            return undefined;
-        }
-        const ratio = estimatedTokens / limit;
-        const threshold = this.contextRouting?.warnRatio ?? 0.9;
-        if (ratio < threshold) {
-            return undefined;
-        }
-        return `${ratio.toFixed(2)}/${Math.round(limit)}`;
-    }
-    describeTargetProvider(providerKey, fallbackModelId) {
-        const parsed = this.parseProviderKey(providerKey);
-        if (!parsed) {
-            return { providerLabel: providerKey, resolvedModel: fallbackModelId };
-        }
-        const aliasLabel = parsed.keyAlias ? `${parsed.providerId}[${parsed.keyAlias}]` : parsed.providerId;
-        const resolvedModel = parsed.modelId || fallbackModelId;
-        return { providerLabel: aliasLabel, resolvedModel };
-    }
-    parseProviderKey(providerKey) {
-        const trimmed = typeof providerKey === 'string' ? providerKey.trim() : '';
-        if (!trimmed) {
-            return null;
-        }
-        const parts = trimmed.split('.');
-        if (parts.length < 2) {
-            return { providerId: trimmed };
-        }
-        if (parts.length === 2) {
-            return { providerId: parts[0], modelId: parts[1] };
-        }
-        return {
-            providerId: parts[0],
-            keyAlias: parts[1],
-            modelId: parts.slice(2).join('.')
-        };
-    }
-}