@dsh-plus/llm-pi 0.1.5 → 0.1.7

package/src/profiles-deepseek.ts

@@ -0,0 +1,282 @@
+/**
+ * deepseek 路由物化：adapter: deepseek 的 provider 配置 → 官方 DeepSeekAdapter
+ * 可直接消费的 DeepSeekConnectionOptions。
+ *
+ * 语义对齐官方 llm-deepseek 的 resolveAdapterOptions，但继承源换为官方内置
+ * 目录（catalog/official.ts）：模型条目只写 id 即继承同名官方模型的模态、
+ * 像素预算等能力；extends: 'deepseek' 时全量继承官方目录。
+ *
+ * 物化产物最终再过一遍官方 resolveAdapterOptions 校验/补默认值，等于把
+ * 官方插件的配置闸门原样复用；文件通道（Files API 上传、file_id 引用、
+ * 失败降级 base64、配额清理）全部在 DeepSeekAdapter 内部，此处只喂配置。
+ * @module llm-pi/profiles-deepseek
+ */
+import type { DeepSeekConnectionOptions } from '@deepseek-ai/dsh-llm-deepseek'
+
+import {
+  type OfficialModelBase,
+  officialBaseUrl,
+  officialModelBase,
+  officialModelIds,
+} from './catalog/official.ts'
+import type { ModelEntryConfig, ProviderProfileConfig } from './config.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+export interface BuildDeepseekDeps {
+  kit: DshKit
+  /** 运行期宽松模式：数据源漂移时跳过 route 并告警，而非抛错弄挂注册循环。 */
+  lenient?: boolean
+  warn?: (message: string) => void
+}
+
+/** 物化产物：route 的展示名与适配器连接事实（注册期事实另见 connection.retryPolicy）。 */
+export interface ResolvedDeepseekRoute {
+  route: string
+  displayName: string
+  connection: DeepSeekConnectionOptions
+}
+
+/** 报告不可服务的 route，命名出错配置键（与 profiles.ts 的 invalid 同格式）。 */
+function invalid(provider: string, detail: string): never {
+  throw new Error(`llm-pi: provider "${provider}" ${detail}`)
+}
+
+/** pi 专有字段在 deepseek 路由上显式拒绝（静默忽略会让用户误以为生效）。 */
+const PI_ONLY_FIELDS = [
+  'api',
+  'compat',
+  'headers',
+  'transport',
+  'websocketConnectTimeoutMs',
+  'thinkingBudgets',
+  'cacheRetention',
+  'reasoning',
+  'defaultInput',
+  'maxRequestImageBytes',
+  'timeoutMs',
+] as const
+
+/** schema 解析会把 dict 字段物化为 {}（schemastery 行为）；空字典视为未配置。 */
+function nonEmptyDict(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && Object.keys(value).length > 0
+}
+
+/** defaultInput 的 schema 物化默认（['text']）；显式写同值无害，同样视为未配置。 */
+function isMaterializedDefaultInput(value: unknown): boolean {
+  return Array.isArray(value) && value.length === 1 && value[0] === 'text'
+}
+
+function rejectPiOnlyFields(route: string, profile: ProviderProfileConfig): void {
+  for (const field of PI_ONLY_FIELDS) {
+    const value = profile[field]
+    if (value === undefined) continue
+    if (field === 'compat' || field === 'headers' || field === 'thinkingBudgets') {
+      if (!nonEmptyDict(value)) continue
+    } else if (field === 'defaultInput' && isMaterializedDefaultInput(value)) {
+      continue
+    }
+    invalid(route, `的 ${field} 仅 adapter: pi 可用；adapter: deepseek 的 route 请移除该字段`)
+  }
+}
+
+/** 解析模型条目的官方目录继承 base；extends 仅允许裸 id 或 "deepseek/id"。 */
+function resolveOfficialBase(
+  route: string,
+  entry: ModelEntryConfig,
+  deps: BuildDeepseekDeps,
+): OfficialModelBase {
+  const ref = entry.extends
+  if (ref !== undefined) {
+    const slash = ref.indexOf('/')
+    const source = slash < 0 ? 'deepseek' : ref.slice(0, slash)
+    const id = slash < 0 ? ref : ref.slice(slash + 1)
+    if (source !== 'deepseek' || id.length === 0 || id.includes('/')) {
+      invalid(
+        route,
+        `model "${entry.id}" 的 extends 引用 ${JSON.stringify(ref)} 非法：` +
+          'adapter: deepseek 的路由仅支持 "deepseek/model" 或裸 model id（官方目录）',
+      )
+    }
+    const base = officialModelBase(deps.kit, id)
+    if (base === undefined) {
+      if (deps.lenient) {
+        deps.warn?.(
+          `llm-pi: provider "${route}" model "${entry.id}" 的 extends 引用 "${ref}" 在当前官方目录` +
+            '未命中；已降级为手写条目',
+        )
+        return {}
+      }
+      invalid(route, `model "${entry.id}" 的 extends 引用 "${ref}" 在官方目录中不存在`)
+    }
+    return base
+  }
+  // 缺省：同名继承官方目录（未命中即手写条目，缺省值由官方 schema 兜底）
+  return officialModelBase(deps.kit, entry.id) ?? {}
+}
+
+/** 条目的声明模态；schema 物化的空数组视为"无答案"，交官方继承 base（同 profiles.ts declaredInput）。 */
+function declaredModalities(
+  configured: readonly ('text' | 'image')[] | undefined,
+): ('text' | 'image')[] | undefined {
+  return configured === undefined || configured.length === 0 ? undefined : [...configured]
+}
+
+/** 物化单个模型目录条目：官方 base 在下，条目显式字段逐字段覆盖。 */
+function materializeModel(
+  route: string,
+  entry: ModelEntryConfig,
+  deps: BuildDeepseekDeps,
+): Record<string, unknown> {
+  if (entry.reasoningEfforts !== undefined || nonEmptyDict(entry.compat)) {
+    invalid(route, `model "${entry.id}" 的 reasoningEfforts/compat 仅 adapter: pi 可用`)
+  }
+  const base = resolveOfficialBase(route, entry, deps)
+  const input = declaredModalities(entry.input) ?? base.input
+  const imageFields = {
+    imagePixelBudget: entry.imagePixelBudget ?? base.imagePixelBudget,
+    imageMaxBytes: entry.imageMaxBytes ?? base.imageMaxBytes,
+    imageDetail: entry.imageDetail ?? base.imageDetail,
+  }
+  const acceptsImage = input?.includes('image') ?? false
+  if (!acceptsImage && Object.values(imageFields).some((value) => value !== undefined)) {
+    invalid(
+      route,
+      `model "${entry.id}" 未声明 image 模态，不可配置 imagePixelBudget/imageMaxBytes/imageDetail`,
+    )
+  }
+  return {
+    id: entry.id,
+    ...((entry.name ?? base.name) === undefined ? {} : { name: entry.name ?? base.name }),
+    ...((entry.contextWindow ?? base.contextWindow) === undefined
+      ? {}
+      : { contextWindow: entry.contextWindow ?? base.contextWindow }),
+    ...((entry.maxTokens ?? base.maxTokens) === undefined
+      ? {}
+      : { maxTokens: entry.maxTokens ?? base.maxTokens }),
+    ...(input === undefined ? {} : { inputModalities: [...input] }),
+    ...(Object.fromEntries(
+      Object.entries(imageFields).filter(([, value]) => value !== undefined),
+    ) as Record<string, unknown>),
+  }
+}
+
+/** 物化一个 route 的模型目录；models 缺省时以官方目录全量继承（要求 extends: 'deepseek'）。 */
+function materializeModels(
+  route: string,
+  profile: ProviderProfileConfig,
+  deps: BuildDeepseekDeps,
+): Record<string, unknown>[] {
+  if (profile.models !== undefined && profile.models.length > 0) {
+    const seen = new Set<string>()
+    return profile.models.map((entry) => {
+      if (entry.id.length === 0) invalid(route, '存在空 id 的模型条目')
+      if (seen.has(entry.id)) invalid(route, `模型 "${entry.id}" 重复列出`)
+      seen.add(entry.id)
+      return materializeModel(route, entry, deps)
+    })
+  }
+  if (profile.extends === 'deepseek') {
+    return officialModelIds(deps.kit).map((id) => materializeModel(route, { id }, deps))
+  }
+  invalid(
+    route,
+    '未配置 models；adapter: deepseek 的 route 可配 extends: deepseek 全量继承官方目录',
+  )
+}
+
+/** 组装官方 resolveAdapterOptions 的输入：仅放入显式配置的键，其余走官方默认值。 */
+function rawAdapterConfig(
+  profile: ProviderProfileConfig,
+  baseURL: string,
+  models: Record<string, unknown>[],
+): Record<string, unknown> {
+  const passthrough = [
+    'apiKeyEnv',
+    'thinking',
+    'reasoningEffort',
+    'streamIdleTimeoutMs',
+    'maxRequestFilesBytes',
+    'maxInlineRequestImageBytes',
+    'maxImagesPerRequest',
+    'imageOffloadByteQuantum',
+    'inlineImageOffloadByteQuantum',
+    'imageOffloadCountQuantum',
+    'filesApiTimeoutMs',
+    'fileExpiresAfterSeconds',
+    'fileRefreshMarginSeconds',
+    'retryPolicy',
+  ] as const
+  const raw: Record<string, unknown> = { baseURL, models }
+  for (const key of passthrough) {
+    if (profile[key] !== undefined) raw[key] = profile[key]
+  }
+  if (profile.defaultMaxTokens !== undefined) raw['maxTokens'] = profile.defaultMaxTokens
+  if (profile.defaultContextWindow !== undefined) {
+    raw['defaultContextWindow'] = profile.defaultContextWindow
+  }
+  return raw
+}
+
+/** 物化单个 deepseek route；lenient 下失败告警并返回 null（调用方跳过注册）。 */
+function buildRoute(
+  route: string,
+  profile: ProviderProfileConfig,
+  deps: BuildDeepseekDeps,
+): ResolvedDeepseekRoute | null {
+  try {
+    if (deps.kit.deepseek === undefined) {
+      invalid(
+        route,
+        '使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（需 dsh ≥ 0.1.1-rc.2）',
+      )
+    }
+    rejectPiOnlyFields(route, profile)
+    if (profile.extends !== undefined && profile.extends !== 'deepseek') {
+      invalid(
+        route,
+        `的 extends ${JSON.stringify(profile.extends)} 非法：adapter: deepseek 仅支持 "deepseek"（官方目录）`,
+      )
+    }
+    if (profile.apiKeyEnv === undefined || profile.apiKeyEnv.length === 0) {
+      invalid(route, '需要 apiKeyEnv：DeepSeekAdapter 无环境自发现，凭据引用必须显式配置')
+    }
+    const baseURL =
+      profile.baseURL ?? (profile.extends === 'deepseek' ? officialBaseUrl(deps.kit) : undefined)
+    if (baseURL === undefined || baseURL.length === 0) {
+      invalid(route, '需要 baseURL（或 extends: deepseek 继承官方端点）')
+    }
+    const models = materializeModels(route, profile, deps)
+    const connection = deps.kit.deepseek.resolveAdapterOptions(
+      rawAdapterConfig(profile, baseURL, models) as never,
+      undefined,
+    )
+    return { route, displayName: profile.displayName ?? route, connection }
+  } catch (error) {
+    if (!deps.lenient) throw error
+    deps.warn?.(
+      `llm-pi: deepseek route "${route}" 不可服务（${error instanceof Error ? error.message : String(error)}），已跳过注册`,
+    )
+    return null
+  }
+}
+
+/**
+ * 校验并物化全部 adapter: deepseek 的 route。严格模式任一 route 失败即整体
+ * 抛错（settings 写入校验），lenient 模式跳过坏 route（运行期热更新）。
+ */
+export function buildDeepseekRoutes(
+  providers: Record<string, ProviderProfileConfig> | undefined,
+  deps: BuildDeepseekDeps,
+): Map<string, ResolvedDeepseekRoute> {
+  const resolved = new Map<string, ResolvedDeepseekRoute>()
+  for (const [route, profile] of Object.entries(providers ?? {})) {
+    if ((profile.adapter ?? 'pi') !== 'deepseek') continue
+    if (route.length === 0) throw new Error('llm-pi: provider 名不能为空')
+    if (profile.displayName !== undefined && profile.displayName.length === 0) {
+      invalid(route, 'displayName 为空')
+    }
+    const built = buildRoute(route, profile, deps)
+    if (built !== null) resolved.set(route, built)
+  }
+  return resolved
+}

