免费模型聚合路由 dushaobindoudou/dsh-freeroute

dsh-freeroute

DeepSeek Harness（dsh）的免费模型聚合代理：注册 freeroute 模型提供方，聚合多家免费额度上游（OpenCode Zen / B.AI / OpenRouter / SenseNova 四家内置，外加远程目录与自定义网关；其余厂商经远程目录接入）。配好任意一家 API Key 即可用；上游失效时在出字前自动切换，对会话透明；另提供本地 OpenAI 兼容端点。

"免费"指各家正规的免费额度，密钥由你自己注册提供。本插件不做共享号池，也不会绕过付费 API。

密钥管理

- 多 Key 轮换：免费额度按账号计，每个上游支持最多 8 把 Key（编辑框里用换行/逗号分隔，或环境变量 KEY_2…KEY_8）。鉴权 / 限流失败只冷却这一把 Key 并自动换下一把，不会连累上游整体。当前这把不失效就一直用它（同账号连续请求，上游提示词缓存也能命中），失效后换到的新 Key 同样一直用下去。「这款模型只对某些客户端/地区/套餐开放」这类 403 属于模型级门禁：不换 Key、不冷却上游，只把这款记 30 分钟、期间直接跳过。
- 默认掩码：密钥框隐藏态是不可编辑的 •••••• 掩码，点「显示」才打开编辑器并预填完整 Key 环（一行一把，可直接编辑）；保存后自动回到掩码态。
密钥只经 credentials 服务存取，绝不以明文写入配置。
- 失效可见：轮换中检测到某把 Key 失效时，面板会提示 「第 N 把 Key 失效」（哪一把、什么原因），坏账号一眼可见，不必翻日志。

原理

1. 适配器注册：llm.registerAdapter(['freeroute'], adapter) 注册成 dsh 模型路由。模型选择器出现 freeroute/auto（自动故障转移）与 freeroute/<上游id>/<模型id>（指定模型）。
2. 请求翻译：dsh 内部消息 ⇄ OpenAI Chat Completions SSE；reasoning、 tool_calls、usage 全量透传。密钥只经 credentials 服务存取。
3. 健康与故障转移：失败按类别冷却（鉴权/配置 10 分钟、限流 60 秒、其他指数退避封顶 10 分钟）。auto 的候选链分四层：锚点模型（「多少家上游都有这款模型」的交集家数最多者，目录声明的 quality 只在打平时裁决）在各家装得下本次会话的提供方，窗口大的在前（同款换厂商，能力不变、最无损）→ 窗口不低于链首的其他模型 → 装得下本次会话的其他模型 → 其余兜底（沉底不删除）。窗口按每一家的实际值判断，同款模型在不同网关的窗口可能差很多。未出字的请求失败即切下一家（含空响应检测），已出字的直接抛错。上游 90 秒内没吐出首个 token （排队、只发心跳）也视为失败并切下一家（链上最后一个候选放宽到 600 秒），首 token 慢的提供方在所在层内沉底；已出字后只要内容还在流就不中断，连续 120 秒没有新内容才中止。
环境变量 FREEROUTE_FIRST_TOKEN_SECONDS（0 关闭）/ FREEROUTE_CONTENT_IDLE_SECONDS 可调整。Key 在鉴权/限流失败时单独轮换，并把失效的那一把提示到面板。
4. 配置三层合成：内置目录 → 远程目录（Cloudflare 托管 JSON，免发版更新；兼容 native 格式与 models.dev api.json，自动筛 0 成本模型）→ 用户 patch （free-proxy 设置命名空间持久化）。
5. 本地端点：/freeroute/v1/chat/completions + /freeroute/v1/models，任意 OpenAI 工具指向它即用同一套免费池。
6. 全局代理（默认关闭）：设置 → 模型 → 免费 → 高级设置 里配置一条 http://127.0.0.1:7890 型代理，所有未单独配置代理的上游（对话请求与模型探测）自动走它；上游自定义或目录声明的 proxy 优先于全局；远程目录同步始终直连。大陆网络用户把 Clash/v2ray 端口填一处即可，无需逐个上游配置。

设置面板

dsh 内置的 设置 -> 模型 页被可逆地包装增强：标题与介绍保持原位，
介绍之后多一排 「默认 | 免费」页签（结构对齐「设置 -> 插件」页：下划线页签、aria 角色、方向键导航、访问过的面板保持挂载）：

- 默认：原有模型设置原样保留；
- 免费：完整 freeroute 面板，形态与「设置 → 插件」页一致——每家上游一张可展开卡片（卡片头：名称 + 状态摘要 + 优先级 + 启停开关，点击就地展开密钥 / 连通测试 / 探测模型 / 申请链接），「模型」与「高级设置」（全局代理 + 远程目录）也是同款卡片。

设置导航里没有独立的 freeroute 平级项（仅当宿主没有可包装的模型页时才退回独立设置页）。/freeproxy 命令输出文本状态。

每条回复的模型标注

