多账户调度器monotykamary/dsh-multiprovider

🔀 dsh-multiprovider

面向 DeepSeek Harness 的提供商中立多账户调度

_一个提供商身份，多个凭据，显式租约，以及运维可见的健康状态。_

checks
npm
DeepSeek Harness
license

dsh-multiprovider 让具体的提供商插件能够在同一个稳定的提供商/模型身份背后暴露多个 OAuth、API 密钥、服务账户或自定义凭据。它负责账户选择、亲和性、健康状态、冷却以及运维偏好。提供商插件继续负责身份验证、凭据存储、传输以及提供商特定的错误解释。

该包是一个原生 Cordis 服务和 DSH bundle，而不是第二个模型路由器。调用方为一次完整操作租用一个账户，对结果恰好结算一次，并在提供商语义使故障转移安全时显式重新获取。

为什么需要 multiprovider？

| | 能力 | 它能解锁什么 |
| :-: | --- | --- |
| 🔁 | 确定性选择 | 在同一个提供商路由背后支持轮询、加权、最少在途和优先级策略。 |
| 📌 | 会话亲和性 | 在所选账户仍然符合条件时，为相关请求稳定复用账户。 |
| 🩺 | 可见健康状态 | 冷却、失败类别和在途计数，且不暴露凭据材料。 |
| 🔐 | 提供商自有密钥 | 不透明的凭据引用保留在主机上，绝不进入浏览器快照。 |
| 🎛️ | 实时偏好 | 运维人员可在 DSH Settings 中启用、加权、设置优先级和重置账户。 |
| 🧩 | 原生组合 | Cordis 生命周期、DSH 设置和 Web 主机仍是唯一的运行时权威。 |

如何融入

flowchart LR
Request[Provider operation] --> Pool[ctx.multiprovider]
Pool --> Policy[Selection + affinity]
Policy --> Lease[Account lease]
Lease --> Provider[Concrete provider plugin]
Provider --> Outcome[Success / failure / cancel]
Outcome --> Health[Health + cooldown]
Health --> Pool
Pool --> Settings[Accounts settings]

逻辑提供商身份保持不变。内部账户 ID 和凭据引用不是模型路由，绝不能作为会话提供商 ID 持久化。

它提供什么

- 通过 ctx.multiprovider 进行动态提供商和账户注册
- 不透明的、提供商自有的凭据引用，绝不进入浏览器快照
- 具有在途记账的幂等账户租约
- 轮询、平滑加权轮询、最少在途和优先级策略
- 可选的会话/工作负载亲和性
- 针对显式故障转移循环的每次尝试账户排除
- 归一化的速率限制、配额、认证、瞬态和致命故障健康状态
- 可配置的冷却时间，带瞬态指数退避
- 通过 DSH 设置实现实时、持久的启用/权重/优先级/策略偏好
- DSH 设置模态框中专用的 Accounts 部分
- 同源、仅限回环、无密钥的设置端点

逻辑提供方身份保持不变。内部账户 ID 和凭据引用不是模型路由，绝不应作为会话提供方 ID 持久化。

安装

要求：Node.js ^22.19.0 || >=24、此检出使用 pnpm 11，以及 DeepSeek Harness ^0.1.1。

该包已包含在经测试的 DSH 发行版中。要将其显式添加到另一个配置文件：

pnpm dlx @monotykamary/dsh@latest plugin --profile web add dsh-multiprovider

对于本地开发，构建此检出并添加其绝对路径：

pnpm install --frozen-lockfile
pnpm run check
pnpm dsh plugin --profile web add link:/absolute/path/to/dsh-multiprovider

该 bundle 补丁会安装 multiprovider 服务。具体的提供方集成会注入该服务，并保留对注册、刷新、存储和传输的所有权。

提供方集成

1. 注册提供方清单

凭据引用对此包是不透明的。它们可以是 DSH CredentialRef 值、凭据记录键、提供方拥有的文件句柄，或其他非密钥定位符。

import type { Context } from '@monotykamary/cordis'
import type {} from 'dsh-multiprovider'

