@fonlan/dsh-model-router 0.1.0

package/src/client/settings-section.tsx

@@ -0,0 +1,235 @@
+/**
+ * The Model Router settings page: one card per merged model, provider chips
+ * that switch the active route on click and reorder by native HTML5 drag &
+ * drop (preference order for future automatic failover). All reads/mutations
+ * go through the plugin's fenced API; the server persists through the
+ * settings service, so a switch here is live for the next request globally.
+ */
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Translate } from '@deepseek-ai/dsh-client-ui-slots'
+import { LOCALE_NS } from './locales'
+import { api, type ModelRouterState, type RouterModelView } from './api'
+import './settings-section.css'
+
+function arrayMove<T>(list: readonly T[], from: number, to: number): T[] {
+  const next = [...list]
+  const [item] = next.splice(from, 1)
+  next.splice(to, 0, item)
+  return next
+}
+
+function useLocaleRevision(ctx: ClientContext): number {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      try {
+        return ctx.locale.subscribe(onChange)
+      } catch {
+        return () => {}
+      }
+    },
+    [ctx],
+  )
+  const getSnapshot = useCallback(() => {
+    try {
+      return ctx.locale.getLocale().revision
+    } catch {
+      return 0
+    }
+  }, [ctx])
+  return useSyncExternalStore(subscribe, getSnapshot)
+}
+
+export function makeSettingsSection(ctx: ClientContext): () => JSX.Element {
+  // Bound translation is namespace-typed; the section's props use the plain
+  // Translate face (string keys), which the dict satisfies structurally.
+  const t: Translate = (() => {
+    try {
+      return ctx.locale.bind(LOCALE_NS) as unknown as Translate
+    } catch {
+      return (key: string) => key
+    }
+  })()
+
+  return function ModelRouterSettingsSection(): JSX.Element {
+    useLocaleRevision(ctx)
+    const [state, setState] = useState<ModelRouterState | null>(null)
+    const [error, setError] = useState<string | null>(null)
+    const [loading, setLoading] = useState(true)
+    const [busyModel, setBusyModel] = useState<string | null>(null)
+    const [drag, setDrag] = useState<{ modelId: string; index: number } | null>(null)
+
+    const load = useCallback(async () => {
+      setLoading(true)
+      try {
+        setState(await api.state())
+        setError(null)
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : String(cause))
+      } finally {
+        setLoading(false)
+      }
+    }, [])
+
+    useEffect(() => {
+      void load()
+    }, [load])
+
+    const switchActive = useCallback(async (model: RouterModelView, providerId: string) => {
+      if (model.active === providerId) return
+      setBusyModel(model.id)
+      try {
+        setState(await api.switchActive(model.id, providerId))
+        setError(null)
+      } catch (cause) {
+        setError(t('switchFailed', { message: cause instanceof Error ? cause.message : String(cause) }))
+      } finally {
+        setBusyModel(null)
+      }
+    }, [t])
+
+    const reorder = useCallback(async (model: RouterModelView, from: number, to: number) => {
+      if (from === to) return
+      const order = arrayMove(model.order, from, to)
+      setState(prev => prev === null ? prev : {
+        ...prev,
+        models: prev.models.map(m => (m.id === model.id ? { ...m, order } : m)),
+      })
+      setBusyModel(model.id)
+      try {
+        setState(await api.reorder(model.id, order))
+        setError(null)
+      } catch (cause) {
+        setError(t('reorderFailed', { message: cause instanceof Error ? cause.message : String(cause) }))
+        setState(prev => prev === null ? prev : {
+          ...prev,
+          models: prev.models.map(m => (m.id === model.id ? { ...m, order: model.order } : m)),
+        })
+      } finally {
+        setBusyModel(null)
+      }
+    }, [t])
+
+    const models = useMemo(() => state?.models ?? [], [state])
+
+    return (
+      <div className="mr-root">
+        <p className="mr-description">{t('settingsDescription')}</p>
+        <div className="mr-toolbar">
+          <span className="mr-count">{t('modelsCount', { count: models.length })}</span>
+          <button type="button" className="mr-button" onClick={() => void load()} disabled={loading}>
+            {t('refresh')}
+          </button>
+        </div>
+        {error !== null && (
+          <div className="mr-error" role="alert">{error}</div>
+        )}
+        {loading && models.length === 0 && (
+          <div className="mr-empty">{t('loading')}</div>
+        )}
+        {!loading && models.length === 0 && (
+          <div className="mr-empty">{t('empty')}</div>
+        )}
+        <div className="mr-models">
+          {models.map(model => (
+            <ModelCard
+              key={model.id}
+              model={model}
+              t={t}
+              busy={busyModel === model.id}
+              dragging={drag}
+              onDragStart={index => setDrag({ modelId: model.id, index })}
+              onDragEnd={() => setDrag(null)}
+              onDrop={index => {
+                if (drag !== null && drag.modelId === model.id) {
+                  void reorder(model, drag.index, index)
+                }
+                setDrag(null)
+              }}
+              onSwitch={providerId => void switchActive(model, providerId)}
+            />
+          ))}
+        </div>
+      </div>
+    )
+  }
+}
+
+interface ModelCardProps {
+  model: RouterModelView
+  t: Translate
+  busy: boolean
+  dragging: { modelId: string; index: number } | null
+  onDragStart: (index: number) => void
+  onDragEnd: () => void
+  onDrop: (index: number) => void
+  onSwitch: (providerId: string) => void
+}
+
+function ModelCard(props: ModelCardProps): JSX.Element {
+  const { model, t, busy, dragging } = props
+  return (
+    <section className={`mr-card${busy ? ' mr-card-busy' : ''}`}>
+      <header className="mr-card-header">
+        <span className="mr-model-name">{model.name}</span>
+        <span className="mr-model-id">{model.id}</span>
+        <span className="mr-provider-count">{t('providerCount', { count: model.providers.length })}</span>
+      </header>
+      <p className="mr-drag-hint">{t('dragHint')}</p>
+      <ul className="mr-providers">
+        {model.providers.map((provider, index) => {
+          const active = provider.id === model.active
+          const selectable = provider.credentialConfigured
+          const dropTarget = dragging !== null && dragging.modelId === model.id && dragging.index !== index
+          return (
+            <li
+              key={provider.id}
+              className={[
+                'mr-provider',
+                active ? 'mr-provider-active' : '',
+                !selectable ? 'mr-provider-nocred' : '',
+                dropTarget ? 'mr-provider-drop' : '',
+              ].filter(Boolean).join(' ')}
+              draggable={!busy && model.providers.length > 1}
+              title={selectable ? undefined : t('noCredential')}
+              onDragStart={(event) => {
+                props.onDragStart(index)
+                event.dataTransfer.effectAllowed = 'move'
+                try {
+                  event.dataTransfer.setData('text/plain', model.id)
+                } catch {
+                  // drag data is cosmetic for our own handler
+                }
+              }}
+              onDragOver={(event) => {
+                if (dragging !== null && dragging.modelId === model.id && dragging.index !== index) {
+                  event.preventDefault()
+                  event.dataTransfer.dropEffect = 'move'
+                }
+              }}
+              onDrop={(event) => {
+                if (dragging !== null && dragging.modelId === model.id) {
+                  event.preventDefault()
+                  props.onDrop(index)
+                }
+              }}
+              onDragEnd={() => props.onDragEnd()}
+            >
+              <span className="mr-grip" aria-hidden="true">⠿</span>
+              <button
+                type="button"
+                className="mr-provider-button"
+                disabled={!selectable || busy || active}
+                onClick={() => props.onSwitch(provider.id)}
+              >
+                <span className="mr-provider-name">{provider.name}</span>
+                {!selectable && <span className="mr-provider-nocred-label">· {t('noCredential')}</span>}
+              </button>
+              {active && <span className="mr-active-badge">{t('activeBadge')}</span>}
+            </li>
+          )
+        })}
+      </ul>
+    </section>
+  )
+}

