opencode LLM 包架構(gòu)解析Schema 優(yōu)先的 LLM 核心與四軸 Route 模型【免費(fèi)下載鏈接】opencodeThe open source coding agent.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/openc/opencode本文圍繞opencode-ai/llm包的架構(gòu)指南AGENTS.md展開系統(tǒng)講解這套基于 Effect 的 LLM 核心的請(qǐng)求流程、Route 四軸Protocol / Endpoint / Auth / Framing組合模型、Provider Facade 配置模式、工具調(diào)度運(yùn)行時(shí)以及協(xié)議文件編寫規(guī)范與 cassette 錄制測(cè)試體系。讀完本文后你可以理解 opencode 如何把「一套類型化請(qǐng)求/響應(yīng)/事件/工具語(yǔ)言」與「各家提供商的差異適配」徹底解耦并知道如何為該項(xiàng)目新增一條 provider 路由、編寫一個(gè)類型化工具或運(yùn)行一次錄制測(cè)試。什么是 opencode-ai/llmpackages/llm是 opencode 的 Schema 優(yōu)先 LLM 核心包一套類型化的請(qǐng)求、響應(yīng)、事件和工具語(yǔ)言提供商的怪癖quirks全部收斂在適配器里不出現(xiàn)在調(diào)用方代碼中。README 給出的最小示例即典型用法import { Effect } from effect import { LLM, LLMClient } from opencode-ai/llm import { OpenAI } from opencode-ai/llm/providers const model OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses(gpt-4o-mini) const request LLM.request({ model, system: You are concise., prompt: Say hello in one short sentence., generation: { maxTokens: 40 }, }) const program Effect.gen(function* () { const response yield* LLMClient.generate(request) console.log(response.text) })事件流是 provider 中立的——OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini、Bedrock Converse 以及任何 OpenAI 兼容部署返回的事件形狀完全一致。包入口在 src/llm.ts對(duì)外導(dǎo)出面通過 package.json 的exports字段精確劃分根導(dǎo)出、./route高級(jí) barrel、按提供商拆分的./providers/*以及按協(xié)議拆分的./protocols/*openai-chat、openai-responses、anthropic-messages、gemini、bedrock-converse、openai-compatible-chat。Effect 編碼規(guī)范該包構(gòu)建在 Effect 之上AGENTS.md 對(duì) Effect 寫法有明確約定新代碼必須遵循在包邊界上優(yōu)先使用HttpClient.HttpClient/HttpClientResponse.HttpClientResponse而不是 web 的fetch/Response流式數(shù)據(jù)一律使用Stream.Stream避免臨時(shí)性的 async generator 或手工 web reader 循環(huán)除非 Effect 的StreamAPI 確實(shí)無法建模該行為JSON 編解碼使用 Effect Schema codec如Schema.fromJsonString(...)實(shí)現(xiàn)代碼中不直接寫JSON.parse/JSON.stringify在Effect.gen中直接 yield 可 yield 的錯(cuò)誤return yield* new MyError(...)而不是Effect.fail(new MyError(...))成功值有意為空時(shí)使用Effect.void而非Effect.succeed(undefined)。從源碼結(jié)構(gòu)看這些約定在 src/route/client.ts 中得到了貫徹compile、prepare、generate等入口均使用Effect.fn(LLM.xxx)具名函數(shù)聲明便于追蹤與測(cè)試斷言。命名約定per-type 構(gòu)造器與 LLM 命名空間同一事物的兩種構(gòu)造方式就多了一種。因此約定類型專屬構(gòu)造器掛在類型本身上而不是做成頂層再導(dǎo)出。直接使用Message.system(...) Message.user(...) Message.assistant(...) Message.tool(...) Model.make(...) ToolDefinition.make(...) ToolCallPart.make(...) ToolResultPart.make(...) ToolChoice.make(...) ToolChoice.named(...) SystemPart.make(...) GenerationOptions.make(...)頂層LLM命名空間保留給「請(qǐng)求形態(tài)的調(diào)用 API」LLM.request、LLM.generate、LLM.stream、LLM.updateRequest、LLM.generateObject。在 src/llm.ts 中可以看到這一約定的落地request(input)是一個(gè)薄構(gòu)造器把易用型輸入system: string、prompt: string歸一化進(jìn)規(guī)范 Schema 類——SystemPart.content(requestSystem)、messages.map(Message.make)、ToolDefinition.make、GenerationOptions.make等最終new LLMRequest({...})返回同一個(gè) Schema 類實(shí)例。updateRequest(input, patch)則是「先展開回RequestInput再合并 patch」的不可變更新。此外LLM.generateObject的實(shí)現(xiàn)也印證了「不制造第二套模型」的原則它內(nèi)部強(qiáng)制構(gòu)造一個(gè)名為generate_object的合成工具并配合ToolChoice.named在所有協(xié)議上走完全相同的路徑——刻意回避各家 provider 原生的 JSON mode以保證行為一致。請(qǐng)求流程從 LLMRequest 到 LLMResponse預(yù)期調(diào)用方式是先構(gòu)造、再執(zhí)行const request LLM.request({ model: OpenAI.configure({ apiKey }).responses(gpt-4o-mini), system: You are concise., prompt: Say hello., }) const response yield* LLMClient.generate(request)LLM.request(...)構(gòu)造一個(gè)LLMRequest。LLMClient.generate(...)隨后讀取request.model.route上攜帶的可執(zhí)行路由構(gòu)建 provider 原生 body向路由的 transport 索取一個(gè)真實(shí)的HttpClientRequest.HttpClientRequest經(jīng)由RequestExecutor.Service發(fā)出把 provider 流解析為公共LLMEvent最終返回LLMResponse。三個(gè)執(zhí)行入口各有分工LLMClient.stream(request)—— 調(diào)用方想要增量LLMEvent流LLMClient.generate(request)—— 把同樣的事件收集成LLMResponseLLMClient.prepareBody(request)—— 把請(qǐng)求編譯過整條路由管線但不真正發(fā)送。可選的Body類型參數(shù)把.body收窄為路由原生形狀例如prepareOpenAIChatBody(...)返回PreparedRequestOfOpenAIChatBody。運(yùn)行時(shí) body 完全相同泛型只是調(diào)用方做出的類型級(jí)斷言。client.ts 中的compile注釋精確描述了這條管線的重要邊界// compile is the important boundary: it turns a common LLMRequest into a // validated provider body plus transport-private prepared data, but does not // execute transport. const compile Effect.fn(LLM.compile)(function* (request: LLMRequest) { const resolved applyCachePolicy(resolveRequestOptions(request)) const route resolved.model.route const body yield* route.body .from(resolved) .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(route.body.schema)))) const prepared yield* route.prepareTransport(body, resolved) ... })注意其中applyCachePolicy(resolveRequestOptions(request))一步請(qǐng)求級(jí)generation/providerOptions/http會(huì)先與模型默認(rèn)值、路由默認(rèn)值逐軸合并mergeGenerationOptions、mergeProviderOptions、mergeHttpOptions緩存策略在編譯期就落進(jìn) body——這與 README 中「prompt 緩存默認(rèn)開啟、cache: auto是缺省值」的描述一致。過濾或收窄事件流使用LLMEvent.is.*駝峰守衛(wèi)例如events.filter(LLMEvent.is.toolCall)。kebab-case 的LLMEvent.guards[tool-call]形式仍然可用但新代碼應(yīng)優(yōu)先is.*。Route 四軸模型一條路由 Protocol Endpoint Auth Framing這是整個(gè)包最核心的架構(gòu)決策。路由Route是四個(gè)正交部件的已注冊(cè)、可執(zhí)行組合Protocolsrc/route/protocol.ts——語(yǔ)義 API 契約。擁有請(qǐng)求 body 構(gòu)造body.from、body schemabody.schema、流事件 schemastream.event以及事件到LLMEvent的狀態(tài)機(jī)stream.step。Route.make(...)會(huì)用body.schema校驗(yàn)并 JSON 編碼 body用stream.event解碼幀。實(shí)例OpenAIChat.protocol、OpenAIResponses.protocol、AnthropicMessages.protocol、Gemini.protocol、BedrockConverse.protocol。Endpointsrc/route/endpoint.ts——URL 構(gòu)造。host、path、route query 都掛在 endpoint 上。Endpoint.path(/chat/completions, { baseURL })是常見形態(tài)當(dāng)路徑內(nèi)嵌模型 id 或 body 字段時(shí)如Endpoint.path(({ body }) /model/${body.modelId}/converse-stream)傳入一個(gè)函數(shù)。Authsrc/route/auth.ts——每請(qǐng)求傳輸鑒權(quán)。Provider facade 在選模型之前把憑證配置到路由上通常通過Auth.bearer(apiKey)或Auth.header(name, apiKey)。需要每請(qǐng)求簽名的路由Bedrock SigV4、未來的 Vertex IAM、Azure AAD把Auth實(shí)現(xiàn)為對(duì) body 簽名并把簽名頭合并進(jìn)結(jié)果簽名的函數(shù)。Framingsrc/route/framing.ts——字節(jié) → 幀。SSEFraming.sse是共享實(shí)現(xiàn)Bedrock 把 AWS event-stream 的幀保持為類型化的Framingobject值與它的協(xié)議并存。通過Route.make(...)組合它們export const route Route.make({ id: openai-chat, provider: openai, protocol: OpenAIChat.protocol, endpoint: Endpoint.path(/chat/completions, { baseURL: https://api.openai.com/v1, }), auth: Auth.bearer(), framing: Framing.sse, })路由上的defaults是「請(qǐng)求塑形默認(rèn)值」headers、limits、generation、providerOptions、http。Endpoint 的 host/query 屬于路由 endpoint。選中的Model值只攜帶模型 id、provider id 和已配置的路由值模型能力/目錄元數(shù)據(jù)活在這個(gè)包之外協(xié)議兼容性由請(qǐng)求降級(jí)lowering階段和類型化LLMError強(qiáng)制。從源碼看Route接口client.ts 的RouteBody, Prepared還暴露with(patch)不可變修補(bǔ)路由facade 覆蓋 auth/endpoint 的入口、model(input)由路由構(gòu)造帶路由值的Model以及prepareTransport/streamPrepared傳輸私有準(zhǔn)備與流讀取。makeRouteModel中有兩個(gè)硬性前置條件路由必須能解析出 provider且 endpoint 必須已有baseURL——Route.model(...)在 baseURL 缺失時(shí)會(huì)直接拋出要求「先配置路由」。這正是「無規(guī)范 URL 的路由必須先配置后執(zhí)行」這條約定在代碼中的落點(diǎn)。四軸分解的收益DeepSeek、TogetherAI、Cerebras、Baseten、Fireworks、DeepInfra 全部原樣復(fù)用OpenAIChat.protocol——每個(gè) provider 部署只是一段 5~15 行的Route.make(...)調(diào)用而不是 300~400 行的路由克隆某個(gè)協(xié)議里修一個(gè) bug一次提交就能傳導(dǎo)到該協(xié)議的所有消費(fèi)者。非 HTTP 傳輸?shù)慕涌p是Transport當(dāng)某 provider 提供非 HTTP 傳輸OpenAI 的 WebSocket Responses 后端、假想的雙向流式 API時(shí)WebSocketTransport.jsonTransport.with(...)構(gòu)造一個(gè) IO 模板其prepare在編譯期接收路由 endpoint/auth構(gòu)建 WebSocket URL 與消息其frames從 socket 產(chǎn)出解碼后的文本。同樣的協(xié)議與 endpoint 來源不同的 transport。LLMClient.layerclient.ts 末尾同時(shí)裝配RequestExecutor.Service與可選的WebSocketExecutor.Service兩種運(yùn)行時(shí)在此匯合。URL 構(gòu)造規(guī)則Endpoint擁有{ baseURL, path, query }。每個(gè)協(xié)議路由在 provider 有規(guī)范地址時(shí)會(huì)帶一個(gè)如https://api.openai.com/v1provider 助手在選模型之前通過配置路由來覆蓋 endpoint 字段。沒有規(guī)范 URL 的路由OpenAI 兼容 Chat、GitHub Copilot執(zhí)行前必須完成配置。對(duì) URL 由類型化輸入派生的 providerAzure 資源名、Bedrock regionprovider 助手在調(diào)用.model(...)之前配置路由 endpoint。當(dāng)輸入接受兩條二選一的派生路徑時(shí)AzureresourceName或baseURL使用 route/auth-options.ts 中的AtLeastOneT。Provider Facade先配置、后選模型面向 provider 的 API 是「路由值之上的已配置 facade」endpoint/auth/資源/API 版本的設(shè)置在選模型之前完成模型選擇器只接受一個(gè)模型 id 或部署 idconst openai OpenAI.configure({ apiKey, baseURL }) const model openai.responses(gpt-4o-mini) const azure Azure.configure({ resourceName, apiKey, apiVersion: v1 }) const deployment azure.responses(my-deployment) const gateway CloudflareAIGateway.configure({ accountId, gatewayId, gatewayApiKey, apiKey }) const proxied gateway.model(openai/gpt-4o-mini)Facade 應(yīng)保持小而顯式直接構(gòu)造 id 時(shí)使用 branded 的ProviderID.make(...)和ModelID.make(...)用model表示默認(rèn) API 路徑用命名方法表示 provider 原生替代路徑OpenAI 的responses、responsesWebSocket、chatprovider 專屬設(shè)置放.configure(...)不要新增model(id, overrides)這種重復(fù)構(gòu)造路徑僅當(dāng)高級(jí)內(nèi)部接線確有需要時(shí)才單獨(dú)導(dǎo)出底層routes數(shù)組apiKey作為 provider 專屬糖auth作為顯式覆蓋在 provider option 類型里用ProviderAuthOption保持二者互斥用AuthOptions.bearer(options, PROVIDER_API_KEY)把a(bǔ)piKey解析為Auth——它尊重顯式auth覆蓋并回退到Auth.config(envVar)使缺失的 key 表現(xiàn)為類型化Authentication錯(cuò)誤而不是運(yùn)行時(shí)崩潰對(duì)需要不同必填設(shè)置的同一廠商產(chǎn)品使用獨(dú)立的頂層 facade如CloudflareAIGateway與CloudflareWorkersAI。Provider.make(...)對(duì)簡(jiǎn)單靜態(tài) provider 定義仍然可用但新的內(nèi)置 provider 應(yīng)優(yōu)先使用普通已配置 facade除非某個(gè) helper 在不增加運(yùn)行時(shí)行為的前提下消除了真實(shí)重復(fù)。auth.ts 中的MissingCredentialError/AuthenticationReason映射toLLMError正是「缺失憑證 → 類型化錯(cuò)誤」這一承諾的實(shí)現(xiàn)細(xì)節(jié)。目錄布局與依賴方向packages/llm/src/ schema/ 規(guī)范 Schema 模型按關(guān)注點(diǎn)拆分 ids.ts branded IDs、字面量類型、ProviderMetadata options.ts Generation/Provider/Http options、Limits、Model、cache policy messages.ts content parts、Message、ToolDefinition、LLMRequest events.ts Usage、各事件、LLMEvent、PreparedRequest、LLMResponse errors.ts 錯(cuò)誤原因、LLMError、ToolFailure index.ts barrel llm.ts 請(qǐng)求構(gòu)造器與便捷 helper route/ index.ts opencode-ai/llm/route 高級(jí) barrel client.ts Route.make LLMClient.prepare/stream/generate executor.ts RequestExecutor service transport 錯(cuò)誤映射 protocol.ts Protocol 類型 Protocol.make endpoint.ts Endpoint 類型 Endpoint.path auth.ts Auth 類型 Auth.bearer / Auth.apiKeyHeader / Auth.passthrough auth-options.ts ProviderAuthOption 形狀、AuthOptions.bearer、AtLeastOne helper framing.ts Framing 類型 Framing.sse transport/ transport 實(shí)現(xiàn) index.ts Transport 類型 HttpTransport / WebSocketTransport 命名空間 http.ts HttpTransport.httpJson — POST framing websocket.ts WebSocketTransport.json WebSocketExecutor service protocols/ shared.ts 協(xié)議實(shí)現(xiàn)內(nèi)使用的 ProviderShared 工具集 openai-chat.ts protocol route組合 OpenAIChat.protocol openai-responses.ts anthropic-messages.ts gemini.ts bedrock-converse.ts bedrock-event-stream.ts AWS event-stream 二進(jìn)制幀的 framing openai-compatible-chat.ts 復(fù)用 OpenAIChat.protocol、無規(guī)范 URL 的 route utils/ 每協(xié)議 helperauth、cache、media、tool-stream 等 providers/ openai-compatible.ts 通用兼容 helper 家族模型 helper openai-compatible-profile.ts 家族默認(rèn)值deepseek、togetherai 等 azure.ts / amazon-bedrock.ts / cloudflare.ts / github-copilot.ts / google.ts / xai.ts / openai.ts / anthropic.ts / openrouter.ts tool.ts 類型化 tool() helper tool-runtime.ts 窄化的單調(diào)用類型化工具調(diào)度器依賴箭頭向下providers/*.ts導(dǎo)入?yún)f(xié)議路由與 auth-option 工具協(xié)議模塊導(dǎo)入endpoint、auth、framing與 transport 部件。協(xié)議不導(dǎo)入 provider facade更底層的模塊對(duì) provider 目錄元數(shù)據(jù)一無所知。ProviderShared協(xié)議實(shí)現(xiàn)的公共工具箱protocols/shared.ts 導(dǎo)出一個(gè)小工具集讓協(xié)議實(shí)現(xiàn)聚焦于 provider 原生形狀joinText(parts)—— 用換行連接TextPart數(shù)組或任何帶.text的對(duì)象。協(xié)議把文本內(nèi)容壓平為單一字符串填 provider 字段時(shí)都用它parseToolInput(route, name, raw)—— 用規(guī)范錯(cuò)誤消息 Invalid JSON input forroutetool callname 對(duì)工具調(diào)用參數(shù)串做 Schema 解碼空輸入按{}處理parseJson(route, raw, message)—— 非工具 body 的通用 JSON-via-Schema 解碼eventError(route, message, ...)—— 流式解碼失敗時(shí)構(gòu)造類型化InvalidProviderOutputvalidateWith(decoder)—— 把 Schema 解碼錯(cuò)誤映射為InvalidRequest。Route.make(...)用它做 body 校驗(yàn)低層路由可復(fù)用matchToolChoice(provider, choice, branches)—— 對(duì)LLMRequest[toolChoice]做 provider 專屬降級(jí)分支。準(zhǔn)則如果你發(fā)現(xiàn)自己在兩個(gè)協(xié)議之間復(fù)制同一段 3~5 行的片段把它提升到ProviderShared與上述 helper 并排放置而不是重復(fù)實(shí)現(xiàn)。時(shí)間序列 System 更新LLMRequest.system是初始的特權(quán)提示詞作用于整段對(duì)話之前。而Message.system(...)是另一回事它是LLMRequest.messages中一個(gè)獨(dú)立的、provider 中立的時(shí)間序列操作者更新只從其所在位置起向后生效且只接受文本內(nèi)容。原生時(shí)間序列 system 消息是 route/model 相關(guān)的Anthropic Messages 對(duì) Claude Opus 4.8claude-opus-4-8做原生降級(jí)。其他路由與模型刻意把更新就地降級(jí)為普通 user 兼容文本使用穩(wěn)定的轉(zhuǎn)義表示system-update ... /system-update這條 wrapped-user 回退在降低權(quán)限外觀的同時(shí)保持順序。絕不要把裸的時(shí)間序列role: system消息穿過可能拒絕它的路由也不要把檢索到的原始文檔、工具輸出或 web 內(nèi)容塞進(jìn)特權(quán)時(shí)間序列 system 更新——不可信內(nèi)容留在普通 user/tool 通道。工具循環(huán)與類型化工具調(diào)度工具循環(huán)用公共消息和事件表示const call ToolCallPart.make({ id: call_1, name: lookup, input: { query: weather } }) const result Message.tool({ id: call_1, name: lookup, result: { forecast: sunny } }) const followUp LLM.request({ model, messages: [Message.user(Weather?), Message.assistant([call]), result], })路由把這些降級(jí)為 provider 原生的 assistant 工具調(diào)用消息與工具結(jié)果消息。流式 provider 應(yīng)在參數(shù)到達(dá)期間發(fā)出tool-input-delta事件隨后發(fā)出帶解析后 input 的最終tool-call事件。ToolRuntime.dispatch只跑一個(gè) provider turnLLM.stream(request)與LLM.generate(request)各執(zhí)行恰好一個(gè)provider turn。把工具 schema 通過Tool.toDefinitions(tools)加進(jìn)request.tools當(dāng)調(diào)用方想要包提供的類型化單調(diào)用執(zhí)行行為時(shí)把每個(gè)規(guī)范的本地tool-call事件傳給ToolRuntime.dispatch(tools, call)const get_weather tool({ description: Get current weather for a city, parameters: Schema.Struct({ city: Schema.String }), success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }), execute: ({ city }) Effect.gen(function* () { // city: string — 由 parameters Schema 推導(dǎo)類型 const data yield* WeatherApi.fetch(city) return { temperature: data.temp, condition: data.cond } // 返回類型相對(duì) success Schema 被檢查 }), }) const tools { get_weather, get_time, ... } const events yield* LLM.stream( LLM.updateRequest(request, { tools: Tool.toDefinitions(tools) }), ).pipe(Stream.runCollect) const call Array.from(events).find(LLMEvent.is.toolCall) if (call !call.providerExecuted) { const dispatched yield* ToolRuntime.dispatch(tools, call) // 持久化 call dispatched.result然后顯式構(gòu)造下一個(gè)請(qǐng)求。 }tool-runtime.ts 中的調(diào)度器職責(zé)邊界非常窄dispatch的實(shí)現(xiàn)可以逐行核對(duì)對(duì)tool-call按名字查工具用parametersSchema 解碼 input分派到類型化execute用successSchema 編碼結(jié)果返回規(guī)范的tool-result事件不流式讀 provider、不構(gòu)造 Session 事件、不調(diào)度 fiber、不追加歷史、不數(shù)步數(shù)、不繼續(xù)模型回合持久化與繼續(xù)continuation留給外層產(chǎn)品流程。handler 依賴services、permissions、plugin hooks、abort 處理由消費(fèi)方在工具構(gòu)造時(shí)閉包捕獲。建議在Effect.gen內(nèi)一次性構(gòu)建 tools 記錄并在多次 dispatch 間復(fù)用。錯(cuò)誤必須表達(dá)為ToolFailure。運(yùn)行時(shí)捕獲它并發(fā)出tool-error事件隨后是一條type: error的tool-result模型可以在下一步自我糾正。任何非ToolFailure的東西都被視為缺陷defect使整個(gè)流失敗。源碼中三條可恢復(fù)錯(cuò)誤路徑都會(huì)產(chǎn)出tool-error事件模型調(diào)用了未知工具名Unknown tool: ...input 未通過parametersSchemaInvalid tool input: ...handler 返回了ToolFailure。此外 tool-runtime.ts 還處理了execute缺失與 success schema 編碼失敗Tool returned an invalid value for its success schema——前者產(chǎn)生錯(cuò)誤結(jié)果后者同樣折疊為ToolFailure。Provider 定義/托管工具直通Anthropic 的web_search/code_execution/web_fetchOpenAI Responses 的web_search_call/file_search_call/code_interpreter_call/mcp_call/local_shell_call/image_generation_call/computer_use_call在運(yùn)行時(shí)原樣穿過路由把模型的調(diào)用作為providerExecuted: true的tool-call事件呈現(xiàn)把 provider 結(jié)果作為匹配的providerExecuted: truetool-result事件呈現(xiàn)調(diào)用方在tool-call上檢測(cè)providerExecuted并跳過本地分派——不調(diào) handler也不為「未知工具」拋tool-errorprovider 已經(jīng)執(zhí)行過了繼續(xù)對(duì)話的調(diào)用方在協(xié)議要求時(shí)應(yīng)在顯式歷史中保留兩個(gè)事件Anthropic 把它們編碼回server_tool_useweb_search_tool_result或code_execution_tool_result/web_fetch_tool_result塊OpenAI Responses 調(diào)用方通常使用previous_response_id而不是重發(fā) hosted-tool 條目。把 provider 定義工具加進(jìn)request.tools不需要運(yùn)行時(shí)條目。匹配的路由必須知道如何把工具定義降級(jí)為 provider 原生形狀當(dāng)前 Anthropic 接受web_search/code_execution/web_fetchOpenAI Responses 接受上述托管工具名。協(xié)議文件風(fēng)格讓文件互相「長(zhǎng)得像」協(xié)議文件應(yīng)當(dāng)彼此自相似。provider 怪癖應(yīng)藏在具名 helper 后面使得評(píng)審一個(gè)新路由時(shí)可以跨文件比對(duì)相同章節(jié)。章節(jié)順序每個(gè)協(xié)議模塊使用這個(gè)順序公共模型輸入請(qǐng)求 body schema流事件 schema解析器狀態(tài)請(qǐng)求 body 構(gòu)造fromRequest流解析step與逐事件 handlerProtocol 與 route協(xié)議路由導(dǎo)出規(guī)則協(xié)議文件聚焦于協(xié)議本身。provider 專屬投影、簽名、媒體歸一化或其他臃腫轉(zhuǎn)換移入src/protocols/utils/*請(qǐng)求 body 構(gòu)造入口用Effect.fn(Provider.fromRequest)yield effect 的事件 handler 用Effect.fn(...)純同步 handler 保持為普通函數(shù)、返回StepResult由調(diào)度器經(jīng)Effect.succeed(...)提升解析器狀態(tài)擁有終止信息狀態(tài)機(jī)記錄 finish reason、usage 與掛起工具調(diào)用每個(gè)完成的響應(yīng)恰好發(fā)出一個(gè)終止finish事件或provider-error。若 provider 把 reason 和 usage 拆在不同事件里在 flush 前于解析器狀態(tài)中合并對(duì)完成的響應(yīng)恰好發(fā)一個(gè)終止finish事件通常在匹配的step-finish之后。provider 有完成哨兵時(shí)用stream.terminal停止讀取當(dāng)最終事件必須在幀流結(jié)束后 flush 時(shí)用stream.onHalt。對(duì)應(yīng)地client.ts 中streamPrepared的實(shí)現(xiàn)正是Stream.mapAccumEffect(() protocol.stream.initial(request), protocol.stream.step, ...)并在有terminal時(shí)套Stream.takeUntil重復(fù)的協(xié)議策略文本拼接、usage 匯總、JSON 解析、工具調(diào)用累積使用共享 helper。ToolStreamprotocols/utils/tool-stream.ts統(tǒng)一累積流式工具調(diào)用參數(shù)有意的 provider 差異要在 helper 名或注釋里顯式表達(dá)。如果兩個(gè)協(xié)議文件視覺上有差異原因應(yīng)當(dāng)從命名上就能看明白優(yōu)先用從一個(gè)小頂層stepswitch 分派出來的逐事件 handleronMessageStart、onContentBlockDelta等而不是長(zhǎng) if 鏈。分派器讓事件面一目了然測(cè)試與協(xié)議保持同一概念順序基礎(chǔ) prepare、工具 prepare、不支持的降級(jí)、文本/usage 解析、工具流、finish reasons、provider 錯(cuò)誤。評(píng)審清單能否與openai-chat.ts并排快速掃讀而不必翻找對(duì)應(yīng)章節(jié)provider 怪癖是否被命名、隔離并有聚焦測(cè)試覆蓋請(qǐng)求 body 構(gòu)造是否在協(xié)議邊界校驗(yàn)不支持的公共內(nèi)容流解析是否發(fā)出穩(wěn)定的公共事件而不把 provider 事件順序泄漏給調(diào)用方toolChoice: none的行為讀起來是否「有意為之」測(cè)試體系Effect 層測(cè)試與 cassette 錄制單元測(cè)試層面需要 Effect layer 的測(cè)試統(tǒng)一使用 test/lib/effect.ts 中的testEffect(...)provider 測(cè)試保持 fixture-first真實(shí)的 provider 調(diào)用必須留在RECORDtrue與必需 API key 檢查之后。錄制測(cè)試使用每場(chǎng)景一個(gè) cassette 文件。cassette 保存一個(gè)有序{ request, response }交互數(shù)組因此多步流程工具循環(huán)、重試、輪詢都錄制進(jìn)同一個(gè)文件。用recordedTests({ prefix, requires })讓 helper 從測(cè)試名派生 cassette 名const recorded recordedTests({ prefix: openai-chat, requires: [OPENAI_API_KEY] }) recorded.effect(streams text, () Effect.gen(function* () { // 測(cè)試主體 }), )replay 是默認(rèn)模式RECORDtrue錄制新 cassette 并要求所列環(huán)境變量。cassette 以 pretty-printed JSON 寫出多交互 diff 可評(píng)審。給recordedTests(...)/recorded.effect.with(...)傳provider、protocol與可選tags讓 cassette 攜帶可搜索元數(shù)據(jù)。錄制過濾器用于不重寫整個(gè)文件就 replay 或錄制窄子集RECORDED_PROVIDERopenai—— 匹配打了provider:openai標(biāo)簽的測(cè)試支持逗號(hào)分隔多值RECORDED_PREFIXopenai-chat—— 按recordedTests({ prefix })匹配 cassette 組支持逗號(hào)分隔RECORDED_TAGStool—— 要求所列標(biāo)簽全部存在如RECORDED_TAGSprovider:togetherai,toolRECORDed_TESTstreams text—— 按測(cè)試名、kebab-case 測(cè)試 id 或 cassette 路徑匹配即RECORDED_TESTstreams text。過濾器在 replay 與 record 模式下都生效配合RECORDtrue即可只刷新一個(gè) provider 或一個(gè)場(chǎng)景。二進(jìn)制響應(yīng)體大多數(shù) provider 流式返回文本SSE、JSON。錄制器把已知的文本型 media typetext/*、JSON/XML 結(jié)構(gòu)化類型、JavaScript、表單、YAML、SVG當(dāng)文本處理其余響應(yīng)以bodyEncoding: base64存儲(chǔ)為 base64——這讓 AWS event-stream 幀等二進(jìn)制格式免于有損的 UTF-8 往返。匹配策略replay 通過內(nèi)部游標(biāo)按錄制順序遍歷 cassette——第 N 個(gè)運(yùn)行時(shí)請(qǐng)求由第 N 個(gè)錄制的交互提供并逐一校驗(yàn) method、URL、白名單 header 與規(guī)范化 JSON body。這統(tǒng)一地支持工具循環(huán)每一輪請(qǐng)求因歷史增長(zhǎng)而不同與重試/輪詢場(chǎng)景逐字節(jié)相同請(qǐng)求、不同響應(yīng)。如果測(cè)試重排了請(qǐng)求順序需要重新錄制 cassette。test/lib/http.ts 中的scriptedResponses是不需要真實(shí) provider 的確定性對(duì)等物按順序腳本化響應(yīng) body不從磁盤讀取。紀(jì)律新增一個(gè) cassette 時(shí)不要整體重錄整個(gè)測(cè)試文件。RECORDtrue會(huì)重寫每個(gè)運(yùn)行到的錄制用例而 provider 流里包含易變 id、時(shí)間戳、指紋與混淆字段。應(yīng)刪除那一個(gè)打算刷新的 cassette或只運(yùn)行注冊(cè)目標(biāo)場(chǎng)景的聚焦測(cè)試模式除非請(qǐng)求形狀或期望行為變了保持既有穩(wěn)定 cassette 不變。倉(cāng)庫(kù)內(nèi)集成點(diǎn)與邊界該包刻意保持獨(dú)立于 session 關(guān)注點(diǎn)。session 鑒權(quán)、權(quán)限、插件、遙測(cè)頭與運(yùn)行時(shí)選擇都屬于 opencode 側(cè)。主要集成點(diǎn)packages/opencode/src/session/llm.ts —— session 擁有的編排層決定某次請(qǐng)求走 AI SDK 還是本包的原生 route runtimenative-request.ts —— 把 opencode 的 session/AI SDK 形狀數(shù)據(jù)降級(jí)為本包LLMRequest模型的適配器native-runtime.ts —— 調(diào)用裸LLMClient.stream(request)、通過本包的類型化分派器橋接 opencode 工具調(diào)用一個(gè) provider turn 的執(zhí)行適配器ai-sdk.ts —— 把 AI SDK 流部件轉(zhuǎn)換為本包共享LLMEvent保持默認(rèn) AI SDK 路徑兼容。這條邊界意味著在packages/llm內(nèi)寫代碼時(shí)永遠(yuǎn)不要把 session 級(jí)概念鑒權(quán)上下文、權(quán)限檢查、telemetry 頭注入帶進(jìn)來它們屬于 session 編排層及其本地適配器。小結(jié)opencode-ai/llm的設(shè)計(jì)可以用三句話概括src/schema/的 Schema 類是唯一運(yùn)行時(shí)數(shù)據(jù)模型llm.ts 的便捷函數(shù)只是返回同一批 Schema 類實(shí)例的薄構(gòu)造器一條路由由 Protocol、Endpoint、Auth、Framing 四個(gè)正交部件經(jīng)Route.make(...)組合提供商差異被壓縮為 5~15 行的配置調(diào)用而工具調(diào)度器tool-runtime.ts只負(fù)責(zé)「解碼輸入 → 執(zhí)行 → 編碼輸出 → 產(chǎn)出事件」這一窄窄的一段把流讀取、持久化與對(duì)話繼續(xù)全部留給外層。配套的類型化錯(cuò)誤LLMError/ToolFailure、fixture-first 的 cassette 錄制測(cè)試與「協(xié)議文件互相像」的風(fēng)格清單則共同保證了這套多協(xié)議體系在擴(kuò)張時(shí)仍然可評(píng)審、可推理。可運(yùn)行的端到端示例見 example/tutorial.ts協(xié)議層測(cè)試見packages/llm/test/下的*.test.tsfixture 優(yōu)先與*.recorded.test.tslive cassette?！久赓M(fèi)下載鏈接】opencodeThe open source coding agent.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/openc/opencode創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考