模型接入：统一服务、适配器与重试策略

llm 定义共享消息和流事件，适配器负责供应商协议与路由能力，llm-retry 执行适配器给出的重试策略。Session 记录实际输入与尝试结算，AgentLoop 承担同一步重新请求的协调。

模型协议适配与 Agent 重试协作

箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。

文字关系说明与章节链接

AgentLoop →（共享调用入口）→ llm；llm →（路由与映射）→ LLM adapters；llm-retry →（错误恢复）→ AgentLoop；LLM adapters →（适配器重试策略）→ llm-retry；llm-retry →（重试记录）→ Session；LLM adapters →（供应商协议）→ Model provider。

AgentLoop · llm · LLM adapters · llm-retry · Session · Model provider

llm 服务连接消费者与供应商适配器

dsh-llm 提供 ctx.llm，是普通对话、压缩摘要等模型调用共同使用的入口。AgentLoop 交入准备好的请求，适配器把统一消息转换成提供者协议，再把响应转换回来。

dsh-llm · 接口摘录，省略上下文 · ctx.llm.stream · packages/llm/llm/README.md

// AgentLoop 或摘要器发起单次提供者尝试，消费流片段并收到一个终止 finish。
for await (const chunk of ctx.llm.stream({
  provider: 'deepseek-official',
  model: 'deepseek-v4-flash',
  messages: [{ role: 'user', content: [{ type: 'text', text: '解释启动方式。' }] }],
})) { /* 处理片段 */ }

dsh-llm-deepseek-api-key 与 llm-deepseek-account 分别处理官方路由的不同身份方式，llm-pi-ai 支持其配置的其他路由。提供者选择、模型能力和凭据配置共同决定能否实际调用，名称出现在界面目录中不等于任意入口都采用同一校验策略。

dsh-llm · 接口摘录，省略上下文 · ctx.llm.listProviders() · packages/llm/llm/README.md

// 模型选择器读取已注册路由，结果按注册顺序排列。
const providers = ctx.llm.listProviders()

消息、流事件与尝试记录各有表示

LLM 公共词汇包含带类型的文本、推理、工具调用等内容块，工具结果以独立消息表达。适配器发出的 StreamChunk 服务于实时展示和当前请求聚合，终止时要给出明确 finish；AgentLoop 才把结算结果交给 Session。

某些提供者需要私有重放信息，这些信息绑定对应 provider/model，不能无条件移植到另一模型。冻结后的请求也不允许后续插件修改，否则日志与实际发送内容会分离。

重试插件接入 Agent 的失败恢复

dsh-llm-retry 监听 agent/request-error，在仍打开的 turn 内重跑失败步骤。它先记录 llm/retry，再等待退避，开始前记录 llm/retry-started，因此重试安排可在日志中观察。

dsh-llm-retry · 接口摘录，省略上下文 · agent/request-error · packages/llm/llm-retry/README.md · llm/retry-started · packages/llm/llm-retry/README.md

// 重试插件按最终适配器策略处理步骤失败，在同一未结束回合中请求重跑。
'agent/request-error'

// 重试插件在真正开始重试前记录事件，使已安排等待与实际再次尝试可区分。
'llm/retry-started'

直接调用 ctx.llm.stream 的消费者仍是单次尝试，因为原始流无法自行区分已经发出的内容该如何持久结算。重试不会把失败片段和内部延迟作为新的模型消息，且每次尝试都可能产生新的提供者费用。

供应商策略限定重试与取消

重试插件本身无独立配置，策略属于提供者。固定版本省略 retryPolicy 时采用 normal：对空响应、限流、服务端、超时和传输错误允许五次重试，退避从五百毫秒到十秒并带抖动。

always 模式先让下游恢复处理，再持续尝试到成功、取消或卸载。取消会中断退避并等待已委托恢复收敛；没有选定最终适配器的失败无法猜测提供者策略，超出正常预算或不符合类型的失败交给后续处理。

辅助示例

模型在总结 README 时遇到限流：适配器返回可分类失败，llm-retry 记录计划并按策略等待，再让 AgentLoop 从同一持久历史重跑步骤。用户在等待中取消，退避停止，系统不再发送后续重试请求；文件读取结果继续使用原有工具结果记录，无需转为新用户消息重发。

设计取舍

统一词汇降低工具与提供者的耦合，步骤级重试保留可解释的历史；代价是适配器仍需维护各自的能力和重放细节。无限重试提高短暂故障下的继续机会，也扩大等待时间与费用，因此它是显式策略而非可靠性保证。

模型接入：统一服务、适配器与重试策略 ​

llm 服务连接消费者与供应商适配器 ​

消息、流事件与尝试记录各有表示 ​

重试插件接入 Agent 的失败恢复 ​

供应商策略限定重试与取消 ​