Skip to content

provider-resolver-refactor.md

Latest commit

 

History

History
56 lines (43 loc) · 2.61 KB

provider-resolver-refactor.md

File metadata and controls

56 lines (43 loc) · 2.61 KB
Raw

Provider Resolver Refactor

Status: Complete (Phase 1–5) Scope: Provider system unification — resolve "主聊天能用、旁路功能失效" structural issue

Problem

  • ApiProvider mixes protocol/vendor/auth/model-mapping into one flat structure
  • claude-client and text-generator are two independent provider resolution chains
  • GLM/Kimi/MiniMax/Volcengine/Bailian are Anthropic-compatible but built as custom (OpenAI-compatible in text-generator)
  • Model listing relies on hardcoded base_url → model label mapping
  • Bridge/chat/onboarding/checkin/plan have divergent provider resolution
  • No contract tests

Solution

Phase 1: Core modules

  • src/lib/provider-catalog.ts — vendor presets, default model catalogs, protocol definitions
  • src/lib/provider-resolver.ts — unified provider/model resolution for all consumers

Phase 2: DB migration

  • Add protocol, headers_json, env_overrides_json, role_models_json to api_providers
  • Create provider_models table
  • Migrate existing data (provider_type → protocol, extra_env → env_overrides_json)

Phase 3: Consumer refactoring

  • claude-client.ts → use resolver's toClaudeCodeEnv()
  • text-generator.ts → use resolver's toAiSdkConfig()
  • route.ts, conversation-engine.ts, onboarding, checkin, plan → use shared resolver

Phase 4: UI update

  • ProviderManager.tsx presets → reference catalog
  • ProviderForm.tsx → protocol selector instead of provider_type
  • /api/providers/models → read from catalog + provider_models

Phase 5: Tests

  • Provider resolver contract tests
  • Entry point consistency tests
  • Preset protocol validation
  • Regression tests (env cleanup, bind semantics)

Decision Log

Date Decision Rationale
2026-03-09 Add fields to existing table, not new system Minimize migration risk, preserve existing data
2026-03-09 Protocol-based dispatch instead of brand-name Matches actual API behavior, extensible
2026-03-09 Merge custom-anthropic into anthropic-thirdparty Remove user confusion between two nearly identical presets
2026-03-09 Auth env keys protected from envOverrides deletion Legacy extra_env placeholders ({"ANTHROPIC_AUTH_TOKEN":""}) were deleting freshly-injected credentials
2026-03-09 Env var names use _MODEL suffix Claude Code SDK expects ANTHROPIC_DEFAULT_SONNET_MODEL, not ANTHROPIC_DEFAULT_SONNET

Verification

  • aiberm (no model mapping): ✅ responded "OK claude-sonnet-4-6"
  • pipellm (with sonnet/opus/haiku mapping): ✅ responded "OK claude-sonnet-4-6"
  • Unit tests: 229/229 passed