AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载导读llm是 Kimi Codeagent-core-v2human 层内部一个独立、自洽的 LLM 请求库位于packages/agent-core-v2/src/human/llm/它封装了一次 LLM 请求的全部能力跨协议openai / openai-responses / anthropic / google-genai的请求编码解码、流式事件、thinking、媒体、错误分类、重试与恢复以及 provider/model 目录管理。本文将以 llm.md 为主干结合源码逐层剖析它的设计原则、架构布局、请求生命周期、两层错误模型与重试/恢复机制读完你将对如何把一次 LLM 调用做成可扩展、可恢复、协议无关的请求管线有完整可落地的认识。一、定位与边界llm 一次请求llm模块的设计哲学可以浓缩为一句边界宣言llm 只处理请求的编码/解码与事件发射。auth、usage 记账、HistoryMessage/meta、compaction、switch、媒体文件系统、Tool Message 组装——这些能力一律不在 llm 范围内要么上移到 turn/agent 层要么作为贡献点contribution point插入。对应的设计原则在 llm.md 中被明确为 9 条最小边界llm a single request只做请求编解码与事件发射流式优先事件即契约对外唯一表面是一个纯可序列化的事件流format 屏蔽协议差异trait 表达 provider 定制协议差异不能泄漏到 turn 层或 requester 装饰器两层错误模型内部抛 SDK 原生错误外部只有llm.failed.syntax与llm.failed.remote无状态核心 turn 驱动编排generate(config, content, control)是无状态函数错误经 onEvent 传递而非抛出不做静默降级No silent fallback配置按原样取用beta 特性、thinking、空响应等场景先定义明确错误条件请求时失败并引导用户修配置每个可变能力都是贡献点providers、media、usage、traceId、错误恢复全部走扩展点llm 核心不含这些概念数据就是数据Data is data模型是纯函数无关数据endpoint url model 唯一标识一个模型可序列化、可直接作为 generate 输入目录只是provider - models的派生缓存消息转换采用编译器范式Message[]到协议 payload 是 N:M 映射用 MLIR 风格 Pattern Rewriter有序、独立的 Pattern 把 MessageRange 重写为另一个 MessageRange最后做一次 lowering。关键源码佐证无状态核心体现在 requester.tsLlmRequester.generate(config, content, control): Promisevoid事件经LlmRequestControl.onEvent回调送出从不 throw模型是纯数据体现在 model.tsLlmModel extends LlmConnection字段仅provider、model、capability、maxContextSize、maxInputSize与连接覆盖baseUrl/apiKey/defaultHeaders/betaApi/vertexai没有任何函数字段modelKey用baseUrl#model唯一标识一个模型。二、架构总览目录即分层llm/的目录结构本身就是架构说明见 llm.md 的 Architecture 一节源码对应 src/human/llmllm/ ├── message.ts 通用 Message 模型按 role 拆分工具声明独立存放 ├── model.ts LlmModel纯数据providermodelendpoint 覆盖 ├── capability.ts / thinking.ts / usage.ts / finish-reason.ts / response-format.ts / syntax-errors.ts ├── errors.ts 两层 LlmErrorKindsyntax | remote各自再细分 ├── toolCallIdNormalizer.ts 流式工具调用 id 去重重复的原始 id 按序重映射 │ ├── protocol/ 共享协议层各 base 通用 │ ├── base.ts ProtocolName / ProtocolBaseTTrait / ProtocolRequesterOptions / TraitContext │ ├── format.ts ProtocolFormatcreateStreamParser(接收回调 resolveUsage 选项) │ ├── connection.ts ProviderConnectionendpoint env 声明 默认请求头 │ ├── thinking.ts ThinkingStrategy → ThinkingContribution → applyThinking → AppliedThinking │ └── patterns.ts / rewrite.ts MLIR 风格 Pattern RewriterMessage N:M 转换 │ ├── requester/ │ ├── requester.ts LlmRequester.generate(config, content, control) │ │ ExtraParams 按协议类型化 {openai?, responses?, anthropic?, googleGenai?} │ │ LlmRequestConfig.credentialProvider凭证贡献点 │ ├── actor.ts 请求 actorfromCallback 包装单次请求 │ │ messageResolvers、abort scope、事件 sendBack │ ├── retry.ts / recovery.ts 纯函数式重试/恢复策略由 turn 状态机驱动 │ ├── empty-response.ts emptyResponseError纯函数空响应判定 │ └── bases/ 四个协议 baseopenai / openai-responses / anthropic / google-genai │ 每个都含 contract / format / lower / patterns / capability / extra-params / trait / requester │ 公开接缝是 contract / trait / requesterformat / lower / patterns 保持内部 │ ├── provider/ │ ├── definition.ts ProviderDefinition{id, protocols, media, models} │ │ createProvider()无注册表→ Provider{listModels, resolveModel, createRequester} │ └── providers/ 内置 provider如 standard经贡献点注册 │ ├── provider-catalog.ts xstate 状态机refresh/upsert/remove/ping 进changed 出 │ provider - models 结构远端拉取模型与本地模型双数据源 │ └── media/ 媒体贡献点cache / degrade / ref / resolver / store / upload值得强调的两条边界规则源码级可见公开接缝 vs 内部实现每个 base 对外只暴露contract / trait / requesterformat / lower / patterns是 requester 管线内部件只有 base 代码与测试可以 import有 lint 强制约束。format与trait互不 import双方只讲协议contract.ts里的中性 wire/chunk 类型——见 base.ts。请求 actor 是组合根createRequestActor(requester, messageResolvers)用fromCallback包装单次请求负责把credentialProvider.resolve()的凭证applyCredential到模型上、串行跑过全部 messageResolvers、再把事件sendBack——见 actor.ts。三、消息模型与事件契约3.1 通用 Message 模型message.ts 定义了一套与具体厂商无关的中性消息结构角色system | user | assistant | toolRole类型内容部件ContentParttext、think含encrypted/detailsIndex/hidden/reasoningKey、image_url、audio_url、video_url工具声明独立存放ToolDescription { name, description, parameters, deferred? }不混入消息正文工具调用ToolCall { type: function, id, name, arguments, extras?, rawId?, _streamIndex? }流式部件StreamedMessagePart ContentPart | ToolCall | ToolCallPart其中ToolCallPart只带argumentsPart与index供流式增量拼接。同文件还提供了两个增量世界的关键设施mergeInPlace(target, source)流式片段就地合并text 拼接、think 拼接、function吸收tool_call_part的参数增量createMessageAccumulator()push(part)逐块累积、finish()产出完整AssistantMessage内部用toolCallIndexMap按流式 index 归并工具调用、用deferredThink处理真空 think 部件——这正是 turn 层在事件流之上重建完整消息的基础设施。3.2 事件流唯一的对外表面requester 层的事件在 requester.ts 中定义是纯可序列化的单条事件流llm.sent llm.streaming.headers // { headers } llm.streaming.part // 流式增量部件 llm.streaming.usage // 部分 TokenUsage llm.streaming.finish // FinishInfo llm.streaming.message_id // messageId llm.failed.syntax // 本地语法错误永不重试 llm.failed.remote // 远端流式错误 llm.request.retrying // 调用方在 turn 之下重试某次 attempt 且须丢弃其流式状态 llm.done // 成功结束turn 层在此基础上追加llm.retrying / llm.recovering并把llm.sent扩展为携带最近一次恢复记录recovery?: LlmRecoveryRecord见 actor.ts。设计要点流式与非流式同构非流式也走事件流累积只是没有 delta事件随到随发不缓存、不 fallback事件即契约usage 记账、tracing、compaction、媒体降级全部以插件/贡献点方式挂在事件流上。四、协议层format 与 trait 的分工跨协议差异由两层各司其职format 住在协议层负责请求/响应/错误/usage/finish 的编解码。它对外只暴露createStreamParser(sink callbacks resolveUsage option)见 format.tstrait 表达 provider 定制每个协议拥有一个类型化 trait 接口OpenAITrait/OpenAIResponsesTrait/AnthropicTrait/GoogleGenAITrait只暴露该协议真正消费的定制点——协议忽略的 hook 无法表达永远不会静默闲置。connection与classifyError、capability也各有归属endpoint/env 解析与默认请求头构成 providerconnectionconnection.ts错误分类是 requester 选项LlmErrorClassifier见 requester.ts模型能力是 provider-binding 字段——这些都不是 format 的业务。requester 是组合根固定管线交替 format 阶段与 trait hook以 OpenAI 为例openai/requester.ts 中的prepareOpenAIRequest展示了完整的显式数据流encodeCacheKey / thinking / encodeMaxCompletionTokens ← trait hook有默认实现 ↓ lowerOpenAIMessagesPattern Rewriter lowering ← format 阶段 ↓ convertMessage可 null 丢弃 ← trait hook ↓ mergeHistory / convertTool / buildParams ← trait hook ↓ encodeOpenAIRequest ← format 阶段FormatRequestInput与resolveMaxCompletionCapmaxCompletionTokens会被maxContextTokens - usedContextTokens钳制见 format.ts保证了请求参数的确定性计算。请求执行侧executeOpenAIRequest则把官方 SDK 的流式 chunk 喂给无状态 parser 回调转成llm.streaming.part / usage / finish / message_id成功发llm.done、失败发llm.failed.*且绝不发llm.done见 openai/requester.ts。五、请求生命周期从 generate 到 donellm.md 给出的完整生命周期如下与源码实现一一对应generate(config, content, control)被调用调用方机器路径上是请求 actor在每次 attempt 之前把config.credentialProvider解析成凭证完备的模型——因此请求总是携带新鲜凭证而凭证刷新恢复可恢复的 401 →credentials.invalidate()发llm.recoveringstrategy 为credentials在重发时自然重新解析。状态机之外的直接调用方ping、generate、full compaction、media upload通过runWithCredentialRecovery/streamWithCredentialRecovery共享同一套单次重试恢复requester 的prepare*Request把纯 format 阶段与 trait hook 组合成协议 requestParamsformat 经 Pattern Rewriter 把通用Message[]降级trait 在中间调整 kwargs、转换后的消息、历史、工具与最终参数execute*Request调用官方 SDK流式 chunk 由无状态 parser 回调转换为llm.streaming.part / usage / finish / message_id事件错误由 format 转换为llm.failed.*成功发llm.done失败以llm.failed.syntax / llm.failed.remote收尾且不发llm.done在llm.done时turn 用纯函数emptyResponseError判定空响应并将其提升为llm.failed.remote进入同一失败级联turn 状态机在llm.failed.remote时先尝试恢复引擎组合的策略链可恢复 401 的凭证刷新优先然后是替换消息类策略每个纯propose返回一条记录其不透明beforeNextAttempt副作用由 turn 执行并发llm.recovering然后带退避重试尊重 Retry-After发llm.retryingattempts 耗尽才失败 turnturn 持有 HistoryAccumulator由事件流喂养在llm.retrying / llm.recovering / llm.request.retrying时回滚并重建它——每次 attempt 从零累积同时尽量保留被中断状态完整消息在llm.done时由 accumulator 产出。已转发给父机器/UI 的部件不会回收只有 accumulator 与工具调用 id 归一化器被重置。Abort 的归属AbortController归 turn 所有通过LlmInput.signal传入请求 actorturn 在turn.abort时直接 abort请求以llm.failed.remote结束。请求 actor既不创建自己的 controller也不在 teardown 时触碰任何 signal——这样已完成的请求永远不会误中止共享 signalactor.ts。六、两层错误模型与错误分类errors.ts 实现了文档描述的两层错误模型内部代码抛 SDK 原生错误本地请求校验抛共享的SyntaxRequestFormatErrorllm/syntax-errors.tsrequester 用toLlmSyntaxErrorMessage统一转换无中间层外部只有两类。llm.failed.syntax本地消息语法错误永不重试与llm.failed.remote远端流式错误由 format 在边界转换。LlmErrorKind的细分源码可见syntax | abort | connection | timeout | status | rate_limit | quota_exhausted | overloaded | context_overflow | request_too_large | request_structure | image_format | empty_response | provider | unknown其中LlmRemoteErrorKind ExcludeLlmErrorKind, syntax。错误分类不是靠猜而是用一组正则模式匹配 状态码判定的纯函数完成例如429 →rate_limitisContextOverflowStatusError400/413/422 context length、maximum context等模式→context_overflowisProviderOverloadStatusError529 直接命中500/503 overload→overloadedisRequestTooLargeStatusError413→request_too_largeisRequestStructureStatusError400/422含 tool exchange 相邻性模式如tool_use...tool_result→request_structureisImageFormatStatusError400 图片解码模式→image_format。还有两个工程细节值得注意sanitizeStatusErrorMessage会从 HTML 错误页里抽取title文本parseRetryAfterMs解析Retry-After响应头为毫秒errors.ts供重试退避使用。对 thinking effort 被 provider 拒绝的场景appendThinkingEffortConfigHint会在 400/422 且消息匹配reasoning_effort/thinking_effort时追加配置提示——这正体现了不静默降级直接失败并引导修复的原则。七、重试与恢复turn 驱动的纯策略7.1 retry.ts退避与可重试判定retry.ts 是纯策略模块关键常量与函数DEFAULT_MAX_RETRY_ATTEMPTS 10resolveMaxAttempts取max(maxAttemptsPerStep, 1)指数退避retryBackoffDelay(attemptIndex)min(500ms * 2^n, 32_000ms) 0.25 * base 的随机抖动readRetryAfterMs优先尊重Retry-AfterisRetryableErrorsyntax / abort / quota_exhausted / context_overflow / request_too_large / request_structure / image_format / unknown不可重试empty_response仅当 finishReason 不是filtered时可重试status仅在RETRYABLE_STATUS_CODES [408, 409, 429, 500, 502, 503, 504, 529]时可重试其余默认可重试shouldRetry(options, attempt, error)infiniteRetry为 true 时无限重试。7.2 recovery.ts策略链的纯 proposerecovery.ts 定义了恢复策略的契约interface LlmRecoveryContext { readonly error: LlmRemoteErrorMessage; readonly messages: readonly Message[]; readonly appliedRecoveries: readonly LlmRecoveryRecord[]; readonly credentialProvider?: LlmCredentialProvider; } interface LlmRecoveryProposal { readonly action: string; readonly attemptMessageOverride?: readonly Message[]; // 可选替换消息 readonly beforeNextAttempt?: () void; // 可选不透明副作用 } interface LlmRecovery { propose(ctx: LlmRecoveryContext): (LlmRecoveryProposal LlmRecoveryRecord) | undefined; }每个策略的propose是纯函数返回自描述记录strategy/action、可选attemptMessageOverride、可选beforeNextAttempt。turn 执行beforeNextAttempt和/或替换消息后把 attempt 重置为 1 重新进入thinking该 override 在同一步骤的后续重试中持续生效直到下一步之前被替换或清除。恢复策略链由调用方引擎组合先credentialsRecovery凭证刷新再配置的替换消息策略如媒体降级。7.3 与凭证贡献点的联动LlmRequestConfig.credentialProviderresolve / canRecover / invalidate是凭证贡献点见 requester.ts工厂与credentialsRecovery策略位于human/credentialscreateStaticCredentialProvider/createOAuthCredentialProvidercreateKimiOAuthCredentialProvider适配 Kimi OAuth 令牌直接调用方的runWithCredentialRecovery/streamWithCredentialRecovery执行器位于llm-adapter/model/credential-recovery。八、Provider 定义与模型目录8.1 无注册表的 createProviderprovider/definition.ts 定义了 provider 的形状interface ProviderDefinition { readonly id: string; readonly protocols: { [N in ProtocolName]?: ProtocolBindingN }; readonly media?: ProviderMediaContribution; readonly models?: ProviderModelSource; // () Promisereadonly LlmModelSeed[] }createProvider(definition)不经过注册表直接导出一个 constProvider暴露listModels / resolveModel / createRequesterdefinition.ts。每个协议绑定ProtocolBinding { base, trait?, connection?, classifyError?, capability? }resolveModel(model, { protocol, baseUrl, apiKey, ... })生成带能力的LlmModel能力优先级为binding.capability → base.capability → UNKNOWN_CAPABILITY。内置 provider如standard经贡献点注册见 provider/providers/standard.ts。8.2 provider-catalog双数据源状态机provider-catalog.ts 是一个 xstate 状态机refresh / upsert / remove / ping进changed出内部维护provider - models结构并区分远端拉取模型与本地模型两个数据源。它只是provider - models的派生缓存——依赖方向只允许 models-dev 进入 llm 内部绝不反向原则 8。九、媒体贡献点llm/media/是一组贡献点cache / degrade / ref / resolver / store / upload对应 media 目录由 provider 的media字段声明。媒体上传/降级、usage、traceId 这些可变能力全部以插件形式接入llm 核心不含任何这些概念原则 7——例如媒体降级是替换消息类恢复策略之一与凭证刷新一起构成 turn 的重试前策略链。十、被否决的设计方案勿再引入llm.md 的 Rejected Schemes 一节记录了设计演进中明确放弃的方案阅读源码时不应再引入把请求 actor 拆成llmActor / llmStreamActor——每个请求一个 actor非流式同样在流上累积用专门的 llm 状态机包住请求 actor——turn 状态机直接调用 actor 并拥有重试/恢复多余机器层无状态可消费DDD 领域方法包装Generation Domain 等——改用 format/trait/provider 分层单一跨协议 trait 大杂烩旧 ProtocolTrait——改为每协议类型化 trait由 requester 请求管线组合把 trait 绑进 formatcreateOpenAIFormat(trait)闭包或作为 formatRequest 选项传递 hook——requester 管线显式交替 format 阶段与 trait hook两侧只共享contract.ts中性类型函数式toWireMessage/WireAdapter命名——用 adapter 接口名字里没有 Wireprovider 注册表 /defineProvider——createProvider直接导出 const出口处把 system 消息从原位置提升——system 消息留在历史原位、原位转换llm 发射{message, meta}Context 对象——meta 属于 turn 域llm 只发事件accumulator 在 llm 与 turn 各实现一份——accumulator 仅由 turn 持有、由事件流喂养beta 特性无限 fallback——协议拆分为anthropic/anthropic_beta未指定即不发送误配置即报错需要 beta 特性的 provider 必须显式使用anthropic_beta协议。十一、小结从一次请求看完整架构把整条链路串起来看llm模块的可复用性来自四组清晰边界关注点归属源码位置请求/响应编解码、流解析format协议层protocol/format.tsprovider 定制 hook每协议 trait各 bases/*/trait.ts请求管线组合format 阶段 × trait hookrequesterbases/openai/requester.tsendpoint/env、默认头connectionprotocol/connection.ts错误分类requester 选项 / format 边界errors.ts重试/恢复策略纯函数retry.ts / recovery.ts由 turn 驱动requester/retry.ts凭证解析与刷新credentialProvider 贡献点requester/requester.ts模型/目录provider provider-catalogprovider/definition.ts、provider-catalog.ts媒体media 贡献点media这套设计把协议差异format、厂商定制trait、请求组合requester 管线、失败处理turn 驱动的重试/恢复彻底解耦同时通过事件即契约 无状态核心 显式错误优先保证了流式请求的可恢复性与行为确定性。若要在 agent-core-v2 之外复用或扩展 LLM 请求能力llm.md 与其对应源码是最完整的起点——所有可变点都已声明为贡献点新增一个协议或 provider 不需要触碰 turn 层。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐DeepSeek Harness 中 LLM 暂时性请求失败的有界恢复LlmFailure、dsh-llm-retry 与按提供方路由的重试策略DeepSeek Harness 中 LLM 暂时性请求失败的有界恢复 LlmFailure 、 dsh llm retry 与按提供方路由的重试策略 本文以人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 有界 LLM 请求恢复机制解析LlmFailure、dsh-llm-retry 与停滞流超时的完整实现DeepSeek Harness 有界 LLM 请求恢复机制解析LlmFailure、dsh llm retry 与停滞流超时的完整实现 本文基于仓库内架构决人工智能AI AgentAgent 框架DeepSeeknew-api RelayKit 实战指南四大 LLM 文本协议的 DTO 与请求/响应/流式转换库new api RelayKit 实战指南四大 LLM 文本协议的 DTO 与请求/响应/流式转换库 RelayKit 是从 new api https://后端API网关LLM 网关大模型认证鉴权桌面应用上一篇Google Cloud Storage 存储桶架构化 Terraform 配置指南从 Draft Plan 到 google_storage_bucket 完整映射实践下一篇TensorRT 11 C Runtime 部署实战用现代 Runtime API 加载并运行 .plan 引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载导读llm是 Kimi Codeagent-core-v2human 层内部一个独立、自洽的 LLM 请求库位于packages/agent-core-v2/src/human/llm/它封装了一次 LLM 请求的全部能力跨协议openai / openai-responses / anthropic / google-genai的请求编码解码、流式事件、thinking、媒体、错误分类、重试与恢复以及 provider/model 目录管理。本文将以 llm.md 为主干结合源码逐层剖析它的设计原则、架构布局、请求生命周期、两层错误模型与重试/恢复机制读完你将对如何把一次 LLM 调用做成可扩展、可恢复、协议无关的请求管线有完整可落地的认识。一、定位与边界llm 一次请求llm模块的设计哲学可以浓缩为一句边界宣言llm 只处理请求的编码/解码与事件发射。auth、usage 记账、HistoryMessage/meta、compaction、switch、媒体文件系统、Tool Message 组装——这些能力一律不在 llm 范围内要么上移到 turn/agent 层要么作为贡献点contribution point插入。对应的设计原则在 llm.md 中被明确为 9 条最小边界llm a single request只做请求编解码与事件发射流式优先事件即契约对外唯一表面是一个纯可序列化的事件流format 屏蔽协议差异trait 表达 provider 定制协议差异不能泄漏到 turn 层或 requester 装饰器两层错误模型内部抛 SDK 原生错误外部只有llm.failed.syntax与llm.failed.remote无状态核心 turn 驱动编排generate(config, content, control)是无状态函数错误经 onEvent 传递而非抛出不做静默降级No silent fallback配置按原样取用beta 特性、thinking、空响应等场景先定义明确错误条件请求时失败并引导用户修配置每个可变能力都是贡献点providers、media、usage、traceId、错误恢复全部走扩展点llm 核心不含这些概念数据就是数据Data is data模型是纯函数无关数据endpoint url model 唯一标识一个模型可序列化、可直接作为 generate 输入目录只是provider - models的派生缓存消息转换采用编译器范式Message[]到协议 payload 是 N:M 映射用 MLIR 风格 Pattern Rewriter有序、独立的 Pattern 把 MessageRange 重写为另一个 MessageRange最后做一次 lowering。关键源码佐证无状态核心体现在 requester.tsLlmRequester.generate(config, content, control): Promisevoid事件经LlmRequestControl.onEvent回调送出从不 throw模型是纯数据体现在 model.tsLlmModel extends LlmConnection字段仅provider、model、capability、maxContextSize、maxInputSize与连接覆盖baseUrl/apiKey/defaultHeaders/betaApi/vertexai没有任何函数字段modelKey用baseUrl#model唯一标识一个模型。二、架构总览目录即分层llm/的目录结构本身就是架构说明见 llm.md 的 Architecture 一节源码对应 src/human/llmllm/ ├── message.ts 通用 Message 模型按 role 拆分工具声明独立存放 ├── model.ts LlmModel纯数据providermodelendpoint 覆盖 ├── capability.ts / thinking.ts / usage.ts / finish-reason.ts / response-format.ts / syntax-errors.ts ├── errors.ts 两层 LlmErrorKindsyntax | remote各自再细分 ├── toolCallIdNormalizer.ts 流式工具调用 id 去重重复的原始 id 按序重映射 │ ├── protocol/ 共享协议层各 base 通用 │ ├── base.ts ProtocolName / ProtocolBaseTTrait / ProtocolRequesterOptions / TraitContext │ ├── format.ts ProtocolFormatcreateStreamParser(接收回调 resolveUsage 选项) │ ├── connection.ts ProviderConnectionendpoint env 声明 默认请求头 │ ├── thinking.ts ThinkingStrategy → ThinkingContribution → applyThinking → AppliedThinking │ └── patterns.ts / rewrite.ts MLIR 风格 Pattern RewriterMessage N:M 转换 │ ├── requester/ │ ├── requester.ts LlmRequester.generate(config, content, control) │ │ ExtraParams 按协议类型化 {openai?, responses?, anthropic?, googleGenai?} │ │ LlmRequestConfig.credentialProvider凭证贡献点 │ ├── actor.ts 请求 actorfromCallback 包装单次请求 │ │ messageResolvers、abort scope、事件 sendBack │ ├── retry.ts / recovery.ts 纯函数式重试/恢复策略由 turn 状态机驱动 │ ├── empty-response.ts emptyResponseError纯函数空响应判定 │ └── bases/ 四个协议 baseopenai / openai-responses / anthropic / google-genai │ 每个都含 contract / format / lower / patterns / capability / extra-params / trait / requester │ 公开接缝是 contract / trait / requesterformat / lower / patterns 保持内部 │ ├── provider/ │ ├── definition.ts ProviderDefinition{id, protocols, media, models} │ │ createProvider()无注册表→ Provider{listModels, resolveModel, createRequester} │ └── providers/ 内置 provider如 standard经贡献点注册 │ ├── provider-catalog.ts xstate 状态机refresh/upsert/remove/ping 进changed 出 │ provider - models 结构远端拉取模型与本地模型双数据源 │ └── media/ 媒体贡献点cache / degrade / ref / resolver / store / upload值得强调的两条边界规则源码级可见公开接缝 vs 内部实现每个 base 对外只暴露contract / trait / requesterformat / lower / patterns是 requester 管线内部件只有 base 代码与测试可以 import有 lint 强制约束。format与trait互不 import双方只讲协议contract.ts里的中性 wire/chunk 类型——见 base.ts。请求 actor 是组合根createRequestActor(requester, messageResolvers)用fromCallback包装单次请求负责把credentialProvider.resolve()的凭证applyCredential到模型上、串行跑过全部 messageResolvers、再把事件sendBack——见 actor.ts。三、消息模型与事件契约3.1 通用 Message 模型message.ts 定义了一套与具体厂商无关的中性消息结构角色system | user | assistant | toolRole类型内容部件ContentParttext、think含encrypted/detailsIndex/hidden/reasoningKey、image_url、audio_url、video_url工具声明独立存放ToolDescription { name, description, parameters, deferred? }不混入消息正文工具调用ToolCall { type: function, id, name, arguments, extras?, rawId?, _streamIndex? }流式部件StreamedMessagePart ContentPart | ToolCall | ToolCallPart其中ToolCallPart只带argumentsPart与index供流式增量拼接。同文件还提供了两个增量世界的关键设施mergeInPlace(target, source)流式片段就地合并text 拼接、think 拼接、function吸收tool_call_part的参数增量createMessageAccumulator()push(part)逐块累积、finish()产出完整AssistantMessage内部用toolCallIndexMap按流式 index 归并工具调用、用deferredThink处理真空 think 部件——这正是 turn 层在事件流之上重建完整消息的基础设施。3.2 事件流唯一的对外表面requester 层的事件在 requester.ts 中定义是纯可序列化的单条事件流llm.sent llm.streaming.headers // { headers } llm.streaming.part // 流式增量部件 llm.streaming.usage // 部分 TokenUsage llm.streaming.finish // FinishInfo llm.streaming.message_id // messageId llm.failed.syntax // 本地语法错误永不重试 llm.failed.remote // 远端流式错误 llm.request.retrying // 调用方在 turn 之下重试某次 attempt 且须丢弃其流式状态 llm.done // 成功结束turn 层在此基础上追加llm.retrying / llm.recovering并把llm.sent扩展为携带最近一次恢复记录recovery?: LlmRecoveryRecord见 actor.ts。设计要点流式与非流式同构非流式也走事件流累积只是没有 delta事件随到随发不缓存、不 fallback事件即契约usage 记账、tracing、compaction、媒体降级全部以插件/贡献点方式挂在事件流上。四、协议层format 与 trait 的分工跨协议差异由两层各司其职format 住在协议层负责请求/响应/错误/usage/finish 的编解码。它对外只暴露createStreamParser(sink callbacks resolveUsage option)见 format.tstrait 表达 provider 定制每个协议拥有一个类型化 trait 接口OpenAITrait/OpenAIResponsesTrait/AnthropicTrait/GoogleGenAITrait只暴露该协议真正消费的定制点——协议忽略的 hook 无法表达永远不会静默闲置。connection与classifyError、capability也各有归属endpoint/env 解析与默认请求头构成 providerconnectionconnection.ts错误分类是 requester 选项LlmErrorClassifier见 requester.ts模型能力是 provider-binding 字段——这些都不是 format 的业务。requester 是组合根固定管线交替 format 阶段与 trait hook以 OpenAI 为例openai/requester.ts 中的prepareOpenAIRequest展示了完整的显式数据流encodeCacheKey / thinking / encodeMaxCompletionTokens ← trait hook有默认实现 ↓ lowerOpenAIMessagesPattern Rewriter lowering ← format 阶段 ↓ convertMessage可 null 丢弃 ← trait hook ↓ mergeHistory / convertTool / buildParams ← trait hook ↓ encodeOpenAIRequest ← format 阶段FormatRequestInput与resolveMaxCompletionCapmaxCompletionTokens会被maxContextTokens - usedContextTokens钳制见 format.ts保证了请求参数的确定性计算。请求执行侧executeOpenAIRequest则把官方 SDK 的流式 chunk 喂给无状态 parser 回调转成llm.streaming.part / usage / finish / message_id成功发llm.done、失败发llm.failed.*且绝不发llm.done见 openai/requester.ts。五、请求生命周期从 generate 到 donellm.md 给出的完整生命周期如下与源码实现一一对应generate(config, content, control)被调用调用方机器路径上是请求 actor在每次 attempt 之前把config.credentialProvider解析成凭证完备的模型——因此请求总是携带新鲜凭证而凭证刷新恢复可恢复的 401 →credentials.invalidate()发llm.recoveringstrategy 为credentials在重发时自然重新解析。状态机之外的直接调用方ping、generate、full compaction、media upload通过runWithCredentialRecovery/streamWithCredentialRecovery共享同一套单次重试恢复requester 的prepare*Request把纯 format 阶段与 trait hook 组合成协议 requestParamsformat 经 Pattern Rewriter 把通用Message[]降级trait 在中间调整 kwargs、转换后的消息、历史、工具与最终参数execute*Request调用官方 SDK流式 chunk 由无状态 parser 回调转换为llm.streaming.part / usage / finish / message_id事件错误由 format 转换为llm.failed.*成功发llm.done失败以llm.failed.syntax / llm.failed.remote收尾且不发llm.done在llm.done时turn 用纯函数emptyResponseError判定空响应并将其提升为llm.failed.remote进入同一失败级联turn 状态机在llm.failed.remote时先尝试恢复引擎组合的策略链可恢复 401 的凭证刷新优先然后是替换消息类策略每个纯propose返回一条记录其不透明beforeNextAttempt副作用由 turn 执行并发llm.recovering然后带退避重试尊重 Retry-After发llm.retryingattempts 耗尽才失败 turnturn 持有 HistoryAccumulator由事件流喂养在llm.retrying / llm.recovering / llm.request.retrying时回滚并重建它——每次 attempt 从零累积同时尽量保留被中断状态完整消息在llm.done时由 accumulator 产出。已转发给父机器/UI 的部件不会回收只有 accumulator 与工具调用 id 归一化器被重置。Abort 的归属AbortController归 turn 所有通过LlmInput.signal传入请求 actorturn 在turn.abort时直接 abort请求以llm.failed.remote结束。请求 actor既不创建自己的 controller也不在 teardown 时触碰任何 signal——这样已完成的请求永远不会误中止共享 signalactor.ts。六、两层错误模型与错误分类errors.ts 实现了文档描述的两层错误模型内部代码抛 SDK 原生错误本地请求校验抛共享的SyntaxRequestFormatErrorllm/syntax-errors.tsrequester 用toLlmSyntaxErrorMessage统一转换无中间层外部只有两类。llm.failed.syntax本地消息语法错误永不重试与llm.failed.remote远端流式错误由 format 在边界转换。LlmErrorKind的细分源码可见syntax | abort | connection | timeout | status | rate_limit | quota_exhausted | overloaded | context_overflow | request_too_large | request_structure | image_format | empty_response | provider | unknown其中LlmRemoteErrorKind ExcludeLlmErrorKind, syntax。错误分类不是靠猜而是用一组正则模式匹配 状态码判定的纯函数完成例如429 →rate_limitisContextOverflowStatusError400/413/422 context length、maximum context等模式→context_overflowisProviderOverloadStatusError529 直接命中500/503 overload→overloadedisRequestTooLargeStatusError413→request_too_largeisRequestStructureStatusError400/422含 tool exchange 相邻性模式如tool_use...tool_result→request_structureisImageFormatStatusError400 图片解码模式→image_format。还有两个工程细节值得注意sanitizeStatusErrorMessage会从 HTML 错误页里抽取title文本parseRetryAfterMs解析Retry-After响应头为毫秒errors.ts供重试退避使用。对 thinking effort 被 provider 拒绝的场景appendThinkingEffortConfigHint会在 400/422 且消息匹配reasoning_effort/thinking_effort时追加配置提示——这正体现了不静默降级直接失败并引导修复的原则。七、重试与恢复turn 驱动的纯策略7.1 retry.ts退避与可重试判定retry.ts 是纯策略模块关键常量与函数DEFAULT_MAX_RETRY_ATTEMPTS 10resolveMaxAttempts取max(maxAttemptsPerStep, 1)指数退避retryBackoffDelay(attemptIndex)min(500ms * 2^n, 32_000ms) 0.25 * base 的随机抖动readRetryAfterMs优先尊重Retry-AfterisRetryableErrorsyntax / abort / quota_exhausted / context_overflow / request_too_large / request_structure / image_format / unknown不可重试empty_response仅当 finishReason 不是filtered时可重试status仅在RETRYABLE_STATUS_CODES [408, 409, 429, 500, 502, 503, 504, 529]时可重试其余默认可重试shouldRetry(options, attempt, error)infiniteRetry为 true 时无限重试。7.2 recovery.ts策略链的纯 proposerecovery.ts 定义了恢复策略的契约interface LlmRecoveryContext { readonly error: LlmRemoteErrorMessage; readonly messages: readonly Message[]; readonly appliedRecoveries: readonly LlmRecoveryRecord[]; readonly credentialProvider?: LlmCredentialProvider; } interface LlmRecoveryProposal { readonly action: string; readonly attemptMessageOverride?: readonly Message[]; // 可选替换消息 readonly beforeNextAttempt?: () void; // 可选不透明副作用 } interface LlmRecovery { propose(ctx: LlmRecoveryContext): (LlmRecoveryProposal LlmRecoveryRecord) | undefined; }每个策略的propose是纯函数返回自描述记录strategy/action、可选attemptMessageOverride、可选beforeNextAttempt。turn 执行beforeNextAttempt和/或替换消息后把 attempt 重置为 1 重新进入thinking该 override 在同一步骤的后续重试中持续生效直到下一步之前被替换或清除。恢复策略链由调用方引擎组合先credentialsRecovery凭证刷新再配置的替换消息策略如媒体降级。7.3 与凭证贡献点的联动LlmRequestConfig.credentialProviderresolve / canRecover / invalidate是凭证贡献点见 requester.ts工厂与credentialsRecovery策略位于human/credentialscreateStaticCredentialProvider/createOAuthCredentialProvidercreateKimiOAuthCredentialProvider适配 Kimi OAuth 令牌直接调用方的runWithCredentialRecovery/streamWithCredentialRecovery执行器位于llm-adapter/model/credential-recovery。八、Provider 定义与模型目录8.1 无注册表的 createProviderprovider/definition.ts 定义了 provider 的形状interface ProviderDefinition { readonly id: string; readonly protocols: { [N in ProtocolName]?: ProtocolBindingN }; readonly media?: ProviderMediaContribution; readonly models?: ProviderModelSource; // () Promisereadonly LlmModelSeed[] }createProvider(definition)不经过注册表直接导出一个 constProvider暴露listModels / resolveModel / createRequesterdefinition.ts。每个协议绑定ProtocolBinding { base, trait?, connection?, classifyError?, capability? }resolveModel(model, { protocol, baseUrl, apiKey, ... })生成带能力的LlmModel能力优先级为binding.capability → base.capability → UNKNOWN_CAPABILITY。内置 provider如standard经贡献点注册见 provider/providers/standard.ts。8.2 provider-catalog双数据源状态机provider-catalog.ts 是一个 xstate 状态机refresh / upsert / remove / ping进changed出内部维护provider - models结构并区分远端拉取模型与本地模型两个数据源。它只是provider - models的派生缓存——依赖方向只允许 models-dev 进入 llm 内部绝不反向原则 8。九、媒体贡献点llm/media/是一组贡献点cache / degrade / ref / resolver / store / upload对应 media 目录由 provider 的media字段声明。媒体上传/降级、usage、traceId 这些可变能力全部以插件形式接入llm 核心不含任何这些概念原则 7——例如媒体降级是替换消息类恢复策略之一与凭证刷新一起构成 turn 的重试前策略链。十、被否决的设计方案勿再引入llm.md 的 Rejected Schemes 一节记录了设计演进中明确放弃的方案阅读源码时不应再引入把请求 actor 拆成llmActor / llmStreamActor——每个请求一个 actor非流式同样在流上累积用专门的 llm 状态机包住请求 actor——turn 状态机直接调用 actor 并拥有重试/恢复多余机器层无状态可消费DDD 领域方法包装Generation Domain 等——改用 format/trait/provider 分层单一跨协议 trait 大杂烩旧 ProtocolTrait——改为每协议类型化 trait由 requester 请求管线组合把 trait 绑进 formatcreateOpenAIFormat(trait)闭包或作为 formatRequest 选项传递 hook——requester 管线显式交替 format 阶段与 trait hook两侧只共享contract.ts中性类型函数式toWireMessage/WireAdapter命名——用 adapter 接口名字里没有 Wireprovider 注册表 /defineProvider——createProvider直接导出 const出口处把 system 消息从原位置提升——system 消息留在历史原位、原位转换llm 发射{message, meta}Context 对象——meta 属于 turn 域llm 只发事件accumulator 在 llm 与 turn 各实现一份——accumulator 仅由 turn 持有、由事件流喂养beta 特性无限 fallback——协议拆分为anthropic/anthropic_beta未指定即不发送误配置即报错需要 beta 特性的 provider 必须显式使用anthropic_beta协议。十一、小结从一次请求看完整架构把整条链路串起来看llm模块的可复用性来自四组清晰边界关注点归属源码位置请求/响应编解码、流解析format协议层protocol/format.tsprovider 定制 hook每协议 trait各 bases/*/trait.ts请求管线组合format 阶段 × trait hookrequesterbases/openai/requester.tsendpoint/env、默认头connectionprotocol/connection.ts错误分类requester 选项 / format 边界errors.ts重试/恢复策略纯函数retry.ts / recovery.ts由 turn 驱动requester/retry.ts凭证解析与刷新credentialProvider 贡献点requester/requester.ts模型/目录provider provider-catalogprovider/definition.ts、provider-catalog.ts媒体media 贡献点media这套设计把协议差异format、厂商定制trait、请求组合requester 管线、失败处理turn 驱动的重试/恢复彻底解耦同时通过事件即契约 无状态核心 显式错误优先保证了流式请求的可恢复性与行为确定性。若要在 agent-core-v2 之外复用或扩展 LLM 请求能力llm.md 与其对应源码是最完整的起点——所有可变点都已声明为贡献点新增一个协议或 provider 不需要触碰 turn 层。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐DeepSeek Harness 中 LLM 暂时性请求失败的有界恢复LlmFailure、dsh-llm-retry 与按提供方路由的重试策略DeepSeek Harness 中 LLM 暂时性请求失败的有界恢复 LlmFailure 、 dsh llm retry 与按提供方路由的重试策略 本文以人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 有界 LLM 请求恢复机制解析LlmFailure、dsh-llm-retry 与停滞流超时的完整实现DeepSeek Harness 有界 LLM 请求恢复机制解析LlmFailure、dsh llm retry 与停滞流超时的完整实现 本文基于仓库内架构决人工智能AI AgentAgent 框架DeepSeeknew-api RelayKit 实战指南四大 LLM 文本协议的 DTO 与请求/响应/流式转换库new api RelayKit 实战指南四大 LLM 文本协议的 DTO 与请求/响应/流式转换库 RelayKit 是从 new api https://后端API网关LLM 网关大模型认证鉴权桌面应用上一篇Google Cloud Storage 存储桶架构化 Terraform 配置指南从 Draft Plan 到 google_storage_bucket 完整映射实践下一篇TensorRT 11 C Runtime 部署实战用现代 Runtime API 加载并运行 .plan 引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
