dsh-router-core 0.1.0

package/src/shared.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared constants and wire types for dsh-router.
+ *
+ * Pure values — no framework imports — so the host (tsdown ESM) and the
+ * client (vite CJS browser bundle) can both inline them safely.
+ */
+
+/** The sidebar entry / panel dataset attribute family name. */
+export const ROUTER_ENTRY_SELECTOR = '[data-dsh-router-entry]'
+
+/** The center-column takeover panel attribute. */
+export const ROUTER_VIEW_SELECTOR = '[data-dsh-router-view]'
+
+/** Active-state attribute on <html> that shows the panel. */
+export const ROUTER_ACTIVE_ATTR = 'data-dsh-router-active'
+
+/** The panel's visible title (also the sidebar entry label). */
+export const ROUTER_TITLE = '路由系统'
+
+/** Same-origin API base the client panel fetches (host half serves it). */
+export const ROUTER_API_BASE = '/router/api'
+
+/** Bearer key env / credential reference protecting /v1/*. */
+export const API_KEY_REF = 'TW2A_API_KEY'
+
+/** One account row from `/router/api/status`. */
+export interface RouterAccount {
+  uid: string
+  nickname?: string
+  credits: number
+  cooling: boolean
+  until?: string
+  reason?: string
+  disabled: boolean
+  err_count?: number
+  /** 所属供应商 id。 */
+  supplier?: string
+}
+
+/** `/router/api/status` response. */
+export interface RouterStatusResponse {
+  ok: boolean
+  error?: string
+  accounts?: RouterAccount[]
+}
+
+/** `/router/api/models` response. */
+export interface RouterModelsResponse {
+  ok: boolean
+  error?: string
+  models?: Array<{ id: string; context_length?: number }>
+}
+
+/** `/router/api/health` response. */
+export interface RouterHealthResponse {
+  ok: boolean
+  suppliers?: Array<{
+    id: string
+    name: string
+    /** 图标（URL 或 SVG data URI）。 */
+    icon?: string
+    /** 面板能力集合（登录/签到/连接池/模型管理等，按存在性）。 */
+    capabilities?: string[]
+    /** 来源：内置 / 用户目录 / 外部插件。 */
+    source?: 'builtin' | 'user' | 'external'
+  }>
+  error?: string
+}
+
+/** 组合策略。 */
+export type RouterComboStrategy = 'fallback' | 'round-robin'
+
+/** 组合。models = 该组合命中的模型列表（裸模型 id，展示时动态拼前缀）。 */
+export interface RouterCombo {
+  id: string
+  name: string
+  strategy: RouterComboStrategy
+  models: string[]
+}
+
+/** `/router/api/combos` response. */
+export interface RouterCombosResponse {
+  ok: boolean
+  error?: string
+  combos?: RouterCombo[]
+  /** 可用模型（按供应商分组，仅启用），面板加模型用。 */
+  groups?: RouterComboSupplierGroup[]
+  /** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。 */
+  aliases?: RouterComboAlias[]
+}
+
+/** 组合页供应商前缀信息。 */
+export interface RouterComboAlias {
+  id: string
+  name: string
+  alias: string
+}
+
+/** 组合页可用模型分组（一个供应商一组）。 */
+export interface RouterComboSupplierGroup {
+  supplier: { id: string; name: string; alias: string }
+  models: RouterSupplierModel[]
+}
+
+/** 库内一条 key（列表含完整 key，客户端脱敏显示）。 */
+export interface RouterKey {
+  id: string
+  name: string
+  key: string
+  masked: string
+  isActive: boolean
+  createdAt: string
+}
+
+/** `/router/api/keys` response. */
+export interface RouterKeysResponse {
+  ok: boolean
+  error?: string
+  keys?: RouterKey[]
+}
+
+/** `/router/api/settings` response. */
+export interface RouterSettingsResponse {
+  ok: boolean
+  error?: string
+  requireApiKey?: boolean
+}
+
+/** 供应商模型（含启用状态）。 */
+export interface RouterSupplierModel {
+  id: string
+  context_length?: number
+  enabled: boolean
+  /** 是否为自定义（手动添加 / 拉取）模型，可删除。 */
+  custom?: boolean
+}
+
+/** `/router/api/suppliers/:id/models` response. */
+export interface RouterSupplierModelsResponse {
+  ok: boolean
+  error?: string
+  /** 供应商前缀（模型全名 = alias/id）。 */
+  alias?: string
+  models?: RouterSupplierModel[]
+}
+
+/** `/router/api/suppliers/:id/login` response. */
+export interface RouterLoginResponse {
+  ok: boolean
+  error?: string
+  loginUrl?: string
+}

