@yzj01/llm-router 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,370 @@
+import { T as Tier, R as RawConfig, b as PhysicalModel, P as ProxyOptions, a as ProxyHandle, c as TraceMode, d as TraceLogger, C as ConfigSource, e as PublicModelConfig } from './proxy-CrRX9deF.js';
+export { D as DEFAULT_SESSION_CONFIG, f as PublicModelMetadata, g as RouteTraceLog, S as SessionConfig, h as SessionEntry, i as SessionStats, j as SessionStore, k as TierEntry, l as TraceAttempt, m as TraceReason, n as TraceSessionAction, o as TraceSummaryInput, p as TraceWriter, V as VERSION, q as buildTraceSummary, r as deriveSessionId, s as emitRouteTrace, t as getPromptPreview, u as hashRequestContent, v as normalizeTraceMode, w as resolveTraceWriter, x as startProxy } from './proxy-CrRX9deF.js';
+
+/**
+ * 路由层只关心 alias 的成本画像，因此这里的 key 是 public alias，而不是
+ * physical model ID。
+ */
+type ModelPricing = {
+    inputPrice: number;
+    outputPrice: number;
+};
+/**
+ * 把 tier 选择结果转换成统一的 RoutingDecision，并补齐成本估算字段。
+ */
+declare function selectModel(tier: Tier, confidence: number, method: "rules" | "llm", reasoning: string, tierConfigs: Record<Tier, TierConfig>, modelPricing: Map<string, ModelPricing>, estimatedInputTokens: number, maxOutputTokens: number, agenticScore?: number, score?: number): RoutingDecision;
+/**
+ * 返回某个 tier 的完整尝试链：先 primary，再按顺序追加 fallback。
+ */
+declare function getFallbackChain(tier: Tier, tierConfigs: Record<Tier, TierConfig>): string[];
+/**
+ * 按 1M token 单价估算当前 alias 的输入 / 输出成本，并和 baseline 进行对比。
+ */
+declare function calculateModelCost(model: string, modelPricing: Map<string, ModelPricing>, estimatedInputTokens: number, maxOutputTokens: number, baselineModelId?: string): {
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+};
+/**
+ * 从候选链里剔除不允许继续尝试的模型；如果剔除后为空，则保底返回原链，避免
+ * 调用方拿到“无路可走”的空数组。
+ */
+declare function filterByExcludeList(models: string[], excludeList: Set<string>): string[];
+
+type ScoringResult = {
+    score: number;
+    tier: Tier | null;
+    confidence: number;
+    signals: string[];
+    agenticScore?: number;
+    dimensions?: Array<{
+        name: string;
+        score: number;
+        signal: string | null;
+    }>;
+};
+type RoutingDecision = {
+    publicModel: string;
+    tier: Tier;
+    confidence: number;
+    method: "rules" | "llm";
+    reasoning: string;
+    score?: number;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+    agenticScore?: number;
+    tierConfigs?: Record<Tier, TierConfig>;
+    profile?: "default";
+};
+interface RouterStrategy {
+    readonly name: string;
+    route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): RoutingDecision;
+}
+type RouterOptions = {
+    strategy?: string;
+    config?: RoutingConfig;
+    modelPricing?: Map<string, ModelPricing>;
+};
+type TierConfig = {
+    primary: string;
+    fallback: string[];
+};
+type ScoringConfig = {
+    tokenCountThresholds: {
+        simple: number;
+        complex: number;
+    };
+    codeKeywords: string[];
+    reasoningKeywords: string[];
+    simpleKeywords: string[];
+    technicalKeywords: string[];
+    creativeKeywords: string[];
+    imperativeVerbs: string[];
+    constraintIndicators: string[];
+    outputFormatKeywords: string[];
+    referenceKeywords: string[];
+    negationKeywords: string[];
+    domainSpecificKeywords: string[];
+    agenticTaskKeywords: string[];
+    dimensionWeights: Record<string, number>;
+    tierBoundaries: {
+        simpleMedium: number;
+        mediumComplex: number;
+        complexReasoning: number;
+    };
+    confidenceSteepness: number;
+    confidenceThreshold: number;
+};
+type OverridesConfig = {
+    structuredOutputMinTier?: Tier;
+    ambiguousDefaultTier?: Tier;
+};
+type RoutingConfig = {
+    version: string;
+    scoring: ScoringConfig;
+    tiers?: Record<Tier, TierConfig>;
+    overrides?: OverridesConfig;
+};
+
+declare const DEFAULT_ROUTING_CONFIG: {
+    version: string;
+    scoring: {
+        tokenCountThresholds: {
+            simple: number;
+            complex: number;
+        };
+        codeKeywords: string[];
+        reasoningKeywords: string[];
+        simpleKeywords: string[];
+        technicalKeywords: string[];
+        creativeKeywords: string[];
+        imperativeVerbs: string[];
+        constraintIndicators: string[];
+        outputFormatKeywords: string[];
+        referenceKeywords: string[];
+        negationKeywords: string[];
+        domainSpecificKeywords: string[];
+        agenticTaskKeywords: string[];
+        dimensionWeights: {
+            tokenCount: number;
+            codePresence: number;
+            reasoningMarkers: number;
+            technicalTerms: number;
+            creativeMarkers: number;
+            simpleIndicators: number;
+            multiStepPatterns: number;
+            questionComplexity: number;
+            imperativeVerbs: number;
+            constraintCount: number;
+            outputFormat: number;
+            referenceComplexity: number;
+            negationComplexity: number;
+            domainSpecificity: number;
+            agenticTask: number;
+        };
+        tierBoundaries: {
+            simpleMedium: number;
+            mediumComplex: number;
+            complexReasoning: number;
+        };
+        confidenceSteepness: number;
+        confidenceThreshold: number;
+    };
+    overrides: {
+        structuredOutputMinTier: "MEDIUM";
+        ambiguousDefaultTier: "MEDIUM";
+    };
+};
+
+/**
+ * 基于规则的默认路由策略。
+ *
+ * 它只负责把 prompt 映射到 tier / alias 决策，不参与 physical model 解析，
+ * 因此可以长期保持纯函数式、可测试的语义层逻辑。
+ */
+declare class RulesStrategy implements RouterStrategy {
+    readonly name = "rules";
+    route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): RoutingDecision;
+}
+/**
+ * 从策略注册表中读取命名路由策略。
+ */
+declare function getStrategy(name: string): RouterStrategy;
+/**
+ * 允许外部测试或扩展模块注册新的路由策略实现。
+ */
+declare function registerStrategy(strategy: RouterStrategy): void;
+
+/**
+ * Router 统一入口。
+ *
+ * 当前总是走规则路由（`rules` strategy），并返回 alias / tier 级别的决策；
+ * 它不会解析 physical model，也不会直接接触 HTTP 请求。
+ */
+declare function route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): RoutingDecision;
+
+/**
+ * OpenClaw 侧约定的 provider 标识。
+ *
+ * Router 本身并不注册 provider 实现，但会持续修复
+ * `models.providers.xiaoyiprovider` 这段配置。
+ */
+declare const LLM_ROUTER_PROVIDER_ID = "xiaoyiprovider";
+declare const LLM_ROUTER_PROVIDER_NAME = "LLM Router Provider";
+declare const LLM_ROUTER_PROVIDER_DESCRIPTION = "LLM Router local routing provider for OpenAI-compatible models";
+declare const LLM_ROUTER_PROVIDER_API = "openai-completions";
+/**
+ * 写入 OpenClaw `models.providers.*.models[]` 时使用的模型元数据结构。
+ *
+ * 这里描述的是“OpenClaw 看到的模型目录项”，不等同于实际上游请求里的
+ * physical model。
+ */
+type OpenClawModelDefinition = {
+    id: string;
+    name: string;
+    api: typeof LLM_ROUTER_PROVIDER_API;
+    reasoning: boolean;
+    input: ["text"];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+};
+/**
+ * 根据运行时配置生成 OpenClaw provider 模型目录。
+ *
+ * 注意：这个函数会为所有 `publicModels` 生成完整元数据；最终是否全部暴露给
+ * OpenClaw，由调用方（当前是 `plugin.ts`）决定。这样可以把“生成目录”和
+ * “裁剪对外暴露范围”两个职责分开。
+ */
+declare function generateOpenClawModels(publicModels: RawConfig["publicModels"], physicalModels: PhysicalModel[]): OpenClawModelDefinition[];
+
+type JsonObject = Record<string, unknown>;
+type OpenClawService = {
+    id: "llm-router-proxy";
+    start: (ctx?: unknown) => Promise<void>;
+    stop: (ctx?: unknown) => Promise<void>;
+};
+type OpenClawPluginApi = {
+    config: JsonObject;
+    pluginConfig?: {
+        port?: unknown;
+        upstreamUrl?: unknown;
+        trace?: unknown;
+        config?: RawConfig;
+        configPath?: string;
+    } | Record<string, unknown>;
+    registrationMode?: string;
+    runtime?: {
+        config?: {
+            mutateConfigFile?: <T = void>(params: {
+                afterWrite: {
+                    mode: "auto";
+                } | {
+                    mode: "none";
+                    reason: string;
+                };
+                mutate: (draft: JsonObject) => T | void | Promise<T | void>;
+            }) => Promise<unknown>;
+        };
+    };
+    registerProvider?: (provider: unknown) => void;
+    registerService: (service: OpenClawService) => void;
+    logger?: {
+        debug?: (message: string) => void;
+        info?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+};
+type OpenClawPlugin = {
+    id: "llm-router";
+    name: "LLM Router";
+    description: "LLM Router local routing proxy for OpenClaw";
+    version: string;
+    register: (api: OpenClawPluginApi) => void;
+};
+type PluginRuntime = {
+    startProxy: (options: ProxyOptions) => Promise<ProxyHandle>;
+};
+/**
+ * 计算 Router 本地 provider base URL。
+ */
+declare function localProviderBaseUrl(port: number): string;
+/**
+ * 把 Router 管理的 provider 配置注入到 OpenClaw 全局配置里。
+ *
+ * 关键策略：虽然 `provider.ts` 会生成完整 alias 元数据，但真正写回 OpenClaw
+ * 时只暴露 `auto`，从而把 alias 选择权完全留在 Router 内部。
+ */
+declare function injectLlmRouterModelsConfig(config: JsonObject, providerBaseUrl: string, modelDefinitions: OpenClawModelDefinition[]): void;
+/**
+ * OpenClaw 插件主注册函数。
+ *
+ * 注册顺序很关键：
+ * 1. 先解析运行时配置；
+ * 2. 生成 provider 元数据；
+ * 3. 把 `auto` 注入到 OpenClaw；
+ * 4. 只有在运行态模式下才真正注册并启动本地 proxy service。
+ */
+declare function registerOpenClawPlugin(api: OpenClawPluginApi, runtime?: PluginRuntime): void;
+
+type RouterConfig = {
+    baseUrl: string;
+    apiKey?: string;
+    headers: Record<string, string>;
+    port: number;
+    sessionPinning: boolean;
+    traceMode: TraceMode;
+    traceLogger?: TraceLogger;
+};
+type RouterConfigInput = Partial<RouterConfig>;
+/**
+ * Pure config resolver — all values come from the caller, no process.env.
+ */
+declare function resolveConfig(input?: RouterConfigInput): RouterConfig;
+
+/**
+ * 加载并校验配置文件
+ * @param source 配置源：内联对象或文件路径
+ * @returns 校验通过的配置对象
+ * @throws {Error} 如果配置不合法（重复 ID、引用不存在、缺少 auto 等）
+ */
+declare function loadConfig(source: ConfigSource): RawConfig;
+
+/**
+ * 运行时模型注册表，提供 O(1) 模型查询 API
+ *
+ * 不变性保证：所有返回值均为内部数据的浅拷贝，外部修改不会污染注册表。
+ */
+type ModelRegistry = {
+    /**
+     * 根据 ID 获取物理模型，不存在返回 undefined。
+     * 返回的对象是副本，修改不会影响注册表内部状态。
+     */
+    get(id: string): PhysicalModel | undefined;
+    /** 检查模型 ID 是否存在 */
+    has(id: string): boolean;
+    /**
+     * 返回所有注册的物理模型。
+     * 返回的数组及其元素均为副本，修改不会影响注册表内部状态。
+     */
+    all(): readonly PhysicalModel[];
+};
+/**
+ * 从物理模型列表创建运行时注册表
+ *
+ * 注册表持有传入模型的浅拷贝，调用方后续修改原始数组或对象不会影响注册表。
+ *
+ * @param models 物理模型列表
+ * @returns 模型注册表实例
+ * @throws {Error} 如果存在重复的模型 ID
+ */
+declare function createModelRegistry(models: PhysicalModel[]): ModelRegistry;
+
+/**
+ * 将公开模型 ID 解析为物理模型 ID
+ * @param publicModelId 公开模型 ID（如 "flash", "pro"）
+ * @param publicModels 公开模型配置映射
+ * @param registry 物理模型注册表
+ * @returns 物理模型 ID
+ * @throws {Error} 如果公开模型不存在或 kind 为 "router"
+ */
+declare function resolvePublicModel(publicModelId: string, publicModels: Record<string, PublicModelConfig>, registry: ModelRegistry): string;
+/**
+ * 将公开模型 ID 解析为物理模型
+ * @param publicModelId 公开模型 ID（如 "flash", "pro"）
+ * @param publicModels 公开模型配置映射
+ * @param registry 物理模型注册表
+ * @returns 选中的物理模型
+ * @throws {Error} 如果公开模型不存在、kind 为 "router" 或候选模型不可用
+ */
+declare function resolvePublicModelCandidate(publicModelId: string, publicModels: Record<string, PublicModelConfig>, registry: ModelRegistry): PhysicalModel;
+
+declare const plugin: OpenClawPlugin;
+
+export { ConfigSource, DEFAULT_ROUTING_CONFIG, LLM_ROUTER_PROVIDER_API, LLM_ROUTER_PROVIDER_DESCRIPTION, LLM_ROUTER_PROVIDER_ID, LLM_ROUTER_PROVIDER_NAME, type ModelPricing, type ModelRegistry, type OpenClawModelDefinition, type OpenClawPlugin, type OpenClawPluginApi, type OpenClawService, PhysicalModel, type PluginRuntime, ProxyHandle, ProxyOptions, PublicModelConfig, RawConfig, type RouterConfig, type RouterConfigInput, type RouterOptions, type RouterStrategy, type RoutingConfig, type RoutingDecision, RulesStrategy, type ScoringConfig, type ScoringResult, Tier, type TierConfig, TraceLogger, TraceMode, calculateModelCost, createModelRegistry, plugin as default, filterByExcludeList, generateOpenClawModels, getFallbackChain, getStrategy, injectLlmRouterModelsConfig, loadConfig, localProviderBaseUrl, registerOpenClawPlugin, registerStrategy, resolveConfig, resolvePublicModel, resolvePublicModelCandidate, route, selectModel };