@dsh-plus/llm-pi 0.1.42 → 0.1.43

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-plus/llm-pi",
-  "version": "0.1.42",
-  "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、models.dev 目录兜底）",
+  "version": "0.1.43",
+  "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、pi-ai 内置目录；协议/compat/字段集现场推导，自动跟随已装 dsh）",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -31,44 +31,43 @@
     }
   },
   "dependencies": {
-    "https-proxy-agent": "^9.1.0",
-    "@dsh-plus/shared": "0.1.32"
+    "@dsh-plus/shared": "0.1.33"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-anonymous-user-id": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-home-paths": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-launch-environment": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm-pi-ai": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.4",
-    "@earendil-works/pi-ai": "^0.85.1"
+    "@deepseek-ai/cordis": "^4.0.5-alpha.1",
+    "@deepseek-ai/dsh-anonymous-user-id": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-credentials": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-home-paths": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm-pi-ai": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-values": "^0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.5-alpha.1",
+    "@earendil-works/pi-ai": ">=0.85.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-anonymous-user-id": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-atomic-write": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-launch-environment": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm-deepseek": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm-pi-ai": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-timeout": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-util-crypto": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "3.18.4",
-    "@earendil-works/pi-ai": "0.85.1",
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-anonymous-user-id": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-credentials": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-crypto": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
+    "@earendil-works/pi-ai": "0.87.1",
     "@types/react": "~18.3.31",
     "react": "^18.2.0"
   },

package/src/catalog/browse.ts

