@dsh-plus/llm-pi 0.1.0

package/src/compat.ts

@@ -0,0 +1,146 @@
+/**
+ * 逐协议 compat 字段表与校验。
+ *
+ * 背景：官方 llm-pi-ai 的配置路径只物化 thinkingFormat/supportsReasoningEffort
+ * 两个字段，多余键被静默丢弃；本插件开放 pi-ai 的全量 compat（字段表与
+ * pi-ai@0.82.1 types.d.ts:423-538 逐字段对齐），并在 settings 写入与
+ * profile 构建时校验——未知键/错类型值直接拒绝并给出合法键清单。
+ *
+ * pi-ai 侧消费语义：getCompat 逐字段 `??` 覆盖 detectCompat 的
+ * baseURL/名称猜测；undefined 视为未设置（无法显式清空检测值）。
+ * @module llm-pi/compat
+ */
+import type { ProtocolId } from './config.ts'
+
+type CompatValue = 'boolean' | 'object' | readonly string[]
+
+/** openai-completions 的 21 个字段（pi-ai OpenAICompletionsCompat）。 */
+const COMPLETIONS_FIELDS: Record<string, CompatValue> = {
+  supportsStore: 'boolean',
+  supportsDeveloperRole: 'boolean',
+  supportsReasoningEffort: 'boolean',
+  supportsUsageInStreaming: 'boolean',
+  maxTokensField: ['max_completion_tokens', 'max_tokens'],
+  requiresToolResultName: 'boolean',
+  requiresAssistantAfterToolResult: 'boolean',
+  requiresThinkingAsText: 'boolean',
+  requiresReasoningContentOnAssistantMessages: 'boolean',
+  thinkingFormat: [
+    'openai',
+    'openrouter',
+    'deepseek',
+    'together',
+    'zai',
+    'qwen',
+    'chat-template',
+    'qwen-chat-template',
+    'string-thinking',
+    'ant-ling',
+  ],
+  chatTemplateKwargs: 'object',
+  openRouterRouting: 'object',
+  vercelGatewayRouting: 'object',
+  zaiToolStream: 'boolean',
+  supportsOpenAIGrammarTools: 'boolean',
+  supportsStrictMode: 'boolean',
+  cacheControlFormat: ['anthropic'],
+  sendSessionAffinityHeaders: 'boolean',
+  deferredToolsMode: ['kimi'],
+  sessionAffinityFormat: ['openai', 'openai-nosession', 'openrouter'],
+  supportsLongCacheRetention: 'boolean',
+}
+
+/** openai-responses 的 7 个字段（pi-ai OpenAIResponsesCompat）。 */
+const RESPONSES_FIELDS: Record<string, CompatValue> = {
+  supportsDeveloperRole: 'boolean',
+  sessionAffinityFormat: ['openai', 'openai-nosession', 'openrouter'],
+  supportsLongCacheRetention: 'boolean',
+  supportsStrictMode: 'boolean',
+  supportsOpenAIGrammarTools: 'boolean',
+  supportsToolSearch: 'boolean',
+  supportsExplicitPromptCacheMode: 'boolean',
+}
+
+/** anthropic-messages 的 9 个字段（pi-ai AnthropicMessagesCompat）。 */
+const ANTHROPIC_FIELDS: Record<string, CompatValue> = {
+  supportsEagerToolInputStreaming: 'boolean',
+  supportsLongCacheRetention: 'boolean',
+  sendSessionAffinityHeaders: 'boolean',
+  supportsCacheControlOnTools: 'boolean',
+  supportsTemperature: 'boolean',
+  forceAdaptiveThinking: 'boolean',
+  allowEmptySignature: 'boolean',
+  supportsStrictTools: 'boolean',
+  supportsToolReferences: 'boolean',
+}
+
+const FIELDS_BY_PROTOCOL: Record<ProtocolId, Record<string, CompatValue>> = {
+  'openai-completions': COMPLETIONS_FIELDS,
+  'openai-responses': RESPONSES_FIELDS,
+  'anthropic-messages': ANTHROPIC_FIELDS,
+}
+
+/** 某协议的全部合法 compat 键（UI 渲染字段组与校验共用）。 */
+export function compatFieldsOf(api: ProtocolId): readonly string[] {
+  return Object.keys(FIELDS_BY_PROTOCOL[api])
+}
+
+/** 某协议某字段的取值约束（UI 渲染开关/下拉用）。 */
+export function compatFieldSpec(api: ProtocolId, field: string): CompatValue | undefined {
+  return FIELDS_BY_PROTOCOL[api][field]
+}
+
+function checkValue(api: ProtocolId, field: string, spec: CompatValue, value: unknown, where: string): void {
+  if (spec === 'boolean') {
+    if (typeof value !== 'boolean') throw new Error(`${where}: compat.${field} 必须是布尔值`)
+    return
+  }
+  if (spec === 'object') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      throw new Error(`${where}: compat.${field} 必须是对象`)
+    }
+    return
+  }
+  if (typeof value !== 'string' || !spec.includes(value)) {
+    throw new Error(`${where}: compat.${field} 必须是 ${spec.map((v) => JSON.stringify(v)).join(' | ')} 之一`)
+  }
+}
+
+/**
+ * 校验一份 compat 字典对指定协议合法：未知协议/未知键拒绝（对比官方的静默丢弃），
+ * 已知键校验值类型/枚举。undefined 值视为未设置，跳过（语义同 pi-ai 的 ??）。
+ */
+export function validateCompat(api: string, compat: Record<string, unknown> | undefined, where: string): void {
+  if (compat === undefined) return
+  const fields = FIELDS_BY_PROTOCOL[api as ProtocolId]
+  if (fields === undefined) {
+    throw new Error(`${where}: 协议 ${JSON.stringify(api)} 无 compat 字段表（支持：${Object.keys(FIELDS_BY_PROTOCOL).join(', ')}）`)
+  }
+  for (const [key, value] of Object.entries(compat)) {
+    const spec = fields[key]
+    if (spec === undefined) {
+      throw new Error(
+        `${where}: compat.${key} 不是 ${api} 协议的合法字段（合法字段：${Object.keys(fields).join(', ')}）`,
+      )
+    }
+    if (value === undefined) continue
+    checkValue(api, key, spec, value, where)
+  }
+}
+
+/**
+ * 逐字段合并 compat 层（后者覆盖前者），丢弃 undefined 值。
+ * 层序：继承源（仅同协议）→ route 级 → 模型级。
+ */
+export function mergeCompat(
+  ...layers: (Record<string, unknown> | undefined)[]
+): Record<string, unknown> | undefined {
+  const merged: Record<string, unknown> = {}
+  for (const layer of layers) {
+    if (layer === undefined) continue
+    for (const [key, value] of Object.entries(layer)) {
+      if (value !== undefined) merged[key] = value
+    }
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined
+}

package/src/config-api.ts

@@ -0,0 +1,135 @@
+/**
+ * 配置 HTTP 通道：webui 配置卡片的后端（notify-email 同款模式）。
+ * 背景：官方 apiproxy 的 settings.* RPC 对 namespace 有硬编码白名单，第三方
+ * namespace 一律 settings-not-exposed；卡片数据走自建 webServer 同源路由，
+ * 写回经 ctx.settings.replace 整段覆盖用户层（providers dict 的删除语义
+ * 无法经深合并表达）。写入先过 settings 校验钩子（完整解析试跑），
+ * 非法配置在写入处拒绝并返回错误明细。
+ * @module llm-pi/config-api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+
+import { builtinModelIds } from './catalog/builtin.ts'
+import { SETTINGS_NS, toWire, WirePatch, type WirePatchInput } from './config.ts'
+import type { LlmPiRuntime } from './service.ts'
+
+const ROUTE_CONFIG = '/dsh-plus/llm-pi/config'
+const ROUTE_CATALOG = '/dsh-plus/llm-pi/catalog'
+const MAX_BODY_BYTES = 256 * 1024
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+async function readPatch(req: IncomingMessage): Promise<WirePatchInput> {
+  const raw = await readBody(req)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('request body is not valid JSON')
+  }
+  return WirePatch(parsed) as WirePatchInput
+}
+
+function wireOf(runtime: LlmPiRuntime, writable: boolean) {
+  // 状态始终上报（含未拉取/失败），由卡片区分文案；不再用 enabled 做 null 开关。
+  return toWire(runtime.currentConfig(), writable, runtime.kitInfo().source, runtime.modelsDev.status())
+}
+
+async function handleConfig(
+  ctx: Context,
+  runtime: LlmPiRuntime,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const settings = ctx.get('settings')
+  if (req.method === 'GET') {
+    sendJson(res, 200, wireOf(runtime, settings !== undefined))
+    return
+  }
+  if (req.method !== 'PUT') {
+    sendJson(res, 405, { error: 'method not allowed' })
+    return
+  }
+  if (settings === undefined) {
+    sendJson(res, 503, { error: 'settings provider 不可用，无法在线保存；请编辑 settings.yaml' })
+    return
+  }
+  const patch = await readPatch(req)
+  await settings.replace(SETTINGS_NS, patch)
+  sendJson(res, 200, wireOf(runtime, true))
+}
+
+/** 目录查询/手动拉取：GET ?provider=&source= → 该源模型 id 列表；POST /refresh → 立即拉取。 */
+function handleCatalog(runtime: LlmPiRuntime, req: IncomingMessage, res: ServerResponse): void {
+  if (req.method === 'POST' && req.url?.endsWith('/refresh')) {
+    void runtime.modelsDev.refresh().then(() => {
+      sendJson(res, 200, { status: runtime.modelsDev.status() })
+    })
+    return
+  }
+  const url = new URL(req.url ?? '', 'http://localhost')
+  const provider = url.searchParams.get('provider') ?? ''
+  const source = url.searchParams.get('source') ?? 'builtin'
+  if (source === 'models-dev') {
+    sendJson(res, 200, {
+      providers: runtime.modelsDev.providerIds(),
+      models: provider.length > 0 ? runtime.modelsDev.modelIds(provider) : [],
+      status: runtime.modelsDev.status(),
+    })
+    return
+  }
+  sendJson(res, 200, {
+    providers: runtime.kit.getBuiltinProviders(),
+    models: provider.length > 0 ? builtinModelIds(runtime.kit, provider) : [],
+  })
+}
+
+/** 注册配置读写与目录查询路由（webServer 缺失时由调用方保证不调用）。 */
+export function registerConfigApi(ctx: Context, runtime: LlmPiRuntime): void {
+  const logger = ctx.logger('llm-pi')
+  const guard = (handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void) => {
+    return async (req: IncomingMessage, res: ServerResponse) => {
+      try {
+        await handler(req, res)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`config api ${req.method ?? '?'} ${req.url ?? '?'} failed: ${message}`)
+        if (!res.headersSent) sendJson(res, 400, { error: message })
+        else res.end()
+      }
+    }
+  }
+  ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTE_CONFIG,
+    handler: guard((req, res) => handleConfig(ctx, runtime, req, res)),
+  })
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE_CATALOG,
+    handler: guard((req, res) => handleCatalog(runtime, req, res)),
+  })
+}