package/src/supplier-config.ts

@@ -0,0 +1,144 @@
+/**
+ * 通用供应商配置 —— dsh-router 核心能力,按供应商 id 存储。
+ *
+ * 通用能力(所有供应商共享,供应商 js 不需要实现)：
+ *   - 别名 alias(前缀,模型全名 = alias/id)
+ *   - 模型管理:启用/禁用 disabled、自定义 custom
+ *   - 连接池:poolOrder(拖动排序)、poolStrategy(回退/轮询)
+ *   - 签到规则 checkinRule(所有链接 / 首个链接)
+ *
+ * 持久化到 data/supplier-config.json。
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export type PoolStrategy = 'fallback' | 'round-robin'
+export type CheckinRule = 'all' | 'first'
+
+export interface SupplierConfig {
+  alias: string
+  disabled: string[]
+  custom: string[]
+  poolOrder: string[]
+  poolStrategy: PoolStrategy
+  checkinRule: CheckinRule
+}
+
+interface ConfigFile {
+  suppliers: Record<string, Partial<SupplierConfig>>
+}
+
+/** 通用供应商配置存储。 */
+export class SupplierConfigStore {
+  private fp = ''
+  private bySupplier = new Map<string, SupplierConfig>()
+
+  constructor(stateFile: string) {
+    this.fp = stateFile ? join(dirname(stateFile), 'supplier-config.json') : ''
+    this.load()
+  }
+
+  /** 读取某供应商配置(不存在则返回默认并注册)。 */
+  get(supplierId: string): SupplierConfig {
+    let cfg = this.bySupplier.get(supplierId)
+    if (!cfg) {
+      cfg = { alias: '', disabled: [], custom: [], poolOrder: [], poolStrategy: 'fallback', checkinRule: 'all' }
+      this.bySupplier.set(supplierId, cfg)
+    }
+    return cfg
+  }
+
+  setAlias(supplierId: string, alias: string): void {
+    this.get(supplierId).alias = alias
+    this.saveLocked()
+  }
+
+  setModelEnabled(supplierId: string, modelId: string, enabled: boolean): void {
+    const cfg = this.get(supplierId)
+    cfg.disabled = enabled
+      ? cfg.disabled.filter((m) => m !== modelId)
+      : [...new Set([...cfg.disabled, modelId])]
+    this.saveLocked()
+  }
+
+  setAllModelsEnabled(supplierId: string, enabled: boolean, allModelIds: string[]): void {
+    const cfg = this.get(supplierId)
+    cfg.disabled = enabled ? [] : [...new Set(allModelIds)]
+    this.saveLocked()
+  }
+
+  addCustomModel(supplierId: string, modelId: string): void {
+    const cfg = this.get(supplierId)
+    if (!cfg.custom.includes(modelId)) cfg.custom.push(modelId)
+    this.saveLocked()
+  }
+
+  removeCustomModel(supplierId: string, modelId: string): void {
+    const cfg = this.get(supplierId)
+    cfg.custom = cfg.custom.filter((m) => m !== modelId)
+    cfg.disabled = cfg.disabled.filter((m) => m !== modelId)
+    this.saveLocked()
+  }
+
+  setPoolOrder(supplierId: string, uids: string[]): void {
+    this.get(supplierId).poolOrder = [...new Set(uids)]
+    this.saveLocked()
+  }
+
+  setPoolStrategy(supplierId: string, strategy: string): void {
+    if (strategy !== 'fallback' && strategy !== 'round-robin') return
+    this.get(supplierId).poolStrategy = strategy
+    this.saveLocked()
+  }
+
+  setCheckinRule(supplierId: string, rule: string): void {
+    if (rule !== 'all' && rule !== 'first') return
+    this.get(supplierId).checkinRule = rule
+    this.saveLocked()
+  }
+
+  private load(): void {
+    if (this.fp === '') return
+    let f: ConfigFile
+    try {
+      f = JSON.parse(readFileSync(this.fp, 'utf8')) as ConfigFile
+    } catch {
+      return
+    }
+    for (const [id, c] of Object.entries(f.suppliers ?? {})) {
+      this.bySupplier.set(id, {
+        alias: typeof c.alias === 'string' ? c.alias : '',
+        disabled: Array.isArray(c.disabled) ? c.disabled.filter((m) => typeof m === 'string') : [],
+        custom: Array.isArray(c.custom) ? c.custom.filter((m) => typeof m === 'string') : [],
+        poolOrder: Array.isArray(c.poolOrder) ? c.poolOrder.filter((u) => typeof u === 'string') : [],
+        poolStrategy: c.poolStrategy === 'round-robin' ? 'round-robin' : 'fallback',
+        checkinRule: c.checkinRule === 'first' ? 'first' : 'all',
+      })
+    }
+  }
+
+  private saveLocked(): void {
+    if (this.fp === '') return
+    const f: ConfigFile = { suppliers: {} }
+    for (const [id, cfg] of this.bySupplier) {
+      f.suppliers[id] = {
+        alias: cfg.alias,
+        disabled: [...cfg.disabled],
+        custom: [...cfg.custom],
+        poolOrder: [...cfg.poolOrder],
+        poolStrategy: cfg.poolStrategy,
+        checkinRule: cfg.checkinRule,
+      }
+    }
+    try {
+      const dir = dirname(this.fp)
+      if (dir !== '' && dir !== '.') mkdirSync(dir, { recursive: true })
+      const raw = JSON.stringify(f, null, 2)
+      const tmp = this.fp + '.tmp'
+      writeFileSync(tmp, raw, { mode: 0o600 })
+      renameSync(tmp, this.fp)
+    } catch {
+      // 持久化失败不阻断运行
+    }
+  }
+}

