工具配置管理模块：从 API 配置到功能开关的完整设计

// API 配置的分层结构示例
interface ApiConfig {
  provider: string          // 供应商标识：openai / anthropic / azure
  baseUrl: string           // API 地址，可按地区区分
  apiKey: string            // 加密存储的凭证
  timeout: number           // 请求超时（毫秒）
  retry: {
    maxAttempts: number
    backoffMs: number
  }
  rateLimit: {
    maxRequests: number     // 每分钟最大请求数
    maxTokens: number       // 每分钟最大 Token 数
  }
}
 
// 配置层级：global < project < environment
const resolvedConfig = mergeConfig(
  globalDefaults,
  projectConfig,
  environmentOverrides
)

interface ToolConfig {
  toolId: string
  name: string
  enabled: boolean
  // 参数约束
  parameters: {
    maxInputLength: number
    allowedFormats: string[]
    timeout: number
  }
  // 权限控制
  permissions: {
    roles: string[]           // 哪些角色可以使用
    plans: string[]           // 哪些付费套餐可用
    regions: string[]         // 哪些地区开放
  }
  // 计费相关
  billing: {
    perCallCost: number       // 每次调用的成本
    monthlyQuota: number      // 每月配额
  }
}

# 配置文件示例：config/models.yaml
defaults:
  temperature: 0.7
  maxTokens: 4096
  timeout: 30000
 
providers:
  openai:
    models:
      - id: gpt-4o
        region: us-east-1
        costPer1kTokens: 0.005
      - id: gpt-4o-mini
        region: us-east-1
        costPer1kTokens: 0.0005
        fallbackFor: gpt-4o
  anthropic:
    models:
      - id: claude-sonnet-4-20250514
        region: us-east-1
        costPer1kTokens: 0.003
 
routing:
  rules:
    - match:
        region: eu
      target:
        provider: openai
        model: gpt-4o
        region: eu-west-1   # 欧洲数据不出境
    - match:
        plan: free
      target:
        provider: openai
        model: gpt-4o-mini

// 功能开关核心数据模型
interface FeatureFlag {
  flagKey: string              // 唯一标识，如 "new_editor_v2"
  name: string                 // 可读名称
  description: string          // 用途说明
  type: "release" | "experiment" | "ops" | "permission"
  
  // 开关状态
  enabled: boolean             // 全局开关
  variants: Variant[]          // 变体（用于 A/B 测试）
  
  // 生效规则
  rules: TargetingRule[]
  
  // 生命周期管理
  createdAt: string
  updatedAt: string
  owner: string                // 负责人
  expiresAt?: string           // 过期时间（防止僵尸 Flag）
  
  // 变更记录
  auditLog: AuditEntry[]
}
 
interface Variant {
  variantKey: string           // 如 "control", "treatment_a"
  weight: number               // 流量权重（0-100）
  payload: Record<string, any> // 变体携带的配置值
}
 
interface TargetingRule {
  attribute: string            // 如 "region", "plan", "userId"
  operator: "eq" | "neq" | "in" | "not_in" | "contains" | "percentage"
  values: any[]
  effect: "enable" | "disable" | "variant"
  variantKey?: string          // effect 为 "variant" 时指定变体
}

// 功能开关评估引擎（简化版）
class FeatureFlagEvaluator {
  private flags: Map<string, FeatureFlag> = new Map()
 
  // 从配置中心加载所有开关
  async loadFlags(): Promise<void> {
    const flags = await configCenter.fetchAllFlags()
    this.flags = new Map(flags.map(f => [f.flagKey, f]))
  }
 
  // 评估某个开关对特定用户的状态
  evaluate(
    flagKey: string,
    context: { userId: string; region: string; plan: string }
  ): { enabled: boolean; variant?: string } {
    const flag = this.flags.get(flagKey)
    if (!flag) return { enabled: false }
    if (!flag.enabled) return { enabled: false }
 
    // 按规则顺序匹配
    for (const rule of flag.rules) {
      const attrValue = context[rule.attribute as keyof typeof context]
      const matched = this.matchRule(attrValue, rule)
      if (matched) {
        if (rule.effect === "enable") return { enabled: true }
        if (rule.effect === "disable") return { enabled: false }
        if (rule.effect === "variant") {
          return { enabled: true, variant: rule.variantKey }
        }
      }
    }
 
    // 默认返回全局状态
    return { enabled: flag.enabled }
  }
 
  private matchRule(attrValue: any, rule: TargetingRule): boolean {
    switch (rule.operator) {
      case "eq": return attrValue === rule.values[0]
      case "in": return rule.values.includes(attrValue)
      case "percentage":
        // 基于 userId 的确定性百分比分配
        const hash = this.simpleHash(`${attrValue}:${rule.values[0]}`)
        return (hash % 100) < rule.values[0]
      default: return false
    }
  }
 
  private simpleHash(str: string): number {
    let hash = 0
    for (let i = 0; i < str.length; i++) {
      hash = (hash * 31 + str.charCodeAt(i)) | 0
    }
    return Math.abs(hash)
  }
}

// React 中使用功能开关的 Hook
function useFeatureFlag(flagKey: string): {
  enabled: boolean
  variant: string | undefined
  loading: boolean
} {
  const flags = useContext(FeatureFlagContext)
  const flag = flags[flagKey]
  return {
    enabled: flag?.enabled ?? false,
    variant: flag?.variant,
    loading: flags._loading,
  }
}
 
// 使用示例
function ExportButton() {
  const { enabled, variant } = useFeatureFlag("pdf_export_v2")
  
  if (!enabled) return null
  
  return variant === "with_watermark"
    ? <PdfExportWithWatermark />
    : <PdfExport />
}

// 配置加载器：带本地缓存兜底
class ConfigLoader {
  private cache: Record<string, any> = {}
  private cacheFile: string
 
  async load(): Promise<Record<string, any>> {
    try {
      // 尝试从配置中心加载
      const config = await this.fetchFromConfigCenter()
      this.cache = config
      // 写入本地缓存文件
      await this.writeCacheFile(config)
      return config
    } catch (error) {
      // 配置中心不可用，使用本地缓存
      console.warn("Config center unavailable, using local cache", error)
      const cached = await this.readCacheFile()
      if (cached) return cached
      // 连本地缓存都没有，使用硬编码的默认值
      return this.getDefaults()
    }
  }
 
  private async readCacheFile(): Promise<Record<string, any> | null> {
    try {
      return JSON.parse(await fs.readFile(this.cacheFile, "utf-8"))
    } catch {
      return null
    }
  }
 
  private async writeCacheFile(config: Record<string, any>): Promise<void> {
    await fs.writeFile(this.cacheFile, JSON.stringify(config))
  }
}