@dsh-plus/llm-pi 0.1.42 → 0.1.43

package/lib/index.js

@@ -1,14 +1,11 @@
 import z from "@deepseek-ai/schemastery";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { deepEqualJson } from "@deepseek-ai/dsh-util-values";
-import { hasVolatileRefs, pluginDataPath, unwrapVolatile } from "@dsh-plus/shared";
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
-import { request } from "node:http";
-import { request as request$1 } from "node:https";
+import { hasVolatileRefs, unwrapVolatile } from "@dsh-plus/shared";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { HttpsProxyAgent } from "https-proxy-agent";
-import { credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
 import { fileURLToPath, pathToFileURL } from "node:url";
+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";
 import { LlmError } from "@deepseek-ai/dsh-llm";
@@ -30,13 +27,20 @@ import { homedir } from "node:os";
 *
 * 与官方 llm-pi-ai 的差异：
 * - compat 是开放 dict，物化时按协议校验（见 compat.ts），写入即拒绝未知键；
-* - provider/model 均支持 extends 继承（见 inherit.ts）。
+* - provider/model 均支持 extends 继承（见 inherit.ts），继承源只有 pi-ai 内置目录；
+* - `api` 不在 schema 里钉死枚举：合法协议集合由已安装官方适配器现场推导
+*   （见 official-surface/resolve-dsh），写时由 profiles.ts 以明确错误拒绝不支持者，
+*   官方将来新增协议无需改本插件。
 * @module llm-pi/config
 */
 /** settings 命名空间（字面量即合法命名空间，0.1.2-alpha.2 起编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
 const SETTINGS_NS = "dsh-plus-llm-pi";
-/** 本插件可为手写 route 提供的协议实现（与官方 PROTOCOLS 表一致）。 */
-const PROTOCOL_IDS = [
+/**
+* 官方适配器不可用/推导失败时的协议兜底三元组（自 0.1.2-alpha 线以来的稳定集）。
+* 运行期生效集合来自已安装官方包的 `supportedProtocols()`（见 resolve-dsh.ts），
+* 本常量只用于 schema 描述、浏览器半首帧兜底与推导失败回退。
+*/
+const FALLBACK_PROTOCOLS = [
 	"openai-completions",
 	"openai-responses",
 	"anthropic-messages"
@@ -101,10 +105,10 @@ const modelEntry = z.object({
 	imageDetail: z.union(DEEPSEEK_IMAGE_DETAILS).description("（已移除）图片细节档位；0.1.2-alpha.1 起请改用 imagePixelBudget/imageMaxBytes")
 });
 const providerProfile = z.object({
-	adapter: z.union(ADAPTER_KINDS).description("路由适配器：pi=PiAiAdapter（默认，三协议）；deepseek=官方 DeepSeekAdapter（图片走 Files API 文件通道，失败自动降级 base64）").default("pi"),
-	extends: z.string().description("provider 级继承：内置 provider id，提供 api/baseURL 默认值与模型 extends 的缺省查找源"),
+	adapter: z.union(ADAPTER_KINDS).description("路由适配器：pi=PiAiAdapter（默认，协议集合随已装官方适配器推导）；deepseek=官方 DeepSeekAdapter（图片走 Files API 文件通道，失败自动降级 base64）").default("pi"),
+	extends: z.string().description("provider 级继承：pi-ai 内置 provider id，提供 api/baseURL 默认值与模型 extends 的缺省查找源"),
 	displayName: z.string().description("选择器显示名；缺省为 route 键"),
-	api: z.union(PROTOCOL_IDS).description("线协议；缺省逐模型取继承值的 api，全部一致时作为 route 协议"),
+	api: z.string().description("线协议（合法集合由已装官方适配器运行期推导，见配置页「内置模型目录」状态行）；缺省逐模型取继承值的 api，全部一致时作为 route 协议"),
 	baseURL: z.string().description("端点；缺省继承 extends 源 provider 的端点"),
 	apiKeyEnv: z.string().role("credential-ref").description("凭据引用名（凭据服务/环境变量）"),
 	headers: z.dict(z.string()).description("provider 请求头（Harness 署名头保留名优先）"),
@@ -147,13 +151,85 @@ const providerProfile = z.object({
 });
 const Config = z.object({
 	enabled: z.boolean().description("总开关（关闭则不注册任何 route）").default(true).volatile(),
-	catalogUrl: z.string().description("models.dev 目录数据端点").default("https://models.dev/api.json").volatile(),
-	catalogRefreshHours: z.number().description("models.dev 自动拉取间隔小时数；0 = 不自动拉取（可手动拉取或读已有缓存）").default(0).volatile(),
-	catalogProxy: z.string().description("拉取 models.dev 目录时的 HTTP 代理地址（如 http://127.0.0.1:7890）；留空直连").default("").volatile(),
 	providers: z.dict(providerProfile).description("provider 路由表，键即 route 名").default({}).volatile()
 });
 //#endregion
 //#region src/catalog/builtin.ts
+/** 已在 facts 显式取出的键：这些不再进 rest。 */
+const FACT_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"provider",
+	"name",
+	"api",
+	"baseUrl",
+	"reasoning",
+	"input",
+	"contextWindow",
+	"maxTokens",
+	"thinkingLevelMap",
+	"compat"
+]);
+/** JSON 值浅拷贝（对象/数组一层；条目要经 settings 序列化，不可留上游引用）。 */
+function cloneJsonValue(value) {
+	if (Array.isArray(value)) return [...value];
+	if (typeof value === "object" && value !== null) return { ...value };
+	return value;
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** 读模态数组：只保留 text/image 两种已知值，其余丢弃（防上游改成别的枚举）。 */
+function readInput(value) {
+	if (!Array.isArray(value)) return ["text"];
+	const out = value.filter((m) => m === "text" || m === "image");
+	return out.length > 0 ? out : ["text"];
+}
+/** 读 thinkingLevelMap：值为字符串或 null，其余（含 undefined 键）丢弃。 */
+function readThinkingLevelMap(value) {
+	const record = asRecord(value);
+	if (record === void 0) return void 0;
+	const out = {};
+	for (const [level, wire] of Object.entries(record)) if (typeof wire === "string") out[level] = wire;
+	else if (wire === null) out[level] = null;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/**
+* 把运行期模型对象读成事实快照。入参用 unknown：pi-ai Model 的类型随版本变化，
+* 继承/浏览都只依赖此处确认过的字段，未确认的一律进 rest 原样展示。
+*/
+function builtinModelFacts(provider, raw) {
+	const model = asRecord(raw);
+	if (model === void 0) return void 0;
+	const id = model["id"];
+	if (typeof id !== "string" || id.length === 0) return void 0;
+	const rest = {};
+	for (const [key, value] of Object.entries(model)) {
+		if (FACT_KEYS.has(key) || value === void 0) continue;
+		rest[key] = cloneJsonValue(value);
+	}
+	const name = model["name"];
+	const api = model["api"];
+	const baseUrl = model["baseUrl"];
+	const contextWindow = model["contextWindow"];
+	const maxTokens = model["maxTokens"];
+	const thinkingLevelMap = readThinkingLevelMap(model["thinkingLevelMap"]);
+	const compat = asRecord(model["compat"]);
+	return {
+		provider,
+		id,
+		path: `${provider}/${id}`,
+		name: typeof name === "string" && name.length > 0 ? name : id,
+		api: typeof api === "string" ? api : "",
+		baseUrl: typeof baseUrl === "string" ? baseUrl : "",
+		reasoning: model["reasoning"] === true,
+		input: readInput(model["input"]),
+		contextWindow: typeof contextWindow === "number" ? contextWindow : 0,
+		maxTokens: typeof maxTokens === "number" ? maxTokens : 0,
+		...thinkingLevelMap === void 0 ? {} : { thinkingLevelMap },
+		...compat === void 0 ? {} : { compat: { ...compat } },
+		rest
+	};
+}
 /** 内置 provider 的端点（provider 级 extends 的 baseURL 缺省值）。 */
 function builtinProviderBaseUrl(kit, provider) {
 	return kit.builtinProviders().find((p) => p.id === provider)?.baseUrl;
@@ -165,43 +241,289 @@ function builtinProviderBaseUrl(kit, provider) {
 function hasBuiltinProvider(kit, provider) {
 	return kit.getBuiltinProviders().includes(provider);
 }
-/** 内置 provider 的全部模型 id（UI extends 选择器用）。 */
+/** 内置 provider 的全部模型 id（UI 选择器/浏览用）。 */
 function builtinModelIds(kit, provider) {
 	if (!hasBuiltinProvider(kit, provider)) return [];
 	return kit.getBuiltinModels(provider).map((m) => m.id);
 }
-/** 查单个内置模型为继承 base；未命中返回 undefined。 */
-function builtinModelBase(kit, provider, modelId) {
+/** 内置目录的全部 provider 条目（含 pi-ai 给的显示名与端点）。 */
+function builtinProviderEntries(kit) {
+	const catalog = kit.builtinProviders();
+	const byId = new Map(catalog.map((p) => [p.id, p]));
+	return kit.getBuiltinProviders().map((id) => {
+		const provider = byId.get(id);
+		const baseUrl = provider?.baseUrl;
+		return {
+			id,
+			name: provider?.name ?? id,
+			...typeof baseUrl === "string" && baseUrl.length > 0 ? { baseUrl } : {},
+			modelCount: kit.getBuiltinModels(id).length
+		};
+	});
+}
+/** 取某 provider 下某模型的事实快照；provider/模型不存在返回 undefined。 */
+function builtinModelFactsOf(kit, provider, modelId) {
 	if (!hasBuiltinProvider(kit, provider)) return void 0;
 	const model = kit.getBuiltinModels(provider).find((m) => m.id === modelId);
-	if (model === void 0) return void 0;
+	return model === void 0 ? void 0 : builtinModelFacts(provider, model);
+}
+/** 事实快照 → 继承 base（`extra` 只包含官方 schema 接受的其余模型级键）。 */
+function modelBaseOf(kit, facts) {
+	const extra = {};
+	for (const field of kit.officialModelFields) {
+		if (FACT_KEYS.has(field) || field === "reasoningEfforts") continue;
+		const value = facts.rest[field];
+		if (value !== void 0) extra[field] = cloneJsonValue(value);
+	}
 	return {
-		name: model.name,
-		api: model.api,
-		baseUrl: model.baseUrl,
-		input: [...model.input],
-		reasoning: model.reasoning,
-		...model.thinkingLevelMap === void 0 ? {} : { thinkingLevelMap: { ...model.thinkingLevelMap } },
-		...model.compat === void 0 ? {} : { compat: { ...model.compat } },
-		contextWindow: model.contextWindow,
-		maxTokens: model.maxTokens,
-		cost: { ...model.cost },
-		...model.headers === void 0 ? {} : { headers: { ...model.headers } }
+		name: facts.name,
+		api: facts.api,
+		baseUrl: facts.baseUrl,
+		input: [...facts.input],
+		reasoning: facts.reasoning,
+		...facts.thinkingLevelMap === void 0 ? {} : { thinkingLevelMap: { ...facts.thinkingLevelMap } },
+		...facts.compat === void 0 ? {} : { compat: { ...facts.compat } },
+		contextWindow: facts.contextWindow,
+		maxTokens: facts.maxTokens,
+		...Object.keys(extra).length === 0 ? {} : { extra }
 	};
 }
+/** 查单个内置模型为继承 base；未命中返回 undefined。 */
+function builtinModelBase(kit, provider, modelId) {
+	const facts = builtinModelFactsOf(kit, provider, modelId);
+	return facts === void 0 ? void 0 : modelBaseOf(kit, facts);
+}
 /**
 * provider 级 extends 的全量模型继承：route 不写 models 时，
 * 以继承源 provider 的全部内置模型作为条目（每个条目 base 即其自身）。
 */
 function inheritedCatalogEntries(kit, provider) {
 	if (!hasBuiltinProvider(kit, provider)) return [];
-	return kit.getBuiltinModels(provider).map((model) => ({
-		id: model.id,
-		base: builtinModelBase(kit, provider, model.id) ?? {}
-	}));
+	return kit.getBuiltinModels(provider).map((model) => {
+		const facts = builtinModelFacts(provider, model);
+		return {
+			id: model.id,
+			base: facts === void 0 ? {} : modelBaseOf(kit, facts)
+		};
+	});
+}
+/** 全量快照按 kit 备忘（同一 kit 实例的目录在进程内不变）。 */
+const snapshotCache = /* @__PURE__ */ new WeakMap();
+/** 归一化：小写 + 去掉分隔符（`/ - _ . 空格`），用于子序列匹配。 */
+function compact(text) {
+	return text.toLowerCase().replace(/[\s/\-_.]+/g, "");
+}
+/** 按分隔符切词（小写），用于词首命中判定。 */
+function words(text) {
+	return text.toLowerCase().split(/[\s/\-_.]+/).filter((word) => word.length > 0);
+}
+/**
+* 模糊匹配得分：越小越相关；不匹配返回 undefined。
+* 分级：完全相等 0 < 整体前缀 1 < 词首前缀 2 < 子串 3 < 归一化相等 4 <
+* 归一化前缀 5 < 首字母缩写 6+（同一档内以命中跨度加权，越紧凑越小）。
+*
+* 缩写匹配要求首字符落在**词首**（`deepseek-flash` 的 `d`、`flash` 的 `f`）：
+* 否则任何长路径都会命中任意短查询（实测 `kimi` 会命中
+* `cloudflare-ai-gateway/workers-ai/@cf/ibm-granite/...`——wokers 里的 k 起头也能凑出
+* 子序列），搜索质量崩坏。跳字过多（超过 needle 长度 4 倍）同样判不命中。
+*/
+function fuzzyScore(query, target) {
+	const needle = query.toLowerCase();
+	if (needle.length === 0) return 0;
+	const haystack = target.toLowerCase();
+	if (haystack === needle) return 0;
+	if (haystack.startsWith(needle)) return 1;
+	if (words(target).some((word) => word.startsWith(needle))) return 2;
+	if (haystack.includes(needle)) return 3;
+	const compactNeedle = compact(query);
+	const compactTarget = compact(target);
+	if (compactNeedle.length === 0) return 0;
+	if (compactTarget === compactNeedle) return 4;
+	if (compactTarget.startsWith(compactNeedle)) return 5;
+	if (compactNeedle.length === 1) return 6;
+	const first = needle[0];
+	const spanCap = compactNeedle.length * 4 + 4;
+	let best;
+	for (const start of wordStarts(target)) {
+		if (haystack[start] !== first) continue;
+		let cursor = 1;
+		let last = start;
+		for (let i = start + 1; i < haystack.length && cursor < compactNeedle.length; i += 1) {
+			const ch = haystack[i];
+			if (/[\s/\-_.]/.test(ch)) continue;
+			if (ch === compactNeedle[cursor]) {
+				cursor += 1;
+				last = i;
+			}
+		}
+		if (cursor < compactNeedle.length) continue;
+		const span = last - start + 1;
+		if (span > spanCap) continue;
+		const score = 6 + span / spanCap;
+		if (best === void 0 || score < best) best = score;
+	}
+	return best;
+}
+/** 词首下标（按分隔符切分的每个词的首字符位置）。 */
+function wordStarts(text) {
+	const out = [];
+	let atStart = true;
+	for (let i = 0; i < text.length; i += 1) {
+		const ch = text[i];
+		if (/[\s/\-_.]/.test(ch)) {
+			atStart = true;
+			continue;
+		}
+		if (atStart) {
+			out.push(i);
+			atStart = false;
+		}
+	}
+	return out;
+}
+/** 单条记录的多字段得分：取最相关字段；全部字段都不匹配返回 undefined。 */
+function scoreOf(query, info) {
+	let best;
+	for (const field of [
+		info.path,
+		info.id,
+		info.name,
+		info.provider
+	]) {
+		const score = fuzzyScore(query, field);
+		if (score === void 0) continue;
+		const weighted = field === info.path ? score : score + 2;
+		if (best === void 0 || weighted < best) best = weighted;
+	}
+	return best;
+}
+/** 多词 AND：每个词都要有命中，得分取各词之和（词少者更相关由长度自然体现）。 */
+function multiScore(query, info) {
+	const tokens = query.split(/\s+/).filter((token) => token.length > 0);
+	if (tokens.length === 0) return 0;
+	let total = 0;
+	for (const token of tokens) {
+		const score = scoreOf(token, info);
+		if (score === void 0) return void 0;
+		total += score;
+	}
+	return total;
+}
+function toInfo(kit, facts) {
+	return {
+		provider: facts.provider,
+		id: facts.id,
+		path: facts.path,
+		name: facts.name,
+		api: facts.api,
+		baseUrl: facts.baseUrl,
+		contextWindow: facts.contextWindow,
+		maxTokens: facts.maxTokens,
+		input: facts.input,
+		reasoning: facts.reasoning,
+		...facts.thinkingLevelMap === void 0 ? {} : { thinkingLevelMap: facts.thinkingLevelMap },
+		...facts.compat === void 0 ? {} : { compat: facts.compat },
+		rest: facts.rest,
+		servable: kit.protocols.includes(facts.api)
+	};
+}
+/** 全量模型条目（按目录顺序：provider 排序即 pi-ai 目录顺序，模型同）。 */
+function listModelInfos(kit) {
+	const cached = snapshotCache.get(kit);
+	if (cached !== void 0) return cached;
+	const out = [];
+	for (const provider of kit.getBuiltinProviders()) for (const model of kit.getBuiltinModels(provider)) {
+		const facts = builtinModelFacts(provider, model);
+		if (facts !== void 0) out.push(toInfo(kit, facts));
+	}
+	snapshotCache.set(kit, out);
+	return out;
+}
+/** 供应商条目（含模型数与显示名）。 */
+function listProviders(kit) {
+	return builtinProviderEntries(kit);
+}
+/**
+* 紧凑协议索引 `{provider: {modelId: api}}`：浏览器半据此推断某个 route 当前
+* 实际生效的协议（route 级 `api` 缺省时由模型继承值决定），用于一键添加前的冲突检查。
+*/
+function buildApiIndex(infos) {
+	const out = {};
+	for (const info of infos) {
+		const perProvider = out[info.provider] ?? {};
+		perProvider[info.id] = info.api;
+		out[info.provider] = perProvider;
+	}
+	return out;
+}
+function matchesFilters(info, query) {
+	if (query.provider !== void 0 && query.provider.length > 0 && info.provider !== query.provider) return false;
+	if (query.api !== void 0 && query.api.length > 0 && info.api !== query.api) return false;
+	if (query.reasoning === true && !info.reasoning) return false;
+	if (query.image === true && !info.input.includes("image")) return false;
+	return true;
+}
+function clampLimit(value) {
+	if (value === void 0 || !Number.isFinite(value) || value <= 0) return 40;
+	return Math.min(Math.floor(value), 100);
+}
+/**
+* 搜索 + 过滤 + 分页。无搜索串时按目录顺序（provider/id）返回；
+* 有搜索串时按相关度排序，同分按路径字典序稳定。
+*/
+function browseModels(kit, query = {}) {
+	const all = listModelInfos(kit);
+	const servableOnly = query.servableOnly !== false;
+	const limit = clampLimit(query.limit);
+	const offset = Math.max(0, Math.floor(query.offset ?? 0));
+	const q = (query.q ?? "").trim();
+	let servableHidden = 0;
+	const matched = [];
+	for (const info of all) {
+		if (!info.servable) {
+			if (servableOnly) servableHidden += 1;
+			if (servableOnly) continue;
+		}
+		if (!matchesFilters(info, query)) continue;
+		const score = q.length === 0 ? 0 : multiScore(q, info);
+		if (score === void 0) continue;
+		matched.push({
+			info,
+			score
+		});
+	}
+	if (q.length > 0) matched.sort((left, right) => left.score === right.score ? left.info.path.length - right.info.path.length || left.info.path.localeCompare(right.info.path) : left.score - right.score);
+	return {
+		total: matched.length,
+		servableHidden,
+		offset,
+		limit,
+		items: matched.slice(offset, offset + limit).map((entry) => entry.info)
+	};
 }
 //#endregion
-//#region src/compat-gates.ts
+//#region src/official-surface.ts
+/**
+* 官方适配面的**自动继承**：从已安装的官方副本（`dsh-llm-pi-ai` + `pi-ai`）
+* 现场推导三样东西，取代早期的手抄镜像：
+*
+* 1. **线协议集合**：官方包根导出的 `supportedProtocols()`（官方 PROTOCOLS 表
+*    的唯一投影）。官方新增协议时本插件自动可用，不再需要改代码；
+* 2. **compat 门控与取值约束**：门控取自运行期 bundle 的 `COMPAT_GATES`
+*    （事实源：运行期拒绝哪些字段由它决定），取值约束取自导出的 Config schema
+*    的 `providers.*.compat` 节点（boolean / number.step(1) / enum / 对象）；
+* 3. **模型条目字段集**：Config schema 的 `providers.*.models` 键集——继承时按此
+*    透传 pi-ai 目录的同名字段，官方将来新增模型级字段即自动跟随。
+*
+* 历史教训（0.1.5-rc.1）：compat 门控曾是官方 catalog.ts 的手抄镜像，官方扩容
+* offer 字段而旧表漏收，导致官方可配字段被本插件**误拒**（静默功能缺失、无报错）。
+* 现改为现场推导，`tests/official-surface.test.ts` 直读官方副本守门推导正确性。
+*
+* 推导失败（官方改布局/改打包形态）时回退到 FALLBACK_*：compat 表用最后已知快照
+* 且**放宽未知键**（见 compat.ts：宁可放行交给官方自身校验，也不误拒官方新字段），
+* 协议回退三元组、模型字段回退已知七键，各自给出诊断——绝不因推导失败弄挂启动。
+* @module llm-pi/official-surface
+*/
 /** 从 `{` 起做括号配对，返回内部文本；未配对返回 undefined。 */
 function balancedBody(text, openIndex) {
 	const start = text.indexOf("{", openIndex);
@@ -291,6 +613,43 @@ function deriveSpecs(module) {
 	}
 	return out;
 }
+/**
+* 从官方适配器模块推导线协议集合：官方包根导出的 `supportedProtocols()`
+* （`Object.keys(PROTOCOLS)` 的投影，顺序即官方表顺序）。
+* 非函数/返回空/含非字符串项都视为推导失败，调用方回退内置三元组。
+*/
+function deriveProtocols(module) {
+	const reader = module["supportedProtocols"];
+	if (typeof reader !== "function") return void 0;
+	const value = reader();
+	if (!Array.isArray(value) || value.length === 0) return void 0;
+	const ids = value.filter((id) => typeof id === "string" && id.length > 0);
+	return ids.length === value.length ? ids : void 0;
+}
+/**
+* 从官方 Config schema 推导模型条目字段集（`providers.*.models` 的元素键集）。
+* 这些是官方适配器**接受**的模型级键；继承时按此透传 pi-ai 目录的同名字段。
+*/
+function deriveModelEntryFields(module) {
+	const fields = (module["Config"]?.dict?.["providers"]?.inner?.dict?.["models"])?.inner?.dict;
+	if (fields === void 0) return void 0;
+	const keys = Object.keys(fields);
+	return keys.length > 0 ? keys : void 0;
+}
+/** 推导失败时的模型条目字段兜底（0.2.x 线实测键集）。 */
+const FALLBACK_MODEL_ENTRY_FIELDS = [
+	"id",
+	"name",
+	"contextWindow",
+	"maxTokens",
+	"input",
+	"reasoningEfforts",
+	"compat"
+];
+/** 协议推导失败时的兜底三元组（转出为可变数组，便于调用方直接持有）。 */
+function fallbackProtocols() {
+	return [...FALLBACK_PROTOCOLS];
+}
 /** 官方门控表不可解析时的最后已知快照（0.1.5-rc.2 实测值）。 */
 const FALLBACK_TABLE = {
 	source: "fallback",
@@ -418,6 +777,13 @@ function compatFieldsOf(api) {
 	if (gate === void 0) return [];
 	return Object.entries(gate).flatMap(([field, disposition]) => disposition === "offer" ? [field] : []);
 }
+/**
+* 生效表里出现过的协议键（运行期协议列表为空时的渲染兜底：
+* 套件异常也要让表单能画出来）。
+*/
+function compatProtocols() {
+	return Object.keys(active.gates);
+}
 /** 某协议某 offer 字段的取值约束（UI 渲染开关/下拉用）。 */
 function compatFieldSpec(api, field) {
 	return active.gates[api]?.[field] === "offer" ? active.specs[field] : void 0;
@@ -455,14 +821,16 @@ function checkValue(field, spec, value, where) {
 */
 function validateCompat(api, compat, where) {
 	if (compat === void 0) return;
-	const gate = active.gates[api];
-	if (gate === void 0) throw new Error(`${where}: 协议 ${JSON.stringify(api)} 无 compat 字段表（支持：${Object.keys(active.gates).join(", ")}）`);
+	const table = active;
+	const gate = table.gates[api];
+	if (gate === void 0) throw new Error(`${where}: 协议 ${JSON.stringify(api)} 无 compat 字段表（可配协议：${Object.keys(table.gates).join(", ")}）`);
 	const offered = compatFieldsOf(api);
+	const permissive = table.source === "fallback";
 	for (const [key, value] of Object.entries(compat)) {
 		const disposition = gate[key];
 		if (disposition !== "offer") {
 			if (disposition === "withhold") throw new Error(`${where}: compat.${key} 官方按协议 withhold（内置目录已为对应厂商设置该开关）；请以目录 provider 名作为 route 名（继承目录值），或移除该字段`);
-			throw new Error(`${where}: compat.${key} 不是 ${api} 协议的合法字段（可配置字段：${offered.join(", ")}；官方全部可配字段：${allOfferedFields().join(", ")}）`);
+			if (!permissive) throw new Error(`${where}: compat.${key} 不是 ${api} 协议的合法字段（可配置字段：${offered.join(", ")}；官方全部可配字段：${allOfferedFields().join(", ")}）`);
 		}
 		if (value === void 0 || value === null) throw new Error(`${where}: compat.${key} 未设置值；给出值或移除该键（留空不会生效）`);
 		const spec = active.specs[key];
@@ -484,13 +852,28 @@ function mergeCompat(...layers) {
 //#endregion
 //#region src/config-api.ts
 const ROUTE_CATALOG = "/dsh-plus/llm-pi/catalog";
+const ROUTE_MODELS = `${ROUTE_CATALOG}/models`;
+/** 查询参数里的布尔开关：'1'/'true' 为真。 */
+function boolParam(value, fallback) {
+	if (value === null) return fallback;
+	return value === "1" || value === "true";
+}
+/** 查询参数里的整数；缺失/非法返回 undefined（由消费方取默认）。 */
+function intParam(value) {
+	if (value === null || value.trim() === "") return void 0;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
 /**
 * 服务端推导的 compat 字段表（协议 → 字段 → 取值约束）。浏览器半读不到官方包，
 * 由本端点下发，UI 渲染与服务端校验同源（不再各存一份手抄镜像表）。
+* 协议列表取运行期生效集合（不能服务的协议不渲染控件）；运行期列表为空时退回
+* 生效表自身的协议键，保证套件异常时表单仍可编辑。
 */
-function compatTablePayload() {
+function compatTablePayload(protocols) {
+	const list = protocols.length > 0 ? [...protocols] : compatProtocols();
 	const fields = {};
-	for (const api of PROTOCOL_IDS) {
+	for (const api of list) {
 		const perField = {};
 		for (const field of compatFieldsOf(api)) {
 			const spec = compatFieldSpec(api, field);
@@ -512,37 +895,31 @@ function sendJson(res, status, body) {
 	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
 	res.end(JSON.stringify(body));
 }
-/** 目录查询/手动拉取：GET ?provider=&source= → 该源模型 id 列表；POST /refresh → 立即拉取。 */
-function handleCatalog(runtime, req, res) {
-	const kitSource = runtime.kitInfo().source;
-	if (req.method === "POST" && req.url?.endsWith("/refresh")) {
-		runtime.modelsDev.refresh().then(() => {
-			sendJson(res, 200, { status: runtime.modelsDev.status() });
-		});
-		return;
-	}
-	const url = new URL(req.url ?? "", "http://localhost");
-	const provider = url.searchParams.get("provider") ?? "";
-	const source = url.searchParams.get("source") ?? "builtin";
-	const compat = compatTablePayload();
-	if (source === "models-dev") {
-		sendJson(res, 200, {
-			providers: runtime.modelsDev.providerIds(),
-			models: provider.length > 0 ? runtime.modelsDev.modelIds(provider) : [],
-			status: runtime.modelsDev.status(),
-			kitSource,
-			compat
-		});
-		return;
-	}
+/** 运行期事实 + 目录索引（卡片挂载时拉一次：版本、协议、目录规模、compat 字段表）。 */
+function handleMeta(runtime, res) {
+	const kit = runtime.kitInfo();
 	sendJson(res, 200, {
-		providers: runtime.kit.getBuiltinProviders(),
-		models: provider.length > 0 ? builtinModelIds(runtime.kit, provider) : [],
-		kitSource,
-		compat
+		kit,
+		providers: runtime.providerEntries(),
+		apis: runtime.apiIndex(),
+		compat: compatTablePayload(kit.protocols)
 	});
 }
-/** 注册目录路由（webServer 缺失时由调用方保证不调用）。 */
+/** 目录搜索：q（模糊）/provider/api/reasoning/image/servable/offset/limit。 */
+function handleModels(runtime, url, res) {
+	const limit = intParam(url.searchParams.get("limit"));
+	sendJson(res, 200, browseModels(runtime.kit, {
+		q: url.searchParams.get("q") ?? "",
+		provider: url.searchParams.get("provider") ?? "",
+		api: url.searchParams.get("api") ?? "",
+		reasoning: boolParam(url.searchParams.get("reasoning"), false),
+		image: boolParam(url.searchParams.get("image"), false),
+		servableOnly: boolParam(url.searchParams.get("servable"), true),
+		offset: intParam(url.searchParams.get("offset")) ?? 0,
+		...limit === void 0 ? {} : { limit }
+	}));
+}
+/** 目录路由（webServer 缺失时由调用方保证不调用）。 */
 function registerCatalogApi(ctx, runtime) {
 	const logger = ctx.logger("llm-pi");
 	const guard = (handler) => {
@@ -560,195 +937,20 @@ function registerCatalogApi(ctx, runtime) {
 	ctx.webServer.register({
 		kind: "prefix",
 		path: ROUTE_CATALOG,
-		handler: guard((req, res) => handleCatalog(runtime, req, res))
-	});
-}
-//#endregion
-//#region src/catalog/models-dev.ts
-/**
-* models.dev 兜底目录源：继承解析的第二级数据源。
-*
-* 只用于内置目录尚未收录的新模型/新供应商。数据是公开快照
-*（默认 https://models.dev/api.json），**默认不自动拉取**（catalogRefreshHours=0）；
-* 拉取方式二选一：
-* - 配置 catalogRefreshHours > 0：启动/过期后后台自动刷新；
-* - 配置卡片「手动拉取」或 POST /catalog/refresh：立即拉取。
-* 拉取可经 catalogProxy 代理（HTTP 代理，如 http://127.0.0.1:7890）。
-* 成功落盘缓存（$DSH_HOME/dsh-plus/llm-pi/models-dev.json）；任何失败都退化为
-* "仅内置目录"，绝不阻塞 route 注册。
-*
-* 保守原则：models.dev 数据未经 pi 官方校正（无 compat/thinkingLevelMap），
-* 且模态声明不被采信——继承自本源的模型 input 一律走 text-only 兜底，
-* 视觉等模态须用户在条目上显式声明（防 over-claiming 导致会话重复失败请求）。
-* @module llm-pi/catalog/models-dev
-*/
-const FETCH_TIMEOUT_MS = 2e4;
-/** 目录文档体上限（api.json 全量约 1-2MB，放宽到 20MB 防未来膨胀）。 */
-const MAX_RESPONSE_BYTES$1 = 20971520;
-/**
-* 极简 JSON GET（node:http(s) 实现）：支持 HTTP 代理（仅 https 目标）与超时。
-* 不跟随重定向（models.dev 直链无重定向；自定义端点需自行保证可直达）。
-*/
-function fetchJson(url, proxy, timeoutMs) {
-	return new Promise((resolve, reject) => {
-		const target = new URL(url);
-		const req = (target.protocol === "https:" ? request$1 : request)(url, {
-			agent: target.protocol === "https:" && proxy.length > 0 ? new HttpsProxyAgent(proxy) : void 0,
-			timeout: timeoutMs,
-			headers: { accept: "application/json" }
-		}, (response) => {
-			const chunks = [];
-			let size = 0;
-			let settled = false;
-			const fail = (error) => {
-				if (settled) return;
-				settled = true;
-				reject(error);
-			};
-			response.on("data", (chunk) => {
-				size += chunk.length;
-				if (size > MAX_RESPONSE_BYTES$1) {
-					req.destroy(/* @__PURE__ */ new Error("响应超过 20MB 上限"));
-					return;
-				}
-				chunks.push(chunk);
-			});
-			response.on("end", () => {
-				if (settled) return;
-				settled = true;
-				resolve({
-					status: response.statusCode ?? 0,
-					body: Buffer.concat(chunks).toString("utf8")
-				});
-			});
-			response.on("error", fail);
-		});
-		req.on("timeout", () => req.destroy(/* @__PURE__ */ new Error(`请求超时（${timeoutMs}ms）`)));
-		req.on("error", reject);
-		req.end();
+		handler: guard((req, res) => {
+			const url = new URL(req.url ?? "", "http://localhost");
+			if (url.pathname === ROUTE_MODELS) {
+				handleModels(runtime, url, res);
+				return;
+			}
+			if (url.pathname !== ROUTE_CATALOG) {
+				sendJson(res, 404, { error: `未知端点 ${url.pathname}` });
+				return;
+			}
+			handleMeta(runtime, res);
+		})
 	});
 }
-function isDocument(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** 单个 models.dev 模型条目 → 继承 base（仅采信名称/容量/推理能力）。 */
-function toModelBase(entry) {
-	const base = {};
-	if (typeof entry.name === "string" && entry.name.length > 0) base.name = entry.name;
-	const context = entry.limit?.context;
-	if (typeof context === "number" && Number.isInteger(context) && context > 0) base.contextWindow = context;
-	const output = entry.limit?.output;
-	if (typeof output === "number" && Number.isInteger(output) && output > 0) base.maxTokens = output;
-	base.reasoning = entry.reasoning === true;
-	return base;
-}
-var ModelsDevSource = class {
-	cacheFile;
-	url;
-	ttlHours;
-	proxy;
-	log;
-	document;
-	fetchedAt = null;
-	lastError = null;
-	refreshing;
-	constructor(cacheFile, url, ttlHours, log, proxy = "") {
-		this.cacheFile = cacheFile;
-		this.url = url;
-		this.ttlHours = ttlHours;
-		this.log = log;
-		this.proxy = proxy;
-	}
-	/** 配置变更时更新端点/TTL/代理并触发刷新（去抖由 refresh 的进行中复用承担）。 */
-	reconfigure(url, ttlHours, proxy) {
-		if (url === this.url && ttlHours === this.ttlHours && proxy === this.proxy) return;
-		this.url = url;
-		this.ttlHours = ttlHours;
-		this.proxy = proxy;
-		if (ttlHours > 0 && this.isStale()) this.refresh();
-	}
-	/** 是否已有可用数据（缓存或拉取成功）；与自动拉取开关无关。 */
-	get enabled() {
-		return this.document !== void 0;
-	}
-	/** 加载缓存，并在启用自动拉取且缓存过期时后台刷新；构造后调用一次，永不抛错。 */
-	async ensureLoaded() {
-		this.loadCache();
-		if (this.ttlHours > 0 && this.isStale()) await this.refresh();
-	}
-	/** 强制刷新（手动拉取/配置变更触发）；ttlHours=0 时同样生效（手动拉取不受自动开关限制）。 */
-	async refresh() {
-		this.refreshing ??= this.doFetch().finally(() => {
-			this.refreshing = void 0;
-		});
-		await this.refreshing;
-	}
-	/** 查继承 base；未命中/未启用返回 undefined。 */
-	lookup(provider, modelId) {
-		const entry = this.document?.[provider]?.models?.[modelId];
-		if (entry === void 0) return void 0;
-		return toModelBase(entry);
-	}
-	/** 全部 provider id（UI extends 选择器用）。 */
-	providerIds() {
-		return Object.keys(this.document ?? {});
-	}
-	/** 某 provider 的模型 id 列表（UI extends 选择器用）。 */
-	modelIds(provider) {
-		return Object.keys(this.document?.[provider]?.models ?? {});
-	}
-	status() {
-		const providers = Object.keys(this.document ?? {});
-		const models = providers.reduce((total, p) => total + Object.keys(this.document?.[p]?.models ?? {}).length, 0);
-		return {
-			fetchedAt: this.fetchedAt,
-			providers: providers.length,
-			models,
-			error: this.lastError
-		};
-	}
-	isStale() {
-		if (this.fetchedAt === null) return true;
-		const ageMs = Date.now() - Date.parse(this.fetchedAt);
-		return !Number.isFinite(ageMs) || ageMs > this.ttlHours * 36e5;
-	}
-	loadCache() {
-		try {
-			const raw = JSON.parse(readFileSync(this.cacheFile, "utf8"));
-			if (!isDocument(raw.data) || typeof raw.fetchedAt !== "string") throw new Error("缓存形状非法");
-			this.document = raw.data;
-			this.fetchedAt = raw.fetchedAt;
-		} catch {}
-	}
-	async doFetch() {
-		try {
-			const response = await fetchJson(this.url, this.proxy, FETCH_TIMEOUT_MS);
-			if (response.status < 200 || response.status >= 300) throw new Error(`HTTP ${response.status}`);
-			const data = JSON.parse(response.body);
-			if (!isDocument(data)) throw new Error("响应不是 models.dev 目录文档");
-			this.document = data;
-			this.fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
-			this.lastError = null;
-			this.persistCache(data);
-		} catch (error) {
-			this.lastError = error instanceof Error ? error.message : String(error);
-			this.log(`models.dev 目录拉取失败（沿用缓存/仅内置目录）：${this.lastError}`);
-		}
-	}
-	persistCache(data) {
-		try {
-			mkdirSync(dirname(this.cacheFile), { recursive: true });
-			const tmp = `${this.cacheFile}.tmp`;
-			writeFileSync(tmp, JSON.stringify({
-				fetchedAt: this.fetchedAt,
-				data
-			}), "utf8");
-			renameSync(tmp, this.cacheFile);
-		} catch (error) {
-			this.log(`models.dev 缓存写入失败：${error instanceof Error ? error.message : String(error)}`);
-		}
-	}
-};
 //#endregion
 //#region src/deepseek-routes.ts
 /** 凭据解析（逐行对齐官方 llm-deepseek resolveApiKey）：凭据服务优先，启动环境兜底。 */
@@ -1083,6 +1285,131 @@ async function discoverModels(request, deps) {
 	}
 }
 //#endregion
+//#region src/kit-meta.ts
+/**
+* 运行期套件元信息：插件实际在用哪一份 pi-ai / 官方适配器，以及版本是否落在
+* 本插件验证过的区间内。
+*
+* 存在的理由：插件**按文件路径**动态加载已装 dsh 树里的 pi-ai（版本随 dsh 升级
+* 自动变化，见 resolve-dsh.ts），因此"当前生效版本"不是 manifest 上写的版本。
+* 配置页把它显示出来，版本漂移一眼可见；`VERIFIED_PI_AI_RANGE` 只用于**提示**，
+* 永不阻断——能不能用由运行期形状自检（assertKitShape）与逐项降级决定。
+* @module llm-pi/kit-meta
+*/
+/** 本插件开发/测试覆盖过的 pi-ai 区间（semver range，仅用于状态行提示）。 */
+const VERIFIED_PI_AI_RANGE = ">=0.85.1 <0.88.0";
+/** 读 package.json 的 version；文件不存在/非 JSON/无 version 都返回 undefined。 */
+function readPackageVersion(manifestPath) {
+	try {
+		const version = JSON.parse(readFileSync(manifestPath, "utf8"))?.version;
+		return typeof version === "string" && version.length > 0 ? version : void 0;
+	} catch {
+		return;
+	}
+}
+/** 读包目录的版本（`<dir>/package.json`）。 */
+function packageVersionOf(packageDir) {
+	return readPackageVersion(join(packageDir, "package.json"));
+}
+/** 只读包名（判断安装树根是不是 dsh 本体）。 */
+function readPackageName(manifestPath) {
+	try {
+		const name = JSON.parse(readFileSync(manifestPath, "utf8"))?.name;
+		return typeof name === "string" ? name : void 0;
+	} catch {
+		return;
+	}
+}
+/** 收集 dsh 安装树内实际加载的那几个包的版本。 */
+function collectTreeVersions(root) {
+	const nm = join(root, "node_modules");
+	const piAi = packageVersionOf(join(nm, "@earendil-works", "pi-ai"));
+	const adapter = packageVersionOf(join(nm, "@deepseek-ai", "dsh-llm-pi-ai"));
+	const dsh = readPackageName(join(root, "package.json")) === "@deepseek-ai/dsh" ? packageVersionOf(root) : void 0;
+	return {
+		...piAi === void 0 ? {} : { piAi },
+		...adapter === void 0 ? {} : { piAiAdapter: adapter },
+		...dsh === void 0 ? {} : { dsh }
+	};
+}
+/**
+* 由模块入口文件向上找包目录（最多 3 层，兼容 `<pkg>/{lib,dist}/index.js`
+* 与根目录入口两种布局）；找不到返回 undefined。
+*/
+function packageDirOf(entryFile) {
+	let dir = dirname(entryFile);
+	for (let depth = 0; depth < 3; depth += 1) {
+		if (readPackageName(join(dir, "package.json")) !== void 0) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+/**
+* 解析已安装包的目录（本进程内解析，只用于读 package.json）。
+* 拿不到即返回 undefined（该版本号留空，不影响运行）。
+*/
+function installedPackageDir(specifier) {
+	try {
+		return packageDirOf(fileURLToPath(import.meta.resolve(specifier)));
+	} catch {
+		return;
+	}
+}
+/** 收集插件 vendored 兜底副本的版本（回退路径下"生效版本"即这两份）。 */
+function collectVendoredVersions() {
+	const piAiDir = installedPackageDir("@earendil-works/pi-ai");
+	const adapterDir = installedPackageDir("@deepseek-ai/dsh-llm-pi-ai");
+	const piAi = piAiDir === void 0 ? void 0 : packageVersionOf(piAiDir);
+	const adapter = adapterDir === void 0 ? void 0 : packageVersionOf(adapterDir);
+	return {
+		...piAi === void 0 ? {} : { piAi },
+		...adapter === void 0 ? {} : { piAiAdapter: adapter }
+	};
+}
+/** 已验证区间的解析端点（与 {@link VERIFIED_PI_AI_RANGE} 同步维护）。 */
+const VERIFIED_MIN = [
+	0,
+	85,
+	1
+];
+const VERIFIED_MAX_EXCLUSIVE = [
+	0,
+	88,
+	0
+];
+/** 解析 `x.y.z[-pre][+build]` 的数值三元组；形状不符返回 undefined。 */
+function numericTriple(version) {
+	const parts = (version.split(/[-+]/, 1)[0] ?? "").split(".");
+	if (parts.length !== 3) return void 0;
+	const [a, b, c] = parts.map((part) => /^\d+$/.test(part) ? Number.parseInt(part, 10) : NaN);
+	if (a === void 0 || b === void 0 || c === void 0) return void 0;
+	if (!Number.isInteger(a) || !Number.isInteger(b) || !Number.isInteger(c)) return void 0;
+	return [
+		a,
+		b,
+		c
+	];
+}
+function compareTriple(left, right) {
+	for (let i = 0; i < 3; i += 1) {
+		const diff = left[i] - right[i];
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
+/**
+* 生效 pi-ai 版本不在已验证区间时的提示文案（**提示而非阻断**）。
+* 区间内或版本号形状无法解析时返回 undefined。
+*/
+function piAiVersionNotice(version) {
+	if (version === void 0) return void 0;
+	const parsed = numericTriple(version);
+	if (parsed === void 0) return void 0;
+	if (compareTriple(parsed, VERIFIED_MIN) < 0) return `当前生效 pi-ai ${version} 低于本插件验证过的下限 ${VERIFIED_PI_AI_RANGE}`;
+	if (compareTriple(parsed, VERIFIED_MAX_EXCLUSIVE) >= 0) return `当前生效 pi-ai ${version} 超出本插件验证过的区间 ${VERIFIED_PI_AI_RANGE}；已启用现场推导与形状自检，若出现异常请先看诊断行`;
+}
+//#endregion
 //#region src/inherit.ts
 var ExtendsError = class extends Error {};
 /** 解析 "provider/model" 或裸 "model" 引用。 */
@@ -1097,42 +1424,37 @@ function parseExtendsRef(raw) {
 		model
 	};
 }
-function lookup(kit, modelsDev, provider, model) {
-	const builtin = builtinModelBase(kit, provider, model);
-	if (builtin !== void 0) return {
-		base: builtin,
-		source: "builtin",
-		sourceProvider: provider
-	};
-	const dev = modelsDev?.lookup(provider, model);
-	if (dev !== void 0) return {
-		base: dev,
-		source: "models-dev",
-		sourceProvider: provider
-	};
-}
 /**
 * 解析一个模型条目的继承 base。
 * @throws ExtendsError 显式 extends 引用不存在（写入时拒绝，指明引用名）。
 */
-function resolveModelBase(route, profile, entry, kit, modelsDev) {
+function resolveModelBase(route, profile, entry, kit) {
 	const where = `provider "${route}" model "${entry.id}"`;
 	if (entry.extends === void 0) {
 		if (profile.extends === void 0) return {
 			base: {},
 			source: "none"
 		};
-		return lookup(kit, modelsDev, profile.extends, entry.id) ?? {
+		const base = builtinModelBase(kit, profile.extends, entry.id);
+		return base === void 0 ? {
 			base: {},
 			source: "none"
+		} : {
+			base,
+			source: "builtin",
+			sourceProvider: profile.extends
 		};
 	}
 	const ref = parseExtendsRef(entry.extends);
 	const provider = ref.provider ?? profile.extends;
 	if (provider === void 0) throw new ExtendsError(`${where}: extends ${JSON.stringify(entry.extends)} 是裸模型 id，但本 route 未配置 provider 级 extends 查找源`);
-	const hit = lookup(kit, modelsDev, provider, ref.model);
-	if (hit === void 0) throw new ExtendsError(`${where}: extends 引用 "${provider}/${ref.model}" 在内置目录与 models.dev 快照中都不存在`);
-	return hit;
+	const base = builtinModelBase(kit, provider, ref.model);
+	if (base === void 0) throw new ExtendsError(`${where}: extends 引用 "${provider}/${ref.model}" 不在 pi-ai ${kit.versions.piAi ?? "?"} 的内置目录中（可继承的 provider/模型见配置页「内置模型目录」，或用裸 model id 配合 route 级 extends）`);
+	return {
+		base,
+		source: "builtin",
+		sourceProvider: provider
+	};
 }
 //#endregion
 //#region src/profiles-deepseek.ts
@@ -1339,6 +1661,26 @@ function invalid(provider, detail) {
 function declaredInput(configured) {
 	return configured === void 0 || configured.length === 0 ? void 0 : [...configured];
 }
+/**
+* 归一化条目里"本层不处理、需原样进 pi-ai Model"的字段（继承自目录的未来
+* 模型级字段，如 samplingParams）。官方 schema 当前的模型条目键（id/name/
+* contextWindow/maxTokens/input/reasoningEfforts/compat）在此全部排除：
+* 它们要么由本层显式翻译，要么不能出现在 pi-ai Model 上。
+*/
+function extraEntryFields(entry) {
+	const known = /* @__PURE__ */ new Set([
+		"id",
+		"name",
+		"contextWindow",
+		"maxTokens",
+		"input",
+		"reasoningEfforts",
+		"compat"
+	]);
+	const out = {};
+	for (const [key, value] of Object.entries(entry)) if (!known.has(key) && value !== void 0) out[key] = value;
+	return out;
+}
 /** 显式 reasoningEfforts 字典的合法性校验（官方 resolveModelReasoning 同款规则）。 */
 function validateReasoningEfforts(provider, entryId, efforts) {
 	if (Object.keys(efforts).length === 0) invalid(provider, `model "${entryId}" 的 reasoningEfforts 为空：声明档位、置 false 或缺省继承`);
@@ -1418,6 +1760,7 @@ function materializeModel(route, profile, entry, base, routeApi, defaultInput, d
 	const compat = mergeCompat(base.api === api ? base.compat : void 0, profile.compat, entry.compat);
 	return {
 		entry: {
+			...base.extra ?? {},
 			id: entry.id,
 			...name === entry.id ? {} : { name },
 			...contextWindow === 262144 ? {} : { contextWindow },
@@ -1445,7 +1788,7 @@ function materializeRouteModels(route, profile, deps, defaultInput) {
 			seen.add(entry.id);
 			let base;
 			try {
-				base = resolveModelBase(route, profile, entry, deps.kit, deps.modelsDev).base;
+				base = resolveModelBase(route, profile, entry, deps.kit).base;
 			} catch (error) {
 				if (!deps.lenient || !(error instanceof ExtendsError)) throw error;
 				deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 的 extends 引用当前不可解析（${error.message}）；已降级为手写条目`);
@@ -1504,6 +1847,10 @@ function normalizeRoute(route, profile, deps) {
 	if ((profile.adapter ?? "pi") === "deepseek") return void 0;
 	if (isDraftRoute(profile)) return void 0;
 	if (route.length === 0) throw new Error("llm-pi: provider 名不能为空");
+	if (profile.extends !== void 0 && !hasBuiltinProvider(deps.kit, profile.extends)) {
+		if (!deps.lenient) invalid(route, `extends ${JSON.stringify(profile.extends)} 不是 pi-ai ${deps.kit.versions.piAi ?? "?"} 的内置 provider；可用：${deps.kit.getBuiltinProviders().join(", ")}`);
+		deps.warn?.(`llm-pi: provider "${route}" 的 extends ${JSON.stringify(profile.extends)} 不是当前 pi-ai 的内置 provider，已忽略该继承源`);
+	}
 	if (profile.baseURL !== void 0 && profile.baseURL.length === 0) invalid(route, "baseURL 为空");
 	if (profile.displayName !== void 0 && profile.displayName.length === 0) invalid(route, "displayName 为空");
 	const streamIdleTimeoutMs = profile.streamIdleTimeoutMs ?? 3e5;
@@ -1519,7 +1866,7 @@ function normalizeRoute(route, profile, deps) {
 	const materialized = materializeRouteModels(route, profile, deps, defaultInput);
 	if (materialized === null) return void 0;
 	const { api, baseUrl, models, configuredMaxTokens } = materialized;
-	if (deps.kit.protocolFactories[api] === void 0) invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`);
+	if (deps.kit.protocolFactories[api] === void 0) invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（当前生效 pi-ai ${deps.kit.versions.piAi ?? "?"} 支持的协议：${deps.kit.protocols.join("/")}）`);
 	const displayName = profile.displayName ?? route;
 	return {
 		profile: {
@@ -1613,9 +1960,9 @@ function resolveProfilesFallback(providers, deps) {
 		if (defaultInput.length === 0) invalid(provider, "defaultInput 至少要声明一种模态");
 		const displayName = source.displayName ?? provider;
 		const api = source.api;
-		if (api === void 0) invalid(provider, "需要 api：本插件仅支持 openai-completions/openai-responses/anthropic-messages");
+		if (api === void 0) invalid(provider, `需要 api：本插件只服务官方适配器声明的协议（${deps.protocols.join("/")}）`);
 		const factory = deps.protocolFactories[api];
-		if (factory === void 0) invalid(provider, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`);
+		if (factory === void 0) invalid(provider, `api ${JSON.stringify(api)} 本插件无法服务（当前支持的协议：${deps.protocols.join("/")}）`);
 		if (source.baseURL === void 0) invalid(provider, "需要 baseURL：官方 schema 无模型级端点，端点只能 route 级表达");
 		const configuredMaxTokens = /* @__PURE__ */ new Map();
 		const modelErrors = /* @__PURE__ */ new Map();
@@ -1630,6 +1977,7 @@ function resolveProfilesFallback(providers, deps) {
 			if (!Number.isInteger(maxTokens) || maxTokens <= 0) invalid(provider, `model "${entry.id}" maxTokens 必须是正整数`);
 			if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
 			return {
+				...extraEntryFields(entry),
 				id: entry.id,
 				name: entry.name ?? entry.id,
 				api,
@@ -1813,10 +2161,17 @@ function authContextFrom(ctx) {
 *    桌面端 Electron 下 argv[1] 探测走不通）→ realpath(argv[1]) 向上找到同时
 *    含 node_modules/@deepseek-ai/dsh-llm-pi-ai 与 node_modules/@earendil-works/pi-ai
 *    的目录，按文件路径动态 import——与 dsh 官方插件共享同一模块实例；
-* 2. vendored：回退到本插件 dependencies 里的固定版本副本（裸 import）。
+* 2. vendored：回退到本插件 devDependencies 里的副本（裸 import）。
+*
+* 两条路径产物都过形状自检（assertKitShape）：上游重构导致形状漂移时抛错，
+* 由调用方决定回退或放弃注册——绝不让坏套件进入消息链路。
 *
-* 两条路径产物都过形状自检（assertKitShape）：上游重构导致形状漂移时
-* 抛错，由调用方决定回退或放弃注册——绝不让坏套件进入消息链路。
+* **自动跟随（版本不参与分支）**：插件不认识"某个 pi-ai 版本"，只认识形状与
+* 现场推导出的适配面。协议集合取自已装官方包的 `supportedProtocols()`，每个协议
+* 的惰性工厂按 `pi-ai/dist/api/<api>.lazy.js`（api id 即模块名，pi-ai 包导出约定）
+* 动态加载；缺失的协议逐项跳过并记诊断，其余协议照常。compat 门控/取值约束与
+* 模型条目字段集同样现场推导（official-surface.ts）。生效版本只用于状态行显示，
+* 超出已验证区间也只是提示（kit-meta.ts），永不阻断。
 *
 * 0.1.2-alpha 线的新面（0.1.2-alpha.2 复核包根仍未导出、仅 src 子路径有）：
 * - resolveProfiles（config.ts）：官方解析链，dev 布局树可经 src 子路径复用；
@@ -1843,7 +2198,9 @@ function assertKitShape(kit, origin) {
 	if (typeof kit.createProvider !== "function") problems.push("pi-ai createProvider 缺失");
 	if (typeof kit.getBuiltinModels !== "function") problems.push("pi-ai getBuiltinModels 缺失");
 	if (typeof kit.builtinProviders !== "function") problems.push("pi-ai builtinProviders 缺失");
-	for (const [api, factory] of Object.entries(kit.protocolFactories)) if (typeof factory !== "function") problems.push(`协议工厂 ${api} 缺失`);
+	if (kit.protocols.length === 0) problems.push("没有可服务的线协议（协议工厂全部加载失败）");
+	for (const api of kit.protocols) if (typeof kit.protocolFactories[api] !== "function") problems.push(`协议 ${api} 的工厂缺失`);
+	if (kit.officialModelFields.length === 0) problems.push("官方模型条目字段集为空");
 	if (typeof kit.LlmError !== "function") problems.push("dsh-llm LlmError 缺失");
 	if (typeof kit.resolveRetryPolicy !== "function") problems.push("dsh-llm resolveRetryPolicy 缺失");
 	if (typeof kit.resolveProfiles !== "function") problems.push("resolveProfiles 缺失");
@@ -1872,27 +2229,21 @@ function findDshTreeRoot(startDir) {
 		dir = parent;
 	}
 }
-/** 从 dsh 安装树按文件路径动态 import 全部套件模块（与官方插件同实例）。 */
+/** 从 dsh 安装树按文件路径动态 import 核心套件模块（与官方插件同实例）。 */
 async function importTreeModules(root) {
 	const nm = join(root, "node_modules");
 	const load = (absPath) => import(pathToFileURL(absPath).href);
-	const [piAiAdapter, llm, piAi, catalog, completions, responses, anthropic] = await Promise.all([
+	const [piAiAdapter, llm, piAi, catalog] = await Promise.all([
 		load(join(nm, "@deepseek-ai", "dsh-llm-pi-ai", "lib", "index.js")),
 		load(join(nm, "@deepseek-ai", "dsh-llm", "lib", "index.js")),
 		load(join(nm, "@earendil-works", "pi-ai", "dist", "index.js")),
-		load(join(nm, "@earendil-works", "pi-ai", "dist", "providers", "all.js")),
-		load(join(nm, "@earendil-works", "pi-ai", "dist", "api", "openai-completions.lazy.js")),
-		load(join(nm, "@earendil-works", "pi-ai", "dist", "api", "openai-responses.lazy.js")),
-		load(join(nm, "@earendil-works", "pi-ai", "dist", "api", "anthropic-messages.lazy.js"))
+		load(join(nm, "@earendil-works", "pi-ai", "dist", "providers", "all.js"))
 	]);
 	return {
 		piAiAdapter,
 		llm,
 		piAi,
-		catalog,
-		completions,
-		responses,
-		anthropic
+		catalog
 	};
 }
 /**
@@ -1932,58 +2283,153 @@ async function importTreeDeepseek(root) {
 		return { problem: error instanceof Error ? error.message : String(error) };
 	}
 }
-function protocolFactoriesOf(mods) {
+/**
+* 取惰性协议模块里的工厂：约定每个 `api/<api>.lazy.js` 只导出一个 `*Api`
+* 工厂函数。名字不符时退化为"唯一函数导出"，多函数且无 `*Api` 命名则判失败
+* （宁可跳过该协议，也不猜错工厂）。
+*/
+function protocolFactoryOf(module) {
+	const functions = Object.entries(module).filter((entry) => typeof entry[1] === "function");
+	const named = functions.filter(([name]) => /Api$/.test(name));
+	if (named.length === 1) return named[0]?.[1];
+	if (functions.length === 1) return functions[0]?.[1];
+}
+/** pi-ai 的惰性协议实现目录（dsh 树布局）。 */
+function piAiApiDir(root) {
+	return join(root, "node_modules", "@earendil-works", "pi-ai", "dist", "api");
+}
+/** 内置三元组的静态加载（协议推导失败或全部工厂加载失败时的兜底）。 */
+async function loadFallbackTreeFactories(root, diagnostics) {
+	const dir = piAiApiDir(root);
+	const out = {};
+	for (const api of fallbackProtocols()) {
+		const file = join(dir, `${api}.lazy.js`);
+		if (!existsSync(file)) continue;
+		try {
+			const factory = protocolFactoryOf(await import(pathToFileURL(file).href));
+			if (factory !== void 0) out[api] = factory;
+		} catch {}
+	}
+	if (Object.keys(out).length < fallbackProtocols().length) diagnostics.push(`pi-ai 协议兜底三元组未能全部加载（${Object.keys(out).join("/") || "空"}）；请检查 dsh 安装树里 @earendil-works/pi-ai/dist/api 的形态`);
+	return out;
+}
+/**
+* 按官方声明的协议集合加载 pi-ai 惰性工厂（api id 即模块名）。
+* 逐项失败只跳过该协议并记诊断；一个都加载不到时回退内置三元组。
+*/
+async function loadTreeProtocols(root, derived, diagnostics) {
+	const dir = piAiApiDir(root);
+	const out = {};
+	for (const api of derived) {
+		const file = join(dir, `${api}.lazy.js`);
+		if (!existsSync(file)) {
+			diagnostics.push(`pi-ai 未提供协议 "${api}" 的惰性实现（缺 ${file}）；该协议不可用，其余协议不受影响`);
+			continue;
+		}
+		try {
+			const factory = protocolFactoryOf(await import(pathToFileURL(file).href));
+			if (factory === void 0) {
+				diagnostics.push(`协议 "${api}" 的实现模块未导出唯一 *Api 工厂；该协议不可用`);
+				continue;
+			}
+			out[api] = factory;
+		} catch (error) {
+			diagnostics.push(`协议 "${api}" 的实现加载失败（${error instanceof Error ? error.message : String(error)}）；该协议不可用`);
+		}
+	}
+	if (Object.keys(out).length > 0) return {
+		protocols: derived.filter((api) => out[api] !== void 0),
+		protocolFactories: out
+	};
+	diagnostics.push("官方声明的协议一个都加载不到；回退内置三元组");
+	const fallback = await loadFallbackTreeFactories(root, diagnostics);
 	return {
-		"openai-completions": mods.completions["openAICompletionsApi"],
-		"openai-responses": mods.responses["openAIResponsesApi"],
-		"anthropic-messages": mods.anthropic["anthropicMessagesApi"]
+		protocols: fallbackProtocols().filter((api) => fallback[api] !== void 0),
+		protocolFactories: fallback
 	};
 }
+function protocolFactoriesOf(protocols, factories) {
+	const out = {};
+	for (const api of protocols) {
+		const factory = factories[api];
+		if (factory !== void 0) out[api] = factory;
+	}
+	return out;
+}
 /** 插件等价解析链的套件依赖（与 PiAiAdapter 同源，杜绝跨源混用）。 */
-function treeResolverDeps(mods, protocolFactories) {
+function treeResolverDeps(mods, protocolFactories, protocols) {
 	return {
 		createProvider: mods.piAi["createProvider"],
 		protocolFactories,
+		protocols,
 		resolveRetryPolicy: mods.llm["resolveRetryPolicy"]
 	};
 }
+/** 读内置目录数据生成时间（官方未导出/形状变化时省略）。 */
+function catalogGeneratedAtOf(catalog) {
+	const reader = catalog["getBuiltinModelDataGeneratedAt"];
+	if (typeof reader !== "function") return void 0;
+	try {
+		const value = reader();
+		return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
 /**
-* 从官方安装副本推导 compat 门控表（bundle 文本给分型、Config schema 给取值约束），
-* 并安装为插件生效表。任一环节失败回退 FALLBACK_TABLE 并给诊断——绝不因推导失败
-* 弄挂插件启动（宁可放宽校验，也不误拒官方可配字段）。
+* 从官方安装副本推导适配面并安装 compat 生效表（bundle 文本给分型、Config schema
+* 给取值约束与模型条目字段集、supportedProtocols() 给协议集合）。
+* 任一环节失败都逐项回退并记诊断——绝不因推导失败弄挂插件启动。
 */
-function installOfficialCompatTable(bundlePath, module, diagnostics) {
-	const label = "compat 门控表";
+function installOfficialSurface(options) {
+	const { bundlePath, adapterModule, origin, diagnostics } = options;
+	const compatLabel = "compat 门控表";
 	try {
 		const gates = deriveGates(readFileSync(bundlePath, "utf8"));
 		if (gates === void 0) {
-			diagnostics.push(`${label}未能从官方 bundle 解析 COMPAT_GATES（${bundlePath}）；使用内置快照（官方新增字段可能被误拒，请检查 dsh-llm-pi-ai 打包形态）`);
+			diagnostics.push(`${compatLabel}未能从官方 bundle 解析 COMPAT_GATES（${bundlePath}）；使用内置快照（未知字段放行、withhold 仍拒绝；请检查 dsh-llm-pi-ai 打包形态）`);
 			installCompatTable(FALLBACK_TABLE);
-			return;
-		}
-		installCompatTable({
+		} else installCompatTable({
 			gates,
 			specs: {
 				...FALLBACK_TABLE.specs,
-				...deriveSpecs(module)
+				...deriveSpecs(adapterModule)
 			},
 			source: "official"
 		});
 	} catch (error) {
 		const reason = error instanceof Error ? error.message : String(error);
-		diagnostics.push(`${label}推导失败（${reason}）；使用内置快照`);
+		diagnostics.push(`${compatLabel}推导失败（${reason}）；使用内置快照（未知字段放行）`);
 		installCompatTable(FALLBACK_TABLE);
 	}
+	const derivedProtocols = deriveProtocols(adapterModule);
+	if (derivedProtocols === void 0) diagnostics.push(`${origin}：官方 supportedProtocols() 不可用；协议集合回退内置三元组 ${fallbackProtocols().join("/")}`);
+	const fields = deriveModelEntryFields(adapterModule);
+	if (fields === void 0) diagnostics.push(`${origin}：官方 Config schema 的模型条目字段集不可推导；继承字段回退已知键 ${FALLBACK_MODEL_ENTRY_FIELDS.join("/")}（官方新增字段可能不被继承）`);
+	const generatedAt = catalogGeneratedAtOf(options.catalogModule);
+	return {
+		protocols: derivedProtocols ?? fallbackProtocols(),
+		protocolSource: derivedProtocols === void 0 ? "fallback" : "official",
+		officialModelFields: fields ?? [...FALLBACK_MODEL_ENTRY_FIELDS],
+		...generatedAt === void 0 ? {} : { catalogGeneratedAt: generatedAt }
+	};
 }
-function kitFromTree(mods, auth, config) {
-	const protocolFactories = protocolFactoriesOf(mods);
-	const resolverDeps = treeResolverDeps(mods, protocolFactories);
-	const officialResolveProfiles = config?.["resolveProfiles"];
-	const officialCredentialStoreFrom = auth?.["credentialStoreFrom"];
-	const officialAuthContextFrom = auth?.["authContextFrom"];
+function kitFromTree(options) {
+	const { mods, surface, protocols, protocolFactories, root, versions } = options;
+	const resolverDeps = treeResolverDeps(mods, protocolFactories, protocols);
+	const officialResolveProfiles = options.config?.["resolveProfiles"];
+	const officialCredentialStoreFrom = options.auth?.["credentialStoreFrom"];
+	const officialAuthContextFrom = options.auth?.["authContextFrom"];
 	const recordKeyFor = mods.piAiAdapter["recordKeyFor"];
 	return {
 		source: "dsh-tree",
+		root,
+		versions,
+		protocols,
+		protocolSource: surface.protocolSource,
+		protocolFactories,
+		officialModelFields: surface.officialModelFields,
+		...surface.catalogGeneratedAt === void 0 ? {} : { catalogGeneratedAt: surface.catalogGeneratedAt },
 		PiAiAdapter: mods.piAiAdapter["PiAiAdapter"],
 		LlmError: mods.llm["LlmError"],
 		resolveRetryPolicy: mods.llm["resolveRetryPolicy"],
@@ -1995,7 +2441,6 @@ function kitFromTree(mods, auth, config) {
 		builtinProviders: mods.catalog["builtinProviders"],
 		getBuiltinProviders: mods.catalog["getBuiltinProviders"],
 		getBuiltinModels: mods.catalog["getBuiltinModels"],
-		protocolFactories,
 		resolveProfiles: officialResolveProfiles !== void 0 ? officialResolveProfiles : (providers) => resolveProfilesFallback(providers, resolverDeps),
 		auth: {
 			credentialStoreFrom: officialCredentialStoreFrom !== void 0 ? officialCredentialStoreFrom : (ctx) => credentialStoreFrom(ctx, recordKeyFor),
@@ -2021,22 +2466,48 @@ function loadVendoredDeepseek() {
 function vendoredAdapterBundlePath() {
 	return fileURLToPath(import.meta.resolve("@deepseek-ai/dsh-llm-pi-ai"));
 }
+/** vendored 副本的静态协议工厂表（devDependencies 钉版，故无需动态加载）。 */
+function vendoredProtocolFactories() {
+	return {
+		"openai-completions": openAICompletionsApi,
+		"openai-responses": openAIResponsesApi,
+		"anthropic-messages": anthropicMessagesApi
+	};
+}
 /**
 * vendored 兜底副本套件（导出供单测直接使用，免走 dsh 树解析）。
+* 副本是**钉版**的，故协议工厂走静态导入，协议集合取"官方声明 ∩ 静态工厂"；
 * npm 发布形态不携带 src/、lib 仅 index.js/invariant.js——resolveProfiles 与
 * auth 助手在此无条件走插件等价实现（内联，见文件头说明）；compat 门控表则
 * 仍从 vendored 副本的 bundle + Config schema 现场推导（与 dsh 树同一推导链）。
+* @param diagnostics 可选诊断收集器（回退原因与逐项降级说明）。
 */
-function loadVendoredKit() {
-	const deepseek = loadVendoredDeepseek();
-	const protocolFactories = {
-		"openai-completions": openAICompletionsApi,
-		"openai-responses": openAIResponsesApi,
-		"anthropic-messages": anthropicMessagesApi
+function loadVendoredKit(diagnostics = []) {
+	const staticFactories = vendoredProtocolFactories();
+	const surface = installOfficialSurface({
+		bundlePath: vendoredAdapterBundlePath(),
+		adapterModule: vendoredPiAiAdapter,
+		catalogModule: vendoredCatalog,
+		origin: "vendored 副本",
+		diagnostics
+	});
+	const protocols = surface.protocols.filter((api) => staticFactories[api] !== void 0);
+	const protocolFactories = protocolFactoriesOf(protocols, staticFactories);
+	const resolverDeps = {
+		createProvider: vendoredPiAi.createProvider,
+		protocolFactories,
+		protocols,
+		resolveRetryPolicy: vendoredLlm.resolveRetryPolicy
 	};
-	installOfficialCompatTable(vendoredAdapterBundlePath(), vendoredPiAiAdapter, []);
+	const deepseek = loadVendoredDeepseek();
 	const kit = {
 		source: "vendored",
+		versions: collectVendoredVersions(),
+		protocols,
+		protocolSource: protocols.length > 0 ? surface.protocolSource : "fallback",
+		protocolFactories,
+		officialModelFields: surface.officialModelFields,
+		...surface.catalogGeneratedAt === void 0 ? {} : { catalogGeneratedAt: surface.catalogGeneratedAt },
 		PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
 		LlmError: vendoredLlm.LlmError,
 		resolveRetryPolicy: vendoredLlm.resolveRetryPolicy,
@@ -2048,12 +2519,7 @@ function loadVendoredKit() {
 		builtinProviders: vendoredCatalog.builtinProviders,
 		getBuiltinProviders: vendoredCatalog.getBuiltinProviders,
 		getBuiltinModels: vendoredCatalog.getBuiltinModels,
-		protocolFactories,
-		resolveProfiles: (providers) => resolveProfilesFallback(providers, {
-			createProvider: vendoredPiAi.createProvider,
-			protocolFactories,
-			resolveRetryPolicy: vendoredLlm.resolveRetryPolicy
-		}),
+		resolveProfiles: (providers) => resolveProfilesFallback(providers, resolverDeps),
 		auth: {
 			credentialStoreFrom: (ctx) => credentialStoreFrom(ctx, vendoredPiAiAdapter.recordKeyFor),
 			authContextFrom
@@ -2085,7 +2551,7 @@ function dshTreeAnchor(installAnchor, argvEntry = process.argv[1]) {
 /**
 * 解析运行时套件：优先 dsh 安装树（自动跟随上游），失败回退 vendored 副本；
 * 两者都过不了形状自检时抛错（调用方应记日志并放弃注册 route）。
-* 返回的 diagnostics 记录回退原因，供配置卡片与日志展示。
+* 返回的 diagnostics 记录回退原因与逐项降级说明，供配置卡片与日志展示。
 * @param installAnchor profile 的 dsh 安装锚点（`ctx.profileContext.installAnchor`）。
 */
 async function resolveDshKit(installAnchor) {
@@ -2095,10 +2561,26 @@ async function resolveDshKit(installAnchor) {
 		const treePkgDir = join(anchor, "node_modules", "@deepseek-ai", "dsh-llm-pi-ai");
 		try {
 			const mods = await importTreeModules(anchor);
+			const surface = installOfficialSurface({
+				bundlePath: join(treePkgDir, "lib", "index.js"),
+				adapterModule: mods.piAiAdapter,
+				catalogModule: mods.catalog,
+				origin: "dsh 安装树",
+				diagnostics
+			});
+			const { protocols, protocolFactories } = await loadTreeProtocols(anchor, surface.protocols, diagnostics);
 			const [auth, config] = await Promise.all([probeSubmodule(treePkgDir, "auth"), probeSubmodule(treePkgDir, "config")]);
-			const kit = kitFromTree(mods, auth, config);
+			const kit = kitFromTree({
+				mods,
+				auth,
+				config,
+				surface,
+				protocols,
+				protocolFactories,
+				root: anchor,
+				versions: collectTreeVersions(anchor)
+			});
 			assertKitShape(kit, "dsh-tree");
-			installOfficialCompatTable(join(treePkgDir, "lib", "index.js"), mods.piAiAdapter, diagnostics);
 			if (auth === void 0) diagnostics.push("dsh 树不含 dsh-llm-pi-ai/src（npm 发布形态）；认证助手使用插件内联等价实现");
 			if (config === void 0) diagnostics.push("dsh 树不含 dsh-llm-pi-ai/src（npm 发布形态）；profile 解析使用插件等价实现（compat 门控对齐官方 catalog.ts）");
 			const tree = await importTreeDeepseek(anchor);
@@ -2118,7 +2600,7 @@ async function resolveDshKit(installAnchor) {
 			diagnostics.push(`dsh 安装树套件不可用（${anchor}）：${error instanceof Error ? error.message : String(error)}；回退 vendored 副本`);
 		}
 	} else diagnostics.push("未能从 profileContext.installAnchor / process.argv[1] 定位 dsh 安装树；回退 vendored 副本");
-	const kit = loadVendoredKit();
+	const kit = loadVendoredKit(diagnostics);
 	if (kit.deepseek === void 0) diagnostics.push("vendored 副本的 dsh-llm-deepseek 形状不兼容；adapter: deepseek 的 route 不可用");
 	return {
 		kit,
@@ -2146,31 +2628,32 @@ function makeResolveApiKey(ctx, kit) {
 		throw new kit.LlmError(`llm-pi: provider route "${provider}" 的凭据引用 ${String(ref)} 未解析到值——请经凭据服务（web Models 页）存放或导出环境变量；仅当该 provider 应使用 pi-ai 自有环境发现时才移除 apiKeyEnv`, "MISSING_CREDENTIAL");
 	};
 }
-/** 启动插件运行时：解析套件、挂载注册/发现/settings 联动。 */
-async function startRuntime(ctx, rawConfig) {
-	const logger = ctx.logger("llm-pi");
-	const fields = hasVolatileRefs(rawConfig) ? rawConfig : Config(rawConfig ?? {});
+/** 解析运行期套件并落启动日志（来源/生效版本/协议/逐项降级诊断）。 */
+async function loadRuntimeKit(ctx, logger) {
 	const { kit, diagnostics } = await resolveDshKit(ctx.get("profileContext")?.installAnchor);
 	for (const line of diagnostics) logger.warn(line);
-	logger.info(`运行时套件来源：${kit.source}`);
-	let snapshot = unwrapVolatile(fields);
-	const modelsDev = new ModelsDevSource(pluginDataPath("llm-pi", "models-dev.json"), snapshot.catalogUrl, snapshot.catalogRefreshHours, (message) => logger.warn(message), snapshot.catalogProxy ?? "");
-	modelsDev.ensureLoaded();
-	const current = () => snapshot;
+	logger.info(`运行时套件来源：${kit.source}；pi-ai ${kit.versions.piAi ?? "?"} / dsh-llm-pi-ai ${kit.versions.piAiAdapter ?? "?"}；协议 ${kit.protocols.join("/")}`);
+	const versionNotice = piAiVersionNotice(kit.versions.piAi);
+	if (versionNotice !== void 0) logger.warn(versionNotice);
+	return {
+		kit,
+		diagnostics
+	};
+}
+/**
+* profiles / deepseek 路由解析器：按原始 config 对象 identity 备忘（官方同款模式）。
+* 运行期走 lenient：目录漂移时降级/跳过并告警，而非抛错弄挂整个 route。
+*/
+function createProfileResolvers(options) {
+	const { kit, current, logger } = options;
 	let lastRaw;
 	let memoized;
 	let memoizedDeepseek;
-	const deps = {
-		kit,
-		modelsDev
-	};
-	/** 当前已解析 profiles，按原始 config identity 备忘（官方同款模式）。
-	*  运行期走 lenient：数据源漂移时降级/跳过并告警，而非抛错弄挂整个 route。 */
 	const profiles = () => {
 		const raw = current();
 		if (raw === lastRaw && memoized !== void 0) return memoized;
 		const next = raw.enabled ? buildProfiles(raw.providers, {
-			...deps,
+			kit,
 			lenient: true,
 			warn: (message) => logger.warn(message)
 		}) : /* @__PURE__ */ new Map();
@@ -2183,13 +2666,19 @@ async function startRuntime(ctx, rawConfig) {
 		memoized = next;
 		return next;
 	};
-	/** deepseek 路由物化表（与 profiles 同一次备忘窗口）。 */
 	const deepseekRoutes = () => {
 		profiles();
 		return memoizedDeepseek ?? /* @__PURE__ */ new Map();
 	};
-	profiles();
-	const adapter = new kit.PiAiAdapter({
+	return {
+		profiles,
+		deepseekRoutes
+	};
+}
+/** 构造 PiAiAdapter（官方给出的接缝全部接上）。 */
+function createAdapter(options) {
+	const { ctx, kit, profiles, logger } = options;
+	return new kit.PiAiAdapter({
 		profiles,
 		resolveApiKey: makeResolveApiKey(ctx, kit),
 		resolveAttachments: () => ctx.get("attachments"),
@@ -2202,17 +2691,14 @@ async function startRuntime(ctx, rawConfig) {
 			logger.warn(`llm-pi: 助手历史中 "${provider}/${model}" 的回放状态不可用，该消息按 provider 中立内容发送（${reason}）`);
 		}
 	});
-	const storedApiKey = async (provider) => {
-		if (provider === void 0) return void 0;
-		const profile = profiles().get(provider);
-		if (profile === void 0) return void 0;
-		return makeResolveApiKey(ctx, kit)(provider, profile);
-	};
-	ctx.llm.registerModelDiscovery(SETTINGS_NS, (request) => discoverModels(request, {
-		kit,
-		configProviders: () => current().providers ?? {},
-		storedApiKey
-	}));
+}
+/**
+* 注册 handle 组。正常路径单个 handle 整批注册/替换；整批注册遇
+* DUPLICATE_ADAPTER（route 名与其他 adapter 冲突）时降级为逐个注册，
+* 跳过冲突 route——启动不再 fail-loud，其余 route 照常服务。
+*/
+function createRegistrationController(options) {
+	const { ctx, adapter, profiles, logger } = options;
 	let registrations;
 	let registeredFacts;
 	const registerGroup = (routes, fallback) => {
@@ -2238,10 +2724,10 @@ async function startRuntime(ctx, rawConfig) {
 		}
 	};
 	const ensureRegistration = () => {
-		const current2 = profiles();
-		const facts = registrationFacts(current2);
+		const resolved = profiles();
+		const facts = registrationFacts(resolved);
 		if (deepEqualJson(facts, registeredFacts)) return;
-		const routes = [...current2.keys()];
+		const routes = [...resolved.keys()];
 		if (registrations === void 0) {
 			if (routes.length === 0) {
 				registeredFacts = facts;
@@ -2266,9 +2752,16 @@ async function startRuntime(ctx, rawConfig) {
 		}
 		registeredFacts = facts;
 	};
+	return { ensureRegistration };
+}
+/**
+* 可配置 provider 目录（pi 路由 + deepseek 路由 + 草稿路由）。
+* 草稿路由从原始配置直读——它们不进 adapter profiles。
+*/
+function createDirectoryController(options) {
+	const { ctx, kit, current, profiles, deepseekRoutes, logger } = options;
 	let directory;
 	let directoryFacts;
-	/** 草稿路由（无模型占位）从原始配置直读——它们不进 adapter profiles。 */
 	const draftRoutes = () => {
 		const providers = current().providers ?? {};
 		return Object.entries(providers).filter(([, profile]) => isDraftRoute(profile)).map(([route, profile]) => ({
@@ -2289,6 +2782,62 @@ async function startRuntime(ctx, rawConfig) {
 		}, entries, (message) => logger.warn(message));
 		directoryFacts = entries;
 	};
+	return { ensureDirectory };
+}
+/** 跑一步热更新动作，失败只告警（保留此前注册/目录）。 */
+function attempt(logger, message, run) {
+	try {
+		run();
+	} catch (error) {
+		logger.error(message);
+		logger.error(error);
+	}
+}
+/** 启动插件运行时：解析套件、挂载注册/发现/settings 联动。 */
+async function startRuntime(ctx, rawConfig) {
+	const logger = ctx.logger("llm-pi");
+	const fields = hasVolatileRefs(rawConfig) ? rawConfig : Config(rawConfig ?? {});
+	const { kit, diagnostics } = await loadRuntimeKit(ctx, logger);
+	let snapshot = unwrapVolatile(fields);
+	const current = () => snapshot;
+	const deps = { kit };
+	const { profiles, deepseekRoutes } = createProfileResolvers({
+		kit,
+		current,
+		logger
+	});
+	profiles();
+	const adapter = createAdapter({
+		ctx,
+		kit,
+		profiles,
+		logger
+	});
+	const storedApiKey = async (provider) => {
+		if (provider === void 0) return void 0;
+		const profile = profiles().get(provider);
+		if (profile === void 0) return void 0;
+		return makeResolveApiKey(ctx, kit)(provider, profile);
+	};
+	ctx.llm.registerModelDiscovery(SETTINGS_NS, (request) => discoverModels(request, {
+		kit,
+		configProviders: () => current().providers ?? {},
+		storedApiKey
+	}));
+	const { ensureRegistration } = createRegistrationController({
+		ctx,
+		adapter,
+		profiles,
+		logger
+	});
+	const { ensureDirectory } = createDirectoryController({
+		ctx,
+		kit,
+		current,
+		profiles,
+		deepseekRoutes,
+		logger
+	});
 	const deepseekRegistrar = new DeepseekRouteRegistrar({
 		ctx,
 		kit,
@@ -2304,26 +2853,9 @@ async function startRuntime(ctx, rawConfig) {
 	ensureDirectory();
 	const reconfigure = () => {
 		snapshot = unwrapVolatile(fields);
-		try {
-			ensureRegistration();
-		} catch (error) {
-			logger.error("llm-pi: 更新被拒，保留此前注册的 route");
-			logger.error(error);
-		}
-		try {
-			ensureDeepseek();
-		} catch (error) {
-			logger.error("llm-pi: deepseek route 更新失败，保留此前注册");
-			logger.error(error);
-		}
-		try {
-			ensureDirectory();
-		} catch (error) {
-			logger.error("llm-pi: 更新被拒，保留此前的 configurable-provider 目录");
-			logger.error(error);
-		}
-		const cfg = current();
-		modelsDev.reconfigure(cfg.catalogUrl, cfg.catalogRefreshHours, cfg.catalogProxy ?? "");
+		attempt(logger, "llm-pi: 更新被拒，保留此前注册的 route", ensureRegistration);
+		attempt(logger, "llm-pi: deepseek route 更新失败，保留此前注册", ensureDeepseek);
+		attempt(logger, "llm-pi: 更新被拒，保留此前的 configurable-provider 目录", ensureDirectory);
 	};
 	ctx.events.on("loader/volatile-update", reconfigure);
 	ctx.on("internal/config", function(_raw, next) {
@@ -2332,13 +2864,33 @@ async function startRuntime(ctx, rawConfig) {
 		assertServiceable(unwrapVolatile(Config(candidate)), deps);
 		return candidate;
 	});
-	return {
-		currentConfig: () => current(),
-		kitInfo: () => ({
+	/** 目录规模：按需从当前套件的 provider/模型清单汇总（不缓存，随套件固定）。 */
+	const kitInfo = () => {
+		const providers = listProviders(kit);
+		const generatedAt = kit.catalogGeneratedAt;
+		const notice = piAiVersionNotice(kit.versions.piAi);
+		return {
 			source: kit.source,
+			...kit.root === void 0 ? {} : { root: kit.root },
+			versions: kit.versions,
+			verifiedRange: VERIFIED_PI_AI_RANGE,
+			...notice === void 0 ? {} : { versionNotice: notice },
+			protocols: kit.protocols,
+			protocolSource: kit.protocolSource,
+			catalog: {
+				providers: providers.length,
+				models: providers.reduce((total, entry) => total + entry.modelCount, 0),
+				...generatedAt === void 0 ? {} : { generatedAt }
+			},
+			compatSource: compatTableInfo().source,
 			diagnostics
-		}),
-		modelsDev,
+		};
+	};
+	return {
+		currentConfig: () => current(),
+		kitInfo,
+		providerEntries: () => listProviders(kit),
+		apiIndex: () => buildApiIndex(listModelInfos(kit)),
 		kit
 	};
 }