package/src/profiles.ts

@@ -14,20 +14,25 @@
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { ResolvedPiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
 
-import { inheritedCatalogEntries, builtinProviderBaseUrl, type ModelBase } from './catalog/builtin.ts'
+import {
+  builtinProviderBaseUrl,
+  inheritedCatalogEntries,
+  type ModelBase,
+} from './catalog/builtin.ts'
 import type { ModelsDevSource } from './catalog/models-dev.ts'
 import { mergeCompat, validateCompat } from './compat.ts'
 import {
   DEFAULT_CONTEXT_WINDOW,
-  DEFAULT_MAX_TOKENS,
   DEFAULT_MAX_REQUEST_IMAGE_BYTES,
+  DEFAULT_MAX_TOKENS,
   DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   MAX_TIMER_DELAY_MS,
-  THINKING_LEVELS,
   type ModelEntryConfig,
   type ProviderProfileConfig,
+  THINKING_LEVELS,
 } from './config.ts'
 import { ExtendsError, resolveModelBase } from './inherit.ts'
+import { buildDeepseekRoutes } from './profiles-deepseek.ts'
 import type { DshKit } from './resolve-dsh.ts'
 
 /** 内置目录未描述时的零价目（harness 不消费 cost 元数据，同官方 NO_COST）。 */
@@ -52,7 +57,9 @@ function invalid(provider: string, detail: string): never {
 }
 
 /** 条目的声明模态；缺省/空数组都视为"无答案"，交下一级（同官方 declaredInput）。 */
-function declaredInput(configured: readonly ('text' | 'image')[] | undefined): ('text' | 'image')[] | undefined {
+function declaredInput(
+  configured: readonly ('text' | 'image')[] | undefined,
+): ('text' | 'image')[] | undefined {
   return configured === undefined || configured.length === 0 ? undefined : [...configured]
 }
 
@@ -73,7 +80,9 @@ function resolveModelReasoning(
       reasoning: base.reasoning,
       ...(base.thinkingLevelMap === undefined
         ? {}
-        : { thinkingLevelMap: base.thinkingLevelMap as Record<string, string | null> }),
+        : {
+            thinkingLevelMap: base.thinkingLevelMap as Record<string, string | null>,
+          }),
     }
   }
   if (efforts === false) return { reasoning: false }