@@ -0,0 +1,297 @@
+/**
+ * pi-ai 内置目录的浏览/搜索后端（纯函数，node 侧单测直测）。
+ *
+ * 为什么在服务端搜：浏览器半拿不到 pi-ai（只能读本插件的 HTTP 端点），且
+ * 匹配/排序逻辑放服务端才能进 `node --test`（本仓无 DOM 测试设施）。
+ * 目录规模（40+ provider / 1500 模型）用按 kit 备忘的全量快照 + 内存过滤完全够用，
+ * 每次搜索只把当前页（默认 40 条）序列化给浏览器。
+ *
+ * 字段不钉死：模型事实由 `builtinModelFacts` 现场读取（见 catalog/builtin.ts），
+ * 官方 pi-ai 新增参数字段会自动出现在 `rest` 里，界面按原样展示。
+ * @module llm-pi/catalog/browse
+ */
+
+import type { DshKit } from '../resolve-dsh.ts'
+import {
+  type BuiltinModelFacts,
+  type BuiltinProviderEntry,
+  builtinModelFacts,
+  builtinProviderEntries,
+} from './builtin.ts'
+
+/** 浏览器可消费的模型条目（纯 JSON；函数面一律不进）。 */
+export interface BuiltinModelInfo {
+  provider: string
+  /** 发送给 provider 的请求 id。 */
+  id: string
+  /** `provider/id` 路径 id（extends 引用与复制用）。 */
+  path: string
+  /** 显示名（pi-ai 目录给的 name）。 */
+  name: string
+  /** 请求协议。 */
+  api: string
+  baseUrl: string
+  contextWindow: number
+  maxTokens: number
+  input: ('text' | 'image')[]
+  reasoning: boolean
+  thinkingLevelMap?: Record<string, string | null>
+  compat?: Record<string, unknown>
+  /** 目录给出但未单列的其余字段（cost / inputLimits / headers 等），原样展示。 */
+  rest: Record<string, unknown>
+  /** 当前生效协议集合能否服务该模型（false = 不能加进任何 pi route）。 */
+  servable: boolean
+}
+
+/** 浏览筛选条件（全部可选；缺省 = 不加该维度过滤）。 */
+export interface BrowseQuery {
+  /** 模糊搜索串（空白分隔多词，全部词都要命中）。 */
+  q?: string
+  /** 供应商（pi-ai provider id）精确匹配。 */
+  provider?: string
+  /** 请求协议精确匹配。 */
+  api?: string
+  /** 只要推理模型。 */
+  reasoning?: boolean
+  /** 只要支持图片输入的模型。 */
+  image?: boolean
+  /** 只列本插件可服务的模型；缺省 true。 */
+  servableOnly?: boolean
+  /** 起始下标（缺省 0）。 */
+  offset?: number
+  /** 每页条数（缺省 {@link BROWSE_DEFAULT_LIMIT}，上限 {@link BROWSE_MAX_LIMIT}）。 */
+  limit?: number
+}
+
+export interface BrowseResult {
+  /** 命中总数（应用 servableOnly 之后）。 */
+  total: number
+  /** 仅因协议不可服务而被隐藏的条数（servableOnly 打开时才有意义）。 */
+  servableHidden: number
+  offset: number
+  limit: number
+  items: BuiltinModelInfo[]
+}
+
+export const BROWSE_DEFAULT_LIMIT = 40
+export const BROWSE_MAX_LIMIT = 100
+
+/** 全量快照按 kit 备忘（同一 kit 实例的目录在进程内不变）。 */
+const snapshotCache = new WeakMap<DshKit, BuiltinModelInfo[]>()
+
+/** 归一化：小写 + 去掉分隔符（`/ - _ . 空格`），用于子序列匹配。 */
+function compact(text: string): string {
+  return text.toLowerCase().replace(/[\s/\-_.]+/g, '')
+}
+
+/** 按分隔符切词（小写），用于词首命中判定。 */
+function words(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[\s/\-_.]+/)
+    .filter((word) => word.length > 0)
+}
+
+/**
+ * 模糊匹配得分：越小越相关；不匹配返回 undefined。
+ * 分级：完全相等 0 < 整体前缀 1 < 词首前缀 2 < 子串 3 < 归一化相等 4 <
+ * 归一化前缀 5 < 首字母缩写 6+（同一档内以命中跨度加权，越紧凑越小）。
+ *
+ * 缩写匹配要求首字符落在**词首**（`deepseek-flash` 的 `d`、`flash` 的 `f`）：
+ * 否则任何长路径都会命中任意短查询（实测 `kimi` 会命中
+ * `cloudflare-ai-gateway/workers-ai/@cf/ibm-granite/...`——wokers 里的 k 起头也能凑出
+ * 子序列），搜索质量崩坏。跳字过多（超过 needle 长度 4 倍）同样判不命中。
+ */
+export function fuzzyScore(query: string, target: string): number | undefined {
+  const needle = query.toLowerCase()
+  if (needle.length === 0) return 0
+  const haystack = target.toLowerCase()
+  if (haystack === needle) return 0
+  if (haystack.startsWith(needle)) return 1
+  if (words(target).some((word) => word.startsWith(needle))) return 2
+  if (haystack.includes(needle)) return 3
+  const compactNeedle = compact(query)
+  const compactTarget = compact(target)
+  if (compactNeedle.length === 0) return 0
+  if (compactTarget === compactNeedle) return 4
+  if (compactTarget.startsWith(compactNeedle)) return 5
+  if (compactNeedle.length === 1) return 6
+  // 首字母缩写：needle 首字符必须是某个词的首字符，其余按顺序命中；
+  // 命中跨度越紧凑越相关（同一档内以跨度/上限为小数权重，越紧越小）。
+  const first = needle[0] as string
+  const spanCap = compactNeedle.length * 4 + 4
+  let best: number | undefined
+  for (const start of wordStarts(target)) {
+    if (haystack[start] !== first) continue
+    let cursor = 1
+    let last = start
+    for (let i = start + 1; i < haystack.length && cursor < compactNeedle.length; i += 1) {
+      const ch = haystack[i] as string
+      if (/[\s/\-_.]/.test(ch)) continue
+      if (ch === compactNeedle[cursor]) {
+        cursor += 1
+        last = i
+      }
+    }
+    if (cursor < compactNeedle.length) continue
+    const span = last - start + 1
+    if (span > spanCap) continue
+    const score = 6 + span / spanCap
+    if (best === undefined || score < best) best = score
+  }
+  return best
+}
+
+/** 词首下标（按分隔符切分的每个词的首字符位置）。 */
+function wordStarts(text: string): number[] {
+  const out: number[] = []
+  let atStart = true
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string
+    if (/[\s/\-_.]/.test(ch)) {
+      atStart = true
+      continue
+    }
+    if (atStart) {
+      out.push(i)
+      atStart = false
+    }
+  }
+  return out
+}
+
+/** 单条记录的多字段得分：取最相关字段；全部字段都不匹配返回 undefined。 */
+function scoreOf(query: string, info: BuiltinModelInfo): number | undefined {
+  let best: number | undefined
+  for (const field of [info.path, info.id, info.name, info.provider]) {
+    const score = fuzzyScore(query, field)
+    if (score === undefined) continue
+    // path 命中比 id/name 命中更相关（用户复制/extends 用的就是 path）
+    const weighted = field === info.path ? score : score + 2
+    if (best === undefined || weighted < best) best = weighted
+  }
+  return best
+}
+
+/** 多词 AND：每个词都要有命中，得分取各词之和（词少者更相关由长度自然体现）。 */
+function multiScore(query: string, info: BuiltinModelInfo): number | undefined {
+  const tokens = query.split(/\s+/).filter((token) => token.length > 0)
+  if (tokens.length === 0) return 0
+  let total = 0
+  for (const token of tokens) {
+    const score = scoreOf(token, info)
+    if (score === undefined) return undefined
+    total += score
+  }
+  return total
+}
+
+function toInfo(kit: DshKit, facts: BuiltinModelFacts): BuiltinModelInfo {
+  return {
+    provider: facts.provider,
+    id: facts.id,
+    path: facts.path,
+    name: facts.name,
+    api: facts.api,
+    baseUrl: facts.baseUrl,
+    contextWindow: facts.contextWindow,
+    maxTokens: facts.maxTokens,
+    input: facts.input,
+    reasoning: facts.reasoning,
+    ...(facts.thinkingLevelMap === undefined ? {} : { thinkingLevelMap: facts.thinkingLevelMap }),
+    ...(facts.compat === undefined ? {} : { compat: facts.compat }),
+    rest: facts.rest,
+    servable: kit.protocols.includes(facts.api),
+  }
+}
+
+/** 全量模型条目（按目录顺序：provider 排序即 pi-ai 目录顺序，模型同）。 */
+export function listModelInfos(kit: DshKit): BuiltinModelInfo[] {
+  const cached = snapshotCache.get(kit)
+  if (cached !== undefined) return cached
+  const out: BuiltinModelInfo[] = []
+  for (const provider of kit.getBuiltinProviders()) {
+    for (const model of kit.getBuiltinModels(provider)) {
+      const facts = builtinModelFacts(provider, model)
+      if (facts !== undefined) out.push(toInfo(kit, facts))
+    }
+  }
+  snapshotCache.set(kit, out)
+  return out
+}
+
+/** 供应商条目（含模型数与显示名）。 */
+export function listProviders(kit: DshKit): BuiltinProviderEntry[] {
+  return builtinProviderEntries(kit)
+}
+
+/**
+ * 紧凑协议索引 `{provider: {modelId: api}}`：浏览器半据此推断某个 route 当前
+ * 实际生效的协议（route 级 `api` 缺省时由模型继承值决定），用于一键添加前的冲突检查。
+ */
+export function buildApiIndex(
+  infos: readonly BuiltinModelInfo[],
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {}
+  for (const info of infos) {
+    const perProvider = out[info.provider] ?? {}
+    perProvider[info.id] = info.api
+    out[info.provider] = perProvider
+  }
+  return out
+}
+
+function matchesFilters(info: BuiltinModelInfo, query: BrowseQuery): boolean {
+  if (query.provider !== undefined && query.provider.length > 0 && info.provider !== query.provider)
+    return false
+  if (query.api !== undefined && query.api.length > 0 && info.api !== query.api) return false
+  if (query.reasoning === true && !info.reasoning) return false
+  if (query.image === true && !info.input.includes('image')) return false
+  return true
+}
+
+function clampLimit(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) return BROWSE_DEFAULT_LIMIT
+  return Math.min(Math.floor(value), BROWSE_MAX_LIMIT)
+}
+
+/**
+ * 搜索 + 过滤 + 分页。无搜索串时按目录顺序（provider/id）返回；
+ * 有搜索串时按相关度排序，同分按路径字典序稳定。
+ */
+export function browseModels(kit: DshKit, query: BrowseQuery = {}): BrowseResult {
+  const all = listModelInfos(kit)
+  const servableOnly = query.servableOnly !== false
+  const limit = clampLimit(query.limit)
+  const offset = Math.max(0, Math.floor(query.offset ?? 0))
+  const q = (query.q ?? '').trim()
+
+  let servableHidden = 0
+  const matched: { info: BuiltinModelInfo; score: number }[] = []
+  for (const info of all) {
+    if (!info.servable) {
+      if (servableOnly) servableHidden += 1
+      if (servableOnly) continue
+    }
+    if (!matchesFilters(info, query)) continue
+    const score = q.length === 0 ? 0 : multiScore(q, info)
+    if (score === undefined) continue
+    matched.push({ info, score })
+  }
+  if (q.length > 0) {
+    // 同分优先更短的路径（更具体的命中），再按字典序稳定
+    matched.sort((left, right) =>
+      left.score === right.score
+        ? left.info.path.length - right.info.path.length ||
+          left.info.path.localeCompare(right.info.path)
+        : left.score - right.score,
+    )
+  }
+  return {
+    total: matched.length,
+    servableHidden,
+    offset,
+    limit,
+    items: matched.slice(offset, offset + limit).map((entry) => entry.info),
+  }
+}

