@dsh-plus/llm-pi 0.1.45 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/llm-pi",
-  "version": "0.1.45",
+  "version": "0.2.1",
   "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、pi-ai 内置目录；协议/compat/字段集现场推导，自动跟随已装 dsh）",
   "type": "module",
   "main": "lib/index.js",
@@ -31,7 +31,8 @@
     }
   },
   "dependencies": {
-    "@dsh-plus/shared": "0.1.35"
+    "yaml": "^2.9.0",
+    "@dsh-plus/shared": "0.1.36"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5-alpha.1",

package/src/client/api.ts

@@ -18,6 +18,14 @@ export interface WireKitInfo {
   protocolSource: string
   catalog: { providers: number; models: number; generatedAt?: number }
   compatSource: string
+  /** 官方应急副本状态（服务端 official-copy-writer 的 OfficialCopyStatus 镜像）。 */
+  officialCopy: {
+    path: string
+    updatedAt?: number
+    routes: number
+    warnings: string[]
+    error?: string
+  }
   diagnostics: string[]
 }
 

package/src/client/client.ts

@@ -7,8 +7,8 @@
  *
  * 类型说明：浏览器半只用到 slots/locale/remote 的很窄一面，
  * scope 与基础控件走 @dsh-plus/shared/client 套件（收编自本插件原实现）。
- * 配置读写经 ctx.remote.settings 直连（0.1.2-alpha.1 起 connection.api.settings
- * 已移除；0.1.7 起 settingsScope 服务亦删除（configForms 取代）——插件卡片自始
+ * 配置读写经 ctx.remote.settings 直连（connection.api.settings
+ * 已移除； settingsScope 服务亦删除（configForms 取代）——插件卡片自始
  * 直连 remote.settings，见 @dsh-plus/shared/client scope.ts）；自定义端点只剩
  * `/catalog`（api.ts：运行期套件事实 + pi-ai 内置目录搜索，浏览器半读不到 pi-ai 包）。
  * 卡片 key/rowId 约定见 @dsh-plus/shared/client/config-slots。

package/src/client/i18n.ts

@@ -23,6 +23,10 @@ const ownZh = {
   runtimeCatalog: '内置模型目录',
   runtimeProtocols: '可服务协议',
   runtimeCompat: 'compat 门控表',
+  runtimeOfficialCopy: '应急副本',
+  officialCopyPending: '尚未生成',
+  officialCopyFailed: '生成失败：',
+  officialCopyRoutes: '个 route',
   runtimeDiagnostics: '诊断',
   runtimeVersionUnknown: '未知',
   runtimeCatalogUnit: '个 provider /',
@@ -160,6 +164,10 @@ const ownEn = {
   runtimeCatalog: 'Built-in catalog',
   runtimeProtocols: 'Servable protocols',
   runtimeCompat: 'compat gates',
+  runtimeOfficialCopy: 'Emergency copy',
+  officialCopyPending: 'not generated yet',
+  officialCopyFailed: 'generation failed: ',
+  officialCopyRoutes: 'routes',
   runtimeDiagnostics: 'Diagnostics',
   runtimeVersionUnknown: 'unknown',
   runtimeCatalogUnit: 'providers /',

package/src/client/root-fields.tsx

@@ -36,6 +36,14 @@ function sourceLabel(t: Translate, source: string): string {
   return source === 'official' ? t('runtimeDerived') : t('runtimeFallback')
 }
 
+/** 应急副本状态行：路径 · route 数 · 生成时间；未生成/失败显式提示。 */
+function officialCopyText(kit: WireKitInfo, t: Translate): string {
+  const copy = kit.officialCopy
+  if (copy.error !== undefined) return `${t('officialCopyFailed')}${copy.error}`
+  if (copy.updatedAt === undefined) return t('officialCopyPending')
+  return `${copy.path} · ${copy.routes} ${t('officialCopyRoutes')} · ${formatTime(copy.updatedAt, t('runtimeVersionUnknown'))}`
+}
+
 export interface RootFieldsProps {
   t: Translate
   draft: Draft
@@ -80,6 +88,9 @@ export function RootFields(props: RootFieldsProps): ReactElement {
           <p className="lpc-statusRow">
             {`${t('runtimeCompat')}：${sourceLabel(t, kit.compatSource)}`}
           </p>
+          <p className="lpc-statusRow">
+            {`${t('runtimeOfficialCopy')}：${officialCopyText(kit, t)}`}
+          </p>
           {kit.versionNotice !== undefined ? (
             <p className="lpc-invalid">{`${t('runtimeNotice')}：${kit.versionNotice}`}</p>
           ) : null}

package/src/compat.ts

@@ -10,7 +10,7 @@
  *   assertOfferedCompatFields："写了但没生效"的表面状态不允许）。
  * - **fallback（推导失败，用最后已知快照）**：只拒绝快照中明确 withhold 的键，
  *   **未知键放行**交给官方适配器自身校验——表落后时"误拒官方新字段"比"多放一个键"
- *   严重得多（0.1.5-rc.1 教训：静默功能缺失、无任何报错）。
+ *   严重得多（教训：静默功能缺失、无任何报错）。
  *
  * pi-ai 侧消费语义：getCompat 逐字段 `??` 覆盖 detectCompat 的 baseURL/名称猜测；
  * undefined 视为未设置（无法显式清空检测值）。
@@ -122,7 +122,7 @@ function checkValue(field: string, spec: CompatValue, value: unknown, where: str
 
 /**
  * 校验一份 compat 字典对指定协议合法（对齐官方门控语义 + schema 值约束）：
- * - 未知键/withhold 字段拒绝（官方写时拒绝，替代旧版静默丢弃）；
+ * - 未知键/withhold 字段拒绝（与官方写时拒绝同款）；
  * - 值类型/枚举按官方 schema 校验；
  * - 无值键（null/undefined）拒绝（官方 assertOfferedCompatFields 同款）。
  */

package/src/config-api.ts

@@ -1,6 +1,6 @@
 /**
  * 自定义端点 HTTP 通道：配置读写走官方 remote.settings 直连
- * （0.1.2-alpha.1 起第三方命名空间全量开放），这里只提供浏览器半拿不到的两样东西：
+ * （第三方命名空间全量开放），这里只提供浏览器半拿不到的两样东西：
  * - 运行期套件事实（生效版本、协议集合、目录规模、逐项降级诊断）；
  * - pi-ai 内置目录的搜索/筛选/分页（浏览器半读不到 pi-ai 包）。
  *

package/src/config.ts

@@ -1,6 +1,6 @@
 /**
  * 配置单一事实源：cordis 行级 Config（组合默认值）与 settings namespace
- *（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）共用同一
+ *（用户层＝profile 行级覆盖层 cordis.patch.yml，热生效）共用同一
  * schemastery schema。无密钥字段（apiKeyEnv 是凭据引用名而非密钥本身）。
  *
  * 与官方 llm-pi-ai 的差异：
@@ -17,11 +17,11 @@ import type { VolatileFields } from '@dsh-plus/shared'
 
 import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
 
-/** settings 命名空间（字面量即合法命名空间，0.1.2-alpha.2 起编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
+/** settings 命名空间（字面量即合法命名空间，编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
 export const SETTINGS_NS = NS_LITERAL
 
 /**
- * 官方适配器不可用/推导失败时的协议兜底三元组（自 0.1.2-alpha 线以来的稳定集）。
+ * 官方适配器不可用/推导失败时的协议兜底三元组。
  * 运行期生效集合来自已安装官方包的 `supportedProtocols()`（见 resolve-dsh.ts），
  * 本常量只用于 schema 描述、浏览器半首帧兜底与推导失败回退。
  */
@@ -45,9 +45,6 @@ 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
-/** 旧版 imageDetail 枚举（0.1.2-alpha.1 已移除该字段；仅用于 schema 透传陷阱的取值集）。 */
-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
@@ -201,12 +198,6 @@ const modelEntry = z.object({
     .step(1)
     .min(1)
     .description('（仅 adapter: deepseek）单张请求图片的编码字节上限；缺省继承官方目录'),
-  // 0.1.2-alpha.1 移除字段的 schema 透传陷阱：官方已删除 imageDetail（改用
-  // imagePixelBudget/imageMaxBytes），此处保留取值 union 让旧配置通过 schema、
-  // 在写时校验（assertServiceable）以中文迁移提示明确拒绝（见 profiles-deepseek.ts）。
-  imageDetail: z
-    .union(DEEPSEEK_IMAGE_DETAILS)
-    .description('（已移除）图片细节档位；0.1.2-alpha.1 起请改用 imagePixelBudget/imageMaxBytes'),
 })
 
 const providerProfile = z.object({
@@ -254,9 +245,7 @@ const providerProfile = z.object({
     .description('单支流式读取的最大空闲间隔毫秒'),
   maxRequestImageBytes: z
     .natural()
-    .description(
-      '单请求 base64 图片载荷上限字节；缺省 20MiB（0.1.2-alpha.1 起官方必需字段，旧配置免改）',
-    ),
+    .description('单请求 base64 图片载荷上限字节；缺省 20MiB（官方必需字段，旧配置免改）'),
   requestImagePixelBudget: z
     .number()
     .step(1)
@@ -333,10 +322,10 @@ const providerProfile = z.object({
     .description('本 route 的模型目录；缺省且 provider 有 extends 时继承该源全部模型'),
 })
 
-// 0.1.7：根字段全 `.volatile()`——条目进入 settings describe 视图（卡片可读写），
+// 根字段全 `.volatile()`——条目进入 settings describe 视图（卡片可读写），
 // loader 原位提交活动引用；输出面标注活动字段声明面（结构兼容 volatile 引用），
 // 平面消费契约保持 LlmPiConfig 接口不变（服务侧经 unwrapVolatile 解包现取）。
-/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+/** 活动字段形态（loader 解析产物：volatile 字段为活动引用）。 */
 export type LlmPiConfigFields = VolatileFields<LlmPiConfig>
 
 export const Config: z<LlmPiConfigInput, LlmPiConfigFields> = z.object({

package/src/deepseek-routes.ts

@@ -11,7 +11,7 @@
  * 请求生效）；retryPolicy 是注册期捕获事实，变化时 handle.replace 原地重注册
  * （官方同款模式）；route 移除即 dispose 释放路由名。
  *
- * 0.1.2-alpha 线：DeepSeekAdapterOptions 必需 prepareExtensions（官方接线
+ * DeepSeekAdapterOptions 必需 prepareExtensions（官方接线
  * ctx.get('deepseekLlmApiExtensions')，缺省空实现）与可选 resolveImageAccess。
  * @module llm-pi/deepseek-routes
  */
@@ -158,7 +158,7 @@ export class DeepseekRouteRegistrar {
             )?.processPathFromHostPath(hostPath),
           ref,
         ) as never,
-      // 0.1.2-alpha 线必需：官方扩展注册表（deepseekLlmApiExtensions）缺席时
+      // 必需项：官方扩展注册表（deepseekLlmApiExtensions）缺席时
       // 给空实现（官方接线范式，llm-deepseek/src/index.ts:404-470）。
       prepareExtensions: (request) => {
         const extensions = ctx.get('deepseekLlmApiExtensions') as

package/src/index.ts

@@ -11,7 +11,10 @@
  *
  * 接线约束：inject 须含 credentials（auth-inline/deepseek-routes 经
  * ctx.get('credentials') 读 seam；凭据解析为请求时惰性调用，硬声明保证
- * 时序，消除启动早窗口的一次性 MISSING_CREDENTIAL）。
+ * 时序，消除启动早窗口的一次性 MISSING_CREDENTIAL）与 settings
+ * （应急副本手写条目来源：readManualProviders 经 ctx.settings.describe
+ * 读官方 llm-pi-ai 生效视图；漏声明即启动期 "cannot get property without
+ * inject" → 插件树加载失败）。
  * @module @dsh-plus/llm-pi
  */
 import type { Context } from '@deepseek-ai/cordis'
@@ -22,7 +25,7 @@ import { startRuntime } from './service.ts'
 
 export const name = 'dsh-plus-llm-pi'
 
-export const inject = ['credentials', 'llm'] as const
+export const inject = ['credentials', 'llm', 'settings'] as const
 
 export type {
   LlmPiConfig,

package/src/inherit.ts

@@ -3,7 +3,7 @@
  *
  * 数据源只有一个：**pi-ai 内置目录**（随已装 dsh 的 pi-ai 版本自动跟随，
  * 含官方校正的 compat/thinkingLevelMap/模态）。未命中即「手写条目」，
- * 必填字段由 route 级配置或兜底给出。models.dev 兜底源已随 0.1.43 移除——
+ * 必填字段由 route 级配置或兜底给出。models.dev 兜底源已移除——
  * 版本漂移靠「现场推导 + 状态行显示生效版本」处理，不引入第二份可能过期的目录。
  *
  * 引用语法：`"provider/model"` 显式引用；裸 `"model"` 随 route 级 extends 源；

package/src/ns.ts

@@ -1,6 +1,6 @@
 /**
  * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
- * 服务端直接以字面量注册（0.1.2-alpha.2 起 dsh-settings 对命名空间做编译期
+ * 服务端直接以字面量注册（dsh-settings 对命名空间做编译期
  * 语法校验，见 config.ts）；浏览器半把它作为配置卡片的注册键
  * （插件页配置卡片挂在 row/bundle config 槽位上，与命名空间解耦，
  * 见 shared/config-slots），

package/src/official-copy-writer.ts

@@ -0,0 +1,207 @@
+/**
+ * 官方应急副本的生成编排：装配（原始配置 → 物化 → 翻译）→ 逐 route 官方校验
+ * → 备忘跳过 / 原子落盘 → 状态供配置卡与 lifeboat 面板消费。
+ *
+ * 触发时机：插件启动、配置热更新（loader/volatile-update）、adapter 注册变化
+ * （llm/adapters-updated，官方 llm-pi-ai 晚注册时手写条目在此补入）。无定时器、
+ * 无 watcher——平时零开销；写失败只降级为状态与日志，绝不影响路由注册。
+ *
+ * 逐 route 官方校验是「副本必然官方可识别」的执行点：官方 Config schema 解析
+ * （非法协议/越界取值在此抛错）+ 官方 resolveProfiles 可服务性链；任一不过即
+ * 剔除该 route 并记 warning——写不进官方的东西绝不落盘。
+ * @module llm-pi/official-copy-writer
+ */
+import { stat } from 'node:fs/promises'
+import type { PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
+import { atomicWriteFile, isVolatileRef } from '@dsh-plus/shared'
+
+import type { LlmPiConfig } from './config.ts'
+import {
+  buildOfficialCopy,
+  deriveOfficialRouteFields,
+  FALLBACK_ROUTE_FIELDS,
+  OFFICIAL_COPY_PATH,
+  type OfficialCopy,
+  renderOfficialCopy,
+} from './official-copy.ts'
+import { normalizeOfficialRoutes } from './profiles.ts'
+import { buildDeepseekRoutes } from './profiles-deepseek.ts'
+import type { DshKit } from './resolve-dsh.ts'
+
+/** 官方 llm-pi-ai 的 settings 命名空间（与插件 NS 同字面量，官方 0.1.x 起稳定）。 */
+const NS_OFFICIAL_PI_AI = 'llm-pi-ai'
+
+/** 副本状态（配置卡状态行与诊断的 JSON 面；updatedAt 缺省 = 尚未生成）。 */
+export interface OfficialCopyStatus {
+  path: string
+  updatedAt?: number
+  routes: number
+  warnings: string[]
+  error?: string
+}
+
+/** 手写官方条目读取结果：providers 缺省 + warning 说明降级原因。 */
+export interface ManualSourceResult {
+  providers?: Record<string, unknown>
+  warning?: string
+}
+
+/** settings 服务窄面（describe 的描述符子集；测试可注入固定值）。 */
+export interface SettingsDescribeLike {
+  describe(): Array<{ ns: string; value?: unknown }>
+}
+
+/**
+ * 手写官方条目来源：settings describe 的 llm-pi-ai 生效视图（composition base
+ * = profile patch 行 + settings 用户层，schema 已解析、已过官方 validate）——
+ * 官方 seam，无需自行解析 patch 文件。ns 未注册/读取失败时降级为「仅本插件
+ * 改写条目」并附 warning，不阻断生成。
+ */
+export function readManualProviders(settings: SettingsDescribeLike): ManualSourceResult {
+  try {
+    const row = settings.describe().find((entry) => entry.ns === NS_OFFICIAL_PI_AI)
+    if (row === undefined) {
+      return { warning: '官方 llm-pi-ai 未注册（插件缺席），副本仅含本插件改写条目' }
+    }
+    const raw = (row.value as { providers?: unknown } | undefined)?.providers
+    const providers = isVolatileRef(raw) ? raw.get() : raw
+    if (providers === null || typeof providers !== 'object') return {}
+    return { providers: providers as Record<string, unknown> }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { warning: `读取官方 llm-pi-ai 生效配置失败（${message}），副本仅含本插件改写条目` }
+  }
+}
+
+export interface OfficialCopyWriterDeps {
+  kit: DshKit
+  /** 当前生效的本插件配置（volatile 已解包的平面快照）。 */
+  current: () => LlmPiConfig
+  /** 手写官方条目读取（生产接 readManualProviders(ctx.settings)）。 */
+  readManual: () => ManualSourceResult
+  /** 来源 profile 名（头注释应用指引用）。 */
+  profile: string | undefined
+  /** 落盘路径（缺省 .dsh 根的 OFFICIAL_COPY_PATH；测试注入临时路径）。 */
+  path?: string
+  logger: { warn(message: unknown): void }
+}
+
+export interface OfficialCopyWriter {
+  /** 生成（或确认最新）副本：串行化执行，失败降级为状态，绝不抛出。 */
+  ensureOfficialCopy(): Promise<void>
+  /** 最近一次生成的状态。 */
+  status(): OfficialCopyStatus
+}
+
+/** 文件是否已存在（内容备忘跳过后自愈外部删除）。 */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** 组装 + 翻译：返回含全部 warning 的副本内容（尚未官方校验）。 */
+function assemble(deps: OfficialCopyWriterDeps, warnings: string[]): OfficialCopy {
+  const routeFields = deriveOfficialRouteFields(deps.kit.officialConfig)
+  if (routeFields === undefined) {
+    warnings.push('官方 Config schema 布局不可识别，route 字段回退内置键集')
+  }
+  const providers = deps.current().providers ?? {}
+  const normalizedPi = normalizeOfficialRoutes(providers, {
+    kit: deps.kit,
+    lenient: true,
+    warn: (message) => warnings.push(message),
+  })
+  const deepseekResolved = buildDeepseekRoutes(providers, {
+    kit: deps.kit,
+    lenient: true,
+    warn: (message) => warnings.push(message),
+  })
+  const manual = deps.readManual()
+  if (manual.warning !== undefined) warnings.push(manual.warning)
+  const copy = buildOfficialCopy({
+    providers,
+    normalizedPi,
+    deepseekResolved,
+    manualProviders: manual.providers,
+    routeFields: routeFields ?? [...FALLBACK_ROUTE_FIELDS],
+    modelFields: deps.kit.officialModelFields,
+  })
+  warnings.push(...copy.warnings)
+  return { providers: copy.providers, warnings }
+}
+
+/** 逐 route 官方校验：schema 解析 + 可服务性链；不过即剔除并记 warning。 */
+function acceptOfficial(
+  deps: OfficialCopyWriterDeps,
+  copy: OfficialCopy,
+  warnings: string[],
+): Record<string, unknown> {
+  const accepted: Record<string, unknown> = {}
+  for (const [route, profile] of Object.entries(copy.providers)) {
+    try {
+      deps.kit.officialConfig({ providers: { [route]: profile } })
+      deps.kit.resolveProfiles({ [route]: profile as PiAiProviderProfile })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      warnings.push(`route "${route}" 未通过官方校验，已从副本剔除：${message}`)
+      continue
+    }
+    accepted[route] = profile
+  }
+  return accepted
+}
+
+/** 生成态：内容备忘（跳过同内容重写）与最近生成时间（mtime 语义）。 */
+interface CopyState {
+  lastContent?: string
+  updatedAt?: number
+}
+
+/** 落盘：内容未变且文件仍在则跳过（并自愈外部删除）；返回最近生成时间。 */
+async function persist(path: string, content: string, state: CopyState): Promise<number> {
+  if (content === state.lastContent && (await fileExists(path)))
+    return state.updatedAt ?? Date.now()
+  await atomicWriteFile(path, content)
+  state.lastContent = content
+  state.updatedAt = Date.now()
+  return state.updatedAt
+}
+
+/** 生成一次副本（错误上抛，由调用方降级为 status.error）。 */
+async function runOnce(
+  deps: OfficialCopyWriterDeps,
+  path: string,
+  state: CopyState,
+): Promise<OfficialCopyStatus> {
+  const warnings: string[] = []
+  const assembled = assemble(deps, warnings)
+  const providers = acceptOfficial(deps, assembled, warnings)
+  const content = renderOfficialCopy({ providers, warnings }, { profile: deps.profile })
+  const updatedAt = await persist(path, content, state)
+  return { path, updatedAt, routes: Object.keys(providers).length, warnings }
+}
+
+/** 装配写入器：启动/热更新/adapter 事件驱动，串行执行（promise 链）。 */
+export function createOfficialCopyWriter(deps: OfficialCopyWriterDeps): OfficialCopyWriter {
+  const path = deps.path ?? OFFICIAL_COPY_PATH
+  const state: CopyState = {}
+  let status: OfficialCopyStatus = { path, routes: 0, warnings: [] }
+  let chain: Promise<void> = Promise.resolve()
+  const ensureOfficialCopy = (): Promise<void> => {
+    chain = chain.then(async () => {
+      try {
+        status = await runOnce(deps, path, state)
+      } catch (error) {
+        // 落盘/装配失败：磁盘上仍是上一次成功的副本，保留其状态并标注错误。
+        const message = error instanceof Error ? error.message : String(error)
+        deps.logger.warn(`llm-pi: 应急副本生成失败：${message}`)
+        status = { ...status, error: message }
+      }
+    })
+    return chain
+  }
+  return { ensureOfficialCopy, status: () => status }
+}