@goodandready/dsh-model-sync 0.3.12 → 0.3.13

package/README.md

@@ -107,6 +107,21 @@ dsh plugin --profile web add @goodandready/dsh-model-sync
 
 ---
 
+## 🚀 Enhancements in v0.3.13
+
+* ⚡ **Zero-Overhead Polling via HTTP ETag / 304 Not Modified**:
+  * Implemented weak ETag generation for `GET /dsh-model-sync/status`. When the Web UI polls every 15 seconds, unchanged catalogs receive an empty `304 Not Modified` response, eliminating redundant JSON serialization and network traffic.
+* 🌐 **Upstream Conditional HTTP Requests**:
+  * Added `If-None-Match` and `If-Modified-Since` headers to upstream provider discovery. Catalogs that return `304 Not Modified` resolve instantly from memory cache without re-parsing or diff re-computation.
+* 🎯 **Debounced Search & Memoized Sorting in UI**:
+  * Introduced 150ms input debouncing and `React.useMemo` for model filtering/sorting in the model picker, ensuring fluid search responsiveness on catalogs with hundreds of models.
+* 🧠 **Expanded Capability Detection**:
+  * Added detection for modern reasoning models (`DeepSeek-R1`, `o1`, `o3-mini`, `thinking`) and specialized code generation models (`code`), plus support for the `code` capability filter in policy matching and UI picker.
+* 🛡️ **Exponential Retry Jitter**:
+  * Enhanced `retryWithBackoff` with randomized jitter (`0.5 - 1.0` multiplier) to prevent thundering-herd effects on provider APIs during network hiccups or rate limits.
+
+---
+
 ## 🛠️ Enhancements & Fixes in v0.3.11
 
 * 🗂️ **Streamlined Settings UI Surface**:

package/README.ru.md

@@ -84,6 +84,21 @@ dsh plugin --profile web add @goodandready/dsh-model-sync
 
 ---
 
+## 🚀 Улучшения в v0.3.13
+
+* ⚡ **ETag / 304 Not Modified для фонового опроса UI**:
+  * Реализована генерация слабого ETag для маршрута `GET /dsh-model-sync/status`. При 15-секундном опросе UI возвращается пустой ответ `304 Not Modified`, исключающий холостую сериализацию JSON и сетевой оверхед.
+* 🌐 **Условные запросы к API провайдеров (Upstream Conditional Requests)**:
+  * Передача заголовков `If-None-Match` и `If-Modified-Since` в generic и declarative адаптерах. При ответе `304` от апстрим-провайдера мгновенно возвращается кэш без повторного парсинга моделей.
+* 🎯 **Debounce поиска и useMemo в веб-интерфейсе**:
+  * Добавлен debounce (150 мс) на ввод в строку поиска и мемоизация `React.useMemo` для фильтрации и сортировки моделей в пикере, обеспечивая плавный отклик без микрофризов.
+* 🧠 **Расширенное распознавание возможностей моделей**:
+  * Распознавание современных reasoning/thinking моделей (`DeepSeek-R1`, `o1`, `o3-mini`, CoT) и моделей для кода (`code`), поддержка тега `code` в политиках фильтрации.
+* 🛡️ **Экспоненциальный джиттер при повторах**:
+  * Защита от thundering herd с помощью случайного коэффициента джиттера (`0.5 - 1.0`) при повторных запросах к API провайдеров.
+
+---
+
 ## 🛠️ Улучшения и исправления в v0.3.11
 
 * 🗂️ **Чистый интерфейс настроек (DSH Design Contract)**:

package/README.zh.md

@@ -25,6 +25,21 @@
 
 ---
 
