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