Jesse-njx/dsh-polyglot

dsh-polyglot

DSH 的模型切换器。 将 DeepSeek Harness 指向任何 OpenAI 兼容的
端点——内置精选的免费和廉价 DeepSeek 提供商预设，并在免费额度触发速率限制时
自动回退。

claude-code-router 之于 Claude Code，正如 dsh-polyglot 之于 DSH——不同之处在于
DSH 的 ctx.llm 是一个受认可的扩展接缝，因此无需请求拦截：
通用适配器和路由器都是真正的 LlmAdapter 注册。

- 一个通用适配器。 单个 OpenAI 兼容的 ctx.llm 适配器，
由 {baseUrl, apiKey, model, headers?, quirks?} 参数化。流式传输、
工具调用和用量提取均已处理；各提供商的差异
（推理字段名、严格的工具 schema、缓存折叠的用量）都是小的
声明式 quirks 标志，而非针对每个提供商的代码。
- 带回退的路由器。 遇到 429 / 配额超限 / 5xx（或缺少
密钥）时，失败的提供商会标记为冷却中（指数退避，
遵循 Retry-After），请求会在链中的下一个提供商上重试。
免费额度会不断触发速率限制——自动故障转移正是
整个产品的核心。
- 提供商预设即数据。 presets/.json——社区 PR 无需改动适配器即可
添加提供商。每个预设都带有 verifiedAt 和免费额度
说明，让失效一目了然。
- 可见的用量。 每次尝试都会以
polyglot/served 记录到仅追加的会话日志中；/polyglot usage 按提供商统计
token 数量和根据预设定价估算的成本。

快速开始

将 bundle 安装到某个 profile 中（DSH profile 是一组有序的
plugin-bundle 补丁层栈）：

dsh plugin --profile web add @dsh-polyglot/bundle

该 bundle 的补丁会注册 polyglot 插件，并采用推荐的
默认链——“整天免费写代码，直到某处触发速率限制，然后
优雅降级到最便宜的付费选项”*：

nous-portal → opencode-zen → deepseek-official (5M grant) → kilo

通过凭据接缝配置密钥（web 的 Models 页面会写入它们），
或导出每个预设声明的环境变量名：

export NOUS_PORTAL_TOKEN=...      # nous-portal (bearer, manual token for v0.1)
export OPENCODE_API_KEY=...       # opencode-zen
export DEEPSEEK_API_KEY=...       # deepseek-official (new accounts: 5M free tokens, 30 days, no card)
export KILO_API_KEY=...           # kilo (paid fallback rung)

在模型选择器中选择虚拟提供商 polyglot。未配置密钥的提供商会
被自动跳过——链会降级，而绝不会硬性失败。

日常命令

| 命令 | 作用 |
|---|---|
| /model | 显示各链及当前活动链 |
| /model  | 在会话中途切换活动链（记录为 polyglot/chain） |
| /polyglot | 状态：活动链、条目、提供商冷却情况 |
| /polyglot usage | 从会话日志按提供商统计：调用次数、成功/失败、token 数、预估成本 |
| /polyglot presets | 活动链各预设的免费额度状况 |
配置

从你的 profile patch 中覆盖 chains 和 cooldown：

your profile's cordis.patch.yml (or --patch overlay)
- patch:
- id: polyglot
config:
chains:
default:
- preset: nous-portal
- preset: opencode-zen
- preset: deepseek-official
model: deepseek-v4-flash
- preset: kilo
paid:
- preset: deepseek-official
model: deepseek-v4-pro
cooldown:
baseMs: 30000        # initial per-provider cooldown after a failure
maxMs: 900000        # ceiling (also honors provider Retry-After)
factor: 2            # exponential growth per consecutive failure
jitterRatio: 0.1     # symmetric jitter around each delay

逐条目覆盖：provider（路由名称）、model、baseUrl、apiKeyEnv、
headers、quirks —— custom preset 是用于
vLLM/Ollama/SGLang localhost 以及任何其他 OpenAI 兼容端点的逃生舱
（包括 Qwen/GLM/Kimi 官方 API）。