package/src/catalog/builtin.ts

@@ -1,14 +1,52 @@
 /**
- * pi-ai 内置目录适配：继承解析的第一级（最高优先级）数据源。
- * 内置条目带 pi 官方校正（compat、thinkingLevelMap、能力过滤），最可信。
+ * pi-ai 内置目录适配：extends 继承解析的唯一数据源，也是配置页「内置模型目录」
+ * 浏览器的数据来源。
+ *
+ * 两个「不钉死」：
+ * - 目录条目随已装 dsh 的 pi-ai 版本自动更新（本文件只读，不复制目录）；
+ * - 可继承的模型级键集按已装官方适配器 Config schema 现场推导
+ *   （`kit.officialModelFields`），官方新增模型级字段即自动透传；
+ *   目录里出现而官方 schema 不接受的字段（如 cost/headers/inputLimits）
+ *   仍会被摘进 facts.rest 供界面展示，但不参与继承。
+ *
+ * 运行时读取对未知/异形字段宽容（跨版本容忍）：只把能确认形状的值纳入事实。
  * @module llm-pi/catalog/builtin
  */
 import type { DshKit } from '../resolve-dsh.ts'
 
+/** 内置目录的 provider id 字面量联合（pi-ai 生成目录的键集，按 vendored 版本收窄）。 */
+export type BuiltinProviderId = ReturnType<DshKit['getBuiltinProviders']>[number]
+
+/** 浏览/状态用的 provider 条目（不含 pi-ai 的函数面，可安全序列化给浏览器半）。 */
+export interface BuiltinProviderEntry {
+  id: string
+  name: string
+  baseUrl?: string
+  modelCount: number
+}
+
 /**
- * 继承源可提供的模型字段（pi-ai Model 的可继承子集）。
- * 全部可选：models.dev 兜底源只给得出其中一部分。
+ * 单个内置模型的事实快照（与 pi-ai 类型解耦的运行期读取结果）。
+ * `rest` 是目录给出但本插件不认识的其余自有键（展示用，随上游字段增删自动变化）。
  */