@@ -84,12 +93,15 @@ function resolveModelReasoning(
     const wire = (efforts as Record<string, string | null | undefined>)[level]
     if (wire === undefined) continue
     if (wire === null) {
-      if (level !== 'off') invalid(provider, `model "${entry.id}" reasoningEfforts.${level} 需要线值；仅 off 可留空`)
+      if (level !== 'off')
+        invalid(provider, `model "${entry.id}" reasoningEfforts.${level} 需要线值；仅 off 可留空`)
     } else if (wire.length === 0) {
       invalid(provider, `model "${entry.id}" reasoningEfforts.${level} 不能为空字符串`)
     }
   }
-  const declared = THINKING_LEVELS.filter((level) => (efforts as Record<string, unknown>)[level] !== undefined)
+  const declared = THINKING_LEVELS.filter(
+    (level) => (efforts as Record<string, unknown>)[level] !== undefined,
+  )
   if (!declared.some((level) => level !== 'off')) {
     invalid(provider, `model "${entry.id}" reasoningEfforts 只有 off；声明思考档位或置 false`)
   }
@@ -107,7 +119,10 @@ function harnessApiKeyAuth(name: string) {
   return {
     name,
     resolve: ({ credential }: { credential?: { key?: string } }) =>
-      Promise.resolve({ auth: credential?.key === undefined ? {} : { apiKey: credential.key }, source: name }),
+      Promise.resolve({
+        auth: credential?.key === undefined ? {} : { apiKey: credential.key },
+        source: name,
+      }),
   }
 }
 
