@dsh-plus/llm-pi 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/llm-pi",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、models.dev 目录兜底）",
   "type": "module",
   "main": "lib/index.js",
@@ -36,25 +36,30 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-credentials": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-llm-pi-ai": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "@earendil-works/pi-ai": "^0.82.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-anonymous-user-id": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
     "@deepseek-ai/schemastery": "3.18.1",
-    "@deepseek-ai/dsh-settings": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-credentials": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-launch-environment": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm-pi-ai": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8",
     "@earendil-works/pi-ai": "0.82.1",
     "@types/react": "~18.3.1",
     "react": "^18.2.0"

package/src/catalog/official.ts

@@ -0,0 +1,71 @@
+/**
+ * 官方模型目录数据源：adapter: deepseek 的 route 的继承 base。
+ *
+ * 目录取自 dsh-llm-deepseek 的 resolveAdapterOptions({}, undefined)——
+ * 即官方 DEFAULT_MODELS 经 schema 默认值补全后的形态（含视觉模型的
+ * inputModalities / imagePixelBudget / imageMaxBytes），跟随 dsh 树升级
+ * 自动更新，不在本仓库复制一份硬编码副本。
+ * @module llm-pi/catalog/official
+ */
+import type { DshKit } from '../resolve-dsh.ts'
+
+/** 官方目录可提供的可继承模型字段（DeepSeekCatalogModel 的可继承子集）。 */
+export interface OfficialModelBase {
+  name?: string
+  contextWindow?: number
+  maxTokens?: number
+  input?: ('text' | 'image')[]
+  imagePixelBudget?: number
+  imageMaxBytes?: number
+  imageDetail?: 'auto' | 'low'
+}
+
+interface OfficialCatalog {
+  baseUrl: string
+  models: Map<string, OfficialModelBase>
+}
+
+/** 按 kit 备忘（kit 实例在进程内唯一，目录随 dsh 树版本固定）。 */
+const cache = new WeakMap<DshKit, OfficialCatalog>()
+
+function catalogOf(kit: DshKit): OfficialCatalog {
+  const hit = cache.get(kit)
+  if (hit !== undefined) return hit
+  if (kit.deepseek === undefined) {
+    throw new Error('llm-pi: 官方模型目录需要 dsh-llm-deepseek（当前运行时套件不含）')
+  }
+  const resolved = kit.deepseek.resolveAdapterOptions({} as never, undefined)
+  const models = new Map<string, OfficialModelBase>()
+  for (const model of resolved.models) {
+    models.set(model.id, {
+      ...(model.name === undefined ? {} : { name: model.name }),
+      ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }),
+      ...(model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens }),
+      ...(model.inputModalities === undefined
+        ? {}
+        : { input: [...model.inputModalities] as ('text' | 'image')[] }),
+      ...(model.imagePixelBudget === undefined ? {} : { imagePixelBudget: model.imagePixelBudget }),
+      ...(model.imageMaxBytes === undefined ? {} : { imageMaxBytes: model.imageMaxBytes }),
+      ...(model.imageDetail === undefined ? {} : { imageDetail: model.imageDetail }),
+    })
+  }
+  const catalog: OfficialCatalog = { baseUrl: resolved.baseURL, models }
+  cache.set(kit, catalog)
+  return catalog
+}
+
+/** 官方端点（route 配 extends: 'deepseek' 且未显式 baseURL 时的缺省值）。 */
+export function officialBaseUrl(kit: DshKit): string {
+  return catalogOf(kit).baseUrl
+}
+
+/** 查单个官方模型为继承 base；未命中返回 undefined。 */
+export function officialModelBase(kit: DshKit, modelId: string): OfficialModelBase | undefined {
+  const base = catalogOf(kit).models.get(modelId)
+  return base === undefined ? undefined : { ...base }
+}
+
+/** 官方目录的全部模型 id（route 级 extends: 'deepseek' 的全量继承与诊断用）。 */
+export function officialModelIds(kit: DshKit): string[] {
+  return [...catalogOf(kit).models.keys()]
+}

