@dsh-plus/llm-pi 0.1.44 → 0.2.0

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/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/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/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 }
+}

package/src/official-copy.ts

@@ -0,0 +1,293 @@
+/**
+ * 官方应急副本的翻译与渲染（纯函数，零 IO）。
+ *
+ * 产出一份「官方可识别」的 profile patch 覆盖层：把 dsh-plus-llm-pi 的 route
+ * 配置改写为官方 `llm-pi-ai` 的 Config 形状，另附一行禁用 dsh-plus-llm-pi 的
+ * 覆盖（应用即切换，同名 route 不撞 DUPLICATE_ADAPTER）。写盘、逐 route 官方
+ * 校验与状态管理见 official-copy-writer.ts。
+ *
+ * 三条翻译底线（对旧「出错自动改写」失效教训的根治）：
+ * 1. **只产出官方 schema 声明的字段**：route 键集从官方 Config schema 现场推导
+ *    （失败回退内置键集），模型条目按 kit.officialModelFields 过滤——官方拒收
+ *    的字段根本不出现在副本里；
+ * 2. **compat 只留 offer**：withhold 与未知键按生效门控表丢弃（目录继承值可能
+ *    携带 withhold 键，写时会被官方拒绝）；
+ * 3. **继承全物化**：官方无 extends——模型条目来自 normalizeRoute 的全显式物化
+ *    产物（单协议、单端点约束由该链保证，无需拆分 route）。
+ *
+ * deepseek 路由改写为 openai-completions（中继网关本就是 OpenAI 兼容面）：
+ * 文件通道与思考配置不迁移（官方 llm-pi-ai 无对应字段/无逐模型 reasoningEfforts），
+ * 以 warning 明示，绝不静默丢弃。
+ * @module llm-pi/official-copy
+ */
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+import type { DeepSeekCatalogModel } from '@deepseek-ai/dsh-llm-deepseek'
+import type { PiAiModelProfile, PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
+import { stringify } from 'yaml'
+
+import { compatDispositionOf } from './compat.ts'
+import type { ProviderProfileConfig } from './config.ts'
+import type { SchemaNode } from './official-surface.ts'
+import { isDraftRoute } from './profiles.ts'
+import type { ResolvedDeepseekRoute } from './profiles-deepseek.ts'
+import type { OfficialConfigSchema } from './resolve-dsh.ts'
+
+/** 副本文件在 Harness home（.dsh）根目录的落点；lifeboat 面板按同一路径消费（文件契约）。 */
+export const OFFICIAL_COPY_PATH = dshHomePath('llm-pi.official-patch.yaml')
+
+/** deepseek 路由改写所用线协议：中继网关对外提供 OpenAI 兼容 chat completions 面。 */
+export const DEEPSEEK_COPY_API = 'openai-completions'
+
+/**
+ * 官方 Config schema 布局不可识别时的 route 字段兜底（官方 PiAiProviderProfile
+ * 最后已知键集）。与官方新增字段的失配只表现为「新字段不进副本」，不弄挂生成。
+ */
+export const FALLBACK_ROUTE_FIELDS = [
+  'apiKeyEnv',
+  'displayName',
+  'api',
+  'baseURL',
+  'models',
+  'modelOverrides',
+  'compat',
+  'defaultContextWindow',
+  'defaultMaxTokens',
+  'defaultInput',
+  'headers',
+  'reasoning',
+  'thinkingBudgets',
+  'cacheRetention',
+  'transport',
+  'timeoutMs',
+  'websocketConnectTimeoutMs',
+  'streamIdleTimeoutMs',
+  'maxRequestImageBytes',
+  'requestImagePixelBudget',
+  'requestImageMaxBytes',
+  'retryPolicy',
+] as const
+
+/** deepseek 专有且官方 llm-pi-ai 无对应字段的 raw 键（出现即记 warning）。 */
+const DEEPSEEK_UNMIGRATED_FIELDS = [
+  'thinking',
+  'reasoningEffort',
+  'maxRequestFilesBytes',
+  'filesApiTimeoutMs',
+  'fileExpiresAfterSeconds',
+  'fileRefreshMarginSeconds',
+  'maxImagesPerRequest',
+  'imageOffloadByteQuantum',
+  'inlineImageOffloadByteQuantum',
+  'imageOffloadCountQuantum',
+] as const
+
+/**
+ * 从官方 Config schema 推导 route 字段键集（`providers.*` 的 dict 键）；
+ * 布局不可识别/键集为空返回 undefined，调用方回退内置键集并告警。
+ */
+export function deriveOfficialRouteFields(config: OfficialConfigSchema): string[] | undefined {
+  const fields = (config as unknown as SchemaNode).dict?.['providers']?.inner?.dict
+  if (fields === undefined) return undefined
+  const keys = Object.keys(fields)
+  return keys.length > 0 ? keys : undefined
+}
+
+/** compat 过滤：只保留该协议 offer 的字段（withhold/未知键丢弃）；无保留项返回 undefined。 */
+function offerCompat(
+  api: string,
+  compat: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (compat === undefined || typeof compat !== 'object') return undefined
+  const out: Record<string, unknown> = {}
+  for (const [field, value] of Object.entries(compat)) {
+    if (value === undefined || value === null) continue
+    if (compatDispositionOf(api, field) === 'offer') out[field] = value
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/** 单个模型条目 → 官方键集内的条目（compat 另过 offer 门控）。 */
+function filterModel(
+  api: string,
+  model: PiAiModelProfile,
+  modelFields: readonly string[],
+): Record<string, unknown> {
+  const source = model as unknown as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const key of modelFields) {
+    const value = source[key]
+    if (value === undefined) continue
+    if (key === 'compat') {
+      const compat = offerCompat(api, value as Record<string, unknown>)
+      if (compat !== undefined) out.compat = compat
+      continue
+    }
+    out[key] = value
+  }
+  return out
+}
+
+/** 归一化 profile → 官方 route 字段内的条目（models 逐条过滤）。 */
+function filterRoute(
+  profile: PiAiProviderProfile,
+  routeFields: readonly string[],
+  modelFields: readonly string[],
+): Record<string, unknown> {
+  const source = profile as unknown as Record<string, unknown>
+  const api = typeof source['api'] === 'string' ? source['api'] : ''
+  const out: Record<string, unknown> = {}
+  for (const key of routeFields) {
+    const value = source[key]
+    if (value === undefined) continue
+    if (key === 'models') {
+      const models = Array.isArray(value) ? (value as PiAiModelProfile[]) : []
+      out.models = models.map((model) => filterModel(api, model, modelFields))
+      continue
+    }
+    out[key] = value
+  }
+  return out
+}
+
+/** deepseek 单模型 → 官方条目（inputModalities 改名 input；图像预算不迁移）。 */
+function deepseekModelEntry(model: DeepSeekCatalogModel): Record<string, unknown> {
+  const out: Record<string, unknown> = { id: model.id }
+  if (model.name !== undefined) out.name = model.name
+  if (model.contextWindow !== undefined) out.contextWindow = model.contextWindow
+  if (model.maxTokens !== undefined) out.maxTokens = model.maxTokens
+  if (model.inputModalities !== undefined) out.input = [...model.inputModalities]
+  return out
+}
+
+interface DeepseekCopyResult {
+  profile: Record<string, unknown>
+  /** 未迁移的字段名（出现即入副本头 warning，绝不静默丢弃）。 */
+  unmirrored: string[]
+}
+
+/**
+ * deepseek 路由 → 官方 llm-pi-ai profile：连接事实取 resolveAdapterOptions 的
+ * 校验产物（端点/凭据引用/限额），模型取官方目录物化结果。思考配置与文件通道
+ * 字段不迁移（llm-pi-ai 无对应语义），逐项列入 unmirrored。
+ */
+function deepseekCopyProfile(
+  raw: ProviderProfileConfig,
+  resolved: ResolvedDeepseekRoute,
+): DeepseekCopyResult {
+  const connection = resolved.connection
+  const unmirrored: string[] = DEEPSEEK_UNMIGRATED_FIELDS.filter((key) => raw[key] !== undefined)
+  if (raw.models?.some((m) => m.imagePixelBudget !== undefined || m.imageMaxBytes !== undefined))
+    unmirrored.push('模型级 imagePixelBudget/imageMaxBytes')
+  const profile: Record<string, unknown> = {
+    displayName: resolved.displayName,
+    api: DEEPSEEK_COPY_API,
+    baseURL: connection.baseURL,
+    apiKeyEnv: raw.apiKeyEnv,
+    defaultContextWindow: connection.defaultContextWindow,
+    defaultMaxTokens: connection.maxTokens,
+    streamIdleTimeoutMs: connection.streamIdleTimeoutMs,
+    models: connection.models.map(deepseekModelEntry),
+  }
+  if (raw.retryPolicy !== undefined) profile.retryPolicy = raw.retryPolicy
+  // 语义对应：deepseek 的 base64 降级后载荷上限 ↔ llm-pi-ai 的单请求 base64 上限。
+  if (raw.maxInlineRequestImageBytes !== undefined) {
+    profile.maxRequestImageBytes = connection.maxInlineRequestImageBytes
+  }
+  return { profile, unmirrored }
+}
+
+/** 翻译输入：运行期物化产物 + 原始配置 + 官方生效的手写条目。 */
+export interface OfficialCopyInput {
+  /** 本插件当前原始配置（不受 enabled 影响——副本是配置层事实）。 */
+  providers: Record<string, ProviderProfileConfig>
+  /** normalizeOfficialRoutes 产物：pi route 的官方形状物化结果。 */
+  normalizedPi: ReadonlyMap<string, PiAiProviderProfile>
+  /** buildDeepseekRoutes 产物：deepseek route 的连接事实。 */
+  deepseekResolved: ReadonlyMap<string, ResolvedDeepseekRoute>
+  /** 官方 llm-pi-ai 生效 providers（settings describe 视图，含 profile 手写条目）。 */
+  manualProviders: Record<string, unknown> | undefined
+  /** 官方 route 字段键集（deriveOfficialRouteFields / FALLBACK_ROUTE_FIELDS）。 */
+  routeFields: readonly string[]
+  /** 官方模型条目字段键集（kit.officialModelFields，现场推导）。 */
+  modelFields: readonly string[]
+}
+
+export interface OfficialCopy {
+  /** route 键 → 官方 profile（已过滤；手写条目覆盖同名 key）。空 = 空补丁。 */
+  providers: Record<string, unknown>
+  /** 生成期警告（渲染进副本头注释，也进配置卡诊断）。 */
+  warnings: string[]
+}
+
+/** 翻译整份配置为官方副本内容（纯函数；坏 route 的跳过告警由上游 warn 通道汇集）。 */
+export function buildOfficialCopy(input: OfficialCopyInput): OfficialCopy {
+  const warnings: string[] = []
+  const providers: Record<string, unknown> = {}
+  for (const [route, raw] of Object.entries(input.providers)) {
+    if ((raw.adapter ?? 'pi') === 'deepseek') {
+      const resolved = input.deepseekResolved.get(route)
+      if (resolved === undefined) continue // 物化失败：buildDeepseekRoutes 已告警
+      const { profile, unmirrored } = deepseekCopyProfile(raw, resolved)
+      providers[route] = profile
+      if (unmirrored.length > 0) {
+        warnings.push(
+          `deepseek route "${route}" 的字段未迁移到 llm-pi-ai：${unmirrored.join('、')}`,
+        )
+      }
+      continue
+    }
+    const normalized = input.normalizedPi.get(route)
+    if (normalized === undefined) {
+      // 物化失败的 route 由 normalizeOfficialRoutes 的 warn 通道报告；草稿
+      // （未配置模型的占位）本就不可服务，在此补一条可读说明。
+      if (isDraftRoute(raw)) warnings.push(`草稿 route "${route}" 未纳入副本（尚无模型）`)
+      continue
+    }
+    providers[route] = filterRoute(normalized, input.routeFields, input.modelFields)
+  }
+  // 手写官方条目（describe 的生效视图）同名 key 手写优先：那是用户的显式意图。
+  for (const [route, profile] of Object.entries(input.manualProviders ?? {})) {
+    if (profile !== null && typeof profile === 'object') providers[route] = profile
+  }
+  return { providers, warnings }
+}
+
+/** 渲染元数据（头注释里的应用指引）。 */
+export interface OfficialCopyMeta {
+  /** 来源 profile 名（缺省以占位符渲染应用命令）。 */
+  profile: string | undefined
+}
+
+/** 头注释：用途、两种应用方式、切换语义、回退方法与警告清单（确定性输出，mtime 即生成时间）。 */
+function renderHeader(copy: OfficialCopy, meta: OfficialCopyMeta): string {
+  const profile = meta.profile ?? '<profile>'
+  return [
+    '# 官方应急 LLM 配置副本 —— @dsh-plus/llm-pi 自动生成（勿手改：下次配置变更会被覆盖；文件 mtime 即最近生成时间）',
+    `# 来源 profile：${profile}`,
+    '# 用途：dsh-plus-llm-pi 缺席/故障时，用本文件把其 route 以官方 llm-pi-ai 配置恢复 LLM 能力。',
+    '# 应用（二选一，重启/重载后生效）：',
+    `#   1) 单次启动：dsh ${profile} --patch ${OFFICIAL_COPY_PATH}`,
+    `#   2) 长期生效：把本文件条目并入该 profile 的 cordis.patch.yml（~/.dsh/profiles/${profile}/）`,
+    '# 语义：应用即切换 —— 副本禁用 dsh-plus-llm-pi，并整行替换 llm-pi-ai 的 config',
+    '#       （官方 llm-pi-ai 现有 providers 已合并保留；同名 key 以手写条目优先）。',
+    '# 回退：移除 --patch 参数或删除并入的条目（含 dsh-plus-llm-pi 的 disabled 行），重启/重载。',
+    `# 本次内容：${Object.keys(copy.providers).length} 个官方 provider route。`,
+    ...copy.warnings.map((warning) => `# 警告：${warning}`),
+  ].join('\n')
+}
+
+/**
+ * 渲染副本文件内容（确定性：同输入同字节，mtime 承载时间语义）。
+ * 零 route 时渲染空补丁列表 `[]`（应用无效果）——绝不产出「只禁用不供给」的误导性副本。
+ */
+export function renderOfficialCopy(copy: OfficialCopy, meta: OfficialCopyMeta): string {
+  const header = renderHeader(copy, meta)
+  if (Object.keys(copy.providers).length === 0) {
+    return `${header}\n# 当前没有可迁移的 route（llm-pi 未配置或全部不可服务），空补丁应用无效果。\n[]\n`
+  }
+  const rows = [
+    { id: 'dsh-plus-llm-pi', disabled: true },
+    { id: 'llm-pi-ai', config: { providers: copy.providers } },
+  ]
+  return `${header}\n${stringify(rows, { lineWidth: 0 })}`
+}

package/src/profiles.ts

@@ -710,6 +710,38 @@ export function buildProfiles(
   return resolved
 }
 
+/**
+ * 应急副本用：逐 route 归一化为官方 schema 形状的 profile（与运行期同一条
+ * normalizeRoute 链：extends 物化、单协议单端点约束、模型条目全显式）。
+ *
+ * 与运行期 buildProfiles 的两点差异：
+ * - 不受 `enabled` 开关影响——副本是配置层事实，插件关闭时其 route 仍应可复制；
+ * - 逐 route 隔离失败（不依赖 lenient 开关）——一个坏条目只丢它自己，
+ *   不让整份应急副本变空。
+ *
+ * adapter: deepseek 的 route 与草稿路由不在此列（前者由 profiles-deepseek
+ * 物化、后者本就不可服务），调用方按缺席另行告警。
+ */
+export function normalizeOfficialRoutes(
+  providers: Record<string, ProviderProfileConfig> | undefined,
+  deps: BuildDeps,
+): Map<string, PiAiProviderProfile> {
+  const out = new Map<string, PiAiProviderProfile>()
+  for (const [route, profile] of Object.entries(providers ?? {})) {
+    try {
+      const normalized = normalizeRoute(route, profile, deps)
+      if (normalized !== undefined) out.set(route, normalized.profile)
+    } catch (error) {
+      deps.warn?.(
+        `llm-pi: provider "${route}" 无法物化为官方形状（${
+          error instanceof Error ? error.message : String(error)
+        }），已跳过应急副本的该 route`,
+      )
+    }
+  }
+  return out
+}
+
 /** settings 写入校验钩子：完整试跑解析，非法配置在写入处拒绝。 */
 export function assertServiceable(
   config: { providers?: Record<string, ProviderProfileConfig> },

package/src/resolve-dsh.ts

@@ -93,6 +93,13 @@ export type ResolveProfiles = (
   providers: Readonly<Record<string, PiAiProviderProfile>> | undefined,
 ) => Map<string, ResolvedPiAiProviderProfile>
 
+/**
+ * 官方 Config schema 的调用面（根导出 `Config`，schemastery schema 的可调用形态）：
+ * 应急副本写前校验「官方是否接受这个形状」——非法协议/取值越界在此抛错。
+ * 只用其抛错语义，解析产物（volatile 视图）不消费。
+ */
+export type OfficialConfigSchema = (value: unknown) => unknown
+
 /** PiAiAdapter 必需 auth 注入的两个助手（官方 auth.ts 面；包根未导出）。 */
 export interface AuthHelpers {
   credentialStoreFrom(ctx: Context): CredentialStore
@@ -117,6 +124,11 @@ export interface DshKit {
   /** 内置目录数据生成时间（毫秒）；官方未导出该信息时省略。 */
   catalogGeneratedAt?: number
   PiAiAdapter: typeof PiAiAdapterType
+  /**
+   * 官方 `Config` schema（与 PiAiAdapter 同一模块根导出，同源取用）：
+   * 应急副本落盘前的官方可识别性校验（见 {@link OfficialConfigSchema}）。
+   */
+  officialConfig: OfficialConfigSchema
   LlmError: typeof DshLlm.LlmError
   resolveRetryPolicy: typeof DshLlm.resolveRetryPolicy
   attributionHeaders: typeof DshLlm.attributionHeaders
@@ -173,6 +185,7 @@ function assertKitShape(kit: DshKit, origin: string): void {
     }
   }
   if (typeof kit.createProvider !== 'function') problems.push('pi-ai createProvider 缺失')
+  if (typeof kit.officialConfig !== 'function') problems.push('dsh-llm-pi-ai Config schema 缺失')
   if (typeof kit.getBuiltinModels !== 'function') problems.push('pi-ai getBuiltinModels 缺失')
   if (typeof kit.builtinProviders !== 'function') problems.push('pi-ai builtinProviders 缺失')
   if (kit.protocols.length === 0) problems.push('没有可服务的线协议（协议工厂全部加载失败）')
@@ -529,6 +542,7 @@ function kitFromTree(options: {
       ? {}
       : { catalogGeneratedAt: surface.catalogGeneratedAt }),
     PiAiAdapter: mods.piAiAdapter['PiAiAdapter'] as DshKit['PiAiAdapter'],
+    officialConfig: mods.piAiAdapter['Config'] as DshKit['officialConfig'],
     LlmError: mods.llm['LlmError'] as DshKit['LlmError'],
     resolveRetryPolicy: mods.llm['resolveRetryPolicy'] as DshKit['resolveRetryPolicy'],
     attributionHeaders: mods.llm['attributionHeaders'] as DshKit['attributionHeaders'],
@@ -626,6 +640,7 @@ export function loadVendoredKit(diagnostics: string[] = []): DshKit {
       ? {}
       : { catalogGeneratedAt: surface.catalogGeneratedAt }),
     PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
+    officialConfig: vendoredPiAiAdapter.Config as DshKit['officialConfig'],
     LlmError: vendoredLlm.LlmError,
     resolveRetryPolicy: vendoredLlm.resolveRetryPolicy,
     attributionHeaders: vendoredLlm.attributionHeaders,