Quirks 参考

| 标志 | 默认值 | 含义 |
|---|---|---|
| reasoningField | 'reasoning_content' | 承载推理文本的 wire delta 字段；null 完全禁用推理 |
| maxTokensField | 'max_tokens' | 输出上限的 wire 字段（较新的主机使用 max_completion_tokens） |
| usage | 'standard' | 'deepseek' 会减去折叠进 prompt_tokens 的缓存命中；当主机不报告任何用量时使用 'none' |
| streamOptions | true | 发送 stream_options: {include_usage: true} |
| strictToolSchemas | false | 向工具 schema 添加 strict: true |
| thinkingField | false | 发送 thinking: {type}（DeepSeek 拼写） |
| reasoningEffortField | true | 为 high/max 档位发送 reasoning_effort |

Preset 注册表

所有数据均已于 2026-08-14 对照提供商文档重新核实；这些数据每周都会变动 —— 每个 preset 都带有 verifiedAt，而一个用 1-token 请求 ping 每个
baseUrl 的 CI 任务是计划中的信任闭环。

| Preset | 你能获得什么 | 费用 / 限制 | 备注 |
|---|---|---|---|
| deepseek-official | V4-Flash、V4-Pro | 每 M 美元 $0.14/$0.28（Flash）；新账户赠送 500 万免费 token，30 天，无需信用卡 | 基线；价格呈上涨趋势 |
| opencode-zen | deepseek-v4-flash-free（+ Qwen 3.6 Plus、MiniMax M3、MiMo……） | 免费，无需信用卡，200k 上下文；速率限制未记录 | 商业条款不明确 —— 已在 preset 的 notes 中标记 |
| nous-portal | deepseek/deepseek-v4-flash:free | 免费，需 OAuth 授权，有会返回错误的硬性速率上限 | 回退机制的典型代表；把它放在链的最前面 |
| kilo | V4-Pro、V4-Flash、V3.1 Terminus | 按量付费，不高于提供商费率加价 | 不错的付费回退层级 |
| openrouter | :free DeepSeek 变体 + 其他一切 | 免费变体受限流；付费按标价 | 目录最广，一个 key 搞定 |
| custom | 任何 OpenAI 兼容服务 | — | vLLM/Ollama/SGLang localhost；Qwen/GLM/Kimi 官方端点 |
| groq / together / fireworks | DeepSeek 托管 | 快但更贵 | 延迟升级，而非节省 |

工作原理

profile ──> provider route "polyglot"（路由器元适配器）
│  链：nous-portal → opencode-zen → deepseek-official → kilo
▼
ctx.llm.stream({provider: "nous-portal", ...})
│  每个真实路由对应一个适配器（OpenAiCompatAdapter，每个预设一个）
▼
POST {baseUrl}/chat/completions   (SSE, usage, tools)

路由器转发第一个完成的尝试。一个符合回退条件的失败若发生在任何内容流出之前——即免费额度上限的情形——会无缝切换到下一个提供商；而内容流出之后的失败无法撤回，会作为普通的错误结束呈现。每一轮实际由哪个提供商服务会持久记录在会话日志中（polyglot/served），因此 /polyglot usage 是对日志的纯折叠，而非插件侧的记账。

服务条款说明

免费额度通常被限制为评估用途（OpenCode Zen 的商业条款未有文档说明）。预设的 notes 会在配置时提示这一点——dsh-polyglot 不会悄悄洗白用量。

开发

pnpm install
pnpm typecheck    # 严格 TS
pnpm build        # tsc → lib/
pnpm test         # 56 个测试：带脚本化 429/500/ 的模拟 OpenAI 兼容服务器
流式场景、针对每种怪癖的黄金线路断言，以及
端到端 cordis 挂载，证明回退 + 会话事件

路线图

- v0.2 — 按角色的链（planner → 付费 V4-Pro，executor/summarizer →
免费 Flash）；Nous Portal 的 OAuth 设备流程；预设自动更新检查；
提供商基准测试/竞技场集成。
- 非目标 — 代理非聊天模态；悄悄洗白密钥。