auto 模式下界面上只显示「⚡ Auto」，看不出这一条到底是谁答的。现在每条回复的 时间右侧（13:17 之后）多一个小标签 ⚡ <实际服务模型>，悬浮显示上游名与请求模型（auto）；动作行沿用宿主的 hover 显隐，不新增交互。故障转移换过上游时，一眼就能看出这一条落到了哪家、哪个模型。

归属只存宿主内存、不写会话日志（dsh 的持久化读路径拒绝未登记的事件类型），所以 dsh web 进程重启后，历史消息不再显示标签；新消息不受影响。

让其他 Agent / 工具接入（一直用 auto）

dsh web 启动后，本插件在同一端口上暴露一个 OpenAI 兼容端点，任何
支持自定义 base URL 的 agent / 工具都能直接复用这套免费池：

- Base URL：http://127.0.0.1:<dsh web 端口>/freeroute/v1 （默认端口 3080；免费面板底部也显示当前完整地址）
- API Key：不需要。端点仅监听本机回环；某些工具强制要求非空 Key，随便填占位符即可（如 sk-freeroute）
- 模型：填 auto 或干脆不传（默认就是 auto）——按优先级自动选已启用的免费上游，失败 / 限流 / 首 token 中断时全链自动切换，单模型失败自动降级为链式 fallback，无需人工干预
- 能力：stream、tools（function calling）、stop、temperature、 max_tokens 均透传；CORS 已开放，浏览器内插件可直连
- 健康检查：GET /freeroute/health；模型列表：GET /freeroute/v1/models （第一项就是 auto）

curl 示例（最简，不带 model 即 auto）：

curl http://127.0.0.1:3080/freeroute/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"messages":[{"role":"user","content":"你好"}]}'

常见工具配置：

| 工具 | 配置 |
| OpenAI SDK | baseURL: 'http://127.0.0.1:3080/freeroute/v1'，apiKey: 'sk-freeroute'，model: 'auto' |
| Codex CLI | ~/.codex/config.toml 里 model_provider 指向该 base URL（wire_api = "chat"） |
| Cline / Roo / Continue | OpenAI Compatible，Base URL 同上，模型名 auto |
| 任意 OpenAI 兼容网关 | 把本端点作为上游挂进 uni-api / new-api / LiteLLM 即可 |

注意：端点随 dsh web 进程存活（同机使用）；至少在免费页签给一个上游配好 Key，auto 链才有可用节点。

安装

dsh plugin --profile web add dsh-freeroute

要求：Node.js ≥ 18；宿主提供 llm / timer；settings / credentials / subprocess / webServer / commands / agentDefaultModel 缺失时优雅降级。

开发

分层源码（详见 src/README.md）：

- src/ 是唯一手改入口，按层拆片：src/host/（20 片：常量 → 目录解析 → 上下文/状态 → 密钥/探测/模型/健康 → 传输/路由/HTTP → 接管/RPC/命令/端点/ 启动）、src/client/（10 片：样式/上下文 → 面板状态/头部/上游/高级/模型 → 模型页/集成/插件尾）。
- npm run build:dynamic 把 src/* 装配成 freeroute-dynamic/ {host,client}.js（动态加载器要求的单函数体形态，版本号从 package.json 注入）。
- freeroute-dynamic/ 带集成测试 137 项： node freeroute-dynamic/test/integration.mjs。
- npm run build:static 从装配产物机械生成 lib/（RPC 层替换为 Typert Remote + Connection 载体），请勿只手改一侧；build:static 会先跑 build:dynamic。
- npm run lint && npm test：lint + 真实 cordis 根上的冒烟测试。
- 模块同一性：@deepseek-ai/dsh-typert-protocol 必须与 dsh 宿主解析到同一份物理副本。宿主网关从它自己那份模块私有的 WeakMap 读取 Remote 方法标记；插件 workspace 自带 pnpm 副本时标记记进了另一份 WeakMap，网关一个方法都扫不到，/api/freeroute/ 静默注册不上（客户端看到 HTTP 404，服务端无任何报错）。v0.7.3 起 lib/index.js 在加载时直接锚定宿主自己的副本（运行中的 dsh CLI 入口 → 全局 npm 布局 → 回退），不再依赖 postinstall、软链或宿主版本。旧版本若出现 transport failure for /api/freeroute/state: HTTP 404，升级到 ≥0.7.3 即永久修复。

诚实的边界

本插件聚合的是「你自己注册的免费额度」。若需多租户 / 计费 / 渠道管理，建议自建 uni-api、new-api 或 LiteLLM，再把它的地址作为本插件的自定义上游接入——两者互补，不重复造轮子。

Web 面板（可选）

lib/client.js 会在 dsh web 设置里注册「免费模型」分区，排行与命令一致，点击即设默认。dsh 的 web 前端是预构建产物，面板需要在 dsh-web-frontend 的 client bundle 里加入本包并重新构建才会出现； free-models-preview.html 是独立镜像预览（把仓库根目录起个 HTTP 服务再打开即可），无需重新构建前端。

License

MIT © dushaobindoudou