@jsonstudio/llms 0.6.473 → 0.6.568

package/dist/router/virtual-router/engine.js

@@ -4,14 +4,18 @@ 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 { 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';
+import { buildHitReason, formatVirtualRouterHit } from './engine-logging.js';
+import { selectProviderImpl } from './engine-selection.js';
+import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
 export class VirtualRouterEngine {
     routing = {};
     providerRegistry = new ProviderRegistry();
     healthManager = new ProviderHealthManager();
+    providerCooldowns = new Map();
     loadBalancer = new RouteLoadBalancer();
     classifier = new RoutingClassifier({});
     contextAdvisor = new ContextAdvisor();
@@ -22,7 +26,20 @@ export class VirtualRouterEngine {
     statsCenter = getStatsCenter();
     // Derived flags from VirtualRouterConfig/routing used by process / response layers.
     webSearchForce = false;
+    healthStore;
+    routingStateStore = {
+        loadSync: loadRoutingInstructionStateSync,
+        saveAsync: saveRoutingInstructionStateAsync
+    };
     routingInstructionState = new Map();
+    constructor(deps) {
+        if (deps?.healthStore) {
+            this.healthStore = deps.healthStore;
+        }
+        if (deps?.routingStateStore) {
+            this.routingStateStore = deps.routingStateStore;
+        }
+    }
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -30,6 +47,8 @@ export class VirtualRouterEngine {
         this.healthManager.configure(config.health);
         this.healthConfig = config.health ?? null;
         this.healthManager.registerProviders(Object.keys(config.providers));
+        this.providerCooldowns.clear();
+        this.restoreHealthFromStore();
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
         this.classifier = new RoutingClassifier(config.classifier);
         this.contextRouting = config.contextRouting ?? { warnRatio: 0.9, hardLimit: false };
@@ -48,6 +67,15 @@ export class VirtualRouterEngine {
         if (metadataInstructions.length > 0) {
             routingState = applyRoutingInstructions(metadataInstructions, routingState);
         }
+        const disableStickyRoutes = metadata &&
+            typeof metadata === 'object' &&
+            metadata.disableStickyRoutes === true;
+        if (disableStickyRoutes && routingState.stickyTarget) {
+            routingState = {
+                ...routingState,
+                stickyTarget: undefined
+            };
+        }
         const instructions = parseRoutingInstructions(request.messages);
         if (instructions.length > 0) {
             routingState = applyRoutingInstructions(instructions, routingState);
@@ -76,7 +104,6 @@ export class VirtualRouterEngine {
             ...(this.webSearchForce ? { forceWebSearch: true } : {}),
             ...(forceVision ? { forceVision: true } : {})
         };
-        this.healthManager.recordSuccess(selection.providerKey);
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
         try {
             this.statsCenter.recordVirtualRouterHit({
@@ -92,10 +119,10 @@ export class VirtualRouterEngine {
         catch {
             // stats must never break routing
         }
-        const hitReason = this.buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode);
+        const hitReason = buildHitReason(selection.routeUsed, selection.providerKey, classification, features, routingMode, { providerRegistry: this.providerRegistry, contextRouting: this.contextRouting });
         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);
+        const formatted = formatVirtualRouterHit(routeForLog, selection.poolId, selection.providerKey, target.modelId || '', hitReason, stickyScope, routingState);
         if (formatted) {
             this.debug?.log?.(formatted);
         }
@@ -126,26 +153,29 @@ export class VirtualRouterEngine {
         };
     }
     handleProviderFailure(event) {
-        if (!event || !event.providerKey) {
-            return;
+        handleProviderFailureImpl(event, this.healthManager, this.providerHealthConfig(), (key, ttl) => this.markProviderCooldown(key, ttl));
+    }
+    handleProviderError(event) {
+        if (this.healthStore && typeof this.healthStore.recordProviderError === 'function') {
+            try {
+                this.healthStore.recordProviderError(event);
+            }
+            catch {
+                // ignore persistence errors
+            }
         }
-        if (event.affectsHealth === false) {
+        // 配额恢复事件优先处理：一旦识别到 virtualRouterQuotaRecovery，
+        // 直接清理健康状态/冷却 TTL，避免继续走常规错误映射逻辑。
+        const handledByQuota = applyQuotaRecoveryImpl(event, this.healthManager, (key) => this.clearProviderCooldown(key), this.debug);
+        if (handledByQuota) {
             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);
+        const handledByQuotaDepleted = applyQuotaDepletedImpl(event, this.healthManager, (key, ttl) => this.markProviderCooldown(key, ttl), this.debug);
+        if (handledByQuotaDepleted) {
+            return;
         }
-    }
-    handleProviderError(event) {
-        const derived = this.mapProviderError(event);
+        applySeriesCooldownImpl(event, this.providerRegistry, this.healthManager, (key, ttl) => this.markProviderCooldown(key, ttl), this.debug);
+        const derived = mapProviderErrorImpl(event, this.providerHealthConfig());
         if (!derived) {
             return;
         }
@@ -210,213 +240,15 @@ export class VirtualRouterEngine {
     }
     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)
-        };
+        return selectProviderImpl(requestedRoute, metadata, classification, features, activeState, {
+            routing: this.routing,
+            providerRegistry: this.providerRegistry,
+            healthManager: this.healthManager,
+            contextAdvisor: this.contextAdvisor,
+            loadBalancer: this.loadBalancer,
+            isProviderCoolingDown: (key) => this.isProviderCoolingDown(key),
+            resolveStickyKey: (m) => this.resolveStickyKey(m)
+        }, { routingState });
     }
     incrementRouteStat(routeName, providerKey) {
         if (!this.routeStats.has(routeName)) {
@@ -430,35 +262,6 @@ export class VirtualRouterEngine {
     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) {
@@ -498,7 +301,12 @@ export class VirtualRouterEngine {
                 allowedProviders: new Set(),
                 disabledProviders: new Set(),
                 disabledKeys: new Map(),
-                disabledModels: new Map()
+                disabledModels: new Map(),
+                stopMessageText: undefined,
+                stopMessageMaxRepeats: undefined,
+                stopMessageUsed: undefined,
+                stopMessageUpdatedAt: undefined,
+                stopMessageLastUsedAt: undefined
             };
         }
         this.routingInstructionState.set(key, initial);
@@ -653,45 +461,16 @@ export class VirtualRouterEngine {
         });
     }
     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 });
+        // legacy helper kept for backward compatibility; selection logic moved to engine-selection.ts
+        return selectProviderImpl(this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE), metadata, classification, features, state, {
+            routing: this.routing,
+            providerRegistry: this.providerRegistry,
+            healthManager: this.healthManager,
+            contextAdvisor: this.contextAdvisor,
+            loadBalancer: this.loadBalancer,
+            isProviderCoolingDown: (key) => this.isProviderCoolingDown(key),
+            resolveStickyKey: (m) => this.resolveStickyKey(m)
+        }, { routingState: state });
     }
     extractProviderId(providerKey) {
         const firstDot = providerKey.indexOf('.');
@@ -767,7 +546,7 @@ export class VirtualRouterEngine {
         ]));
         const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
         // 初始候选集合：sticky 池中的所有 key
-        let candidates = Array.from(stickyKeySet);
+        let candidates = Array.from(stickyKeySet).filter((key) => !this.isProviderCoolingDown(key));
         // 应用 provider 白名单 / 黑名单
         if (allowedProviders.size > 0) {
             candidates = candidates.filter((key) => {
@@ -816,21 +595,8 @@ export class VirtualRouterEngine {
         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
-        };
+        // delegate to selection module
+        return null;
     }
     extractKeyAlias(providerKey) {
         const parts = providerKey.split('.');
@@ -869,87 +635,19 @@ export class VirtualRouterEngine {
         }
         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;
+    // mapProviderError/applySeriesCooldown moved to engine-health.ts
+    extractExcludedProviderKeySet(metadata) {
+        if (!metadata) {
+            return new Set();
         }
-        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';
+        const raw = metadata.excludedProviderKeys;
+        if (!Array.isArray(raw) || raw.length === 0) {
+            return new Set();
         }
-        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';
+        const normalized = raw
+            .map((value) => (typeof value === 'string' ? value.trim() : ''))
+            .filter((value) => Boolean(value));
+        return new Set(normalized);
     }
     buildRouteCandidates(requestedRoute, classificationCandidates, features) {
         const forceVision = this.routeHasForceFlag('vision');
@@ -1099,50 +797,6 @@ export class VirtualRouterEngine {
         }
         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;
@@ -1153,121 +807,144 @@ export class VirtualRouterEngine {
         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;
+        const noStopMessage = (!state.stopMessageText || !state.stopMessageText.trim()) &&
+            (typeof state.stopMessageMaxRepeats !== 'number' || !Number.isFinite(state.stopMessageMaxRepeats)) &&
+            (typeof state.stopMessageUsed !== 'number' || !Number.isFinite(state.stopMessageUsed)) &&
+            (typeof state.stopMessageUpdatedAt !== 'number' || !Number.isFinite(state.stopMessageUpdatedAt)) &&
+            (typeof state.stopMessageLastUsedAt !== 'number' || !Number.isFinite(state.stopMessageLastUsedAt));
+        return (noForced &&
+            noSticky &&
+            noAllowed &&
+            noDisabledProviders &&
+            noDisabledKeys &&
+            noDisabledModels &&
+            noStopMessage);
     }
     persistRoutingInstructionState(key, state) {
         if (!key || (!key.startsWith('session:') && !key.startsWith('conversation:'))) {
             return;
         }
         if (this.isRoutingStateEmpty(state)) {
-            saveRoutingInstructionStateAsync(key, null);
+            this.routingStateStore.saveAsync(key, null);
             return;
         }
-        saveRoutingInstructionStateAsync(key, state);
+        this.routingStateStore.saveAsync(key, state);
     }
-    decorateWithDetail(baseLabel, primaryReason, detail) {
-        const normalizedDetail = detail && detail.trim();
-        if (!normalizedDetail) {
-            return primaryReason || baseLabel;
+    markProviderCooldown(providerKey, cooldownMs) {
+        if (!providerKey) {
+            return;
         }
-        if (primaryReason) {
-            return `${primaryReason}(${normalizedDetail})`;
+        const ttl = typeof cooldownMs === 'number' ? Math.round(cooldownMs) : Number.NaN;
+        if (!Number.isFinite(ttl) || ttl <= 0) {
+            return;
         }
-        return `${baseLabel}(${normalizedDetail})`;
+        this.providerCooldowns.set(providerKey, Date.now() + ttl);
+        this.persistHealthSnapshot();
     }
-    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}`;
+    clearProviderCooldown(providerKey) {
+        if (!providerKey) {
+            return;
         }
-        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}` : ''}`;
+        if (this.providerCooldowns.delete(providerKey)) {
+            this.persistHealthSnapshot();
         }
     }
-    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';
+    isProviderCoolingDown(providerKey) {
+        if (!providerKey) {
+            return false;
+        }
+        const expiry = this.providerCooldowns.get(providerKey);
+        if (!expiry) {
+            return false;
+        }
+        if (Date.now() >= expiry) {
+            this.providerCooldowns.delete(providerKey);
+            return false;
+        }
+        return true;
     }
-    describeContextUsage(providerKey, estimatedTokens) {
-        if (typeof estimatedTokens !== 'number' || !Number.isFinite(estimatedTokens) || estimatedTokens <= 0) {
-            return undefined;
+    restoreHealthFromStore() {
+        if (!this.healthStore || typeof this.healthStore.loadInitialSnapshot !== 'function') {
+            return;
         }
-        let limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+        let snapshot = null;
         try {
-            const profile = this.providerRegistry.get(providerKey);
-            if (profile?.maxContextTokens && Number.isFinite(profile.maxContextTokens)) {
-                limit = profile.maxContextTokens;
-            }
+            snapshot = this.healthStore.loadInitialSnapshot();
         }
         catch {
-            limit = DEFAULT_MODEL_CONTEXT_TOKENS;
+            snapshot = null;
         }
-        if (!limit || limit <= 0) {
-            return undefined;
+        if (!snapshot) {
+            return;
         }
-        const ratio = estimatedTokens / limit;
-        const threshold = this.contextRouting?.warnRatio ?? 0.9;
-        if (ratio < threshold) {
-            return undefined;
+        const now = Date.now();
+        const providerKeys = new Set();
+        for (const pools of Object.values(this.routing)) {
+            for (const pool of pools) {
+                for (const key of pool.targets) {
+                    if (typeof key === 'string' && key) {
+                        providerKeys.add(key);
+                    }
+                }
+            }
+        }
+        const byKey = new Map();
+        for (const entry of snapshot.cooldowns || []) {
+            if (!entry || !entry.providerKey) {
+                continue;
+            }
+            if (!providerKeys.has(entry.providerKey)) {
+                continue;
+            }
+            if (!Number.isFinite(entry.cooldownExpiresAt) || entry.cooldownExpiresAt <= now) {
+                continue;
+            }
+            byKey.set(entry.providerKey, entry);
+            this.providerCooldowns.set(entry.providerKey, entry.cooldownExpiresAt);
+        }
+        for (const state of snapshot.providers || []) {
+            if (!state || !state.providerKey) {
+                continue;
+            }
+            if (!providerKeys.has(state.providerKey)) {
+                continue;
+            }
+            if (state.cooldownExpiresAt && state.cooldownExpiresAt > now) {
+                const ttl = state.cooldownExpiresAt - now;
+                if (ttl > 0) {
+                    this.healthManager.tripProvider(state.providerKey, state.reason, ttl);
+                    if (!byKey.has(state.providerKey)) {
+                        this.providerCooldowns.set(state.providerKey, state.cooldownExpiresAt);
+                    }
+                }
+            }
         }
-        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 };
+    buildHealthSnapshot() {
+        const providers = this.healthManager.getSnapshot();
+        const cooldowns = [];
+        const now = Date.now();
+        for (const [providerKey, expiry] of this.providerCooldowns.entries()) {
+            if (!expiry || expiry <= now) {
+                continue;
+            }
+            cooldowns.push({
+                providerKey,
+                cooldownExpiresAt: expiry
+            });
+        }
+        return { providers, cooldowns };
     }
-    parseProviderKey(providerKey) {
-        const trimmed = typeof providerKey === 'string' ? providerKey.trim() : '';
-        if (!trimmed) {
-            return null;
+    persistHealthSnapshot() {
+        if (!this.healthStore || typeof this.healthStore.persistSnapshot !== 'function') {
+            return;
         }
-        const parts = trimmed.split('.');
-        if (parts.length < 2) {
-            return { providerId: trimmed };
+        try {
+            const snapshot = this.buildHealthSnapshot();
+            this.healthStore.persistSnapshot(snapshot);
         }
-        if (parts.length === 2) {
-            return { providerId: parts[0], modelId: parts[1] };
+        catch {
+            // 持久化失败不影响路由主流程
         }
-        return {
-            providerId: parts[0],
-            keyAlias: parts[1],
-            modelId: parts.slice(2).join('.')
-        };
     }
 }