@dsh-plus/llm-pi 0.1.0

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh 插件：自定义 LLM 路由（方案 4 基准层）。
+ *
+ * 复用官方 PiAiAdapter（消息互译/护栏零重写），经官方承认的 profiles 回调
+ * 接缝注入插件自建的 provider 物化产物，从而获得：
+ * - 全量 compat（逐协议字段表，写入即校验，对比官方的 2 字段+静默丢弃）；
+ * - 模型继承（内置目录 → models.dev 快照 → 手写，用户显式字段最终覆盖）；
+ * - 模块解析优先 dsh 安装树（dsh 升级即自动跟随上游），vendored 副本兜底。
+ *
+ * 注册全新的 route 名，不触碰官方 llm-pi-ai 的任何 route 与配置。
+ * @module @dsh-plus/llm-pi
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { Config, type LlmPiConfig } from './config.ts'
+import { registerConfigApi } from './config-api.ts'
+import { startRuntime } from './service.ts'
+
+export const name = 'dsh-plus-llm-pi'
+
+export const inject = ['llm'] as const
+
+export { Config }
+
+export type { LlmPiConfig, ProviderProfileConfig, ModelEntryConfig, WireConfig } from './config.ts'
+export { SETTINGS_NS } from './config.ts'
+
+export async function apply(ctx: Context, config: LlmPiConfig): Promise<void> {
+  const runtime = await startRuntime(ctx, config)
+  ctx.inject(['webServer'], (webCtx) => {
+    registerConfigApi(webCtx, runtime)
+  })
+}

package/src/inherit.ts

@@ -0,0 +1,85 @@
+/**
+ * extends 继承解析：把 provider/model 条目上的继承引用解析为继承 base。
+ *
+ * 数据源优先级（三级）：
+ * 1. pi-ai 内置目录（含官方校正，最可信）；
+ * 2. models.dev 快照（仅内置未收录的新模型，字段保守）；
+ * 3. 都未命中 → 手写模型（无 base，必填字段由配置/兜底给出）。
+ *
+ * 引用语法：`"provider/model"` 显式跨源；裸 `"model"` 随 route 级 extends 源；
+ * 条目缺省 extends 时以 route extends 源下的同名模型为 base。
+ * @module llm-pi/inherit
+ */
+import type { ModelBase } from './catalog/builtin.ts'
+import { builtinModelBase } from './catalog/builtin.ts'
+import type { ModelsDevSource } from './catalog/models-dev.ts'
+import type { ModelEntryConfig, ProviderProfileConfig } from './config.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+export interface BaseResolution {
+  base: ModelBase
+  source: 'builtin' | 'models-dev' | 'none'
+  /** 实际命中的继承源 provider（诊断/错误消息用）。 */
+  sourceProvider?: string
+}
+
+export class ExtendsError extends Error {}
+
+/** 解析 "provider/model" 或裸 "model" 引用。 */
+export function parseExtendsRef(raw: string): { provider?: string; model: string } {
+  const slash = raw.indexOf('/')
+  if (slash < 0) return { model: raw }
+  const provider = raw.slice(0, slash)
+  const model = raw.slice(slash + 1)
+  if (provider.length === 0 || model.length === 0 || model.includes('/')) {
+    throw new ExtendsError(`extends 引用 ${JSON.stringify(raw)} 非法：应为 "provider/model" 或 "model"`)
+  }
+  return { provider, model }
+}
+
+function lookup(
+  kit: DshKit,
+  modelsDev: ModelsDevSource | undefined,
+  provider: string,
+  model: string,
+): BaseResolution | undefined {
+  const builtin = builtinModelBase(kit, provider, model)
+  if (builtin !== undefined) return { base: builtin, source: 'builtin', sourceProvider: provider }
+  const dev = modelsDev?.lookup(provider, model)
+  if (dev !== undefined) return { base: dev, source: 'models-dev', sourceProvider: provider }
+  return undefined
+}
+
+/**
+ * 解析一个模型条目的继承 base。
+ * @throws ExtendsError 显式 extends 引用不存在（写入时拒绝，指明引用名）。
+ */
+export function resolveModelBase(
+  route: string,
+  profile: ProviderProfileConfig,
+  entry: ModelEntryConfig,
+  kit: DshKit,
+  modelsDev: ModelsDevSource | undefined,
+): BaseResolution {
+  const where = `provider "${route}" model "${entry.id}"`
+  if (entry.extends === undefined) {
+    if (profile.extends === undefined) return { base: {}, source: 'none' }
+    return (
+      lookup(kit, modelsDev, profile.extends, entry.id) ?? { base: {}, source: 'none' }
+    )
+  }
+  const ref = parseExtendsRef(entry.extends)
+  const provider = ref.provider ?? profile.extends
+  if (provider === undefined) {
+    throw new ExtendsError(
+      `${where}: extends ${JSON.stringify(entry.extends)} 是裸模型 id，但本 route 未配置 provider 级 extends 查找源`,
+    )
+  }
+  const hit = lookup(kit, modelsDev, provider, ref.model)
+  if (hit === undefined) {
+    throw new ExtendsError(
+      `${where}: extends 引用 "${provider}/${ref.model}" 在内置目录与 models.dev 快照中都不存在`,
+    )
+  }
+  return hit
+}