package/src/client/slot-augment.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declare this plugin's locale namespace so slot registrations can type-check
+ * the `locale` seat. zh is the key source of truth; en must carry the exact
+ * same key set (checked at runtime by the locale registry).
+ */
+import type { zh } from './locales'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    'model-router': keyof typeof zh
+  }
+}
+
+export {}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @fonlan/dsh-model-router host half: the virtual model-router provider.
+ *
+ * Registers one `model-router` LLM adapter that aggregates every configured
+ * provider and model (strict model-id merge), routes each request to the
+ * model's currently active provider by in-process delegation, persists the
+ * per-model provider order/active config in the `model-router` settings
+ * namespace, and serves the fenced JSON API the web settings page calls.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { ModelRouterService } from './server/service.js'
+import { registerApiRoutes } from './server/rpc.js'
+
+export const name = '@fonlan/dsh-model-router'
+
+// The llm service is part of dsh-base (required); the settings service and
+// web server are attached opportunistically so the router works in web, CLI,
+// and headless profiles alike (headless profiles route by config but expose
+// no settings page).
+export const inject = ['llm']
+
+export const Config = z.object({})
+
+export function apply(ctx: Context): void {
+  const service = new ModelRouterService(ctx)
+
+  ctx.effect(() => {
+    service.start()
+    return () => service.stop()
+  }, 'model-router: service')
+
+  // The settings-page API only exists where a web server does.
+  ctx.inject(['webServer'], (sctx) => {
+    sctx.effect(() => registerApiRoutes(sctx, service), 'model-router: api routes')
+  })
+}

