架構

了解 go-llm-router 如何把供應商名稱轉換為統一 Agent，並將各家回應正規化。

系統概覽

graph TB
    App[呼叫端應用]
    Server[cmd/test]
    Router[core/router]
    Contract[core Agent / StreamAgent]
    Policy[共用政策 Reasoning / Mode]
    Providers[供應商適配器]
    APIs[供應商 API]
    OAuth[core/oauth]
    Keychain[系統 Keychain]

    App --> Router
    App --> Contract
    Server --> Router
    Router --> Contract
    Contract --> Policy
    Contract --> Providers
    Providers --> APIs
    OAuth --> Keychain
    OAuth --> Providers

分層

層級	套件	職責
呼叫端	應用程式碼、`cmd/test`	組裝訊息與工具；決定模型、推理強度、執行模式與同步或串流消費方式
Router	`core/router`	解析供應商名稱並建立對應的 `core.Agent`
共用核心	`core`	定義傳輸中立的型別、推理與加速層政策、HTTP client 預設值
供應商適配器	`core/<provider>`	認證、payload 轉換、endpoint 選擇與回應正規化
OAuth	`core/oauth/*`	登入、token 儲存、過期判斷與刷新

Router

router.New 取 @ 之前的字串作為供應商前綴，去掉可選的 [tag]，在工廠表中查找並建立 Agent。查無對應鍵值即回傳錯誤。方括號標籤只影響命名，不影響選擇結果。

共用政策

core 標準化呼叫參數，但刻意不介入 wire payload。Reasoning 由 ClampReasoning 夾到各模型區間；Mode 由 SupportFast 比對 provider／model 白名單，命中才由適配器加上原生欄位（Claude 的 speed、OpenAI 與 Grok 系的 service_tier）。實際服務層級一律由回應回讀，非請求值。

供應商適配器

每個適配器自行處理 system prompt 合併、訊息與工具轉換、認證、endpoint 選擇與上游回應解碼，對外只回傳 core.Output 或 core.StreamEvent。OpenAI 與 Copilot 依模型在 Chat Completions 與 Responses API 之間切換；Codex 與 Grok OAuth 在內部消化 SSE 後回傳完整結果；Claude 與 Copilot 另外對外提供 SendStream。

OAuth 生命週期

OAuth 套件把 token 以 JSON 存進系統 keychain。Codex 與 Grok 的過期判斷保留 60 秒安全緩衝，過期時以 refresh grant 換發並寫回；Copilot 走 GitHub device flow 並以 session token 刷新。

請求流程

呼叫端以 Name（例如 openai@gpt-5.4）建立 router.Config。
router.New 選出工廠並建立 Agent。
呼叫端以訊息、可選工具、Reasoning 與 Mode 呼叫 Send 或 SendStream。
適配器夾住推理強度、判斷加速層資格，組出供應商 payload 並送出。
回應轉為 core.Output（或 StreamEvent 序列），連同 HTTP status code 與 error 回傳。
用量統一為 Input、Output、CacheCreate、CacheRead；服務層級落在 Output.ServiceTier。

延伸閱讀

模組級的完整展開——含 per-module 圖、sequence 圖與 OAuth 狀態機——見儲存庫的 doc/architecture.md。

架構