@dsh-plus/llm-pi 0.1.45 → 0.2.0

package/lib/client.js

@@ -1147,6 +1147,13 @@ ${extra}
 		function sourceLabel(t, source) {
 			return source === "official" ? t("runtimeDerived") : t("runtimeFallback");
 		}
+		/** 应急副本状态行：路径 · route 数 · 生成时间；未生成/失败显式提示。 */
+		function officialCopyText(kit, t) {
+			const copy = kit.officialCopy;
+			if (copy.error !== void 0) return `${t("officialCopyFailed")}${copy.error}`;
+			if (copy.updatedAt === void 0) return t("officialCopyPending");
+			return `${copy.path} · ${copy.routes} ${t("officialCopyRoutes")} · ${formatTime(copy.updatedAt, t("runtimeVersionUnknown"))}`;
+		}
 		function RootFields(props) {
 			const { t, draft, disabled, kit, onEdit } = props;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
@@ -1190,6 +1197,10 @@ ${extra}
 						className: "lpc-statusRow",
 						children: `${t("runtimeCompat")}：${sourceLabel(t, kit.compatSource)}`
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "lpc-statusRow",
+						children: `${t("runtimeOfficialCopy")}：${officialCopyText(kit, t)}`
+					}),
 					kit.versionNotice !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						className: "lpc-invalid",
 						children: `${t("runtimeNotice")}：${kit.versionNotice}`
@@ -2851,6 +2862,10 @@ ${extra}
 			runtimeCatalog: "内置模型目录",
 			runtimeProtocols: "可服务协议",
 			runtimeCompat: "compat 门控表",
+			runtimeOfficialCopy: "应急副本",
+			officialCopyPending: "尚未生成",
+			officialCopyFailed: "生成失败：",
+			officialCopyRoutes: "个 route",
 			runtimeDiagnostics: "诊断",
 			runtimeVersionUnknown: "未知",
 			runtimeCatalogUnit: "个 provider /",
@@ -2981,6 +2996,10 @@ ${extra}
 			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/lib/index.d.ts

@@ -95,7 +95,7 @@ declare const Config: z<LlmPiConfigInput, LlmPiConfigFields>;
 //#endregion
 //#region src/index.d.ts
 declare const name = "dsh-plus-llm-pi";
-declare const inject: readonly ['credentials', 'llm'];
+declare const inject: readonly ['credentials', 'llm', 'settings'];
 declare function apply(ctx: Context, config: LlmPiConfig): Promise<void>;
 //#endregion
 export { Config, type LlmPiConfig, type ModelEntryConfig, type ProviderProfileConfig, SETTINGS_NS, apply, inject, name };

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,7 +19,6 @@ 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
@@ -771,6 +773,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];
@@ -2044,11 +2050,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));
@@ -2196,6 +2581,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 +2817,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 +2896,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 +3236,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 +3267,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 +3282,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 +3301,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) => {

package/package.json

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

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,

package/src/service.ts

@@ -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[]
 }
@@ -412,9 +419,20 @@ 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 三钩子）：
   // - 活动引用原位提交 → volatile-update 触发快照换代与重注册（原 onChange 体）；
@@ -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}）`]),
+      ],
     }
   }