@dsh-plus/llm-pi 0.1.44 → 0.2.0

package/lib/client.js

@@ -7,6 +7,42 @@ window.__ModuleLoader__.load({
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		//#region ../shared/src/client/fields.tsx
+		/** 卡片按钮（与 CardChrome 页脚同一套类名与视觉）。 */
+		function Button(props) {
+			const p = props.prefix ?? "dshp";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+				type: "button",
+				className: `${p}-btn ${props.variant === "primary" ? `${p}-btnPrimary` : `${p}-btnGhost`}`,
+				disabled: props.disabled === true,
+				onClick: props.onClick,
+				children: props.label
+			});
+		}
+		/**
+		* 勾选行：自绘圆角扁平开关（switch），对齐官方 WebUI 无原生 checkbox 的
+		* 设计语言（官方选择类控件全走胶囊/菜单，见 cardCss 的 -switch 规则）。
+		* 语义保持 checkbox（无障碍树与表单语义不变），视觉自绘。
+		*/
+		function CheckRow(props) {
+			const p = props.prefix ?? "dshp";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: `${p}-checkRow`,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+					id: props.id,
+					type: "checkbox",
+					role: "switch",
+					"aria-checked": props.checked,
+					checked: props.checked,
+					disabled: props.disabled === true,
+					onChange: (event) => props.onEdit(event.target.checked)
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+					htmlFor: props.id,
+					children: props.label
+				})]
+			});
+		}
+		//#endregion
 		//#region ../shared/src/client/card.tsx
 		const IDLE_STATUS = {
 			kind: "idle",
@@ -55,12 +91,12 @@ window.__ModuleLoader__.load({
 									className: `${p}-status${props.status.kind === "error" ? ` ${p}-statusError` : ""}`,
 									role: "status",
 									children: props.status.text
-								}) : null, props.actions.map((action) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-									type: "button",
-									className: `${p}-btn ${action.variant === "primary" ? `${p}-btnPrimary` : `${p}-btnGhost`}`,
-									disabled: action.disabled === true,
-									onClick: action.onClick,
-									children: action.label
+								}) : null, props.actions.map((action) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+									prefix: p,
+									label: action.label,
+									variant: action.variant,
+									disabled: action.disabled,
+									onClick: action.onClick
 								}, action.key))]
 							})
 						]
@@ -139,31 +175,6 @@ window.__ModuleLoader__.load({
 		* @module @dsh-plus/shared/client/draft
 		*/
 		//#endregion
-		//#region ../shared/src/client/fields.tsx
-		/**
-		* 勾选行：自绘圆角扁平开关（switch），对齐官方 WebUI 无原生 checkbox 的
-		* 设计语言（官方选择类控件全走胶囊/菜单，见 cardCss 的 -switch 规则）。
-		* 语义保持 checkbox（无障碍树与表单语义不变），视觉自绘。
-		*/
-		function CheckRow(props) {
-			const p = props.prefix ?? "dshp";
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: `${p}-checkRow`,
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-					id: props.id,
-					type: "checkbox",
-					role: "switch",
-					"aria-checked": props.checked,
-					checked: props.checked,
-					disabled: props.disabled === true,
-					onChange: (event) => props.onEdit(event.target.checked)
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
-					htmlFor: props.id,
-					children: props.label
-				})]
-			});
-		}
-		//#endregion
 		//#region ../shared/src/client/i18n.ts
 		/** 卡片通用文案（save/discard/unsaved/loading 等四插件共有键）。 */
 		const commonZh = {
@@ -1136,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: [
@@ -1179,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}`
@@ -2840,6 +2862,10 @@ ${extra}
 			runtimeCatalog: "内置模型目录",
 			runtimeProtocols: "可服务协议",
 			runtimeCompat: "compat 门控表",
+			runtimeOfficialCopy: "应急副本",
+			officialCopyPending: "尚未生成",
+			officialCopyFailed: "生成失败：",
+			officialCopyRoutes: "个 route",
 			runtimeDiagnostics: "诊断",
 			runtimeVersionUnknown: "未知",
 			runtimeCatalogUnit: "个 provider /",
@@ -2970,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.44",
+  "version": "0.2.0",
   "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、pi-ai 内置目录；协议/compat/字段集现场推导，自动跟随已装 dsh）",
   "type": "module",
   "main": "lib/index.js",
@@ -31,7 +31,8 @@
     }
   },
   "dependencies": {
-    "@dsh-plus/shared": "0.1.34"
+    "yaml": "^2.9.0",
+    "@dsh-plus/shared": "0.1.35"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5-alpha.1",