+## 🚀 v0.3.13 性能与质量优化
+
+* ⚡ **ETag / 304 Not Modified 状态缓存**:
+  * 为 `GET /dsh-model-sync/status` 提供弱 ETag 支持。UI 定时 15 秒轮询时直接返回 `304 Not Modified`，避免多余 JSON 序列化与流量损耗。
+* 🌐 **上游条件请求 (Upstream Conditional Requests)**:
+  * 向提供商 API 发送 `If-None-Match` / `If-Modified-Since`。当提供商返回 304 时直接命中缓存，无需重复解析。
+* 🎯 **模型搜索防抖与 useMemo 优化**:
+  * 模型选择器搜索框加入 150ms debounce 与 `React.useMemo` 缓存，大幅提升大模型列表下的筛选与排序流畅度。
+* 🧠 **扩展模型能力检测**:
+  * 支持现代推理/思考模型（DeepSeek-R1、o1/o3-mini）及代码专用模型（`code`）的能力标记与策略过滤。
+* 🛡️ **带抖动的指数退避重试 (Exponential Jitter)**:
+  * 在 API 失败重试时加入随机抖动系数，有效防止高并发下的惊群效应。
+
+---
+
 ## ⚡ 插件概览
 
 **`dsh-model-sync`** 保持 **DeepSeek Harness** 模型选单与上游大模型服务商实时同步。

package/lib/adapter-registry.js

@@ -5,7 +5,7 @@ import { normalizeModels } from './models.js'
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
 const SAFE_AUTH = new Set(['bearer', 'x-api-key', 'query-key', 'none'])
 const SAFE_PARSERS = new Set(['openai', 'google'])
