dsh-model-capability-sync 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "dsh-model-capability-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Fill model capabilities (context window, output cap, input modalities, reasoning efforts) into an already-configured DeepSeek Harness LLM provider by matching gateway model ids against the models.dev catalog. Host half fetches and matches; browser half previews and writes through the official settings service.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "scripts",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "dsh": "^0.2.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "npm run build:host && npm run build:client",
+    "build:host": "node scripts/build-host.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "typecheck": "npm run typecheck:host && npm run typecheck:client",
+    "typecheck:host": "tsc -p tsconfig.json --noEmit",
+    "typecheck:client": "tsc -p tsconfig.client.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run verify:package",
+    "verify:package": "node scripts/verify-package.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "models.dev",
+    "capability",
+    "context-window",
+    "multimodal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zyi07/dsh-model-capability-sync.git"
+  },
+  "homepage": "https://github.com/zyi07/dsh-model-capability-sync#readme",
+  "bugs": {
+    "url": "https://github.com/zyi07/dsh-model-capability-sync/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^18.2.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.2"
+  }
+}

package/scripts/build-client.mjs

@@ -0,0 +1,42 @@
+/**
+ * Browser-half build: one closure-factory module registered on the shell's
+ * module loader — `window.__ModuleLoader__.load({ id, factory })`. React and
+ * the JSX runtime are the only runtime externals the shell's module table
+ * supplies; every `@deepseek-ai/*` import in the source is type-only and is
+ * erased here.
+ */
+import { build } from 'esbuild'
+
+const ID = 'dsh-model-capability-sync'
+
+const CLIENT_EXTERNALS = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+]
+
+await build({
+  entryPoints: ['src/client/index.ts'],
+  bundle: true,
+  format: 'cjs',
+  platform: 'browser',
+  target: 'es2022',
+  jsx: 'automatic',
+  outfile: 'lib/client.js',
+  sourcemap: true,
+  legalComments: 'none',
+  external: CLIENT_EXTERNALS,
+  define: {
+    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'production'),
+  },
+  banner: {
+    js: [
+      `window.__ModuleLoader__.load({ id: ${JSON.stringify(ID)}, factory: (require) => {`,
+      'var module = { exports: {} }; var exports = module.exports;',
+    ].join('\n'),
+  },
+  footer: { js: 'return module.exports; } });' },
+})
+
+console.log(`${ID}: wrote lib/client.js`)

package/scripts/build-host.mjs

@@ -0,0 +1,22 @@
+/**
+ * Host-half build: bundle `src/index.ts` (and its relative modules) into one
+ * ESM file. Every bare specifier stays external, so the plugin resolves
+ * `@deepseek-ai/*` from the host installation at load time — the same contract
+ * the official adapters use.
+ */
+import { build } from 'esbuild'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+  target: 'node22',
+  outfile: 'lib/index.js',
+  sourcemap: true,
+  legalComments: 'none',
+  packages: 'external',
+  logLevel: 'info',
+})
+
+console.log('dsh-model-capability-sync: wrote lib/index.js')

package/scripts/smoke.mjs

@@ -0,0 +1,56 @@
+/**
+ * Offline-ish smoke test: download the real models.dev catalog and run the
+ * matcher + mapper over the model ids this machine has configured.
+ *
+ * Run with `node --experimental-strip-types scripts/smoke.mjs` (Node 24 strips
+ * types by default). It reads ids from the desktop profile patch when present
+ * and falls back to a built-in sample, so it also works on a fresh checkout.
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { loadCatalog } from '../src/catalog.ts'
+import { matchModel } from '../src/match.ts'
+import { capabilitiesOf } from '../src/mapping.ts'
+
+const PATCH = 'C:/Users/19603/.dsh/profiles/desktop/cordis.patch.yml'
+
+/** Pull `- id:` lines out of the llm-newapi catalog block, without a YAML dependency. */
+function idsFromPatch(path) {
+  if (!existsSync(path)) return undefined
+  const text = readFileSync(path, 'utf8')
+  const start = text.indexOf('- id: llm-newapi')
+  if (start === -1) return undefined
+  const block = text.slice(start)
+  const ids = [...block.matchAll(/^\s+- id: (\S+)$/gm)].map(match => match[1])
+  return ids.length > 0 ? ids : undefined
+}
+
+const ids = idsFromPatch(PATCH) ?? [
+  'work-gj/deepseek-v4.1-flash',
+  'gemini/gemini-3.8-flash-high',
+  'qoder-gj/Qwen3.8-Flash',
+  'beichenapi/gpt-6',
+  'openai/gpt-4o',
+]
+
+const catalog = await loadCatalog({ refresh: true })
+console.log(`catalog: ${catalog.modelCount} models, fetched ${new Date(catalog.fetchedAt).toISOString()}`)
+
+const stats = { total: 0, matched: 0, image: 0, unmatched: [] }
+const sample = []
+for (const id of ids) {
+  stats.total += 1
+  const match = matchModel(catalog, id)
+  if (match === undefined) {
+    stats.unmatched.push(id)
+    continue
+  }
+  stats.matched += 1
+  const entry = catalog.byId.get(match.modelId)?.find(candidate => candidate.provider === match.provider)
+  const fields = entry === undefined ? {} : capabilitiesOf(entry)
+  if (fields.input?.includes('image')) stats.image += 1
+  if (sample.length < 6) sample.push({ id, via: match.via, to: `${match.provider}/${match.modelId}`, fields })
+}
+
+console.log(`matched ${stats.matched}/${stats.total}, image-capable ${stats.image}, unmatched ${stats.unmatched.length}`)
+console.log('sample:', JSON.stringify(sample, null, 1))
+if (stats.unmatched.length > 0) console.log('unmatched ids:', stats.unmatched.join(', '))