@@ -142,7 +157,9 @@ function materializeModel(
   const api = profile.api ?? base.api ?? routeApi
   if (api === undefined) {
     if (deps.lenient) {
-      deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 无法获得 api（继承源缺失），已跳过该模型`)
+      deps.warn?.(
+        `llm-pi: provider "${route}" model "${entry.id}" 无法获得 api（继承源缺失），已跳过该模型`,
+      )
       return null
     }
     invalid(route, `model "${entry.id}" 需要 api：继承源未提供，请在 route 上设置 api`)
@@ -150,16 +167,27 @@ function materializeModel(
   const baseUrl = profile.baseURL ?? base.baseUrl ?? providerBaseUrl
   if (baseUrl === undefined) {
     if (deps.lenient) {
-      deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 无法获得 baseURL（继承源缺失），已跳过该模型`)
+      deps.warn?.(
+        `llm-pi: provider "${route}" model "${entry.id}" 无法获得 baseURL（继承源缺失），已跳过该模型`,
+      )
       return null
     }
     invalid(route, `model "${entry.id}" 需要 baseURL：继承源未提供，请在 route 上设置 baseURL`)
   }
-  const contextWindow = entry.contextWindow ?? base.contextWindow ?? profile.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW
-  const maxTokens = entry.maxTokens ?? base.maxTokens ?? profile.defaultMaxTokens ?? DEFAULT_MAX_TOKENS
+  const contextWindow =
+    entry.contextWindow ??
+    base.contextWindow ??
+    profile.defaultContextWindow ??
+    DEFAULT_CONTEXT_WINDOW
+  const maxTokens =
+    entry.maxTokens ?? base.maxTokens ?? profile.defaultMaxTokens ?? DEFAULT_MAX_TOKENS
   if (entry.maxTokens !== undefined) configuredMaxTokens.set(entry.id, entry.maxTokens)
   validateCompat(api, profile.compat as Record<string, unknown> | undefined, `provider "${route}"`)
