dsh-llm-auto-route：Provider 自动匹配与路由插件

dsh-llm-auto-route 是 DeepSeek Harness 的社区 Cordis 插件。它根据环境变量、Base URL、端口和模型名前缀，从已经由 dsh-llm-pi-ai 配置并注册的 route 中选择一个，并在首个可见输出前执行安全的失败切换。

本项目只实现路由策略，不实现 HTTP 协议、不携带 Provider SDK，也不注册 openai、anthropic、deepseek 等适配器 route。Provider、模型目录、凭证、流式协议仍由官方 @deepseek-ai/dsh-llm-pi-ai 负责。

这是社区项目，不是 DeepSeek Harness 官方包，也不代表官方背书。

要求

• Node.js >=22.19.0
• DeepSeek Harness 0.1.0-rc.5 或兼容的 0.1.x 版本
• 已配置目标 route 的 @deepseek-ai/dsh-llm-pi-ai

当前开发依赖按 npm 0.1.0-rc.6 companion packages 验证，同时保持对 rc.5 的 peer 兼容范围。

安装

pnpm add dsh-llm-auto-route

官方 base bundle 已包含 @deepseek-ai/dsh-llm-pi-ai。如果你手动组合插件，请先加载官方适配器，再加载本包；使用部署中原有的 DeepSeek Harness/Cordis composition 命令加载仓库内的 cordis.patch.yml。

这个 patch 只插入一个名为 llm-auto-route 的插件，不会新增或替换官方 Provider route。

先配置官方适配器

本插件的 route key 必须已经出现在 dsh-llm-pi-ai 的注册目录中。下面是官方适配器配置的简化示例：

- id: llm
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      deepseek:
        apiKeyEnv: DEEPSEEK_API_KEY
      openai:
        apiKeyEnv: OPENAI_API_KEY
      anthropic:
        apiKeyEnv: ANTHROPIC_API_KEY
      ollama:
        baseURL: http://127.0.0.1:11434/v1
        api: openai-completions
        models:
          - id: llama3.1
            contextWindow: 131072
            maxTokens: 8192
      vllm:
        baseURL: http://127.0.0.1:8000/v1
        api: openai-completions
        models:
          - id: local-model
            contextWindow: 32768
            maxTokens: 4096
      openai-compatible:
        apiKeyEnv: GATEWAY_API_KEY
        baseURL: https://gateway.example.test/v1
        api: openai-completions
        models:
          - id: gateway-model
            contextWindow: 65536
            maxTokens: 8192

官方适配器拥有凭证、模型元数据、传输和流转换；自动路由插件只读取 route 目录并返回其中一个 route key。

自动选择规则

自动请求使用 provider: auto；当插件配置中的 provider token 是 auto 时，也可以省略 provider：

const options = {
  provider: 'auto',
  model: 'deepseek-chat',
  messages,
}

默认且固定的匹配顺序是：

explicit → provider_env → base_url → model_prefix

• 非 auto 的显式 Provider 永远保持不变，不会被静默改写。
• DEEPSEEK_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY 只作为检测信号；日志不会输出 key 值。
• LLM_BASE_URL 选择通用 openai-compatible 规则；端口 11434 识别 Ollama，8000 识别 vLLM/OpenAI-compatible 本地端点。
• deepseek-*、gpt-*、o1-*、o3-*、o4-*、claude-* 提供模型前缀提示。
• 候选 route 必须已经由官方适配器注册。
• 同一匹配阶段和同一优先级出现并列候选时返回 AMBIGUOUS_ROUTE，不会猜测。
• 请求缺少 model 时，只有匹配规则定义了 defaultModel 才会补默认模型。

每次选择都可以解释，且不暴露凭证：

已选择 deepseek/deepseek-chat；原因：发现 DEEPSEEK_API_KEY

如果环境中同时存在多个 key，请显式指定 provider，或用 route priority 做确定性决策。

配置

仓库提供的 patch 已包含默认规则；应用可以在 Cordis 配置中覆盖：

provider: auto
precedence:
  - explicit
  - provider_env
  - base_url
  - model_prefix
healthCheck:
  mode: adaptive       # off | adaptive | probe
  timeoutMs: 3000
  cacheTtlMs: 30000