package/src/config.ts

@@ -0,0 +1,210 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值）与 settings namespace
+ *（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）共用同一
+ * schemastery schema。无密钥字段（apiKeyEnv 是凭据引用名而非密钥本身）。
+ *
+ * 与官方 llm-pi-ai 的差异：
+ * - compat 是开放 dict，物化时按协议校验（见 compat.ts），写入即拒绝未知键；
+ * - provider/model 均支持 extends 继承（见 inherit.ts）。
+ * @module llm-pi/config
+ */
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份。 */
+export const SETTINGS_NS = settingsNamespace('dsh-plus-llm-pi')
+
+/** 本插件可为手写 route 提供的协议实现（与官方 PROTOCOLS 表一致）。 */
+export const PROTOCOL_IDS = ['openai-completions', 'openai-responses', 'anthropic-messages'] as const
+export type ProtocolId = (typeof PROTOCOL_IDS)[number]
+
+/** pi-ai 思考档位，升级序。 */
+export const THINKING_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+
+export const MODALITIES = ['text', 'image'] as const
+
+export const DEFAULT_CONTEXT_WINDOW = 262144
+export const DEFAULT_MAX_TOKENS = 32768
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000
+/** dsh-timeout 的定时器上限（与官方 MAX_TIMER_DELAY_MS 对齐）。 */
+export const MAX_TIMER_DELAY_MS = 2 ** 31 - 1
+
+/** 键为可选档位，值为线协议拼写；仅 off 可留空（支持但不发送参数）。 */
+const reasoningEfforts = z.dict(z.union([z.string(), z.const(null)]), z.union(THINKING_LEVELS))
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number]
+export type Modality = (typeof MODALITIES)[number]
+export type ReasoningEfforts = Partial<Record<ThinkingLevel, string | null>>
+
+/** 单个模型条目：id 必填，其余字段缺省即继承。 */
+export interface ModelEntryConfig {
+  id: string
+  extends?: string
+  name?: string
+  contextWindow?: number
+  maxTokens?: number
+  input?: Modality[]
+  reasoningEfforts?: false | ReasoningEfforts
+  compat?: Record<string, unknown>
+}
+
+/** 单个 provider route 配置（providers 字典的值）。 */
+export interface ProviderProfileConfig {
+  extends?: string
+  displayName?: string
+  api?: ProtocolId
+  baseURL?: string
+  apiKeyEnv?: string
+  headers?: Record<string, string>
+  compat?: Record<string, unknown>
+  defaultContextWindow?: number
+  defaultMaxTokens?: number
+  defaultInput?: Modality[]
+  reasoning?: ThinkingLevel
+  thinkingBudgets?: { minimal: number; low: number; medium: number; high: number }
+  cacheRetention?: 'none' | 'short' | 'long'
+  transport?: 'sse' | 'websocket' | 'websocket-cached' | 'auto'
+  timeoutMs?: number
+  websocketConnectTimeoutMs?: number
+  streamIdleTimeoutMs?: number
+  retryPolicy?: unknown
+  models?: ModelEntryConfig[]
+}
+
+/** 插件配置根。 */
+export interface LlmPiConfig {
+  enabled: boolean
+  catalogUrl: string
+  catalogRefreshHours: number
+  catalogProxy: string
+  providers: Record<string, ProviderProfileConfig>
+}
+
+const thinkingBudgets = z.object({
+  minimal: z.number(),
+  low: z.number(),
+  medium: z.number(),
+  high: z.number(),
+})
+
+/**
+ * compat 开放字典：承载 pi-ai 的全量 compat 字段（按协议分型，
+ * 字段集与值校验见 compat.ts，在 settings 写入与 profile 构建时执行）。
+ * schema 层不收紧，是因为字段集取决于本条目的 api，schema 无法表达条件分型。
+ */
+const compatDict = z.dict(z.any())
+
+const modelEntry = z.object({
+  id: z.string().required().description('模型 id（发送给 provider 的标识）'),
+  extends: z
+    .string()
+    .description('继承源："provider/model" 或裸 model id（随 provider 级 extends 源）；缺省先查内置目录同名模型'),
+  name: z.string().description('选择器显示名；缺省继承内置目录名，再退化为 id'),
+  contextWindow: z.number().step(1).min(1).description('上下文容量（覆盖继承值）'),
+  maxTokens: z.number().step(1).min(1).description('输出能力上限；显式配置同时成为无 cap 请求的默认 cap'),
+  input: z.array(z.union(MODALITIES)).description('请求模态；缺省继承内置目录，再退化 route defaultInput'),
+  reasoningEfforts: z
+    .union([z.const(false), reasoningEfforts])
+    .description('可选 reasoning 档位：false=非推理模型；dict=档位→线值映射；缺省继承内置目录能力'),
+  compat: compatDict.description('模型级 compat（字段级合并，压过 route 级与继承值）'),
+})
+
+const providerProfile = z.object({
+  extends: z
+    .string()
+    .description('provider 级继承：内置 provider id，提供 api/baseURL 默认值与模型 extends 的缺省查找源'),
+  displayName: z.string().description('选择器显示名；缺省为 route 键'),
+  api: z.union(PROTOCOL_IDS).description('线协议；缺省逐模型取继承值的 api，全部一致时作为 route 协议'),
+  baseURL: z.string().description('端点；缺省继承 extends 源 provider 的端点'),
+  apiKeyEnv: z.string().role('credential-ref').description('凭据引用名（凭据服务/环境变量）'),
+  headers: z.dict(z.string()).description('provider 请求头（Harness 署名头保留名优先）'),
+  compat: compatDict.description('route 级 compat 默认（逐模型按字段生效）'),
+  defaultContextWindow: z.number().step(1).min(1).description('模型与继承源都未标注时的上下文容量兜底'),
+  defaultMaxTokens: z.number().step(1).min(1).description('模型与继承源都未标注时的输出能力兜底'),
+  defaultInput: z
+    .array(z.union(MODALITIES))
+    .description('模型与继承源都未声明时的模态兜底（不可为空）')
+    .default(['text']),
+  reasoning: z.union(THINKING_LEVELS).description('provider 默认 reasoning 档位'),
+  thinkingBudgets: thinkingBudgets.description('支持 token 预算的推理 provider 的档位预算'),
+  cacheRetention: z.union(['none', 'short', 'long']).description('提示缓存保留偏好'),
+  transport: z.union(['sse', 'websocket', 'websocket-cached', 'auto']).description('流式传输偏好'),
+  timeoutMs: z.natural().description('HTTP/provider 超时毫秒'),
+  websocketConnectTimeoutMs: z.natural().description('WebSocket 连接超时毫秒'),
+  streamIdleTimeoutMs: z
+    .number()
+    .min(Number.MIN_VALUE)
+    .max(MAX_TIMER_DELAY_MS)
+    .description('单支流式读取的最大空闲间隔毫秒'),
+  retryPolicy: z.any().description('provider 重试策略（dsh-llm RetryPolicy 形状，构建期校验）'),
+  models: z.array(modelEntry).description('本 route 的模型目录；缺省且 provider 有 extends 时继承该源全部模型'),
+})
+
+export const Config: z<LlmPiConfig> = z.object({
+  enabled: z.boolean().description('总开关（关闭则不注册任何 route）').default(true),
+  catalogUrl: z.string().description('models.dev 目录数据端点').default('https://models.dev/api.json'),
+  catalogRefreshHours: z
+    .number()
+    .description('models.dev 自动拉取间隔小时数；0 = 不自动拉取（可手动拉取或读已有缓存）')
+    .default(0),
+  catalogProxy: z
+    .string()
+    .description('拉取 models.dev 目录时的 HTTP 代理地址（如 http://127.0.0.1:7890）；留空直连')
+    .default(''),
+  providers: z.dict(providerProfile).description('provider 路由表，键即 route 名').default({}),
+})
+
+/** 配置卡片读取用的传输对象：配置无密钥字段，原样传输；附运行期元信息。 */
+export interface WireConfig {
+  enabled: boolean
+  catalogUrl: string
+  catalogRefreshHours: number
+  catalogProxy: string
+  providers: Record<string, ProviderProfileConfig>
+  /** 是否存在可写的 settings provider（决定卡片是否允许编辑）。 */
+  writable: boolean
+  /** 模块解析来源与自检结果（dsh 树 / vendored 兜底）。 */
+  kitSource: string
+  /** models.dev 快照状态（fetchedAt/模型数/错误），供卡片展示。 */
+  modelsDevStatus: { fetchedAt: string | null; providers: number; models: number; error: string | null } | null
+}
+
+export function toWire(
+  cfg: LlmPiConfig,
+  writable: boolean,
+  kitSource: string,
+  modelsDevStatus: WireConfig['modelsDevStatus'],
+): WireConfig {
+  return {
+    enabled: cfg.enabled,
+    catalogUrl: cfg.catalogUrl,
+    catalogRefreshHours: cfg.catalogRefreshHours,
+    catalogProxy: cfg.catalogProxy ?? '',
+    providers: cfg.providers ?? {},
+    writable,
+    kitSource,
+    modelsDevStatus,
+  }
+}
+
+/**
+ * 配置卡片写回：卡片总是提交完整配置对象（含 providers 全量），
+ * 后端经 settings.replace 整段覆盖用户层——providers dict 的删除语义
+ * 无法经深合并表达，整段替换是唯一正确语义。
+ */
+/** 卡片提交的形状：字段全可选（无默认值），只携带用户编辑过的字段。 */
+export interface WirePatchInput {
+  enabled?: boolean
+  catalogUrl?: string
+  catalogRefreshHours?: number
+  catalogProxy?: string
+  providers?: Record<string, ProviderProfileConfig>
+}
+
+export const WirePatch: z<WirePatchInput> = z.object({
+  enabled: z.boolean(),
+  catalogUrl: z.string(),
+  catalogRefreshHours: z.number(),
+  catalogProxy: z.string(),
+  providers: z.dict(providerProfile),
+})