package/src/profiles.ts

@@ -0,0 +1,340 @@
+/**
+ * profile 构建器：插件 Config → ResolvedPiAiProviderProfile 映射。
+ *
+ * 语义与官方 dsh-llm-pi-ai 的 resolveProfiles 链逐点对齐（index.js:1068-1471），
+ * 差异仅在两点扩展：
+ * - base 来源从"route 同名内置目录"换为 extends 三级数据源（inherit.ts）；
+ * - compat 从 2 字段枚举扩展为逐协议全量字段（compat.ts），写入即校验。
+ *
+ * 产物经 `new PiAiAdapter({ profiles })` 进入官方消息链路；
+ * 任何不可服务的配置在此处抛错（命名 route/model），配合 settings 写入校验，
+ * 非法配置在写入时被拒绝、运行期保留上一份好配置。
+ * @module llm-pi/profiles
+ */
+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 type { ModelsDevSource } from './catalog/models-dev.ts'
+import { mergeCompat, validateCompat } from './compat.ts'
+import {
+  DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+  MAX_TIMER_DELAY_MS,
+  THINKING_LEVELS,
+  type ModelEntryConfig,
+  type ProviderProfileConfig,
+} from './config.ts'
+import { ExtendsError, resolveModelBase } from './inherit.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+/** 内置目录未描述时的零价目（harness 不消费 cost 元数据，同官方 NO_COST）。 */
+const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+
+export interface BuildDeps {
+  kit: DshKit
+  modelsDev?: ModelsDevSource
+  /**
+   * 运行期宽松模式：数据源漂移（models.dev 刷新/内置目录变化）导致已写入的
+   * extends 引用失效时，降级/跳过并告警，而不是抛错把整个 route 弄挂。
+   * 写时校验（assertServiceable）保持严格（缺省），非法引用在写入处拒绝。
+   */
+  lenient?: boolean
+  /** lenient 模式下的告警通道（service 层接 logger）。 */
+  warn?: (message: string) => void
+}
+
+/** 报告不可服务的 route，命名出错配置键（对齐官方 invalid()）。 */
+function invalid(provider: string, detail: string): never {
+  throw new Error(`llm-pi: provider "${provider}" ${detail}`)
+}
+
+/** 条目的声明模态；缺省/空数组都视为"无答案"，交下一级（同官方 declaredInput）。 */
+function declaredInput(configured: readonly ('text' | 'image')[] | undefined): ('text' | 'image')[] | undefined {
+  return configured === undefined || configured.length === 0 ? undefined : [...configured]
+}
+
+/**
+ * 单个模型的 reasoning 物化（逐行对齐官方 resolveModelReasoning）：
+ * 显式 dict → 全档位确定的 thinkingLevelMap（未声明档位置 null）；
+ * false → 非推理模型；缺省 → 保留继承源的 reasoning 能力。
+ */
+function resolveModelReasoning(
+  provider: string,
+  entry: ModelEntryConfig,
+  base: ModelBase,
+): { reasoning: boolean; thinkingLevelMap?: Record<string, string | null> } {
+  const efforts = entry.reasoningEfforts
+  if (efforts === undefined) {
+    if (base.reasoning === undefined) return { reasoning: false }
+    return {
+      reasoning: base.reasoning,
+      ...(base.thinkingLevelMap === undefined
+        ? {}
+        : { thinkingLevelMap: base.thinkingLevelMap as Record<string, string | null> }),
+    }
+  }
+  if (efforts === false) return { reasoning: false }
+  if (Object.keys(efforts).length === 0) {
+    invalid(provider, `model "${entry.id}" 的 reasoningEfforts 为空：声明档位、置 false 或缺省继承`)
+  }
+  for (const level of THINKING_LEVELS) {
+    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 可留空`)
+    } 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)
+  if (!declared.some((level) => level !== 'off')) {
+    invalid(provider, `model "${entry.id}" reasoningEfforts 只有 off；声明思考档位或置 false`)
+  }
+  const map: Record<string, string | null> = {}
+  for (const level of THINKING_LEVELS) {
+    const wire = (efforts as Record<string, string | null | undefined>)[level]
+    if (wire === undefined) map[level] = null
+    else if (wire !== null) map[level] = wire
+  }
+  return { reasoning: true, thinkingLevelMap: map }
+}
+
+/** Harness 自管凭据的 api-key auth（对齐官方 harnessApiKeyAuth，index.js:1215）。 */
+function harnessApiKeyAuth(name: string) {
+  return {
+    name,
+    resolve: ({ credential }: { credential?: { key?: string } }) =>
+      Promise.resolve({ auth: credential?.key === undefined ? {} : { apiKey: credential.key }, source: name }),
+  }
+}
+
+interface MaterializedModel {
+  id: string
+  name: string
+  api: string
+  provider: string
+  baseUrl: string
+  reasoning: boolean
+  thinkingLevelMap?: Record<string, string | null>
+  input: ('text' | 'image')[]
+  cost: typeof NO_COST
+  contextWindow: number
+  maxTokens: number
+  headers?: Record<string, string>
+  compat?: Record<string, unknown>
+}
+
+/** 物化单个模型：继承 base 在下，条目显式字段逐字段覆盖。lenient 下缺 api/baseURL 时跳过（返回 null）。 */
+function materializeModel(
+  route: string,
+  profile: ProviderProfileConfig,
+  entry: ModelEntryConfig,
+  base: ModelBase,
+  routeApi: string | undefined,
+  providerBaseUrl: string | undefined,
+  defaultInput: ('text' | 'image')[],
+  deps: BuildDeps,
+  configuredMaxTokens: Map<string, number>,
+): MaterializedModel | null {
+  const api = profile.api ?? base.api ?? routeApi
+  if (api === undefined) {
+    if (deps.lenient) {
+      deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 无法获得 api（继承源缺失），已跳过该模型`)
+      return null
+    }
+    invalid(route, `model "${entry.id}" 需要 api：继承源未提供，请在 route 上设置 api`)
+  }
+  const baseUrl = profile.baseURL ?? base.baseUrl ?? providerBaseUrl
+  if (baseUrl === undefined) {
+    if (deps.lenient) {
+      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
+  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}"`)
+  const compat = mergeCompat(
+    base.api === api ? base.compat : undefined,
+    profile.compat as Record<string, unknown> | undefined,
+    entry.compat as Record<string, unknown> | undefined,
+  )
+  return {
+    id: entry.id,
+    name: entry.name ?? base.name ?? entry.id,
+    api,
+    provider: route,
+    baseUrl,
+    ...resolveModelReasoning(route, entry, base),
+    input: declaredInput(entry.input) ?? base.input ?? [...defaultInput],
+    cost: base.cost ?? NO_COST,
+    contextWindow,
+    maxTokens,
+    ...(base.headers === undefined ? {} : { headers: { ...base.headers } }),
+    ...(compat === undefined ? {} : { compat }),
+  }
+}
+
+/** 物化一个 route 的全部模型；返回模型列表与显式配置的请求 cap 表。
+ *  lenient 下 route 无任何可服务模型时返回 null（调用方跳过该 route）。 */
+function materializeRouteModels(
+  route: string,
+  profile: ProviderProfileConfig,
+  deps: BuildDeps,
+  defaultInput: ('text' | 'image')[],
+): { models: MaterializedModel[]; configuredMaxTokens: Map<string, number> } | null {
+  const configuredMaxTokens = new Map<string, number>()
+  const providerBaseUrl =
+    profile.extends === undefined ? undefined : builtinProviderBaseUrl(deps.kit, profile.extends)
+  const entries: { id: string; entry?: ModelEntryConfig; base: ModelBase }[] = []
+  if (profile.models !== undefined && profile.models.length > 0) {
+    const seen = new Set<string>()
+    for (const entry of profile.models) {
+      if (entry.id.length === 0) invalid(route, '存在空 id 的模型条目')
+      if (seen.has(entry.id)) invalid(route, `模型 "${entry.id}" 重复列出`)
+      seen.add(entry.id)
+      let base: ModelBase
+      try {
+        base = resolveModelBase(route, profile, entry, deps.kit, deps.modelsDev).base
+      } catch (error) {
+        // 运行期数据源漂移：已写入的引用在当前目录 miss。严格模式（写时校验）保持拒绝；
+        // lenient 模式降级为手写条目并告警，避免整个 route 不可服务。
+        if (!deps.lenient || !(error instanceof ExtendsError)) throw error
+        deps.warn?.(
+          `llm-pi: provider "${route}" model "${entry.id}" 的 extends 引用当前不可解析` +
+            `（${error.message}）；已降级为手写条目`,
+        )
+        base = {}
+      }
+      entries.push({ id: entry.id, entry, base })
+    }
+  } else if (profile.extends !== undefined) {
+    for (const { id, base } of inheritedCatalogEntries(deps.kit, profile.extends)) {
+      entries.push({ id, base })
+    }
+    if (entries.length === 0) {
+      invalid(route, `extends 源 "${profile.extends}" 在内置目录中没有模型；请显式列出 models`)
+    }
+  } else {
+    invalid(route, '未配置 models 且未配置 provider 级 extends；本 route 无模型可服务')
+  }
+  const apis = new Set(
+    entries
+      .map(({ base }) => profile.api ?? base.api)
+      .filter((api): api is string => api !== undefined),
+  )
+  const routeApi = apis.size === 1 ? [...apis][0] : undefined
+  const models = entries
+    .map(({ id, entry, base }) =>
+      materializeModel(
+        route,
+        profile,
+        entry ?? { id },
+        base,
+        routeApi,
+        providerBaseUrl,
+        defaultInput,
+        deps,
+        configuredMaxTokens,
+      ),
+    )
+    .filter((model): model is MaterializedModel => model !== null)
+  if (models.length === 0) {
+    if (deps.lenient) {
+      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 只能服务一种协议`)
+  }
+  return { models, configuredMaxTokens }
+}
+
+/**
+ * 校验并物化全部 route。任一 route 不可服务即整体抛错——
+ * settings 写入校验与运行期 profiles 回调共用本函数，
+ * 保证"写入时被拒"与"运行期不可能拿到坏配置"互为表里。
+ */
+export function buildProfiles(
+  providers: Record<string, ProviderProfileConfig> | undefined,
+  deps: BuildDeps,
+): Map<string, ResolvedPiAiProviderProfile> {
+  const resolved = new Map<string, ResolvedPiAiProviderProfile>()
+  for (const [route, profile] of Object.entries(providers ?? {})) {
+    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 为空')
+    const streamIdleTimeoutMs = profile.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
+    if (
+      !Number.isFinite(streamIdleTimeoutMs) ||
+      streamIdleTimeoutMs <= 0 ||
+      streamIdleTimeoutMs > MAX_TIMER_DELAY_MS
+    ) {
+      invalid(route, `streamIdleTimeoutMs 必须是 (0, ${MAX_TIMER_DELAY_MS}] 内的有限数`)
+    }
+    const defaultInput = [...(profile.defaultInput ?? ['text'])] as ('text' | 'image')[]
+    if (defaultInput.length === 0) invalid(route, 'defaultInput 至少要声明一种模态')
+    const displayName = profile.displayName ?? route
+    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']]
+    if (factory === undefined) {
+      invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`)
+    }
+    const piProvider = deps.kit.createProvider({
+      id: route,
+      name: displayName,
+      ...(profile.baseURL === undefined
+        ? profile.extends === undefined
+          ? {}
+          : { baseUrl: builtinProviderBaseUrl(deps.kit, profile.extends) }
+        : { baseUrl: profile.baseURL }),
+      ...(profile.headers === undefined ? {} : { headers: { ...profile.headers } }),
+      auth: { apiKey: harnessApiKeyAuth(displayName) },
+      models: catalog.models,
+      api: factory() as never,
+    })
+    resolved.set(route, {
+      provider: route,
+      displayName,
+      ...(profile.apiKeyEnv === undefined ? {} : { apiKeyEnv: credentialRef(profile.apiKeyEnv) }),
+      streamIdleTimeoutMs,
+      retryPolicy: deps.kit.resolveRetryPolicy(
+        profile.retryPolicy as Parameters<DshKit['resolveRetryPolicy']>[0],
+        `llm-pi: provider "${route}" retryPolicy`,
+      ),
+      ...(profile.headers === undefined ? {} : { headers: { ...profile.headers } }),
+      ...(profile.reasoning === undefined ? {} : { reasoning: profile.reasoning }),
+      ...(profile.thinkingBudgets === undefined ? {} : { thinkingBudgets: { ...profile.thinkingBudgets } }),
+      ...(profile.cacheRetention === undefined ? {} : { cacheRetention: profile.cacheRetention }),
+      ...(profile.transport === undefined ? {} : { transport: profile.transport }),
+      ...(profile.timeoutMs === undefined ? {} : { timeoutMs: profile.timeoutMs }),
+      ...(profile.websocketConnectTimeoutMs === undefined
+        ? {}
+        : { websocketConnectTimeoutMs: profile.websocketConnectTimeoutMs }),
+      configuredMaxTokens: catalog.configuredMaxTokens,
+      piProvider,
+    } as ResolvedPiAiProviderProfile)
+  }
+  return resolved
+}
+
+/** settings 写入校验钩子：完整试跑解析，非法配置在写入处拒绝。 */
+export function assertServiceable(
+  config: { providers?: Record<string, ProviderProfileConfig> },
+  deps: BuildDeps,
+): void {
+  buildProfiles(config.providers, deps)
+}

