Twinny 发布适配器架构：实现“一合同三适配”，让本地与云端模型无缝统一
在 AI 应用开发的复杂生态中，模型后端（Local Server vs. Hosted API）的协议差异一直是阻碍开发者体验一致性的最大痛点。Twinny 团队近日在其官方博客中深度剖析了其核心架构——适配器模式（Adapter Pattern），并展示了如何通过“一合同三适配”的设计哲学，将 19 种不同的模型后端（包括 Ollama, llama.cpp, LM Studio, OpenAI 兼容服务器及八大托管 API 等）无缝统一。
核心架构：一合同，三适配
Twinny 的核心设计理念在于解耦。在 src/extension/inference/types.ts 中确立了基本规则：上层功能（Feature）仅请求能力（Capability），而适配器负责将其转换为后端服务器所需的特定格式。这意味着，无论是本地推理还是云端调用，上层应用无需关心路由、请求体形状或响应结构。
该架构通过三个关键适配器层实现统一：
- 本地服务器适配器（Local Adapter）：负责与 Ollama、llama.cpp 等本地服务对话，处理其特有的 JSON Lines 格式。
- 托管 SDK 适配器（Hosted SDK Adapter）：驱动 OpenAI 兼容的托管 API，利用其原生 SDK 进行高效通信。
- 网关协议适配器（Gateway Adapter）：处理通过代理或网关访问的远程服务。
标准化流式接口与错误处理
Twinny 强制所有适配器遵循统一的流式接口规范。无论是 fim（填空）、chat（对话）还是 embeddings（嵌入），所有请求均返回 AsyncIterable。开发者只需使用标准的 for await 循环即可读取文本、使用量（usage）及推理模型思维链（thinking）。
此外，Twinny 建立了严格的错误分类机制。在 errors.ts 中，系统根据 HTTP 状态码和消息内容，将错误细分为 8 种类型（如 provider-unavailable, model-unavailable, timeout 等），并保留原始服务器响应以供调试。这种细粒度的错误处理确保了应用在面对不同后端故障时的鲁棒性。
适配器内部的协议翻译艺术
适配器并非简单的转发器，而是协议翻译器。在 adapters/fim-dialects.ts 中，Twinny 展示了如何根据后端类型动态调整请求格式：
- Ollama 与 Open WebUI：使用
prompt、keep_alive和options对象，并支持raw: true以避免模板重复渲染。 - llama.cpp 与 Oobabooga：直接传递
prompt和max_tokens，无需模型名称。 - Mistral 与 DeepSeek：必须在请求体中包含模型名称，并限制最多 4 个停止序列。
- LiteLLM：自动适配其预设的
/v1/chat/completions端点。
在响应解析上，Twinny 同样具备强大的兼容性。它优先查找后端原生字段（如 Ollama 的 response 或 llama.cpp 的 content），若失败则尝试通用的 choices[0].text 等路径，确保即使后端配置稍有偏差，应用仍能正常工作。
实际价值：降低集成门槛
对于开发者而言，这一架构意味着“一次编写，到处运行”。Twinny 屏蔽了底层 19 种后端的具体实现细节，让开发者可以专注于构建应用逻辑，而非纠结于如何调用 Ollama 或 OpenRouter。这种设计不仅提升了开发效率，也为未来接入新的模型后端提供了零摩擦的扩展路径。
“Nothing above this layer knows a route, a request body or a response shape, so a new backend is a new adapter and nothing else.” —— Twinny 核心设计原则