export function installAccounts(ctx: Context) {
ctx.inject(['multiprovider'], (mctx) => {
mctx.effect(() => mctx.multiprovider.registerProvider({
id: 'anthropic',
label: 'Anthropic',
managementHint: 'Add and remove keys in the Anthropic provider settings.',
accounts: async () => [
{
id: 'work',
label: 'Work key',
authKind: 'api-key',
credentialRef: { kind: 'record', key: 'anthropic/work' },
weight: 3,
metadata: { organization: 'Work' },
},
{
id: 'personal',
label: 'Personal key',
authKind: 'api-key',
credentialRef: { kind: 'record', key: 'anthropic/personal' },
},
],
classifyFailure: (error) => {
const status = (error as { status?: number }).status
if (status === 429) return { kind: 'rate-limit', retryable: true }
if (status === 401 || status === 403) return { kind: 'auth', retryable: true }
if (status !== undefined && status >= 500) return { kind: 'transient', retryable: true }
return { kind: 'fatal', retryable: false }
},
}), 'anthropic: multiprovider accounts')
})
}
不要在 metadata、标签、账户 ID 或凭据引用中放置 API 密钥、访问令牌、刷新令牌或原始提供商诊断信息。引用必须是定位符，而不是密钥本身。

2. 为完整操作租用一个账户

const attempted = new Set()

for (;;) {
const lease = await ctx.multiprovider.acquire({
providerId: 'anthropic',
affinityKey: session.id,
excludeAccountIds: attempted,
})
attempted.add(lease.accountId)

try {
const credential = await resolveCredential(lease.credentialRef)
const result = await runCompleteProviderOperation(credential)
lease.release({ status: 'success' })
return result
} catch (error) {
const disposition = lease.release({ status: 'failure', error })
if (!disposition?.retryable || !isSafeToReplay(error)) throw error
// Reacquiring with excludeAccountIds selects another eligible account.
}
}

对于流式 LLM 请求，应持有租约直到流已完成或失败——而不仅仅直到创建了异步可迭代对象。在用户可见的输出已经开始后，绝不要自动重放，除非提供商集成能够证明重放是安全的。

相关的搜索、图像、用量和工具操作在可用时应传递相同的会话/工作负载亲和键。

设置 UI

浏览器插件提供一个独立的 settings.section，名为 Accounts。它显示：

- 已注册的提供商池和账户认证类型
- 健康、冷却、失败和进行中状态
- 池选择策略和会话亲和性
- 每账户的启用、权重和优先级
- 提供商提供的账户管理指南
- 用于清除自动冷却/失败健康状态的操作员操作

GET /plugins/dsh-multiprovider/state 绝不返回密钥。变更端点强制实施回环和同源检查、限制 JSON 请求体大小、方法允许列表、no-store 响应以及严格的字段验证。

所有权边界

| 层 | 拥有 |
| --- | --- |
| dsh-multiprovider | 账户池、租约、选择、亲和性、健康、冷却、故障转移原语、操作员策略 UI |
| 提供商插件 | OAuth/API 密钥注册、凭据持久化和刷新、传输、完整流生命周期、错误分类 |
| DSH 核心 | 请求/会话生命周期、凭据和授权服务、提供商/模型身份 |

当前范围

健康、租约和亲和性是进程本地的。偏好通过 DSH 设置持久化。此版本不会为账户容量排队、不会施加每账户并发限制，也不会执行隐藏重试。这些是有意为之的未来扩展；显式重新获取将重放安全性保留在提供商集成中，因为协议语义在那里是已知的。

开发和发布

pnpm install --frozen-lockfile
pnpm run check
pnpm pack --dry-run
pnpm run check 会对宿主端和浏览器端进行类型检查，运行完整的 Vitest 测试套件，并构建 ESM 服务以及浏览器客户端 bundle。prepack 会在 npm 创建发布载荷之前重复该检查。

与其他项目的关系

- DeepSeek Harness 负责提供商/模型身份、请求与会话生命周期、设置持久化、Web 宿主以及客户端组合。
- dsh-codex 是一个具体集成：它租用 Codex 账户，同时保留 OAuth、令牌刷新以及响应流的归属权。
- dsh-fabric、dsh-fovea、dsh-factory 和 dsh-tool-repair 是经过测试的 DSH 发行版所固定的其他外部 bundle。

许可证

MIT © Tom Nguyen。