package/src/resolve-dsh.ts

@@ -0,0 +1,203 @@
+/**
+ * dsh 运行时套件解析：让插件跑在 dsh 当前安装树的同一份
+ * dsh-llm-pi-ai / dsh-llm / pi-ai 之上，从而 dsh 升级即自动跟随上游。
+ *
+ * 解析策略（全部模块同源地整体成功或整体回退，杜绝跨源混用）：
+ * 1. dsh-tree：从 process.argv[1]（systemd/CLI 启动的 dsh 即 bin.js  shim，
+ *    realpath 后落在 dsh 安装树内）向上找到同时含有
+ *    node_modules/@deepseek-ai/dsh-llm-pi-ai 与 node_modules/@earendil-works/pi-ai
+ *    的目录，按文件路径动态 import——与 dsh 官方插件共享同一模块实例；
+ * 2. vendored：回退到本插件 dependencies 里的固定版本副本（裸 import）。
+ *
+ * 两条路径产物都过形状自检（assertKitShape）：上游 rc 重构导致形状漂移时
+ * 抛错，由调用方决定回退或放弃注册——绝不让坏套件进入消息链路。
+ * @module llm-pi/resolve-dsh
+ */
+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 * as DshLlm from '@deepseek-ai/dsh-llm'
+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 type { ProtocolId } from './config.ts'
+
+/** 插件运行期所需的全部上游模块表面（单一来源，内部一致）。 */
+export interface DshKit {
+  /** 解析来源：dsh 安装树 / 插件 vendored 兜底副本。 */
+  source: 'dsh-tree' | 'vendored'
+  PiAiAdapter: typeof PiAiAdapterType
+  LlmError: typeof DshLlm.LlmError
+  resolveRetryPolicy: typeof DshLlm.resolveRetryPolicy
+  attributionHeaders: typeof DshLlm.attributionHeaders
+  normalizeApiKey: typeof DshLlm.normalizeApiKey
+  assertUsableApiKey: typeof DshLlm.assertUsableApiKey
+  INVALID_CREDENTIAL_CODE: string
+  createProvider: typeof PiAi.createProvider
+  builtinProviders: typeof vendoredCatalog.builtinProviders
+  getBuiltinProviders: typeof vendoredCatalog.getBuiltinProviders
+  getBuiltinModels: typeof vendoredCatalog.getBuiltinModels
+  /** 三协议的 pi-ai api 实现工厂（与官方 PROTOCOLS 表同来源）。 */
+  protocolFactories: Record<ProtocolId, () => unknown>
+}
+
+/** kit 必备形状清单：缺失即视为上游不兼容。 */
+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) {
+      if (typeof (kit.PiAiAdapter.prototype as Record<string, unknown>)[method] !== 'function') {
+        problems.push(`PiAiAdapter.prototype.${method} 缺失`)
+      }
+    }
+  }
+  if (typeof kit.createProvider !== 'function') problems.push('pi-ai createProvider 缺失')
+  if (typeof kit.getBuiltinModels !== 'function') problems.push('pi-ai getBuiltinModels 缺失')
+  if (typeof kit.builtinProviders !== 'function') problems.push('pi-ai builtinProviders 缺失')
+  for (const [api, factory] of Object.entries(kit.protocolFactories)) {
+    if (typeof factory !== 'function') problems.push(`协议工厂 ${api} 缺失`)
+  }
+  if (typeof kit.LlmError !== 'function') problems.push('dsh-llm LlmError 缺失')
+  if (typeof kit.resolveRetryPolicy !== 'function') problems.push('dsh-llm resolveRetryPolicy 缺失')
+  if (problems.length > 0) {
+    throw new Error(`llm-pi: ${origin} 来源的运行时套件形状不兼容：${problems.join('；')}`)
+  }
+}
+
+/** 从 startDir 向上找同时含有 dsh-llm-pi-ai 与 pi-ai 的安装树根。 */
+function findDshTreeRoot(startDir: string): string | undefined {
+  let dir = startDir
+  for (let depth = 0; depth < 8; depth += 1) {
+    const nm = join(dir, 'node_modules')
+    if (
+      existsSync(join(nm, '@deepseek-ai', 'dsh-llm-pi-ai', 'lib', 'index.js')) &&
+      existsSync(join(nm, '@earendil-works', 'pi-ai', 'dist', 'index.js'))
+    ) {
+      return dir
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+  return undefined
+}
+
+interface TreeModules {
+  piAiAdapter: Record<string, unknown>
+  llm: Record<string, unknown>
+  piAi: Record<string, unknown>
+  catalog: Record<string, unknown>
+  completions: Record<string, unknown>
+  responses: Record<string, unknown>
+  anthropic: Record<string, unknown>
+}
+
+/** 从 dsh 安装树按文件路径动态 import 全部套件模块（与官方插件同实例）。 */
+async function importTreeModules(root: string): Promise<TreeModules> {
+  const nm = join(root, 'node_modules')
+  const load = (absPath: string): Promise<Record<string, unknown>> =>
+    import(pathToFileURL(absPath).href) as Promise<Record<string, unknown>>
+  const [piAiAdapter, llm, piAi, catalog, completions, responses, anthropic] = await Promise.all([
+    load(join(nm, '@deepseek-ai', 'dsh-llm-pi-ai', 'lib', 'index.js')),
+    load(join(nm, '@deepseek-ai', 'dsh-llm', 'lib', 'index.js')),
+    load(join(nm, '@earendil-works', 'pi-ai', 'dist', 'index.js')),
+    load(join(nm, '@earendil-works', 'pi-ai', 'dist', 'providers', 'all.js')),
+    load(join(nm, '@earendil-works', 'pi-ai', 'dist', 'api', 'openai-completions.lazy.js')),
+    load(join(nm, '@earendil-works', 'pi-ai', 'dist', 'api', 'openai-responses.lazy.js')),
+    load(join(nm, '@earendil-works', 'pi-ai', 'dist', 'api', 'anthropic-messages.lazy.js')),
+  ])
+  return { piAiAdapter, llm, piAi, catalog, completions, responses, anthropic }
+}
+
+function kitFromTree(mods: TreeModules): DshKit {
+  return {
+    source: 'dsh-tree',
+    PiAiAdapter: mods.piAiAdapter['PiAiAdapter'] as DshKit['PiAiAdapter'],
+    LlmError: mods.llm['LlmError'] as DshKit['LlmError'],
+    resolveRetryPolicy: mods.llm['resolveRetryPolicy'] as DshKit['resolveRetryPolicy'],
+    attributionHeaders: mods.llm['attributionHeaders'] as DshKit['attributionHeaders'],
+    normalizeApiKey: mods.llm['normalizeApiKey'] as DshKit['normalizeApiKey'],
+    assertUsableApiKey: mods.llm['assertUsableApiKey'] as DshKit['assertUsableApiKey'],
+    INVALID_CREDENTIAL_CODE: mods.llm['INVALID_CREDENTIAL_CODE'] as string,
+    createProvider: mods.piAi['createProvider'] as DshKit['createProvider'],
+    builtinProviders: mods.catalog['builtinProviders'] as DshKit['builtinProviders'],
+    getBuiltinProviders: mods.catalog['getBuiltinProviders'] as DshKit['getBuiltinProviders'],
+    getBuiltinModels: mods.catalog['getBuiltinModels'] as DshKit['getBuiltinModels'],
+    protocolFactories: {
+      'openai-completions': mods.completions['openAICompletionsApi'] as () => unknown,
+      'openai-responses': mods.responses['openAIResponsesApi'] as () => unknown,
+      'anthropic-messages': mods.anthropic['anthropicMessagesApi'] as () => unknown,
+    },
+  }
+}
+
+/** vendored 兜底副本套件（导出供单测直接使用，免走 dsh 树解析）。 */
+export function loadVendoredKit(): DshKit {
+  const kit: DshKit = {
+    source: 'vendored',
+    PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
+    LlmError: vendoredLlm.LlmError,
+    resolveRetryPolicy: vendoredLlm.resolveRetryPolicy,
+    attributionHeaders: vendoredLlm.attributionHeaders,
+    normalizeApiKey: vendoredLlm.normalizeApiKey,
+    assertUsableApiKey: vendoredLlm.assertUsableApiKey,
+    INVALID_CREDENTIAL_CODE: vendoredLlm.INVALID_CREDENTIAL_CODE,
+    createProvider: vendoredPiAi.createProvider,
+    builtinProviders: vendoredCatalog.builtinProviders,
+    getBuiltinProviders: vendoredCatalog.getBuiltinProviders,
+    getBuiltinModels: vendoredCatalog.getBuiltinModels,
+    protocolFactories: {
+      'openai-completions': vendoredCompletions,
+      'openai-responses': vendoredResponses,
+      'anthropic-messages': vendoredAnthropic,
+    },
+  }
+  assertKitShape(kit, 'vendored')
+  return kit
+}
+
+/** 定位 dsh 安装树根：realpath(argv[1]) 向上查找；argv 异常时返回 undefined。 */
+function dshTreeAnchor(): string | undefined {
+  const entry = process.argv[1]
+  if (entry === undefined) return undefined
+  try {
+    return findDshTreeRoot(dirname(realpathSync(entry)))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 解析运行时套件：优先 dsh 安装树（自动跟随上游），失败回退 vendored 副本；
+ * 两者都过不了形状自检时抛错（调用方应记日志并放弃注册 route）。
+ * 返回的 diagnostics 记录回退原因，供配置卡片与日志展示。
+ */
+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')
+      return { kit, diagnostics }
+    } catch (error) {
+      diagnostics.push(
+        `dsh 安装树套件不可用（${anchor}）：${error instanceof Error ? error.message : String(error)}；回退 vendored 副本`,
+      )
+    }
+  } else {
+    diagnostics.push('未能从 process.argv[1] 定位 dsh 安装树；回退 vendored 副本')
+  }
+  const kit = loadVendoredKit()
+  return { kit, diagnostics }
+}