package/src/discovery.ts

@@ -0,0 +1,176 @@
+/**
+ * 模型发现：配置面"拉取可用模型"动作的后端（对齐官方 discoverModels 语义）。
+ *
+ * 与官方的差异：本插件 route 不是内置目录 id，目录直答改为"provider 级
+ * extends 的内置源目录直答"；其余（手写 route 仅 openai 系协议走
+ * GET {baseURL}/models、4MB 上限、署名头）与官方一致。结果不落盘。
+ * @module llm-pi/discovery
+ */
+import { hasBuiltinProvider, builtinModelIds } from './catalog/builtin.ts'
+import type { ProviderProfileConfig } from './config.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+const LISTABLE_PROTOCOLS = new Set(['openai-completions', 'openai-responses'])
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+export interface DiscoveryRequest {
+  provider?: string
+  baseURL?: string
+  api?: string
+  apiKey?: string
+  signal?: AbortSignal
+}
+
+export interface DiscoveryEntry {
+  id: string
+  name?: string
+  contextWindow?: number
+  maxTokens?: number
+}
+
+export interface DiscoveryDeps {
+  kit: DshKit
+  /** 当前生效的原始配置 providers 表（发现面对的是草稿/配置，不是物化产物）。 */
+  configProviders: () => Record<string, ProviderProfileConfig | undefined>
+  storedApiKey: (provider: string | undefined) => Promise<string | undefined>
+}
+
+/** 读取有界响应体：声明超长或累计超长都拒绝（对齐官方 readBounded）。 */
+async function readBounded(kit: DshKit, response: Response, url: string): Promise<string> {
+  const oversized = () => new kit.LlmError(`${url} 响应超过 ${MAX_RESPONSE_BYTES} 字节`, 'DISCOVERY_FAILED')
+  const declared = Number(response.headers.get('content-length') ?? NaN)
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel()
+    throw oversized()
+  }
+  if (response.body === null) return ''
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > MAX_RESPONSE_BYTES) throw oversized()
+      chunks.push(value)
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+  }
+  const body = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(body)
+}
+
+/** 解析 OpenAI 兼容模型清单；坏行跳过而非整表失败（对齐官方 readListing）。 */
+function readListing(kit: DshKit, body: unknown): DiscoveryEntry[] {
+  const data = (body as { data?: unknown })?.data
+  if (!Array.isArray(data)) {
+    throw new kit.LlmError('端点的模型清单缺少 "data" 数组；请手工录入模型', 'DISCOVERY_FAILED')
+  }
+  const models: DiscoveryEntry[] = []
+  for (const raw of data) {
+    const entry = raw as Record<string, unknown>
+    if (typeof entry?.['id'] !== 'string' || entry['id'].length === 0) continue
+    const out: DiscoveryEntry = { id: entry['id'] }
+    const name = entry['name'] ?? entry['display_name']
+    if (typeof name === 'string' && name.length > 0) out.name = name
+    for (const [key, field] of [
+      ['context_window', 'contextWindow'],
+      ['context_length', 'contextWindow'],
+      ['max_output_tokens', 'maxTokens'],
+      ['max_tokens', 'maxTokens'],
+    ] as const) {
+      const value = entry[key]
+      if (typeof value === 'number' && Number.isInteger(value) && value > 0 && out[field] === undefined) {
+        out[field] = value
+      }
+    }
+    models.push(out)
+  }
+  return models
+}
+
+/** 内置目录直答（route 配了 provider 级 extends 时）。 */
+function catalogAnswer(kit: DshKit, source: string): DiscoveryEntry[] {
+  return builtinModelIds(kit, source).map((id) => {
+    const models = kit.getBuiltinModels(source)
+    const model = models.find((m) => m.id === id)
+    return {
+      id,
+      ...(model?.name === undefined ? {} : { name: model.name }),
+      ...(model?.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }),
+      ...(model?.maxTokens === undefined ? {} : { maxTokens: model.maxTokens }),
+    }
+  })
+}
+
+/**
+ * 回答"该 provider 可服务哪些模型"：extends 内置源零网络直答；
+ * 否则仅 openai 系协议走 GET {baseURL}/models；其余协议明确不支持。
+ */
+export async function discoverModels(request: DiscoveryRequest, deps: DiscoveryDeps): Promise<DiscoveryEntry[]> {
+  const { kit } = deps
+  const route: ProviderProfileConfig | undefined =
+    request.provider === undefined ? undefined : deps.configProviders()[request.provider]
+  if (route?.extends !== undefined && hasBuiltinProvider(kit, route.extends)) {
+    return catalogAnswer(kit, route.extends)
+  }
+  const baseURL = request.baseURL ?? route?.baseURL
+  if (baseURL === undefined || baseURL.length === 0) {
+    throw new kit.LlmError(
+      `route ${JSON.stringify(request.provider ?? '')} 未配 baseURL 且 extends 源无内置目录；无法探测模型清单`,
+      'DISCOVERY_FAILED',
+    )
+  }
+  const api = request.api ?? route?.api ?? 'openai-completions'
+  if (!LISTABLE_PROTOCOLS.has(api)) {
+    throw new kit.LlmError(`协议 "${api}" 无可读取的模型清单端点；请手工录入模型`, 'DISCOVERY_UNSUPPORTED')
+  }
+  const url = `${baseURL.replace(/\/+$/, '')}/models`
+  const supplied = request.apiKey ?? (await deps.storedApiKey(request.provider))
+  let authorization: string | undefined
+  if (supplied !== undefined) {
+    const checked = kit.normalizeApiKey(supplied)
+    if (!checked.ok) {
+      throw new kit.LlmError(
+        checked.reason === 'empty' ? 'API key 为空；请在 Models 页配置或留空以匿名探测' : 'API key 含有 HTTP 头无法携带的字符',
+        kit.INVALID_CREDENTIAL_CODE,
+      )
+    }
+    authorization = `Bearer ${checked.value}`
+  }
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json',
+        ...(authorization === undefined ? {} : { authorization }),
+        ...kit.attributionHeaders(),
+      },
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+    })
+  } catch (error) {
+    if (request.signal?.aborted) throw new kit.LlmError('模型发现被调用方中止', 'ABORTED', { cause: error })
+    throw new kit.LlmError(`无法连接 ${url}`, 'DISCOVERY_FAILED', { cause: error })
+  }
+  if (!response.ok) {
+    throw new kit.LlmError(
+      `${url} 返回 ${response.status}${response.status === 401 || response.status === 403 ? '；请检查 API key' : ''}`,
+      'DISCOVERY_FAILED',
+    )
+  }
+  const text = await readBounded(kit, response, url)
+  try {
+    return readListing(kit, JSON.parse(text))
+  } catch (error) {
+    if (error instanceof kit.LlmError) throw error
+    throw new kit.LlmError(`${url} 未返回 JSON`, 'DISCOVERY_FAILED', { cause: error })
+  }
+}