failover:
  enabled: true
  maxAttempts: 3
diagnostics: info      # silent | error | info
routes:
  deepseek:
    apiKeyEnv: DEEPSEEK_API_KEY
    defaultModel: deepseek-chat
    priority: 10
  openai-compatible:
    apiKeyEnv: GATEWAY_API_KEY
    baseURLEnv: LLM_BASE_URL
    modelPrefixes: [gateway-]

Route 字段只是匹配提示，不是适配器配置：

字段	含义
provider	返回的已注册 route id，默认使用 routes 的 key。
apiKeyEnv	非空环境变量，作为 Provider 环境信号和 discovery 凭证来源。
baseURL / baseURLEnv	精确或用户提供的端点提示；baseURLEnv 支持未知域名的 OpenAI-compatible 网关。
baseURLPatterns	额外的规范化 URL 前缀。
ports	本地端口识别提示。
modelPrefixes	模型 ID 前缀。
defaultModel	请求不指定 model 时使用的默认模型。
priority	同一匹配阶段的并列决策，数值越大越优先。

不要在路由配置中直接写 API Key。让官方适配器使用凭证引用（通常是 apiKeyEnv），并让本插件的检测变量名与它保持一致。

健康检查与失败切换

adaptive 模式优先复用官方 dsh-llm model-discovery 接口，并提供超时和内存缓存。如果当前 Harness 版本或 Provider 无法提供 discovery，则退回 route/model 解析，并把真实 stream 作为最后的可用性检查；off 完全跳过预检；probe 在适配器提供 discovery 时主动探测。

失败切换有意保持保守：

• 只有在输出文本、推理、工具调用或 block 内容之前才允许切换；
• 失败尝试已经产生的协议元数据会被丢弃，不会拼接到下一个 Provider；
• 用户取消、显式 Provider、配置错误，以及已经产生首个输出的请求都不会重试；
• 后续 Provider 永远不会收到前一个 Provider 的半截 assistant 响应。

插件监听 agent/request、agent/request-error 和 llm/stream，返回新的不可变请求配置，不修改被冻结的对象。

公共 API

包导出 AutoRouteConfig、RouteRule、RouteDecision、MatchStage，以及无副作用的 normalizeConfig、normalizeBaseURL、resolveRoute：

import { normalizeConfig, resolveRoute } from 'dsh-llm-auto-route'

const decision = resolveRoute(normalizeConfig(), {
  model: 'deepseek-chat',
  env: { DEEPSEEK_API_KEY: 'present' },
  registeredProviders: new Set(['deepseek']),
})

if (decision.kind === 'matched') {
  console.log(decision.candidate.provider, decision.candidate.model, decision.stage)
}

AutoRouteError.code 提供稳定错误码：AMBIGUOUS_ROUTE、MISSING_MODEL、NO_CANDIDATE、NO_REGISTERED_ROUTE。

故障排查

NO_REGISTERED_ROUTE：本插件有默认提示，但 ctx.llm.listProviders() 中没有对应 route。请在官方适配器的 providers 下使用相同 key。

AMBIGUOUS_ROUTE：多个候选在同一阶段、同一优先级命中。显式指定 provider、移除无关环境变量，或提高一个 route 的 priority。

MISSING_CREDENTIAL / INVALID_CREDENTIAL：检测变量名和官方适配器变量名不一致，或变量为空。日志和 issue 中不要粘贴变量值。

本地网关没有被选中：设置 LLM_BASE_URL，或者提供包含 11434（Ollama）/8000（vLLM）的 URL。官方适配器仍必须配置相同 route 和模型目录。

没有发生重试：如果已经产生文本、推理、工具调用或 block 输出，发生取消，使用了显式 Provider，或错误属于配置错误，这是预期行为。继续重试可能造成重复回答或半截响应拼接。

兼容性与项目状态

这是面向 DeepSeek Harness 开发者预览版的独立生态插件，遵循上游关于社区插件、dsh-plugin topic、Discussions 公告和独立仓库的建议。不向官方 Harness 仓库创建外部 PR。

上游参考：

• dsh-llm-pi-ai README
• LLM 接口
• 流式调用与路由扩展点
• 贡献指南

许可证

MIT，见 LICENSE。