@jsonstudio/llms 0.6.795 → 0.6.938

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

@@ -29,12 +29,32 @@ export function bootstrapVirtualRouterConfig(input) {
     }
     const webSearch = normalizeWebSearch(section.webSearch, routingSource);
     validateWebSearchRouting(webSearch, routingSource);
-    const { runtimeEntries, aliasIndex } = buildProviderRuntimeEntries(providersSource);
+    const execCommandGuard = normalizeExecCommandGuard(section.execCommandGuard);
+    const { runtimeEntries, aliasIndex, modelIndex } = buildProviderRuntimeEntries(providersSource);
     const { routing, targetKeys } = expandRoutingTable(routingSource, aliasIndex);
     if (!routing.default || routing.default.length === 0) {
         throw new VirtualRouterError('Virtual Router default route must contain at least one provider target', VirtualRouterErrorCode.CONFIG_ERROR);
     }
-    const { profiles: providerProfiles, targetRuntime } = buildProviderProfiles(targetKeys, runtimeEntries);
+    // Build provider profiles for:
+    // - routing targets (targetKeys), and
+    // - all declared provider models across all auth aliases (modelIndex × aliasIndex),
+    // so that "direct model" and "prefer model" routing can bypass route pools when needed.
+    const expandedTargetKeys = new Set(targetKeys);
+    for (const [providerId, aliases] of aliasIndex.entries()) {
+        const models = modelIndex.get(providerId) ?? [];
+        if (!models.length || !aliases.length) {
+            continue;
+        }
+        for (const alias of aliases) {
+            const runtimeKey = buildRuntimeKey(providerId, alias);
+            for (const modelId of models) {
+                if (modelId && typeof modelId === 'string') {
+                    expandedTargetKeys.add(`${runtimeKey}.${modelId}`);
+                }
+            }
+        }
+    }
+    const { profiles: providerProfiles, targetRuntime } = buildProviderProfiles(expandedTargetKeys, runtimeEntries);
     const classifier = normalizeClassifier(section.classifier);
     const loadBalancing = section.loadBalancing ?? DEFAULT_LOAD_BALANCING;
     const health = section.health ?? DEFAULT_HEALTH;