+export interface BuiltinModelFacts {
+  provider: string
+  id: string
+  /** `provider/id` 路径 id（extends 引用与「复制路径 id」用）。 */
+  path: string
+  name: string
+  api: string
+  baseUrl: string
+  reasoning: boolean
+  input: ('text' | 'image')[]
+  contextWindow: number
+  maxTokens: number
+  thinkingLevelMap?: Record<string, string | null>
+  compat?: Record<string, unknown>
+  rest: Record<string, unknown>
+}
+
+/** 继承源可提供的模型字段（pi-ai Model 的可继承子集）。 */
 export interface ModelBase {
   name?: string
   api?: string
@@ -19,17 +57,94 @@ export interface ModelBase {
   compat?: Record<string, unknown>
   contextWindow?: number
   maxTokens?: number
-  cost?: {
-    input: number
-    output: number
-    cacheRead: number
-    cacheWrite: number
+  /** 官方 schema 接受、且目录给出的其余模型级字段（键集现场推导，浅拷贝）。 */
+  extra?: Record<string, unknown>
+}
+
+/** 已在 facts 显式取出的键：这些不再进 rest。 */
+const FACT_KEYS = new Set([
+  'id',
+  'provider',
+  'name',
+  'api',
+  'baseUrl',
+  'reasoning',
+  'input',
+  'contextWindow',
+  'maxTokens',
+  'thinkingLevelMap',
+  'compat',
+])
+
+/** JSON 值浅拷贝（对象/数组一层；条目要经 settings 序列化，不可留上游引用）。 */
+export function cloneJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return [...value]
+  if (typeof value === 'object' && value !== null) return { ...(value as Record<string, unknown>) }
+  return value
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+/** 读模态数组：只保留 text/image 两种已知值，其余丢弃（防上游改成别的枚举）。 */
+function readInput(value: unknown): ('text' | 'image')[] {
+  if (!Array.isArray(value)) return ['text']
+  const out = value.filter((m): m is 'text' | 'image' => m === 'text' || m === 'image')
+  return out.length > 0 ? out : ['text']
+}
+
+/** 读 thinkingLevelMap：值为字符串或 null，其余（含 undefined 键）丢弃。 */
+function readThinkingLevelMap(value: unknown): Record<string, string | null> | undefined {
+  const record = asRecord(value)
+  if (record === undefined) return undefined
+  const out: Record<string, string | null> = {}
+  for (const [level, wire] of Object.entries(record)) {
+    if (typeof wire === 'string') out[level] = wire
+    else if (wire === null) out[level] = null
   }
-  headers?: Record<string, string>
+  return Object.keys(out).length > 0 ? out : undefined
 }
 
-/** 内置目录的 provider id 字面量联合（pi-ai 生成目录的键集）。 */
-export type BuiltinProviderId = ReturnType<DshKit['getBuiltinProviders']>[number]
+/**
+ * 把运行期模型对象读成事实快照。入参用 unknown：pi-ai Model 的类型随版本变化，
+ * 继承/浏览都只依赖此处确认过的字段，未确认的一律进 rest 原样展示。
+ */
+export function builtinModelFacts(provider: string, raw: unknown): BuiltinModelFacts | undefined {
+  const model = asRecord(raw)
+  if (model === undefined) return undefined
+  const id = model['id']
+  if (typeof id !== 'string' || id.length === 0) return undefined
+  const rest: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(model)) {
+    if (FACT_KEYS.has(key) || value === undefined) continue
+    rest[key] = cloneJsonValue(value)
+  }
+  const name = model['name']
+  const api = model['api']
+  const baseUrl = model['baseUrl']
+  const contextWindow = model['contextWindow']
+  const maxTokens = model['maxTokens']
+  const thinkingLevelMap = readThinkingLevelMap(model['thinkingLevelMap'])
+  const compat = asRecord(model['compat'])
+  return {
+    provider,
+    id,
+    path: `${provider}/${id}`,
+    name: typeof name === 'string' && name.length > 0 ? name : id,
+    api: typeof api === 'string' ? api : '',
+    baseUrl: typeof baseUrl === 'string' ? baseUrl : '',
+    reasoning: model['reasoning'] === true,
+    input: readInput(model['input']),
+    contextWindow: typeof contextWindow === 'number' ? contextWindow : 0,
+    maxTokens: typeof maxTokens === 'number' ? maxTokens : 0,
+    ...(thinkingLevelMap === undefined ? {} : { thinkingLevelMap }),
+    ...(compat === undefined ? {} : { compat: { ...compat } }),
+    rest,
+  }
+}
 
 /** 内置 provider 的端点（provider 级 extends 的 baseURL 缺省值）。 */
 export function builtinProviderBaseUrl(kit: DshKit, provider: string): string | undefined {
@@ -45,40 +160,73 @@ export function hasBuiltinProvider(kit: DshKit, provider: string): provider is B
   return ids.includes(provider)
 }
 
-/** 内置 provider 的全部模型 id（UI extends 选择器用）。 */
+/** 内置 provider 的全部模型 id（UI 选择器/浏览用）。 */
 export function builtinModelIds(kit: DshKit, provider: string): string[] {
   if (!hasBuiltinProvider(kit, provider)) return []
   return kit.getBuiltinModels(provider).map((m) => m.id)
 }
 
-/** 查单个内置模型为继承 base；未命中返回 undefined。 */
-export function builtinModelBase(
+/** 内置目录的全部 provider 条目（含 pi-ai 给的显示名与端点）。 */
+export function builtinProviderEntries(kit: DshKit): BuiltinProviderEntry[] {
+  const catalog = kit.builtinProviders()
+  const byId = new Map(catalog.map((p) => [p.id as string, p]))
+  return kit.getBuiltinProviders().map((id) => {
+    const provider = byId.get(id)
+    const baseUrl = provider?.baseUrl
+    return {
+      id,
+      name: provider?.name ?? id,
+      ...(typeof baseUrl === 'string' && baseUrl.length > 0 ? { baseUrl } : {}),
+      modelCount: kit.getBuiltinModels(id).length,
+    }
+  })
+}
+
+/** 取某 provider 下某模型的事实快照；provider/模型不存在返回 undefined。 */
+export function builtinModelFactsOf(
   kit: DshKit,
   provider: string,
   modelId: string,
-): ModelBase | undefined {
+): BuiltinModelFacts | undefined {
   if (!hasBuiltinProvider(kit, provider)) return undefined
   const model = kit.getBuiltinModels(provider).find((m) => m.id === modelId)
-  if (model === undefined) return undefined
+  return model === undefined ? undefined : builtinModelFacts(provider, model)
+}
+
+/** 事实快照 → 继承 base（`extra` 只包含官方 schema 接受的其余模型级键）。 */
+export function modelBaseOf(kit: DshKit, facts: BuiltinModelFacts): ModelBase {
+  const extra: Record<string, unknown> = {}
+  for (const field of kit.officialModelFields) {
+    if (FACT_KEYS.has(field) || field === 'reasoningEfforts') continue
+    const value = facts.rest[field]
+    if (value !== undefined) extra[field] = cloneJsonValue(value)
+  }
   return {
-    name: model.name,
-    api: model.api,
-    baseUrl: model.baseUrl,
-    input: [...model.input],
-    reasoning: model.reasoning,
-    ...(model.thinkingLevelMap === undefined
-      ? {}
-      : { thinkingLevelMap: { ...model.thinkingLevelMap } }),
-    ...(model.compat === undefined
+    name: facts.name,
+    api: facts.api,
+    baseUrl: facts.baseUrl,
+    input: [...facts.input],
+    reasoning: facts.reasoning,
+    ...(facts.thinkingLevelMap === undefined
       ? {}
-      : { compat: { ...(model.compat as Record<string, unknown>) } }),
-    contextWindow: model.contextWindow,
-    maxTokens: model.maxTokens,
-    cost: { ...model.cost },
-    ...(model.headers === undefined ? {} : { headers: { ...model.headers } }),
+      : { thinkingLevelMap: { ...facts.thinkingLevelMap } }),
+    ...(facts.compat === undefined ? {} : { compat: { ...facts.compat } }),
+    contextWindow: facts.contextWindow,
+    maxTokens: facts.maxTokens,
+    ...(Object.keys(extra).length === 0 ? {} : { extra }),
   }
 }
 
+/** 查单个内置模型为继承 base；未命中返回 undefined。 */
+export function builtinModelBase(
+  kit: DshKit,
+  provider: string,
+  modelId: string,
+): ModelBase | undefined {
+  const facts = builtinModelFactsOf(kit, provider, modelId)
+  return facts === undefined ? undefined : modelBaseOf(kit, facts)
+}
+
 /**
  * provider 级 extends 的全量模型继承：route 不写 models 时，
  * 以继承源 provider 的全部内置模型作为条目（每个条目 base 即其自身）。
@@ -88,8 +236,8 @@ export function inheritedCatalogEntries(
   provider: string,
 ): { id: string; base: ModelBase }[] {
   if (!hasBuiltinProvider(kit, provider)) return []
-  return kit.getBuiltinModels(provider).map((model) => ({
-    id: model.id,
-    base: builtinModelBase(kit, provider, model.id) ?? {},
-  }))
+  return kit.getBuiltinModels(provider).map((model) => {
+    const facts = builtinModelFacts(provider, model)
+    return { id: model.id, base: facts === undefined ? {} : modelBaseOf(kit, facts) }
+  })
 }