@dsh-plus/llm-pi 0.1.42 → 0.1.44

package/src/client/api.ts

@@ -1,15 +1,32 @@
 /**
- * 自定义端点通道：仅剩「模型目录」（配置读写已迁移到 ctx.remote.settings
- * 直连传输，0.1.2-alpha.1 起 connection.api.settings 已移除；见 scope.ts 与
- * card.tsx）。目录响应附带 kitSource 与 models-dev 状态，供卡片的状态行
- * 展示（运行期诊断，非配置数据）。
+ * 自定义端点通道：只剩浏览器半拿不到的两样东西——运行期套件事实（生效版本、
+ * 协议集合、目录规模、诊断）与 pi-ai 内置目录搜索（配置读写走 ctx.remote.settings
+ * 直连，见 card.tsx / shared 的 scope.ts）。
  * @module llm-pi/client/api
  */
 
-export interface WireModelsDevStatus {
-  fetchedAt: string | null
-  providers: number
-  error: string | null
+import type { CompatValue } from './constants.ts'
+
+/** 运行期套件事实（服务端 kitInfo() 的镜像）。 */
+export interface WireKitInfo {
+  source: string
+  root?: string
+  versions: { piAi?: string; piAiAdapter?: string; dsh?: string }
+  verifiedRange: string
+  versionNotice?: string
+  protocols: string[]
+  protocolSource: string
+  catalog: { providers: number; models: number; generatedAt?: number }
+  compatSource: string
+  diagnostics: string[]
+}
+
+/** 内置 provider 条目。 */
+export interface WireProviderEntry {
+  id: string
+  name: string
+  baseUrl?: string
+  modelCount: number
 }
 
 export interface WireProvider {
@@ -54,9 +71,6 @@ export interface WireModel {
 /** settings 命名空间的解析值（llm-pi 无 secret 字段，value 即完整配置）。 */
 export interface ConfigValue {
   enabled: boolean
-  catalogUrl: string
-  catalogRefreshHours: number
-  catalogProxy: string
   providers: Record<string, WireProvider>
 }
 
@@ -65,18 +79,59 @@ export type ConfigPatch = ConfigValue
 
 /** compat 字段表（服务端从官方包推导后下发；浏览器半不手抄）。 */
 export interface WireCompatTable {
-  fields: Record<string, Record<string, 'boolean' | 'integer' | 'number' | 'object' | string[]>>
+  fields: Record<string, Record<string, CompatValue>>
   source: string
   problem?: string
 }
 
-/** GET /catalog?provider=&source= 返回（kitSource 为运行期套件来源诊断）。 */
-export interface CatalogResult {
-  providers: string[]
-  models: string[]
-  status?: WireModelsDevStatus
-  kitSource?: string
-  compat?: WireCompatTable
+/** 内置目录的单个模型（服务端 catalog/browse.ts 的镜像）。 */
+export interface WireModelInfo {
+  provider: string
+  id: string
+  path: string
+  name: string
+  api: string
+  baseUrl: string
+  contextWindow: number
+  maxTokens: number
+  input: string[]
+  reasoning: boolean
+  thinkingLevelMap?: Record<string, string | null>
+  compat?: Record<string, unknown>
+  /** 目录给出但未单列的其余字段（cost / inputLimits 等），原样展示。 */
+  rest: Record<string, unknown>
+  /** 当前生效协议集合能否服务该模型。 */
+  servable: boolean
+}
+
+/** `GET /catalog` 响应：运行期事实 + provider/协议索引 + compat 字段表。 */
+export interface CatalogMeta {
+  kit: WireKitInfo
+  providers: WireProviderEntry[]
+  /** `{provider: {modelId: api}}`：推断 route 生效协议用。 */
+  apis: Record<string, Record<string, string>>
+  compat: WireCompatTable
+}
+
+/** `GET /catalog/models` 响应。 */
+export interface CatalogPage {
+  total: number
+  servableHidden: number
+  offset: number
+  limit: number
+  items: WireModelInfo[]
+}
+
+/** 目录搜索条件（与 server 端同名参数一一对应）。 */
+export interface CatalogQuery {
+  q?: string
+  provider?: string
+  api?: string
+  reasoning?: boolean
+  image?: boolean
+  servableOnly?: boolean
+  offset?: number
+  limit?: number
 }
 
 const ROUTE_CATALOG = '/dsh-plus/llm-pi/catalog'
@@ -87,23 +142,31 @@ async function parse<T>(res: Response): Promise<T> {
   return body
 }
 
-/** 目录查询：provider 为空时只返回该源的 provider 列表。 */
-export async function fetchCatalog(
-  provider: string,
-  source: 'builtin' | 'models-dev',
-): Promise<CatalogResult> {
-  const url = `${ROUTE_CATALOG}?provider=${encodeURIComponent(provider)}&source=${source}`
-  return parse<CatalogResult>(await fetch(url, { credentials: 'same-origin' }))
+/** 运行期事实 + 目录索引（卡片挂载时一次）。 */
+export async function fetchCatalogMeta(): Promise<CatalogMeta> {
+  return parse<CatalogMeta>(await fetch(ROUTE_CATALOG, { credentials: 'same-origin' }))
 }
 
-/** 手动拉取 models.dev 目录：POST /catalog/refresh → 最新快照状态。 */
-export async function refreshCatalog(): Promise<{
-  status: WireModelsDevStatus
-}> {
-  return parse<{ status: WireModelsDevStatus }>(
-    await fetch(`${ROUTE_CATALOG}/refresh`, {
-      method: 'POST',
+/** 目录搜索（模糊 q + provider/api/能力/分页）。 */
+export async function searchCatalog(
+  query: CatalogQuery,
+  signal?: AbortSignal,
+): Promise<CatalogPage> {
+  const params = new URLSearchParams()
+  if (query.q !== undefined && query.q.length > 0) params.set('q', query.q)
+  if (query.provider !== undefined && query.provider.length > 0)
+    params.set('provider', query.provider)
+  if (query.api !== undefined && query.api.length > 0) params.set('api', query.api)
+  if (query.reasoning === true) params.set('reasoning', '1')
+  if (query.image === true) params.set('image', '1')
+  if (query.servableOnly === false) params.set('servable', '0')
+  if (query.offset !== undefined) params.set('offset', String(query.offset))
+  if (query.limit !== undefined) params.set('limit', String(query.limit))
+  const suffix = params.toString()
+  return parse<CatalogPage>(
+    await fetch(`${ROUTE_CATALOG}/models${suffix === '' ? '' : `?${suffix}`}`, {
       credentials: 'same-origin',
+      ...(signal === undefined ? {} : { signal }),
     }),
   )
 }

package/src/client/card.tsx

@@ -1,10 +1,17 @@
 /**
  * 「LLM 路由」配置卡片：经 injectPluginConfigCard 注册（插件页
  * plugins.row.config / plugins.bundle.config，view 分发 summary/page）。
- * 顶部：enabled / catalogUrl / catalogRefreshHours / 只读状态行（kitSource、
- * modelsDevStatus，来自模型目录端点）+ 保存（settings.update 全量深合并）与
- * 错误/成功提示；下方为 providers 路由列表（新增/删除/字段编辑/compat/模型
- * 目录，见 views/）。外壳与基础控件走 @dsh-plus/shared/client 套件。
+ *
+ * 页面结构（自上而下，除根字段外**默认全部收起**，避免长列表划不到头）：
+ * 1. 根字段：启用开关 + 运行期状态行（生效版本/安装树/目录规模/协议/compat 来源/诊断）；
+ * 2. 「内置模型目录」浏览器（折叠小节，默认收起）：搜索/筛选/复制路径 id/
+ *    一键把 `{id, extends}` 加到目标 route（添加后自动展开该 route 并回显）；
+ * 3. Provider 路由列表（每 route 收起；route 内模型行同样默认收起）。
+ *
+ * 数据来源：配置读写走官方 remote.settings（scope/api）；运行期事实与目录搜索
+ * 走本插件 `/catalog` 端点（浏览器半读不到 pi-ai 包）。草稿/保存与目录索引各由
+ * 本文件的 hook 承担，全部状态（浏览器开合、目标 route、route 展开态）在卡片持有，
+ * 子组件受控。
  * @module llm-pi/client/card
  */
 
@@ -19,18 +26,21 @@ import {
   type Scope,
 } from '@dsh-plus/shared/client'
 import { type ReactElement, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
-import { type ConfigValue, fetchCatalog, refreshCatalog, type WireModelsDevStatus } from './api.ts'
-import { installCompatFields } from './constants.ts'
+import { type CatalogMeta, type ConfigValue, fetchCatalogMeta, type WireModelInfo } from './api.ts'
+import { installCompatFields, installProtocols } from './constants.ts'
 import {
+  addModelEntry,
   type Draft,
   draftFromValue,
   emptyProviderDraft,
-  numTextOk,
   type ProviderDraft,
   toPatch,
 } from './draft.ts'
+import { CollapseSection } from './fields.tsx'
 import type { Translate } from './i18n.ts'
 import { RootFields } from './root-fields.tsx'
+import { type ApiIndex, routeApiFacts, targetRoutes } from './route-fit.ts'
+import { CatalogBrowser } from './views/catalog-browser.tsx'
 import { ProvidersSection } from './views/providers.tsx'
 
 export interface CardProps extends PluginConfigViewProps {
@@ -39,29 +49,94 @@ export interface CardProps extends PluginConfigViewProps {
   api: NamespaceSettingsApi
 }
 
-/** 运行期诊断行数据来源：模型目录端点（compat 字段表同批安装）。 */
-function useRuntimeDiagnostics(): {
-  kitSource: string | null
-  modelsDevStatus: WireModelsDevStatus | null
-  setModelsDevStatus(next: WireModelsDevStatus): void
-} {
-  const [kitSource, setKitSource] = useState<string | null>(null)
-  const [modelsDevStatus, setModelsDevStatus] = useState<WireModelsDevStatus | null>(null)
+/** 运行期事实 + 目录索引：卡片挂载拉一次（同时安装协议集合与 compat 字段表）。 */
+function useCatalogMeta(): { meta: CatalogMeta | null; error: string } {
+  const [meta, setMeta] = useState<CatalogMeta | null>(null)
+  const [error, setError] = useState('')
   useEffect(() => {
     let alive = true
-    fetchCatalog('', 'models-dev')
+    fetchCatalogMeta()
       .then((result) => {
         if (!alive) return
-        setKitSource(result.kitSource ?? null)
-        setModelsDevStatus(result.status ?? null)
-        if (result.compat !== undefined) installCompatFields(result.compat.fields)
+        installProtocols(result.kit.protocols)
+        installCompatFields(result.compat.fields)
+        setMeta(result)
+      })
+      .catch((reason: unknown) => {
+        if (!alive) return
+        setError(reason instanceof Error ? reason.message : String(reason))
       })
-      .catch(() => {})
     return () => {
       alive = false
     }
   }, [])
-  return { kitSource, modelsDevStatus, setModelsDevStatus }
+  return { meta, error }
+}
+
+/**
+ * 草稿与保存：首次拿到解析值后播种草稿；后续 Host 更新不覆盖在途编辑
+ * （与官方 staged 表单一致）。dirty 由"提交形状"双向比较得出。
+ */
+function useCardDraft(options: {
+  value: ConfigValue | undefined
+  scope: Scope
+  api: NamespaceSettingsApi
+  t: Translate
+}) {
+  const { value, scope, api, t } = options
+  const [draft, setDraft] = useState<Draft | null>(null)
+  const [epoch, setEpoch] = useState(0)
+  const [saving, setSaving] = useState(false)
+  const [status, setStatus] = useState<CardStatusState>(IDLE_STATUS)
+
+  useEffect(() => {
+    if (value === undefined || draft !== null) return
+    setDraft(draftFromValue(value))
+  }, [value, draft])
+
+  const dirty = useMemo(
+    () =>
+      value !== undefined &&
+      draft !== null &&
+      JSON.stringify(toPatch(draft)) !== JSON.stringify(toPatch(draftFromValue(value))),
+    [value, draft],
+  )
+  const onSave = (): void => {
+    if (draft === null) return
+    setSaving(true)
+    const revision = scope.getSnapshot().revision
+    api
+      .update(toPatch(draft) as unknown as Record<string, unknown>, revision)
+      .then(async () => {
+        await scope.load()
+        const next = scope.getSnapshot().value as ConfigValue | undefined
+        if (next !== undefined) setDraft(draftFromValue(next))
+        setEpoch((current) => current + 1)
+        setStatus({ kind: 'ok', text: t('saveOk') })
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        setStatus({ kind: 'error', text: `${t('saveFailed')}${message}` })
+      })
+      .finally(() => setSaving(false))
+  }
+  const onDiscard = (): void => {
+    if (value === undefined) return
+    setDraft(draftFromValue(value))
+    setEpoch((current) => current + 1)
+    setStatus(IDLE_STATUS)
+  }
+  return {
+    draft,
+    setDraft,
+    dirty,
+    saving,
+    status,
+    idle: () => setStatus(IDLE_STATUS),
+    epoch,
+    onSave,
+    onDiscard,
+  }
 }
 
 /** 路由级草稿改写：改字段 / 新增 route / 删除 route（返回新草稿，不改入参）。 */
@@ -80,26 +155,17 @@ function withoutRoute(draft: Draft, route: string): Draft {
   return { ...draft, providers: next }
 }
 
-/** 卡片动作：手动拉取目录、放弃、保存。 */
+/** 卡片动作：放弃、保存（模型目录已唯一来自 pi-ai，无可拉取项）。 */
 function cardActions(options: {
   t: Translate
   dirty: boolean
-  invalid: boolean
   saving: boolean
-  refreshing: boolean
   disabled: boolean
-  onRefresh(): void
   onDiscard(): void
   onSave(): void
 }): CardAction[] {
   const { t } = options
   return [
-    {
-      key: 'refresh',
-      label: t(options.refreshing ? 'refreshingCatalog' : 'refreshCatalog'),
-      disabled: options.disabled || options.refreshing,
-      onClick: options.onRefresh,
-    },
     {
       key: 'discard',
       label: t('discard'),
@@ -110,12 +176,18 @@ function cardActions(options: {
       key: 'save',
       label: t(options.saving ? 'saving' : 'save'),
       variant: 'primary',
-      disabled: !options.dirty || options.invalid || options.saving || options.disabled,
+      disabled: !options.dirty || options.saving || options.disabled,
       onClick: options.onSave,
     },
   ]
 }
 
+/** 打开浏览器时的目标 route 选择：优先当前目标，否则第一个候选。 */
+function pickTarget(targets: readonly string[], preferred: string): string {
+  if (preferred !== '' && targets.includes(preferred)) return preferred
+  return targets[0] ?? ''
+}
+
 export function LlmPiCard(props: CardProps): ReactElement | string | null {
   const { t, scope, api } = props
   const snapshot = useSyncExternalStore(
@@ -123,35 +195,16 @@ export function LlmPiCard(props: CardProps): ReactElement | string | null {
     () => scope.getSnapshot(),
   )
   const value = snapshot.value as ConfigValue | undefined
-  const [draft, setDraft] = useState<Draft | null>(null)
-  const [epoch, setEpoch] = useState(0)
-  const [saving, setSaving] = useState(false)
-  const [refreshing, setRefreshing] = useState(false)
-  const [status, setStatus] = useState<CardStatusState>(IDLE_STATUS)
-  const { kitSource, modelsDevStatus, setModelsDevStatus } = useRuntimeDiagnostics()
-
-  // 首次拿到解析值后播种草稿；后续 Host 更新不覆盖在途编辑（与官方 staged 表单一致）。
-  useEffect(() => {
-    if (value === undefined || draft !== null) return
-    setDraft(draftFromValue(value))
-  }, [value, draft])
-
-  const dirty = useMemo(
-    () =>
-      value !== undefined &&
-      draft !== null &&
-      JSON.stringify(toPatch(draft)) !== JSON.stringify(toPatch(draftFromValue(value))),
-    [value, draft],
-  )
-  const invalid = useMemo(() => {
-    if (draft === null) return false
-    return (
-      !numTextOk(draft.catalogRefreshHours) ||
-      Object.values(draft.providers).some((provider) =>
-        provider.models.some((model) => model.id.trim() === ''),
-      )
-    )
-  }, [draft])
+  const { draft, setDraft, dirty, saving, status, idle, epoch, onSave, onDiscard } = useCardDraft({
+    value,
+    scope,
+    api,
+    t,
+  })
+  const [browserOpen, setBrowserOpen] = useState(false)
+  const [browserTarget, setBrowserTarget] = useState('')
+  const [openRoutes, setOpenRoutes] = useState<Record<string, boolean>>({})
+  const { meta, error: metaError } = useCatalogMeta()
 
   // 插件页 summary 视图只出一行简介（hooks 已全部落定，可安全提前返回）。
   if (props.view === 'summary') return t('summaryLine')
@@ -160,53 +213,30 @@ export function LlmPiCard(props: CardProps): ReactElement | string | null {
     return <CardLoading prefix="lpc" text={t('loading')} />
   }
 
-  const setProvider = (route: string, patch: Partial<ProviderDraft>): void => {
-    setDraft(withProviderPatch(draft, route, patch))
-    setStatus(IDLE_STATUS)
+  const apis: ApiIndex = meta?.apis ?? {}
+  const targets = targetRoutes(draft.providers)
+  const target = pickTarget(targets, browserTarget)
+  const openBrowserFor = (route: string): void => {
+    setBrowserTarget(route)
+    setBrowserOpen(true)
   }
   const onAddRoute = (key: string): void => {
     setDraft(withNewRoute(draft, key))
-    setStatus(IDLE_STATUS)
-  }
-  const onRemoveRoute = (route: string): void => {
-    setDraft(withoutRoute(draft, route))
-    setStatus(IDLE_STATUS)
-  }
-  const onSave = (): void => {
-    setSaving(true)
-    const revision = scope.getSnapshot().revision
-    api
-      .update(toPatch(draft) as unknown as Record<string, unknown>, revision)
-      .then(async () => {
-        await scope.load()
-        const next = scope.getSnapshot().value as ConfigValue | undefined
-        if (next !== undefined) setDraft(draftFromValue(next))
-        setEpoch((value) => value + 1)
-        setStatus({ kind: 'ok', text: t('saveOk') })
-      })
-      .catch((error: unknown) => {
-        const message = error instanceof Error ? error.message : String(error)
-        setStatus({ kind: 'error', text: `${t('saveFailed')}${message}` })
-      })
-      .finally(() => setSaving(false))
-  }
-  const onDiscard = (): void => {
-    setDraft(draftFromValue(value))
-    setEpoch((value) => value + 1)
-    setStatus(IDLE_STATUS)
+    setOpenRoutes((prev) => ({ ...prev, [key]: true }))
+    setBrowserTarget((prev) => (prev === '' ? key : prev))
+    idle()
   }
-  const onRefreshCatalog = (): void => {
-    setRefreshing(true)
-    refreshCatalog()
-      .then((result) => {
-        setModelsDevStatus(result.status)
-        setStatus({ kind: 'ok', text: t('refreshOk') })
-      })
-      .catch((error: unknown) => {
-        const message = error instanceof Error ? error.message : String(error)
-        setStatus({ kind: 'error', text: `${t('refreshFailed')}${message}` })
-      })
-      .finally(() => setRefreshing(false))
+  /**
+   * 目录一键添加：把 `{id, extends: 'provider/model'}` 写进目标 route 草稿
+   * （不预填 name/容量——继承才能跟随 pi-ai 目录升级），并展开该 route 给出反馈。
+   */
+  const onAddModel = (route: string, model: WireModelInfo): boolean => {
+    const result = addModelEntry(draft, route, model)
+    if (!result.added) return false
+    setDraft(result.draft)
+    setOpenRoutes((prev) => ({ ...prev, [route]: true }))
+    idle()
+    return true
   }
 
   const disabled = !snapshot.writable
@@ -220,37 +250,67 @@ export function LlmPiCard(props: CardProps): ReactElement | string | null {
       dirtyLabel={t('unsaved')}
       readOnlyNotice={disabled ? t('readOnly') : undefined}
       status={status}
-      actions={cardActions({
-        t,
-        dirty,
-        invalid,
-        saving,
-        refreshing,
-        disabled,
-        onRefresh: onRefreshCatalog,
-        onDiscard,
-        onSave,
-      })}
+      actions={cardActions({ t, dirty, saving, disabled, onDiscard, onSave })}
     >
       <RootFields
         t={t}
         draft={draft}
         disabled={disabled}
-        kitSource={kitSource}
-        modelsDevStatus={modelsDevStatus}
+        kit={meta?.kit ?? null}
+        kitError={metaError}
         onEdit={(patch) => {
           setDraft({ ...draft, ...patch })
-          setStatus(IDLE_STATUS)
+          idle()
         }}
       />
+      <CollapseSection
+        id="lpc-catalog-browser"
+        title={t('browserGroup')}
+        defaultOpen={false}
+        open={browserOpen}
+        onToggle={() => setBrowserOpen((open) => !open)}
+        meta={meta === null ? '' : `${meta.kit.catalog.models}`}
+      >
+        <CatalogBrowser
+          t={t}
+          targets={targets}
+          apis={apis}
+          providers={meta?.providers ?? []}
+          target={target}
+          onTargetChange={setBrowserTarget}
+          providerOf={(route) => draft.providers[route]}
+          routeApiOf={(route) => {
+            const provider = draft.providers[route]
+            return provider === undefined ? undefined : routeApiFacts(provider, apis).api
+          }}
+          onAdd={onAddModel}
+          disabled={disabled}
+          {...(metaError === '' ? {} : { metaError })}
+        />
+      </CollapseSection>
       <ProvidersSection
         providers={draft.providers}
+        openRoutes={openRoutes}
         epoch={epoch}
         disabled={disabled}
         t={t}
         onAddRoute={onAddRoute}
-        onRemoveRoute={onRemoveRoute}
-        onPatchProvider={setProvider}
+        onRemoveRoute={(route) => {
+          setDraft(withoutRoute(draft, route))
+          idle()
+        }}
+        onPatchProvider={(route, patch) => {
+          setDraft(withProviderPatch(draft, route, patch))
+          idle()
+        }}
+        onToggleRoute={(route, open) => setOpenRoutes((prev) => ({ ...prev, [route]: open }))}
+        onCollapseAll={() => setOpenRoutes({})}
+        onExpandAll={() =>
+          setOpenRoutes(
+            Object.fromEntries(Object.keys(draft.providers).map((route) => [route, true])),
+          )
+        }
+        onAddFromCatalog={openBrowserFor}
       />
     </CardChrome>
   )

package/src/client/client.ts

@@ -9,8 +9,8 @@
  * scope 与基础控件走 @dsh-plus/shared/client 套件（收编自本插件原实现）。
  * 配置读写经 ctx.remote.settings 直连（0.1.2-alpha.1 起 connection.api.settings
  * 已移除；0.1.7 起 settingsScope 服务亦删除（configForms 取代）——插件卡片自始
- * 直连 remote.settings，见 @dsh-plus/shared/client scope.ts）；自定义端点仅剩「模型目录」
- * （api.ts，含 kitSource/models-dev 运行期诊断）。
+ * 直连 remote.settings，见 @dsh-plus/shared/client scope.ts）；自定义端点只剩
+ * `/catalog`（api.ts：运行期套件事实 + pi-ai 内置目录搜索，浏览器半读不到 pi-ai 包）。
  * 卡片 key/rowId 约定见 @dsh-plus/shared/client/config-slots。
  * @module @dsh-plus/llm-pi/client
  */

package/src/client/constants.ts

@@ -1,12 +1,16 @@
 /**
- * 浏览器半内联常量：与服务端 packages/llm-pi/src/config.ts、compat.ts 逐字对齐。
+ * 浏览器半内联常量：与服务端 packages/llm-pi/src/config.ts 逐字对齐。
  * 浏览器半不能 import 服务端模块（tsdown 只打包 client 侧入口），
  * 改动服务端这些常量时必须同步本文件。
+ *
+ * 两个集合改为**服务端下发**（与服务端校验同源，浏览器半不再手抄）：
+ * - 线协议：取自已装官方适配器的 supportedProtocols()（`installProtocols`）；
+ * - compat 字段表：取自官方 bundle + Config schema 推导（`installCompatFields`）。
  * @module llm-pi/client/constants
  */
 
-/** 协议枚举（来源：config.ts PROTOCOL_IDS）。 */
-export const PROTOCOL_IDS = [
+/** 协议兜底集合（来源：config.ts FALLBACK_PROTOCOLS）；服务端下发前/失败时使用。 */
+export const FALLBACK_PROTOCOLS = [
   'openai-completions',
   'openai-responses',
   'anthropic-messages',
@@ -29,15 +33,31 @@ export const BUDGET_KEYS = ['minimal', 'low', 'medium', 'high'] as const
 
 export type CompatValue = 'boolean' | 'integer' | 'number' | 'object' | readonly string[]
 
+/**
+ * 生效协议集合：由服务端 /catalog 下发（服务端与官方适配器同源推导），
+ * 未拿到前用 FALLBACK_PROTOCOLS。
+ */
+let protocols: string[] = [...FALLBACK_PROTOCOLS]
+
+/** 安装服务端下发的协议集合（card 挂载时调用）。 */
+export function installProtocols(list: readonly string[]): void {
+  if (list.length > 0) protocols = [...list]
+}
+
+/** 当前可选协议（顺序即官方表顺序）。 */
+export function protocolOptions(): readonly string[] {
+  return protocols
+}
+
 /**
  * 逐协议 compat 字段表：**服务端推导结果经 /catalog 下发**，浏览器半不再手抄
- * （手抄遗漏官方新增字段 = UI 不渲染 + 保存被后端拒绝；见 compat-gates.ts）。
+ * （手抄遗漏官方新增字段 = UI 不渲染 + 保存被后端拒绝；见 official-surface.ts）。
  * 未拿到服务端表时用 EMPTY（UI 只渲染提示行），不放内置副本兜底——宁可少画
  * 控件，也不给出可能与官方不符的字段集。
  */
 let compatTable: Record<string, Record<string, CompatValue>> = {}
 
-/** 安装服务端下发的字段表（card 挂载/刷新目录时调用）。 */
+/** 安装服务端下发的字段表（card 挂载时调用）。 */
 export function installCompatFields(table: Record<string, Record<string, CompatValue>>): void {
   compatTable = table
 }