做 Code Agent 相关工作的朋友应该都有过这种体验模型底座一换整个 Agent 的上下文构建、工具调用、输出解析全都要跟着重新过一遍。有人觉得接一个新 LLM Provider 不就是改个 base_url 和 api_key 吗真上手就会发现问题全藏在那些看起来差不多的细节里。最近我在解剖 Continue 这个开源 AI Code Agent 的源码正好把从零接入一个新 Provider这条链路完整走了一遍。这篇是系列第 21 篇我打算用实战的方式把 Provider 抽象层到底该怎么设计、新 Provider 怎么接进去、哪些地方最容易翻车一次讲透。内容以 Continue 为参照系但思路适用于任何自研的 Code Agent——你只要手里有一个基于 LLM 的编码助手这篇文章就能帮你少走弯路。1. 为什么接 Provider是 Code Agent 解剖系列里绕不开的一课1.1 模型底座是 Code Agent 唯一的外脑市面上叫得上名字的 Code Agent不管 UI 长什么样、前缀是 Continue 还是 Copilot 还是 Cursor内核都一样把用户的自然语言意图、当前编辑器上下文、仓库里的相关代码片段拼装成 Prompt扔给一个 LLM拿到回复后要么直接展示要么解析成工具调用继续执行。这意味着 LLM Provider 就是 Code Agent 的外脑。换外脑不是换个脑子那么简单因为不同脑子的说话方式不一样OpenAI 系的 API 用chat/completions接口工具调用叫tools/tool_calls。Anthropic 系用messages接口工具调用叫tools/tool_use而且消息轮次结构里多了一个tool_use块的拆分逻辑。本地跑的 Ollama、LM Studio接口是 OpenAI 兼容的但模型名、参数项、是否支持流式工具调用每家又有自己的脾气。所以接入新的 LLM Provider这件事本质上是在做一层翻译把 Code Agent 内部的统一诉求翻译成某个 Provider 听得懂的方言再把 Provider 的回话翻译回 Agent 的统一格式。这层翻译做得好不好直接决定这个 Agent 能不能在不改上层逻辑的前提下快速拥抱新模型。1.2 Continue 这个开源参照系为什么值得看我选 Continue 当参照系不是因为它功能最全而是因为它把 Provider 抽象做得足够典型而且是个可以随便翻源码的开源项目。它支持几十个 Provider从 OpenAI、Anthropic、Google 到 Ollama、vLLM、各种国内厂商的兼容端点覆盖面广抽象层就必然被磨得比较薄、比较实用。更关键的是Continue 的 Provider 接入不是写死在一坨 if-else 里而是有明确的接口定义、注册机制和配置映射。你去看它的core/llm/llms/目录会发现每个 Provider 一个文件继承同一个基类重写几个关键方法就完事。这个结构本身就是一份很好的教材它告诉你哪些东西应该抽象到基类里哪些东西应该留给子类去实现。对我这种喜欢抄作业的人来说直接读一个生产级开源项目的扩展点比看十篇理论文章都管用。下面我就沿着 Continue 的设计思路把整条链路拆开讲。2. Provider 抽象层接口边界画在哪决定了你能走多远2.1 最小必要接口一个可用 Provider 最少要暴露什么接入新 Provider 之前最重要的决策是抽象层到底要抽象到什么程度。抽象太粗上层代码全是 if-else抽象太细接一个小众 Provider 要写 200 行空实现。以 Continue 的实践来看一个可用的 Provider 最少需要回答三个问题你能列出哪些模型决定用户在下拉框里能看到什么你能做非流式的补全吗决定简单问答和测试能不能跑通你能做流式补全吗决定真实编码场景里的逐字输出体验对应到代码上就是这样一个接口轮廓interface LLMProvider { id: string; listModels(): PromiseModelInfo[]; chatComplete(params: ChatParams): PromiseChatResponse; streamChat(params: ChatParams): AsyncGeneratorStreamEvent; } interface ChatParams { messages: ChatMessage[]; model: string; tools?: ToolDefinition[]; temperature?: number; maxTokens?: number; signal?: AbortSignal; } interface ChatResponse { content: string; toolCalls?: ToolCall[]; usage?: TokenUsage; } type StreamEvent | { type: text; delta: string } | { type: tool_call; delta: PartialToolCall } | { type: done; usage?: TokenUsage } | { type: error; message: string };这个设计里最重要的不是方法签名而是StreamEvent这个联合类型。它把任意 Provider 的流式输出统一成了三种事件文本增量、工具调用增量、结束。上层 UI 和 Agent 循环只需要消费这三种事件完全不关心底层是 SSE 还是 WebSocket是 OpenAI 格式还是 Anthropic 格式。接口画到这个边界后面接任何 Provider 都只是实现三个方法的事。如果你发现某个方法在某个 Provider 上天然不支持比如一个纯补全模型不支持工具调用那就在基类里提供默认抛错实现子类按需覆盖。2.2 比接口更重要的请求/响应的方言归一化接口只是外壳真正的工作量在方言归一化。举个最典型的例子OpenAI 和 Anthropic 对模型返回工具调用的表达方式完全不同。OpenAI 的响应里工具调用长这样{ choices: [{ message: { role: assistant, content: null, tool_calls: [{ id: call_123, type: function, function: { name: read_file, arguments: {\path\: \/src/main.py\} } }] } }] }Anthropic 的响应里同样的事情长这样{ content: [ { type: text, text: 我来读取文件 }, { type: tool_use, id: toolu_123, name: read_file, input: { path: /src/main.py } } ] }注意区别OpenAI 的arguments是字符串需要你 JSON.parseAnthropic 的input直接是对象。OpenAI 的content是 null文本和工具调用分开Anthropic 的content是数组文本块和工具块混在一起。如果你不做归一化上层 Agent 循环就得同时处理两套逻辑每接一个新 Provider 就多一套分支。归一化之后上层只看到统一的ToolCall { id, name, arguments }至于底层哪种格式Provider 实现类自己消化。StreamEvent的tool_call增量事件也是为这个设计的。OpenAI 流式返回tool_calls数组里的 delta 是逐步拼出来的Anthropic 流式返回content_block_delta里的input_json_delta它们拼接方式不同但归一化到PartialToolCall后上层只管累积arguments字符串最后统一解析。2.3 配置体系的设计让新 Provider 只改配置文件接口和归一化解决的是代码层的问题配置层一样有讲究。Continue 的用户配置里一个模型长这样{ models: [ { title: My Custom Model, provider: custom, model: my-model-name, apiKey: sk-xxx, baseUrl: https://api.example.com/v1, apiVersion: 2024-02-01 } ] }注意provider字段对应的是注册在代码里的 Provider idmodel字段是要发给服务端的模型名apiKey、baseUrl这些是可选参数。这种设计的好处是接新 Provider 时如果它只是某个已有协议的变体你甚至不用写新代码配一个provider: openai加上自定义baseUrl就能用。真正需要写代码的情况只有两种一种是这个 Provider 的协议跟所有现有 Provider 都不同另一种是你需要在请求里塞一些只有它才有的特殊参数。后一种情况Continue 的处理方式是在配置里允许透传自定义参数Provider 实现里读出来塞进请求体。这样既保持了配置的灵活性又不需要为了个别参数去改抽象接口。3. 实战从零接入一个新 Provider以 Continue 为例3.1 摸清仓库结构和扩展点先说清楚这里不是教你改 Continue 源码然后提 PR而是教你理解它的扩展点然后可以把它平移到你自己的 Code Agent 上。Continue 的仓库结构里核心逻辑在core/目录Provider 相关代码集中在core/llm/llms/。每个 Provider 一个文件比如OpenAI.ts、Anthropic.ts、Ollama.ts。它们的共同特征是继承一个BaseLLM类重写_streamChat或_complete这类内部方法。基类负责公共逻辑比如组装请求头、处理 AbortSignal、统计 token 用量子类只负责协议差异。接入一个新 Provider 的第一步就是在这个目录里新建一个文件然后去注册表里登记。这个登记动作看似不起眼其实是整个扩展机制的核心注册表是一个把字符串 id 映射到 Provider 构造函数的地方上层代码只跟 id 打交道。export const llmProviders: Recordstring, new () BaseLLM { openai: OpenAI, anthropic: Anthropic, ollama: Ollama, custom: CustomProvider, };加了这一行配置里写provider: custom就能被正确识别。注册机制的意义在于上层模块不需要 import 每一个 Provider只需要查这张表。这也是为什么 Continue 能保持核心逻辑和 Provider 实现解耦。3.2 实现 Provider 类从 Model 列表到 Chat Completion假设我们要接一个虚构的 Provider叫example它提供了一个 OpenAI 风格的接口但有一些私有改动。最稳妥的实现路径是先照着OpenAI.ts抄骨架再逐段替换成新服务的协议。一个最小的实现长这样import { BaseLLM } from ../base; import { ChatParams, StreamEvent, ToolCall } from ../types; interface ExampleChatResponse { choices: Array{ message?: { content?: string; tool_calls?: any[] }; delta?: { content?: string; tool_calls?: any[] }; finish_reason?: string; }; } export class ExampleProvider extends BaseLLM { async listModels(): PromiseModelInfo[] { const resp await fetch(${this.baseUrl}/models, { headers: { Authorization: Bearer ${this.apiKey} }, }); const data await resp.json(); return data.data.map((m: any) ({ name: m.id, title: m.id })); } async *streamChat(params: ChatParams): AsyncGeneratorStreamEvent { const body { model: params.model, messages: params.messages, stream: true, temperature: params.temperature, max_tokens: params.maxTokens, }; const resp await fetch(${this.baseUrl}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify(body), signal: params.signal, }); if (!resp.ok) { const text await resp.text(); throw new Error(Example API error ${resp.status}: ${text}); } const reader resp.body!.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop()!; for (const line of lines) { const trimmed line.trim(); if (!trimmed.startsWith(data:)) continue; const payload trimmed.slice(5).trim(); if (payload [DONE]) { yield { type: done }; continue; } const json: ExampleChatResponse JSON.parse(payload); const delta json.choices[0]?.delta; if (delta?.content) { yield { type: text, delta: delta.content }; } if (delta?.tool_calls) { yield { type: tool_call, delta: normalizeToolCall(delta.tool_calls[0]) }; } } } } }这段代码的核心逻辑就三步拼请求、读 SSE 流、把每一行data:载荷解析后归一化成StreamEvent。注意TextDecoder一定要开{ stream: true }否则多字节字符比如中文注释在跨 chunk 时会被截断成乱码。这个坑我在第一次写的时候踩过后面细讲。3.3 非流式路径测试和兜底都靠它流式接口是生产环境的主角但非流式接口一样不能少。原因有两个第一单元测试和集成测试用非流式接口最方便。你不需要起一个 SSE 解析器直接await provider.chatComplete(...)拿到完整响应断言内容是否符合预期。第二某些场景下流式就是不可用的。比如一些批处理任务、CI 里的静默执行、或者 Provider 端临时禁用了 stream。这时候一个能用的非流式兜底比报错强得多。实现非流式接口其实就是把stream: true改成stream: false然后从响应体里直接取choices[0].message。很多新手会忽略这个路径结果一接进去测试全挂因为测试用例走的是非流式。建议在实现 Provider 时两条路径一起实现别偷懒。4. 工具调用与结构化输出Provider 兼容性的真正分水岭4.1 各家 Function Calling 的同与不同如果说流式文本输出是 Provider 接入的及格线那工具调用就是分水岭。Code Agent 之所以叫 Agent就是因为它能调用工具读文件、跑命令、搜索代码、改代码。没有工具调用的模型充其量是个高级补全插件。各家对工具调用的实现思路其实大同小异都是让模型输出一个结构化的我想调用某个函数的声明然后由 Agent 循环去执行再把结果送回模型。但落到协议层差异就大了维度OpenAIAnthropicGoogle Gemini请求字段tools/tool_choicetools格式略有不同tools/function_declarations响应字段message.tool_callscontent[].tool_usecandidates[].content.parts[].functionCall参数格式arguments是 JSON 字符串input是 JSON 对象args是 JSON 对象多工具并行支持数组支持多个 tool_use 块支持多个 functionCall最坑的是参数格式这一行。OpenAI 把arguments设计成字符串是为了让模型在输出时不用保证 JSON 合法性只需要生成文本到了客户端再解析。Anthropic 则让模型直接输出 JSON 对象。如果你在归一化层不处理这个差异上层拿到一个字符串一个对象JSON.parse会直接炸。4.2 把工具定义转换成 Provider 方言归一化的另一面是请求方向的转换Agent 内部的工具定义要翻译成 Provider 能理解的格式。Agent 内部的工具定义通常长这样interface ToolDefinition { name: string; description: string; parameters: JSONSchema; }OpenAI 接受的就是这个格式直接透传。但Anthropic 的请求里工具描述的 prompt 越长越好参数格式对 JSON Schema 的支持也有限。Google 那边又不一样它要求parameters必须是type: object开头的 schema否则会报错。所以一个健壮的 Provider 实现应该包含一个convertTools的内部函数把统一的ToolDefinition[]转成目标 Provider 的请求结构。这个函数虽然代码不多但是最容易出 bug 的地方尤其是处理 JSON Schema 里的$defs、$ref、anyOf这些高级特性时各家支持程度天差地别。我的建议是第一版只支持 JSON Schema 的基础子集type、properties、required、enum、description、嵌套object、array够用就好。等跑通了再按需求渐进式支持高级特性。一上来就想把完整 JSON Schema 全实现只会把自己耗死在兼容性泥潭里。4.3 流式工具调用增量解析的通用方案流式工具调用是另一个折磨人的点。非流式时模型一次性把整个工具调用返回你解析一次就行。流式时工具调用的arguments是被切成一小段一小段吐出来的你需要自己拼。OpenAI 的流式增量格式是每 chunk 返回delta.tool_calls[0].function.arguments的一个片段你需要累积字符串。Anthropic 的流式增量是content_block_delta.delta.partial_json也是一段 JSON 字符串片段但它的 content block 结构意味着你要自己跟踪当前正在累积哪个 tool_use 块。这里有一个小技巧不要在每个增量到达时都尝试JSON.parse完整字符串那样解析器会疯狂报错因为中间状态本来就是非法的 JSON。正确的做法是只累积arguments字符串等流结束时收到finish_reason: tool_calls或[DONE]再统一解析。如果在中间想实时展示工具参数的进度可以用一个尽量解析失败就忽略的容错函数function tryParseJsonLoose(str: string): any { try { return JSON.parse(str); } catch { return null; } }这个函数的作用仅限于预览最终以流结束后的完整解析结果为准。这样既不会因为中间态报错又能给用户反馈进度。5. 踩坑实录认证、模型名、并发与超时的那些坑5.1 认证方式不是只有 API Key 一种绝大多数 Provider 认证都是一个 API Key 塞在Authorizationheader 里但真接起来你会发现世界远比这复杂某些企业网关要求 API Key 放在自定义 header 里比如X-API-Key。某些服务要求Authorization: Bearer token但 token 需要先从另一个接口换取而且有有效期。某些本地服务比如 Ollama 默认跑在 localhost压根不需要认证但你代码里如果硬塞一个空Authorizationheader反而可能触发 CORS 或网关拒绝。Azure OpenAI 的认证是api-keyheader 加 URL 里的api-version参数跟标准 OpenAI 完全不同。处理这些差异的正确姿势是Provider 实现类内部封装一个buildHeaders()方法把所有认证逻辑收拢到一个地方。配置层面给用户暴露apiKey、apiVersion、customHeaders这几个字段其中customHeaders是对象类型允许用户自由透传额外 header。这样你就不需要为了某个特殊网关去改代码用户配一下就完事。还有一个我反复强调的细节永远不要用console.log打印完整请求头。我在调试时不止一次看到有人把包含 API Key 的 header 打进了日志提交到仓库然后被爬虫扫到Key 直接裸奔。Provider 实现里如果要打印调试信息一定要做脱敏处理只打印 header 的 key 名不打印 value。5.2 模型名映射用户写的短名和 API 的全名模型名是 Code Agent 集成里最容易忽略、也最容易出问题的地方。用户视角的模型名是gpt-4o这种短名但某些 Provider 的 API 里你可能必须传完整的部署名或带版本号的 model id比如 Azure 的部署名是你在资源里自己起的跟 OpenAI 官方模型名没有任何对应关系。更麻烦的是有些 Provider 的模型名大小写敏感传错一个字符就 404 或 400。解决思路是在配置层加一个可选的modelAlias字段。如果用户填了就以它为准如果没填就把配置里的model原样传出。这样用户可以自己解决短名和全名的映射不需要动代码。另一个相关问题是对listModels返回结果的处理。有些 Provider 的模型列表接口一次返回几百个模型其中一半是废弃的、不能实际调用的。如果你把它们全部塞进下拉框用户体验会很差。我建议在listModels里做一次过滤只保留id包含实际可用前缀的模型或者至少按字母排序 去重。这个小优化实测能显著降低用户选错模型的比例。5.3 超时、重试与限流Provider 挂了不能拖垮整个 Agent接 Provider 最怕的不是接口报错而是接口既不报错也不返回一直挂在那里。Code Agent 是交互式工具用户等一次补全最多忍耐几十秒超过这个时间就该果断放弃给人反馈。实现上有几个通用做法fetch请求必须带AbortSignal把用户取消和超时统一挂到一个AbortController上。超时时间建议分层连接超时 10 秒首字节超时 30 秒整体空闲超时 60 秒。不要只设一个总超时否则慢启动的流式服务会被误杀。重试策略要区分错误类型。429限流和5xx服务端错误可以重试400请求格式错误、401认证失败、404模型不存在重试一万次也是白搭直接抛错。重试要带指数退避和抖动。最简单的实现是delay min(2^attempt * 1000, 8000) random(0, 500)毫秒。这些逻辑看着繁琐但属于那种一次实现所有 Provider 受益的公共能力建议放在基类里而不是每个子类写一遍。Continue 的基类就做了大量这类工作这也是为什么它的几十个 Provider 子类都很简洁。6. 验证与回归怎样才算接好了6.1 先跑通最小链路再叠加能力一个新 Provider 接入后最忌讳的就是一次性联调所有功能然后在新功能出问题时不知道是哪一环的问题。我的习惯是分四步走第一步只验证listModels。发一个请求看返回的模型列表是否符合预期。这一步能快速暴露认证、baseUrl、网络路径这些基础问题。第二步验证非流式文本补全。不传工具只发一个你好看能不能拿到完整回复。这一步能验证请求体组装、响应解析、消息格式这些核心逻辑。第三步验证流式文本补全。在终端里用脚本消费AsyncGenerator观察text增量事件是否按预期到达。这一步重点测中英文混合内容、换行符、特殊字符这些边缘 case。第四步验证工具调用。给一个简单的工具定义比如get_current_time让模型回答现在几点然后看工具调用事件是否能被正确归一化。这个场景能覆盖请求方向的工具格式转换、响应方向的 tool_call 解析、以及流式增量拼接。每一步通过后再走下一步出了问题能立刻定位到具体模块不用从头排查。6.2 用配置化测试覆盖 Provider 差异Provider 接入的回归测试说白了就是同样的输入不同的 Provider都要得到符合预期的结构化结果。但你不能在 CI 里真的调外部 API那样又慢又不稳定。我推荐两层测试策略第一层是 mock 测试。用msw或者简单的fetchmock模拟 Provider 的 HTTP 响应只测你的代码能否正确解析。把 OpenAI、Anthropic、自定义 Provider 的典型响应都 mock 一遍每个 Provider 一个 fixture 文件。这一层跑得快适合在任何一次代码变更后全量跑。第二层是冒烟测试。用真实 API Key只跑几个最小用例标记为smoke不在每次 CI 里跑而是在发版前手动触发。冒烟测试用例要写得很克制比如只发一条短消息、只调用一次工具控制成本。我还习惯在 fixture 里专门造一些恶意输入比如超长的工具参数、含 unicode 转义的内容、嵌套很深的 JSON Schema。这些边缘 case 才是 Provider 差异集中爆发的地方比正常用例值钱得多。6.3 兼容性检查清单接任何一个 Provider 前过一遍最后分享一个我手头一直维护的检查清单。每次往 Code Agent 里接新 Provider我都会逐条过一遍确认没有遗漏配置项是否完整覆盖apiKey、baseUrl、apiVersion、模型名、自定义 header。流式和非流式两条路径是否都实现测试是否都通过。SSE 解析是否处理了[DONE]、多行data:、注释行、空行、chunk 截断。多字节字符中文、日文、emoji在流式传输中是否不乱码。工具调用请求格式是否正确响应是否归一化成统一ToolCall。流式工具调用增量是否正确累积结束时能否正确解析完整 JSON。认证失败的报错是否友好能否提示用户检查 API Key。限流、超时、服务端错误是否区分处理重试策略是否生效。模型列表是否过滤、排序、去重用户选错模型时是否有明显报错。日志是否脱敏API Key 不会被打进日志文件。这个清单看着长但每一条都是用真实事故换来的教训。比如chunk 截断那条我第一次接流式接口时中文注释被切成两半解码出来一堆乱码排查了半天才发现是TextDecoder的问题。现在我把这条写进清单再也没有在这个问题上浪费过时间。接入 LLM Provider 这件事本质上是给 Code Agent 装一个可替换的发动机。发动机的品牌可以换但油路、电路、仪表盘得是统一的规格。只要抽象层设计得干净、归一化做得彻底、踩坑经验沉淀成清单你的 Agent 就能在模型快速迭代的时代始终保持想换就换的灵活性。这也是我解剖这一系列源码后最深的一点体会真正决定一个 Code Agent 能走多远的往往不是它当前用的那个模型有多强而是它的架构能不能在下一个更强的模型出现时用最小的成本接上去。