fluxcore

fluxcore 是 tokflux 项目的共享核心库，包含纯函数和数据结构。

设计原则

• 纯函数：无状态，无副作用，易于测试
• 数据结构：Provider、UsageRecord、QueryFilter 等公共定义
• 无接口：避免约束，上层自由组合

目录结构

fluxcore/
├── routing/                    # 路由选择
│   ├── provider.go             # Provider 结构体
│   ├── snapshot.go             # ProviderSnapshot
│   ├── select.go               # SelectFunc 函数类型
│   ├── select_quota.go         # SelectByQuota()
│   ├── select_price.go         # SelectByPrice()
│   ├── select_latency.go       # SelectByLatency()
│   ├── select_round.go         # SelectByRoundRobin()
│   └── select_manual.go        # SelectByManual()
│
├── adapter/                    # 格式转换
│   ├── detect.go               # DetectFormat()
│   ├── openai.go               # OpenAI ↔ Internal
│   ├── anthropic.go            # Anthropic ↔ Internal
│   └── internal.go             # InternalRequest/Response
│
├── proxy/                      # 代理转发
│   ├── proxy.go                # Proxy()
│   └── stream.go               # ProxyStream()
│
├── usage/                      # 使用统计
│   ├── estimate.go             # EstimateTokens()
│   ├── pricing.go              # CalculatePrice()
│   ├── record.go               # UsageRecord 结构体
│   ├── stats.go                # UsageStats 结构体
│   └── filter.go               # QueryFilter 结构体
│
├── config/                     # 配置数据结构
│   ├── types.go                # ProviderConfig、ServerConfig 等
│   └── defaults.go             # 默认值常量
│
├── validate/                   # 输入验证
│   └ validate.go               # ValidateModel、ValidateMessages 等
│
├── errors.go                   # ErrorCode + ErrorResponse
├── trace.go                    # GenerateTraceID()
└── README.md                   # 本文件

核心模块

routing - 路由选择

import "fluxcore/routing"

// 策略常量
routing.StrategyQuotaFirst   // "quota_first"
routing.StrategyPriceFirst   // "price_first"
routing.StrategyLatencyFirst // "latency_first"
routing.StrategyRoundRobin   // "round_robin"
routing.StrategyManual       // "manual"

// 获取策略函数
fn, ok := routing.GetStrategy("quota_first")

// Provider 结构体
type Provider struct {
    Name       string
    Format     string  // 使用 adapter.FormatOpenAI 等常量
    BaseURL    string
    APIKey     string
    Models     map[string]ModelInfo
    QuotaLimit int64
    Healthy    bool
    Latency    int
    Enabled    bool
}

// 选择函数（O(n) 算法）
provider, err := routing.SelectByQuota(snapshots)
provider, err := routing.SelectByPrice(snapshots)
provider, err := routing.SelectByLatency(snapshots)
provider, err := routing.SelectByRoundRobin(snapshots)

// RoundRobin 可创建独立实例
selector := routing.NewRoundRobinSelector()
provider, err := selector.Select(snapshots)

adapter - 格式转换

import "fluxcore/adapter"

// 格式常量
adapter.FormatOpenAI    // "openai"
adapter.FormatAnthropic // "anthropic"
adapter.FormatGemini    // "gemini"

// 路径检测
format := adapter.DetectFormat("/v1/chat/completions")

// Header 检测
format := adapter.DetectFormatFromHeaders(headers)

// 格式转换
unified, err := adapter.OpenAIToUnified(body)
unified, err := adapter.AnthropicToUnified(body)

usage - Token 估算

import "fluxcore/usage"

// 中文感知估算
// 中文: 1.5 chars/token, 英文: 4 chars/token
tokens := usage.EstimateTokens("你好世界")  // 约 3 tokens
tokens := usage.EstimateTokens("hello")    // 约 2 tokens

// 消息估算
tokens := usage.EstimateTokensFromMessages(messages)

// 最大 token 估算
maxTokens := usage.EstimateMaxTokens(messages, 1024)

// 价格计算（美元/百万 token）
price := usage.CalculatePrice(record, pricing)

proxy - 代理转发

import "fluxcore/proxy"

// 同步转发
resp, err := proxy.Proxy(ctx, client, provider, req)

// 流式转发 (SSE)
err := proxy.ProxyStream(ctx, client, provider, req, w)