package/src/server/adapter.ts

@@ -0,0 +1,99 @@
+/**
+ * The virtual `model-router` LLM adapter. Registered for the single provider
+ * route `model-router`, it advertises the merged catalog and, at request time,
+ * rewrites the provider field to the model's currently active provider and
+ * delegates in-process to `ctx.llm.stream` — credentials, retry, streaming
+ * and metering all stay inside the real adapter's pipeline.
+ */
+import { LlmAdapter, LlmError, type LlmRuntime } from '@deepseek-ai/dsh-llm'
+import type {
+  GenerateOptions,
+  LlmModelInfo,
+  LlmProviderInfo,
+  LlmResolvedModelInfo,
+  StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+import {
+  displayProvider,
+  resolveActive,
+  ROUTER_PROVIDER_ID,
+  type MergedModel,
+  type RouterConfigShape,
+} from '../shared/config.js'
+
+/** Facts the adapter reads from the owning service (live, per request). */
+export interface RouterFacts {
+  /** Current merged catalog (refreshed on topology changes). */
+  catalog(): { models: readonly MergedModel[]; byId: ReadonlyMap<string, MergedModel> }
+  /** Current stored router config. */
+  config(): RouterConfigShape
+  /** Provider display names by id. */
+  providerNames(): ReadonlyMap<string, string>
+  /** The LLM runtime to delegate to. */
+  llm(): LlmRuntime
+}
+
+/** One resolved route for a model id. */
+export interface ResolvedRoute {
+  provider: string
+}
+
+/**
+ * Resolve the effective route for one model id: the stored active provider
+ * when still present, otherwise the first remaining order entry, otherwise
+ * the catalog head. Unadvertised model ids do not route.
+ */
+export function routeFor(facts: RouterFacts, modelId: string): ResolvedRoute | null {
+  const merged = facts.catalog().byId.get(modelId)
+  if (merged === undefined) return null
+  const ids = merged.providers.map(provider => provider.provider)
+  const active = resolveActive(facts.config(), modelId, ids)
+  return active === null ? null : { provider: active }
+}
+
+export class ModelRouterAdapter extends LlmAdapter {
+  constructor(private readonly facts: RouterFacts) {
+    super()
+  }
+
+  providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: 'Model Router' }
+  }
+
+  async listModels(_provider: string): Promise<readonly LlmModelInfo[]> {
+    const { models } = this.facts.catalog()
+    const names = this.facts.providerNames()
+    const out: LlmModelInfo[] = []
+    for (const merged of models) {
+      const route = routeFor(this.facts, merged.id)
+      const display = displayProvider(merged, route?.provider)
+      if (display === null) continue
+      out.push({
+        provider: ROUTER_PROVIDER_ID,
+        id: merged.id,
+        name: display.name,
+        description: `via ${names.get(display.provider) ?? display.provider}`,
+      })
+    }
+    return out
+  }
+
+  async resolveModel(_provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo> {
+    const route = routeFor(this.facts, model)
+    if (route === null) {
+      throw new LlmError(`model-router: no provider serves model "${model}"`, 'NO_ADAPTER')
+    }
+    const resolved = await this.facts.llm().resolveModelInfo(route.provider, model, signal)
+    return { ...resolved, provider: ROUTER_PROVIDER_ID }
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const route = routeFor(this.facts, options.model)
+    if (route === null) {
+      throw new LlmError(`model-router: no provider serves model "${options.model}"`, 'NO_ADAPTER')
+    }
+    // In-process delegation: the inner call resolves the real adapter and
+    // runs its full pipeline (retry, waterfall, replay-state stripping).
+    yield* this.facts.llm().stream({ ...options, provider: route.provider })
+  }
+}

