dsh-router-core

dsh plugin --profile web add dsh-router-core

<h1 align="center">dsh-router</h1>

<p align="center">DeepSeek Harness 的 OpenAI 兼容路由插件</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-router-core"><img src="https://img.shields.io/npm/v/dsh-router-core?style=flat-square&logo=npm&label=npm" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="MIT license"></a>

<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="DSH 0.2.0" src="https://img.shields.io/badge/DSH-0.2.0-4d6bfe?style=flat-square" /></a>

<a href="#agent-team-支持"><img alt="Agent Team" src="https://img.shields.io/badge/Agent%20Team-%E2%9C%93-10b981?style=flat-square" /></a>

</p>

<p align="center">

<a href="#快速安装">快速安装</a> ·

<a href="#面板设置--路由">面板</a> ·

<a href="#agent-team-支持">Agent Team</a> ·

<a href="#api-端点openai-兼容v1">API 端点</a> ·

<a href="docs/suppliers.md">供应商开发</a> ·

<a href="docs/ext.md">扩展开发</a>

</p>

直接把 DSH 变成一个多协议、多供应商的模型网关 —— 不是另开一个网关服务,

而是作为插件嵌进 DSH web,在宿主 Web 服务上原生暴露四个端点,把请求路由到内部供应商。

管理界面在设置 → 路由(官方设置页座位,不是自己开的页面)。装好即用:

不另起进程、不占第二个端口、不用在网关和 DSH 之间搬配置。

四种协议双向互转(详见 [四种协议入口](#四种协议入口)):

端点 · 客户端 · 协议

POST /v1/chat/completions · OpenAI SDK / Cline / DSH 自身 · OpenAI Chat Completions

POST /v1/messages · Claude Code · Anthropic Messages

POST /v1/responses · Codex · OpenAI Responses

POST /v1beta/models/<m>:generateContent · Gemini CLI · Google Gemini

四个入口共享同一套鉴权、账号池、组合回退与用量统计。把 Claude Code 的

ANTHROPIC_BASE_URL 指过来,它用的就是你的账号池;Codex、Gemini CLI 同理。

供应商侧也可以说这四种里的任意一种 —— 声明一下方言,核心负责翻译。

原生支持 Agent Team / 多会话 —— team 的每个成员是独立会话,

dsh-router 按会话身份亲和选号:同会话固定落同一个连接(前缀缓存只写一份),

不同会话尽量铺开到不同连接;多会话共用同号时按会话隔离统计,不会互相拖累。

详见 [Agent Team 支持](#agent-team-支持)。

快速安装

需要 DSH 0.2.0 及以上、Node.js >= 20,以及 web profile。0.1.x 宿主不再支持(设置注册、

tool 消息形态都已按 0.2.0 单面实现)。

dsh plugin --profile web add dsh-router-core

然后重启 dsh web。打开设置面板,左侧导航「模型」下面会出现 路由。

第二处入口是侧栏的插件面板:内置的供应商与扩展在那里各占一行「包含的组件」,

供应商与扩展的开关也在那一面(见 [面板](#面板设置--路由)与

[供应商开关](#供应商开关))。

更多供应商:DSH 插件形态的供应商各自发 npm 包,同样

dsh plugin --profile web add <包名> 即可;供应商接入与开发见

[docs/suppliers.md](docs/suppliers.md)。

本地开发版:不用 npm,直接 dependencies 加

"dsh-router-core": "link:/path/to/dsh-router" 指向本地仓库。

它解决什么问题

能力 · 说明

零额外进程 · 就是 DSH 插件,随 dsh web 启停,天然同源(/router/api/* 无 CORS、面板嵌在设置里)。

四协议互转 · Chat / Anthropic / Responses / Gemini 进站出站都认,Claude Code、Codex、Gemini CLI 直接接上来就能用账号池。供应商侧也只需声明方言,翻译在核心统一做。

扩展即插即拔 · 扩展插件(如 dsh-router-ext-rtk)经 router.ext 注册,在 bash 执行前改写命令(如加 rtk 前缀压缩输出)。开关在官方插件页(设置 → 插件 → dsh-router-core),带自检;面板「扩展」页只列已启用的、只读。

供应商即插即拔 · 内置供应商是插件页「包含的组件」里的三行,可单独开关;更多供应商 = 装一个 DSH 插件(dsh-router-*)或放一个 js 文件到 ~/.dsh/profiles/web/suppliers/(同名 js 覆盖内置)。

模型不内置 · 供应商只实现差异化能力,模型拉取与缓存由核心统一管,不写死、不过时。

策略只写一次 · 组合回退、账号池(选号/冷却/禁用)、响应写入、凭证存储、积分持久化、模型管理都由核心提供。供应商 js 只对单个账号调一次上游并报告成败,不自己遍历账号、不维护冷却表、不落盘积分——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。

凭证单库 · auths/credentials.sqlite,供应商凭证不透明 blob,核心统一生命周期,干净可备份。

组合即模型 · 建好的组合自动带出为 DSH 模型目录里的 router provider 选项,设置 → 模型直接选组合名即可。

用量可观测 · 面板概览看板:周期切换、汇总卡、趋势折线、Top 榜、最近请求。

Team 友好 · 按会话身份亲和选号:同会话固定同一连接(前缀缓存只写一份),不同会话尽量铺开到不同连接;多会话共用同号时缓存质量按会话隔离统计,不会互相拖累。

供应商开发与接入规范见 [docs/suppliers.md](docs/suppliers.md)

（契约 / 加载顺序 / 模型统一策略 / 内置供应商参考实现）。

选号/亲和/team 的完整设计与实测见

[docs/pool-sticky-block.md](docs/pool-sticky-block.md)。

Agent Team 支持

DSH 的智能体团队把任务拆给多个成员,每个成员是独立会话,一轮

team 测试就是多个会话交错发请求。dsh-router 原生适配这个场景:

• 真会话身份 —— 从宿主 GenerateOptions.sessionId 拿到权威会话 id

(adapter 转成内部头),不再靠猜。有 id 就按 id 亲和,精确、零撞车;

外部 OpenAI 客户端拿不到 id 时,回落前缀指纹兜底。

• 会话亲和选号 —— 同一会话的连续请求永远落回同一个连接,前缀在该

连接缓存里只写一份,缓存命中率稳定在 ~98%;新会话按游标分发,天然均衡。

• fresh 会话优先铺开 —— 多个成员交替到达时,优先分配到**还没被别的会话

占用**的连接,各成员尽量独占一个连接;连接数不够时才回绕复用。

• 按会话隔离的缓存统计 —— 多会话共用同号时,各会话的缓存质量分开统计,

不会因为别的会话"踩"了同一个号就把这个号误判成"缓存坏了"从而集体降权

(消除了 team 场景下的「降权串」)。

• 底部命中指示 —— 输入框旁的「路由」徽章按当前会话显示最近一次命中

的连接/积分;点击展开卡片,点外部或 Esc 收

…(truncated)