package/src/client/draft.ts

@@ -38,6 +38,8 @@ export interface ModelDraft {
   input: InputDraft
   reasoningEfforts: ReasoningDraft
   compat: Record<string, unknown>
+  /** 卡片未认识的字段原样往返（如 adapter: deepseek 的 imagePixelBudget 等）。 */
+  extra: Record<string, unknown>
 }
 
 export interface ProviderDraft {
@@ -61,6 +63,8 @@ export interface ProviderDraft {
   maxRequestImageBytes: string
   retryPolicy: unknown
   models: ModelDraft[]
+  /** 卡片未认识的字段原样往返（如 adapter/thinking/filesApiTimeoutMs 等）。 */
+  extra: Record<string, unknown>
 }
 
 export interface Draft {
@@ -167,6 +171,50 @@ function omitEmpty(obj: Record<string, unknown>): Record<string, unknown> {
   return out
 }
 
+/** 卡片已认识的 wire 字段（其余进 extra 原样往返）。 */
+const KNOWN_MODEL_KEYS = new Set([
+  'id',
+  'extends',
+  'name',
+  'contextWindow',
+  'maxTokens',
+  'input',
+  'reasoningEfforts',
+  'compat',
+])
+
+const KNOWN_PROVIDER_KEYS = new Set([
+  'extends',
+  'displayName',
+  'api',
+  'baseURL',
+  'apiKeyEnv',
+  'headers',
+  'compat',
+  'defaultContextWindow',
+  'defaultMaxTokens',
+  'defaultInput',
+  'reasoning',
+  'thinkingBudgets',
+  'cacheRetention',
+  'transport',
+  'timeoutMs',
+  'websocketConnectTimeoutMs',
+  'streamIdleTimeoutMs',
+  'maxRequestImageBytes',
+  'retryPolicy',
+  'models',
+])
+
+/** 摘出 wire 对象里卡片未认识的字段（undefined 值不保留）。 */
+function extraOf(wire: Record<string, unknown>, known: Set<string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(wire)) {
+    if (!known.has(key) && value !== undefined) out[key] = value
+  }
+  return out
+}
+
 function modelDraftFromWire(model: WireModel): ModelDraft {
   return {
     id: model.id,
@@ -177,21 +225,25 @@ function modelDraftFromWire(model: WireModel): ModelDraft {
     input: inputFromWire(model.input),
     reasoningEfforts: reasoningFromWire(model.reasoningEfforts),
     compat: { ...(model.compat ?? {}) },
+    extra: extraOf(model as Record<string, unknown>, KNOWN_MODEL_KEYS),
   }
 }
 
 function modelToWire(model: ModelDraft): WireModel {
   const reasoningEfforts = reasoningToWire(model.reasoningEfforts)
-  return omitEmpty({
-    id: model.id.trim(),
-    extends: model.extends.trim(),
-    name: model.name.trim(),
-    contextWindow: toNum(model.contextWindow),
-    maxTokens: toNum(model.maxTokens),
-    input: inputToWire(model.input),
-    ...(reasoningEfforts === undefined ? {} : { reasoningEfforts }),
-    compat: model.compat,
-  }) as WireModel
+  return {
+    ...model.extra,
+    ...(omitEmpty({
+      id: model.id.trim(),
+      extends: model.extends.trim(),
+      name: model.name.trim(),
+      contextWindow: toNum(model.contextWindow),
+      maxTokens: toNum(model.maxTokens),
+      input: inputToWire(model.input),
+      ...(reasoningEfforts === undefined ? {} : { reasoningEfforts }),
+      compat: model.compat,
+    }) as Record<string, unknown>),
+  } as unknown as WireModel
 }
 
 function providerDraftFromWire(provider: WireProvider): ProviderDraft {
@@ -216,32 +268,36 @@ function providerDraftFromWire(provider: WireProvider): ProviderDraft {
     maxRequestImageBytes: numToText(provider.maxRequestImageBytes),
     retryPolicy: provider.retryPolicy,
     models: (provider.models ?? []).map(modelDraftFromWire),
+    extra: extraOf(provider as Record<string, unknown>, KNOWN_PROVIDER_KEYS),
   }
 }
 
 function providerToWire(provider: ProviderDraft): WireProvider {
-  return omitEmpty({
-    extends: provider.extends.trim(),
-    displayName: provider.displayName.trim(),
-    api: provider.api,
-    baseURL: provider.baseURL.trim(),
-    apiKeyEnv: provider.apiKeyEnv.trim(),
-    headers: pairsToHeaders(provider.headers),
-    compat: provider.compat,
-    defaultContextWindow: toNum(provider.defaultContextWindow),
-    defaultMaxTokens: toNum(provider.defaultMaxTokens),
-    input: inputToWire(provider.input),
-    reasoning: provider.reasoning,
-    thinkingBudgets: budgetToWire(provider.thinkingBudgets),
-    cacheRetention: provider.cacheRetention,
-    transport: provider.transport,
-    timeoutMs: toNum(provider.timeoutMs),
-    websocketConnectTimeoutMs: toNum(provider.websocketConnectTimeoutMs),
-    streamIdleTimeoutMs: toNum(provider.streamIdleTimeoutMs),
-    maxRequestImageBytes: toNum(provider.maxRequestImageBytes),
-    retryPolicy: provider.retryPolicy,
-    models: provider.models.map(modelToWire),
-  }) as WireProvider
+  return {
+    ...provider.extra,
+    ...(omitEmpty({
+      extends: provider.extends.trim(),
+      displayName: provider.displayName.trim(),
+      api: provider.api,
+      baseURL: provider.baseURL.trim(),
+      apiKeyEnv: provider.apiKeyEnv.trim(),
+      headers: pairsToHeaders(provider.headers),
+      compat: provider.compat,
+      defaultContextWindow: toNum(provider.defaultContextWindow),
+      defaultMaxTokens: toNum(provider.defaultMaxTokens),
+      input: inputToWire(provider.input),
+      reasoning: provider.reasoning,
+      thinkingBudgets: budgetToWire(provider.thinkingBudgets),
+      cacheRetention: provider.cacheRetention,
+      transport: provider.transport,
+      timeoutMs: toNum(provider.timeoutMs),
+      websocketConnectTimeoutMs: toNum(provider.websocketConnectTimeoutMs),
+      streamIdleTimeoutMs: toNum(provider.streamIdleTimeoutMs),
+      maxRequestImageBytes: toNum(provider.maxRequestImageBytes),
+      retryPolicy: provider.retryPolicy,
+      models: provider.models.map(modelToWire),
+    }) as Record<string, unknown>),
+  } as unknown as WireProvider
 }
 
 export function emptyProviderDraft(): ProviderDraft {
@@ -266,6 +322,7 @@ export function emptyProviderDraft(): ProviderDraft {
     maxRequestImageBytes: '',
     retryPolicy: undefined,
     models: [],
+    extra: {},
   }
 }
 
@@ -279,6 +336,7 @@ export function emptyModelDraft(): ModelDraft {
     input: { text: false, image: false },
     reasoningEfforts: { nonReasoning: false, levels: {} },
     compat: {},
+    extra: {},
   }
 }
 

package/src/config.ts

@@ -30,6 +30,15 @@ export const THINKING_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhig
 
 export const MODALITIES = ['text', 'image'] as const
 
+/** 路由适配器种类：pi = PiAiAdapter（默认）；deepseek = 官方 DeepSeekAdapter（文件通道）。 */
+export const ADAPTER_KINDS = ['pi', 'deepseek'] as const
+export type AdapterKind = (typeof ADAPTER_KINDS)[number]
+
+/** deepseek 路由的思考/推理档位（线协议枚举，对齐官方 llm-deepseek）。 */
+export const DEEPSEEK_THINKING = ['enabled', 'disabled'] as const
+export const DEEPSEEK_REASONING_EFFORTS = ['off', 'low', 'high', 'max'] as const
+export const DEEPSEEK_IMAGE_DETAILS = ['auto', 'low'] as const
+
 export const DEFAULT_CONTEXT_WINDOW = 262144
 export const DEFAULT_MAX_TOKENS = 32768
 export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000
@@ -56,10 +65,15 @@ export interface ModelEntryConfig {
   input?: Modality[]
   reasoningEfforts?: false | ReasoningEfforts
   compat?: Record<string, unknown>
+  /** 以下仅 adapter: deepseek 的 route 有效（官方 llm-deepseek 目录字段）。 */
+  imagePixelBudget?: number
+  imageMaxBytes?: number
+  imageDetail?: 'auto' | 'low'
 }
 
 /** 单个 provider route 配置（providers 字典的值）。 */
 export interface ProviderProfileConfig {
+  adapter?: AdapterKind
   extends?: string
   displayName?: string
   api?: ProtocolId
@@ -85,6 +99,18 @@ export interface ProviderProfileConfig {
   maxRequestImageBytes?: number
   retryPolicy?: unknown
   models?: ModelEntryConfig[]
+  /** 以下仅 adapter: deepseek 的 route 有效（透传官方 llm-deepseek 同名策略）。 */
+  thinking?: 'enabled' | 'disabled'
+  reasoningEffort?: 'off' | 'low' | 'high' | 'max'
+  maxRequestFilesBytes?: number
+  maxInlineRequestImageBytes?: number
+  maxImagesPerRequest?: number
+  imageOffloadByteQuantum?: number
+  inlineImageOffloadByteQuantum?: number
+  imageOffloadCountQuantum?: number
+  filesApiTimeoutMs?: number
+  fileExpiresAfterSeconds?: number
+  fileRefreshMarginSeconds?: number
 }
 
 /** 插件配置根。 */
@@ -131,9 +157,28 @@ const modelEntry = z.object({
     .union([z.const(false), reasoningEfforts])
     .description('可选 reasoning 档位：false=非推理模型；dict=档位→线值映射；缺省继承内置目录能力'),
   compat: compatDict.description('模型级 compat（字段级合并，压过 route 级与继承值）'),
+  imagePixelBudget: z
+    .number()
+    .step(1)
+    .min(1)
+    .description('（仅 adapter: deepseek）单张请求图片的总像素预算；缺省继承官方目录'),
+  imageMaxBytes: z
+    .number()
+    .step(1)
+    .min(1)
+    .description('（仅 adapter: deepseek）单张请求图片的编码字节上限；缺省继承官方目录'),
+  imageDetail: z
+    .union(DEEPSEEK_IMAGE_DETAILS)
+    .description('（仅 adapter: deepseek）图片细节档位；low 使用 512x512 像素预算'),
 })
 
 const providerProfile = z.object({
+  adapter: z
+    .union(ADAPTER_KINDS)
+    .description(
+      '路由适配器：pi=PiAiAdapter（默认，三协议）；deepseek=官方 DeepSeekAdapter（图片走 Files API 文件通道，失败自动降级 base64）',
+    )
+    .default('pi'),
   extends: z
     .string()
     .description(
@@ -172,6 +217,66 @@ const providerProfile = z.object({
     .natural()
     .description('单请求 base64 图片载荷上限字节；缺省 20MiB（rc8 起生效，旧配置免改）'),
   retryPolicy: z.any().description('provider 重试策略（dsh-llm RetryPolicy 形状，构建期校验）'),
+  thinking: z
+    .union(DEEPSEEK_THINKING)
+    .description('（仅 adapter: deepseek）思考模式开关；缺省用提供商默认'),
+  reasoningEffort: z
+    .union(DEEPSEEK_REASONING_EFFORTS)
+    .description('（仅 adapter: deepseek）推理档位；缺省为 high'),
+  maxRequestFilesBytes: z
+    .number()
+    .step(1)
+    .min(1)
+    .description('（仅 adapter: deepseek）单请求文件引用图片累积上限字节；缺省 128MiB'),
+  maxInlineRequestImageBytes: z
+    .number()
+    .step(1)
+    .min(1)
+    .description('（仅 adapter: deepseek）文件通道降级后 base64 图片载荷上限字节；缺省 20MiB'),
+  maxImagesPerRequest: z
+    .number()
+    .step(1)
+    .min(1)
+    .description(
+      '（仅 adapter: deepseek）单请求图片数量上限；缺省 600（调低时需同步调低 imageOffloadCountQuantum）',
+    ),
+  imageOffloadByteQuantum: z
+    .number()
+    .step(1)
+    .min(1)
+    .description(
+      '（仅 adapter: deepseek）文件引用超限后的原始字节削减步长；缺省 64MiB，不可超过 maxRequestFilesBytes',
+    ),
+  inlineImageOffloadByteQuantum: z
+    .number()
+    .step(1)
+    .min(1)
+    .description(
+      '（仅 adapter: deepseek）base64 降级超限后的削减步长；缺省 10MiB，不可超过 maxInlineRequestImageBytes',
+    ),
+  imageOffloadCountQuantum: z
+    .number()
+    .step(1)
+    .min(1)
+    .description(
+      '（仅 adapter: deepseek）图片数量超限后的削减步长；缺省 20，不可超过 maxImagesPerRequest',
+    ),
+  filesApiTimeoutMs: z
+    .number()
+    .min(Number.MIN_VALUE)
+    .max(MAX_TIMER_DELAY_MS)
+    .description('（仅 adapter: deepseek）单次 Files API 图片解析超时毫秒；缺省 60s'),
+  fileExpiresAfterSeconds: z
+    .number()
+    .step(1)
+    .min(3600)
+    .max(2592000)
+    .description('（仅 adapter: deepseek）上传文件的远端存活秒数；缺省 7 天'),
+  fileRefreshMarginSeconds: z
+    .number()
+    .step(1)
+    .min(0)
+    .description('（仅 adapter: deepseek）文件过期前提前重传的余量秒数；缺省 3600'),
   models: z
     .array(modelEntry)
     .description('本 route 的模型目录；缺省且 provider 有 extends 时继承该源全部模型'),

package/src/deepseek-routes.ts

@@ -0,0 +1,139 @@
+/**
+ * deepseek 路由注册器：每条 adapter: deepseek 的 route 一个官方
+ * DeepSeekAdapter 实例（baseURL 各异，无法共享实例），注册到独立路由名。
+ *
+ * 与官方 deepseek-official 渠道的隔离：
+ * - 路由名独立（重复名注册冲突时跳过并告警，不互相覆盖）；
+ * - 文件索引作用域 = sha256(baseURL + apiKey)（官方实现），中转与官方天然分池；
+ * - 适配器实例、连接事实、重试策略各自独立。
+ *
+ * 热更新：适配器 options thunk 每次操作重读当前物化产物（连接事实变化下一
+ * 请求生效）；retryPolicy 是注册期捕获事实，变化时 handle.replace 原地重注册
+ * （官方同款模式）；route 移除即 dispose 释放路由名。
+ * @module llm-pi/deepseek-routes
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import type { AdapterRegistrationHandle } from '@deepseek-ai/dsh-llm'
+import { deepEqualJson } from '@deepseek-ai/dsh-settings'
+
+import type { ResolvedDeepseekRoute } from './profiles-deepseek.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+interface RouteRegistration {
+  handle: AdapterRegistrationHandle
+  /** 注册期捕获的重试策略（变化才 replace）。 */
+  retryPolicy: unknown
+}
+
+export interface DeepseekRegistrarDeps {
+  ctx: Context
+  kit: DshKit
+  logger: {
+    warn(message: string): void
+    error(message: string | unknown): void
+  }
+  /** 当前物化产物表（service 层按 config identity 备忘）。 */
+  routes: () => Map<string, ResolvedDeepseekRoute>
+}
+
+/** 凭据解析（逐行对齐官方 llm-deepseek resolveApiKey）：凭据服务优先，启动环境兜底。 */
+function makeResolveApiKey(ctx: Context, kit: DshKit) {
+  return async (connection: { apiKeyEnv: unknown }): Promise<string> => {
+    const ref = connection.apiKeyEnv as CredentialRef
+    const credentials = ctx.get('credentials')
+    const hit =
+      credentials !== undefined
+        ? (await credentials.resolve(ref))?.value
+        : launchEnvironmentOf(ctx).get(ref as unknown as string)?.value
+    if (hit !== undefined && hit.length > 0) {
+      return kit.assertUsableApiKey(hit, 'llm-pi', ref as unknown as string)
+    }
+    throw new kit.LlmError(
+      `llm-pi: deepseek route 的凭据引用 ${String(ref)} 未解析到值——` +
+        '请经凭据服务（web Models 页）存放或导出环境变量',
+      'MISSING_CREDENTIAL',
+    )
+  }
+}
+
+export class DeepseekRouteRegistrar {
+  private readonly deps: DeepseekRegistrarDeps
+  private readonly registrations = new Map<string, RouteRegistration>()
+  private readonly resolveApiKey: (connection: { apiKeyEnv: unknown }) => Promise<string>
+  private userId: unknown
+
+  constructor(deps: DeepseekRegistrarDeps) {
+    this.deps = deps
+    this.resolveApiKey = makeResolveApiKey(deps.ctx, deps.kit)
+  }
+
+  /** 同步注册表与目标 route 集：新增注册、移除 dispose、retryPolicy 变化原地 replace。 */
+  sync(target: Map<string, ResolvedDeepseekRoute>): void {
+    for (const [route, registration] of this.registrations) {
+      if (target.has(route)) continue
+      registration.handle()
+      this.registrations.delete(route)
+      this.deps.logger.warn(`llm-pi: deepseek route "${route}" 已随配置移除而注销`)
+    }
+    for (const [route, built] of target) {
+      const existing = this.registrations.get(route)
+      if (existing !== undefined) {
+        this.refreshPolicy(route, built, existing)
+        continue
+      }
+      this.register(route, built)
+    }
+  }
+
+  private refreshPolicy(
+    route: string,
+    built: ResolvedDeepseekRoute,
+    registration: RouteRegistration,
+  ): void {
+    const policy = built.connection.retryPolicy
+    if (deepEqualJson(policy, registration.retryPolicy)) return
+    try {
+      registration.handle.replace([route])
+      registration.retryPolicy = policy
+    } catch (error) {
+      this.deps.logger.error(`llm-pi: deepseek route "${route}" 重试策略更新被拒，保留此前注册`)
+      this.deps.logger.error(error)
+    }
+  }
+
+  /** 匿名用户 id（首次调用时生成并备忘；register 前已确认 kit.deepseek 存在）。 */
+  private resolveUserId(): unknown {
+    if (this.userId === undefined) {
+      this.userId = this.deps.kit.deepseek?.getOrCreateAnonymousUserId()
+    }
+    return this.userId
+  }
+
+  private register(route: string, built: ResolvedDeepseekRoute): void {
+    const { ctx, kit, logger, routes } = this.deps
+    if (kit.deepseek === undefined) return // 构建期已拦截；此处只是类型护栏
+    const adapter = new kit.deepseek.DeepSeekAdapter({
+      options: () => {
+        const current = routes().get(route)
+        if (current === undefined) {
+          throw new kit.LlmError(`llm-pi: deepseek route "${route}" 已注销`, 'INVALID_REQUEST')
+        }
+        return current.connection
+      },
+      resolveApiKey: this.resolveApiKey as never,
+      resolveUserId: () => this.resolveUserId() as never,
+      resolveAttachments: () => ctx.get('attachments') as never,
+    })
+    try {
+      const handle = ctx.llm.registerAdapter([route], adapter as never)
+      this.registrations.set(route, { handle, retryPolicy: built.connection.retryPolicy })
+    } catch (error) {
+      logger.error(
+        `llm-pi: deepseek route "${route}" 注册失败（可能与其他 adapter 重名），该 route 不可用`,
+      )
+      logger.error(error)
+    }
+  }
+}

package/src/discovery.ts

@@ -7,6 +7,7 @@
  * @module llm-pi/discovery
  */
 import { builtinModelIds, hasBuiltinProvider } from './catalog/builtin.ts'
+import { officialModelIds } from './catalog/official.ts'
 import type { ProviderProfileConfig } from './config.ts'
 import type { DshKit } from './resolve-dsh.ts'
 
@@ -102,6 +103,32 @@ function readListing(kit: DshKit, body: unknown): DiscoveryEntry[] {
   return models
 }
 
+/** deepseek 路由直答：extends 'deepseek' 给官方目录全量；否则给 route 自配模型。 */
+function deepseekCatalogAnswer(kit: DshKit, route: ProviderProfileConfig): DiscoveryEntry[] {
+  if (kit.deepseek === undefined) {
+    throw new kit.LlmError(
+      '当前运行时套件不含 dsh-llm-deepseek，无法读取官方目录',
+      'DISCOVERY_FAILED',
+    )
+  }
+  if (route.extends === 'deepseek') {
+    return officialModelIds(kit).map((id) => ({ id }))
+  }
+  const models = (route.models ?? []).map((entry) => ({
+    id: entry.id,
+    ...(entry.name === undefined ? {} : { name: entry.name }),
+    ...(entry.contextWindow === undefined ? {} : { contextWindow: entry.contextWindow }),
+    ...(entry.maxTokens === undefined ? {} : { maxTokens: entry.maxTokens }),
+  }))
+  if (models.length === 0) {
+    throw new kit.LlmError(
+      '该 route 未配置 models 且未 extends deepseek；请手工录入模型',
+      'DISCOVERY_FAILED',
+    )
+  }
+  return models
+}
+
 /** 内置目录直答（route 配了 provider 级 extends 时）。 */
 function catalogAnswer(kit: DshKit, source: string): DiscoveryEntry[] {
   return builtinModelIds(kit, source).map((id) => {
@@ -117,8 +144,9 @@ function catalogAnswer(kit: DshKit, source: string): DiscoveryEntry[] {
 }
 
 /**
- * 回答"该 provider 可服务哪些模型"：extends 内置源零网络直答；
- * 否则仅 openai 系协议走 GET {baseURL}/models；其余协议明确不支持。
+ * 回答"该 provider 可服务哪些模型"：deepseek 路由读官方目录/自有配置直答；
+ * extends 内置源零网络直答；否则仅 openai 系协议走 GET {baseURL}/models；
+ * 其余协议明确不支持。
  */
 export async function discoverModels(
   request: DiscoveryRequest,
@@ -127,6 +155,9 @@ export async function discoverModels(
   const { kit } = deps
   const route: ProviderProfileConfig | undefined =
     request.provider === undefined ? undefined : deps.configProviders()[request.provider]
+  if ((route?.adapter ?? 'pi') === 'deepseek') {
+    return deepseekCatalogAnswer(kit, route)
+  }
   if (route?.extends !== undefined && hasBuiltinProvider(kit, route.extends)) {
     return catalogAnswer(kit, route.extends)
   }