@@ -46,7 +66,8 @@ export function bootstrapVirtualRouterConfig(input) {
         loadBalancing,
         health,
         contextRouting,
-        ...(webSearch ? { webSearch } : {})
+        ...(webSearch ? { webSearch } : {}),
+        ...(execCommandGuard ? { execCommandGuard } : {})
     };
     return {
         config,
@@ -68,13 +89,17 @@ function extractVirtualRouterSection(input) {
     const health = normalizeHealth(section.health ?? root.health);
     const contextRouting = normalizeContextRouting(section.contextRouting ?? root.contextRouting);
     const webSearch = section.webSearch ?? root.webSearch;
-    return { providers, routing, classifier, loadBalancing, health, contextRouting, webSearch };
+    const execCommandGuard = section.execCommandGuard ?? root.execCommandGuard;
+    return { providers, routing, classifier, loadBalancing, health, contextRouting, webSearch, execCommandGuard };
 }
 function buildProviderRuntimeEntries(providers) {
     const runtimeEntries = {};
     const aliasIndex = new Map();
+    const modelIndex = new Map();
     for (const [providerId, providerRaw] of Object.entries(providers)) {
         const normalizedProvider = normalizeProvider(providerId, providerRaw);
+        const modelsNode = asRecord(providerRaw?.models);
+        modelIndex.set(providerId, modelsNode ? Object.keys(modelsNode).filter(Boolean) : []);
         const authEntries = extractProviderAuthEntries(providerId, providerRaw);
         if (!authEntries.length) {
             throw new VirtualRouterError(`Provider ${providerId} requires at least one auth entry`, VirtualRouterErrorCode.CONFIG_ERROR);
@@ -126,7 +151,7 @@ function buildProviderRuntimeEntries(providers) {
             };
         }
     }
-    return { runtimeEntries, aliasIndex };
+    return { runtimeEntries, aliasIndex, modelIndex };
 }
 function expandRoutingTable(routingSource, aliasIndex) {
     const routing = {};
@@ -690,6 +715,25 @@ function normalizeWebSearch(input, routingSource) {
         ...(force ? { force } : {})
     };
 }
+function normalizeExecCommandGuard(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return undefined;
+    }
+    const record = input;
+    const enabledRaw = record.enabled;
+    const enabled = enabledRaw === true ||
+        (typeof enabledRaw === 'string' && enabledRaw.trim().toLowerCase() === 'true') ||
+        (typeof enabledRaw === 'number' && enabledRaw === 1);
+    if (!enabled) {
+        return undefined;
+    }
+    const policyFileRaw = record.policyFile ?? record?.policy_file;
+    const policyFile = typeof policyFileRaw === 'string' && policyFileRaw.trim().length ? policyFileRaw.trim() : undefined;
+    return {
+        enabled: true,
+        ...(policyFile ? { policyFile } : {})
+    };
+}
 function extractProviderAuthEntries(providerId, raw) {
     const provider = asRecord(raw);
     const auth = asRecord(provider.auth);

package/dist/router/virtual-router/classifier.d.ts

@@ -0,0 +1,10 @@
+import type { ClassificationResult, RoutingFeatures, VirtualRouterClassifierConfig } from './types.js';
+export declare class RoutingClassifier {
+    private readonly config;
+    constructor(config: VirtualRouterClassifierConfig);
+    classify(features: RoutingFeatures): ClassificationResult;
+    private buildResult;
+    private ensureDefaultCandidate;
+    private orderRoutes;
+    private routeWeight;
+}

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

@@ -76,13 +76,41 @@ export function selectProviderImpl(requestedRoute, metadata, classification, fea
             }
         }
         if (forcedKeySet.size > 0) {
-            const candidates = buildRouteCandidates(requestedRoute, classification.candidates, features, deps.routing, deps.providerRegistry);
+            const candidates = extendRouteCandidatesForState(buildRouteCandidates(requestedRoute, classification.candidates, features, deps.routing, deps.providerRegistry), state, deps.routing);
             const filteredCandidates = filterCandidatesByRoutingState(candidates, state, deps.routing, deps.providerRegistry);
             if (filteredCandidates.length === 0) {
-                throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
+                const allowedProviders = Array.from(state.allowedProviders);
+                const disabledProviders = Array.from(state.disabledProviders);
+                const providersInRouting = new Set();
+                for (const pools of Object.values(deps.routing)) {
+                    if (!Array.isArray(pools))
+                        continue;
+                    for (const pool of pools) {
+                        if (!pool || !Array.isArray(pool.targets))
+                            continue;
+                        for (const key of pool.targets) {
+                            if (typeof key !== 'string' || !key)
+                                continue;
+                            const providerId = extractProviderId(key);
+                            if (providerId) {
+                                providersInRouting.add(providerId);
+                            }
+                        }
+                    }
+                }
+                const missingAllowedProviders = allowedProviders.length > 0 ? allowedProviders.filter((provider) => !providersInRouting.has(provider)) : [];
+                const hint = (() => {
+                    if (missingAllowedProviders.length > 0) {
+                        return `Allowed providers not present in routing pools: ${missingAllowedProviders.join(', ')}`;
+                    }
+                    return 'Routing instructions excluded all route candidates';
+                })();
+                throw new VirtualRouterError(`No available providers after applying routing instructions (${hint}). ` +
+                    `Tip: remove/adjust <**...**> routing instructions (or use <**clear**>), or add providers/models to routing.`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
                     requestedRoute,
-                    allowedProviders: Array.from(state.allowedProviders),
-                    disabledProviders: Array.from(state.disabledProviders)
+                    allowedProviders,
+                    disabledProviders,
+                    missingAllowedProviders
                 });
             }
             return selectFromCandidates(filteredCandidates, metadata, classification, features, state, deps, {
@@ -98,18 +126,65 @@ export function selectProviderImpl(requestedRoute, metadata, classification, fea
         }
     }
     const candidates = buildRouteCandidates(requestedRoute, classification.candidates, features, deps.routing, deps.providerRegistry);
-    const filteredCandidates = filterCandidatesByRoutingState(candidates, state, deps.routing, deps.providerRegistry);
+    const expandedCandidates = extendRouteCandidatesForState(candidates, state, deps.routing);
+    const filteredCandidates = filterCandidatesByRoutingState(expandedCandidates, state, deps.routing, deps.providerRegistry);
     if (filteredCandidates.length === 0) {
-        throw new VirtualRouterError('No available providers after applying routing instructions', VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
+        const allowedProviders = Array.from(state.allowedProviders);
+        const disabledProviders = Array.from(state.disabledProviders);
+        const providersInRouting = new Set();
+        for (const pools of Object.values(deps.routing)) {
+            if (!Array.isArray(pools))
+                continue;
+            for (const pool of pools) {
+                if (!pool || !Array.isArray(pool.targets))
+                    continue;
+                for (const key of pool.targets) {
+                    if (typeof key !== 'string' || !key)
+                        continue;
+                    const providerId = extractProviderId(key);
+                    if (providerId) {
+                        providersInRouting.add(providerId);
+                    }
+                }
+            }
+        }
+        const missingAllowedProviders = allowedProviders.length > 0 ? allowedProviders.filter((provider) => !providersInRouting.has(provider)) : [];
+        const hint = (() => {
+            if (missingAllowedProviders.length > 0) {
+                return `Allowed providers not present in routing pools: ${missingAllowedProviders.join(', ')}`;
+            }
+            return 'Routing instructions excluded all route candidates';
+        })();
+        throw new VirtualRouterError(`No available providers after applying routing instructions (${hint}). ` +
+            `Tip: remove/adjust <**...**> routing instructions (or use <**clear**>), or add providers/models to routing.`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, {
             requestedRoute,
-            allowedProviders: Array.from(state.allowedProviders),
-            disabledProviders: Array.from(state.disabledProviders)
+            allowedProviders,
+            disabledProviders,
+            missingAllowedProviders
         });
     }
     return selectFromCandidates(filteredCandidates, metadata, classification, features, state, deps, {
         allowAliasRotation
     });
 }
+function extendRouteCandidatesForState(candidates, state, routing) {
+    // When provider allowlists are active (e.g. "<**!glm**>"), routing should not be bounded by
+    // classifier candidates only. Otherwise, a perfectly valid provider that exists in config
+    // (e.g. in a backup/default pool) can become unreachable and cause PROVIDER_NOT_AVAILABLE.
+    //
+    // We keep original ordering, then append all known routes (by priority) as a fallback search space.
+    if (!state.allowedProviders || state.allowedProviders.size === 0) {
+        return candidates;
+    }
+    const allRoutes = sortByPriority(Object.keys(routing).filter((routeName) => routeName && routeHasTargets(routing[routeName])));
+    const expanded = Array.isArray(candidates) ? [...candidates] : [];
+    for (const routeName of allRoutes) {
+        if (!expanded.includes(routeName)) {
+            expanded.push(routeName);
+        }
+    }
+    return expanded;
+}
 export function selectDirectProviderModel(providerId, modelId, metadata, features, activeState, deps) {
     const normalizedProvider = typeof providerId === 'string' ? providerId.trim() : '';
     const normalizedModel = typeof modelId === 'string' ? modelId.trim() : '';
@@ -220,7 +295,11 @@ function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features
         targets = targets.filter((key) => !excludedKeys.has(key));
     }
     if (targets.length > 0) {
-        targets = targets.filter((key) => !deps.isProviderCoolingDown(key));
+        const cooled = targets.filter((key) => !deps.isProviderCoolingDown(key));
+        // 单 provider 兜底：当一个 tier 只有一个候选 key 时，不因 cooldown 造成路由池为空。
+        if (cooled.length > 0 || targets.length !== 1) {
+            targets = cooled;
+        }
     }
     if (allowedProviders && allowedProviders.size > 0) {
         targets = targets.filter((key) => {
@@ -331,14 +410,22 @@ function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features
     const selectWithQuota = (candidates) => {
         if (!quotaView) {
             if (tier.mode === 'priority') {
-                return selectFirstAvailable(candidates);
+                const selected = selectFirstAvailable(candidates);
+                if (!selected && candidates.length === 1) {
+                    return candidates[0];
+                }
+                return selected;
             }
-            return deps.loadBalancer.select({
+            const selected = deps.loadBalancer.select({
                 routeName: `${routeName}:${tier.id}`,
                 candidates,
                 stickyKey: options.allowAliasRotation ? undefined : stickyKey,
                 availabilityCheck: (key) => deps.healthManager.isAvailable(key)
             }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+            if (!selected && candidates.length === 1) {
+                return candidates[0];
+            }
+            return selected;
         }
         const buckets = new Map();
         for (const key of candidates) {
@@ -389,6 +476,33 @@ function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features
                 }
             }
         }
+        // default 路由永不因 quota gating 而“空池”：
+        // 当 quotaView 过滤后没有任何可用候选时，默认路由允许忽略 quotaView，
+        // 继续按健康/负载均衡选择一个 providerKey（但不覆盖 forced/required 约束）。
+        const quotaBypassAllowed = routeName === DEFAULT_ROUTE && (!requiredProviderKeys || requiredProviderKeys.size === 0);
+        if (quotaBypassAllowed) {
+            if (tier.mode === 'priority') {
+                const selected = selectFirstAvailable(candidates);
+                if (selected) {
+                    return selected;
+                }
+            }
+            else {
+                const selected = deps.loadBalancer.select({
+                    routeName: `${routeName}:${tier.id}:quota-bypass`,
+                    candidates,
+                    stickyKey: options.allowAliasRotation ? undefined : stickyKey,
+                    availabilityCheck: (key) => deps.healthManager.isAvailable(key)
+                }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+                if (selected) {
+                    return selected;
+                }
+            }
+        }
+        // 单 provider 兜底：当只剩一个候选 key 时，不因 quota/blacklist/cooldown 或健康状态过滤导致无 provider。
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
         return null;
     };
     for (const candidatePool of prioritizedPools) {
@@ -416,10 +530,13 @@ export function selectFromStickyPool(stickyKeySet, metadata, features, state, de
     ]));
     const disabledModels = new Map(Array.from(state.disabledModels.entries()).map(([provider, models]) => [provider, new Set(models)]));
     let candidates = Array.from(stickyKeySet).filter((key) => !deps.isProviderCoolingDown(key));
+    if (!candidates.length && stickyKeySet.size === 1) {
+        candidates = Array.from(stickyKeySet);
+    }
     const quotaView = deps.quotaView;
     const now = quotaView ? Date.now() : 0;
     if (quotaView) {
-        candidates = candidates.filter((key) => {
+        const filtered = candidates.filter((key) => {
             const entry = quotaView(key);
             if (!entry) {
                 return true;
@@ -435,6 +552,9 @@ export function selectFromStickyPool(stickyKeySet, metadata, features, state, de
             }
             return true;
         });
+        if (filtered.length > 0 || candidates.length !== 1) {
+            candidates = filtered;
+        }
     }
     if (allowedProviders.size > 0) {
         candidates = candidates.filter((key) => {
@@ -777,9 +897,21 @@ function resolveInstructionTarget(target, providerRegistry) {
     const alias = typeof target.keyAlias === 'string' ? target.keyAlias.trim() : '';
     const aliasExplicit = alias.length > 0 && target.pathLength === 3;
     if (aliasExplicit) {
-        const runtimeKey = providerRegistry.resolveRuntimeKeyByAlias(providerId, alias);
-        if (runtimeKey) {
-            return { mode: 'exact', keys: [runtimeKey] };
+        const prefix = `${providerId}.${alias}.`;
+        const aliasKeys = providerKeys.filter((key) => key.startsWith(prefix));
+        if (aliasKeys.length > 0) {
+            if (target.model && target.model.trim()) {
+                const normalizedModel = target.model.trim();
+                const matching = aliasKeys.filter((key) => getProviderModelId(key, providerRegistry) === normalizedModel);
+                if (matching.length > 0) {
+                    // Prefer exact to keep sticky pool deterministic when only one key matches.
+                    if (matching.length === 1) {
+                        return { mode: 'exact', keys: [matching[0]] };
+                    }
+                    return { mode: 'filter', keys: matching };
+                }
+            }
+            return { mode: 'filter', keys: aliasKeys };
         }
     }
     if (typeof target.keyIndex === 'number' && target.keyIndex > 0) {

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

@@ -9,7 +9,7 @@ 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 { selectDirectProviderModel, selectProviderImpl } from './engine-selection.js';
+import { selectDirectProviderModel, selectFromStickyPool, selectProviderImpl } from './engine-selection.js';
 import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
 export class VirtualRouterEngine {
     routing = {};
@@ -105,7 +105,11 @@ export class VirtualRouterEngine {
     }
     route(request, metadata) {
         const stickyKey = this.resolveStickyKey(metadata);
-        const baseState = this.getRoutingInstructionState(stickyKey);
+        const sessionScope = this.resolveSessionScope(metadata);
+        // Routing instructions should be session/conversation-scoped when available (including /v1/responses),
+        // while auto-sticky for Responses remains request-chain scoped via resolveStickyKey().
+        const stateKey = sessionScope || stickyKey || 'default';
+        const baseState = this.getRoutingInstructionState(stateKey);
         let routingState = baseState;
         const metadataInstructions = this.buildMetadataInstructions(metadata);
         if (metadataInstructions.length > 0) {
@@ -114,13 +118,13 @@ export class VirtualRouterEngine {
         const disableStickyRoutes = metadata &&
             typeof metadata === 'object' &&
             metadata.disableStickyRoutes === true;
-        if (disableStickyRoutes && routingState.stickyTarget) {
+        if (disableStickyRoutes && (routingState.stickyTarget || routingState.preferTarget)) {
             routingState = {
                 ...routingState,
-                stickyTarget: undefined
+                stickyTarget: undefined,
+                preferTarget: undefined
             };
         }
-        const sessionScope = this.resolveSessionScope(metadata);
         if (sessionScope) {
             const sessionState = this.getRoutingInstructionState(sessionScope);
             if (typeof sessionState.stopMessageText === 'string' ||
@@ -163,9 +167,8 @@ export class VirtualRouterEngine {
         }
         if (instructions.length > 0) {
             routingState = applyRoutingInstructions(instructions, routingState);
-            const effectiveKey = stickyKey || 'default';
-            this.routingInstructionState.set(effectiveKey, routingState);
-            this.persistRoutingInstructionState(effectiveKey, routingState);
+            this.routingInstructionState.set(stateKey, routingState);
+            this.persistRoutingInstructionState(stateKey, routingState);
             // 对 stopMessage 指令补充一份基于 session/conversation 的持久化状态，
             // 便于 server-side 工具通过 session:*/conversation:* scope 读取到相同配置。
             if (sessionScope) {
@@ -236,12 +239,52 @@ export class VirtualRouterEngine {
                 routingState.stopMessageLastUsedAt = sessionState.stopMessageLastUsedAt;
             }
         }
-        const routingMode = this.resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
+        // Guardrail: if a session is restricted to providers that do not exist in any routing pools,
+        // we must not hard-fail the request loop. Auto-clear the allowlist and fall back to normal routing.
+        if (routingState.allowedProviders.size > 0) {
+            const providersInRouting = new Set();
+            for (const pools of Object.values(this.routing)) {
+                if (!Array.isArray(pools))
+                    continue;
+                for (const pool of pools) {
+                    if (!pool || !Array.isArray(pool.targets))
+                        continue;
+                    for (const key of pool.targets) {
+                        if (typeof key !== 'string' || !key)
+                            continue;
+                        const providerId = this.extractProviderId(key);
+                        if (providerId) {
+                            providersInRouting.add(providerId);
+                        }
+                    }
+                }
+            }
+            const allowed = Array.from(routingState.allowedProviders);
+            const hasIntersection = allowed.some((provider) => providersInRouting.has(provider));
+            if (!hasIntersection) {
+                routingState = {
+                    ...routingState,
+                    allowedProviders: new Set()
+                };
+                this.routingInstructionState.set(stateKey, routingState);
+                this.persistRoutingInstructionState(stateKey, routingState);
+            }
+        }
         const features = buildRoutingFeatures(request, metadata);
         const directProviderModel = this.parseDirectProviderModel(request?.model);
         let classification;
         let requestedRoute;
         let selection;
+        const selectionDeps = {
+            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),
+            quotaView: this.quotaView
+        };
         if (directProviderModel) {
             const providerKeys = this.providerRegistry.listProviderKeys(directProviderModel.providerId);
             let hasModel = false;
@@ -268,33 +311,129 @@ export class VirtualRouterEngine {
                 candidates: ['direct']
             };
             requestedRoute = 'direct';
-            const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, {
-                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),
-                quotaView: this.quotaView
-            });
+            const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, selectionDeps);
             if (!directSelection) {
                 throw new VirtualRouterError(`All providers unavailable for model ${directProviderModel.providerId}.${directProviderModel.modelId}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
             }
             selection = directSelection;
         }
         else {
-            classification = metadata.routeHint && metadata.routeHint.trim()
-                ? {
-                    routeName: metadata.routeHint.trim(),
-                    confidence: 1,
-                    reasoning: `route_hint:${metadata.routeHint.trim()}`,
-                    fallback: false,
-                    candidates: [metadata.routeHint.trim()]
+            // Prefer target (from "<**!provider.model**>") is evaluated before routing classification.
+            const preferTarget = routingState.preferTarget;
+            if (preferTarget && typeof preferTarget.provider === 'string' && preferTarget.provider.trim()) {
+                const providerId = preferTarget.provider.trim();
+                const keyAlias = typeof preferTarget.keyAlias === 'string' ? preferTarget.keyAlias.trim() : '';
+                const modelId = typeof preferTarget.model === 'string' ? preferTarget.model.trim() : '';
+                const keyIndex = typeof preferTarget.keyIndex === 'number' && Number.isFinite(preferTarget.keyIndex)
+                    ? Math.floor(preferTarget.keyIndex)
+                    : undefined;
+                const candidateKeys = [];
+                if (keyIndex !== undefined && keyIndex > 0) {
+                    const runtimeKey = this.providerRegistry.resolveRuntimeKeyByIndex(providerId, keyIndex);
+                    if (runtimeKey) {
+                        candidateKeys.push(runtimeKey);
+                    }
                 }
-                : this.classifier.classify(features);
-            requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
-            selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
+                else if (modelId) {
+                    const allKeys = this.providerRegistry.listProviderKeys(providerId);
+                    for (const key of allKeys) {
+                        if (keyAlias) {
+                            const prefix = `${providerId}.${keyAlias}.`;
+                            if (!key.startsWith(prefix)) {
+                                continue;
+                            }
+                        }
+                        try {
+                            const profile = this.providerRegistry.get(key);
+                            if (profile?.modelId === modelId) {
+                                candidateKeys.push(key);
+                            }
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                }
+                const allowAliasRotation = !keyAlias && keyIndex === undefined;
+                const eligibleKeys = (() => {
+                    if (candidateKeys.length === 0) {
+                        return [];
+                    }
+                    const quotaView = selectionDeps.quotaView;
+                    const now = quotaView ? Date.now() : 0;
+                    return candidateKeys.filter((key) => {
+                        if (this.isProviderCoolingDown(key)) {
+                            return false;
+                        }
+                        if (!this.healthManager.isAvailable(key)) {
+                            return false;
+                        }
+                        if (!quotaView) {
+                            return true;
+                        }
+                        const entry = quotaView(key);
+                        if (!entry) {
+                            return true;
+                        }
+                        if (!entry.inPool) {
+                            return false;
+                        }
+                        if (entry.cooldownUntil && entry.cooldownUntil > now) {
+                            return false;
+                        }
+                        if (entry.blacklistUntil && entry.blacklistUntil > now) {
+                            return false;
+                        }
+                        return true;
+                    });
+                })();
+                const preferSelection = eligibleKeys.length > 0
+                    ? selectFromStickyPool(new Set(eligibleKeys), metadata, features, routingState, selectionDeps, {
+                        allowAliasRotation
+                    })
+                    : null;
+                if (preferSelection) {
+                    classification = {
+                        routeName: 'prefer',
+                        confidence: 1,
+                        reasoning: keyIndex !== undefined ? `prefer_key:${providerId}.${keyIndex}` : `prefer_model:${providerId}.${modelId}`,
+                        fallback: false,
+                        candidates: ['prefer']
+                    };
+                    requestedRoute = 'prefer';
+                    selection = {
+                        ...preferSelection,
+                        routeUsed: 'prefer',
+                        poolId: 'prefer-primary'
+                    };
+                }
+                else if (routingState.preferTarget) {
+                    // Auto-clear only when the target becomes invalid or blocked by explicit routing instructions.
+                    // Do NOT clear for temporary unavailability (e.g. 429 cooldown, quota cooldown, transient health).
+                    const shouldAutoClear = candidateKeys.length === 0 || eligibleKeys.length > 0;
+                    if (shouldAutoClear) {
+                        routingState = {
+                            ...routingState,
+                            preferTarget: undefined
+                        };
+                        this.routingInstructionState.set(stateKey, routingState);
+                        this.persistRoutingInstructionState(stateKey, routingState);
+                    }
+                }
+            }
+            if (!selection) {
+                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);
+                requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+                selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
+            }
         }
         const baseTarget = this.providerRegistry.buildTarget(selection.providerKey);
         const forceVision = this.routeHasForceFlag('vision');
@@ -304,6 +443,7 @@ export class VirtualRouterEngine {
             ...(forceVision ? { forceVision: true } : {})
         };
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
+        const routingMode = this.resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
         try {
             this.statsCenter.recordVirtualRouterHit({
                 requestId: metadata.requestId,
@@ -577,7 +717,7 @@ export class VirtualRouterEngine {
         // 能在 VirtualRouter 日志中实时反映出来。
         if (existing && (key.startsWith('session:') || key.startsWith('conversation:'))) {
             try {
-                const persisted = loadRoutingInstructionStateSync(key);
+                const persisted = this.routingStateStore.loadSync(key);
                 if (persisted) {
                     // 以持久化状态为准（包括清空后的 undefined），避免 stopMessage 状态“卡死”在内存中。
                     existing.stopMessageText = persisted.stopMessageText;
@@ -603,7 +743,7 @@ export class VirtualRouterEngine {
         let initial = null;
         // 仅对 session:/conversation: 作用域的 key 尝试从磁盘恢复持久化状态
         if (key.startsWith('session:') || key.startsWith('conversation:')) {
-            initial = loadRoutingInstructionStateSync(key);
+            initial = this.routingStateStore.loadSync(key);
         }
         if (!initial) {
             initial = {
@@ -661,6 +801,7 @@ export class VirtualRouterEngine {
         const hasForce = instructions.some((inst) => inst.type === 'force');
         const hasAllow = instructions.some((inst) => inst.type === 'allow');
         const hasClear = instructions.some((inst) => inst.type === 'clear');
+        const hasPrefer = instructions.some((inst) => inst.type === 'prefer');
         if (hasClear) {
             return 'none';
         }
@@ -670,6 +811,9 @@ export class VirtualRouterEngine {
         if (hasForce || state.forcedTarget) {
             return 'force';
         }
+        if (hasPrefer || state.preferTarget) {
+            return 'sticky';
+        }
         if (state.stickyTarget) {
             return 'sticky';
         }
@@ -1114,6 +1258,7 @@ export class VirtualRouterEngine {
         }
         const noForced = !state.forcedTarget;
         const noSticky = !state.stickyTarget;
+        const noPrefer = !state.preferTarget;
         const noAllowed = state.allowedProviders.size === 0;
         const noDisabledProviders = state.disabledProviders.size === 0;
         const noDisabledKeys = state.disabledKeys.size === 0;
@@ -1125,6 +1270,7 @@ export class VirtualRouterEngine {
             (typeof state.stopMessageLastUsedAt !== 'number' || !Number.isFinite(state.stopMessageLastUsedAt));
         return (noForced &&
             noSticky &&
+            noPrefer &&
             noAllowed &&
             noDisabledProviders &&
             noDisabledKeys &&