package/src/suppliers/contract.ts

@@ -0,0 +1,73 @@
+/**
+ * 通用供应商契约 —— 供应商 js 只需 export 一个满足本契约的对象/类实例。
+ *
+ * 分工：
+ *   - 通用能力（连接池排序/策略、模型启用/自定义、别名）由 dsh-router 核心
+ *     SupplierConfigStore 统一管理，供应商 js 不需要实现。
+ *   - 可插拔 js 模块只提供**差异化能力**：如何列模型/调上游/登录/签到等。
+ *
+ * 用户自定义供应商 js 放到 `~/.dsh/profiles/web/suppliers/*.js`，重启后自动加载。
+ * 内置供应商与用户 js 同构（差异化能力驱动）。
+ */
+import type { ServerResponse } from 'node:http'
+import type { ChatRequest, ModelInfo, SupplierAccount, SupplierStatus } from '../router/types.ts'
+import type { SupplierConfigStore } from '../supplier-config.ts'
+import type { CredentialStore } from '../credential-store.ts'
+
+/** 供应商配置：loader 注入的运行时环境。 */
+export interface SupplierEnv {
+  /** 数据目录（state.json / keys.json 所在目录）。 */
+  dataDir: string
+  /** 日志。 */
+  log: (msg: string) => void
+  /** 通用配置存储（连接池/模型管理/别名/签到规则，核心统一管）。 */
+  store: SupplierConfigStore
+  /** 通用凭证存储（账号凭证，核心统一管）。 */
+  credentials: CredentialStore
+}
+
+/** 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。 */
+export type SupplierFactory = (env: SupplierEnv) => SupplierModule
+
+/** 供应商模块 —— 契约（核心必须，差异化可选）。 */
+export interface SupplierModule {
+  /** 供应商唯一 id（小写字母数字 - _）。 */
+  readonly id: string
+  /** 显示名。 */
+  readonly name: string
+  /** 优先级：数字越小越优先（免费通道优先）。 */
+  readonly priority?: number
+  /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
+  readonly icon?: string
+
+  // ---- 核心（必须） ----
+  status(): SupplierStatus
+  /** 模型来源。`force=true` 时强制刷新来源（核心「获取模型」按钮调用）。 */
+  listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[]
+  /** 默认前缀（可被通用层 alias 覆盖）。 */
+  getAlias(): string
+  chatCompletions(req: ChatRequest, res: ServerResponse): Promise<boolean>
+  /** 测试模型（验证上游真实可用，必要差异化能力）。 */
+  testModel(id: string): Promise<{ ok: boolean; error?: string }>
+  dispose(): void
+
+  // ---- 差异化能力（可选，按存在性暴露端点/UI） ----
+
+  /** 生成登录链接（加账号）。有它才显示连接池（账号池）。 */
+  generateLoginUrl?(): string | { ok: boolean; error?: string; loginUrl?: string } | Promise<string | { ok: boolean; error?: string; loginUrl?: string }>
+  /** 回调完成登录。 */
+  completeLogin?(callbackUrl: string): Promise<{ uid: string; nickname: string }>
+
+  /** 添加 API key 账号（弹窗填名字+key，而非 URL 登录）。有它同样显示连接池。 */
+  addApiKey?(input: { name: string; apiKey: string }): Promise<{ ok: boolean; error?: string; account?: { uid: string; nickname: string } }>
+  /** 删除链接（清理凭证；内部能力）。 */
+  removeLink?(uid: string): Promise<boolean>
+  /** 轮询式登录标记：有它 → 面板隐藏「粘贴回调链接」步骤，登录后直接点完成（后台轮询）。 */
+  pollLogin?(): boolean
+
+  /** 触发签到。签到规则(all/first)是 dsh-router 通用策略,不在此列。 */
+  checkinNow?(): Promise<{ ok: boolean; total: number; succeeded: number; already?: number; error?: string; results?: Array<{ uid: string; ok: boolean; status?: string; message?: string }> }>
+}
+
+/** 供应商账号（复用 router 类型，供 loader 包装）。 */
+export type { SupplierAccount }

