dsh-router-core 0.1.0

package/src/llm/adapter.ts

@@ -0,0 +1,273 @@
+/**
+ * DSH llm adapter for dsh-router（provider 固定卡片，名字 Router）。
+ *
+ * 模型目录 = 组合（自动带出，不可改）。对话转发到本插件 /v1/chat/completions，
+ * 由现有路由按组合策略命中供应商模型。
+ *
+ * 纯文本流：组合为文本模型，本 adapter 不处理图片附件。
+ */
+import {
+  CallId,
+  EMPTY_RESPONSE_CODE,
+  LlmAdapter,
+  LlmError,
+  type GenerateOptions,
+  type LlmModelInfo,
+  type StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+
+/** 模型目录来源：组合。 */
+export interface RouterAdapterSource {
+  comboModels: () => Promise<Array<{ id: string; name?: string }>>
+}
+
+/** 解析 SSE 文本，产出 `data:` 载荷（含结尾 [DONE]）。 */
+function* parseSseText(text: string): Generator<string> {
+  let data = ''
+  for (const line of text.split('\n')) {
+    if (line.startsWith('data:')) {
+      const value = line.slice(5).trimStart()
+      if (data.length > 0) data += '\n'
+      data += value
+      continue
+    }
+    if (line === '' && data.length > 0) {
+      yield data
+      data = ''
+    }
+  }
+  if (data.length > 0) yield data
+}
+
+/** 把 DSH 消息序列化成 openai 兼容 wire 消息（纯文本 + tool）。 */
+function wireMessages(options: GenerateOptions): Array<Record<string, unknown>> {
+  const out: Array<Record<string, unknown>> = []
+  for (const message of options.messages) {
+    if (message.role === 'system') {
+      out.push({ role: 'system', content: flattenText(message.content) })
+      continue
+    }
+    if (message.role === 'assistant') {
+      const text = flattenText(message.content)
+      const toolCalls = message.content
+        .filter((b) => b.type === 'tool-call')
+        .map((b) => ({ id: b.id, type: 'function', function: { name: b.name, arguments: b.arguments } }))
+      const reasoning = message.content
+        .filter((b) => b.type === 'reasoning')
+        .map((b) => b.text)
+        .join('')
+      out.push({
+        role: 'assistant',
+        content: text,
+        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        ...(reasoning.length > 0 ? { reasoning_content: reasoning } : {}),
+      })
+      continue
+    }
+    // user / tool-result
+    const text = flattenText(message.content)
+    const toolResults = message.content.filter((b) => b.type === 'tool-result')
+    if (text.length > 0 || toolResults.length === 0) out.push({ role: 'user', content: text })
+    for (const result of toolResults) {
+      out.push({ role: 'tool', tool_call_id: result.toolCallId, content: flattenText(result.content) || '(no output)' })
+    }
+  }
+  return out
+}
+
+/** 组装 wire 请求体。 */
+function wireRequest(options: GenerateOptions): Record<string, unknown> {
+  const messages = wireMessages(options)
+  const body: Record<string, unknown> = {
+    model: options.model,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+  }
+  const tools = options.tools?.map((tool) => ({
+    type: 'function',
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+  }))
+  if (tools !== undefined && tools.length > 0) body.tools = tools
+  if (options.temperature !== undefined) body.temperature = options.temperature
+  if (options.maxTokens !== undefined) body.max_tokens = options.maxTokens
+  if (options.stop !== undefined) body.stop = options.stop
+  return body
+}
+
+function flattenText(blocks: readonly { type: string; text?: string }[]): string {
+  return blocks.filter((b) => b.type === 'text').map((b) => b.text ?? '').join('')
+}
+
+interface OpenBlock {
+  index: number
+  kind: 'text' | 'reasoning' | 'tool-call'
+  text: string
+  callId?: string
+  name?: string
+}
+
+/** openai SSE payload → DSH StreamChunk 流。 */
+async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChunk> {
+  let nextIndex = 0
+  let textBlock: OpenBlock | undefined
+  let reasoningBlock: OpenBlock | undefined
+  const toolBlocks = new Map<number, OpenBlock>()
+  const order: OpenBlock[] = []
+  let pendingFinish: { kind: string; failure?: unknown } | undefined
+  let pendingUsage: unknown
+
+  const open = (kind: OpenBlock['kind']): OpenBlock => {
+    const block: OpenBlock = { index: nextIndex++, kind, text: '' }
+    order.push(block)
+    return block
+  }
+
+  for (const payload of payloads) {
+    if (payload === '[DONE]') {
+      for (const block of order) {
+        yield { type: 'block-end', index: block.index, block: closeBlock(block) }
+      }
+      if (pendingUsage !== undefined) yield { type: 'usage', usage: pendingUsage as never }
+      const reason = pendingFinish ?? { kind: 'stop' }
+      yield {
+        type: 'finish',
+        reason:
+          reason.kind === 'stop' && order.length === 0
+            ? { kind: 'error', failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE } }
+            : (reason as never),
+      }
+      return
+    }
+    let chunk: { choices?: Array<{ delta?: Record<string, unknown>; finish_reason?: string }>; usage?: unknown }
+    try {
+      chunk = JSON.parse(payload) as typeof chunk
+    } catch {
+      throw new LlmError(`malformed SSE payload: ${payload.slice(0, 120)}`, 'MALFORMED_RESPONSE')
+    }
+    for (const choice of chunk.choices ?? []) {
+      const delta = choice.delta ?? {}
+      const reasoning = delta.reasoning_content
+      if (typeof reasoning === 'string' && reasoning.length > 0) {
+        if (!reasoningBlock) {
+          reasoningBlock = open('reasoning')
+          yield { type: 'block-start', index: reasoningBlock.index, blockType: 'reasoning' }
+        }
+        reasoningBlock.text += reasoning
+        yield { type: 'reasoning-delta', index: reasoningBlock.index, text: reasoning }
+      }
+      const content = delta.content
+      if (typeof content === 'string' && content.length > 0) {
+        if (!textBlock) {
+          textBlock = open('text')
+          yield { type: 'block-start', index: textBlock.index, blockType: 'text' }
+        }
+        textBlock.text += content
+        yield { type: 'text-delta', index: textBlock.index, text: content }
+      }
+      const toolCalls = delta.tool_calls as Array<{ index?: number; id?: string; function?: { name?: string; arguments?: string } }> | undefined
+      for (const call of toolCalls ?? []) {
+        const key = call.index ?? 0
+        let block = toolBlocks.get(key)
+        if (!block) {
+          block = open('tool-call')
+          toolBlocks.set(key, block)
+          yield { type: 'block-start', index: block.index, blockType: 'tool-call' }
+        }
+        if (call.id !== undefined) block.callId = call.id
+        if (call.function?.name !== undefined) block.name = call.function.name
+        const fragment = call.function?.arguments ?? ''
+        block.text += fragment
+        yield {
+          type: 'tool-call-delta',
+          index: block.index,
+          id: CallId(block.callId ?? ''),
+          ...(block.name !== undefined ? { name: block.name } : {}),
+          argumentsDelta: fragment,
+        }
+      }
+      if (typeof choice.finish_reason === 'string') pendingFinish = mapFinishReason(choice.finish_reason)
+    }
+    if (chunk.usage !== undefined) pendingUsage = chunk.usage
+  }
+  throw new LlmError('SSE payload stream ended without [DONE]', 'STREAM_CLOSED')
+}
+
+function mapFinishReason(reason: string): { kind: string; failure?: unknown } {
+  switch (reason) {
+    case 'stop': return { kind: 'stop' }
+    case 'tool_calls': return { kind: 'tool-calls' }
+    case 'length': return { kind: 'max-tokens' }
+    default: return { kind: 'error', failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() } }
+  }
+}
+
+function closeBlock(block: OpenBlock): never {
+  switch (block.kind) {
+    case 'text': return { type: 'text', text: block.text } as never
+    case 'reasoning': return { type: 'reasoning', text: block.text } as never
+    case 'tool-call': return {
+      type: 'tool-call',
+      id: CallId(block.callId ?? ''),
+      name: block.name ?? '',
+      arguments: block.text,
+    } as never
+  }
+}
+
+/**
+ * DSH adapter：provider `router`。模型目录 = 组合；stream 转发到本插件
+ * /v1/chat/completions（组合路由在 /v1 内完成）。
+ */
+export class RouterAdapter extends LlmAdapter {
+  private readonly baseURL: string
+  private readonly source: RouterAdapterSource
+
+  constructor(baseURL: string, source: RouterAdapterSource) {
+    super()
+    this.baseURL = baseURL
+    this.source = source
+  }
+
+  providerInfo(provider: string): { id: string; name: string } {
+    return { id: provider, name: 'Router' }
+  }
+
+  async listModels(_provider: string): Promise<readonly LlmModelInfo[]> {
+    const combos = await this.source.comboModels()
+    const seen = new Set<string>()
+    const out: LlmModelInfo[] = []
+    for (const m of combos) {
+      if (seen.has(m.id)) continue
+      seen.add(m.id)
+      out.push({ provider: 'router', id: m.id, name: m.name ?? m.id })
+    }
+    return out
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const body = wireRequest(options)
+    const controller = new AbortController()
+    const onAbort = (): void => controller.abort()
+    options.signal?.addEventListener('abort', onAbort, { once: true })
+    let resp: Response
+    try {
+      resp = await fetch(`${this.baseURL}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+    } catch (error) {
+      throw new LlmError(`dsh-router upstream call failed: ${(error as Error).message}`, 'TRANSPORT', { cause: error })
+    } finally {
+      options.signal?.removeEventListener('abort', onAbort)
+    }
+    if (!resp.ok) {
+      const detail = await resp.text().catch(() => '')
+      throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, 'TRANSPORT')
+    }
+    const text = resp.body === null ? '' : await resp.text()
+    yield* translate(parseSseText(text))
+  }
+}

package/src/router/index.ts

@@ -0,0 +1,273 @@
+/**
+ * dsh-router 路由器本体：供应商注册表 + OpenAI 兼容 /v1/* 处理。
+ * 仿 9router：组合 = 一组模型，请求 model 命中组合名时，按策略
+ * （fallback 顺序尝试 / round-robin 轮转）选中一个模型路由。
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { ServerResponse } from 'node:http'
+import type { Supplier, ChatRequest, ModelInfo, ModelWithEnabled, SupplierStatus, Combo } from './types.ts'
+
+function openAIError(code: string, msg: string): Record<string, unknown> {
+  return { error: { message: msg, type: 'api_error', code } }
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+/** 路由器。 */
+export class Router {
+  private suppliers: Supplier[] = []
+  private combosFp = ''
+  private customCombos: Combo[] = []
+  /** round-robin 轮转游标（按组合 id 记忆）。 */
+  private rrCursors = new Map<string, number>()
+
+  constructor(stateFile = '') {
+    this.combosFp = stateFile ? join(dirname(stateFile), 'combos.json') : ''
+    this.loadCombos()
+  }
+
+  private loadCombos(): void {
+    if (this.combosFp === '') return
+    try {
+      const f = JSON.parse(readFileSync(this.combosFp, 'utf8')) as { combos?: Combo[] }
+      if (Array.isArray(f.combos)) {
+        // 兼容旧格式：steps(供应商) → models(模型)；无 strategy 默认 fallback。
+        this.customCombos = f.combos
+          .filter((c) => typeof c.id === 'string' && c.id !== '')
+          .map((c) => {
+            const old = c as unknown as { steps?: Array<{ supplier: string }> }
+            const raw = Array.isArray(c.models)
+              ? c.models.filter((m) => typeof m === 'string' && m !== '')
+              : Array.isArray(old.steps)
+                ? old.steps
+                    .map((s) => s.supplier)
+                    .filter((m) => typeof m === 'string' && m !== '')
+                : []
+            // 兼容旧版存的全名 alias/id：剥掉前缀存裸 id（前缀随供应商动态变）
+            const models = raw.map((m) => {
+              const slash = m.lastIndexOf('/')
+              return slash >= 0 ? m.slice(slash + 1) : m
+            })
+            return {
+              id: c.id,
+              name: typeof c.name === 'string' ? c.name : c.id,
+              strategy: c.strategy === 'round-robin' ? 'round-robin' as const : 'fallback' as const,
+              models,
+            }
+          })
+          .filter((c) => c.models.length > 0)
+      }
+    } catch {
+      // 无文件或损坏 → 空
+    }
+  }
+
+  private saveCombos(): void {
+    if (this.combosFp === '') return
+    try {
+      const dir = dirname(this.combosFp)
+      if (dir !== '' && dir !== '.') mkdirSync(dir, { recursive: true })
+      const raw = JSON.stringify({ combos: this.customCombos }, null, 2)
+      const tmp = this.combosFp + '.tmp'
+      writeFileSync(tmp, raw, { mode: 0o600 })
+      renameSync(tmp, this.combosFp)
+    } catch {
+      // 持久化失败不阻断
+    }
+  }
+
+  add(supplier: Supplier): void {
+    this.suppliers.push(supplier)
+    this.suppliers.sort((a, b) => a.priority - b.priority)
+  }
+
+  /** 移除供应商（外部插件卸载时注销）。 */
+  removeSupplier(id: string): boolean {
+    const i = this.suppliers.findIndex((s) => s.id === id)
+    if (i < 0) return false
+    const [s] = this.suppliers.splice(i, 1)
+    s?.dispose()
+    return true
+  }
+
+  /** 返回全部供应商状态（面板用）。 */
+  status(): { suppliers: SupplierStatus[] } {
+    return { suppliers: this.suppliers.map((s) => s.status()) }
+  }
+
+  /** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。 */
+  aliases(): Array<{ id: string; name: string; alias: string }> {
+    return this.suppliers.map((s) => ({ id: s.id, name: s.name, alias: s.getAlias() }))
+  }
+
+  /**
+   * OpenAI 兼容模型列表（/v1/models）：组合（自动带出，不可改）+ 手动添加的模型。
+   * pi-ai 等 DSH provider 通过它发现 Router 的模型目录。
+   */
+  async listModels(): Promise<ModelInfo[]> {
+    const seen = new Set<string>()
+    const out: ModelInfo[] = []
+    const combos = await this.combos()
+    for (const c of combos) {
+      if (!seen.has(c.name)) {
+        seen.add(c.name)
+        out.push({ id: c.name })
+      }
+    }
+    for (const s of this.suppliers) {
+      try {
+        const ids = s.customModelIds?.()
+        for (const id of ids ?? []) {
+          if (!seen.has(id)) {
+            seen.add(id)
+            out.push({ id })
+          }
+        }
+      } catch {
+        // 单供应商失败不影响其它
+      }
+    }
+    return out
+  }
+
+  /** 组合列表（面板用）：用户自定义组合。 */
+  async combos(): Promise<Combo[]> {
+    return [...this.customCombos]
+  }
+
+  /** 可用模型（按供应商分组，仅启用），面板加模型用。 */
+  async supplierModels(): Promise<Array<{ supplier: { id: string; name: string; alias: string }; models: ModelWithEnabled[] }>> {
+    const out: Array<{ supplier: { id: string; name: string; alias: string }; models: ModelWithEnabled[] }> = []
+    for (const s of this.suppliers) {
+      try {
+        const models = (await s.modelsWithEnabled()).filter((m) => m.enabled)
+        out.push({ supplier: { id: s.id, name: s.name, alias: s.getAlias() }, models })
+      } catch {
+        // 单供应商失败不影响其它
+      }
+    }
+    return out
+  }
+
+  private validModels(models: string[]): boolean {
+    return Array.isArray(models) && models.length > 0 && models.every((m) =>
+      typeof m === 'string' && m !== '')
+  }
+
+  private validStrategy(strategy: string | undefined): strategy is 'fallback' | 'round-robin' {
+    return strategy === 'fallback' || strategy === 'round-robin'
+  }
+
+  /** 组合模型统一存裸 id：剥掉 alias/ 前缀（前缀随供应商动态变）。 */
+  private normalizeModelIds(models: string[]): string[] {
+    return models.map((m) => {
+      const slash = m.lastIndexOf('/')
+      return slash >= 0 ? m.slice(slash + 1) : m
+    })
+  }
+
+  /** 创建组合（name 唯一，非 default）。 */
+  createCombo(name: string, strategy: string, models: string[]): { ok: boolean; error?: string; combo?: Combo } {
+    const clean = name.trim()
+    if (clean === '' || clean === 'default') return { ok: false, error: '组合名无效' }
+    if (!/^[A-Za-z0-9._-]+$/.test(clean)) return { ok: false, error: '组合名只能含字母、数字、-、_ 和 .' }
+    if (this.customCombos.some((c) => c.name === clean)) return { ok: false, error: `组合 ${clean} 已存在` }
+    if (!this.validModels(models)) return { ok: false, error: '至少需要一个模型' }
+    if (!this.validStrategy(strategy)) return { ok: false, error: '策略无效' }
+    const combo: Combo = { id: clean, name: clean, strategy, models: this.normalizeModelIds(models) }
+    this.customCombos.push(combo)
+    this.saveCombos()
+    return { ok: true, combo }
+  }
+
+  /** 更新组合（按 id）。 */
+  updateCombo(id: string, name: string, strategy: string, models: string[]): { ok: boolean; error?: string } {
+    const target = this.customCombos.find((c) => c.id === id)
+    if (!target) return { ok: false, error: '组合不存在' }
+    const clean = name.trim()
+    if (clean === '' || clean === 'default') return { ok: false, error: '组合名无效' }
+    if (!/^[A-Za-z0-9._-]+$/.test(clean)) return { ok: false, error: '组合名只能含字母、数字、-、_ 和 .' }
+    if (this.customCombos.some((c) => c.id !== id && c.name === clean)) return { ok: false, error: `组合 ${clean} 已存在` }
+    if (!this.validModels(models)) return { ok: false, error: '至少需要一个模型' }
+    if (!this.validStrategy(strategy)) return { ok: false, error: '策略无效' }
+    target.name = clean
+    target.strategy = strategy
+    target.models = this.normalizeModelIds(models)
+    this.saveCombos()
+    return { ok: true }
+  }
+
+  /** 删除组合（按 id，default 不可删）。 */
+  removeCombo(id: string): { ok: boolean; error?: string } {
+    if (id === 'default') return { ok: false, error: '默认组合不可删除' }
+    const idx = this.customCombos.findIndex((c) => c.id === id)
+    if (idx === -1) return { ok: false, error: '组合不存在' }
+    this.customCombos.splice(idx, 1)
+    this.saveCombos()
+    return { ok: true }
+  }
+
+  /** 按组合名查组合（含 `/` 的模型名不匹配）。 */
+  comboByName(name: string): Combo | undefined {
+    if (name.includes('/')) return undefined
+    return this.customCombos.find((c) => c.name === name)
+  }
+
+  /**
+   * 处理 /v1/chat/completions。
+   * - model 命中组合名 → 在组合模型里按策略选一个，交给供应商；失败按回退顺序尝试剩余模型。
+   * - 否则 → 依次尝试供应商，直到某个返回 true（已写响应）或全部返回 false。
+   */
+  async chatCompletions(req: ChatRequest, res: ServerResponse): Promise<void> {
+    const combo = this.comboByName(req.model)
+    if (combo) {
+      // 组合：按策略选起点，然后按组合模型顺序回退
+      const start = combo.strategy === 'round-robin'
+        ? (this.rrCursors.get(combo.id) ?? 0) % combo.models.length
+        : 0
+      if (combo.strategy === 'round-robin') this.rrCursors.set(combo.id, (this.rrCursors.get(combo.id) ?? 0) + 1)
+      for (let i = 0; i < combo.models.length; i++) {
+        const model = combo.models[(start + i) % combo.models.length]
+        if (model === undefined) continue
+        const served = await this.chatWithModel(req, res, model)
+        if (served) return
+      }
+      writeJson(res, 503, openAIError('no_healthy_supplier', `combo ${JSON.stringify(req.model)}: all models unavailable`))
+      return
+    }
+    for (const s of this.suppliers) {
+      const served = await s.chatCompletions(req, res)
+      if (served) return
+    }
+    writeJson(res, 503, openAIError('no_healthy_supplier', 'all suppliers unavailable'))
+  }
+
+  /** 把 model 改写为组合选中的模型名后尝试供应商。 */
+  private async chatWithModel(req: ChatRequest, res: ServerResponse, model: string): Promise<boolean> {
+    const clone: ChatRequest = { ...req, model }
+    try {
+      const obj = JSON.parse(req.rawBody) as Record<string, unknown>
+      obj.model = model
+      clone.rawBody = JSON.stringify(obj)
+    } catch {
+      clone.rawBody = req.rawBody
+    }
+    for (const s of this.suppliers) {
+      const served = await s.chatCompletions(clone, res)
+      if (served) return true
+    }
+    return false
+  }
+
+  dispose(): void {
+    for (const s of this.suppliers) s.dispose()
+    this.suppliers = []
+  }
+}

package/src/router/types.ts

@@ -0,0 +1,85 @@
+/**
+ * 供应商（supplier）抽象 —— dsh-router 路由器本体对接的外部通道。
+ * 每个供应商提供 OpenAI 兼容的 chat/models，并暴露面板状态。
+ * 仿 9router：供应商 = 一种"免费/付费"通道；dsh-router 在其上做路由。
+ */
+import type { ServerResponse } from 'node:http'
+
+/** 面板展示的账号状态（脱敏）。 */
+export interface SupplierAccount {
+  uid: string
+  nickname?: string
+  credits: number
+  cooling: boolean
+  until?: string
+  reason?: string
+  disabled: boolean
+  err_count?: number
+}
+
+/** 供应商面板状态。 */
+export interface SupplierStatus {
+  id: string
+  name: string
+  accounts: SupplierAccount[]
+}
+
+/** OpenAI 模型条目。 */
+export interface ModelInfo {
+  id: string
+  context_length?: number
+}
+
+/** 面板展示的模型（含启用状态）。 */
+export interface ModelWithEnabled extends ModelInfo {
+  enabled: boolean
+  /** 是否为自定义模型（可删除）。 */
+  custom?: boolean
+}
+
+/** 组合策略：fallback = 按顺序尝试；round-robin = 轮转。 */
+export type ComboStrategy = 'fallback' | 'round-robin'
+
+/** 组合：命名的一组模型，路由时按策略（回退/轮询）命中其中一个。 */
+export interface Combo {
+  id: string
+  name: string
+  strategy: ComboStrategy
+  models: string[]
+}
+
+/** 一次 /v1/chat/completions 请求。 */
+export interface ChatRequest {
+  /** 原始请求体 JSON 字符串。 */
+  rawBody: string
+  stream: boolean
+  model: string
+}
+
+/**
+ * 供应商接口。chatCompletions 直接向 res 写响应（流式 SSE 或 JSON），
+ * 成功返回 true；返回 false 表示"该供应商无健康账号可服务"（触发路由器
+ * 轮换到下一个供应商）。写响应后不得再改 res。
+ */
+export interface Supplier {
+  readonly id: string
+  readonly name: string
+  /** 优先级：数字越小越优先（免费通道优先）。 */
+  readonly priority: number
+  /** 图标（URL 或 SVG data URI），面板供应商卡片显示。可选。 */
+  readonly icon?: string
+  status(): SupplierStatus
+  listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[]
+  /** 面板展示的模型（含启用/自定义标记）。 */
+  modelsWithEnabled(): Promise<ModelWithEnabled[]> | ModelWithEnabled[]
+  /** 供应商前缀（模型完整名 = alias/id）。 */
+  getAlias(): string
+  /** 用户手动添加的模型 id（可选，/v1/models 用它聚合自定义模型）。 */
+  customModelIds?(): string[]
+  chatCompletions(req: ChatRequest, res: ServerResponse): Promise<boolean>
+  /** 测试模型（验证上游真实可用，必要差异化能力）。 */
+  testModel(id: string): Promise<{ ok: boolean; error?: string }>
+  /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
+  removeLink?(uid: string): Promise<boolean>
+  dispose(): void
+}