package/src/server/catalog.ts

@@ -0,0 +1,128 @@
+/**
+ * Provider discovery for the router: every registered LLM provider route
+ * (minus the router itself) becomes a ProviderInfo, models merge by exact id
+ * through the shared core, and per-provider credential status is detected
+ * generically through the configurable-provider directory + the credentials
+ * seam.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialRef, type CredentialProvider } from '@deepseek-ai/dsh-credentials'
+import type { SettingsProvider } from '@deepseek-ai/dsh-settings'
+import { mergeModels, ROUTER_PROVIDER_ID, type MergedModel, type ProviderInfo } from '../shared/config.js'
+
+/** Live router catalog: everything the router can advertise and route to. */
+export interface RouterCatalog {
+  /** All providers (minus the router) in registration order. */
+  providers: ProviderInfo[]
+  /** Provider id → human display name (configurable-directory name when known). */
+  providerNames: Map<string, string>
+  /** Models merged by exact id across providers. */
+  models: MergedModel[]
+  /** Model id → merged model. */
+  byId: Map<string, MergedModel>
+  /** Provider id → whether the provider currently has usable credentials. */
+  credentialConfigured: Map<string, boolean>
+}
+
+const EMPTY_CATALOG: RouterCatalog = {
+  providers: [],
+  providerNames: new Map(),
+  models: [],
+  byId: new Map(),
+  credentialConfigured: new Map(),
+}
+
+interface ConfigurableEntry {
+  provider: string
+  displayName: string
+  settingsNs: string
+  settingsPath: readonly string[]
+}
+
+/** Read the resolved value of another plugin's settings section, if registered. */
+function settingsSection(ctx: Context, ns: string): unknown {
+  try {
+    return (ctx.settings as SettingsProvider).get(ns as never)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Determine whether one provider has usable credentials. Generic: the
+ * configurable-provider directory names the settings section + path where the
+ * provider's profile (and its optional apiKeyEnv) lives; the credentials seam
+ * answers whether that reference currently resolves. Providers without a
+ * directory entry or without an apiKeyEnv answer "configured" (unknown —
+ * never gray out what we cannot verify).
+ */
+async function detectCredentialConfigured(
+  ctx: Context,
+  entry: ConfigurableEntry | undefined,
+): Promise<boolean> {
+  if (entry === undefined) return true
+  const section = settingsSection(ctx, entry.settingsNs)
+  let profile: unknown = section
+  for (const key of entry.settingsPath) {
+    if (typeof profile !== 'object' || profile === null) {
+      profile = undefined
+      break
+    }
+    profile = (profile as Record<string, unknown>)[key]
+  }
+  const apiKeyEnv = typeof profile === 'object' && profile !== null
+    ? (profile as Record<string, unknown>).apiKeyEnv
+    : undefined
+  if (typeof apiKeyEnv !== 'string' || apiKeyEnv.trim() === '') return true
+  let credentials: CredentialProvider | undefined
+  try {
+    credentials = ctx.get('credentials') as CredentialProvider | undefined
+  } catch {
+    credentials = undefined
+  }
+  if (credentials === undefined) return true
+  try {
+    return (await credentials.describe(credentialRef(apiKeyEnv.trim()))).configured
+  } catch {
+    return true
+  }
+}
+
+/** Rebuild the live router catalog from the LLM registry. */
+export async function buildCatalog(ctx: Context): Promise<RouterCatalog> {
+  const routes = ctx.llm.listProviders().filter(provider => provider.id !== ROUTER_PROVIDER_ID)
+  const directory = new Map<string, ConfigurableEntry>(
+    ctx.llm.listConfigurableProviders().map(entry => [entry.provider, {
+      provider: entry.provider,
+      displayName: entry.displayName,
+      settingsNs: entry.settingsNs,
+      settingsPath: entry.settingsPath,
+    }]),
+  )
+
+  const providers: ProviderInfo[] = []
+  const providerNames = new Map<string, string>()
+  const credentialConfigured = new Map<string, boolean>()
+
+  for (const route of routes) {
+    const entry = directory.get(route.id)
+    providerNames.set(route.id, entry?.displayName || route.name || route.id)
+    const seen = new Set<string>()
+    const models: Array<{ id: string; name: string; contextWindow?: number; maxTokens?: number }> = []
+    try {
+      for (const model of await ctx.llm.listModels(route.id)) {
+        if (seen.has(model.id)) continue
+        seen.add(model.id)
+        models.push({ id: model.id, name: model.name })
+      }
+    } catch {
+      // provider whose catalog is unavailable contributes no models
+    }
+    providers.push({ id: route.id, name: route.name, models })
+    credentialConfigured.set(route.id, await detectCredentialConfigured(ctx, entry))
+  }
+
+  const models = mergeModels(providers)
+  const byId = new Map(models.map(model => [model.id, model]))
+  return { providers, providerNames, models, byId, credentialConfigured }
+}

package/src/server/rpc.ts

@@ -0,0 +1,147 @@
+/**
+ * Fenced JSON API under /plugins/@fonlan/dsh-model-router/api/<method> for the
+ * web settings page. Same browser-trust fence as the /api gateway and the
+ * task-kanban plugin: loopback Host-header or configured trustedHosts,
+ * same-origin browser markers.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { ModelRouterService } from './service.js'
+
+const API_PREFIX = '/plugins/@fonlan/dsh-model-router/api'
+
+// ── browser-trust fence (mirrors dsh-client-connection's api-request-trust) ──
+
+function header(headers: IncomingMessage['headers'], name: string): string | undefined {
+  const value = headers[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every(p => /^\d{1,3}$/.test(p) && Number(p) <= 255)
+}
+
+function isTrustedApiRequest(req: IncomingMessage, trustedHosts: readonly string[]): boolean {
+  const host = header(req.headers, 'host')
+  if (host === undefined) return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname) && !trustedHosts.includes(hostUrl.host) && !trustedHosts.includes(hostUrl.hostname)) {
+    return false
+  }
+  if (header(req.headers, 'sec-fetch-site') === 'cross-site') return false
+  const origin = header(req.headers, 'origin')
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+function trustedHostsOf(ctx: Context): string[] {
+  for (const entry of ctx.get('loader')?.entries?.() ?? []) {
+    if (entry.options?.name === 'connection') {
+      const config = entry.options.config as { trustedHosts?: string[] } | undefined
+      return config?.trustedHosts ?? []
+    }
+  }
+  return []
+}
+
+// ── wire helpers ────────────────────────────────────────────────────────────
+
+function writeJson(res: ServerResponse, body: unknown): void {
+  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(body))
+}
+
+function writeError(res: ServerResponse, code: string, message: string, status = 400): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify({ ok: false, error: { code, message } }))
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  const raw = Buffer.concat(chunks).toString('utf8')
+  if (raw.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+// ── routes ──────────────────────────────────────────────────────────────────
+
+export function registerApiRoutes(ctx: Context, service: ModelRouterService): () => void {
+  const fence = (req: IncomingMessage): boolean => isTrustedApiRequest(req, trustedHostsOf(ctx))
+  const disposers: Array<() => void> = []
+
+  const route = (name: string, handler: (payload: Record<string, unknown>) => Promise<unknown>): void => {
+    disposers.push(ctx.webServer.register({
+      kind: 'prefix',
+      path: `${API_PREFIX}/${name}`,
+      handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+        if (!fence(req)) {
+          writeError(res, 'forbidden', 'forbidden', 403)
+          return
+        }
+        if (req.method !== 'POST' && req.method !== 'GET') {
+          writeError(res, 'method', 'method not allowed', 405)
+          return
+        }
+        const payload = await readJsonBody(req)
+        try {
+          const value = await handler(payload)
+          writeJson(res, { ok: true, value })
+        } catch (error) {
+          writeError(res, 'error', error instanceof Error ? error.message : String(error))
+        }
+      },
+    }))
+  }
+
+  route('state', async () => service.state())
+
+  route('switch-active', async (p) => {
+    const modelId = requireString(p.modelId, 'modelId')
+    const providerId = requireString(p.providerId, 'providerId')
+    await service.switchActive(modelId, providerId)
+    return service.state()
+  })
+
+  route('reorder', async (p) => {
+    const modelId = requireString(p.modelId, 'modelId')
+    if (!Array.isArray(p.order) || !p.order.every((id): id is string => typeof id === 'string')) {
+      throw new Error('order 必须是提供商 id 数组')
+    }
+    await service.reorder(modelId, p.order)
+    return service.state()
+  })
+
+  route('refresh', async () => {
+    await service.refreshAndReconcile()
+    return service.state()
+  })
+
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+function requireString(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${name} 不能为空`)
+  }
+  return value
+}