@jsonstudio/rcc 0.89.555 → 0.89.611

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

@@ -6,6 +6,8 @@ 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();
@@ -20,6 +22,7 @@ export class VirtualRouterEngine {
     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;
@@ -38,6 +41,22 @@ export class VirtualRouterEngine {
         }
     }
     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()
             ? {
@@ -49,7 +68,7 @@ export class VirtualRouterEngine {
             }
             : this.classifier.classify(features);
         const requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
-        const selection = this.selectProvider(requestedRoute, metadata, classification, features);
+        const selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
         const baseTarget = this.providerRegistry.buildTarget(selection.providerKey);
         const forceVision = this.routeHasForceFlag('vision');
         const target = {
@@ -73,8 +92,10 @@ export class VirtualRouterEngine {
         catch {
             // stats must never break routing
         }
-        const hitReason = this.buildHitReason(selection.routeUsed, selection.providerKey, classification, features);
-        const formatted = this.formatVirtualRouterHit(selection.routeUsed, selection.poolId, selection.providerKey, target.modelId || '', hitReason);
+        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);
         }
@@ -114,6 +135,11 @@ export class VirtualRouterEngine {
         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);
         }
@@ -182,42 +208,151 @@ export class VirtualRouterEngine {
             }
         }
     }
-    selectProvider(requestedRoute, metadata, classification, features) {
-        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates, features);
-        const stickyKey = this.resolveStickyKey(metadata);
-        const attempted = [];
-        const visitedRoutes = new Set();
-        const routeQueue = this.initializeRouteQueue(candidates);
-        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);
-                if (providerKey) {
-                    return { providerKey, routeUsed: routeName, pool: poolTargets, poolId: tierId };
+    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 (failureHint) {
-                    attempted.push(failureHint);
+            }
+            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);
                 }
             }
         }
-        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
+        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) {
+    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 = [];
@@ -269,7 +404,7 @@ export class VirtualRouterEngine {
             const providerKey = this.loadBalancer.select({
                 routeName: `${routeName}:${tier.id}`,
                 candidates: candidatePool,
-                stickyKey,
+                stickyKey: allowAliasRotation ? undefined : stickyKey,
                 availabilityCheck: (key) => this.healthManager.isAvailable(key)
             });
             if (providerKey) {
@@ -325,12 +460,415 @@ export class VirtualRouterEngine {
         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
@@ -561,24 +1099,37 @@ export class VirtualRouterEngine {
         }
         return flattened;
     }
-    buildHitReason(routeUsed, providerKey, classification, features) {
+    buildHitReason(routeUsed, providerKey, classification, features, mode) {
         const reasoning = classification.reasoning || '';
-        const primary = reasoning.split('|')[0] || '';
+        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') {
-                return this.decorateWithDetail(primary || 'tools', primary, commandDetail);
+                const label = isStickyMode ? 'sticky' : 'tools';
+                return this.decorateWithDetail(primary || label, primary, commandDetail);
             }
             if (routeUsed === 'thinking') {
-                return this.decorateWithDetail(primary || 'thinking', primary, commandDetail);
+                const label = isStickyMode ? 'sticky' : 'thinking';
+                return this.decorateWithDetail(primary || label, primary, commandDetail);
             }
             if (routeUsed === 'coding') {
-                return this.decorateWithDetail(primary || 'coding', primary, commandDetail);
+                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) {
@@ -592,6 +1143,28 @@ export class VirtualRouterEngine {
         }
         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) {
@@ -602,7 +1175,7 @@ export class VirtualRouterEngine {
         }
         return `${baseLabel}(${normalizedDetail})`;
     }
-    formatVirtualRouterHit(routeName, poolId, providerKey, modelId, hitReason) {
+    formatVirtualRouterHit(routeName, poolId, providerKey, modelId, hitReason, stickyScope) {
         try {
             // 生成本地时间戳
             const now = new Date();
@@ -613,20 +1186,23 @@ export class VirtualRouterEngine {
             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}${reasonLabel}${reset}`;
+            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;
-            return `[virtual-router-hit] ${timestamp} ${routeLabel} -> ${providerKey}${modelId ? '.' + modelId : ''}${hitReason ? ` reason=${hitReason}` : ''}`;
+            const stickyLabel = stickyScope ? ` [sticky:${stickyScope}]` : '';
+            return `[virtual-router-hit] ${timestamp} ${routeLabel} -> ${providerKey}${modelId ? '.' + modelId : ''}${stickyLabel}${hitReason ? ` reason=${hitReason}` : ''}`;
         }
     }
     resolveRouteColor(routeName) {