package/src/suppliers/loader.ts

@@ -0,0 +1,191 @@
+/**
+ * 供应商 loader —— 扫描 suppliers 目录下的 *.js，动态 import，按契约包装成
+ * 内部 Supplier，并暴露"能力检测"(capabilities)供通用路由/前端按能力渲染。
+ *
+ * 加载来源（两处，profile 优先）：
+ *   1. 内置：<plugin>/lib/suppliers/*.js（随插件分发）
+ *   2. 用户：~/.dsh/profiles/web/suppliers/*.js（用户自定义）
+ */
+import { readdirSync } from 'node:fs'
+import { join, dirname, basename } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ServerResponse } from 'node:http'
+import type { ChatRequest, ModelInfo, ModelWithEnabled, Supplier, SupplierStatus } from '../router/types.ts'
+import type { SupplierConfigStore } from '../supplier-config.ts'
+import type { CredentialStore } from '../credential-store.ts'
+import type { SupplierEnv, SupplierFactory, SupplierModule } from './contract.ts'
+
+/** 供应商加载错误（不阻断其他供应商）。 */
+export interface SupplierLoadError {
+  id: string
+  file: string
+  error: string
+}
+
+/** 供应商实例 + 能力标记。 */
+export interface LoadedSupplier {
+  supplier: Supplier
+  /** 差异化能力集合（方法名存在性，通用能力不在此列）。 */
+  capabilities: Set<string>
+  /** 来源：内置 / 用户目录 / 外部插件（cordis service）。 */
+  source: 'builtin' | 'user' | 'external'
+}
+
+function isFn(v: unknown): v is (...args: unknown[]) => unknown {
+  return typeof v === 'function'
+}
+
+/** 从模块导出解析出供应商模块对象（支持 export default / 命名导出 / factory）。 */
+function resolveModule(mod: Record<string, unknown>, file: string): SupplierModule {
+  const cand = (mod.default ?? mod) as Record<string, unknown>
+  // factory 形式：模块 default 是 (env) => SupplierModule，跳过静态检查，loadOne 调用后实例生效
+  if (typeof cand === 'function') return cand as unknown as SupplierModule
+  if (typeof cand !== 'object' || cand === null) throw new Error(`供应商模块无效: ${file}`)
+  if (typeof cand.id !== 'string' || cand.id === '') throw new Error(`供应商缺少 id: ${file}`)
+  if (typeof cand.name !== 'string' || cand.name === '') throw new Error(`供应商缺少 name: ${file}`)
+  if (typeof cand.testModel !== 'function') throw new Error(`供应商 ${cand.id} 缺少 testModel（必要差异化能力）: ${file}`)
+  return cand as unknown as SupplierModule
+}
+
+/** 加载单个供应商文件，返回模块对象或抛错。 */
+async function importSupplierFile(file: string): Promise<SupplierModule> {
+  const url = pathToFileURL(file).href
+  const mod = (await import(url)) as Record<string, unknown>
+  return resolveModule(mod, file)
+}
+
+/**
+ * 差异化能力（供应商 js 实现；其余为通用能力由核心提供）。
+ * testModel 是必要差异化能力（核心必须），不在此列。
+ */
+const DIFF_CAPS = [
+  'generateLoginUrl', 'completeLogin',
+  'addApiKey',
+  'pollLogin',
+  'checkinNow',
+] as const
+
+/** 从文件构造 LoadedSupplier。 */
+async function loadOne(file: string, env: SupplierEnv, source: 'builtin' | 'user'): Promise<LoadedSupplier> {
+  const mod = await importSupplierFile(file)
+  // 支持 factory: 模块本身就是工厂函数
+  let instance: SupplierModule
+  if (typeof mod === 'function') {
+    instance = (mod as unknown as SupplierFactory)(env)
+    if (typeof instance !== 'object' || instance === null || typeof instance.id !== 'string' || instance.id === '') {
+      throw new Error(`供应商 factory 返回无效: ${file}`)
+    }
+    if (typeof instance.testModel !== 'function') {
+      throw new Error(`供应商 ${instance.id} 缺少 testModel（必要差异化能力）: ${file}`)
+    }
+  } else {
+    instance = mod
+  }
+  return wrapModule(instance, env, file, source)
+}
+
+/**
+ * 从 SupplierModule 实例构造 LoadedSupplier（能力检测 + Supplier 包装）。
+ * 文件加载（loadOne）与外部插件供应商（cordis service）共用。
+ */
+export function wrapModule(instance: SupplierModule, env: SupplierEnv, source: string, kind: 'builtin' | 'user' | 'external' = 'external'): LoadedSupplier {
+  if (typeof instance !== 'object' || instance === null || typeof instance.id !== 'string' || instance.id === '') {
+    throw new Error(`供应商模块无效: ${source}`)
+  }
+  if (typeof instance.testModel !== 'function') {
+    throw new Error(`供应商 ${instance.id} 缺少 testModel（必要差异化能力）: ${source}`)
+  }
+  const capabilities = new Set<string>()
+  for (const key of DIFF_CAPS) {
+    if (isFn((instance as unknown as Record<string, unknown>)[key])) capabilities.add(key)
+  }
+
+  const supplier: Supplier = {
+    id: instance.id,
+    name: instance.name,
+    priority: instance.priority ?? 0,
+    icon: (instance as { icon?: string }).icon,
+    status: (): SupplierStatus => instance.status(),
+    listModels: (force?: boolean): Promise<ModelInfo[]> | ModelInfo[] => instance.listModels(force),
+    // 通用能力：模型启用状态/自定义由核心 SupplierConfigStore 合并
+    modelsWithEnabled: (force?: boolean): Promise<ModelWithEnabled[]> | ModelWithEnabled[] => {
+      const cfg = env.store.get(instance.id)
+      const disabled = new Set(cfg.disabled)
+      const custom = new Set(cfg.custom)
+      return Promise.resolve(instance.listModels(force)).then((list) =>
+        list.map((mm) => ({
+          ...mm,
+          enabled: !disabled.has(mm.id),
+          custom: custom.has(mm.id) ? true : undefined,
+        })),
+      )
+    },
+    getAlias: (): string => env.store.get(instance.id).alias || instance.getAlias(),
+    customModelIds: (): string[] => [...env.store.get(instance.id).custom],
+    chatCompletions: (req: ChatRequest, res: ServerResponse): Promise<boolean> => instance.chatCompletions(req, res),
+    testModel: (id: string): Promise<{ ok: boolean; error?: string }> => instance.testModel(id),
+    // 删除链接：数据删除是通用能力，凭证清理由供应商内部实现（js 契约不要求）
+    removeLink: isFn((instance as unknown as Record<string, unknown>).removeLink)
+      ? (uid: string): Promise<boolean> => (instance as unknown as { removeLink(uid: string): Promise<boolean> }).removeLink(uid)
+      : undefined,
+    dispose: (): void => instance.dispose(),
+  }
+  // 差异化路由通过 LoadedSupplier.capabilities + supplier 实例调用面板方法
+  ;(supplier as Supplier & { __module?: SupplierModule }).__module = instance
+
+  return { supplier, capabilities, source: kind }
+}
+
+/** 扫描目录下所有 *.js（一层）。 */
+function scanDir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.js'))
+      .map((f) => join(dir, f))
+  } catch {
+    return []
+  }
+}
+
+export interface LoadSuppliersOptions {
+  /** 内置供应商目录（<plugin>/lib/suppliers）。 */
+  builtinDir: string
+  /** 用户供应商目录（~/.dsh/profiles/web/suppliers）。 */
+  userDir: string
+  /** 数据目录。 */
+  dataDir: string
+  /** 通用配置存储。 */
+  store: SupplierConfigStore
+  /** 通用凭证存储。 */
+  credentials: CredentialStore
+  log: (msg: string) => void
+}
+
+/** 加载全部供应商（内置 + 用户，用户覆盖内置同 id）。 */
+export async function loadSuppliers(opts: LoadSuppliersOptions): Promise<{
+  suppliers: LoadedSupplier[]
+  errors: SupplierLoadError[]
+}> {
+  const env: SupplierEnv = { dataDir: opts.dataDir, log: opts.log, store: opts.store, credentials: opts.credentials }
+  const byId = new Map<string, LoadedSupplier>()
+  const errors: SupplierLoadError[] = []
+
+  const files = [
+    ...scanDir(opts.builtinDir).map((f) => ({ f, builtin: true })),
+    ...scanDir(opts.userDir).map((f) => ({ f, builtin: false })),
+  ]
+  for (const { f, builtin } of files) {
+    try {
+      const loaded = await loadOne(f, env, builtin ? 'builtin' : 'user')
+      // 用户目录覆盖内置
+      const existing = byId.get(loaded.supplier.id)
+      if (existing && builtin) continue // 内置已被用户版覆盖
+      byId.set(loaded.supplier.id, loaded)
+      opts.log(`supplier ${loaded.supplier.id} loaded (${builtin ? 'builtin' : 'user'}) from ${basename(f)}`)
+    } catch (err) {
+      errors.push({ id: basename(f, '.js'), file: f, error: (err as Error).message })
+      opts.log(`supplier load failed ${basename(f)}: ${(err as Error).message}`)
+    }
+  }
+  return { suppliers: [...byId.values()], errors }
+}