@dsh-plus/llm-pi 0.1.45 → 0.2.1

package/lib/index.js

@@ -1,10 +1,13 @@
 import z from "@deepseek-ai/schemastery";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { deepEqualJson } from "@deepseek-ai/dsh-util-values";
-import { hasVolatileRefs, unwrapVolatile } from "@dsh-plus/shared";
+import { atomicWriteFile, hasVolatileRefs, isVolatileRef, unwrapVolatile } from "@dsh-plus/shared";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { access, stat } from "node:fs/promises";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import { stringify } from "yaml";
 import { credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
 import * as vendoredAnonId from "@deepseek-ai/dsh-anonymous-user-id";
 import * as vendoredLlm from "@deepseek-ai/dsh-llm";
@@ -16,13 +19,12 @@ import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messag
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
 import * as vendoredCatalog from "@earendil-works/pi-ai/providers/all";
-import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 //#endregion
 //#region src/config.ts
 /**
 * 配置单一事实源：cordis 行级 Config（组合默认值）与 settings namespace
-*（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）共用同一
+*（用户层＝profile 行级覆盖层 cordis.patch.yml，热生效）共用同一
 * schemastery schema。无密钥字段（apiKeyEnv 是凭据引用名而非密钥本身）。
 *
 * 与官方 llm-pi-ai 的差异：
@@ -33,10 +35,10 @@ import { homedir } from "node:os";
 *   官方将来新增协议无需改本插件。
 * @module llm-pi/config
 */
-/** settings 命名空间（字面量即合法命名空间，0.1.2-alpha.2 起编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
+/** settings 命名空间（字面量即合法命名空间，编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
 const SETTINGS_NS = "dsh-plus-llm-pi";
 /**
-* 官方适配器不可用/推导失败时的协议兜底三元组（自 0.1.2-alpha 线以来的稳定集）。
+* 官方适配器不可用/推导失败时的协议兜底三元组。
 * 运行期生效集合来自已安装官方包的 `supportedProtocols()`（见 resolve-dsh.ts），
 * 本常量只用于 schema 描述、浏览器半首帧兜底与推导失败回退。
 */
@@ -66,8 +68,6 @@ const DEEPSEEK_REASONING_EFFORTS = [
 	"high",
 	"max"
 ];
-/** 旧版 imageDetail 枚举（0.1.2-alpha.1 已移除该字段；仅用于 schema 透传陷阱的取值集）。 */
-const DEEPSEEK_IMAGE_DETAILS = ["auto", "low"];
 /** dsh-timeout 的定时器上限（与官方 MAX_TIMER_DELAY_MS 对齐）。 */
 const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 /**
@@ -101,8 +101,7 @@ const modelEntry = z.object({
 	reasoningEfforts: z.union([z.const(false), reasoningEfforts]).description("可选 reasoning 档位：false=非推理模型；dict=档位→线值映射；缺省继承内置目录能力"),
 	compat: compatDict.description("模型级 compat（字段级合并，压过 route 级与继承值）"),
 	imagePixelBudget: z.number().step(1).min(1).description("（仅 adapter: deepseek）单张请求图片的总像素预算；缺省继承官方目录"),
-	imageMaxBytes: z.number().step(1).min(1).description("（仅 adapter: deepseek）单张请求图片的编码字节上限；缺省继承官方目录"),
-	imageDetail: z.union(DEEPSEEK_IMAGE_DETAILS).description("（已移除）图片细节档位；0.1.2-alpha.1 起请改用 imagePixelBudget/imageMaxBytes")
+	imageMaxBytes: z.number().step(1).min(1).description("（仅 adapter: deepseek）单张请求图片的编码字节上限；缺省继承官方目录")
 });
 const providerProfile = z.object({
 	adapter: z.union(ADAPTER_KINDS).description("路由适配器：pi=PiAiAdapter（默认，协议集合随已装官方适配器推导）；deepseek=官方 DeepSeekAdapter（图片走 Files API 文件通道，失败自动降级 base64）").default("pi"),
@@ -132,7 +131,7 @@ const providerProfile = z.object({
 	timeoutMs: z.natural().description("HTTP/provider 超时毫秒"),
 	websocketConnectTimeoutMs: z.natural().description("WebSocket 连接超时毫秒"),
 	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).description("单支流式读取的最大空闲间隔毫秒"),
-	maxRequestImageBytes: z.natural().description("单请求 base64 图片载荷上限字节；缺省 20MiB（0.1.2-alpha.1 起官方必需字段，旧配置免改）"),
+	maxRequestImageBytes: z.natural().description("单请求 base64 图片载荷上限字节；缺省 20MiB（官方必需字段，旧配置免改）"),
 	requestImagePixelBudget: z.number().step(1).min(1).description("单请求每个确定性内联图片版本的像素总预算；缺省 2048x2048（官方同值）"),
 	requestImageMaxBytes: z.number().step(1).min(1).description("内联图片版本编码字节目标；缺省 1MiB（官方同值）"),
 	retryPolicy: z.any().description("provider 重试策略（dsh-llm RetryPolicy 形状，构建期校验）"),
@@ -515,7 +514,7 @@ function browseModels(kit, query = {}) {
 * 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` 直读官方副本守门推导正确性。
 *
@@ -650,10 +649,18 @@ const FALLBACK_MODEL_ENTRY_FIELDS = [
 function fallbackProtocols() {
 	return [...FALLBACK_PROTOCOLS];
 }
-/** 官方门控表不可解析时的最后已知快照（0.1.5-rc.2 实测值）。 */
+/**
+* 官方门控表不可解析时的兜底快照（0.2.1-alpha.1 现场推导值）。
+*
+* 只在官方改打包形态、`COMPAT_GATES` 解析失败时启用（此时未知键放行、只拦快照里
+* 明确 withhold 的键，见 compat.ts 的「语义分两档」）。快照过期会重新引入
+* 「误拒官方新字段」那类静默故障，故由 tests/official-surface.test.ts 的
+* 「兜底快照不得过期」用例与现场推导逐协议比对守门。
+*/
 const FALLBACK_TABLE = {
 	source: "fallback",
 	gates: {
+		"mistral-conversations": { supportsMidConvoSystemMessages: "withhold" },
 		"openai-completions": {
 			supportsStore: "offer",
 			supportsDeveloperRole: "offer",
@@ -679,7 +686,8 @@ const FALLBACK_TABLE = {
 			zaiToolStream: "withhold",
 			supportsOpenAIGrammarTools: "withhold",
 			sendSessionAffinityHeaders: "withhold",
-			deferredToolsMode: "withhold",
+			supportsMidConvoSystemMessages: "withhold",
+			supportsMidConvoToolAdditions: "withhold",
 			sessionAffinityFormat: "withhold"
 		},
 		"openai-responses": {
@@ -691,7 +699,32 @@ const FALLBACK_TABLE = {
 			supportsOpenAIGrammarTools: "withhold",
 			supportsAdditionalTools: "withhold",
 			supportsToolSearch: "withhold",
-			supportsExplicitPromptCacheMode: "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",
@@ -702,10 +735,13 @@ const FALLBACK_TABLE = {
 			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",
@@ -771,6 +807,10 @@ function compatTableInfo() {
 		problem: active.problem
 	};
 }
+/** 某协议某字段的可配性（'offer'/'withhold'；未列出 = 无此字段）。 */
+function compatDispositionOf(api, field) {
+	return active.gates[api]?.[field];
+}
 /** 某协议全部可配置（offer）的 compat 键（UI 渲染字段组与校验共用）。 */
 function compatFieldsOf(api) {
 	const gate = active.gates[api];
@@ -815,7 +855,7 @@ function checkValue(field, spec, value, where) {
 }
 /**
 * 校验一份 compat 字典对指定协议合法（对齐官方门控语义 + schema 值约束）：
-* - 未知键/withhold 字段拒绝（官方写时拒绝，替代旧版静默丢弃）；
+* - 未知键/withhold 字段拒绝（与官方写时拒绝同款）；
 * - 值类型/枚举按官方 schema 校验；
 * - 无值键（null/undefined）拒绝（官方 assertOfferedCompatFields 同款）。
 */
@@ -1521,7 +1561,6 @@ function declaredModalities(configured) {
 /** 物化单个模型目录条目：官方 base 在下，条目显式字段逐字段覆盖。 */
 function materializeModel$1(route, entry, deps) {
 	if (entry.reasoningEfforts !== void 0 || nonEmptyDict(entry.compat)) invalid$1(route, `model "${entry.id}" 的 reasoningEfforts/compat 仅 adapter: pi 可用`);
-	if (entry.imageDetail !== void 0) invalid$1(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 = {
@@ -1582,7 +1621,7 @@ function rawAdapterConfig(profile, baseURL, models) {
 /** 物化单个 deepseek route；lenient 下失败告警并返回 null（调用方跳过注册）。 */
 function buildRoute(route, profile, deps) {
 	try {
-		if (deps.kit.deepseek === void 0) invalid$1(route, "使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（0.1.2-alpha.1 基线）");
+		if (deps.kit.deepseek === void 0) invalid$1(route, "使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（本仓基线的必需套件）");
 		rejectPiOnlyFields(route, profile);
 		if (profile.extends !== void 0 && profile.extends !== "deepseek") invalid$1(route, `的 extends ${JSON.stringify(profile.extends)} 非法：adapter: deepseek 仅支持 "deepseek"（官方目录）`);
 		if (profile.apiKeyEnv === void 0 || profile.apiKeyEnv.length === 0) invalid$1(route, "需要 apiKeyEnv：DeepSeekAdapter 无环境自发现，凭据引用必须显式配置");
@@ -1619,7 +1658,7 @@ function buildDeepseekRoutes(providers, deps) {
 //#endregion
 //#region src/profiles.ts
 /**
-* profile 构建器（0.1.2-alpha.2 复核兼容）：插件 Config → 官方 schema 形状的
+* profile 构建器：插件 Config → 官方 schema 形状的
 * 「前置数据源归一化」→ 官方 resolveProfiles（或插件等价兜底）→
 * ResolvedPiAiProviderProfile。
 *
@@ -1734,7 +1773,6 @@ function reasoningEffortsFromBase(provider, entry, base) {
 * 返回 null（调用方跳过该模型）。
 */
 function materializeModel(route, profile, entry, base, routeApi, defaultInput, deps) {
-	if (entry.imageDetail !== void 0) 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 === void 0) {
 		if (deps.lenient) {
@@ -2044,11 +2082,390 @@ function buildProfiles(providers, deps) {
 	}
 	return resolved;
 }
+/**
+* 应急副本用：逐 route 归一化为官方 schema 形状的 profile（与运行期同一条
+* normalizeRoute 链：extends 物化、单协议单端点约束、模型条目全显式）。
+*
+* 与运行期 buildProfiles 的两点差异：
+* - 不受 `enabled` 开关影响——副本是配置层事实，插件关闭时其 route 仍应可复制；
+* - 逐 route 隔离失败（不依赖 lenient 开关）——一个坏条目只丢它自己，
+*   不让整份应急副本变空。
+*
+* adapter: deepseek 的 route 与草稿路由不在此列（前者由 profiles-deepseek
+* 物化、后者本就不可服务），调用方按缺席另行告警。
+*/
+function normalizeOfficialRoutes(providers, deps) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [route, profile] of Object.entries(providers ?? {})) try {
+		const normalized = normalizeRoute(route, profile, deps);
+		if (normalized !== void 0) out.set(route, normalized.profile);
+	} catch (error) {
+		deps.warn?.(`llm-pi: provider "${route}" 无法物化为官方形状（${error instanceof Error ? error.message : String(error)}），已跳过应急副本的该 route`);
+	}
+	return out;
+}
 /** settings 写入校验钩子：完整试跑解析，非法配置在写入处拒绝。 */
 function assertServiceable(config, deps) {
 	buildProfiles(config.providers, deps);
 	buildDeepseekRoutes(config.providers, deps);
 }
+//#endregion
+//#region src/official-copy.ts
+/**
+* 官方应急副本的翻译与渲染（纯函数，零 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
+*/
+/** 副本文件在 Harness home（.dsh）根目录的落点；lifeboat 面板按同一路径消费（文件契约）。 */
+const OFFICIAL_COPY_PATH = dshHomePath("llm-pi.official-patch.yaml");
+/** deepseek 路由改写所用线协议：中继网关对外提供 OpenAI 兼容 chat completions 面。 */
+const DEEPSEEK_COPY_API = "openai-completions";
+/**
+* 官方 Config schema 布局不可识别时的 route 字段兜底（官方 PiAiProviderProfile
+* 最后已知键集）。与官方新增字段的失配只表现为「新字段不进副本」，不弄挂生成。
+*/
+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"
+];
+/** deepseek 专有且官方 llm-pi-ai 无对应字段的 raw 键（出现即记 warning）。 */
+const DEEPSEEK_UNMIGRATED_FIELDS = [
+	"thinking",
+	"reasoningEffort",
+	"maxRequestFilesBytes",
+	"filesApiTimeoutMs",
+	"fileExpiresAfterSeconds",
+	"fileRefreshMarginSeconds",
+	"maxImagesPerRequest",
+	"imageOffloadByteQuantum",
+	"inlineImageOffloadByteQuantum",
+	"imageOffloadCountQuantum"
+];
+/**
+* 从官方 Config schema 推导 route 字段键集（`providers.*` 的 dict 键）；
+* 布局不可识别/键集为空返回 undefined，调用方回退内置键集并告警。
+*/
+function deriveOfficialRouteFields(config) {
+	const fields = config.dict?.["providers"]?.inner?.dict;
+	if (fields === void 0) return void 0;
+	const keys = Object.keys(fields);
+	return keys.length > 0 ? keys : void 0;
+}
+/** compat 过滤：只保留该协议 offer 的字段（withhold/未知键丢弃）；无保留项返回 undefined。 */
+function offerCompat(api, compat) {
+	if (compat === void 0 || typeof compat !== "object") return void 0;
+	const out = {};
+	for (const [field, value] of Object.entries(compat)) {
+		if (value === void 0 || value === null) continue;
+		if (compatDispositionOf(api, field) === "offer") out[field] = value;
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/** 单个模型条目 → 官方键集内的条目（compat 另过 offer 门控）。 */
+function filterModel(api, model, modelFields) {
+	const source = model;
+	const out = {};
+	for (const key of modelFields) {
+		const value = source[key];
+		if (value === void 0) continue;
+		if (key === "compat") {
+			const compat = offerCompat(api, value);
+			if (compat !== void 0) out.compat = compat;
+			continue;
+		}
+		out[key] = value;
+	}
+	return out;
+}
+/** 归一化 profile → 官方 route 字段内的条目（models 逐条过滤）。 */
+function filterRoute(profile, routeFields, modelFields) {
+	const source = profile;
+	const api = typeof source["api"] === "string" ? source["api"] : "";
+	const out = {};
+	for (const key of routeFields) {
+		const value = source[key];
+		if (value === void 0) continue;
+		if (key === "models") {
+			out.models = (Array.isArray(value) ? value : []).map((model) => filterModel(api, model, modelFields));
+			continue;
+		}
+		out[key] = value;
+	}
+	return out;
+}
+/** deepseek 单模型 → 官方条目（inputModalities 改名 input；图像预算不迁移）。 */
+function deepseekModelEntry(model) {
+	const out = { id: model.id };
+	if (model.name !== void 0) out.name = model.name;
+	if (model.contextWindow !== void 0) out.contextWindow = model.contextWindow;
+	if (model.maxTokens !== void 0) out.maxTokens = model.maxTokens;
+	if (model.inputModalities !== void 0) out.input = [...model.inputModalities];
+	return out;
+}
+/**
+* deepseek 路由 → 官方 llm-pi-ai profile：连接事实取 resolveAdapterOptions 的
+* 校验产物（端点/凭据引用/限额），模型取官方目录物化结果。思考配置与文件通道
+* 字段不迁移（llm-pi-ai 无对应语义），逐项列入 unmirrored。
+*/
+function deepseekCopyProfile(raw, resolved) {
+	const connection = resolved.connection;
+	const unmirrored = DEEPSEEK_UNMIGRATED_FIELDS.filter((key) => raw[key] !== void 0);
+	if (raw.models?.some((m) => m.imagePixelBudget !== void 0 || m.imageMaxBytes !== void 0)) unmirrored.push("模型级 imagePixelBudget/imageMaxBytes");
+	const profile = {
+		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 !== void 0) profile.retryPolicy = raw.retryPolicy;
+	if (raw.maxInlineRequestImageBytes !== void 0) profile.maxRequestImageBytes = connection.maxInlineRequestImageBytes;
+	return {
+		profile,
+		unmirrored
+	};
+}
+/** 翻译整份配置为官方副本内容（纯函数；坏 route 的跳过告警由上游 warn 通道汇集）。 */
+function buildOfficialCopy(input) {
+	const warnings = [];
+	const providers = {};
+	for (const [route, raw] of Object.entries(input.providers)) {
+		if ((raw.adapter ?? "pi") === "deepseek") {
+			const resolved = input.deepseekResolved.get(route);
+			if (resolved === void 0) continue;
+			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 === void 0) {
+			if (isDraftRoute(raw)) warnings.push(`草稿 route "${route}" 未纳入副本（尚无模型）`);
+			continue;
+		}
+		providers[route] = filterRoute(normalized, input.routeFields, input.modelFields);
+	}
+	for (const [route, profile] of Object.entries(input.manualProviders ?? {})) if (profile !== null && typeof profile === "object") providers[route] = profile;
+	return {
+		providers,
+		warnings
+	};
+}
+/** 头注释：用途、两种应用方式、切换语义、回退方法与警告清单（确定性输出，mtime 即生成时间）。 */
+function renderHeader(copy, meta) {
+	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 时渲染空补丁列表 `[]`（应用无效果）——绝不产出「只禁用不供给」的误导性副本。
+*/
+function renderOfficialCopy(copy, meta) {
+	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 })}`;
+}
+//#endregion
+//#region src/official-copy-writer.ts
+/**
+* 官方应急副本的生成编排：装配（原始配置 → 物化 → 翻译）→ 逐 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
+*/
+/** 官方 llm-pi-ai 的 settings 命名空间（与插件 NS 同字面量，官方 0.1.x 起稳定）。 */
+const NS_OFFICIAL_PI_AI = "llm-pi-ai";
+/**
+* 手写官方条目来源：settings describe 的 llm-pi-ai 生效视图（composition base
+* = profile patch 行 + settings 用户层，schema 已解析、已过官方 validate）——
+* 官方 seam，无需自行解析 patch 文件。ns 未注册/读取失败时降级为「仅本插件
+* 改写条目」并附 warning，不阻断生成。
+*/
+function readManualProviders(settings) {
+	try {
+		const row = settings.describe().find((entry) => entry.ns === NS_OFFICIAL_PI_AI);
+		if (row === void 0) return { warning: "官方 llm-pi-ai 未注册（插件缺席），副本仅含本插件改写条目" };
+		const raw = row.value?.providers;
+		const providers = isVolatileRef(raw) ? raw.get() : raw;
+		if (providers === null || typeof providers !== "object") return {};
+		return { providers };
+	} catch (error) {
+		return { warning: `读取官方 llm-pi-ai 生效配置失败（${error instanceof Error ? error.message : String(error)}），副本仅含本插件改写条目` };
+	}
+}
+/** 文件是否已存在（内容备忘跳过后自愈外部删除）。 */
+async function fileExists(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+/** 组装 + 翻译：返回含全部 warning 的副本内容（尚未官方校验）。 */
+function assemble(deps, warnings) {
+	const routeFields = deriveOfficialRouteFields(deps.kit.officialConfig);
+	if (routeFields === void 0) 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 !== void 0) 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, copy, warnings) {
+	const accepted = {};
+	for (const [route, profile] of Object.entries(copy.providers)) {
+		try {
+			deps.kit.officialConfig({ providers: { [route]: profile } });
+			deps.kit.resolveProfiles({ [route]: profile });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			warnings.push(`route "${route}" 未通过官方校验，已从副本剔除：${message}`);
+			continue;
+		}
+		accepted[route] = profile;
+	}
+	return accepted;
+}
+/** 落盘：内容未变且文件仍在则跳过（并自愈外部删除）；返回最近生成时间。 */
+async function persist(path, content, state) {
+	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, path, state) {
+	const warnings = [];
+	const providers = acceptOfficial(deps, assemble(deps, warnings), warnings);
+	return {
+		path,
+		updatedAt: await persist(path, renderOfficialCopy({
+			providers,
+			warnings
+		}, { profile: deps.profile }), state),
+		routes: Object.keys(providers).length,
+		warnings
+	};
+}
+/** 装配写入器：启动/热更新/adapter 事件驱动，串行执行（promise 链）。 */
+function createOfficialCopyWriter(deps) {
+	const path = deps.path ?? OFFICIAL_COPY_PATH;
+	const state = {};
+	let status = {
+		path,
+		routes: 0,
+		warnings: []
+	};
+	let chain = Promise.resolve();
+	const ensureOfficialCopy = () => {
+		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
+	};
+}
 /** 官方 jsonImage：pi-ai 凭据里显式 undefined 成员 JSON 序列化为缺省/数组 null。 */
 function jsonImage(value) {
 	if (Array.isArray(value)) return value.map((entry) => entry === void 0 ? null : jsonImage(entry));
@@ -2173,7 +2590,7 @@ function authContextFrom(ctx) {
 * 模型条目字段集同样现场推导（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 树优先
@@ -2196,6 +2613,7 @@ function assertKitShape(kit, origin) {
 		"providerRetryPolicy"
 	]) if (typeof kit.PiAiAdapter.prototype[method] !== "function") problems.push(`PiAiAdapter.prototype.${method} 缺失`);
 	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("没有可服务的线协议（协议工厂全部加载失败）");
@@ -2431,6 +2849,7 @@ function kitFromTree(options) {
 		officialModelFields: surface.officialModelFields,
 		...surface.catalogGeneratedAt === void 0 ? {} : { catalogGeneratedAt: surface.catalogGeneratedAt },
 		PiAiAdapter: mods.piAiAdapter["PiAiAdapter"],
+		officialConfig: mods.piAiAdapter["Config"],
 		LlmError: mods.llm["LlmError"],
 		resolveRetryPolicy: mods.llm["resolveRetryPolicy"],
 		attributionHeaders: mods.llm["attributionHeaders"],
@@ -2509,6 +2928,7 @@ function loadVendoredKit(diagnostics = []) {
 		officialModelFields: surface.officialModelFields,
 		...surface.catalogGeneratedAt === void 0 ? {} : { catalogGeneratedAt: surface.catalogGeneratedAt },
 		PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
+		officialConfig: vendoredPiAiAdapter.Config,
 		LlmError: vendoredLlm.LlmError,
 		resolveRetryPolicy: vendoredLlm.resolveRetryPolicy,
 		attributionHeaders: vendoredLlm.attributionHeaders,
@@ -2848,16 +3268,26 @@ async function startRuntime(ctx, rawConfig) {
 		routes: deepseekRoutes
 	});
 	const ensureDeepseek = () => deepseekRegistrar.sync(deepseekRoutes());
+	const copyWriter = createOfficialCopyWriter({
+		kit,
+		current,
+		readManual: () => readManualProviders(ctx.settings),
+		profile: ctx.get("profileContext")?.name,
+		logger
+	});
 	ensureRegistration();
 	ensureDeepseek();
 	ensureDirectory();
+	copyWriter.ensureOfficialCopy();
 	const reconfigure = () => {
 		snapshot = unwrapVolatile(fields);
 		attempt(logger, "llm-pi: 更新被拒，保留此前注册的 route", ensureRegistration);
 		attempt(logger, "llm-pi: deepseek route 更新失败，保留此前注册", ensureDeepseek);
 		attempt(logger, "llm-pi: 更新被拒，保留此前的 configurable-provider 目录", ensureDirectory);
+		copyWriter.ensureOfficialCopy();
 	};
 	ctx.events.on("loader/volatile-update", reconfigure);
+	ctx.root.on("llm/adapters-updated", () => void copyWriter.ensureOfficialCopy());
 	ctx.on("internal/config", function(_raw, next) {
 		const candidate = next();
 		if (this !== ctx.fiber) return candidate;
@@ -2869,6 +3299,7 @@ async function startRuntime(ctx, rawConfig) {
 		const providers = listProviders(kit);
 		const generatedAt = kit.catalogGeneratedAt;
 		const notice = piAiVersionNotice(kit.versions.piAi);
+		const copy = copyWriter.status();
 		return {
 			source: kit.source,
 			...kit.root === void 0 ? {} : { root: kit.root },
@@ -2883,7 +3314,12 @@ async function startRuntime(ctx, rawConfig) {
 				...generatedAt === void 0 ? {} : { generatedAt }
 			},
 			compatSource: compatTableInfo().source,
-			diagnostics
+			officialCopy: copy,
+			diagnostics: [
+				...diagnostics,
+				...copy.warnings.map((warning) => `应急副本：${warning}`),
+				...copy.error === void 0 ? [] : [`应急副本：生成失败（${copy.error}）`]
+			]
 		};
 	};
 	return {
@@ -2897,7 +3333,11 @@ async function startRuntime(ctx, rawConfig) {
 //#endregion
 //#region src/index.ts
 const name = "dsh-plus-llm-pi";
-const inject = ["credentials", "llm"];
+const inject = [
+	"credentials",
+	"llm",
+	"settings"
+];
 async function apply(ctx, config) {
 	const runtime = await startRuntime(ctx, config);
 	ctx.inject(["webServer"], (webCtx) => {