@dsh-plus/llm-pi 0.1.42 → 0.1.44

package/src/kit-meta.ts

@@ -0,0 +1,156 @@
+/**
+ * 运行期套件元信息：插件实际在用哪一份 pi-ai / 官方适配器，以及版本是否落在
+ * 本插件验证过的区间内。
+ *
+ * 存在的理由：插件**按文件路径**动态加载已装 dsh 树里的 pi-ai（版本随 dsh 升级
+ * 自动变化，见 resolve-dsh.ts），因此"当前生效版本"不是 manifest 上写的版本。
+ * 配置页把它显示出来，版本漂移一眼可见；`VERIFIED_PI_AI_RANGE` 只用于**提示**，
+ * 永不阻断——能不能用由运行期形状自检（assertKitShape）与逐项降级决定。
+ * @module llm-pi/kit-meta
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 实际生效的三个版本；拿不到即省略（读文件失败不视为错误）。 */
+export interface KitVersions {
+  /** pi-ai（目录与协议实现的来源）。 */
+  piAi?: string
+  /** 官方 dsh-llm-pi-ai（PiAiAdapter 与 compat 门控的来源）。 */
+  piAiAdapter?: string
+  /** dsh 本体（安装树根 package.json，仅在根就是 dsh 包时可得）。 */
+  dsh?: string
+}
+
+/** 本插件开发/测试覆盖过的 pi-ai 区间（semver range，仅用于状态行提示）。 */
+export const VERIFIED_PI_AI_RANGE = '>=0.85.1 <0.88.0'
+
+/** 读 package.json 的 version；文件不存在/非 JSON/无 version 都返回 undefined。 */
+export function readPackageVersion(manifestPath: string): string | undefined {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    const version = (parsed as { version?: unknown } | null)?.version
+    return typeof version === 'string' && version.length > 0 ? version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** 读包目录的版本（`<dir>/package.json`）。 */
+export function packageVersionOf(packageDir: string): string | undefined {
+  return readPackageVersion(join(packageDir, 'package.json'))
+}
+
+/** 只读包名（判断安装树根是不是 dsh 本体）。 */
+function readPackageName(manifestPath: string): string | undefined {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    const name = (parsed as { name?: unknown } | null)?.name
+    return typeof name === 'string' ? name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** 收集 dsh 安装树内实际加载的那几个包的版本。 */
+export function collectTreeVersions(root: string): KitVersions {
+  const nm = join(root, 'node_modules')
+  const piAi = packageVersionOf(join(nm, '@earendil-works', 'pi-ai'))
+  const adapter = packageVersionOf(join(nm, '@deepseek-ai', 'dsh-llm-pi-ai'))
+  // 树根 package.json 是 dsh 本体时才算 dsh 版本（源码仓库布局下根可能是别的包）。
+  const rootManifest = join(root, 'package.json')
+  const dsh =
+    readPackageName(rootManifest) === '@deepseek-ai/dsh' ? packageVersionOf(root) : undefined
+  return {
+    ...(piAi === undefined ? {} : { piAi }),
+    ...(adapter === undefined ? {} : { piAiAdapter: adapter }),
+    ...(dsh === undefined ? {} : { dsh }),
+  }
+}
+
+/**
+ * 由模块入口文件向上找包目录（最多 3 层，兼容 `<pkg>/{lib,dist}/index.js`
+ * 与根目录入口两种布局）；找不到返回 undefined。
+ */
+function packageDirOf(entryFile: string): string | undefined {
+  let dir = dirname(entryFile)
+  for (let depth = 0; depth < 3; depth += 1) {
+    if (readPackageName(join(dir, 'package.json')) !== undefined) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+  return undefined
+}
+
+/**
+ * 解析已安装包的目录（本进程内解析，只用于读 package.json）。
+ * 拿不到即返回 undefined（该版本号留空，不影响运行）。
+ */
+export function installedPackageDir(specifier: string): string | undefined {
+  try {
+    return packageDirOf(fileURLToPath(import.meta.resolve(specifier)))
+  } catch {
+    return undefined
+  }
+}
+
+/** 收集插件 vendored 兜底副本的版本（回退路径下"生效版本"即这两份）。 */
+export function collectVendoredVersions(): KitVersions {
+  const piAiDir = installedPackageDir('@earendil-works/pi-ai')
+  const adapterDir = installedPackageDir('@deepseek-ai/dsh-llm-pi-ai')
+  const piAi = piAiDir === undefined ? undefined : packageVersionOf(piAiDir)
+  const adapter = adapterDir === undefined ? undefined : packageVersionOf(adapterDir)
+  return {
+    ...(piAi === undefined ? {} : { piAi }),
+    ...(adapter === undefined ? {} : { piAiAdapter: adapter }),
+  }
+}
+
+/** 已验证区间的解析端点（与 {@link VERIFIED_PI_AI_RANGE} 同步维护）。 */
+const VERIFIED_MIN: readonly [number, number, number] = [0, 85, 1]
+const VERIFIED_MAX_EXCLUSIVE: readonly [number, number, number] = [0, 88, 0]
+
+/** 解析 `x.y.z[-pre][+build]` 的数值三元组；形状不符返回 undefined。 */
+function numericTriple(version: string): [number, number, number] | undefined {
+  const core = version.split(/[-+]/, 1)[0] ?? ''
+  const parts = core.split('.')
+  if (parts.length !== 3) return undefined
+  const nums = parts.map((part) => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : Number.NaN))
+  const [a, b, c] = nums
+  if (a === undefined || b === undefined || c === undefined) return undefined
+  if (!Number.isInteger(a) || !Number.isInteger(b) || !Number.isInteger(c)) return undefined
+  return [a, b, c]
+}
+
+function compareTriple(
+  left: readonly [number, number, number],
+  right: readonly [number, number, number],
+): number {
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] as number) - (right[i] as number)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/**
+ * 生效 pi-ai 版本不在已验证区间时的提示文案（**提示而非阻断**）。
+ * 区间内或版本号形状无法解析时返回 undefined。
+ */
+export function piAiVersionNotice(version: string | undefined): string | undefined {
+  if (version === undefined) return undefined
+  const parsed = numericTriple(version)
+  if (parsed === undefined) return undefined
+  if (compareTriple(parsed, VERIFIED_MIN) < 0) {
+    return `当前生效 pi-ai ${version} 低于本插件验证过的下限 ${VERIFIED_PI_AI_RANGE}`
+  }
+  if (compareTriple(parsed, VERIFIED_MAX_EXCLUSIVE) >= 0) {
+    return (
+      `当前生效 pi-ai ${version} 超出本插件验证过的区间 ${VERIFIED_PI_AI_RANGE}；` +
+      '已启用现场推导与形状自检，若出现异常请先看诊断行'
+    )
+  }
+  return undefined
+}

package/src/{compat-gates.ts → official-surface.ts}

@@ -1,24 +1,25 @@
 /**
- * compat 门控表的**自动继承**：从官方 `dsh-llm-pi-ai` 安装副本现场推导，
- * 取代早期的手抄镜像表（手抄遗漏即静默误拒官方可配字段，见 ADR/文档的
- * 0.1.5-rc.1 教训）。
+ * 官方适配面的**自动继承**：从已安装的官方副本（`dsh-llm-pi-ai` + `pi-ai`）
+ * 现场推导三样东西，取代早期的手抄镜像：
  *
- * 官方不导出该表（包根仅 7 个符号、`src/` 不随 npm 发布），但有两条稳定可用的
- * 机器可读来源，本模块同时消费：
+ * 1. **线协议集合**：官方包根导出的 `supportedProtocols()`（官方 PROTOCOLS 表
+ *    的唯一投影）。官方新增协议时本插件自动可用，不再需要改代码；
+ * 2. **compat 门控与取值约束**：门控取自运行期 bundle 的 `COMPAT_GATES`
+ *    （事实源：运行期拒绝哪些字段由它决定），取值约束取自导出的 Config schema
+ *    的 `providers.*.compat` 节点（boolean / number.step(1) / enum / 对象）；
+ * 3. **模型条目字段集**：Config schema 的 `providers.*.models` 键集——继承时按此
+ *    透传 pi-ai 目录的同名字段，官方将来新增模型级字段即自动跟随。
  *
- * 1. **运行期 bundle**（`lib/index.js`，即真正执行门控的那份代码）：
- *    `const COMPAT_GATES = { "openai-completions": COMPLETIONS_COMPAT_GATE, ... }`
- *    ——给出「协议 → 门控」映射（anthropic 在 bundle 内联，解析器同时支持
- *    命名常量与内联对象两种形态）。门控表取自这里而非 d.ts，因为它是**事实源**：
- *    运行期拒绝哪些字段由它决定。
- * 2. **导出的 Config schema**（schemastery 标准 schema）：`providers.*.compat`
- *    节点逐字段给出取值约束（boolean/number.step(1)/enum/对象），据此推导
- *    取值校验，不再手写 VALUE_SPECS。
+ * 历史教训（0.1.5-rc.1）：compat 门控曾是官方 catalog.ts 的手抄镜像，官方扩容
+ * offer 字段而旧表漏收，导致官方可配字段被本插件**误拒**（静默功能缺失、无报错）。
+ * 现改为现场推导，`tests/official-surface.test.ts` 直读官方副本守门推导正确性。
  *
- * 推导失败（官方改布局/改打包形态）时回退到 FALLBACK_TABLE（最后已知快照，
- * 随本文件版本冻结）并给出诊断——绝不因推导失败弄挂插件启动。
- * @module llm-pi/compat-gates
+ * 推导失败（官方改布局/改打包形态）时回退到 FALLBACK_*：compat 表用最后已知快照
+ * 且**放宽未知键**（见 compat.ts：宁可放行交给官方自身校验，也不误拒官方新字段），
+ * 协议回退三元组、模型字段回退已知七键，各自给出诊断——绝不因推导失败弄挂启动。
+ * @module llm-pi/official-surface
  */
+import { FALLBACK_PROTOCOLS } from './config.ts'
 
 /** 字段可配性：offer = 官方允许写；withhold = 官方为厂商内置、写时拒绝。 */
 export type CompatDisposition = 'offer' | 'withhold'
@@ -161,6 +162,49 @@ export function deriveSpecs(module: Record<string, unknown>): Record<string, Com
   return out
 }
 