package/scripts/verify-package.mjs

@@ -0,0 +1,64 @@
+/**
+ * Release-hygiene check for the publishable surface.
+ *
+ * Runs against the source tree, not a tarball, so it is fast enough to keep in
+ * the release checklist. It catches the mistakes that only show up after a
+ * publish: a build artifact missing from the tree, a `dsh` declaration that
+ * points nowhere, a client bundle without the loader wrapper, a manifest field
+ * the host would reject.
+ *
+ *   node scripts/verify-package.mjs
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.cwd()
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const checks = []
+const check = (label, ok, detail = '') => {
+  checks.push({ label, ok, detail })
+}
+
+check('name 是合法 npm 包名', /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(manifest.name), manifest.name)
+check('version 是精确 SemVer', /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?$/.test(manifest.version), manifest.version)
+check('未声明 private', manifest.private !== true)
+check('publishConfig.access 为 public', manifest.publishConfig?.access === 'public')
+check('engines.dsh 已声明', typeof manifest.engines?.dsh === 'string', manifest.engines?.dsh)
+check('main 指向存在的文件', typeof manifest.main === 'string' && existsSync(join(root, manifest.main)), manifest.main)
+check('exports["./client"] 存在', existsSync(join(root, 'lib/client.js')))
+check('LICENSE 文件存在', existsSync(join(root, 'LICENSE')))
+check('README 存在', existsSync(join(root, 'README.md')))
+check('repository.url 已声明', typeof manifest.repository?.url === 'string', manifest.repository?.url)
+check('homepage 是绝对 URL', typeof manifest.homepage === 'string' && URL.canParse(manifest.homepage), manifest.homepage)
+check('bugs.url 是绝对 URL', typeof manifest.bugs?.url === 'string' && URL.canParse(manifest.bugs.url), manifest.bugs?.url)
+
+const patchPath = manifest.dsh?.bundle?.patch
+check('dsh.bundle.patch 已声明', typeof patchPath === 'string', patchPath)
+check('dsh.bundle.patch 文件存在', typeof patchPath === 'string' && existsSync(join(root, patchPath)))
+check('dsh.client.platform 为 web', manifest.dsh?.client?.platform === 'web')
+
+if (typeof patchPath === 'string' && existsSync(join(root, patchPath))) {
+  const patch = readFileSync(join(root, patchPath), 'utf8')
+  check('patch 里插入了本插件', patch.includes('model-capability-sync'))
+}
+
+if (existsSync(join(root, 'lib/client.js'))) {
+  const client = readFileSync(join(root, 'lib/client.js'), 'utf8')
+  check('client 带 __ModuleLoader__ 包装', client.includes('__ModuleLoader__'))
+  check('client 只外部化 react', !/require\("(?!react)/.test(client))
+}
+
+const hostBundle = join(root, manifest.main ?? '')
+if (existsSync(hostBundle)) {
+  const host = readFileSync(hostBundle, 'utf8')
+  check('宿主产物不 import 第三方包', !/^import .* from "(?!node:|\.)/m.test(host))
+}
+
+for (const entry of manifest.files ?? []) {
+  check(`files 条目存在：${entry}`, existsSync(join(root, entry)))
+}
+
+const failed = checks.filter(entry => !entry.ok)
+for (const entry of checks) console.log(`${entry.ok ? 'OK  ' : 'FAIL'} ${entry.label}${entry.detail === '' ? '' : ` (${entry.detail})`}`)
+console.log(failed.length === 0 ? `\n全部通过：${String(checks.length)} 项` : `\n失败 ${String(failed.length)} 项`)
+process.exitCode = failed.length === 0 ? 0 : 1

package/scripts/warm-cache.mjs

@@ -0,0 +1,15 @@
+/**
+ * Warm the on-disk catalog copy.
+ *
+ * The host process may sit behind a network the command line does not share,
+ * so the page falls back to `~/.dsh/model-capability-sync/catalog.json`. This
+ * script fills that file from a machine that can reach models.dev, which makes
+ * the first page load work even when the app itself cannot download.
+ *
+ *   node --experimental-strip-types scripts/warm-cache.mjs
+ */
+import { loadCatalog } from '../src/catalog.ts'
+
+const catalog = await loadCatalog({ refresh: true })
+console.log(`cached ${String(catalog.modelCount)} models from ${new Date(catalog.fetchedAt).toISOString()}`)
+console.log('file: ~/.dsh/model-capability-sync/catalog.json')