-const CAPABILITIES = new Set(['vision', 'tools', 'reasoning', 'embeddings'])
+const CAPABILITIES = new Set(['vision', 'tools', 'reasoning', 'embeddings', 'code'])
 const BLOCKED_HEADERS = /authorization|api[_-]?key|token|secret|cookie/i
 
 const PROVIDER_ADAPTERS = Object.freeze({
@@ -120,7 +120,7 @@ export function normalizeAdapterConfig(config, profile = {}) {
   return { endpoint: endpoint.toString(), auth, parse, headers, modelsPath, capabilityMap, fields }
 }
 
-async function requestSpecific(profile, descriptor, { resolveCredential, fetchImpl, signal }) {
+async function requestSpecific(profile, descriptor, { resolveCredential, fetchImpl, signal, etag, lastModified }) {
   const keyRef = profile.apiKeyEnv || profile.credentialRef || profile.apiKeyRef
   const apiKey = keyRef ? await resolveCredential(keyRef) : ''
   const url = new URL(descriptor.endpoint)
@@ -128,11 +128,14 @@ async function requestSpecific(profile, descriptor, { resolveCredential, fetchIm
   if (descriptor.auth === 'bearer' && apiKey) headers.Authorization = 'Bearer ' + apiKey
   if (descriptor.auth === 'x-api-key' && apiKey) headers['x-api-key'] = apiKey
   if (descriptor.auth === 'query-key' && apiKey) url.searchParams.set('key', apiKey)
+  if (etag) headers['If-None-Match'] = etag
+  if (lastModified) headers['If-Modified-Since'] = lastModified
   let response
   try { response = await fetchImpl(url, { headers, signal }) } catch (error) {
     if (error && typeof error === 'object') error.adapterCode = 'endpoint'
     throw error
   }
+  if (response.status === 304) return response
   if (!response.ok) {
     const error = catalogRequestError(response.status, response)
     error.adapterCode = [401, 403].includes(response.status) ? 'auth' : response.status === 429 ? 'rate-limit' : 'http'
@@ -145,6 +148,11 @@ async function fetchSpecific(profile, descriptor, options) {
   let payload
   try {
     const response = await requestSpecific(profile, descriptor, options)
+    if (response.status === 304) {
+      return { notModified: true, etag: response.headers?.get?.('etag') || options.etag, lastModified: response.headers?.get?.('last-modified') || options.lastModified }
+    }
+    const respEtag = response.headers?.get?.('etag') || undefined
+    const respLastMod = response.headers?.get?.('last-modified') || undefined
     const declared = Number(response.headers?.get?.('content-length') ?? NaN)
     if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
       const error = new Error('model catalog response is too large')
@@ -163,7 +171,16 @@ async function fetchSpecific(profile, descriptor, options) {
       throw error
     }
     const rows = parseRows(profile.provider, payload, descriptor)
-    if (Array.isArray(rows) && rows.length > 0) return rows
+    if (Array.isArray(rows) && rows.length > 0) {
+      if (respEtag || respLastMod) {
+        Object.defineProperty(rows, '__httpMeta', {
+          value: { etag: respEtag, lastModified: respLastMod },
+          enumerable: false,
+          configurable: true,
+        })
+      }
+      return rows
+    }
   } catch (error) {
     if (descriptor.defaultModels && Array.isArray(descriptor.defaultModels) && descriptor.defaultModels.length > 0) {
       return normalizeModels(profile.provider, descriptor.defaultModels.map((id) => ({ id })))

package/lib/client.js

@@ -96,7 +96,11 @@ window.__ModuleLoader__.load({
     function ModelSyncSection({ ctx, includeIntro = true }) {
       const locale = useLocale(ctx); const t = locale === 'ru' ? ru : en
       const [status, setStatus] = React.useState(null); const [provider, setProvider] = React.useState(''); const [dryRun, setDryRun] = React.useState(true); const [removeMissing, setRemoveMissing] = React.useState(false); const [busy, setBusy] = React.useState(false); const [error, setError] = React.useState(''); const [credentialStatus, setCredentialStatus] = React.useState(null)
-      const [selectionProvider, setSelectionProvider] = React.useState(''); const [selectionDraft, setSelectionDraft] = React.useState([]); const [capabilityFilter, setCapabilityFilter] = React.useState([]); const [searchQuery, setSearchQuery] = React.useState(''); const [sortBy, setSortBy] = React.useState('name'); const [preview, setPreview] = React.useState(null); const [policyProvider, setPolicyProvider] = React.useState(''); const [policyDraft, setPolicyDraft] = React.useState({ include: '', exclude: '', requireCapabilities: '', denyCapabilities: '' })
+      const [selectionProvider, setSelectionProvider] = React.useState(''); const [selectionDraft, setSelectionDraft] = React.useState([]); const [capabilityFilter, setCapabilityFilter] = React.useState([]); const [searchQuery, setSearchQuery] = React.useState(''); const [debouncedSearchQuery, setDebouncedSearchQuery] = React.useState(''); const [sortBy, setSortBy] = React.useState('name');
+      React.useEffect(() => {
+        const timer = setTimeout(() => { setDebouncedSearchQuery(searchQuery) }, 150);
+        return () => clearTimeout(timer);
+      }, [searchQuery]); const [preview, setPreview] = React.useState(null); const [policyProvider, setPolicyProvider] = React.useState(''); const [policyDraft, setPolicyDraft] = React.useState({ include: '', exclude: '', requireCapabilities: '', denyCapabilities: '' })
       const [pageSize, setPageSize] = React.useState(50); const [quickFilter, setQuickFilter] = React.useState({ context100k: false, cheap: false })
       const scope = React.useMemo(() => (ctx && ctx.settingsScope ? ctx.settingsScope.bind({ namespace: NS }) : undefined), [ctx])
       const snapshot = React.useSyncExternalStore(React.useMemo(() => (cb) => (scope ? scope.subscribe(cb) : () => {}), [scope]), React.useCallback(() => (scope ? scope.getSnapshot() : { status: 'loading' }), [scope]), React.useCallback(() => ({ status: 'loading' }), []))
@@ -148,11 +152,16 @@ window.__ModuleLoader__.load({
       const saveSelection = () => { const row = rows.find((item) => item.provider === selectionProvider); const available = row?.availableModels ?? row?.models ?? []; if (available.length > 0 && selectionDraft.length === 0) { setError(t.selectAtLeastOne); return } const models = selectionDraft.length === available.length ? [] : selectionDraft; setBusy(true); setError(''); fetch(`${API}/selection`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ provider: selectionProvider, models }) }).then(async (r) => { const body = await r.json(); if (!r.ok) throw new Error(body?.error?.message ?? `HTTP ${r.status}`); return body }).then((body) => { setStatus(body); closeSelection() }).catch((e) => setError(String(e?.message ?? e))).finally(() => setBusy(false)) }
       const rollback = (entry, targetProvider) => { if (!window.confirm(t.rollbackConfirm)) return; setBusy(true); setError(''); fetch(`${API}/history/rollback`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ historyId: entry.id, provider: targetProvider }) }).then(async (r) => { const body = await r.json(); if (!r.ok) throw new Error(body?.error?.message ?? `HTTP ${r.status}`); return body }).then(() => load()).catch((e) => setError(String(e?.message ?? e))).finally(() => setBusy(false)) }
       const isNewModel = (model, row) => { const added = status?.lastRun?.results?.find(r=>r.provider===row.provider)?.diff?.added||[]; const isAdded = added.some(m=>m.id===model.id); if(!isAdded) return false; const finishedAt = status?.lastRun?.finishedAt; if(!finishedAt) return false; return (Date.now()-new Date(finishedAt).getTime()) < 7*24*60*60*1000; };
-      const rows = (status?.providers ?? []).filter((row) => row.configured); const selectedRow = rows.find((row) => row.provider === selectionProvider); const choices = selectedRow?.availableModels ?? selectedRow?.models ?? []; const filteredChoicesBase = filterModelsByCapabilities(choices, capabilityFilter);
-      const tokens = searchQuery.trim().toLowerCase().split(/\s+/).filter(Boolean);
-      const searchedChoices = tokens.length ? filteredChoicesBase.filter((m) => { const haystack = (m.id + ' ' + (m.name||'') + ' ' + (m.aliases||[]).join(' ') + ' ' + (m.tags||[]).join(' ') + ' ' + (m.description||'')).toLowerCase(); return tokens.every((tok) => haystack.includes(tok)); }) : filteredChoicesBase;
-      const quickFilteredChoices = searchedChoices.filter((m) => { if (quickFilter.context100k && (!m.contextWindow || m.contextWindow < 100000)) return false; if (quickFilter.cheap && (!m.pricing?.inputPerToken || (m.pricing.inputPerToken * 1000000) > 1.0)) return false; return true; });
-      const filteredChoices = [...quickFilteredChoices].sort((a,b) => { if (sortBy==='price') { const pa=a.pricing?.inputPerToken??Infinity; const pb=b.pricing?.inputPerToken??Infinity; return pa-pb; } if (sortBy==='context') return (b.contextWindow??0)-(a.contextWindow??0); if (sortBy==='date') return (b.firstSeenAt??0)-(a.firstSeenAt??0); return (a.name || a.id || '').localeCompare(b.name || b.id || ''); }); const maxContext = filteredChoices.reduce((max, m) => Math.max(max, m.contextWindow || 0), 0); const minPrice = filteredChoices.reduce((min, m) => m.pricing?.inputPerToken !== undefined ? Math.min(min, m.pricing.inputPerToken) : min, Infinity); const availableCapabilities = [...new Set(choices.flatMap((model) => Object.entries(model?.capabilities ?? {}).filter(([, enabled]) => enabled === true).map(([key]) => key)))].sort(); const visibleChoices = filteredChoices.slice(0, pageSize); const button = (label, onClick, variant) => React.createElement('button', { type: 'button', disabled: busy, onClick, className: 'dms-btn' + (variant ? ' dms-btn-' + variant : '') }, label)
+      const rows = (status?.providers ?? []).filter((row) => row.configured); const selectedRow = rows.find((row) => row.provider === selectionProvider); const choices = selectedRow?.availableModels ?? selectedRow?.models ?? [];
+      const filteredChoices = React.useMemo(() => {
+        const filteredChoicesBase = filterModelsByCapabilities(choices, capabilityFilter);
+        const tokens = debouncedSearchQuery.trim().toLowerCase().split(/\s+/).filter(Boolean);
+        const searchedChoices = tokens.length ? filteredChoicesBase.filter((m) => { const haystack = (m.id + ' ' + (m.name||'') + ' ' + (m.aliases||[]).join(' ') + ' ' + (m.tags||[]).join(' ') + ' ' + (m.description||'')).toLowerCase(); return tokens.every((tok) => haystack.includes(tok)); }) : filteredChoicesBase;
+        const quickFilteredChoices = searchedChoices.filter((m) => { if (quickFilter.context100k && (!m.contextWindow || m.contextWindow < 100000)) return false; if (quickFilter.cheap && (!m.pricing?.inputPerToken || (m.pricing.inputPerToken * 1000000) > 1.0)) return false; return true; });
+        return [...quickFilteredChoices].sort((a,b) => { if (sortBy==='price') { const pa=a.pricing?.inputPerToken??Infinity; const pb=b.pricing?.inputPerToken??Infinity; return pa-pb; } if (sortBy==='context') return (b.contextWindow??0)-(a.contextWindow??0); if (sortBy==='date') return (b.firstSeenAt??0)-(a.firstSeenAt??0); return (a.name || a.id || '').localeCompare(b.name || b.id || ''); });
+      }, [choices, capabilityFilter, debouncedSearchQuery, quickFilter, sortBy]);
+      const maxContext = React.useMemo(() => filteredChoices.reduce((max, m) => Math.max(max, m.contextWindow || 0), 0), [filteredChoices]);
+      const minPrice = React.useMemo(() => filteredChoices.reduce((min, m) => m.pricing?.inputPerToken !== undefined ? Math.min(min, m.pricing.inputPerToken) : min, Infinity), [filteredChoices]); const availableCapabilities = [...new Set(choices.flatMap((model) => Object.entries(model?.capabilities ?? {}).filter(([, enabled]) => enabled === true).map(([key]) => key)))].sort(); const visibleChoices = filteredChoices.slice(0, pageSize); const button = (label, onClick, variant) => React.createElement('button', { type: 'button', disabled: busy, onClick, className: 'dms-btn' + (variant ? ' dms-btn-' + variant : '') }, label)
       const renderNotifications = () => {
         const entries = status?.notifications ?? []
         if (entries.length === 0) return React.createElement('small', { style: { display: 'block', marginTop: 6 } }, t.noNotifications)

package/lib/generic-adapter.js

@@ -31,16 +31,19 @@ export function canUseGenericAdapter(profile) {
   return Boolean(profile?.baseURL) && SUPPORTED_APIS.has(profile?.api || 'openai-completions')
 }
 
-function requestHeaders(apiKey) {
+function requestHeaders(apiKey, etag, lastModified) {
   const headers = { Accept: 'application/json' }
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+  if (etag) headers['If-None-Match'] = etag
+  if (lastModified) headers['If-Modified-Since'] = lastModified
   return headers
 }
 
-async function resolveGenericRequest(profile, { resolveCredential, fetchImpl, signal }) {
+async function resolveGenericRequest(profile, { resolveCredential, fetchImpl, signal, etag, lastModified }) {
   const keyRef = profile.apiKeyEnv || profile.credentialRef || profile.apiKeyRef
   const apiKey = keyRef ? await resolveCredential(keyRef) : ''
-  const response = await fetchImpl(endpointFor(profile.baseURL), { headers: requestHeaders(apiKey), signal })
+  const response = await fetchImpl(endpointFor(profile.baseURL), { headers: requestHeaders(apiKey, etag, lastModified), signal })
+  if (response.status === 304) return response
   if (!response.ok) throw catalogRequestError(response.status, response)
   return response
 }
@@ -49,18 +52,33 @@ export async function discoverOpenAIModels(profile, {
   resolveCredential,
   fetchImpl = fetch,
   signal,
+  etag,
+  lastModified,
 } = {}) {
   if (!canUseGenericAdapter(profile)) {
     throw new Error('generic discovery requires an OpenAI-compatible baseURL and protocol')
   }
-  const response = await resolveGenericRequest(profile, { resolveCredential, fetchImpl, signal })
+  const response = await resolveGenericRequest(profile, { resolveCredential, fetchImpl, signal, etag, lastModified })
+  if (response.status === 304) {
+    return { notModified: true, etag: response.headers?.get?.('etag') || etag, lastModified: response.headers?.get?.('last-modified') || lastModified }
+  }
+  const respEtag = response.headers?.get?.('etag') || undefined
+  const respLastMod = response.headers?.get?.('last-modified') || undefined
   let payload
   try {
     payload = JSON.parse(await readBody(response))
   } catch {
     throw new Error('model catalog response is not valid JSON')
   }
-  return normalizeModels(profile.provider ?? '', rowsFrom(payload))
+  const models = normalizeModels(profile.provider ?? '', rowsFrom(payload))
+  if (respEtag || respLastMod) {
+    Object.defineProperty(models, '__httpMeta', {
+      value: { etag: respEtag, lastModified: respLastMod },
+      enumerable: false,
+      configurable: true,
+    })
+  }
+  return models
 }