+/**
+ * 从官方适配器模块推导线协议集合：官方包根导出的 `supportedProtocols()`
+ * （`Object.keys(PROTOCOLS)` 的投影，顺序即官方表顺序）。
+ * 非函数/返回空/含非字符串项都视为推导失败，调用方回退内置三元组。
+ */
+export function deriveProtocols(module: Record<string, unknown>): string[] | undefined {
+  const reader = module['supportedProtocols']
+  if (typeof reader !== 'function') return undefined
+  const value = (reader as () => unknown)()
+  if (!Array.isArray(value) || value.length === 0) return undefined
+  const ids = value.filter((id): id is string => typeof id === 'string' && id.length > 0)
+  return ids.length === value.length ? ids : undefined
+}
+
+/**
+ * 从官方 Config schema 推导模型条目字段集（`providers.*.models` 的元素键集）。
+ * 这些是官方适配器**接受**的模型级键；继承时按此透传 pi-ai 目录的同名字段。
+ */
+export function deriveModelEntryFields(module: Record<string, unknown>): string[] | undefined {
+  const config = module['Config'] as SchemaNode | undefined
+  const models = config?.dict?.['providers']?.inner?.dict?.['models']
+  const fields = models?.inner?.dict
+  if (fields === undefined) return undefined
+  const keys = Object.keys(fields)
+  return keys.length > 0 ? keys : undefined
+}
+
+/** 推导失败时的模型条目字段兜底（0.2.x 线实测键集）。 */
+export const FALLBACK_MODEL_ENTRY_FIELDS = [
+  'id',
+  'name',
+  'contextWindow',
+  'maxTokens',
+  'input',
+  'reasoningEfforts',
+  'compat',
+] as const
+
+/** 协议推导失败时的兜底三元组（转出为可变数组，便于调用方直接持有）。 */
+export function fallbackProtocols(): string[] {
+  return [...FALLBACK_PROTOCOLS]
+}
+
 /** 官方门控表不可解析时的最后已知快照（0.1.5-rc.2 实测值）。 */
 export const FALLBACK_TABLE: CompatTable = {
   source: 'fallback',

package/src/profiles.ts

@@ -35,10 +35,10 @@ import type {
 
 import {
   builtinProviderBaseUrl,
+  hasBuiltinProvider,
   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,
@@ -61,9 +61,8 @@ const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
 
 export interface BuildDeps {
   kit: DshKit
-  modelsDev?: ModelsDevSource
   /**
-   * 运行期宽松模式：数据源漂移（models.dev 刷新/内置目录变化）导致已写入的
+   * 运行期宽松模式：数据源漂移（dsh 树升级换 pi-ai 版本导致内置目录变化）使已写入的
    * extends 引用失效时，降级/跳过并告警，而不是抛错把整个 route 弄挂。
    * 写时校验（assertServiceable）保持严格（缺省），非法引用在写入处拒绝。
    */
@@ -84,6 +83,29 @@ function declaredInput(
   return configured === undefined || configured.length === 0 ? undefined : [...configured]
 }
 
+/**
+ * 归一化条目里"本层不处理、需原样进 pi-ai Model"的字段（继承自目录的未来
+ * 模型级字段，如 samplingParams）。官方 schema 当前的模型条目键（id/name/
+ * contextWindow/maxTokens/input/reasoningEfforts/compat）在此全部排除：
+ * 它们要么由本层显式翻译，要么不能出现在 pi-ai Model 上。
+ */
+function extraEntryFields(entry: PiAiModelProfile): Record<string, unknown> {
+  const known = new Set([
+    'id',
+    'name',
+    'contextWindow',
+    'maxTokens',
+    'input',
+    'reasoningEfforts',
+    'compat',
+  ])
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(entry)) {
+    if (!known.has(key) && value !== undefined) out[key] = value
+  }
+  return out
+}
+
 /** 显式 reasoningEfforts 字典的合法性校验（官方 resolveModelReasoning 同款规则）。 */
 function validateReasoningEfforts(
   provider: string,
@@ -223,6 +245,9 @@ function materializeModel(
   // 用户手写层（上面两次 validateCompat）。
   return {
     entry: {
+      // 继承源的其余官方可继承字段先落定（官方 schema 接受的键集运行期推导），
+      // 表单显式字段随后覆盖：官方将来新增模型级字段即自动跟随，无需改本插件。
+      ...(base.extra ?? {}),
       id: entry.id,
       ...(name === entry.id ? {} : { name }),
       ...(contextWindow === DEFAULT_CONTEXT_WINDOW ? {} : { contextWindow }),
@@ -230,7 +255,7 @@ function materializeModel(
       ...(input.length === 1 && input[0] === 'text' ? {} : { input }),
       reasoningEfforts: reasoningEffortsFromBase(route, entry, base),
       ...(compat === undefined ? {} : { compat }),
-    },
+    } as PiAiModelProfile,
     api,
     baseUrl,
   }
@@ -261,7 +286,7 @@ function materializeRouteModels(
       seen.add(entry.id)
       let base: ModelBase
       try {
-        base = resolveModelBase(route, profile, entry, deps.kit, deps.modelsDev).base
+        base = resolveModelBase(route, profile, entry, deps.kit).base
       } catch (error) {
         // 运行期数据源漂移：已写入的引用在当前目录 miss。严格模式（写时校验）保持拒绝；
         // lenient 模式降级为手写条目并告警，避免整个 route 不可服务。
@@ -366,6 +391,20 @@ function normalizeRoute(
   // 注意：不做"route 名与内置 provider 名重名"的静态校验——内置名 ≠ 已注册
   // route（如官方 llm-pi-ai 配置清空后 anthropic 名可用）。真实冲突只在注册期
   // 暴露（DUPLICATE_ADAPTER），由 service 层逐个 route 注册降级处理。
+  if (profile.extends !== undefined && !hasBuiltinProvider(deps.kit, profile.extends)) {
+    // 继承源只有 pi-ai 内置目录（models.dev 兜底已移除）：写错 provider 名过去会
+    // 静默退化成手写条目，现在写入即拒绝并给出可用集合，避免"配了没生效"。
+    if (!deps.lenient) {
+      invalid(
+        route,
+        `extends ${JSON.stringify(profile.extends)} 不是 pi-ai ${deps.kit.versions.piAi ?? '?'} 的内置 provider；` +
+          `可用：${deps.kit.getBuiltinProviders().join(', ')}`,
+      )
+    }
+    deps.warn?.(
+      `llm-pi: provider "${route}" 的 extends ${JSON.stringify(profile.extends)} 不是当前 pi-ai 的内置 provider，已忽略该继承源`,
+    )
+  }
   if (profile.baseURL !== undefined && profile.baseURL.length === 0) invalid(route, 'baseURL 为空')
   if (profile.displayName !== undefined && profile.displayName.length === 0)
     invalid(route, 'displayName 为空')
@@ -395,11 +434,11 @@ function normalizeRoute(
   const materialized = materializeRouteModels(route, profile, deps, defaultInput)
   if (materialized === null) return undefined // lenient 下 route 无模型可服务，跳过注册
   const { api, baseUrl, models, configuredMaxTokens } = materialized
-  const factory = deps.kit.protocolFactories[api as keyof DshKit['protocolFactories']]
+  const factory = deps.kit.protocolFactories[api]
   if (factory === undefined) {
     invalid(
       route,
-      `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`,
+      `api ${JSON.stringify(api)} 本插件无法服务（当前生效 pi-ai ${deps.kit.versions.piAi ?? '?'} 支持的协议：${deps.kit.protocols.join('/')}）`,
     )
   }
   const displayName = profile.displayName ?? route
@@ -462,6 +501,8 @@ function harnessApiKeyAuth(name: string) {
 export interface ResolverDeps {
   createProvider: DshKit['createProvider']
   protocolFactories: DshKit['protocolFactories']
+  /** 当前生效协议集合（写时错误消息用；与 protocolFactories 的键同源）。 */
+  protocols: string[]
   resolveRetryPolicy: DshKit['resolveRetryPolicy']
 }
 
@@ -550,16 +591,13 @@ export function resolveProfilesFallback(
     const displayName = source.displayName ?? provider
     const api = source.api
     if (api === undefined) {
-      invalid(
-        provider,
-        '需要 api：本插件仅支持 openai-completions/openai-responses/anthropic-messages',
-      )
+      invalid(provider, `需要 api：本插件只服务官方适配器声明的协议（${deps.protocols.join('/')}）`)
     }
-    const factory = deps.protocolFactories[api as keyof DshKit['protocolFactories']]
+    const factory = deps.protocolFactories[api]
     if (factory === undefined) {
       invalid(
         provider,
-        `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`,
+        `api ${JSON.stringify(api)} 本插件无法服务（当前支持的协议：${deps.protocols.join('/')}）`,
       )
     }
     if (source.baseURL === undefined) {
@@ -589,6 +627,7 @@ export function resolveProfilesFallback(
       }
       if (entry.maxTokens !== undefined) configuredMaxTokens.set(entry.id, entry.maxTokens)
       return {
+        ...extraEntryFields(entry),
         id: entry.id,
         name: entry.name ?? entry.id,
         api,