llm-simple-router 0.1.0 → 0.2.0

package/dist/proxy/enhancement-handler.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "crypto";
+import { getSetting } from "../db/settings.js";
+import { getActiveProviderModels, resolveByProviderModel } from "../db/index.js";
+import { resolveMapping } from "./mapping-resolver.js";
+import { parseDirective } from "./directive-parser.js";
+import { modelState } from "./model-state.js";
+import { cleanRouterResponses } from "./response-cleaner.js";
+const MODEL_INFO_TAG_TYPE = "model-info";
+/**
+ * 解析 "provider_name/backend_model" 格式，返回对应的 client_model。
+ * provider_name 只允许 [a-zA-Z0-9_-]，/ 作为分隔符。
+ */
+function resolveProviderModel(db, providerSlashModel) {
+    const match = /^([a-zA-Z0-9_-]+)\/(.+)$/.exec(providerSlashModel);
+    if (!match)
+        return null;
+    const resolved = resolveByProviderModel(db, match[1], match[2]);
+    return resolved?.client_model ?? null;
+}
+/**
+ * 在代理转发前应用代理增强逻辑（指令解析 + 会话记忆 + 模型替换 + 命令拦截）。
+ * 仅当 proxy_enhancement.claude_code_enabled 开启时生效。
+ */
+export function applyEnhancement(db, request, clientModel, sessionId) {
+    const nullResult = { effectiveModel: clientModel, originalModel: null, interceptResponse: null };
+    const enhancementRaw = getSetting(db, "proxy_enhancement");
+    let enhancement = null;
+    try {
+        enhancement = enhancementRaw ? JSON.parse(enhancementRaw) : null;
+    }
+    catch {
+        request.log.warn("Invalid proxy_enhancement JSON, feature disabled");
+    }
+    if (enhancement?.claude_code_enabled !== true) {
+        return nullResult;
+    }
+    // 清理历史消息中的 <router-response> 标签
+    const cleaned = cleanRouterResponses(request.body);
+    request.body.messages = cleaned.messages;
+    const directive = parseDirective(request.body);
+    // 命令拦截：select-model → 返回可用模型列表
+    if (directive.isCommandMessage && directive.command?.startsWith("select-model")) {
+        const routerKeyId = request.routerKey?.id ?? null;
+        const parts = directive.command.trim().split(/\s+/);
+        const arg = parts.length > 1 ? parts.slice(1).join(" ") : null;
+        // 带参数：设置模型并返回确认
+        if (arg && arg !== "") {
+            const resolvedClientModel = resolveProviderModel(db, arg);
+            if (!resolvedClientModel) {
+                return {
+                    effectiveModel: clientModel,
+                    originalModel: null,
+                    interceptResponse: {
+                        ...buildTextResponse("error", `未找到模型: ${arg}`),
+                        meta: { action: "模型选择失败", detail: arg },
+                    },
+                };
+            }
+            modelState.set(routerKeyId, arg, sessionId, clientModel, "command");
+            return {
+                effectiveModel: arg,
+                originalModel: null,
+                interceptResponse: {
+                    ...buildSelectModelResponse(db, request.routerKey?.allowed_models ?? null, arg),
+                    meta: { action: "模型选择", detail: arg },
+                },
+            };
+        }
+        // 无参数：返回模型列表
+        return {
+            effectiveModel: clientModel,
+            originalModel: null,
+            interceptResponse: {
+                ...buildSelectModelResponse(db, request.routerKey?.allowed_models ?? null),
+                meta: { action: "模型列表" },
+            },
+        };
+    }
+    if (directive.modelName) {
+        // 内联模型指令 → resolveMapping 验证（client_model 格式）
+        const resolvedDirective = resolveMapping(db, directive.modelName, { now: new Date() });
+        if (resolvedDirective) {
+            modelState.set(request.routerKey?.id ?? null, directive.modelName, sessionId, clientModel, "directive");
+            request.body.messages = directive.cleanedBody.messages;
+            return { effectiveModel: directive.modelName, originalModel: clientModel, interceptResponse: null };
+        }
+        // 映射失败时保留原始请求（降级策略）
+        return nullResult;
+    }
+    // 无指令 → 查询会话记忆
+    const remembered = modelState.get(request.routerKey?.id ?? null, sessionId);
+    if (remembered) {
+        // 优先尝试 provider_name/backend_model 格式（select-model 命令存储）
+        // 直接保留该格式，resolveMapping 会解析出 provider + model
+        const providerResolved = resolveProviderModel(db, remembered);
+        if (providerResolved) {
+            return { effectiveModel: remembered, originalModel: clientModel, interceptResponse: null };
+        }
+        // 回退到 client_model 格式（内联指令存储）
+        const resolvedRemembered = resolveMapping(db, remembered, { now: new Date() });
+        if (resolvedRemembered) {
+            return { effectiveModel: remembered, originalModel: clientModel, interceptResponse: null };
+        }
+    }
+    return nullResult;
+}
+/** 构造 Anthropic 格式的 router 文本响应 */
+function buildTextResponse(type, inner) {
+    const text = `<router-response type="${type}">${inner}</router-response>`;
+    const body = {
+        id: `msg-${randomUUID()}`,
+        type: "message",
+        role: "assistant",
+        content: [{ type: "text", text }],
+        model: "router",
+        stop_reason: "end_turn",
+        stop_sequence: null,
+        usage: { input_tokens: 0, output_tokens: 0 },
+    };
+    return { statusCode: 200, body };
+}
+/** 查询所有可用的 provider_model 并构造响应 */
+function buildSelectModelResponse(db, allowedModelsRaw, selectedModel) {
+    const providerModels = getActiveProviderModels(db);
+    // 按 allowed_models 过滤（allowed_models 存储的是 client_model 列表）
+    let allowedSet = null;
+    if (allowedModelsRaw) {
+        try {
+            const parsed = JSON.parse(allowedModelsRaw).filter((s) => s.trim() !== "");
+            if (parsed.length > 0)
+                allowedSet = new Set(parsed);
+        }
+        catch { /* 忽略解析失败 */ }
+    }
+    const filtered = allowedSet
+        ? providerModels.filter(m => allowedSet.has(m.backend_model))
+        : providerModels;
+    // 去重并格式化为 "provider_name/backend_model"
+    const seen = new Set();
+    const displayModels = [];
+    for (const m of filtered) {
+        const key = `${m.provider_name}/${m.backend_model}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            displayModels.push(key);
+        }
+    }
+    let inner;
+    let responseType;
+    if (selectedModel) {
+        inner = `已选择模型: ${selectedModel}`;
+        responseType = "model-selected";
+    }
+    else if (displayModels.length > 0) {
+        inner = displayModels.map((m, i) => `${i + 1}. ${m}`).join("\n");
+        responseType = "model-list";
+    }
+    else {
+        inner = "（无可用模型）";
+        responseType = "model-list";
+    }
+    return buildTextResponse(responseType, inner);
+}
+/** 生成注入到非流式响应中的模型信息标签 */
+export function buildModelInfoTag(effectiveModel) {
+    return `<router-response type="${MODEL_INFO_TAG_TYPE}">当前模型: ${effectiveModel}</router-response>`;
+}

package/dist/proxy/log-helpers.d.ts

@@ -0,0 +1,41 @@
+import Database from "better-sqlite3";
+import type { Provider } from "../db/index.js";
+import type { RawHeaders } from "./proxy-core.js";
+export interface RequestLogParams {
+    id: string;
+    apiType: string;
+    model: string;
+    provider: Provider;
+    isStream: boolean;
+    startTime: number;
+    reqBody: string;
+    clientReq: string;
+    upstreamReq: string;
+    status: number;
+    respBody: string | null;
+    upHdrs: Record<string, string>;
+    cliHdrs: Record<string, string>;
+    isRetry?: boolean;
+    originalRequestId?: string | null;
+    routerKeyId?: string | null;
+    originalModel?: string | null;
+}
+/** 插入成功请求日志，供 openai/anthropic 插件共享 */
+export declare function insertSuccessLog(db: Database.Database, params: RequestLogParams): void;
+export interface RejectedLogParams {
+    db: Database.Database;
+    logId: string;
+    apiType: string;
+    model: string;
+    statusCode: number;
+    errorMessage: string;
+    startTime: number;
+    isStream: boolean;
+    routerKeyId: string | null;
+    originalBody: Record<string, unknown>;
+    clientHeaders: RawHeaders;
+    providerId?: string | null;
+    originalModel?: string | null;
+}
+/** Log a request rejected before reaching upstream */
+export declare function insertRejectedLog(params: RejectedLogParams): void;

package/dist/proxy/log-helpers.js

@@ -0,0 +1,35 @@
+import { insertRequestLog } from "../db/index.js";
+/** 插入成功请求日志，供 openai/anthropic 插件共享 */
+export function insertSuccessLog(db, params) {
+    const { id: logId, apiType, model, provider, isStream, startTime, reqBody, clientReq, upstreamReq, status, respBody, upHdrs, cliHdrs, isRetry = false, originalRequestId = null, routerKeyId = null, originalModel = null } = params;
+    insertRequestLog(db, {
+        id: logId, api_type: apiType, model, provider_id: provider.id,
+        status_code: status, latency_ms: Date.now() - startTime,
+        is_stream: isStream ? 1 : 0, error_message: null,
+        created_at: new Date().toISOString(), request_body: reqBody,
+        response_body: respBody, client_request: clientReq, upstream_request: upstreamReq,
+        upstream_response: JSON.stringify({ statusCode: status, headers: upHdrs, body: respBody }),
+        client_response: JSON.stringify({ statusCode: status, headers: cliHdrs, body: respBody }),
+        is_retry: isRetry ? 1 : 0, original_request_id: originalRequestId,
+        router_key_id: routerKeyId, original_model: originalModel,
+    });
+}
+/** Log a request rejected before reaching upstream */
+export function insertRejectedLog(params) {
+    const { db, logId, apiType, model, statusCode, errorMessage, startTime, isStream, routerKeyId, originalBody, clientHeaders, providerId = null, originalModel = null } = params;
+    insertRequestLog(db, {
+        id: logId,
+        api_type: apiType,
+        model,
+        provider_id: providerId,
+        status_code: statusCode,
+        latency_ms: Date.now() - startTime,
+        is_stream: isStream ? 1 : 0,
+        error_message: errorMessage,
+        created_at: new Date().toISOString(),
+        request_body: JSON.stringify(originalBody),
+        client_request: JSON.stringify({ headers: clientHeaders, body: originalBody }),
+        router_key_id: routerKeyId,
+        original_model: originalModel,
+    });
+}

package/dist/proxy/mapping-resolver.js

@@ -1,5 +1,8 @@
 import { STRATEGY_NAMES } from "./strategy/types.js";
 import { ScheduledStrategy } from "./strategy/scheduled.js";
+import { RoundRobinStrategy } from "./strategy/round-robin.js";
+import { RandomStrategy } from "./strategy/random.js";
+import { FailoverStrategy } from "./strategy/failover.js";
 import { getMappingGroup } from "../db/index.js";
 // 策略注册表：key 为数据库中 mapping_groups.strategy 字段的值。
 // 新增策略时：
@@ -7,11 +10,45 @@ import { getMappingGroup } from "../db/index.js";
 // 2. 在此注册表中添加映射
 const STRATEGIES = {
     [STRATEGY_NAMES.SCHEDULED]: new ScheduledStrategy(),
+    [STRATEGY_NAMES.ROUND_ROBIN]: new RoundRobinStrategy(),
+    [STRATEGY_NAMES.RANDOM]: new RandomStrategy(),
+    [STRATEGY_NAMES.FAILOVER]: new FailoverStrategy(),
 };
 export function resolveMapping(db, clientModel, context) {
+    // 优先处理 provider_name/backend_model 格式（如 kimi-coding-plan/kimi-for-coding）
+    // 这种格式直接路由到指定 provider，不需要 mapping group
+    const slashMatch = /^([a-zA-Z0-9_-]+)\/(.+)$/.exec(clientModel);
+    if (slashMatch) {
+        const providerName = slashMatch[1];
+        const backendModel = slashMatch[2];
+        const provider = db.prepare("SELECT id, models FROM providers WHERE name = ? AND is_active = 1").get(providerName);
+        if (provider) {
+            try {
+                const models = JSON.parse(provider.models);
+                if (models.includes(backendModel)) {
+                    return { backend_model: backendModel, provider_id: provider.id };
+                }
+            }
+            catch { /* 忽略解析失败 */ }
+        }
+        // 明确的 provider/model 格式解析失败，不再 fallback 到 mapping group
+        return null;
+    }
     const group = getMappingGroup(db, clientModel);
-    if (!group)
+    if (!group) {
+        // Fallback: 没有 mapping group 时，直接查 provider 的 models 字段
+        const providers = db.prepare("SELECT id, models FROM providers WHERE is_active = 1").all();
+        for (const p of providers) {
+            try {
+                const models = JSON.parse(p.models);
+                if (models.includes(clientModel)) {
+                    return { backend_model: clientModel, provider_id: p.id };
+                }
+            }
+            catch { /* 忽略解析失败 */ }
+        }
         return null;
+    }
     let rule;
     try {
         rule = JSON.parse(group.rule);
@@ -23,5 +60,5 @@ export function resolveMapping(db, clientModel, context) {
     const strategy = STRATEGIES[group.strategy];
     if (!strategy)
         return null;
-    return strategy.select(rule, context) ?? null;
+    return strategy.select(rule, context, clientModel) ?? null;
 }

package/dist/proxy/model-state.d.ts

@@ -0,0 +1,28 @@
+import type Database from "better-sqlite3";
+export declare class ModelStateManager {
+    private store;
+    private db;
+    /** 单例注入 DB 实例，启动时调用一次 */
+    init(db: Database.Database): void;
+    /** 构造内存 Map 的 key：有 sessionId 时用复合键 */
+    buildKey(routerKeyId: string | null, sessionId?: string): string;
+    /**
+     * 写入模型状态。
+     * - 始终写内存
+     * - 有 sessionId 时双写 DB（事务：upsert + history）
+     * - model="default" 时删除记忆
+     */
+    set(routerKeyId: string | null, model: string, sessionId?: string, originalModel?: string, triggerType?: string): void;
+    /**
+     * 读取模型状态。
+     * - 先查内存，命中且未过期直接返回
+     * - 未命中且有 sessionId 时查 DB 并回填内存
+     */
+    get(routerKeyId: string | null, sessionId?: string): string | null;
+    /**
+     * 删除模型状态。
+     * - 同时清除内存和 DB
+     */
+    delete(routerKeyId: string, sessionId: string): void;
+}
+export declare const modelState: ModelStateManager;

package/dist/proxy/model-state.js

@@ -0,0 +1,111 @@
+import { upsertSessionState, getSessionState, deleteSessionState, insertSessionHistory, } from "../db/session-states.js";
+// 会话记忆在 24 小时后过期（滑动窗口）
+const HOUR_MS = 3600_000;
+const TTL_HOURS = 24;
+const TTL_MS = TTL_HOURS * HOUR_MS;
+export class ModelStateManager {
+    store = new Map();
+    db = null;
+    /** 单例注入 DB 实例，启动时调用一次 */
+    init(db) {
+        this.db = db;
+    }
+    /** 构造内存 Map 的 key：有 sessionId 时用复合键 */
+    buildKey(routerKeyId, sessionId) {
+        if (sessionId) {
+            return `${routerKeyId ?? "null"}:${sessionId}`;
+        }
+        return String(routerKeyId);
+    }
+    /**
+     * 写入模型状态。
+     * - 始终写内存
+     * - 有 sessionId 时双写 DB（事务：upsert + history）
+     * - model="default" 时删除记忆
+     */
+    set(routerKeyId, model, sessionId, originalModel, triggerType) {
+        const key = this.buildKey(routerKeyId, sessionId);
+        if (model === "default") {
+            this.store.delete(key);
+            if (sessionId && routerKeyId && this.db) {
+                this.db.transaction(() => {
+                    deleteSessionState(this.db, routerKeyId, sessionId);
+                    insertSessionHistory(this.db, {
+                        router_key_id: routerKeyId,
+                        session_id: sessionId,
+                        old_model: null,
+                        new_model: "default",
+                        trigger_type: triggerType ?? "command",
+                    });
+                })();
+            }
+            return;
+        }
+        this.store.set(key, { model, updatedAt: Date.now() });
+        if (sessionId && routerKeyId && this.db) {
+            this.db.transaction(() => {
+                upsertSessionState(this.db, {
+                    router_key_id: routerKeyId,
+                    session_id: sessionId,
+                    current_model: model,
+                    original_model: originalModel ?? null,
+                });
+                insertSessionHistory(this.db, {
+                    router_key_id: routerKeyId,
+                    session_id: sessionId,
+                    old_model: null,
+                    new_model: model,
+                    trigger_type: triggerType ?? "command",
+                });
+            })();
+        }
+    }
+    /**
+     * 读取模型状态。
+     * - 先查内存，命中且未过期直接返回
+     * - 未命中且有 sessionId 时查 DB 并回填内存
+     */
+    get(routerKeyId, sessionId) {
+        const key = this.buildKey(routerKeyId, sessionId);
+        const entry = this.store.get(key);
+        // 内存命中
+        if (entry) {
+            if (Date.now() - entry.updatedAt > TTL_MS) {
+                this.store.delete(key);
+                return null;
+            }
+            return entry.model;
+        }
+        // 内存未命中，尝试从 DB 回填
+        if (sessionId && routerKeyId && this.db) {
+            const row = getSessionState(this.db, routerKeyId, sessionId);
+            if (row) {
+                this.store.set(key, { model: row.current_model, updatedAt: Date.now() });
+                return row.current_model;
+            }
+        }
+        return null;
+    }
+    /**
+     * 删除模型状态。
+     * - 同时清除内存和 DB
+     */
+    delete(routerKeyId, sessionId) {
+        const key = this.buildKey(routerKeyId, sessionId);
+        this.store.delete(key);
+        if (this.db) {
+            this.db.transaction(() => {
+                deleteSessionState(this.db, routerKeyId, sessionId);
+                insertSessionHistory(this.db, {
+                    router_key_id: routerKeyId,
+                    session_id: sessionId,
+                    old_model: null,
+                    new_model: "default",
+                    trigger_type: "manual_clear",
+                });
+            })();
+        }
+    }
+}
+// singleton
+export const modelState = new ModelStateManager();

package/dist/proxy/openai.d.ts

@@ -3,7 +3,6 @@ import Database from "better-sqlite3";
 import { RetryRuleMatcher } from "./retry-rules.js";
 export interface OpenaiProxyOptions {
     db: Database.Database;
-    encryptionKey: string;
     streamTimeoutMs: number;
     retryMaxAttempts: number;
     retryBaseDelayMs: number;

package/dist/proxy/openai.js

@@ -1,5 +1,6 @@
 import fp from "fastify-plugin";
 import { getActiveProviders } from "../db/index.js";
+import { getSetting } from "../db/settings.js";
 import { decrypt } from "../utils/crypto.js";
 import { proxyGetRequest, handleProxyPost, } from "./proxy-core.js";
 const HTTP_NOT_FOUND = 404;
@@ -32,9 +33,9 @@ function sendError(reply, e) {
     return reply.status(e.statusCode).send(e.body);
 }
 const openaiProxyRaw = (app, opts, done) => {
-    const { db, encryptionKey, streamTimeoutMs, retryMaxAttempts, retryBaseDelayMs, matcher } = opts;
+    const { db, streamTimeoutMs, retryMaxAttempts, retryBaseDelayMs, matcher } = opts;
     app.post(CHAT_COMPLETIONS_PATH, async (request, reply) => {
-        const deps = { db, encryptionKey, streamTimeoutMs, retryMaxAttempts, retryBaseDelayMs, matcher };
+        const deps = { db, streamTimeoutMs, retryMaxAttempts, retryBaseDelayMs, matcher };
         return handleProxyPost(request, reply, "openai", CHAT_COMPLETIONS_PATH, openaiErrors, deps, {
             beforeSendProxy: (body, isStream) => {
                 if (isStream && !body.stream_options) {
@@ -51,7 +52,7 @@ const openaiProxyRaw = (app, opts, done) => {
                 body: { error: { message: "No active OpenAI provider configured", type: "invalid_request_error", code: "no_provider" } },
             });
         const provider = providers[0];
-        const apiKey = decrypt(provider.api_key, encryptionKey);
+        const apiKey = decrypt(provider.api_key, getSetting(db, "encryption_key"));
         const cliHdrs = request.headers;
         try {
             const result = await proxyGetRequest(provider, apiKey, cliHdrs, MODELS_PATH);

package/dist/proxy/proxy-core.d.ts

@@ -1,52 +1,9 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import Database from "better-sqlite3";
 import type { Provider } from "../db/index.js";
-import { SSEMetricsTransform } from "../metrics/sse-metrics-transform.js";
-import type { MetricsResult } from "../metrics/metrics-extractor.js";
 import type { RetryRuleMatcher } from "./retry-rules.js";
+import { type ProxyResult, type StreamProxyResult, type GetProxyResult } from "./upstream-call.js";
 export type RawHeaders = Record<string, string | string[] | undefined>;
-export interface UpstreamRequestOptions {
-    hostname: string;
-    port: number;
-    path: string;
-    method: string;
-    headers: Record<string, string>;
-}
-export interface ProxyResult {
-    statusCode: number;
-    body: string;
-    headers: Record<string, string>;
-    sentHeaders: Record<string, string>;
-    sentBody: string;
-}
-export interface StreamProxyResult {
-    statusCode: number;
-    responseBody?: string;
-    upstreamResponseHeaders?: Record<string, string>;
-    sentHeaders?: Record<string, string>;
-    /** 流结束时从 SSEMetricsTransform 采集的指标，仅当传入了 metricsTransform 时存在 */
-    metricsResult?: MetricsResult;
-}
-export interface GetProxyResult {
-    statusCode: number;
-    body: string;
-    headers: Record<string, string>;
-}
-export declare const UPSTREAM_SUCCESS = 200;
-export declare const SKIP_UPSTREAM: Set<string>;
-export declare const SKIP_DOWNSTREAM: Set<string>;
-export declare function selectHeaders(raw: RawHeaders, skip: Set<string>): Record<string, string>;
-/** 构建发往上游的请求 headers：过滤客户端 headers + 注入后端 API key */
-export declare function buildUpstreamHeaders(clientHeaders: RawHeaders, apiKey: string, payloadBytes?: number): Record<string, string>;
-/** 根据 URL scheme 选择 http 或 https 模块 */
-export declare function createUpstreamRequest(url: URL, options: UpstreamRequestOptions): import("http").ClientRequest;
-/** 从 URL + headers 构造 Node.js http.request 所需的 options */
-export declare function buildRequestOptions(url: URL, headers: Record<string, string>, method?: string): UpstreamRequestOptions;
-/** 插入成功请求日志，供 openai/anthropic 插件共享 */
-export declare function insertSuccessLog(db: Database.Database, apiType: string, logId: string, model: string, provider: Provider, isStream: boolean, startTime: number, reqBody: string, clientReq: string, upstreamReq: string, status: number, respBody: string | null, upHdrs: Record<string, string>, cliHdrs: Record<string, string>, isRetry?: boolean, originalRequestId?: string | null, routerKeyId?: string | null): void;
-export declare function proxyNonStream(backend: Provider, apiKey: string, body: Record<string, unknown>, clientHeaders: RawHeaders, upstreamPath: string): Promise<ProxyResult>;
-export declare function proxyStream(backend: Provider, apiKey: string, body: Record<string, unknown>, clientHeaders: RawHeaders, reply: FastifyReply, timeoutMs: number, upstreamPath: string, metricsTransform?: SSEMetricsTransform): Promise<StreamProxyResult>;
-export declare function proxyGetRequest(backend: Provider, apiKey: string, clientHeaders: RawHeaders, upstreamPath: string): Promise<GetProxyResult>;
 export interface ProxyErrorResponse {
     statusCode: number;
     body: unknown;
@@ -60,15 +17,20 @@ export interface ProxyErrorFormatter {
 }
 export interface ProxyHandlerDeps {
     db: Database.Database;
-    encryptionKey: string;
     streamTimeoutMs: number;
     retryMaxAttempts: number;
     retryBaseDelayMs: number;
     matcher?: RetryRuleMatcher;
 }
+export type { ProxyResult, StreamProxyResult, GetProxyResult };
+export declare const SKIP_UPSTREAM: Set<string>;
+export declare function selectHeaders(raw: RawHeaders, skip: Set<string>): Record<string, string>;
+export declare function buildUpstreamHeaders(clientHeaders: RawHeaders, apiKey: string, payloadBytes?: number): Record<string, string>;
+export declare function proxyGetRequest(backend: Provider, apiKey: string, clientHeaders: RawHeaders, upstreamPath: string): Promise<GetProxyResult>;
 /**
- * 共享 POST handler，参数化 apiType/errorFormat/upstreamPath 等差异，
- * 消除 openai.ts / anthropic.ts 中约 120 行重复代码。
+ * 共享 POST handler，参数化 apiType/errorFormat/upstreamPath 等差异。
+ * 当分组策略为 failover 时，在 while 循环中依次尝试不同 target，
+ * 直到成功（或 headers 已发送）才返回。
  */
 export declare function handleProxyPost(request: FastifyRequest, reply: FastifyReply, apiType: "openai" | "anthropic", upstreamPath: string, errors: ProxyErrorFormatter, deps: ProxyHandlerDeps, options?: {
     beforeSendProxy?: (body: Record<string, unknown>, isStream: boolean) => void;