多模型路由

一句话版：一个会话能用多个模型：不同任务走不同 provider/模型。能力来自多 provider 配置(llm-pi-ai 网关)+ 路由选择,而不是"自动切模型"插件。

一、核心:按 provider 区分模型

真实机制是按 provider 区分模型,不是 plan/execute 自动切换:

在 ~/.dsh/settings.yaml 的 llm-pi-ai.providers 配多个 provider(各自 apiKeyEnv/baseURL/models)
用 agent-default-model(部署默认,web / headless / API 入口共用)选 provider/model
会话内可在 Models 设置页按需选模型

别被误导:@deepseek-ai/dsh-plan-mode(/plan 命令)只维护规划协作状态 + 政策提示段,不切换模型、不做 plan/execute 双路由。多模型 = 多 provider 配置,不是切换。

二、两种 provider 形状

包	形状	用在哪
`llm-deepseek`	扁平顶层字段(单 provider)	官方 chat-completions
`llm-pi-ai`	`providers:` 字典(多 provider 网关)	接多个 OpenAI 兼容端点

配多个第三方便用 llm-pi-ai:

llm-pi-ai:
  providers:
    cpa:
      apiKeyEnv: CPA_API_KEY
      api: openai-completions
      baseURL: http://example.gw:8317/v1
      models:
        - id: gpt-5.6-sol
    another:
      apiKeyEnv: ANOTHER_API_KEY
      baseURL: https://another.endpoint/v1
      models:
        - id: some-model

三、路由选择:agent 级默认

# 各 agent 的默认模型
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash

agent-default-model 是各 agent 默认的 provider/model(@deepseek-ai/dsh-agent-default-model 要求两者),可被会话内 Models 设置覆盖。(api-gateway 是 host/client 的 RPC 网关,与模型路由无关,别把它当默认模型配置.)

四、provider 体系

类型	说明
官方 provider	`deepseek-official`(api.deepseek.com,chat-completions)
OpenAI 兼容	任意兼容端点(设置面板/llm-pi-ai 添加)
自定义网关	私有/代理端点(注意明文 HTTP 风险)
Web 搜索端点	独立 Anthropic 端点,复用主 key(`web-search-deepseek`)

两个认证边界容易踩坑：

纯 OAuth provider 不进入可选目录：llm-pi-ai 没有 credential store，也不执行登录/刷新流程；只有 OAuth、没有 API Key 的 route 会在请求前报 Provider is not configured。已存在的设置项仍保留以便编辑或删除。
provider-native discovery 只读进程环境：无 credential ref 的 route 由 provider 自己解析 AZURE_OPENAI_API_KEY、AWS_PROFILE、AWS_ACCESS_KEY_ID 等变量；它看不到 Harness 托管凭据，也不会仅凭 ~/.aws/credentials 自动选 profile。

五、发现模型

DSH 提供 endpoint 模型发现:ctx.llm.listModels(provider) / discoverModels(...) 询问某 provider 当前通告的模型(见模型路由)。Models 设置页用它在加 provider 时预填候选模型。

六、多模型的典型用途

场景	怎么做
官方模型干重活、便宜模型跑轻任务	不同 agent 设不同 `agent-default-model`
接自建网关/私有端点	`llm-pi-ai.providers` 加一个
Web 搜索走独立端点	`web-search-deepseek` 复用主 key、走 `anthropic/v1`(不复用主 baseURL)
会话内临时换模型	Models 设置页

七、验证

# 看注册的 provider
dsh web --dump-config | grep -iE "llm-|provider"
# 看一次请求实际路由(request/header)
zstdcat ~/.dsh/sessions/*/*/session.jsonl.zstd | grep "request/header" | tail -1

下一步

模型路由：ctx.llm / adapter / URL 请求机制
配置：provider 配置怎么落盘

一、核心:按 provider 区分模型​

二、两种 provider 形状​

三、路由选择:agent 级默认​

四、provider 体系​

五、发现模型​

六、多模型的典型用途​

七、验证​

下一步​