validate - 输入验证

import "fluxcore/validate"

result := validate.ValidateModel("gpt-4")
result := validate.ValidateMessages(messages)
result := validate.ValidateMaxTokens(4096)
result := validate.ValidateProvider("openai")
result := validate.ValidateAPIKey("sk-xxx")

config - 配置结构

import "fluxcore/config"

// 默认值
config.DefaultStrategy    // routing.StrategyQuotaFirst
config.DefaultPort        // 8080
config.DefaultMaxTokens   // 4096

// 默认配置
serverCfg := config.DefaultServerConfig()
routerCfg := config.DefaultRouterConfig()

核心类型

ErrorCode

type ErrorCode string

const (
    ErrCodeRateLimited         ErrorCode = "RATE_LIMITED"
    ErrCodeQuotaExhausted      ErrorCode = "QUOTA_EXHAUSTED"
    ErrCodeDailyLimitExhausted ErrorCode = "DAILY_LIMIT_EXHAUSTED"
    ErrCodeModelNotAllowed     ErrorCode = "MODEL_NOT_ALLOWED"
    ErrCodeProviderNotFound    ErrorCode = "PROVIDER_NOT_FOUND"
    ErrCodeProviderUnhealthy   ErrorCode = "PROVIDER_UNHEALTHY"
    ErrCodeInvalidRequest      ErrorCode = "INVALID_REQUEST"
    ErrCodeUnauthorized        ErrorCode = "UNAUTHORIZED"
    ErrCodeNoAvailableProvider ErrorCode = "NO_AVAILABLE_PROVIDER"
)

ErrorResponse

type ErrorResponse struct {
    Code      ErrorCode
    Message   string
    TraceID   string
    Details   map[string]interface{}
}

ProviderSnapshot

type ProviderSnapshot struct {
    Provider     *Provider
    QuotaUsed    int64
    QuotaPercent float64
    Price        float64
    Latency      int
    Priority     int  // 用于 manual 策略
}

路由策略

fluxcore 提供五种路由策略：

策略	常量	函数	说明
quota_first	routing.StrategyQuotaFirst	SelectByQuota()	选择 quota 使用率最低的
price_first	routing.StrategyPriceFirst	SelectByPrice()	选择价格最低的
latency_first	routing.StrategyLatencyFirst	SelectByLatency()	选择延迟最低的
round_robin	routing.StrategyRoundRobin	SelectByRoundRobin()	轮询选择
manual	routing.StrategyManual	SelectByManual()	选择第一个

所有选择函数使用 O(n) 算法（线性扫描），而非 O(n log n) 排序。

通过 GetStrategy(name) 函数获取策略：

fn, ok := routing.GetStrategy("price_first")
if ok {
    provider, err := fn(snapshots)
}

RoundRobin 支持创建独立实例：

selector := routing.NewRoundRobinSelector()
provider, err := selector.Select(snapshots)

使用示例

路由选择

import "fluxcore/routing"

snapshots := []*routing.ProviderSnapshot{
    {Provider: p1, QuotaPercent: 30, Price: 0.03, Latency: 100},
    {Provider: p2, QuotaPercent: 80, Price: 0.01, Latency: 50},
}

provider, err := routing.SelectByPrice(snapshots)

Token 估算

import "fluxcore/usage"

tokens := usage.EstimateTokens("hello world")
// 返回约 4 tokens

价格计算

import (
    "fluxcore/usage"
    "fluxcore/routing"
)

record := &usage.UsageRecord{
    InputTokens:  1000,
    OutputTokens: 500,
}
pricing := routing.PricingInfo{Input: 30, Output: 60}
price := usage.CalculatePrice(record, pricing)
// 返回 $0.06

格式检测

import "fluxcore/adapter"

format := adapter.DetectFormat("/v1/chat/completions")
// 返回 "openai"

TraceID 生成

import "fluxcore"

traceID := fluxcore.GenerateTraceID()
// 返回 "1234567890-abcd1234"

测试覆盖率

包	覆盖率
routing	≥95%
adapter	≥80%
proxy	≥80%
usage	≥95%
config	≥95%
validate	≥95%

依赖关系

fluxcore 是纯核心库，不依赖 tokrouter 或 tokhub。

         fluxcore
            ↑
       ┌────┴────┐
       │         │
  tokrouter   tokhub