-  validateCompat(api, entry.compat as Record<string, unknown> | undefined, `provider "${route}" model "${entry.id}"`)
+  validateCompat(
+    api,
+    entry.compat as Record<string, unknown> | undefined,
+    `provider "${route}" model "${entry.id}"`,
+  )
   const compat = mergeCompat(
     base.api === api ? base.compat : undefined,
     profile.compat as Record<string, unknown> | undefined,
@@ -188,7 +216,10 @@ function materializeRouteModels(
   profile: ProviderProfileConfig,
   deps: BuildDeps,
   defaultInput: ('text' | 'image')[],
-): { models: MaterializedModel[]; configuredMaxTokens: Map<string, number> } | null {
+): {
+  models: MaterializedModel[]
+  configuredMaxTokens: Map<string, number>
+} | null {
   const configuredMaxTokens = new Map<string, number>()
   const providerBaseUrl =
     profile.extends === undefined ? undefined : builtinProviderBaseUrl(deps.kit, profile.extends)
@@ -247,14 +278,19 @@ function materializeRouteModels(
     .filter((model): model is MaterializedModel => model !== null)
   if (models.length === 0) {
     if (deps.lenient) {
-      deps.warn?.(`llm-pi: provider "${route}" 当前没有可服务的模型（继承源漂移），已跳过该 route 的注册`)
+      deps.warn?.(
+        `llm-pi: provider "${route}" 当前没有可服务的模型（继承源漂移），已跳过该 route 的注册`,
+      )
       return null
     }
     invalid(route, 'route 内没有可服务的模型')
   }
   const finalApis = new Set(models.map((m) => m.api))
   if (finalApis.size > 1) {
-    invalid(route, `route 内模型协议不一致（${[...finalApis].join(', ')}）；一个 route 只能服务一种协议`)
+    invalid(
+      route,
+      `route 内模型协议不一致（${[...finalApis].join(', ')}）；一个 route 只能服务一种协议`,
+    )
   }
   return { models, configuredMaxTokens }
 }
@@ -270,12 +306,16 @@ export function buildProfiles(
 ): Map<string, ResolvedPiAiProviderProfile> {
   const resolved = new Map<string, ResolvedPiAiProviderProfile>()
   for (const [route, profile] of Object.entries(providers ?? {})) {
+    // adapter: deepseek 的 route 由 profiles-deepseek.ts 物化（官方 DeepSeekAdapter 链路）
+    if ((profile.adapter ?? 'pi') === 'deepseek') continue
     if (route.length === 0) throw new Error('llm-pi: provider 名不能为空')
     // 注意：不做"route 名与内置 provider 名重名"的静态校验——内置名 ≠ 已注册
     // route（如官方 llm-pi-ai 配置清空后 anthropic 名可用）。真实冲突只在注册期
     // 暴露（DUPLICATE_ADAPTER），由 service 层逐个 route 注册降级处理。
-    if (profile.baseURL !== undefined && profile.baseURL.length === 0) invalid(route, 'baseURL 为空')
-    if (profile.displayName !== undefined && profile.displayName.length === 0) invalid(route, 'displayName 为空')
+    if (profile.baseURL !== undefined && profile.baseURL.length === 0)
+      invalid(route, 'baseURL 为空')
+    if (profile.displayName !== undefined && profile.displayName.length === 0)
+      invalid(route, 'displayName 为空')
     const streamIdleTimeoutMs = profile.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
     if (
       !Number.isFinite(streamIdleTimeoutMs) ||
@@ -290,9 +330,15 @@ export function buildProfiles(
     const catalog = materializeRouteModels(route, profile, deps, defaultInput)
     if (catalog === null) continue // lenient 下 route 无模型可服务，跳过注册
     const api = catalog.models[0]?.api
-    const factory = api === undefined ? undefined : deps.kit.protocolFactories[api as keyof DshKit['protocolFactories']]
+    const factory =
+      api === undefined
+        ? undefined
+        : deps.kit.protocolFactories[api as keyof DshKit['protocolFactories']]
     if (factory === undefined) {
-      invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`)
+      invalid(
+        route,
+        `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`,
+      )
     }
     const piProvider = deps.kit.createProvider({
       id: route,
@@ -319,7 +365,9 @@ export function buildProfiles(
       ),
       ...(profile.headers === undefined ? {} : { headers: { ...profile.headers } }),
       ...(profile.reasoning === undefined ? {} : { reasoning: profile.reasoning }),
-      ...(profile.thinkingBudgets === undefined ? {} : { thinkingBudgets: { ...profile.thinkingBudgets } }),
+      ...(profile.thinkingBudgets === undefined
+        ? {}
+        : { thinkingBudgets: { ...profile.thinkingBudgets } }),
       ...(profile.cacheRetention === undefined ? {} : { cacheRetention: profile.cacheRetention }),
       ...(profile.transport === undefined ? {} : { transport: profile.transport }),
       ...(profile.timeoutMs === undefined ? {} : { timeoutMs: profile.timeoutMs }),
@@ -339,4 +387,6 @@ export function assertServiceable(
   deps: BuildDeps,
 ): void {
   buildProfiles(config.providers, deps)
+  // deepseek 路由同样整体验证（严格模式）：写入处拒绝非法配置
+  buildDeepseekRoutes(config.providers, deps)
 }

package/src/resolve-dsh.ts

@@ -16,21 +16,38 @@
 import { existsSync, realpathSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-
-import type { PiAiAdapter as PiAiAdapterType } from '@deepseek-ai/dsh-llm-pi-ai'
+import type { getOrCreateAnonymousUserId as getAnonIdType } from '@deepseek-ai/dsh-anonymous-user-id'
+import * as vendoredAnonId from '@deepseek-ai/dsh-anonymous-user-id'
 import type * as DshLlm from '@deepseek-ai/dsh-llm'
+import * as vendoredLlm from '@deepseek-ai/dsh-llm'
+import type {
+  DeepSeekAdapter as DeepSeekAdapterType,
+  resolveAdapterOptions as resolveDeepSeekOptionsType,
+} from '@deepseek-ai/dsh-llm-deepseek'
+import * as vendoredDeepseek from '@deepseek-ai/dsh-llm-deepseek'
+import type { PiAiAdapter as PiAiAdapterType } from '@deepseek-ai/dsh-llm-pi-ai'
+import * as vendoredPiAiAdapter from '@deepseek-ai/dsh-llm-pi-ai'
 import type * as PiAi from '@earendil-works/pi-ai'
-
 import * as vendoredPiAi from '@earendil-works/pi-ai'
-import * as vendoredCatalog from '@earendil-works/pi-ai/providers/all'
 import { anthropicMessagesApi as vendoredAnthropic } from '@earendil-works/pi-ai/api/anthropic-messages.lazy'
 import { openAICompletionsApi as vendoredCompletions } from '@earendil-works/pi-ai/api/openai-completions.lazy'
 import { openAIResponsesApi as vendoredResponses } from '@earendil-works/pi-ai/api/openai-responses.lazy'
-import * as vendoredLlm from '@deepseek-ai/dsh-llm'
-import * as vendoredPiAiAdapter from '@deepseek-ai/dsh-llm-pi-ai'
+import * as vendoredCatalog from '@earendil-works/pi-ai/providers/all'
 
 import type { ProtocolId } from './config.ts'
 
+/**
+ * deepseek 适配器模块表面（可选）：dsh-llm-deepseek 的官方 DeepSeekAdapter
+ * 与目录解析器 + 匿名用户 id。缺失（旧版 dsh 树或形状漂移）不拖垮核心
+ * 套件——deepseek 类 route 在构建期以明确错误拒绝，pi 路由不受影响。
+ * 与核心套件强制同源（杜绝跨源模块混用：brand/LlmError 恒等性敏感）。
+ */
+export interface DeepSeekKit {
+  DeepSeekAdapter: typeof DeepSeekAdapterType
+  resolveAdapterOptions: typeof resolveDeepSeekOptionsType
+  getOrCreateAnonymousUserId: typeof getAnonIdType
+}
+
 /** 插件运行期所需的全部上游模块表面（单一来源，内部一致）。 */
 export interface DshKit {
   /** 解析来源：dsh 安装树 / 插件 vendored 兜底副本。 */
@@ -48,6 +65,8 @@ export interface DshKit {
   getBuiltinModels: typeof vendoredCatalog.getBuiltinModels
   /** 三协议的 pi-ai api 实现工厂（与官方 PROTOCOLS 表同来源）。 */
   protocolFactories: Record<ProtocolId, () => unknown>
+  /** deepseek 文件通道路由所需模块；同源自检失败时为 undefined（见 diagnostics）。 */
+  deepseek?: DeepSeekKit
 }
 
 /** kit 必备形状清单：缺失即视为上游不兼容。 */
@@ -55,7 +74,13 @@ function assertKitShape(kit: DshKit, origin: string): void {
   const problems: string[] = []
   if (typeof kit.PiAiAdapter !== 'function') problems.push('PiAiAdapter 不是类')
   else {
-    for (const method of ['current', 'stream', 'listModels', 'resolveModel', 'providerInfo'] as const) {
+    for (const method of [
+      'current',
+      'stream',
+      'listModels',
+      'resolveModel',
+      'providerInfo',
+    ] as const) {
       if (typeof (kit.PiAiAdapter.prototype as Record<string, unknown>)[method] !== 'function') {
         problems.push(`PiAiAdapter.prototype.${method} 缺失`)
       }
@@ -74,6 +99,22 @@ function assertKitShape(kit: DshKit, origin: string): void {
   }
 }
 
+/** deepseek 模块形状自检；返回问题清单（空 = 可用），由调用方决定降级。 */
+function checkDeepseekShape(kit: DeepSeekKit): string[] {
+  const problems: string[] = []
+  if (typeof kit.DeepSeekAdapter !== 'function') problems.push('DeepSeekAdapter 不是类')
+  else if (
+    typeof (kit.DeepSeekAdapter.prototype as Record<string, unknown>)['stream'] !== 'function'
+  ) {
+    problems.push('DeepSeekAdapter.prototype.stream 缺失')
+  }
+  if (typeof kit.resolveAdapterOptions !== 'function') problems.push('resolveAdapterOptions 缺失')
+  if (typeof kit.getOrCreateAnonymousUserId !== 'function') {
+    problems.push('getOrCreateAnonymousUserId 缺失')
+  }
+  return problems
+}
+
 /** 从 startDir 向上找同时含有 dsh-llm-pi-ai 与 pi-ai 的安装树根。 */
 function findDshTreeRoot(startDir: string): string | undefined {
   let dir = startDir
@@ -119,6 +160,33 @@ async function importTreeModules(root: string): Promise<TreeModules> {
   return { piAiAdapter, llm, piAi, catalog, completions, responses, anthropic }
 }
 
+/** 从同一 dsh 安装树加载 deepseek 适配器模块（失败返回 undefined，不拖垮核心套件）。 */
+async function importTreeDeepseek(root: string): Promise<{ kit?: DeepSeekKit; problem?: string }> {
+  const nm = join(root, 'node_modules')
+  const load = (absPath: string): Promise<Record<string, unknown>> =>
+    import(pathToFileURL(absPath).href) as Promise<Record<string, unknown>>
+  try {
+    const [deepseek, anonId] = await Promise.all([
+      load(join(nm, '@deepseek-ai', 'dsh-llm-deepseek', 'lib', 'index.js')),
+      load(join(nm, '@deepseek-ai', 'dsh-anonymous-user-id', 'lib', 'index.js')),
+    ])
+    const kit: DeepSeekKit = {
+      DeepSeekAdapter: deepseek['DeepSeekAdapter'] as DeepSeekKit['DeepSeekAdapter'],
+      resolveAdapterOptions: deepseek[
+        'resolveAdapterOptions'
+      ] as DeepSeekKit['resolveAdapterOptions'],
+      getOrCreateAnonymousUserId: anonId[
+        'getOrCreateAnonymousUserId'
+      ] as DeepSeekKit['getOrCreateAnonymousUserId'],
+    }
+    const problems = checkDeepseekShape(kit)
+    if (problems.length > 0) return { problem: `形状不兼容：${problems.join('；')}` }
+    return { kit }
+  } catch (error) {
+    return { problem: error instanceof Error ? error.message : String(error) }
+  }
+}
+
 function kitFromTree(mods: TreeModules): DshKit {
   return {
     source: 'dsh-tree',
@@ -141,8 +209,19 @@ function kitFromTree(mods: TreeModules): DshKit {
   }
 }
 
+/** vendored 兜底副本的 deepseek 模块（形状自检不过时返回 undefined）。 */
+function loadVendoredDeepseek(): DeepSeekKit | undefined {
+  const kit: DeepSeekKit = {
+    DeepSeekAdapter: vendoredDeepseek.DeepSeekAdapter,
+    resolveAdapterOptions: vendoredDeepseek.resolveAdapterOptions,
+    getOrCreateAnonymousUserId: vendoredAnonId.getOrCreateAnonymousUserId,
+  }
+  return checkDeepseekShape(kit).length === 0 ? kit : undefined
+}
+
 /** vendored 兜底副本套件（导出供单测直接使用，免走 dsh 树解析）。 */
 export function loadVendoredKit(): DshKit {
+  const deepseek = loadVendoredDeepseek()
   const kit: DshKit = {
     source: 'vendored',
     PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
@@ -161,6 +240,7 @@ export function loadVendoredKit(): DshKit {
       'openai-responses': vendoredResponses,
       'anthropic-messages': vendoredAnthropic,
     },
+    ...(deepseek === undefined ? {} : { deepseek }),
   }
   assertKitShape(kit, 'vendored')
   return kit
@@ -182,13 +262,24 @@ function dshTreeAnchor(): string | undefined {
  * 两者都过不了形状自检时抛错（调用方应记日志并放弃注册 route）。
  * 返回的 diagnostics 记录回退原因，供配置卡片与日志展示。
  */
-export async function resolveDshKit(): Promise<{ kit: DshKit; diagnostics: string[] }> {
+export async function resolveDshKit(): Promise<{
+  kit: DshKit
+  diagnostics: string[]
+}> {
   const diagnostics: string[] = []
   const anchor = dshTreeAnchor()
   if (anchor !== undefined) {
     try {
       const kit = kitFromTree(await importTreeModules(anchor))
       assertKitShape(kit, 'dsh-tree')
+      const tree = await importTreeDeepseek(anchor)
+      if (tree.kit !== undefined) {
+        return { kit: { ...kit, deepseek: tree.kit }, diagnostics }
+      }
+      diagnostics.push(
+        `dsh 安装树的 dsh-llm-deepseek 不可用（${tree.problem ?? '未知原因'}）；` +
+          'adapter: deepseek 的 route 不可用，pi 路由不受影响',
+      )
       return { kit, diagnostics }
     } catch (error) {
       diagnostics.push(
@@ -199,5 +290,10 @@ export async function resolveDshKit(): Promise<{ kit: DshKit; diagnostics: strin
     diagnostics.push('未能从 process.argv[1] 定位 dsh 安装树；回退 vendored 副本')
   }
   const kit = loadVendoredKit()
+  if (kit.deepseek === undefined) {
+    diagnostics.push(
+      'vendored 副本的 dsh-llm-deepseek 形状不兼容；adapter: deepseek 的 route 不可用',
+    )
+  }
   return { kit, diagnostics }
 }