docs(llm): 新增 LLM Provider 统一接口设计文档

2026-06-15 23:07:33 +08:00
parent 829be90d19
commit 8686a2e1d6
8 changed files with 1303 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 背景与架构总览
+
+> 本文档从 `9-llm-provider-unified-interface.md` 拆分而来，包含 §1 背景与目标 + §2 架构总览。
+
+## 1. 背景与目标
+
+### 1.1 当前状态
+
+`LlmProvider` trait 的请求/响应类型直接绑定到 OpenAI Chat Completion API 格式：
+
+```rust
+pub type ChatRequest = OpenaiChatRequest;   // 类型别名
+pub type ChatResponse = struct { message: OpenaiChatMessage, ... };
+pub type Message = OpenaiChatMessage;
+```
+
+所有 "内部统一类型" 都是 OpenAI 格式的直接映射。这导致：
+
+| API 类型 | 兼容性 | 代价 |
+|----------|--------|------|
+| OpenAI Chat（DeepSeek、Qwen 等） | ✅ 原生兼容 | 零 |
+| Anthropic Messages | ❌ 语义丢失 | 需逆向映射，丢失 thinking 等特性 |
+| OpenAI Response API | ❌ 范式不兼容 | ChatResponse 无法表达多类型 output |
+| 非标自定义 API | ❌ 无扩展点 | 只能走 extra_body 逃生舱 |
+
+### 1.2 目标
+
+设计一套**真正与 Provider 无关的内部统一类型（IR）**，使得：
+
+1. 所有 Provider 对外暴露的接口完全一致（统一 trait）
+2. 每个 Provider 内部自行完成 IR ↔ 原生格式的映射
+3. 上层（LlmCycle、AgentSession）完全感知不到具体 Provider
+4. 新 Provider 只需实现一次双向映射即可接入
+5. 各 API 的独有特性（thinking、内置工具等）有表达空间
+
+### 1.3 非目标
+
+- 不追求覆盖所有 API 的每一个参数（90% 核心流程即可）
+- 不追求在不改上层代码的情况下切换 Provider（接口一致足以）
+- 不试图让 OpenAI Response API 的内置工具完全融入消息循环（通过逃生舱 + 可选能力 trait）
+
+---
+
+## 2. 架构总览
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                上　层（AgentSession / TaskAgent）              │
+│               只与 IR 类型和 LlmProvider trait 交互            │
+├──────────────────────────────────────────────────────────────┤
+│                        LlmCycle                              │
+│      循环 / 重试 / Tool 循环 / Hook / Compact / CostTracker   │
+│           内部使用 Vec<Message> + MessageRequest              │
+├──────────────────────────────────────────────────────────────┤
+│               LlmProvider trait（核心接口）                    │
+│   chat(MessageRequest) → Result<MessageResponse, LlmError>   │
+│   chat_stream(MessageRequest) → Stream<StreamEvent>          │
+│   capabilities() → ProviderCapabilities                      │
+├────────────────┬──────────────────────┬──────────────────────┤
+│ OpenaiProvider │ AnthropicProvider    │ DeepSeekProvider ... │
+│ IR ↔ OpenAI    │ IR ↔ Anthropic       │ IR ↔ OpenAI 格式     │
+│ JSON           │ JSON                 │ (兼容 Chat API)      │
+└────────────────┴──────────────────────┴──────────────────────┘
+```
+
+### 2.1 分层原则
+
+- **IR 层**：全项目唯一的内部表示，与任何具体 API 格式无关
+- **Provider 层**：每个 Provider 实现 IR ↔ 原生格式的双向映射，复杂度隔离在此层
+- **上层**：只与 IR 和 `LlmProvider` trait 交互，不感知具体 Provider