package/src/catalog.ts

@@ -0,0 +1,204 @@
+/**
+ * The models.dev catalog: download, cache, and index for lookup.
+ *
+ * One shared `api.json` carries every provider's model facts. The download
+ * happens host-side so the browser never makes a cross-origin request, and a
+ * forward proxy stays a plain HTTP proxy the host can use.
+ *
+ * A copy also lands on disk. The host process may sit behind a network the
+ * command line does not share — a proxy, a firewall, a flaky route — and a
+ * settings page that cannot open because one download failed is worse than a
+ * page reading a slightly old catalog. The disk copy is the fallback; its age
+ * is reported so the answer is never silently stale.
+ * @module dsh-model-capability-sync/catalog
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const CATALOG_URL = 'https://models.dev/api.json'
+/** Reuse one download for this long; a `refresh` request bypasses it. */
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000
+/** Attempts per download before falling back to the disk copy. */
+const DOWNLOAD_ATTEMPTS = 3
+/** Pause between attempts: long enough to outlast a reset connection. */
+const RETRY_DELAY_MS = 600
+
+/** One model entry as models.dev publishes it (only the fields we read). */
+export interface ModelsDevModel {
+  id?: string
+  name?: string
+  description?: string
+  /** Whether the model accepts reasoning control at all. */
+  reasoning?: boolean
+  /** Accepted input/output media; `input` is the modality list we map. */
+  modalities?: { input?: string[]; output?: string[] }
+  /** Capacity facts: token counts. */
+  limit?: { context?: number; input?: number; output?: number }
+  /** Reasoning control shapes; the `effort` type carries the selectable levels. */
+  reasoning_options?: Array<{ type?: string; values?: Array<string | null> }>
+}
+
+/** One catalog entry with its provider id attached. */
+export interface CatalogEntry {
+  provider: string
+  id: string
+  model: ModelsDevModel
+}
+
+/** A loaded catalog plus its lookup indexes. */
+export interface Catalog {
+  fetchedAt: number
+  modelCount: number
+  /** True when this copy came from disk because the download failed. */
+  stale?: boolean
+  /** Exact id → entries (a bare id can appear under several providers). */
+  byId: Map<string, CatalogEntry[]>
+  /** Lower-cased id → entries, for case-insensitive vendor spellings. */
+  byFolded: Map<string, CatalogEntry[]>
+}
+
+let cache: { catalog: Catalog; proxyUrl: string | undefined } | undefined
+
+/** Where the on-disk copy lives, mirroring the other plugins' data roots. */
+const CACHE_FILE = join(homedir(), '.dsh', 'model-capability-sync', 'catalog.json')
+
+/** The on-disk envelope: the raw catalog body plus when it was fetched. */
+interface DiskCache {
+  fetchedAt: number
+  source: string
+  body: unknown
+}
+
+/** Persist one successful download; a cache write must never fail the request. */
+async function writeDiskCache(body: unknown): Promise<void> {
+  try {
+    const envelope: DiskCache = { fetchedAt: Date.now(), source: CATALOG_URL, body }
+    await mkdir(dirname(CACHE_FILE), { recursive: true })
+    await writeFile(CACHE_FILE, JSON.stringify(envelope), 'utf8')
+  } catch {
+    // A read-only or full home directory only costs the fallback, not the answer.
+  }
+}
+
+/** Read the on-disk copy, or undefined when there is none to trust. */
+async function readDiskCache(): Promise<DiskCache | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(CACHE_FILE, 'utf8')) as Partial<DiskCache>
+    if (typeof parsed.fetchedAt !== 'number' || parsed.body === undefined) return undefined
+    return { fetchedAt: parsed.fetchedAt, source: typeof parsed.source === 'string' ? parsed.source : CATALOG_URL, body: parsed.body }
+  } catch {
+    return undefined
+  }
+}
+
+/** Wait between download attempts. */
+function pause(ms: number): Promise<void> {
+  return new Promise((resolve) => { setTimeout(resolve, ms) })
+}
+
+/** Push one entry into an index bucket. */
+function push(index: Map<string, CatalogEntry[]>, key: string, entry: CatalogEntry): void {
+  const bucket = index.get(key)
+  if (bucket === undefined) index.set(key, [entry])
+  else bucket.push(entry)
+}
+
+/** Build both indexes from the raw catalog body. */
+function buildCatalog(body: unknown, fetchedAt: number): Catalog {
+  const byId = new Map<string, CatalogEntry[]>()
+  const byFolded = new Map<string, CatalogEntry[]>()
+  let modelCount = 0
+  if (typeof body === 'object' && body !== null) {
+    for (const [provider, value] of Object.entries(body as Record<string, unknown>)) {
+      const models = (value as { models?: Record<string, ModelsDevModel> } | undefined)?.models
+      if (typeof models !== 'object' || models === null) continue
+      for (const [id, model] of Object.entries(models)) {
+        if (id.length === 0) continue
+        modelCount += 1
+        const entry: CatalogEntry = { provider, id, model }
+        push(byId, id, entry)
+        push(byFolded, id.toLowerCase(), entry)
+      }
+    }
+  }
+  if (modelCount === 0) throw new Error('models.dev returned a catalog with no models')
+  return { fetchedAt, modelCount, byId, byFolded }
+}
+
+/** Download the catalog body, optionally through a forward proxy. */
+async function download(proxyUrl: string | undefined, signal: AbortSignal | undefined): Promise<unknown> {
+  if (proxyUrl === undefined || proxyUrl.length === 0) {
+    const response = await fetch(CATALOG_URL, { signal })
+    if (!response.ok) throw new Error(`models.dev download failed (HTTP ${String(response.status)})`)
+    return await response.json()
+  }
+  // The proxy path needs undici's dispatcher. It ships with the harness
+  // runtime; a missing copy is reported instead of silently going direct. The
+  // specifier stays a runtime value so this package needs no undici types.
+  interface UndiciFace {
+    fetch(input: string, init?: Record<string, unknown>): Promise<Response>
+    ProxyAgent: new (url: string) => unknown
+  }
+  const specifier: string = 'undici'
+  let undici: UndiciFace
+  try {
+    undici = await import(specifier) as UndiciFace
+  } catch {
+    throw new Error('a proxy URL was set but the host cannot load "undici"; clear the proxy or install it')
+  }
+  const dispatcher = new undici.ProxyAgent(proxyUrl)
+  const response = await undici.fetch(CATALOG_URL, { signal, dispatcher })
+  if (!response.ok) throw new Error(`models.dev download through the proxy failed (HTTP ${String(response.status)})`)
+  return await response.json()
+}
+
+/**
+ * Load the catalog, reusing the cached copy unless it expired or the caller
+ * asked for a refresh.
+ *
+ * A failed download is retried, then answered from the on-disk copy with
+ * `stale` set. Only when both paths fail does this throw, and the message
+ * names the network reason so the page can show something actionable.
+ * @param options - refresh flag and optional proxy URL.
+ * @param signal - caller cancellation.
+ * @returns the indexed catalog.
+ */
+export async function loadCatalog(
+  options: { refresh?: boolean; proxyUrl?: string } = {},
+  signal?: AbortSignal,
+): Promise<Catalog> {
+  const now = Date.now()
+  const fresh = cache !== undefined
+    && cache.proxyUrl === options.proxyUrl
+    && now - cache.catalog.fetchedAt < CACHE_TTL_MS
+  if (options.refresh !== true && fresh && cache !== undefined) return cache.catalog
+
+  let lastError: unknown
+  for (let attempt = 1; attempt <= DOWNLOAD_ATTEMPTS; attempt += 1) {
+    try {
+      const body = await download(options.proxyUrl, signal)
+      const catalog = buildCatalog(body, Date.now())
+      cache = { catalog, proxyUrl: options.proxyUrl }
+      void writeDiskCache(body)
+      return catalog
+    } catch (error) {
+      if (signal?.aborted === true) throw error
+      lastError = error
+      if (attempt < DOWNLOAD_ATTEMPTS) await pause(RETRY_DELAY_MS)
+    }
+  }
+
+  const disk = await readDiskCache()
+  if (disk !== undefined) {
+    try {
+      const catalog: Catalog = { ...buildCatalog(disk.body, disk.fetchedAt), stale: true }
+      cache = { catalog, proxyUrl: options.proxyUrl }
+      return catalog
+    } catch {
+      // A corrupt copy is no better than no copy; report the download failure.
+    }
+  }
+  const reason = lastError instanceof Error ? lastError.message : String(lastError)
+  throw new Error(`models.dev catalog unavailable (${reason}) and no local copy exists`)
+}