@jsonstudio/llms 0.6.230 → 0.6.467

package/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();
@@ -18,6 +20,9 @@ export class VirtualRouterEngine {
     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;
@@ -29,17 +34,48 @@ export class VirtualRouterEngine {
         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 = this.classifier.classify(features);
-        const routeName = classification.routeName || DEFAULT_ROUTE;
-        const selection = this.selectProvider(routeName, metadata, classification, features);
-        const target = this.providerRegistry.buildTarget(selection.providerKey);
+        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 {
@@ -56,15 +92,17 @@ 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);
         }
         else {
             this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '', hitReason ? `reason=${hitReason}` : '');
         }
-        const didFallback = selection.routeUsed !== routeName;
+        const didFallback = selection.routeUsed !== requestedRoute;
         return {
             target,
             decision: {
@@ -123,6 +161,14 @@ export class VirtualRouterEngine {
             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);
@@ -157,42 +203,180 @@ export class VirtualRouterEngine {
             }
         }
     }
-    selectProvider(requestedRoute, metadata, classification, features) {
-        const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates);
-        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;
+    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'
+                    };
+                }
             }
-            const routePools = this.routing[routeName];
-            if (!this.routeHasTargets(routePools)) {
-                visitedRoutes.add(routeName);
-                attempted.push(`${routeName}:empty`);
-                continue;
+            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);
+                }
             }
-            visitedRoutes.add(routeName);
-            const orderedPools = this.sortRoutePools(routePools);
-            for (const poolTier of orderedPools) {
-                const { providerKey, poolTargets, tierId, failureHint } = this.trySelectFromTier(routeName, poolTier, stickyKey, estimatedTokens);
-                if (providerKey) {
-                    return { providerKey, routeUsed: routeName, pool: poolTargets, poolId: tierId };
+        }
+        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 : [];
+        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 (failureHint) {
-                    attempted.push(failureHint);
+                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;
+            }
         }
-        throw new VirtualRouterError(`All providers unavailable for route ${requestedRoute}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { routeName: requestedRoute, attempted });
-    }
-    trySelectFromTier(routeName, tier, stickyKey, estimatedTokens) {
-        const targets = Array.isArray(tier.targets) ? tier.targets : [];
         if (!targets.length) {
             return { providerKey: null, poolTargets: [], tierId: tier.id, failureHint: `${routeName}:${tier.id}:empty` };
         }
@@ -202,7 +386,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) {
@@ -258,12 +442,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
@@ -346,12 +933,32 @@ export class VirtualRouterEngine {
             return 'client_error';
         return 'unknown';
     }
-    buildRouteCandidates(requestedRoute, classificationCandidates) {
-        const normalized = requestedRoute || DEFAULT_ROUTE;
-        const baseList = classificationCandidates && classificationCandidates.length
-            ? classificationCandidates
-            : [normalized];
-        const ordered = this.sortByPriority(baseList);
+    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)) {
@@ -367,6 +974,53 @@ export class VirtualRouterEngine {
         }
         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));
     }
@@ -374,6 +1028,13 @@ export class VirtualRouterEngine {
         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;
@@ -420,24 +1081,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 === 'websearch') {
-                return this.decorateWithDetail(primary || 'websearch', 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) {
@@ -451,6 +1125,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) {
@@ -461,7 +1157,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();
@@ -472,20 +1168,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) {
@@ -495,7 +1194,8 @@ export class VirtualRouterEngine {
             thinking: '\x1b[34m',
             coding: '\x1b[35m',
             longcontext: '\x1b[38;5;141m',
-            websearch: '\x1b[32m',
+            web_search: '\x1b[32m',
+            search: '\x1b[38;5;34m',
             vision: '\x1b[38;5;207m',
             background: '\x1b[90m'
         };