Refactor Provider Architecture: By Protocol Instead of By Vendor

[Zepan]

#122 (comment)

[yinwm]

Technical Architecture Analysis

As the assignee for this roadmap item, I have conducted a comprehensive technical analysis of the provider refactoring proposal.

---

Current Issues Confirmed

The current http_provider.go and CreateProvider() have serious problems:

1. Implicit routing: auth_method is abused to control protocol type (Provider/API routing is implicit and confusing (auth_method controls API type); Anthropic api_base is ignored on Messages path #206)
2. Code bloat: 200+ lines of switch-statement hell
3. Vendor hacks scattered: Kimi temperature=1, GLM max_completion_tokens hardcoded
4. Incomplete Gemini protocol: Lost thought_signature (Incompatibility with Gemini 3 Pro/Flash due to Mandatory Thought Signatures #160/Incompatibility with Gemini 3 Pro/Flash due to Mandatory Thought Signatures #161)
5. Difficult to extend: Adding new providers requires modifying core code

---

PR #213 Evaluation

@jmahotiedu's PR #213 is the right first step:

Status	Content
✅ Done	Protocol package separation (openai_compat/, anthropic/), backward compatible, CI passing
⚠️ Partial	Factory logic just moved, not simplified
❌ Not done	Explicit api_type config, independent Gemini protocol, vendor hack configuration

Recommendation: Merge as Phase 1, but needs follow-up PRs for complete refactoring.

---

Phased Implementation Plan

Phase	Content	Effort	Issues Resolved
Phase 1	Protocol package restructure (PR #213)	5 person-days	Foundation
Phase 2	Explicit api_type + config refactor	5 person-days	#206, #17, #43
Phase 3	Independent Gemini protocol	3 person-days	#160, #161, #79, #127
Phase 4	Local LLM support + cleanup	3 person-days	#109, #75

---

Related PRs Status

PR	Status	Recommendation
#213	Protocol refactor	✅ Merge as Phase 1
#307	Gemini thought_signature	✅ Merge first, integrate in Phase 3
#110	Gemini compat	✅ Can merge, integrate in Phase 3
#125	CLI providers	✅ Can merge, not affected
#87	Registry refactor	❌ Close, superseded by #213
#177	Z.AI provider	⏸️ Wait for Phase 2
#154	MiniMax provider	⏸️ Wait for Phase 2

---

Next Steps

1. Review and merge PR fix(gemini): Implement Gemini 3 thought_signature handling for stateful reasoning #307 (Gemini 3 fix - urgent)
2. Merge PR Refactor providers by protocol family (discussion #122) #213 as Phase 1
3. Start Phase 2: Implement explicit api_type configuration
4. Proceed with Phase 3-4

I will be driving this refactoring effort. Community contributors are welcome to participate.