dsh-multiprovider：DeepSeek Harness 多賬號調度與健康管理插件

DSH 採用插件化架構，實際開發中常需在一個 Provider 邏輯身份下管理多組憑證。dsh-multiprovider 是爲此設計的插件，它接管了賬號選擇、會話親和性、健康狀態和冷卻策略，而不涉及具體的模型路由邏輯。

該插件由 monotykamary 維護，遵循 MIT 協議。它爲 DeepSeek Harness 提供了 provider-neutral 的多賬號調度、會話親和性、健康監控以及設置界面。

核心功能¶

插件主要提供以下能力：

確定性調度：支持輪詢、加權、最少進行中和優先級策略。
會話親和性：通過 affinityKey 保持相關請求使用同一賬號。
可見健康狀態：展示冷卻時間、失敗分類和進行中的請求數。
憑證管理：使用 Provider 持有的 opaque references（不直接存儲密鑰）。
實時偏好：通過 DSH 設置界面直接啓用、調整權重或優先級。
歸一化失敗健康：識別 rate-limit、auth、transient、fatal 等錯誤類型。
可配置冷卻：支持指數退避策略。
設置界面：在 DSH 設置模態框中提供獨立的 Accounts 部分。

安裝與啓用¶

使用前需確保環境滿足：Node.js ^22.19.0 || >=24、pnpm 11 以及 DeepSeek Harness ^0.1.1。

執行以下命令安裝：

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

安裝後，插件會作爲一個 Cordis 服務注入到 ctx.multiprovider 中。

典型用法¶

1. 註冊 Provider Inventory¶

在 Provider 插件中注入 multiprovider 服務，並定義賬號列表與失敗分類邏輯。

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')
  })
}

2. 獲取與釋放租約¶

在業務邏輯中通過 acquire 獲取賬號，操作完成後必須調用 release。

const attempted = new Set<string>()

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.
  }
}

注意事項¶

憑證安全：憑證以 opaque references 形式存在，不會進入瀏覽器快照。
流式請求：對於流式 LLM 請求，必須持有 lease 直到流完成或失敗，而非僅僅創建迭代器。
設置安全：設置界面僅允許同源訪問以保護憑證。
租約釋放：必須顯式調用 lease.release()，否則賬號將無法被其他請求使用。

總結¶

dsh-multiprovider 通過標準化賬號管理和健康檢查機制，降低了多賬號調度的複雜度。其代碼庫位於 GitHub，可在 SkillHub 目錄頁查看詳情。