@dsh-plus/llm-pi 0.1.45 → 0.2.1

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/official-surface.ts

@@ -10,7 +10,7 @@
  * 3. **模型条目字段集**：Config schema 的 `providers.*.models` 键集——继承时按此
  *    透传 pi-ai 目录的同名字段，官方将来新增模型级字段即自动跟随。
  *
- * 历史教训（0.1.5-rc.1）：compat 门控曾是官方 catalog.ts 的手抄镜像，官方扩容
+ * 历史教训（详见 docs/repo/事故记录.md）：compat 门控曾是官方的手抄镜像，官方扩容
  * offer 字段而旧表漏收，导致官方可配字段被本插件**误拒**（静默功能缺失、无报错）。
  * 现改为现场推导，`tests/official-surface.test.ts` 直读官方副本守门推导正确性。
  *
@@ -205,10 +205,20 @@ export function fallbackProtocols(): string[] {
   return [...FALLBACK_PROTOCOLS]
 }
 
-/** 官方门控表不可解析时的最后已知快照（0.1.5-rc.2 实测值）。 */
+/**
+ * 官方门控表不可解析时的兜底快照（0.2.1-alpha.1 现场推导值）。
+ *
+ * 只在官方改打包形态、`COMPAT_GATES` 解析失败时启用（此时未知键放行、只拦快照里
+ * 明确 withhold 的键，见 compat.ts 的「语义分两档」）。快照过期会重新引入
+ * 「误拒官方新字段」那类静默故障，故由 tests/official-surface.test.ts 的
+ * 「兜底快照不得过期」用例与现场推导逐协议比对守门。
+ */
 export const FALLBACK_TABLE: CompatTable = {
   source: 'fallback',
   gates: {
+    'mistral-conversations': {
+      supportsMidConvoSystemMessages: 'withhold',
+    },
     'openai-completions': {
       supportsStore: 'offer',
       supportsDeveloperRole: 'offer',
@@ -234,7 +244,8 @@ export const FALLBACK_TABLE: CompatTable = {
       zaiToolStream: 'withhold',
       supportsOpenAIGrammarTools: 'withhold',
       sendSessionAffinityHeaders: 'withhold',
-      deferredToolsMode: 'withhold',
+      supportsMidConvoSystemMessages: 'withhold',
+      supportsMidConvoToolAdditions: 'withhold',
       sessionAffinityFormat: 'withhold',
     },
     'openai-responses': {
@@ -247,6 +258,31 @@ export const FALLBACK_TABLE: CompatTable = {
       supportsAdditionalTools: 'withhold',
       supportsToolSearch: 'withhold',
       supportsExplicitPromptCacheMode: 'withhold',
+      supportsMidConvoSystemMessages: 'withhold',
+    },
+    'azure-openai-responses': {
+      supportsDeveloperRole: 'offer',
+      supportsMaxOutputTokens: 'offer',
+      supportsStrictMode: 'offer',
+      supportsLongCacheRetention: 'offer',
+      sessionAffinityFormat: 'withhold',
+      supportsOpenAIGrammarTools: 'withhold',
+      supportsAdditionalTools: 'withhold',
+      supportsToolSearch: 'withhold',
+      supportsExplicitPromptCacheMode: 'withhold',
+      supportsMidConvoSystemMessages: 'withhold',
+    },
+    'openai-codex-responses': {
+      supportsDeveloperRole: 'offer',
+      supportsMaxOutputTokens: 'offer',
+      supportsStrictMode: 'offer',
+      supportsLongCacheRetention: 'offer',
+      sessionAffinityFormat: 'withhold',
+      supportsOpenAIGrammarTools: 'withhold',
+      supportsAdditionalTools: 'withhold',
+      supportsToolSearch: 'withhold',
+      supportsExplicitPromptCacheMode: 'withhold',
+      supportsMidConvoSystemMessages: 'withhold',
     },
     'anthropic-messages': {
       supportsEagerToolInputStreaming: 'offer',
@@ -257,10 +293,15 @@ export const FALLBACK_TABLE: CompatTable = {
       allowEmptySignature: 'offer',
       supportsStrictTools: 'offer',
       sendSessionAffinityHeaders: 'withhold',
-      supportsToolReferences: 'withhold',
+      sessionAffinityFormat: 'withhold',
+      supportsMidConvoSystemMessages: 'withhold',
+      supportsMidConvoToolChanges: 'withhold',
       supportsMidConvoEffort: 'withhold',
       allowedFallbackModels: 'withhold',
     },
+    'bedrock-converse-stream': {
+      supportsStrictMode: 'offer',
+    },
   },
   specs: {
     supportsStore: 'boolean',

package/src/profiles-deepseek.ts

@@ -130,16 +130,6 @@ function materializeModel(
   if (entry.reasoningEfforts !== undefined || nonEmptyDict(entry.compat)) {
     invalid(route, `model "${entry.id}" 的 reasoningEfforts/compat 仅 adapter: pi 可用`)
   }
-  const legacyImageDetail = (entry as ModelEntryConfig & { imageDetail?: unknown }).imageDetail
-  if (legacyImageDetail !== undefined) {
-    // 0.1.2-alpha.1 移除字段：写时明确拒绝并给出迁移提示（官方 llm-deepseek
-    // 对含 imageDetail 的目录模型同样直接抛错，index.ts:212-215）。
-    invalid(
-      route,
-      `model "${entry.id}" 的 imageDetail 已随 0.1.2-alpha.1 移除；` +
-        '请改用 imagePixelBudget/imageMaxBytes（低细节可配更小的 imagePixelBudget）并删除 imageDetail',
-    )
-  }
   const base = resolveOfficialBase(route, entry, deps)
   const input = declaredModalities(entry.input) ?? base.input
   const imageFields = {
@@ -233,7 +223,7 @@ function buildRoute(
     if (deps.kit.deepseek === undefined) {
       invalid(
         route,
-        '使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（0.1.2-alpha.1 基线）',
+        '使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（本仓基线的必需套件）',
       )
     }
     rejectPiOnlyFields(route, profile)

package/src/profiles.ts

@@ -1,5 +1,5 @@
 /**
- * profile 构建器（0.1.2-alpha.2 复核兼容）：插件 Config → 官方 schema 形状的
+ * profile 构建器：插件 Config → 官方 schema 形状的
  * 「前置数据源归一化」→ 官方 resolveProfiles（或插件等价兜底）→
  * ResolvedPiAiProviderProfile。
  *
@@ -190,14 +190,6 @@ function materializeModel(
   defaultInput: ('text' | 'image')[],
   deps: BuildDeps,
 ): MaterializedEntry | null {
-  const legacyImageDetail = (entry as ModelEntryConfig & { imageDetail?: unknown }).imageDetail
-  if (legacyImageDetail !== undefined) {
-    invalid(
-      route,
-      `model "${entry.id}" 的 imageDetail 已随 0.1.2-alpha.1 移除；` +
-        '请改用 imagePixelBudget/imageMaxBytes（仅 adapter: deepseek）并删除 imageDetail',
-    )
-  }
   const api = profile.api ?? base.api ?? routeApi
   if (api === undefined) {
     if (deps.lenient) {
@@ -606,7 +598,7 @@ export function resolveProfilesFallback(
     // 模型物化：全显式条目 + route 级 api/baseURL（官方 resolveRouteModels 镜像，
     // 无目录继承——归一化已把继承值落定在条目里）
     const configuredMaxTokens = new Map<string, number>()
-    // 官方 0.1.5-alpha.2（llm-pi-ai）adapter 读取 profile.modelErrors/catalogError：
+    // 官方 llm-pi-ai adapter 读取 profile.modelErrors/catalogError：
     // 本 fallback 对条目严格校验、坏条目整体拒绝（不产生"条目级不可服务"的
     // deferred 诊断），故补空表保持与官方 profile 形状一致——缺失会让
     // PiAiAdapter.modelOf 读 modelErrors.get 时以 TypeError 打崩。
@@ -710,6 +702,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

@@ -19,7 +19,7 @@
  * 模型条目字段集同样现场推导（official-surface.ts）。生效版本只用于状态行显示，
  * 超出已验证区间也只是提示（kit-meta.ts），永不阻断。
  *
- * 0.1.2-alpha 线的新面（0.1.2-alpha.2 复核包根仍未导出、仅 src 子路径有）：
+ * 仅 src 子路径导出、包根不导出的两块面：
  * - resolveProfiles（config.ts）：官方解析链，dev 布局树可经 src 子路径复用；
  * - credentialStoreFrom/authContextFrom（auth.ts）：PiAiAdapter 必需 auth 注入。
  * npm 发布形态（lib/index.js 单 bundle + 无 src/）两者都拿不到：dsh 树优先
@@ -76,7 +76,7 @@ import { type ResolverDeps, resolveProfilesFallback } from './profiles.ts'
 
 /**
  * deepseek 适配器模块表面（可选）：dsh-llm-deepseek 的官方 DeepSeekAdapter
- * 与目录解析器 + 匿名用户 id。缺失（旧版 dsh 树或形状漂移）不拖垮核心
+ * 与目录解析器 + 匿名用户 id。缺失（形状漂移）不拖垮核心
  * 套件——deepseek 类 route 在构建期以明确错误拒绝，pi 路由不受影响。
  * 与核心套件强制同源（杜绝跨源模块混用：brand/LlmError 恒等性敏感）。
  */
@@ -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
@@ -149,8 +161,8 @@ function assertKitShape(kit: DshKit, origin: string): void {
   const problems: string[] = []
   if (typeof kit.PiAiAdapter !== 'function') problems.push('PiAiAdapter 不是类')
   else {
-    // 0.1.2-alpha.2 的 LlmAdapter 抽象面：prepareCall/providerRetryPolicy 为
-    // master 适配器必需 override；models.getModels/getModel 语义未变
+    // LlmAdapter 抽象面：prepareCall/providerRetryPolicy 为适配器必需 override；
+    // models.getModels/getModel 语义
     // （pi-ai 0.84.2 Models.getModel(provider,id)/getModels(provider)，
     // 由同源 adapter 内部消费，本插件不直调）。
     for (const method of [
@@ -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,

package/src/service.ts

@@ -1,8 +1,8 @@
 /**
  * 运行时主逻辑：注册/热更新/发现（逐点对齐官方 dsh-llm-pi-ai apply 的模式）。
  *
- * - profiles 回调按原始 config 对象 identity 备忘；配置变更经 0.1.7
- *   volatile 原位提交（loader/volatile-update 换代快照）传播，下一请求生效
+ * - profiles 回调按原始 config 对象 identity 备忘；配置变更经 volatile 原位提交
+ *   （loader/volatile-update 换代快照）传播，下一请求生效
  *   （adapter 快照按 profiles identity 失效）；
  * - route 集或注册时捕获的事实（displayName/retryPolicy）变化 → 原子的
  *   handle.replace 重注册；写入被校验拒绝时保留旧注册（官方同款护栏）；
@@ -40,6 +40,11 @@ import { DeepseekRouteRegistrar } from './deepseek-routes.ts'
 import { buildDirectoryEntries, commitDirectory, type DirectoryEntry } from './directory.ts'
 import { discoverModels } from './discovery.ts'
 import { type KitVersions, piAiVersionNotice, VERIFIED_PI_AI_RANGE } from './kit-meta.ts'
+import {
+  createOfficialCopyWriter,
+  type OfficialCopyStatus,
+  readManualProviders,
+} from './official-copy-writer.ts'
 import { assertServiceable, buildProfiles, isDraftRoute } from './profiles.ts'
 import { buildDeepseekRoutes, type ResolvedDeepseekRoute } from './profiles-deepseek.ts'
 import { type DshKit, resolveDshKit } from './resolve-dsh.ts'
@@ -64,6 +69,8 @@ export interface LlmPiKitInfo {
   catalog: { providers: number; models: number; generatedAt?: number }
   /** compat 门控表来源：official / fallback。 */
   compatSource: string
+  /** 官方应急副本状态（路径/生成时间/覆盖 route/警告；error = 最近生成失败）。 */
+  officialCopy: OfficialCopyStatus
   /** 回退与逐项降级诊断（有内容时界面显式展示）。 */
   diagnostics: string[]
 }
@@ -194,8 +201,8 @@ function createAdapter(options: {
     profiles,
     resolveApiKey: makeResolveApiKey(ctx, kit),
     resolveAttachments: () => ctx.get('attachments'),
-    // 0.1.2-alpha.2 必需（包根仍未导出官方 auth 助手）：登录/OAuth 类 provider 与
-    // pi-ai 自有凭据写入的落点。dsh 树 dev 布局（src/auth.ts 存在）时为官方助手，
+    // 官方 auth 助手只在 src 子路径导出：登录/OAuth 类 provider 与 pi-ai 自有
+    // 凭据写入的落点。dsh 树 dev 布局（src/auth.ts 存在）时为官方助手，
     // 其余形态为内联等价实现（resolve-dsh.ts 探测，见 auth-inline.ts）。
     auth: {
       credentials: kit.auth.credentialStoreFrom(ctx),
@@ -365,7 +372,7 @@ export async function startRuntime(
 ): Promise<LlmPiRuntime> {
   const logger = ctx.logger('llm-pi')
   // cordis 行级 config 可能未经 schema 解析（insert 行无 config 键时为原始空对象），
-  // 在此统一规范化；0.1.7 loader 解析出的 volatile 活动字段形态直接透传
+  // 在此统一规范化；loader 解析出的 volatile 活动字段形态直接透传
   // （hasVolatileRefs 辨识——重复校验会把引用再包一层、破坏 loader 原位提交）。
   const fields: LlmPiConfigFields = hasVolatileRefs(rawConfig)
     ? (rawConfig as LlmPiConfigFields)
@@ -412,11 +419,22 @@ export async function startRuntime(
   })
   const ensureDeepseek = (): void => deepseekRegistrar.sync(deepseekRoutes())
 
+  // 官方应急副本：启动即生成一次；热更新与 adapter 注册变化（官方 llm-pi-ai
+  // 晚注册时手写条目在此补入）再生成。写失败只降级为状态，不影响路由注册。
+  const copyWriter = createOfficialCopyWriter({
+    kit,
+    current,
+    readManual: () => readManualProviders(ctx.settings),
+    profile: ctx.get('profileContext')?.name,
+    logger,
+  })
+
   ensureRegistration()
   ensureDeepseek()
   ensureDirectory()
+  void copyWriter.ensureOfficialCopy()
 
-  // 0.1.7 替代 installSection（validate/setSource/onChange 三钩子）：
+  // 替代 installSection（validate/setSource/onChange 三钩子）：
   // - 活动引用原位提交 → volatile-update 触发快照换代与重注册（原 onChange 体）；
   // - internal/config waterfall 承接写入校验（原 validate；官方 llm-pi-ai
   //   同款）：configEditor.edit 落盘前先跑 waterfall，handler throw 即拒绝整笔写入。
@@ -425,8 +443,12 @@ export async function startRuntime(
     attempt(logger, 'llm-pi: 更新被拒，保留此前注册的 route', ensureRegistration)
     attempt(logger, 'llm-pi: deepseek route 更新失败，保留此前注册', ensureDeepseek)
     attempt(logger, 'llm-pi: 更新被拒，保留此前的 configurable-provider 目录', ensureDirectory)
+    void copyWriter.ensureOfficialCopy()
   }
   ctx.events.on('loader/volatile-update', reconfigure)
+  // 官方 llm-pi-ai 晚于本插件注册时，describe 的手写条目视图此时才完整——
+  // adapter 集变化即重新生成副本（无 provider 变化时内容未变、跳过写盘）。
+  ctx.root.on('llm/adapters-updated', () => void copyWriter.ensureOfficialCopy())
   ctx.on('internal/config', function (_raw: unknown, next: () => unknown) {
     const candidate = next()
     if (this !== ctx.fiber) return candidate
@@ -439,6 +461,7 @@ export async function startRuntime(
     const providers = listProviders(kit)
     const generatedAt = kit.catalogGeneratedAt
     const notice = piAiVersionNotice(kit.versions.piAi)
+    const copy = copyWriter.status()
     return {
       source: kit.source,
       ...(kit.root === undefined ? {} : { root: kit.root }),
@@ -453,7 +476,12 @@ export async function startRuntime(
         ...(generatedAt === undefined ? {} : { generatedAt }),
       },
       compatSource: compatTableInfo().source,
-      diagnostics,
+      officialCopy: copy,
+      diagnostics: [
+        ...diagnostics,
+        ...copy.warnings.map((warning) => `应急副本：${warning}`),
+        ...(copy.error === undefined ? [] : [`应急副本：生成失败（${copy.error}）`]),
+      ],
     }
   }