Kilo Session LLM 运行时边界解析：AI SDK 与 @opencode-ai/llm 原生运行时的双轨适配架构

Kilo Session LLM 运行时边界解析AI SDK 与 opencode-ai/llm 原生运行时的双轨适配架构【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode本文档深入解析 Kiloopencode会话层 LLM 服务的运行时边界设计src/session/llm.ts作为会话专属编排入口如何通过ai-sdk.ts、native-request.ts、native-runtime.ts三个适配器在默认 AI SDK 运行时与实验性原生opencode-ai/llm运行时之间完成逐请求per-request的选路、降级与事件统一。读完本文你将掌握该适配层的文件职责划分、五条关键集成接缝、原生运行时的门控判定逻辑与安全回退规则以及如何通过环境变量开启实验性原生执行。边界职责llm.ts 拥有哪些会话专属职责packages/opencode/src/session/llm.ts是 opencode 的会话 LLM 服务opencode/LLM是整个src/session/llm/目录中唯一需要了解完整会话请求形态StreamInput/StreamRequest的文件。从源码看它通过Effect依赖注入方式组合了认证Auth.Service、配置Config.Service、模型/提供商解析Provider.Service、插件Plugin.Service、权限Permission.Service、事件桥EventV2Bridge.Service、LLM 客户端LLMClientService与运行时开关RuntimeFlags.Service等服务。在 llm.ts 的LLM.run中请求在被交给任何运行时之前会先完成一组opencode 归属的预处理解析语言模型与提供商信息、拉取配置与认证信息、通过LLMRequestPrep.prepare组装系统提示词、消息、工具、采样参数、请求头与插件钩子结果。也就是说认证、配置、模型/提供商解析、插件、权限、遥测头、运行时选择都归属于服务层适配器层只负责翻译与传输不持有会话逻辑。与之相对src/session/llm/目录下的文件是服务边界之后的适配器adapter它们的目标是让不同的底层执行引擎对会话处理器呈现一致的接口。适配层文件结构与职责划分文档给出的目录结构原文见 AGENTS.md如下仓库中实际还包含一个request.ts请求预处理即上文的LLMRequestPrepsrc/session/ llm.ts session-owned orchestration and runtime selection llm/ AGENTS.md boundary notes for the adapter layer ai-sdk.ts AI SDK fullStream - opencode-ai/llm LLMEvent adapter native-request.ts opencode/AI SDK-shaped input - opencode-ai/llm LLMRequest native-runtime.ts native runtime gate, tool bridge, and LLMClient handoff三个适配器的职责定位ai-sdk.ts默认路径把 AI SDKstreamText(...)返回的fullStream事件start-step、text-delta、reasoning-delta、tool-call、tool-result、finish-step、finish等逐条转换为opencode-ai/llm的LLMEvent。它是默认运行时路径见 ai-sdk.ts。native-request.ts纯降级不执行把 opencode 规范化的会话输入RequestInput转换为原生opencode-ai/llm的LLMRequest。它只负责降级lowering不发起任何请求见 native-request.ts。native-runtime.ts可选原生运行时适配器判定所选模型是否受原生运行时支持构建原生请求把 opencode 的工具桥接为原生可执行工具并把传输委托给LLMClient/RequestExecutor见 native-runtime.ts。值得注意的是request.ts同样位于该目录但属于服务层的请求装配逻辑系统提示词、chat.params/chat.headers插件钩子、工具过滤与排序、请求头组装这也是AGENTS.md强调避免把会话服务导入native-request.ts改用RequestInput传递规范化数据的原因——装配与降级必须解耦。五条集成接缝新代码应停留的位置文档明确了 5 个集成点integration points它们是新增集成代码唯一允许落位的接缝llm.ts→LLMClient来自opencode-ai/llm/route原生执行是唯一直接调用LLMClient的路径。llm.ts→LLMAISDK来自./llm/ai-sdkAI SDK 路径仍在本地调用streamText(...)随后把result.fullStream适配为共享的LLMEvent。llm.ts→LLMNativeRuntime来自./llm/native-runtime这是运行时选择接缝。不受支持的原生请求返回一个具体原因reason随后回退到 AI SDK。native-runtime.ts→LLMNative来自./native-request保持请求降级与传输/工具执行分离。native-request.ts是唯一应构造LLM.request(...)、LLM.model(...)、Message.*、SystemPart、ToolCallPart、ToolResultPart、ToolDefinition等opencode-ai/llm规范对象的适配文件——这是文档设定的构造约束防止规范对象散落各处。在 llm.ts 中可以看到接缝 1/2/3 的实际落点当flags.experimentalNativeLlm开启时先尝试LLMNativeRuntime.stream(...)若返回{ type: supported }则直接消费其LLMEvent流否则记录llm.native_unsupported_reason并继续走 AI SDK 分支。在llm.ts的stream方法末尾两条分支汇合原生分支直接返回流AI SDK 分支则经LLMAISDK.toLLMEvents逐事件转换后拼装为同一形态的流见 llm.ts。运行时选择机制逐请求门控与统一事件流文档给出了完整的运行时选择流程图两个运行时收敛到同一个由会话处理器消费的LLMEvent流。门控是**逐请求per-request**的同一个会话中某些调用可以走原生另一些可以回退到 AI SDK。原图如下╭───────────────────╮ ╭───────────────────────────▶│ session processor │ │ ╰─────────┬─────────╯ │ │ │ │ │ │ │ ▼ │ ╭─────────────────────────╮ │ │ LLM.Service (../llm.ts) │ │ ╰────────────┬────────────╯ │ │ │ │ │ │ │ ▼ │ ╭───────────╮ │ ╭─╯ ╰─╮ │ │ native gate │ │ ╰─╮ ╭─╯ │ ╰─────┬─────╯ │ │ │ ╭────── no ──────┴─────── yes ────────╮ │ │ │ │ ▼ ▼ │ ╭───────────────────────────╮ ╭───────────────────╮ │ │ AI SDK │ │ native-runtime.ts │ │ │ streamText / generateText │ ╰────────┬──────────╯ │ ╰─────────────┬─────────────╯ │ │ │ │ │ ╭───╯ │ │ │ │ │ ▼ ▼ │ ╭───────────────────────╮ ╭────────────────────────────╮ │ │ ai-sdk.ts │ │ native-request.ts │ │ │ fullStream → LLMEvent │ │ session input → LLMRequest │ │ ╰──────────┬────────────╯ ╰──────────────┬─────────────╯ │ │ │ │ │ ╭───╯ │ │ │ │ ▼ ▼ │ ╭─────────────────╮ ╭─────────────────────────────╮ ╰───────┤ LLMEvent stream │◀────────────┤ LLMClient · RequestExecutor │ ╰─────────────────╯ ╰─────────────────────────────╯native-runtime.ts负责评估门控gate要么桥接到opencode-ai/llm要么把控制权交还给llm.ts走 AI SDK 路径。工具执行tool execution在两条分支中都由 opencode 持有只有请求降级与传输不同——这正是运行时可替换但工具体系统一这一设计的关键。门控判定源码级拆解native-runtime.ts的statusWithFetch实现了门控判定依次检查见 native-runtime.ts提供商 ID仅接受openai、anthropic或以opencode开头的提供商否则返回provider is not openai, opencode, or anthropic。SDK 包npm 字段仅接受ai-sdk/openai、ai-sdk/openai-compatible、ai-sdk/anthropic否则返回provider package is not OpenAI, OpenAI-compatible, or Anthropic。OAuth 认证若认证类型为oauth要求提供商必须是openai且提供了provider.options.fetch覆盖否则返回OAuth auth requires a provider fetch overrideOpenAI OAuth 需要自定义 fetch 注入令牌。API Key从provider.options.apiKey或provider.key中取值缺失则返回API key is not configured。全部通过后返回{ type: supported, apiKey, baseURL? }。这些分支在测试 llm-native.test.ts 中均有对应断言。原生请求降级native-request.ts与模型路由native-request.ts的request函数把RequestInput降级为LLM.request(...)系统提示词与消息中的system角色合并为SystemPart其余角色转为Message.make保留providerOptions中的原生续传元数据工具转为ToolDefinition采样参数收敛为generationtemperature/topP/topK/maxTokens。内容部分content part支持text、filemedia、reasoning、tool-call、tool-result五种形态其中媒体文件仅接受string或Uint8Array数据。model函数则根据模型目录条目中的api.npm字段路由到对应提供商配置见 native-request.tsai-sdk/openai→OpenAI.configure(...).responses(...)ai-sdk/azure→Azure.configure(...)ai-sdk/anthropic→Anthropic.configure(...)ai-sdk/google→Google.configure(...)ai-sdk/amazon-bedrock→AmazonBedrock.configure(...)ai-sdk/openai-compatible→OpenAICompatible.configure({ provider, baseURL })openrouter/ai-sdk-provider→OpenRouter.configure(...)。配置项包含 API Key、baseURL、合并后的请求头以及模型上下限limits.context/limits.output。baseURL 缺失时requireBaseURL会抛出明确错误Azure 与 OpenAI-compatible 强制要求。原生工具桥执行仍归 opencode 所有native-runtime.ts的nativeTools把 opencode 的 AI SDKTool包装为原生NativeTool见 native-runtime.tsjsonSchema优先取inputSchema.jsonSchema否则用asSchema归一化execute内部重新调用原工具的item.execute(args, { toolCallId, messages, abortSignal })异常被包装为ToolFailure。流式处理中原生tool-call事件若未被提供商执行!event.providerExecuted会经ToolRuntime.dispatch调度到这些工具结果事件通过Queue回灌到LLMEvent流已完成执行的工具调用providerExecuted则直接透传。这正是工具执行 stays opencode-owned的实现细节。安全边界默认 AI SDK原生为可选增强文档明确列出安全边界safety boundary这是使用原生运行时前必须理解的三条规则AI SDK 保持默认不设置任何实验开关时所有请求走streamText路径原生运行时完全不会被触发。KILO_EXPERIMENTAL_NATIVE_LLMtrue或伞形开关KILO_EXPERIMENTALtrue开启原生原生不是全局替换而是逐请求选路。原生执行当前支持的范围OpenAI、opencode 托管的 OpenAI 兼容、Anthropic API-Key 路径由ai-sdk/openai、ai-sdk/openai-compatible、ai-sdk/anthropic三类目录条目支撑。回退情形不支持的提供商、OpenAI OAuth、缺失 API Key 等一律回退到 AI SDK。开关的底层实现在 runtime-flags.tsexperimentalNativeLlm: bool(KILO_EXPERIMENTAL_NATIVE_LLM)即读取同名环境变量布尔值默认false。而伞形开关KILO_EXPERIMENTALtrue通过enabledByExperimental组合器作用于一批实验特性experimentalScout、experimentalReferences、experimentalLspTool等experimentalNativeLlm本身是独立的bool读取与伞形开关相互独立但文档建议二者皆可开启。测试文件 llm-native.test.ts 使用LLMClient.layer、RequestExecutor.layer与WebSocketExecutor.layer组合真实执行链路覆盖了请求降级、门控拒绝分支与端到端流式执行含工具失败包装ToolFailure。实践建议与总结从文档与源码可以总结出以下工程约束对任何希望在src/session/llm/目录内新增集成的开发者同样适用新增集成代码只允许落在五条接缝上需要扩展原生提供商时先在native-request.ts的model路由中补充 npm 包映射再在native-runtime.ts的门控中同步更新支持清单避免跳过门控直接接入传输层。不要向native-request.ts导入会话服务它只消费RequestInput规范化数据任何会话级上下文认证、权限、插件都应先在llm.ts/request.ts装配完毕。统一事件流是兼容性契约ai-sdk.ts与native-runtime.ts都产出opencode-ai/llm的LLMEvent会话处理器不关心请求实际由哪个运行时处理新增运行时同样必须遵守这一事件契约。工具执行永远归 opencode 所有原生运行时只负责把工具调用翻译回 AI SDKTool.execute形态工具注册、权限判定与执行结果回传的语义不变。这套服务层统一编排 适配层双轨执行 逐请求门控回退的架构让 Kilo 能够在保持 AI SDK 默认路径稳定性的同时渐进式验证opencode-ai/llm原生传输层为后续将更多提供商乃至 Copilot 计费字段提取等场景见 ai-sdk.ts 中的临时桥接注释迁移到原生运行时保留了清晰的演进路径。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考